@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

package/dist/adapters/AnthropicAdapter.d.ts

@@ -0,0 +1,39 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { LlmMessage, LlmResponse, LlmToolSchema } from '../types.js';
+interface AdapterOptions {
+    key?: string;
+    model?: string;
+}
+/**
+ * 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 declare class AnthropicAdapter {
+    private client;
+    model: string;
+    constructor({ key, model }: AdapterOptions);
+    chat(prompt: string, tools?: LlmToolSchema[], _temperature?: number, systemHints?: LlmMessage[], options?: Record<string, unknown>): Promise<LlmResponse>;
+    chatMessages(messages: LlmMessage[], tools?: LlmToolSchema[], _options?: Record<string, unknown>): Promise<LlmResponse>;
+    chatMessagesStream(messages: LlmMessage[], onChunk: (text: string) => void): Promise<{
+        text: string;
+        usage: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        } | undefined;
+    }>;
+}
+/**
+ * Convert the runtime's tool list into Anthropic's `tools` param.
+ *
+ * The declared `LlmToolSchema` type (`{ type, function }`) is a lie at runtime:
+ * `runTurn` launders `ToolDefinition[]` (shape `{ schema: { function } }`)
+ * through an `as unknown as LlmToolSchema[]` cast before it reaches any adapter.
+ * OpenAIAdapter already reads `t.schema.function || t.schema`; this must do the
+ * same, or every claude-backed agent whose state exposes ≥1 tool crashes on
+ * `t.function` being undefined ("Cannot read properties of undefined (reading
+ * 'name')"). Both shapes are accepted so raw wire-shaped tools also work.
+ */
+export declare function toAnthropicTools(tools?: LlmToolSchema[]): Anthropic.Tool[] | undefined;
+export {};

package/dist/adapters/AnthropicAdapter.js

