@thisispandora/agent-sdk

Standalone alpha TypeScript/Node SDK for Pandora's MCP tool interface and generated contract catalog.

Status and delivery

• primary package identity: @thisispandora/agent-sdk
• generated artifacts ship package-locally under @thisispandora/agent-sdk/generated
• current external distribution paths:
  • public npm package: npm install @thisispandora/agent-sdk@alpha
  • signed GitHub release asset tarball for the tagged Pandora release
• repository checkout path: sdk/typescript is for maintainers and in-tree development only
• the Pandora CLI package also vendors a matching copy under sdk/typescript and pandora-cli-skills/sdk/typescript for parity and in-tree consumers
• public npm publication is live; the newest prerelease is published under the alpha dist-tag

What it exposes

• local stdio MCP execution via pandora mcp
• remote streamable HTTP MCP execution via pandora mcp http
• one generic client surface for tool discovery and tool calls
• first-class bootstrap helpers so cold agents can start from Pandora's canonical bootstrap contract
• generated catalog helpers for policy/profile and contract inspection
• both CommonJS and native Node ESM entrypoints

Install and access

Current validated install paths:

Preferred for external consumers:

npm install @thisispandora/agent-sdk@alpha

Or install from a signed GitHub release tarball:

npm install /path/to/downloaded/thisispandora-agent-sdk-<version>.tgz

Maintainer and repository-checkout flows:

npm install ./sdk/typescript

Or build a local tarball from source:

npm pack ./sdk/typescript

Use the public npm package for the normal external install path. Use the signed GitHub release tarball when you need an explicitly pinned audited artifact. Use the repo path only when you intentionally want an in-tree checkout.

Node >=18 is required.

Useful package subpaths:

@thisispandora/agent-sdk
@thisispandora/agent-sdk/generated
@thisispandora/agent-sdk/generated/manifest
@thisispandora/agent-sdk/generated/command-descriptors
@thisispandora/agent-sdk/generated/mcp-tool-definitions
@thisispandora/agent-sdk/generated/contract-registry

Native ESM is supported for the root package and the generated subpaths above.

Vendored equivalent inside the Pandora CLI package:

• pandora-cli-skills/sdk/typescript
• pandora-cli-skills/sdk/generated

Quick start

Cold agents should start with bootstrap, not with low-level capabilities or schema calls.

const {
  connectPandoraAgentClient,
  loadGeneratedManifest,
} = require('@thisispandora/agent-sdk');

async function main() {
  const client = await connectPandoraAgentClient({
    command: 'pandora',
    args: ['mcp'],
  });

  try {
    const bootstrap = await client.getBootstrap();
    const manifest = loadGeneratedManifest();
    console.log(bootstrap.recommendedBootstrapFlow[0], manifest.commandDescriptorVersion);
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Native ESM quick start

import { connectPandoraAgentClient, loadGeneratedManifest } from '@thisispandora/agent-sdk';

const client = await connectPandoraAgentClient({
  command: 'pandora',
  args: ['mcp'],
});

try {
  const bootstrap = await client.getBootstrap();
  const manifest = loadGeneratedManifest();
  console.log(bootstrap.recommendedBootstrapFlow[0], manifest.commandDescriptorVersion);
} finally {
  await client.close();
}

Local vs remote backends

Use the generic client factory when you want one entrypoint:

const {
  createPandoraAgentClient,
} = require('@thisispandora/agent-sdk');

const localClient = createPandoraAgentClient({
  command: 'pandora',
  args: ['mcp'],
});

const remoteClient = createPandoraAgentClient({
  mode: 'remote',
  url: 'http://127.0.0.1:8787/mcp',
  authToken: process.env.PANDORA_MCP_TOKEN,
});

Backend mapping:

• local backend:
  • start pandora mcp
  • connect over stdio on the same machine
  • no bearer token is involved
• remote backend:
  • intentionally host pandora mcp http ...
  • connect to the /mcp endpoint with a bearer token
  • signer material, if any, stays on the gateway runtime

Generated catalog access

The root entrypoint already exports the generated helpers:

const {
  loadGeneratedContractRegistry,
  loadGeneratedCapabilities,
  inspectToolPolicySurface,
} = require('@thisispandora/agent-sdk');

const registry = loadGeneratedContractRegistry();
const capabilities = loadGeneratedCapabilities();
const trade = inspectToolPolicySurface('trade', registry);

console.log(capabilities.commandDescriptorVersion);
console.log(trade.policyScopes);

If you want the canonical bootstrap payload directly:

const { connectPandoraAgentClient } = require('@thisispandora/agent-sdk');

async function main() {
  const client = await connectPandoraAgentClient({
    mode: 'remote',
    url: 'http://127.0.0.1:8787/mcp',
    authToken: process.env.PANDORA_MCP_TOKEN,
  });

  try {
    const bootstrap = await client.getBootstrap();
    console.log(bootstrap.canonicalTools.length);
  } finally {
    await client.close();
  }
}

If you want the raw generated bundle:

const generated = require('@thisispandora/agent-sdk/generated');

console.log(generated.manifest.packageVersion);
console.log(Object.keys(generated.contractRegistry.tools).length);

Native ESM can also import those generated subpaths directly:

import manifest from '@thisispandora/agent-sdk/generated/manifest';
import contractRegistry from '@thisispandora/agent-sdk/generated/contract-registry';

console.log(manifest.packageVersion);
console.log(Object.keys(contractRegistry.tools).length);

Error handling

const {
  PandoraSdkError,
  PandoraToolCallError,
} = require('@thisispandora/agent-sdk');

try {
  // tool call
} catch (error) {
  if (error instanceof PandoraToolCallError) {
    console.error(error.code, error.toolName, error.toolError);
  } else if (error instanceof PandoraSdkError) {
    console.error(error.code, error.details);
  } else {
    throw error;
  }
}

Current boundaries

• this SDK does not bundle the Pandora CLI itself; local stdio usage still needs a pandora executable or an explicit command/args pair
• remote HTTP usage still requires an operator-hosted pandora mcp http gateway and any required bearer token
• repository checkouts can regenerate the vendored bundle with npm run generate:sdk-contracts
• the Pandora CLI package vendors a matching copy under sdk/typescript, but the standalone package is the primary SDK product surface