@thisispandora/agent-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,229 @@
+# @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 path: 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 not claimed by this README until a release explicitly says so
+
+## 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:
+
+```bash
+npm install /path/to/downloaded/thisispandora-agent-sdk-<version>.tgz
+```
+
+Maintainer and repository-checkout flows:
+
+```bash
+npm install ./sdk/typescript
+```
+
+Or build a local tarball from source:
+
+```bash
+npm pack ./sdk/typescript
+```
+
+Use the signed GitHub release tarball when working outside the repository. Use the repo path only when you intentionally want an in-tree checkout.
+
+Node `>=18` is required.
+
+Useful package subpaths:
+
+```text
+@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.
+
+```js
+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
+
+```js
+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:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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
+
+```js
+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

package/backends.d.ts

@@ -0,0 +1,15 @@
+export {
+  PandoraAgentClient,
+  PandoraMcpBackend,
+  PandoraStdioBackend,
+  PandoraRemoteBackend,
+  createPandoraStdioBackend,
+  createPandoraRemoteBackend,
+  createLocalPandoraAgentClient,
+  createRemotePandoraAgentClient,
+  createPandoraAgentClient,
+  connectPandoraAgentClient,
+  type PandoraAgentClientFactoryOptions,
+  type PandoraRemoteBackendOptions,
+  type PandoraStdioBackendOptions,
+} from './index';

package/backends.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const sdk = require('./index.js');
+
+const api = {
+  PandoraAgentClient: sdk.PandoraAgentClient,
+  PandoraMcpBackend: sdk.PandoraMcpBackend,
+  PandoraStdioBackend: sdk.PandoraStdioBackend,
+  PandoraRemoteBackend: sdk.PandoraRemoteBackend,
+  createPandoraStdioBackend: sdk.createPandoraStdioBackend,
+  createPandoraRemoteBackend: sdk.createPandoraRemoteBackend,
+  createLocalPandoraAgentClient: sdk.createLocalPandoraAgentClient,
+  createRemotePandoraAgentClient: sdk.createRemotePandoraAgentClient,
+  createPandoraAgentClient: sdk.createPandoraAgentClient,
+  connectPandoraAgentClient: sdk.connectPandoraAgentClient,
+};
+
+api.default = api;
+
+module.exports = Object.freeze(api);

package/backends.mjs

@@ -0,0 +1,14 @@
+import api from './backends.js';
+export const {
+  PandoraAgentClient,
+  PandoraMcpBackend,
+  PandoraStdioBackend,
+  PandoraRemoteBackend,
+  createPandoraStdioBackend,
+  createPandoraRemoteBackend,
+  createLocalPandoraAgentClient,
+  createRemotePandoraAgentClient,
+  createPandoraAgentClient,
+  connectPandoraAgentClient,
+} = api;
+export default api;

package/catalog.d.ts

@@ -0,0 +1,26 @@
+export {
+  loadGeneratedContractRegistry,
+  loadGeneratedManifest,
+  loadGeneratedCommandDescriptors,
+  loadGeneratedMcpToolDefinitions,
+  loadGeneratedCapabilities,
+  loadGeneratedToolCatalog,
+  getPolicyProfileCapabilities,
+  getPolicyPackCapability,
+  getSignerProfileCapability,
+  listPolicyScopes,
+  listPolicyScopedCommands,
+  listSignerProfileCommands,
+  inspectPolicyScope,
+  inspectToolPolicySurface,
+  type PandoraCommandDescriptor,
+  type PandoraContractRegistry,
+  type PandoraGeneratedManifest,
+  type PandoraGeneratedMcpToolDefinition,
+  type PandoraPolicyPackCapability,
+  type PandoraPolicyProfileCapabilities,
+  type PandoraPolicyScopeInspection,
+  type PandoraSignerProfileCapability,
+  type PandoraToolContract,
+  type PandoraToolPolicySurface,
+} from './index';