@@ -0,0 +1,200 @@
+import Anthropic from '@anthropic-ai/sdk';
+import { runtimeLog } from '../shared/runtimeLog.js';
+// 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 {
+    client;
+    model;
+    constructor({ key, model = 'claude-opus-4-8' }) {
+        this.client = new Anthropic({ apiKey: key });
+        this.model = model;
+    }
+    async chat(prompt, tools = [], _temperature = 0, systemHints = [], options = {}) {
+        const messages = [
+            { role: 'system', content: 'Respond with valid JSON.' },
+            ...systemHints,
+            { role: 'user', content: prompt },
+        ];
+        return this.chatMessages(messages, tools, options);
+    }
+    async chatMessages(messages, tools = [], _options = {}) {
+        const { system, anthropicMessages } = translateMessages(messages);
+        const anthropicTools = toAnthropicTools(tools);
+        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.type === 'text')
+                .map(b => b.text)
+                .join('')
+                .trim() || null;
+            const toolCalls = (() => {
+                const uses = res.content.filter((b) => 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;
+            runtimeLog.error('AnthropicAdapter', `LLM API call failed: ${err.message}`, {
+                model: this.model,
+                error: err.message,
+                status: err.status ?? 'unknown',
+            });
+            throw error;
+        }
+    }
+    async chatMessagesStream(messages, onChunk) {
+        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);
+        });
+        const final = await stream.finalMessage();
+        const u = final.usage;
+        // Fold cache read/creation into prompt tokens so the streamed reply is not
+        // undercounted (cache traffic was the bulk of the ZIG-759 drain).
+        const usage = u
+            ? {
+                prompt_tokens: (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0),
+                completion_tokens: u.output_tokens ?? 0,
+                total_tokens: (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.output_tokens ?? 0),
+            }
+            : undefined;
+        return { text, usage };
+    }
+}
+/**
+ * Convert the runtime's tool list into Anthropic's `tools` param.
+ *
+ * The declared `LlmToolSchema` type (`{ type, function }`) is a lie at runtime:
+ * `runTurn` launders `ToolDefinition[]` (shape `{ schema: { function } }`)
+ * through an `as unknown as LlmToolSchema[]` cast before it reaches any adapter.
+ * OpenAIAdapter already reads `t.schema.function || t.schema`; this must do the
+ * same, or every claude-backed agent whose state exposes ≥1 tool crashes on
+ * `t.function` being undefined ("Cannot read properties of undefined (reading
+ * 'name')"). Both shapes are accepted so raw wire-shaped tools also work.
+ */
+export function toAnthropicTools(tools = []) {
+    if (!tools.length)
+        return undefined;
+    return tools.map(t => {
+        const td = t;
+        const fn = (td.schema?.function ?? td.function ?? {});
+        return {
+            name: fn['name'],
+            description: fn['description'] ?? '',
+            input_schema: (fn['parameters'] ?? { type: 'object' }),
+        };
+    });
+}
+/**
+ * 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) {
+    const systemParts = [];
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'system') {
+            if (m.content)
+                systemParts.push(m.content);
+            continue;
+        }
+        if (m.role === 'tool') {
+            const block = {
+                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.push(block);
+            }
+            else {
+                out.push({ role: 'user', content: [block] });
+            }
+            continue;
+        }
+        if (m.role === 'assistant' && m.tool_calls?.length) {
+            const blocks = [];
+            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) {
+    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/dist/adapters/McpAdapter.d.ts

@@ -0,0 +1,199 @@
+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 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;
+} | {
+    /**
+     * Per-user brokered connection (ZIG-771): the agent holds NO
+     * connectionId/grantId. It speaks StreamableHTTP to
+     * `/connections/mcp/relay` and asserts the invoking end-user via
+     * `x-on-behalf-of-user`; the gateway resolves that user's own connection
+     * + grant and injects their token. One MCP client is created per invoking
+     * user so each keeps an isolated upstream session. Tool schemas cannot be
+     * discovered at boot (there is no connection yet) — pass `toolSchema`.
+     */
+    type: 'ziggs-per-user';
+    /** 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;
+    /**
+     * The MCP server URL this agent fronts. Not used for gateway calls (the
+     * gateway derives the server from the resolved connection), but needed to
+     * open a connection request when the invoking user hasn't connected yet
+     * (ZIG-771). Without it, a NO_USER_CONNECTION surfaces as an error rather
+     * than an auto-created consent prompt.
+     */
+    serverUrl?: 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 declare class ZiggsGatewayError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+/**
+ * Wrap fetch so structured gateway denials (401/403 with a `code` body)
+ * surface as ZiggsGatewayError instead of a generic transport failure.
+ */
+export declare function wrapGatewayFetch(baseFetch?: typeof fetch): typeof fetch;
+/** Resolve the gateway URL + auth headers for a `type: 'ziggs'` transport. */
+export declare function resolveZiggsGatewayTarget(config: Extract<McpTransportConfig, {
+    type: 'ziggs';
+}>, defaults?: {
+    agentId?: string;
+}): {
+    url: URL;
+    headers: Record<string, string>;
+};
+/**
+ * Resolve the per-user gateway URL + headers (ZIG-771). No connectionId/grantId —
+ * the gateway resolves the invoking user's own connection + grant from
+ * `x-on-behalf-of-user` + the impersonated agent.
+ */
+export declare function resolvePerUserGatewayTarget(config: Extract<McpTransportConfig, {
+    type: 'ziggs-per-user';
+}>, agentId: string, userId: string, onBehalfOfAgreementId?: string): {
+    url: URL;
+    headers: Record<string, string>;
+};
+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;
+    /**
+     * Restrict the bound tool set to only tools whose name matches one of these
+     * case-insensitive substrings, applied BEFORE the maxTools cap. Lets a large
+     * MCP server (e.g. PostHog's 146 tools) be narrowed to the handful this agent
+     * actually needs — cutting per-turn cost and stopping the model from thrashing
+     * across (or never binding) the tool it should call. Empty/undefined = bind
+     * all (unchanged behavior). ZIG-759 Phase 2 = name-based selection.
+     */
+    allowedTools?: string[];
+    /**
+     * Pre-discovered MCP tool schemas. REQUIRED for `type: 'ziggs-per-user'`
+     * (ZIG-771) — there is no boot connection to call `tools/list` on, so the
+     * schema is baked at provision time and passed here. Ignored for the other
+     * transports, which discover tools live at boot.
+     */
+    toolSchema?: Array<{
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    }>;
+}
+/**
+ * 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 declare function mcpToolBudget(maxTools: number, extraToolCount: number): number;
+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 declare function buildTransport(config: McpTransportConfig, defaults?: {
+    agentId?: string;
+}): StdioClientTransport | StreamableHTTPClientTransport;
+/**
+ * Max chars for a single tool description bound to the LLM. Verbose MCP servers
+ * embed whole manuals in their descriptions (PostHog's `execute-sql` alone is
+ * ~30K chars of HogQL docs; its 146 tools total ~54K tokens of descriptions) and
+ * that full block rides every turn. Keep the lead — what the tool does + how to
+ * call it — and drop the embedded reference; agents fetch detail via dedicated
+ * schema/help tools at call time. Tunable; big enough to preserve real guidance.
+ * ZIG-759.
+ */
+export declare const MAX_TOOL_DESC_CHARS = 2000;
+/** Truncate one description at a sentence/newline boundary near the cap. */
+export declare function trimDescription(desc: string | undefined): string | undefined;
+/**
+ * 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 declare function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle>;