@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/dist/agent/Agent.d.ts

@@ -0,0 +1,78 @@
+import type { Ctx, Identity, Workflow, EffectHandler } from '../types.js';
+import { type TransitionEvent } from '../runtime/AgentMachine.js';
+import { PromptBuilder } from '../runtime/PromptBuilder.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+export interface AgentOptions {
+    workflow: Workflow;
+    toolManager: ToolManager;
+    promptBuilder?: PromptBuilder;
+}
+export interface TickInput {
+    /** Wire event (already normalized: a `message` or `task_result`-style envelope). */
+    event: unknown;
+    /** Server-provided per-session state. Omit on the first tick — a fresh ctx is constructed. */
+    ctx?: Ctx;
+    /** Server-provided workflow state name. Omit on the first tick — defaults to `workflow.initial`. */
+    state?: string;
+    /** Who am I and what session am I running in. The Agent carries this through Ctx. */
+    identity: Identity;
+    /** The single side channel for I/O — LLM, context, tools, send, record. */
+    eff: EffectHandler;
+    /**
+     * Agent-private long-term memory. Operator-provided (default
+     * `InMemoryStore` when omitted by `AgentHost`). Key shape is the agent's
+     * choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
+     */
+    memory?: MemoryStore;
+    /** Optional tap for FSM transition events (ZIG-442). */
+    transitionTap?: (event: TransitionEvent) => void;
+}
+export interface TickOutput {
+    /** Updated ctx — Server persists this against the session. */
+    ctx: Ctx;
+    /** Workflow state name after the tick — Server persists this against the session. */
+    state: string;
+    /** Whether the machine settled at a parked state. */
+    parked: boolean;
+    /** True when a state-timeout outcome matched no transition this tick — the host must NOT re-arm. */
+    stateTimeoutUnhandled: boolean;
+    /**
+     * Accumulated LLM call count and token usage for this tick.
+     * `cacheRead` / `cacheCreation` are populated by the Claude brain (its usage
+     * exposes cache traffic, which is the bulk of real cost — ZIG-759/813); the
+     * FSM path leaves them undefined. `total` includes cache tokens when present.
+     */
+    metrics: {
+        llmCalls: number;
+        tokens: {
+            total: number;
+            input: number;
+            output: number;
+            cacheRead?: number;
+            cacheCreation?: number;
+        };
+    };
+}
+/**
+ * Pure agent: workflow definition + cognition machinery. No I/O, no transport,
+ * no services. The Agent's only side channel is the `eff` handler it receives
+ * on each `tick`. Server-side state (sessions, lanes, queue, outbox) lives in
+ * `AgentHost` — not here.
+ *
+ * The contract:
+ *
+ *   `tick({ event, ctx, state, identity, eff })` →
+ *   `{ ctx, state, parked }`
+ *
+ * Reads top-to-bottom like a synchronous function. Every `await eff(...)`
+ * inside the cognition core is a yield to the Server, which performs the
+ * impure operation and resumes the Agent with the result.
+ */
+export declare class Agent {
+    workflow: Workflow;
+    toolManager: ToolManager;
+    promptBuilder: PromptBuilder;
+    constructor({ workflow, toolManager, promptBuilder }: AgentOptions);
+    tick({ event, ctx, state, identity, eff, memory, transitionTap }: TickInput): Promise<TickOutput>;
+}

package/dist/agent/Agent.js