package/catalog.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const sdk = require('./index.js');
+
+const api = {
+  loadGeneratedContractRegistry: sdk.loadGeneratedContractRegistry,
+  loadGeneratedManifest: sdk.loadGeneratedManifest,
+  loadGeneratedCommandDescriptors: sdk.loadGeneratedCommandDescriptors,
+  loadGeneratedMcpToolDefinitions: sdk.loadGeneratedMcpToolDefinitions,
+  loadGeneratedCapabilities: sdk.loadGeneratedCapabilities,
+  loadGeneratedToolCatalog: sdk.loadGeneratedToolCatalog,
+  getPolicyProfileCapabilities: sdk.getPolicyProfileCapabilities,
+  getPolicyPackCapability: sdk.getPolicyPackCapability,
+  getSignerProfileCapability: sdk.getSignerProfileCapability,
+  listPolicyScopes: sdk.listPolicyScopes,
+  listPolicyScopedCommands: sdk.listPolicyScopedCommands,
+  listSignerProfileCommands: sdk.listSignerProfileCommands,
+  inspectPolicyScope: sdk.inspectPolicyScope,
+  inspectToolPolicySurface: sdk.inspectToolPolicySurface,
+};
+
+api.default = api;
+
+module.exports = Object.freeze(api);

package/catalog.mjs

@@ -0,0 +1,18 @@
+import api from './catalog.js';
+export const {
+  loadGeneratedContractRegistry,
+  loadGeneratedManifest,
+  loadGeneratedCommandDescriptors,
+  loadGeneratedMcpToolDefinitions,
+  loadGeneratedCapabilities,
+  loadGeneratedToolCatalog,
+  getPolicyProfileCapabilities,
+  getPolicyPackCapability,
+  getSignerProfileCapability,
+  listPolicyScopes,
+  listPolicyScopedCommands,
+  listSignerProfileCommands,
+  inspectPolicyScope,
+  inspectToolPolicySurface,
+} = api;
+export default api;

package/errors.d.ts

@@ -0,0 +1,7 @@
+export {
+  PandoraSdkError,
+  PandoraToolCallError,
+  normalizeStructuredEnvelope,
+  type PandoraCallToolRawResult,
+  type PandoraSdkErrorDetails,
+} from './index';

package/errors.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const sdk = require('./index.js');
+
+const api = {
+  PandoraSdkError: sdk.PandoraSdkError,
+  PandoraToolCallError: sdk.PandoraToolCallError,
+  normalizeStructuredEnvelope: sdk.normalizeStructuredEnvelope,
+};
+
+api.default = api;
+
+module.exports = Object.freeze(api);

package/errors.mjs

@@ -0,0 +1,7 @@
+import api from './errors.js';
+export const {
+  PandoraSdkError,
+  PandoraToolCallError,
+  normalizeStructuredEnvelope,
+} = api;
+export default api;

package/examples/local-stdio.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+const { connectPandoraAgentClient } = require('..');
+
+async function main() {
+  const client = await connectPandoraAgentClient({
+    command: 'pandora',
+    args: ['mcp'],
+  });
+
+  try {
+    const capabilities = await client.callTool('capabilities');
+    console.log(capabilities.command, capabilities.data.summary.totalCommands);
+  } finally {
+    await client.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/remote-http.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const { connectPandoraAgentClient } = require('..');
+
+async function main() {
+  const client = await connectPandoraAgentClient({
+    mode: 'remote',
+    url: process.env.PANDORA_MCP_URL || 'http://127.0.0.1:8787/mcp',
+    authToken: process.env.PANDORA_MCP_TOKEN || undefined,
+  });
+
+  try {
+    const tools = await client.listTools();
+    console.log(`connected to ${tools.length} tools`);
+  } finally {
+    await client.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/generated/command-descriptors.d.ts

@@ -0,0 +1,5 @@
+import type { PandoraCommandDescriptor } from '../index';
+
+declare const commandDescriptors: Record<string, PandoraCommandDescriptor>;
+
+export = commandDescriptors;