@ziggs-ai/agent-sdk 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",

package/src/adapters/McpAdapter.ts

@@ -8,7 +8,110 @@ import type { Workflow } from '../types.js';
 
 export type McpTransportConfig =
   | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
-  | { type: 'http'; url: string };
+  | { type: 'http'; url: string }
+  | {
+      /**
+       * Brokered connection through the Ziggs MCP gateway: the agent speaks
+       * StreamableHTTP to `/connections/:id/mcp` and Ziggs injects the
+       * connection owner's OAuth token upstream. The agent never holds the
+       * token; every tools/call is checked against the grant's caveats.
+       */
+      type: 'ziggs';
+      /** Connection id (`con_…`) of the user's MCP server connection. */
+      connectionId: string;
+      /** ConnectionGrant id (`cgr_…`) issued to this agent. */
+      grantId: string;
+      /** Operator key — defaults to ZIGGS_OPERATOR_KEY. */
+      operatorKey?: string;
+      /** Ziggs backend base URL — defaults to BACKEND_URL / ZIGGS_BACKEND_URL. */
+      baseUrl?: string;
+      /** Agent to impersonate (X-Agent-Id) — defaults to the host agentId. */
+      agentId?: string;
+    };
+
+/**
+ * Typed failure from the Ziggs MCP gateway (ZIG-702). `code` is the stable
+ * machine-readable reason — e.g. `GRANT_REVOKED`, `GRANT_EXPIRED`,
+ * `GRANT_HOLDER_MISMATCH`, `GRANT_CONNECTION_MISMATCH` — so agent code can
+ * branch ("revoked → tell the user and stop retrying" vs "network blip →
+ * retry") instead of parsing transport-error prose.
+ */
+export class ZiggsGatewayError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(code: string, message: string, status: number) {
+    super(message);
+    this.name = 'ZiggsGatewayError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * Wrap fetch so structured gateway denials (401/403 with a `code` body)
+ * surface as ZiggsGatewayError instead of a generic transport failure.
+ */
+export function wrapGatewayFetch(
+  baseFetch: typeof fetch = fetch,
+): typeof fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const response = await baseFetch(input, init);
+    if (response.status === 401 || response.status === 403) {
+      const body = (await response
+        .clone()
+        .json()
+        .catch(() => null)) as { code?: unknown; message?: unknown } | null;
+      if (body && typeof body.code === 'string') {
+        throw new ZiggsGatewayError(
+          body.code,
+          typeof body.message === 'string' ? body.message : body.code,
+          response.status,
+        );
+      }
+    }
+    return response;
+  }) as typeof fetch;
+}
+
+/** Resolve the gateway URL + auth headers for a `type: 'ziggs'` transport. */
+export function resolveZiggsGatewayTarget(
+  config: Extract<McpTransportConfig, { type: 'ziggs' }>,
+  defaults: { agentId?: string } = {},
+): { url: URL; headers: Record<string, string> } {
+  if (!config.connectionId) {
+    throw new Error('ziggs MCP transport requires a connectionId');
+  }
+  if (!config.grantId) {
+    throw new Error('ziggs MCP transport requires a grantId');
+  }
+  const operatorKey = config.operatorKey || process.env.ZIGGS_OPERATOR_KEY;
+  if (!operatorKey) {
+    throw new Error(
+      'ziggs MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)',
+    );
+  }
+  const agentId = config.agentId || defaults.agentId;
+  if (!agentId) {
+    throw new Error(
+      'ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)',
+    );
+  }
+  const baseUrl = (
+    config.baseUrl ||
+    process.env.BACKEND_URL ||
+    process.env.ZIGGS_BACKEND_URL ||
+    'http://localhost:3000'
+  ).replace(/\/$/, '');
+  return {
+    url: new URL(`${baseUrl}/connections/${encodeURIComponent(config.connectionId)}/mcp`),
+    headers: {
+      authorization: `Bearer ${operatorKey}`,
+      'x-agent-id': agentId,
+      'x-grant-id': config.grantId,
+    },
+  };
+}
 
 export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' | 'workflow' | 'states' | 'initial'> {
   /** MCP server connection — stdio (local process) or HTTP (remote). */
@@ -27,7 +130,7 @@ export interface McpAgentHandle {
   toolNames: string[];
 }
 
-function buildTransport(config: McpTransportConfig) {
+function buildTransport(config: McpTransportConfig, defaults: { agentId?: string }) {
   if (config.type === 'stdio') {
     return new StdioClientTransport({
       command: config.command,
@@ -35,6 +138,13 @@ function buildTransport(config: McpTransportConfig) {
       env: config.env,
     });
   }
+  if (config.type === 'ziggs') {
+    const target = resolveZiggsGatewayTarget(config, defaults);
+    return new StreamableHTTPClientTransport(target.url, {
+      requestInit: { headers: target.headers },
+      fetch: wrapGatewayFetch(),
+    });
+  }
   return new StreamableHTTPClientTransport(new URL(config.url));
 }
 
@@ -81,28 +191,6 @@ function mapMcpTools(client: Client, tools: McpTool[]): ToolDefinition[] {
   }));
 }
 