@@ -0,0 +1,58 @@
+import { AgentMachine } from '../runtime/AgentMachine.js';
+import { runTurn } from '../runtime/runTurn.js';
+import { PromptBuilder } from '../runtime/PromptBuilder.js';
+/**
+ * Pure agent: workflow definition + cognition machinery. No I/O, no transport,
+ * no services. The Agent's only side channel is the `eff` handler it receives
+ * on each `tick`. Server-side state (sessions, lanes, queue, outbox) lives in
+ * `AgentHost` — not here.
+ *
+ * The contract:
+ *
+ *   `tick({ event, ctx, state, identity, eff })` →
+ *   `{ ctx, state, parked }`
+ *
+ * Reads top-to-bottom like a synchronous function. Every `await eff(...)`
+ * inside the cognition core is a yield to the Server, which performs the
+ * impure operation and resumes the Agent with the result.
+ */
+export class Agent {
+    workflow;
+    toolManager;
+    promptBuilder;
+    constructor({ workflow, toolManager, promptBuilder }) {
+        if (!workflow?.states)
+            throw new Error('Agent: workflow with states is required');
+        if (!toolManager)
+            throw new Error('Agent: toolManager is required');
+        this.workflow = workflow;
+        this.toolManager = toolManager;
+        this.promptBuilder = promptBuilder || new PromptBuilder();
+    }
+    async tick({ event, ctx, state, identity, eff, memory, transitionTap }) {
+        if (!identity?.sessionId)
+            throw new Error('Agent.tick: identity.sessionId is required');
+        if (!eff)
+            throw new Error('Agent.tick: eff is required');
+        const machine = new AgentMachine({
+            workflow: this.workflow,
+            executionCore: runTurn,
+            eff,
+            toolManager: this.toolManager,
+            promptBuilder: this.promptBuilder,
+            memory,
+            input: { identity, ctx, state },
+            transitionTap,
+        });
+        // `send` awaits the recursive _step until the machine settles at a
+        // parked state (or stops). When it returns, we have the final state.
+        await machine.send({ event: event, identity });
+        return {
+            ctx: machine.ctx,
+            state: machine.state,
+            parked: machine.isParked,
+            stateTimeoutUnhandled: machine.stateTimeoutUnhandled,
+            metrics: { llmCalls: machine.llmCalls, tokens: machine.tokens },
+        };
+    }
+}

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -0,0 +1,38 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import type { Workflow } from '../types.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type { TickInput, TickOutput } from './Agent.js';
+export type CognitionKind = 'fsm' | 'claude-sdk';
+export interface ClaudeSdkAgentOptions {
+    workflow: Workflow;
+    toolManager: ToolManager;
+    description: string;
+    specialization?: string | null;
+    model: string;
+    anthropicKey: string;
+    operatorKey: string;
+    agentId: string;
+    maxTurns?: number;
+    /** Injectable for tests. Defaults to @anthropic-ai/claude-agent-sdk query(). */
+    queryFn?: typeof query;
+}
+/**
+ * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`
+ * side channel, same tool surface as the FSM `Agent` — the ONLY difference is
+ * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
+ * `query()` (see ZIG-784: "host is the product; the brain is how it decides").
+ */
+export declare class ClaudeSdkAgent {
+    workflow: Workflow;
+    toolManager: ToolManager;
+    private description;
+    private specialization;
+    private model;
+    private anthropicKey;
+    private operatorKey;
+    private agentId;
+    private maxTurns;
+    private queryFn;
+    constructor(opts: ClaudeSdkAgentOptions);
+    tick({ event, ctx, state, identity, eff }: TickInput): Promise<TickOutput>;
+}

package/dist/agent/ClaudeSdkAgent.js

