@ziggs-ai/agent-sdk 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",
@@ -16,8 +16,9 @@
     "test:watch": "node --experimental-test-module-mocks --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.9",
+    "@ziggs-ai/api-client": "^0.1.25",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0"

package/src/AgentHost.ts

@@ -1,6 +1,7 @@
 import type { AgentConfig, Ctx, EffectHandler, Identity, Workflow } from './types.js';
 import { Agent } from './agent/Agent.js';
 import { EventQueue } from './server/EventQueue.js';
+import { StateTimers } from './server/StateTimers.js';
 import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent, type NormalizedEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
@@ -21,6 +22,7 @@ import { ToolManager } from './tools/ToolManager.js';
 import type { ToolDefinition } from './tools/defineTool.js';
 import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import {
   WebSocketClient,
   MessagesClient,
@@ -65,6 +67,7 @@ interface AgentServices {
 
 export interface AgentHostOptions {
   openaiKey?: string;
+  anthropicKey?: string;
   model?: string;
   operatorKey?: string;
   agentId?: string;
@@ -124,9 +127,12 @@ function isLlmAdapter(v: unknown): v is LlmAdapter {
 
 function createBackendServices(options: AgentHostOptions) {
   const toolManager = createToolManager(options);
+  const model = (options.services?.llm as { model?: string } | undefined)?.model || options.model;
   const llm = isLlmAdapter(options.services?.llm)
     ? options.services!.llm as LlmAdapter
-    : new OpenAIAdapter({ key: options.openaiKey, model: (options.services?.llm as { model?: string } | undefined)?.model || options.model });
+    : model?.startsWith('claude')
+      ? new AnthropicAdapter({ key: options.anthropicKey, model })
+      : new OpenAIAdapter({ key: options.openaiKey, model });
   const operatorKey = options.operatorKey!;
   const agentId = options.agentId!;
   const messagesClient = new MessagesClient(operatorKey, agentId);
@@ -180,12 +186,14 @@ export class AgentHost {
   private agreementService!: AgreementService;
   private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
   private seenMessages = new SeenMessages();
+  private stateTimers!: StateTimers;
   private catchUpInFlight: Promise<void> | null = null;
   private inboxCatchUpEnabled: boolean;
 
   constructor(options: AgentHostOptions = {}) {
     this.options = {
       openaiKey: options.openaiKey || process.env.OPENAI_API_KEY,
+      anthropicKey: options.anthropicKey || process.env.ANTHROPIC_API_KEY,
       model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || 'gpt-5.4',
       operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
       agentId: options.agentId || '',
@@ -215,7 +223,13 @@ export class AgentHost {
   }
 
   private _validate(): void {
-    if (!this.options.openaiKey) throw new Error('openaiKey is required');
+    if (!isLlmAdapter(this.options.services?.llm)) {
+      if (this.options.model?.startsWith('claude')) {
+        if (!this.options.anthropicKey) throw new Error('anthropicKey is required for claude-* models — pass { anthropicKey } or set ANTHROPIC_API_KEY');
+      } else if (!this.options.openaiKey) {
+        throw new Error('openaiKey is required');
+      }
+    }
     if (!this.options.operatorKey) throw new Error('operatorKey is required — pass { operatorKey } or set ZIGGS_OPERATOR_KEY');
     if (!this.options.agentId) throw new Error('agentId is required');
   }
@@ -278,6 +292,7 @@ export class AgentHost {
     });
 
     this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
+    this.stateTimers = new StateTimers((ev, laneKey) => { void this.eventQueue.enqueue(ev, laneKey); });
 
     this.wsClient.setMessageHandler((text: string, metadata: MessageMetadata) => this.handleMessage(text, metadata as unknown as Record<string, unknown>));
     this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event as unknown as Record<string, unknown>));
@@ -408,6 +423,15 @@ export class AgentHost {
     const session = this.sessions.get(laneKey);
     if (!session?.sessionId) return;
 
+    // Stale timer frames (superseded epoch) are dropped BEFORE touching the
+    // live timer — a pure-stale frame must not reset a freshly armed countdown.
+    const frame = this.stateTimers.stripStale(event, laneKey);
+    if (frame === null) return;
+
+    // Any event reaching the machine invalidates the countdown ("clear on any
+    // event for the lane"); re-armed below if the tick settles parked+timed.
+    this.stateTimers.clear(laneKey);
+
     // Cold-start recovery: restore FSM state from sessionStore when the
     // in-memory lane has no prior context (e.g. after a container restart).
     if (this.sessionStore && session.ctx === undefined && session.state === undefined) {
@@ -430,7 +454,7 @@ export class AgentHost {
 
     try {
       const result = await Promise.race([
-        this.agent.tick({ event, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap }),
+        this.agent.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory, transitionTap: this.options.transitionTap }),
         new Promise<never>((_, reject) =>
           setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs),
         ),
@@ -444,11 +468,37 @@ export class AgentHost {
           runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
         });
       }
+
+      // Arm only when the timeout was handled: an unhandled state-timeout must
+      // not re-arm, or the lane would runtimeLog.error every timeoutMs forever.
+      if (!result.stateTimeoutUnhandled) this._armIfTimedParked(laneKey, result.state);
     } catch (err: unknown) {
       runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+      // Deliberate re-arm on failure. Exact scenario: the tick timed out at
+      // tickTimeoutMs (or sessionStore.load threw) leaving session.state at a
+      // timed parked state — without re-arming, that lane would never wake
+      // again unless a real event happens to arrive.
+      this._armIfTimedParked(laneKey, session.state ?? this.agent.workflow.initial);
+      // Best-effort: also notify the user so the conversation isn't silently
+      // stuck (ZIG-607). Complements the timer re-arm above — that recovers a
+      // parked lane; this tells a waiting human.
+      const ev = event as Record<string, unknown> | undefined;
+      const senderType = String(ev?.senderType ?? '').toUpperCase();
+      const senderId = ev?.senderId as string | undefined;
+      if (senderId && senderType === 'USER') {
+        this.eff({ kind: 'send-message', sessionId: session.sessionId, receiverId: senderId, text: 'Something went wrong. Please try again.' }).catch(() => {});
+      }
     }
   }
 
+  /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
+  private _armIfTimedParked(laneKey: string, stateName: string | undefined): void {
+    if (!stateName) return;
+    const sd = this.agent.workflow.states[stateName];
+    if (sd?.kind !== 'parked' || sd.timeoutMs === undefined) return;
+    this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
+  }
+
   private _resolveOwnAgentId(metadata: Record<string, unknown> = {}): string | null {
     const self = metadata.self as Record<string, unknown> | undefined;
     const agent = metadata.agent as Record<string, unknown> | undefined;
@@ -467,7 +517,7 @@ export class AgentHost {
     }
     return this;
   }
-  disconnect() { this.wsClient.disconnect(); }
+  disconnect() { this.stateTimers.clearAll(); this.wsClient.disconnect(); }
   /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */
   drain(timeoutMs = 30_000): Promise<void> { return this.eventQueue.waitForIdle(timeoutMs); }
   registerTool(tool: ToolDefinition) { return this.toolManager.register(tool); }

package/src/adapters/AnthropicAdapter.ts

@@ -0,0 +1,206 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { LlmMessage, LlmResponse, LlmToolCall, LlmToolSchema } from '../types.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+interface AdapterOptions {
+  key?: string;
+  model?: string;
+}
+
+// Claude 4.7+ models reject sampling params (temperature/top_p/top_k) with a
+// 400 and run without thinking when the `thinking` param is omitted. We omit
+// both on purpose: the SDK's LlmMessage history cannot round-trip thinking
+// blocks through the tool loop, so thinking must stay off.
+const MAX_COMPLETION_TOKENS = 16000;
+
+/**
+ * Anthropic adapter satisfying the same LlmAdapter contract as OpenAIAdapter:
+ * OpenAI-wire-shaped LlmMessage[] in, { content, tool_calls, usage } out.
+ * Selected by AgentHost when the configured model id starts with "claude".
+ */
+export class AnthropicAdapter {
+  private client: Anthropic;
+  model: string;
+
+  constructor({ key, model = 'claude-opus-4-8' }: AdapterOptions) {
+    this.client = new Anthropic({ apiKey: key });
+    this.model = model;
+  }
+
+  async chat(
+    prompt: string,
+    tools: LlmToolSchema[] = [],
+    _temperature = 0,
+    systemHints: LlmMessage[] = [],
+    options: Record<string, unknown> = {},
+  ): Promise<LlmResponse> {
+    const messages: LlmMessage[] = [
+      { role: 'system', content: 'Respond with valid JSON.' },
+      ...systemHints,
+      { role: 'user', content: prompt },
+    ];
+    return this.chatMessages(messages, tools, options);
+  }
+
+  async chatMessages(
+    messages: LlmMessage[],
+    tools: LlmToolSchema[] = [],
+    _options: Record<string, unknown> = {},
+  ): Promise<LlmResponse> {
+    const { system, anthropicMessages } = translateMessages(messages);
+    const anthropicTools: Anthropic.Tool[] | undefined = tools.length > 0
+      ? tools.map(t => ({
+          name: t.function.name,
+          description: t.function.description ?? '',
+          input_schema: (t.function.parameters ?? { type: 'object' }) as Anthropic.Tool.InputSchema,
+        }))
+      : undefined;
+
+    try {
+      const res = await this.client.messages.create({
+        model: this.model,
+        max_tokens: MAX_COMPLETION_TOKENS,
+        ...(system ? { system } : {}),
+        messages: anthropicMessages,
+        ...(anthropicTools ? { tools: anthropicTools } : {}),
+      });
+
+      if (res.stop_reason === 'refusal') {
+        throw new Error(`LLM refused the request (stop_reason=refusal)`);
+      }
+
+      const content = res.content
+        .filter((b): b is Anthropic.TextBlock => b.type === 'text')
+        .map(b => b.text)
+        .join('')
+        .trim() || null;
+      const toolCalls: LlmToolCall[] | null = (() => {
+        const uses = res.content.filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use');
+        if (!uses.length) return null;
+        return uses.map(u => ({
+          id: u.id,
+          function: { name: u.name, arguments: JSON.stringify(u.input ?? {}) },
+        }));
+      })();
+
+      if (!content && !toolCalls && res.stop_reason === 'max_tokens') {
+        throw new Error(
+          `LLM returned no usable output — completion token budget exhausted before any content (stop_reason=max_tokens)`,
+        );
+      }
+
+      return {
+        content: content ?? undefined,
+        tool_calls: toolCalls ?? undefined,
+        usage: res.usage
+          ? {
+              prompt_tokens: res.usage.input_tokens,
+              completion_tokens: res.usage.output_tokens,
+              total_tokens: res.usage.input_tokens + res.usage.output_tokens,
+            }
+          : undefined,
+      };
+    } catch (error) {
+      const err = error as Error & { status?: number };
+      runtimeLog.error('AnthropicAdapter', `LLM API call failed: ${err.message}`, {
+        model: this.model,
+        error: err.message,
+        status: err.status ?? 'unknown',
+      });
+      throw error;
+    }
+  }
+
+  async chatMessagesStream(
+    messages: LlmMessage[],
+    onChunk: (text: string) => void,
+  ): Promise<string> {
+    const { system, anthropicMessages } = translateMessages(messages);
+    const stream = this.client.messages.stream({
+      model: this.model,
+      max_tokens: MAX_COMPLETION_TOKENS,
+      ...(system ? { system } : {}),
+      messages: anthropicMessages,
+    });
+    let text = '';
+    stream.on('text', (delta) => {
+      text += delta;
+      onChunk(delta);
+    });
+    await stream.finalMessage();
+    return text;
+  }
+}
+
+/**
+ * OpenAI-wire-shaped LlmMessage[] → Anthropic { system, messages }.
+ * - system messages concatenate into the top-level system param
+ * - assistant tool_calls become tool_use blocks (arguments JSON-parsed)
+ * - role:"tool" results become user-turn tool_result blocks
+ * Consecutive same-role turns are merged (Anthropic requires alternation to
+ * start with user; the API tolerates consecutive same-role, but tool_result
+ * blocks must open the user turn that answers a tool_use turn).
+ */
+function translateMessages(messages: LlmMessage[]): {
+  system: string | undefined;
+  anthropicMessages: Anthropic.MessageParam[];
+} {
+  const systemParts: string[] = [];
+  const out: Anthropic.MessageParam[] = [];
+
+  for (const m of messages) {
+    if (m.role === 'system') {
+      if (m.content) systemParts.push(m.content);
+      continue;
+    }
+    if (m.role === 'tool') {
+      const block: Anthropic.ToolResultBlockParam = {
+        type: 'tool_result',
+        tool_use_id: m.tool_call_id ?? '',
+        content: m.content ?? '',
+      };
+      const last = out[out.length - 1];
+      if (last && last.role === 'user' && Array.isArray(last.content)) {
+        (last.content as Anthropic.ContentBlockParam[]).push(block);
+      } else {
+        out.push({ role: 'user', content: [block] });
+      }
+      continue;
+    }
+    if (m.role === 'assistant' && m.tool_calls?.length) {
+      const blocks: Anthropic.ContentBlockParam[] = [];
+      if (m.content) blocks.push({ type: 'text', text: m.content });
+      for (const tc of m.tool_calls) {
+        blocks.push({
+          type: 'tool_use',
+          id: tc.id,
+          name: tc.function.name,
+          input: safeParseJson(tc.function.arguments),
+        });
+      }
+      out.push({ role: 'assistant', content: blocks });
+      continue;
+    }
+    out.push({ role: m.role, content: m.content ?? '' });
+  }
+
+  if (!out.length || out[0].role !== 'user') {
+    out.unshift({ role: 'user', content: '(session start)' });
+  }
+
+  return {
+    system: systemParts.length ? systemParts.join('\n\n') : undefined,
+    anthropicMessages: out,
+  };
+}
+
+function safeParseJson(s: string): Record<string, unknown> {
+  try {
+    const v = JSON.parse(s);
+    return typeof v === 'object' && v !== null ? v : {};
+  } catch {
+    // Malformed arguments string from a prior turn's history: replaying it as
+    // an empty input beats crashing the whole turn on someone else's output.
+    return {};
+  }
+}

package/src/adapters/McpAdapter.ts

@@ -8,7 +8,120 @@ 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;
+      /**
+       * Optional static request headers — e.g. a fixed API key the server is
+       * keyed by. Sent on every request to the server. Values are used as-is;
+       * `$VAR` interpolation (if any) is the caller's job, mirroring how the
+       * stdio path leaves `env` interpolation to the caller.
+       */
+      headers?: Record<string, 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). */
@@ -17,6 +130,28 @@ export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' |
   extraTools?: ToolDefinition[];
   /** Override the default single-state thinking workflow. */
   workflow?: Workflow;
+  /**
+   * Max tools to bind to the LLM per turn. LLM providers cap the `tools` array
+   * (OpenAI: 128); an MCP server exposing more (e.g. PostHog: 146) makes every
+   * turn fail with `400 ... array too long`. When the server's tool count
+   * exceeds this budget the list is truncated (and logged). Defaults to 128.
+   * See ZIG-759; Phase 2 will replace truncation with query-aware selection.
+   */
+  maxTools?: number;
+}
+
+/** Provider `tools` array cap (OpenAI's is 128). */
+const DEFAULT_MAX_TOOLS = 128;
+/** Headroom reserved for control actions (wait/respond) + future additions. */
+const CONTROL_TOOL_RESERVE = 4;
+
+/**
+ * How many MCP tools may be bound to the LLM, given the provider cap and the
+ * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
+ * pathological config still binds something rather than nothing. ZIG-759.
+ */
+export function mcpToolBudget(maxTools: number, extraToolCount: number): number {
+  return Math.max(1, maxTools - CONTROL_TOOL_RESERVE - extraToolCount);
 }
 
 export interface McpAgentHandle {
@@ -27,7 +162,7 @@ export interface McpAgentHandle {
   toolNames: string[];
 }
 
-function buildTransport(config: McpTransportConfig) {
+export function buildTransport(config: McpTransportConfig, defaults: { agentId?: string } = {}) {
   if (config.type === 'stdio') {
     return new StdioClientTransport({
       command: config.command,
@@ -35,7 +170,19 @@ function buildTransport(config: McpTransportConfig) {
       env: config.env,
     });
   }
-  return new StreamableHTTPClientTransport(new URL(config.url));
+  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),
+    config.headers && Object.keys(config.headers).length > 0
+      ? { requestInit: { headers: config.headers } }
+      : undefined,
+  );
 }
 
 type McpTool = {
@@ -81,28 +228,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 +282,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 +295,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();
@@ -177,17 +313,26 @@ function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflo
  *   });
  */
 export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle> {
-  const { transport: transportConfig, extraTools = [], workflow, ...hostOptions } = options;
+  const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, ...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);
 
-  const { tools: rawTools } = await client.listTools();
-  const mcpTools = mapMcpTools(client, rawTools as McpTool[]);
+  const listed = (await client.listTools()).tools as McpTool[];
+  // Cap the tool set bound to the LLM: providers reject a `tools` array longer
+  // than their limit (OpenAI 128). Truncate — never crash — and log what dropped
+  // so a large server (e.g. PostHog: 146 tools) still answers. ZIG-759 Phase 1.
+  const budget = mcpToolBudget(maxTools, extraTools.length);
+  let rawTools = listed;
+  if (listed.length > budget) {
+    rawTools = listed.slice(0, budget);
+    console.warn(`[McpAdapter] ${hostOptions.agentId}: MCP server exposes ${listed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${rawTools.length}, dropping ${listed.length - rawTools.length}. (ZIG-759 Phase 2 will select per query.)`);
+  }
+  const mcpTools = mapMcpTools(client, rawTools);
 
-  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools as McpTool[]);
+  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools);
 
   const host = new AgentHost({
     ...hostOptions,

package/src/adapters/OpenAIAdapter.ts

@@ -14,6 +14,13 @@ interface AdapterOptions {
   model?: string;
 }
 
+/** OpenAI completion-token cap varies by model family (e.g. gpt-4o-mini max 16384). */
+export function maxCompletionTokensForModel(model: string): number {
+  const m = model.toLowerCase();
+  if (m.includes('gpt-4o')) return 16384;
+  return 25000;
+}
+
 export class OpenAIAdapter {
   private client: OpenAI;
   model: string;
@@ -99,11 +106,9 @@ export class OpenAIAdapter {
         model: this.model,
         messages: finalMessages,
         stream: false,
-        // 25000 reserves room for hidden reasoning tokens on reasoning models
-        // (gpt-5.x/o-series) — they're billed against this cap before any
-        // visible content, so a low cap can exhaust the budget and return
-        // empty content with finish_reason "length".
-        max_completion_tokens: 25000,
+        // Reasoning models (gpt-5.x/o-series) need a high cap for hidden
+        // reasoning tokens; gpt-4o family is capped lower by the API.
+        max_completion_tokens: maxCompletionTokensForModel(this.model),
         response_format: responseFormat,
         ...(openAITools && { tools: openAITools }),
         ...restOptions,
@@ -167,7 +172,7 @@ export class OpenAIAdapter {
       model: this.model,
       messages,
       stream: true,
-      max_completion_tokens: 25000,
+      max_completion_tokens: maxCompletionTokensForModel(this.model),
     });
     let text = '';
     for await (const chunk of stream) {

package/src/adapters/index.ts

@@ -1 +1,2 @@
 export { OpenAIAdapter } from './OpenAIAdapter.js';
+export { AnthropicAdapter } from './AnthropicAdapter.js';