-/**
- * Wraps any MCP server as a Ziggs AgentHost.
- *
- * 1. Opens a connection to the MCP server (stdio or HTTP).
- * 2. Calls tools/list and maps each tool to a Ziggs ToolDefinition.
- * 3. Returns an AgentHost pre-loaded with those tools, ready to connectAsync().
- *
- * Usage:
- *   const { host, closeMcp } = await createMcpAgent({
- *     transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
- *     agentId: 'my-github-agent',
- *     name: 'GitHub Agent',
- *     description: 'Wraps the GitHub MCP server',
- *   });
- *   await host.connectAsync();
- *
- *   process.on('SIGTERM', async () => {
- *     host.disconnect();
- *     await host.drain();
- *     await closeMcp();
- *   });
- */
 function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflow {
   const dflt = thinkingDefaults({ initial: 'idle' });
   // Bind each MCP tool as an explicit action so runTurn includes them in the
@@ -157,11 +245,11 @@ function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflo
 /**
  * Wraps any MCP server as a Ziggs AgentHost.
  *
- * 1. Opens a connection to the MCP server (stdio or HTTP).
+ * 1. Opens a connection to the MCP server (stdio, HTTP, or the Ziggs gateway).
  * 2. Calls tools/list and maps each tool to a Ziggs ToolDefinition.
  * 3. Returns an AgentHost pre-loaded with those tools, ready to connectAsync().
  *
- * Usage:
+ * Usage (local stdio server):
  *   const { host, closeMcp } = await createMcpAgent({
  *     transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },
  *     agentId: 'my-github-agent',
@@ -170,6 +258,17 @@ function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflo
  *   });
  *   await host.connectAsync();
  *
+ * Usage (OAuth-protected remote server, brokered through Ziggs — the user
+ * connected the server and issued this agent a grant; the agent never sees
+ * the user's token):
+ *   const { host, closeMcp } = await createMcpAgent({
+ *     transport: { type: 'ziggs', connectionId: 'con_abc', grantId: 'cgr_xyz' },
+ *     agentId: 'my-notion-agent',
+ *     name: 'Notion Agent',
+ *     description: 'Works in the owner\'s Notion via their MCP connection',
+ *   });
+ *   await host.connectAsync();
+ *
  *   process.on('SIGTERM', async () => {
  *     host.disconnect();
  *     await host.drain();
@@ -179,7 +278,7 @@ function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflo
 export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle> {
   const { transport: transportConfig, extraTools = [], workflow, ...hostOptions } = options;
 
-  const transport = buildTransport(transportConfig);
+  const transport = buildTransport(transportConfig, { agentId: hostOptions.agentId });
   const client = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
 
   await client.connect(transport);

package/src/index.ts

@@ -9,7 +9,7 @@
  */
 
 export { defineAgent } from './defineAgent.js';
-export { createMcpAgent } from './adapters/McpAdapter.js';
+export { createMcpAgent, resolveZiggsGatewayTarget, wrapGatewayFetch, ZiggsGatewayError } from './adapters/McpAdapter.js';
 export type { CreateMcpAgentOptions, McpAgentHandle, McpTransportConfig } from './adapters/McpAdapter.js';
 export { AgentHost, createAgent, createAgentPool } from './AgentHost.js';
 export { Agent } from './agent/Agent.js';

package/src/server/tools/index.ts

@@ -32,7 +32,7 @@ export {
   PAYMENT_TOOLS,
   paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
   paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
-  paymentIssueTokenTool, paymentAttenuateTokenTool, paymentRevokeTokenTool, paymentListTokensTool,
+  paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool,
 } from './tier2/paymentTools.js';
 export {
   CONNECTION_TOOLS,

package/src/server/tools/tier2/paymentTools.ts

@@ -121,14 +121,8 @@ export const paymentIssueGrantTool: ToolDefinition = defineTool('payment_issue_g
   issueGrantHandler,
 );
 
-/** @deprecated Use payment_issue_grant */
-export const paymentIssueTokenTool: ToolDefinition = defineTool('payment_issue_token',
-  { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
-  issueGrantHandler,
-);
-
 const attenuateGrantHandler = async (args: AnyObj, ctx: Ctx) => {
-  const grantId = (args['grantId'] || args['tokenId']) as string;
+  const grantId = args['grantId'] as string;
   if (!grantId) throw new Error('grantId is required');
   if (!args['holderId']) throw new Error('holderId is required');
   try {
@@ -144,14 +138,8 @@ export const paymentAttenuateGrantTool: ToolDefinition = defineTool('payment_att
   attenuateGrantHandler,
 );
 
-/** @deprecated Use payment_attenuate_grant */
-export const paymentAttenuateTokenTool: ToolDefinition = defineTool('payment_attenuate_token',
-  { tokenId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' },
-  attenuateGrantHandler,
-);
-
 const revokeGrantHandler = async (args: AnyObj, ctx: Ctx) => {
-  const grantId = (args['grantId'] || args['tokenId']) as string;
+  const grantId = args['grantId'] as string;
   if (!grantId) throw new Error('grantId is required');
   try {
     const result = await clientFor(ctx).revokeGrant(grantId) as AnyObj;
@@ -164,12 +152,6 @@ export const paymentRevokeGrantTool: ToolDefinition = defineTool('payment_revoke
   revokeGrantHandler,
 );
 
-/** @deprecated Use payment_revoke_grant */
-export const paymentRevokeTokenTool: ToolDefinition = defineTool('payment_revoke_token',
-  { tokenId: { type: 'string', required: true } },
-  revokeGrantHandler,
-);
-
 const listGrantsHandler = async (_args: AnyObj, ctx: Ctx) => {
   try {
     const result = await clientFor(ctx).listGrants();
@@ -181,11 +163,6 @@ export const paymentListGrantsTool: ToolDefinition = defineTool('payment_list_gr
   listGrantsHandler,
 );
 
-/** @deprecated Use payment_list_grants */
-export const paymentListTokensTool: ToolDefinition = defineTool('payment_list_tokens', {},
-  listGrantsHandler,
-);
-
 export const PAYMENT_TOOLS: ToolDefinition[] = [
   paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
   paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,