@ziggs-ai/agent-sdk 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.8",
+  "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,30 +191,17 @@ 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): Workflow {
+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
+  // LLM API call and the decision schema. Without this, allowedToolNames is
+  // empty and the tools array passed to the LLM is also empty.
+  const toolActions = Object.fromEntries(
+    mcpTools.map(t => [t.name, {
+      tool: t.name,
+      prompt: { when: t.description || `Use ${t.name}` },
+    }]),
+  );
   return {
     id: 'mcp-agent',
     description: description || 'MCP-backed agent',
@@ -115,10 +212,31 @@ function buildDefaultWorkflow(description: string): Workflow {
         prompt: {
           role: 'You are a helpful agent powered by an MCP server.',
           goal: description || 'Help the user by calling the available tools.',
-          constraints: 'Use your tools to answer requests. When no action is needed, wait.',
+          constraints: 'Use your tools to answer the user\'s request. After gathering results, use "respond" to send the answer. Use "wait" only when no action is needed.',
         },
-        actions: { ...dflt.actions },
-        transitions: [...dflt.transitions],
+        actions: {
+          ...dflt.actions,
+          ...toolActions,
+          respond: {
+            prompt: {
+              instruction: 'Send your final answer to the user.',
+              when: 'You have gathered enough information and are ready to reply to the user.',
+              format: 'args: { receiverId: "<userId>", message: "<your answer>" }',
+            },
+            produces: 'message-sent',
+          },
+        },
+        transitions: [
+          { to: 'idle', when: (o) => o.kind === 'wait' },
+          { to: 'idle', when: (o) => o.kind === 'error' },
+          { to: 'done', when: (o) => o.kind === 'message-sent' },
+        ],
+      },
+      done: {
+        kind: 'parked',
+        transitions: [
+          { to: 'idle', when: (o) => o.kind === 'message-received' },
+        ],
       },
     },
   };
@@ -127,11 +245,11 @@ function buildDefaultWorkflow(description: string): Workflow {
 /**
  * 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',
@@ -140,6 +258,17 @@ function buildDefaultWorkflow(description: string): Workflow {
  *   });
  *   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();
@@ -149,7 +278,7 @@ function buildDefaultWorkflow(description: string): Workflow {
 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);
@@ -157,7 +286,7 @@ export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<Mc
   const { tools: rawTools } = await client.listTools();
   const mcpTools = mapMcpTools(client, rawTools as McpTool[]);
 
-  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '');
+  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools as McpTool[]);
 
   const host = new AgentHost({
     ...hostOptions,

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/runtime/validateWorkflow.ts

@@ -169,7 +169,7 @@ export function validateWorkflow(workflow: Workflow): ValidationResult {
         });
         if (!hasErrorFallthrough) {
           warnings.push(
-            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard (ZIG-303). Add an error transition or spread thinkingDefaults().transitions.`,
+            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard. Add an error transition or spread thinkingDefaults().transitions.`,
           );
         }
       }

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,
@@ -42,6 +42,5 @@ export {
 export {
   CONTEXT_TOOLS,
   contextDiscoverTool,
-  contextListGrantsTool,
   contextDelegateTool,
 } from './tier2/contextTools.js';

package/src/server/tools/tier1/protocolRunner.ts

@@ -32,6 +32,7 @@ interface ProtocolPayload {
   parentAgreementId?: string;
   parentTaskId?: string;
   taskId?: string;
+  assigneeId?: string;
   status?: string;
   result?: unknown;
   plan?: unknown;
@@ -95,6 +96,7 @@ export async function dispatchProtocolOp(
         plan: payload.plan,
         planReviewTiming: payload.planReviewTiming,
         requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
+        assigneeId: payload.assigneeId,
       });
     case 'task-update':
       if (!payload.taskId || !payload.status) return null;

package/src/server/tools/tier1/protocolTools.ts

@@ -87,9 +87,9 @@ export const taskUpdatePlanStepTool: ToolDefinition = defineTool(
 
 export const taskSpawnTool: ToolDefinition = defineTool(
   'task_spawn',
-  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
+  { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, plan: { type: 'object' }, planReviewTiming: 'string', requireMidWorkPlanAck: 'boolean' },
   handlerFor('task-spawn'),
-  { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place.' },
+  { description: 'Spawn a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' },
 );
 
 export const PROTOCOL_TOOLS: ToolDefinition[] = [

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

@@ -18,17 +18,7 @@ export const contextDiscoverTool: ToolDefinition = defineTool(
   async (_args, ctx) => clientFor(ctx as Ctx).discover(),
   {
     description:
-      'List which chats, agreements, and org scopes this agent can reach via context grants (descriptors only — no message or artifact content).',
-  },
-);
-
-export const contextListGrantsTool: ToolDefinition = defineTool(
-  'context_list_grants',
-  {},
-  async (_args, ctx) => clientFor(ctx as Ctx).listGrants(),
-  {
-    description:
-      'List context grants held by this agent (grant ids and bounds). Does not fetch scoped content.',
+      'List every context grant this agent holds, as scope descriptors — grantId, scope, temporal, watermarkAt, expiresAt (no message or artifact content).',
   },
 );
 
@@ -69,6 +59,5 @@ export const contextDelegateTool: ToolDefinition = defineTool(
 
 export const CONTEXT_TOOLS = [
   contextDiscoverTool,
-  contextListGrantsTool,
   contextDelegateTool,
 ] as const;

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,

package/src/server/ziggscontext/ZiggsContextClient.ts

@@ -69,14 +69,6 @@ export class ZiggsContextClient {
     return (res['reach'] as ContextReachDescriptor[]) || [];
   }
 
-  /** List persisted grant rows held by this agent (may include signedBytes). */
-  async listGrants(): Promise<unknown[]> {
-    this.requireActAsAgent('listGrants');
-    const res = (await this._get('/context/grants')) as Record<string, unknown>;
-    const grants = (res['grants'] as Array<Record<string, unknown>>) || [];
-    return grants.filter((g) => g['holderId'] === this.actAsAgentId);
-  }
-
   /** Holder delegates a narrower child grant. */
   async delegate(params: DelegateContextGrantParams): Promise<unknown> {
     this.requireActAsAgent('delegate');