@@ -0,0 +1,322 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { outcomeFromEvent } from '../runtime/buildOutcome.js';
+import { bootstrapCtx } from '../runtime/bootstrapCtx.js';
+import { CLAUDE_SDK_PROTOCOL } from './claudeSdkProtocol.js';
+import { buildZiggsSdkMcpServer } from './toolManagerToSdkMcp.js';
+import { claudeQueryOptions, buildClaudeEventPrompt, summarizeContext, extractAssistantText, } from './claudeCognition.js';
+import { assertHostedAgentZiggsTools } from './hostedAgentConnection.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+const DEFAULT_STATE = 'ready';
+/**
+ * Per-task turn cap. A wake drives one `query()` that may loop up to this many
+ * internal turns; the tool schema + system prompt ride every turn, so this is
+ * the direct multiplier on a task's token spend. 30 let a confused MCP agent
+ * burn schema×30 per wake; brokered tasks (fetch → record → done) converge in a
+ * handful of turns, so 12 is ample. Env-overridable (raise for genuinely long
+ * agents). ZIG-759. */
+const DEFAULT_MAX_TURNS = Number(process.env.CLAUDE_SDK_MAX_TURNS ?? 12);
+/**
+ * Hard ceiling on billable input tokens (incl. cache read/write) a single wake
+ * may spend before we abort the query. Defense-in-depth on the shared fleet key
+ * against a runaway loop; set high enough that normal tasks never trip it. The
+ * task ends unfinished (and logs loudly) rather than burning unbounded. ZIG-759. */
+const MAX_TASK_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_INPUT_TOKENS ?? 500_000);
+/**
+ * Per-lane wake-rate circuit breaker. The per-wake caps above bound one wake;
+ * nothing bounded the NUMBER of wakes — the agent-private artifact echo drove
+ * one wake per wake, forever. The echo is fixed at the source (backend skips
+ * agent actors; host drops self-caused events), so this is a backstop for any
+ * future echo path: a lane waking faster than real traffic plausibly drives it
+ * skips the LLM (and logs loudly) instead of draining the fleet key. */
+const WAKE_WINDOW_MS = 10 * 60_000;
+const MAX_WAKES_PER_WINDOW = Number(process.env.CLAUDE_SDK_MAX_WAKES_PER_WINDOW ?? 40);
+/**
+ * Resumed-transcript ceiling (ZIG-816). Each wake resumes the lane's Claude
+ * session, so the whole transcript (event prompts, tool results, summaries)
+ * replays on every turn — mostly as cache reads, but it grows without bound on
+ * a long-lived lane and dominates per-wake cost. When a wake's billable input
+ * crosses this, we drop the session id so the NEXT wake starts fresh. The
+ * protocol is backend-authoritative (the brain re-reads via ziggs_context_snapshot),
+ * so the transcript is convenience memory, not the source of truth — safe to
+ * discard. Env-overridable. Kept below MAX_TASK_INPUT_TOKENS so a lane resets
+ * before it can approach the per-wake abort. */
+const MAX_SESSION_RESUME_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_SESSION_INPUT_TOKENS ?? 200_000);
+/** Total billable input for one API response (base + cache read + cache write). */
+function billableInput(usage) {
+    if (!usage)
+        return 0;
+    return ((usage.input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0));
+}
+/**
+ * Per-API-call usage. Only assistant turns carry it — the result message's
+ * usage is the CUMULATIVE total of the whole query, so adding it on top of
+ * the per-turn sums would double-count the wake.
+ */
+function usageOf(message) {
+    if (message.type === 'assistant') {
+        return message.message?.usage;
+    }
+    return undefined;
+}
+function extractMetrics(message) {
+    if (message.type !== 'result')
+        return null;
+    const usage = message.usage;
+    // Billable input includes cache reads/writes — that is what the Anthropic
+    // console counts and what the fleet key pays for. Reporting only the
+    // uncached slice made our telemetry read ~10-20x under the real usage.
+    const input = billableInput(usage);
+    const output = usage?.output_tokens ?? 0;
+    // Cache read/write are already folded into `input` above; surfaced separately
+    // here for per-tick visibility (metricsTap metadata / dashboards, ZIG-813).
+    const cacheRead = usage?.cache_read_input_tokens ?? 0;
+    const cacheCreation = usage?.cache_creation_input_tokens ?? 0;
+    return {
+        llmCalls: message.num_turns ?? 1,
+        // `input` is already the full billable input (base + cache); total = input + output.
+        tokens: { total: input + output, input, output, cacheRead, cacheCreation },
+    };
+}
+/**
+ * Resolve the agreement this wake acts under, for a delegated per-user MCP call
+ * (ZIG-831/832). Without it the gateway resolves the connection owner from
+ * `senderId` — which, under a delegation, is the delegating agent (who owns no
+ * connection) → a spurious NO_USER_CONNECTION even though the payer IS connected.
+ *
+ * The id must be found on ANY wake the worker might fetch on, not just
+ * `task_result` events. In practice the worker often fetches while reacting to
+ * the proposal-approved / agreement-active lifecycle events, which carry the id
+ * at the event top level rather than under `result`. Reading only
+ * `result.agreementId` (the original ZIG-831 wiring) left those wakes with no
+ * agreement → the false "authorize your connection" prompt. Resolve from every
+ * reliable source instead:
+ *   1. task_result events → `result.agreementId`
+ *   2. agreement-lifecycle events → top-level `agreementId`
+ *   3. task lanes → `sessionId` IS the agreement id
+ *   4. fallback → the single active agreement in context this agent provides
+ */
+function resolveOnBehalfAgreementId(rawEvent, contextSnap, agentId, sessionId) {
+    const str = (v) => typeof v === 'string' && v ? v : undefined;
+    const fromResult = str(rawEvent?.result?.agreementId);
+    if (fromResult)
+        return fromResult;
+    const fromEvent = str(rawEvent?.agreementId);
+    if (fromEvent)
+        return fromEvent;
+    if (typeof sessionId === 'string' && sessionId.startsWith('agr_'))
+        return sessionId;
+    // Fallback: exactly one active agreement in context where this agent is the
+    // provider. Guarded to a single match so we never send the wrong agreement.
+    const ags = Array.isArray(contextSnap?.agreements)
+        ? contextSnap.agreements
+        : [];
+    const provides = ags.filter((a) => {
+        const p = a?.parties ?? a;
+        const providerIds = [p?.provider, p?.providerAgent, a?.providerId, a?.providerAgentId, a?.executorId];
+        const isProvider = providerIds.some((x) => x === agentId);
+        const status = a?.status != null ? String(a.status).toLowerCase() : '';
+        const active = !status || status === 'active' || status === 'approved';
+        return isProvider && active;
+    });
+    if (provides.length === 1) {
+        return str(provides[0].agreementId) ?? str(provides[0].id) ?? str(provides[0]._id);
+    }
+    return undefined;
+}
+/**
+ * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`
+ * side channel, same tool surface as the FSM `Agent` — the ONLY difference is
+ * the loop: instead of the FSM + `runTurn`, a wake drives a headless Claude
+ * `query()` (see ZIG-784: "host is the product; the brain is how it decides").
+ */
+export class ClaudeSdkAgent {
+    workflow;
+    toolManager;
+    description;
+    specialization;
+    model;
+    anthropicKey;
+    operatorKey;
+    agentId;
+    maxTurns;
+    queryFn;
+    constructor(opts) {
+        if (!opts.workflow?.states)
+            throw new Error('ClaudeSdkAgent: workflow with states is required');
+        if (!opts.toolManager)
+            throw new Error('ClaudeSdkAgent: toolManager is required');
+        if (!opts.anthropicKey)
+            throw new Error('ClaudeSdkAgent: anthropicKey is required');
+        this.workflow = opts.workflow;
+        this.toolManager = opts.toolManager;
+        this.description = opts.description;
+        this.specialization = opts.specialization ?? null;
+        this.model = opts.model;
+        this.anthropicKey = opts.anthropicKey;
+        this.operatorKey = opts.operatorKey;
+        this.agentId = opts.agentId;
+        this.maxTurns = opts.maxTurns ?? DEFAULT_MAX_TURNS;
+        this.queryFn = opts.queryFn ?? query;
+    }
+    async tick({ event, ctx, state, identity, eff }) {
+        if (!identity?.sessionId)
+            throw new Error('ClaudeSdkAgent.tick: identity.sessionId is required');
+        if (!eff)
+            throw new Error('ClaudeSdkAgent.tick: eff is required');
+        const rawEvent = event;
+        const nextCtx = bootstrapCtx(identity, ctx);
+        nextCtx.lastOutcome = outcomeFromEvent(rawEvent ?? null, identity.agentId);
+        const now = Date.now();
+        const recentWakes = (nextCtx.recentWakes ?? []).filter((t) => now - t < WAKE_WINDOW_MS);
+        if (recentWakes.length >= MAX_WAKES_PER_WINDOW) {
+            runtimeLog.warn('ClaudeSdkAgent', `wake-rate breaker tripped: ${recentWakes.length} wakes in ${WAKE_WINDOW_MS / 60_000}min ` +
+                `session=${identity.sessionId} agent=${this.agentId} — skipping LLM for this wake`);
+            nextCtx.recentWakes = recentWakes;
+            return {
+                ctx: nextCtx,
+                state: state ?? DEFAULT_STATE,
+                parked: true,
+                stateTimeoutUnhandled: false,
+                metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
+            };
+        }
+        nextCtx.recentWakes = [...recentWakes, now];
+        let contextSnap = null;
+        try {
+            contextSnap = await eff({
+                kind: 'read-context',
+                sessionId: identity.sessionId,
+            });
+        }
+        catch (err) {
+            runtimeLog.warn('ClaudeSdkAgent', `read-context failed session=${identity.sessionId}: ${err.message}`);
+        }
+        // Same guard as the FSM's runTurn: a message wake for a chat the backend
+        // no longer resolves (deleted / not visible) has no world to act in —
+        // skip the query instead of burning a wake on a fabricated empty history.
+        // Task lanes (sessionId = agreementId) also trip chatMissing and must run.
+        if (contextSnap?.chatMissing === true && nextCtx.lastOutcome?.kind === 'message-received') {
+            runtimeLog.warn('ClaudeSdkAgent', `chat ${identity.sessionId} not found on backend — skipping message wake agent=${this.agentId}`);
+            return {
+                ctx: nextCtx,
+                state: state ?? DEFAULT_STATE,
+                parked: true,
+                stateTimeoutUnhandled: false,
+                metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
+            };
+        }
+        const roleBlock = [
+            `## Your role`,
+            this.description,
+            this.specialization ? `Specialization: ${this.specialization}` : '',
+        ].filter(Boolean).join('\n');
+        const systemPrompt = `${CLAUDE_SDK_PROTOCOL}\n\n${roleBlock}`;
+        const runId = crypto.randomUUID();
+        const toolContext = {
+            operatorKey: this.operatorKey,
+            agentId: this.agentId,
+            chatId: identity.sessionId,
+            sessionId: identity.sessionId,
+            eff,
+            senderId: rawEvent?.senderId != null ? String(rawEvent.senderId) : undefined,
+            senderType: rawEvent?.senderType != null ? String(rawEvent.senderType) : undefined,
+            // ZIG-831/832: agreement this wake acts under → lets a delegated per-user
+            // MCP call resolve the originating end-user (payer) rather than the
+            // delegating agent (senderId). Resolved from every reliable wire source,
+            // not just task_result events — see resolveOnBehalfAgreementId.
+            onBehalfOfAgreementId: resolveOnBehalfAgreementId(rawEvent, contextSnap, this.agentId, identity.sessionId),
+            runId,
+        };
+        const availableTools = await this.toolManager.getAvailableTools();
+        const mcpServer = buildZiggsSdkMcpServer(availableTools, () => toolContext, {
+            name: 'ziggs',
+            instructions: 'In-process Ziggs tools backed by api-client. No external MCP process.',
+        });
+        const prompt = buildClaudeEventPrompt(rawEvent, summarizeContext(contextSnap));
+        const mcpServers = { ziggs: mcpServer };
+        assertHostedAgentZiggsTools(mcpServers);
+        const queryOptions = claudeQueryOptions({
+            systemPrompt,
+            model: this.model,
+            mcpServers,
+            maxTurns: this.maxTurns,
+            apiKey: this.anthropicKey,
+            stderr: (data) => {
+                const line = data.trim();
+                if (line)
+                    runtimeLog.warn('ClaudeSdkAgent', `stderr session=${identity.sessionId}: ${line}`);
+            },
+            resume: nextCtx.claudeSessionId,
+        });
+        let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
+        let sessionId = nextCtx.claudeSessionId;
+        let spentInput = 0;
+        try {
+            for await (const message of this.queryFn({ prompt, options: queryOptions })) {
+                if ('session_id' in message && typeof message.session_id === 'string') {
+                    sessionId = message.session_id;
+                }
+                // Surface the model's own prose so a hired Claude agent is as legible as
+                // an FSM agent (ZIG-787). Each completed assistant turn's text is recorded
+                // as a `thought` — the SAME agent-private channel the FSM uses for its
+                // reasoning (runTurn `emitThought` → record-event → recordThought), so it
+                // shows in the hired-agent view without cluttering the counterparty chat.
+                // Pure tool-use turns carry no text and record nothing.
+                //
+                // Fire-and-forget on purpose: this runs inside `for await (query())`, so
+                // awaiting an artifacts round-trip per turn would couple model-stream
+                // consumption to the artifacts backend — a slow/wedged backend would stall
+                // the whole wake, not just fail a breadcrumb. Recording is best-effort and
+                // thought ordering is not load-bearing, so we let it run in the background
+                // and swallow failures with a warn.
+                if (message.type === 'assistant') {
+                    const text = extractAssistantText(message).trim();
+                    if (text) {
+                        void eff({ kind: 'record-event', sessionId: identity.sessionId, entry: { kind: 'thought', text } })
+                            .catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record thought failed session=${identity.sessionId}: ${err.message}`));
+                    }
+                }
+                const m = extractMetrics(message);
+                if (m)
+                    metrics = m;
+                if (message.type === 'result' && message.subtype !== 'success') {
+                    runtimeLog.warn('ClaudeSdkAgent', `query ended without success subtype=${message.subtype} session=${identity.sessionId}`);
+                }
+                // Runaway guard (ZIG-759): abort before an unbounded loop drains the
+                // shared fleet key. Breaking the for-await calls the generator's return(),
+                // which terminates the underlying query.
+                spentInput += billableInput(usageOf(message));
+                if (spentInput > MAX_TASK_INPUT_TOKENS) {
+                    runtimeLog.warn('ClaudeSdkAgent', `input-token budget exceeded (~${spentInput} > ${MAX_TASK_INPUT_TOKENS}) session=${identity.sessionId} agent=${this.agentId} — aborting query to cap spend (ZIG-759)`);
+                    break;
+                }
+            }
+        }
+        catch (err) {
+            runtimeLog.warn('ClaudeSdkAgent', `query failed session=${identity.sessionId}: ${err.message}`);
+            throw err;
+        }
+        if (sessionId)
+            nextCtx.claudeSessionId = sessionId;
+        // ZIG-816: bound resumed-transcript growth. `metrics.tokens.input` is the
+        // wake's billable input off the result message (dominated by the resumed
+        // transcript's cache reads); `spentInput` covers an aborted wake that never
+        // produced a result. Past the ceiling, forget the session so the next wake
+        // starts fresh rather than paying an ever-larger replay.
+        const wakeInput = Math.max(metrics.tokens.input, spentInput);
+        if (nextCtx.claudeSessionId && wakeInput > MAX_SESSION_RESUME_INPUT_TOKENS) {
+            runtimeLog.info('ClaudeSdkAgent', `resetting Claude session (wake input ~${wakeInput} > ${MAX_SESSION_RESUME_INPUT_TOKENS}) ` +
+                `session=${identity.sessionId} agent=${this.agentId} — next wake starts fresh (ZIG-816)`);
+            nextCtx.claudeSessionId = undefined;
+        }
+        return {
+            ctx: nextCtx,
+            state: state ?? DEFAULT_STATE,
+            parked: true,
+            stateTimeoutUnhandled: false,
+            metrics,
+        };
+    }
+}

package/dist/agent/claudeCognition.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared Claude-Agent-SDK cognition pieces.
+ *
+ * Everything a Claude-brain agent needs to turn a Ziggs wake into a `query()`
+ * call, EXCEPT the loop itself. `ClaudeSdkAgent` owns the loop (drive `query()`,
+ * collect metrics); this module owns the periphery so it lives in one place and
+ * is unit-testable without spinning up the SDK.
+ *
+ * The lockdown option set (`tools: []`, `strictMcpConfig`, `settingSources: []`,
+ * bypass permissions, no local settings) is a security boundary, not a default —
+ * it MUST be applied on every Claude-brain wake. Centralizing it here means a
+ * caller cannot silently drift from it.
+ */
+import type { Options, SDKAssistantMessage } from '@anthropic-ai/claude-agent-sdk';
+import type { RawEvent } from '../runtime/buildOutcome.js';
+export interface ClaudeQueryOptionsParams {
+    /** Protocol + role system prompt. */
+    systemPrompt: string;
+    /** Claude model id for the brain. */
+    model: string;
+    /** In-process MCP servers exposing the agent's tools (e.g. `{ ziggs }`). */
+    mcpServers: NonNullable<Options['mcpServers']>;
+    /** Max agentic turns per wake. */
+    maxTurns: number;
+    /** Working dir for the query subprocess. Defaults to `$CLAUDE_SDK_CWD` or `/tmp`. */
+    cwd?: string;
+    /** stderr sink for the query subprocess. */
+    stderr?: (data: string) => void;
+    /** Claude session id to resume across ticks. Omitted → a fresh session. */
+    resume?: string;
+    /**
+     * Anthropic API key for this wake. Passed to the query subprocess via the
+     * `env` option (which inherits `process.env` and overrides the key) rather
+     * than mutating the parent process's global `process.env` — so agents with
+     * different keys can share one process safely.
+     */
+    apiKey?: string;
+}
+/**
+ * Pick the Claude model for a Claude-brain wake. The brain must run a `claude-*`
+ * model, but the host's default model is provider-agnostic (an OpenAI id today),
+ * so this prefers an explicit `claude-*` id (direct or via `services.llm`) and
+ * otherwise falls back to a safe Claude default — never an OpenAI id.
+ */
+export declare function resolveClaudeModel(preferred?: string, servicesModel?: string): string;
+/**
+ * Build the `query()` options for a Claude-brain wake. The lockdown fields are
+ * fixed here; callers only supply the per-wake variables (prompt, model, tools,
+ * turn budget, resume). Returns `Options` so it drops straight into `query()`.
+ */
+export declare function claudeQueryOptions(params: ClaudeQueryOptionsParams): Options;
+/**
+ * Concatenate the text blocks of a completed Claude assistant turn. Tool-use,
+ * thinking, and other block kinds are skipped — only the model's user-facing
+ * prose is returned (empty string for a pure tool-use turn). This is what a
+ * Claude-brain wake records as a `thought` per turn (ZIG-787), the same way
+ * the FSM's `emitThought` surfaces the model's reasoning.
+ */
+export declare function extractAssistantText(message: SDKAssistantMessage): string;
+/** One-line digest of a context snapshot for the wake prompt. */
+export declare function summarizeContext(snap: Record<string, unknown> | null | undefined): string;
+/**
+ * Turn a Ziggs wake event + context digest into the user prompt that starts a
+ * Claude-brain turn. The agent's standing instructions come from its system
+ * prompt (protocol + role); this is just "here's what woke you, go handle it."
+ */
+export declare function buildClaudeEventPrompt(event: RawEvent | undefined, contextSummary: string): string;

package/dist/agent/claudeCognition.js

@@ -0,0 +1,103 @@
+const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-6';
+/**
+ * Pick the Claude model for a Claude-brain wake. The brain must run a `claude-*`
+ * model, but the host's default model is provider-agnostic (an OpenAI id today),
+ * so this prefers an explicit `claude-*` id (direct or via `services.llm`) and
+ * otherwise falls back to a safe Claude default — never an OpenAI id.
+ */
+export function resolveClaudeModel(preferred, servicesModel) {
+    if (preferred?.startsWith('claude'))
+        return preferred;
+    if (servicesModel?.startsWith('claude'))
+        return servicesModel;
+    return DEFAULT_CLAUDE_MODEL;
+}
+/**
+ * Build the `query()` options for a Claude-brain wake. The lockdown fields are
+ * fixed here; callers only supply the per-wake variables (prompt, model, tools,
+ * turn budget, resume). Returns `Options` so it drops straight into `query()`.
+ */
+export function claudeQueryOptions(params) {
+    return {
+        systemPrompt: params.systemPrompt,
+        model: params.model,
+        mcpServers: params.mcpServers,
+        // The agent's ONLY capabilities are its MCP tools — no built-in file/bash/web
+        // tools, no project/user/plugin MCP config, no local settings / CLAUDE.md.
+        tools: [],
+        strictMcpConfig: true,
+        settingSources: [],
+        permissionMode: 'bypassPermissions',
+        allowDangerouslySkipPermissions: true,
+        maxTurns: params.maxTurns,
+        cwd: params.cwd ?? process.env.CLAUDE_SDK_CWD ?? '/tmp',
+        // Set the key for the subprocess without touching the parent process.env.
+        // `env` replaces the subprocess environment, so spread process.env to keep
+        // PATH/HOME/etc. and override only the key.
+        ...(params.apiKey ? { env: { ...process.env, ANTHROPIC_API_KEY: params.apiKey } } : {}),
+        ...(params.stderr ? { stderr: params.stderr } : {}),
+        ...(params.resume ? { resume: params.resume } : {}),
+    };
+}
+/**
+ * Concatenate the text blocks of a completed Claude assistant turn. Tool-use,
+ * thinking, and other block kinds are skipped — only the model's user-facing
+ * prose is returned (empty string for a pure tool-use turn). This is what a
+ * Claude-brain wake records as a `thought` per turn (ZIG-787), the same way
+ * the FSM's `emitThought` surfaces the model's reasoning.
+ */
+export function extractAssistantText(message) {
+    const content = message.message?.content;
+    if (!Array.isArray(content))
+        return '';
+    let out = '';
+    for (const block of content) {
+        if (block && block.type === 'text') {
+            out += block.text ?? '';
+        }
+    }
+    return out;
+}
+/** One-line digest of a context snapshot for the wake prompt. */
+export function summarizeContext(snap) {
+    if (!snap)
+        return '';
+    const agreements = Array.isArray(snap.agreements) ? snap.agreements.length : 0;
+    const history = Array.isArray(snap.history) ? snap.history.length : 0;
+    const users = Array.isArray(snap.users) ? snap.users.length : 0;
+    return `history=${history} messages, agreements=${agreements}, users=${users}`;
+}
+/**
+ * Turn a Ziggs wake event + context digest into the user prompt that starts a
+ * Claude-brain turn. The agent's standing instructions come from its system
+ * prompt (protocol + role); this is just "here's what woke you, go handle it."
+ */
+export function buildClaudeEventPrompt(event, contextSummary) {
+    const lines = ['You received a new Ziggs event. Handle it per your protocol.'];
+    if (event?.type)
+        lines.push(`Event type: ${event.type}`);
+    if (event?.text)
+        lines.push(`Message: ${event.text}`);
+    if (event?.senderId)
+        lines.push(`Sender: ${event.senderId}`);
+    if (event?.operation)
+        lines.push(`Operation: ${event.operation}`);
+    // ZIG-832: surface the task/agreement this event carries. Without it the brain
+    // can't tell WHICH task to update/complete (workers otherwise stall asking for
+    // their own taskId) and can't see whether the referenced step already ran or
+    // failed — which makes an orchestrator re-spawn duplicate delegations.
+    const result = event?.result;
+    if (result && typeof result === 'object') {
+        if (typeof result.taskId === 'string')
+            lines.push(`Task: ${result.taskId}`);
+        if (typeof result.agreementId === 'string')
+            lines.push(`Agreement: ${result.agreementId}`);
+        if (typeof result.state === 'string')
+            lines.push(`Task state: ${result.state}`);
+    }
+    if (contextSummary) {
+        lines.push('', 'Session context snapshot:', contextSummary);
+    }
+    lines.push('', 'Use ziggs_context_snapshot if you need more context. If the event needs nothing from you, say so briefly and stop.');
+    return lines.join('\n');
+}