@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/src/adapters/AnthropicAdapter.ts

@@ -1,206 +0,0 @@
-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

@@ -1,348 +0,0 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
-import type { ToolDefinition } from '../tools/defineTool.js';
-import { thinkingDefaults } from '../runtime/defaults.js';
-import type { Workflow } from '../types.js';
-
-export type McpTransportConfig =
-  | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, 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). */
-  transport: McpTransportConfig;
-  /** Additional Ziggs tools to register alongside the MCP-derived ones. */
-  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 {
-  host: AgentHost;
-  /** Disconnect the MCP client (call on shutdown alongside host.disconnect()). */
-  closeMcp: () => Promise<void>;
-  /** Names of MCP tools that were mapped to Ziggs tools on startup. */
-  toolNames: string[];
-}
-
-export function buildTransport(config: McpTransportConfig, defaults: { agentId?: string } = {}) {
-  if (config.type === 'stdio') {
-    return new StdioClientTransport({
-      command: config.command,
-      args: config.args ?? [],
-      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),
-    config.headers && Object.keys(config.headers).length > 0
-      ? { requestInit: { headers: config.headers } }
-      : undefined,
-  );
-}
-
-type McpTool = {
-  name: string;
-  description?: string;
-  inputSchema?: Record<string, unknown>;
-};
-
-type McpContent = { type: string; text?: string };
-
-function mcpContentToResult(content: McpContent[]): unknown {
-  const text = content
-    .map(c => (c.type === 'text' ? c.text ?? '' : JSON.stringify(c)))
-    .join('\n');
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-function mapMcpTools(client: Client, tools: McpTool[]): ToolDefinition[] {
-  return tools.map(tool => ({
-    schema: {
-      type: 'function' as const,
-      function: {
-        name: tool.name,
-        description: tool.description ?? '',
-        parameters: tool.inputSchema ?? { type: 'object', properties: {} },
-      },
-    },
-    handler: async (args: Record<string, unknown>) => {
-      const result = await client.callTool({ name: tool.name, arguments: args }) as {
-        isError?: boolean;
-        content: McpContent[];
-      };
-      if (result.isError) {
-        throw new Error(mcpContentToResult(result.content) as string);
-      }
-      return mcpContentToResult(result.content);
-    },
-    isGenericFallback: true,
-  }));
-}
-
-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',
-    initial: 'idle',
-    states: {
-      idle: {
-        kind: 'thinking',
-        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 the user\'s request. After gathering results, use "respond" to send the answer. Use "wait" only when no action is needed.',
-        },
-        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' },
-        ],
-      },
-    },
-  };
-}
-
-/**
- * Wraps any MCP server as a Ziggs AgentHost.
- *
- * 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 (local stdio server):
- *   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();
- *
- * 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();
- *     await closeMcp();
- *   });
- */
-export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle> {
-  const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, ...hostOptions } = options;
-
-  const transport = buildTransport(transportConfig, { agentId: hostOptions.agentId });
-  const client = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
-
-  await client.connect(transport);
-
-  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);
-
-  const host = new AgentHost({
-    ...hostOptions,
-    workflow: resolvedWorkflow,
-    tools: [...mcpTools, ...extraTools],
-  });
-
-  return {
-    host,
-    closeMcp: () => client.close(),
-    toolNames: rawTools.map((t: McpTool) => t.name),
-  };
-}