@ziggs-ai/agent-sdk 0.1.11 → 0.1.12

package/package.json

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

package/src/AgentHost.ts

@@ -1,5 +1,10 @@
 import type { AgentConfig, Ctx, EffectHandler, Identity, Workflow } from './types.js';
 import { Agent } from './agent/Agent.js';
+import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
+import { CLAUDE_SDK_TOOLS } from './agent/claudeSdkTools.js';
+import { resolveClaudeModel } from './agent/claudeCognition.js';
+
+export type { CognitionKind };
 import { EventQueue } from './server/EventQueue.js';
 import { StateTimers } from './server/StateTimers.js';
 import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
@@ -25,10 +30,10 @@ import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import {
   WebSocketClient,
-  MessagesClient,
   ArtifactsClient,
-  ScopeClient,
+  ContextReadClient,
   TelemetryClient,
+  InboxClient,
   type MessageMetadata,
 } from '@ziggs-ai/api-client';
 import { TaskService } from './server/tasks/TaskService.js';
@@ -37,6 +42,15 @@ import { runInboxCatchUp } from './server/InboxCatchUp.js';
 import { SeenMessages } from './server/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 
+/**
+ * The single fleet-wide default model — the one place the fallback lives.
+ * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
+ * model anywhere else. The id also picks the provider: a `claude-*` value routes
+ * to AnthropicAdapter (+ ANTHROPIC_API_KEY), anything else to OpenAIAdapter — see
+ * the `model?.startsWith('claude')` branch in createBackendServices below.
+ */
+export const DEFAULT_MODEL = 'claude-haiku-4-5';
+
 // ConnectionPool lives in a separate module; resolved via a computed-path
 // dynamic import to avoid a circular import with AgentHost.
 async function loadConnectionPool(): Promise<new (opts?: { maxActive?: number; idleTimeoutMs?: number }) => unknown> {
@@ -65,6 +79,7 @@ interface AgentServices {
   [key: string]: unknown;
 }
 
+
 export interface AgentHostOptions {
   openaiKey?: string;
   anthropicKey?: string;
@@ -77,6 +92,10 @@ export interface AgentHostOptions {
   specialization?: string | null;
   tools?: ToolDefinition[];
   taskTools?: 'all' | 'none' | string[];
+  /** Cognition runtime: FSM (default) or Claude Agent SDK headless delegate. */
+  cognition?: CognitionKind;
+  /** Max agentic turns per Claude SDK wake. Default 30. */
+  claudeMaxTurns?: number;
   services?: AgentServices;
   workflow?: Workflow;
   // Convenience: states + initial without an explicit workflow.
@@ -101,6 +120,21 @@ export interface AgentHostOptions {
   effectTap?: (effect: import('./types.js').Effect, response: unknown) => void;
   /** Observability tap: called on every FSM state transition, no-match, depth-guard, or error-escape (ZIG-442). */
   transitionTap?: (event: import('./runtime/AgentMachine.js').TransitionEvent) => void;
+  /**
+   * Usage/cost tap: called once per settled tick with the tick's authoritative
+   * token usage (result.metrics). This is the SINGLE source of truth for
+   * usage/cost across every cognition — the FSM (llm-call + streamed reply +
+   * tool-internal LLM) and the Claude brain (incl. cache tokens) both funnel
+   * their spend here (ZIG-813). effectTap / tool generations are structural
+   * tracing only and must NOT also carry billable usage, or cost double-counts.
+   */
+  metricsTap?: (info: {
+    agentId: string;
+    sessionId: string;
+    model: string;
+    cognition: string;
+    metrics: import('./agent/Agent.js').TickOutput['metrics'];
+  }) => void;
   /** Production monitoring ingest (ZIG-360). Default on; set false to disable. */
   telemetryIngest?: boolean;
   /**
@@ -117,7 +151,8 @@ function createToolManager(options: AgentHostOptions): ToolManager {
   if (options.taskTools === 'none') taskTools = [];
   else if (Array.isArray(options.taskTools)) taskTools = PROTOCOL_TOOLS.filter((t: ToolDefinition) => (options.taskTools as string[]).includes(t.schema.function.name as string));
   else taskTools = PROTOCOL_TOOLS; // 'all' or undefined
-  toolManager.registerAll([...taskTools, ...(Array.isArray(userTools) ? userTools : [])]);
+  const claudeSdkTools = options.cognition === 'claude-sdk' ? CLAUDE_SDK_TOOLS : [];
+  toolManager.registerAll([...taskTools, ...claudeSdkTools, ...(Array.isArray(userTools) ? userTools : [])]);
   return toolManager;
 }
 
@@ -128,16 +163,22 @@ 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
-    : model?.startsWith('claude')
-      ? new AnthropicAdapter({ key: options.anthropicKey, model })
-      : new OpenAIAdapter({ key: options.openaiKey, model });
+  // The Claude brain drives query() directly and never emits llm-call/stream-text
+  // effects, so it needs no adapter. Building one here would be dead — and worse,
+  // the provider client throws at construction on a missing key, so a claude-sdk
+  // agent left on the default (OpenAI) model with no openaiKey would fail to
+  // start over an adapter it never uses. Skip it.
+  const llm = options.cognition === 'claude-sdk'
+    ? undefined
+    : isLlmAdapter(options.services?.llm)
+      ? options.services!.llm as LlmAdapter
+      : 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);
   const artifactsClient = new ArtifactsClient(operatorKey, agentId);
-  const scopeClient = new ScopeClient(operatorKey, agentId);
+  const contextReadClient = new ContextReadClient(operatorKey, agentId);
   const promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
   const taskService = new TaskService(operatorKey, agentId);
   const agreementService = new AgreementService(operatorKey, agentId);
@@ -145,9 +186,8 @@ function createBackendServices(options: AgentHostOptions) {
   return {
     toolManager,
     llm,
-    messagesClient,
     artifactsClient,
-    scopeClient,
+    contextReadClient,
     promptBuilder,
     taskService,
     agreementService,
@@ -172,8 +212,10 @@ interface LaneSession {
 export class AgentHost {
   options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
   toolManager!: ToolManager;
-  llm!: OpenAIAdapter | LlmAdapter;  // retained for external inspection
-  agent!: Agent;
+  // Retained for external inspection. Undefined for the Claude brain, which
+  // drives query() directly and needs no LLM adapter.
+  llm?: OpenAIAdapter | LlmAdapter;
+  agent!: Agent | ClaudeSdkAgent;
   wsClient!: WebSocketClient;
   private eff!: EffectHandler;
   private eventQueue!: EventQueue;
@@ -186,6 +228,8 @@ export class AgentHost {
   private agreementService!: AgreementService;
   private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
   private seenMessages = new SeenMessages();
+  /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
+  private _inbox?: InboxClient;
   private stateTimers!: StateTimers;
   private catchUpInFlight: Promise<void> | null = null;
   private inboxCatchUpEnabled: boolean;
@@ -194,7 +238,7 @@ export class AgentHost {
     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',
+      model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || DEFAULT_MODEL,
       operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
       agentId: options.agentId || '',
       name: options.name || null,
@@ -211,7 +255,10 @@ export class AgentHost {
       sessionResolver: options.sessionResolver,
       effectTap: options.effectTap,
       transitionTap: options.transitionTap,
+      metricsTap: options.metricsTap,
       inboxCatchUp: options.inboxCatchUp,
+      cognition: options.cognition ?? 'fsm',
+      claudeMaxTurns: options.claudeMaxTurns,
     } as Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
     this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
     this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
@@ -223,7 +270,11 @@ export class AgentHost {
   }
 
   private _validate(): void {
-    if (!isLlmAdapter(this.options.services?.llm)) {
+    if (this.options.cognition === 'claude-sdk') {
+      if (!this.options.anthropicKey) {
+        throw new Error('anthropicKey is required for claude-sdk cognition — pass { anthropicKey } or set ANTHROPIC_API_KEY');
+      }
+    } else 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) {
@@ -266,13 +317,26 @@ export class AgentHost {
         states: this.options.states,
       };
     }
-    if (!workflow?.states) throw new Error('AgentHost: workflow (or states + initial) is required');
+    if (!workflow?.states) {
+      // The Claude brain has no FSM — it drives query() per wake and parks. It
+      // still plugs into the host's lane/timer machinery via a trivial parked
+      // workflow, synthesized here so callers don't hand-write a dummy one.
+      if (this.options.cognition === 'claude-sdk') {
+        workflow = {
+          id: this.options.agentId,
+          description: this.options.description!,
+          initial: 'ready',
+          states: { ready: { kind: 'parked', transitions: [] } },
+        };
+      } else {
+        throw new Error('AgentHost: workflow (or states + initial) is required');
+      }
+    }
 
     this.eff = createZiggsEffectHandler({
       llm: services.llm as unknown as import('./server/ZiggsEffectHandler.js').ZiggsEffectDeps['llm'],
-      messagesClient: services.messagesClient,
       artifactsClient: services.artifactsClient,
-      scopeClient: services.scopeClient,
+      contextReadClient: services.contextReadClient,
       taskService: services.taskService,
       agreementService: services.agreementService,
       messageSender,
@@ -285,11 +349,29 @@ export class AgentHost {
       effectTap: this.options.effectTap,
     });
 
-    this.agent = new Agent({
-      workflow,
-      toolManager: services.toolManager,
-      promptBuilder: services.promptBuilder,
-    });
+    this.agent = this.options.cognition === 'claude-sdk'
+      ? new ClaudeSdkAgent({
+          workflow,
+          toolManager: services.toolManager,
+          description: this.options.description!,
+          specialization: this.options.specialization,
+          model: resolveClaudeModel(
+            this.options.model,
+            (this.options.services?.llm as { model?: string } | undefined)?.model,
+          ),
+          anthropicKey: this.options.anthropicKey!,
+          operatorKey: this.options.operatorKey!,
+          agentId: this.options.agentId!,
+          // No taskService/agreementService: Claude-brain tools execute through
+          // eff({ kind: 'tool-call' }) → the shared executor, which sources those
+          // services from the effect handler's deps like the FSM path (ZIG-775).
+          maxTurns: this.options.claudeMaxTurns,
+        })
+      : new Agent({
+          workflow,
+          toolManager: services.toolManager,
+          promptBuilder: services.promptBuilder,
+        });
 
     this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, laneKey));
     this.stateTimers = new StateTimers((ev, laneKey) => { void this.eventQueue.enqueue(ev, laneKey); });
@@ -354,6 +436,33 @@ export class AgentHost {
     const ownAgentId = this.options.agentId;
     if (!ownAgentId) return;
 
+    // The agent's own writes aren't news to it (same rule the backend inbox
+    // applies to counts). The backend already skips agent actors on emit;
+    // this guards the same invariant host-side so a self-caused event can
+    // never re-wake the brain — that echo was a token-burning wake loop for
+    // LLM cognitions (one wake's tool calls seeded the next wake, forever).
+    if (event.actorId != null && String(event.actorId) === ownAgentId) {
+      runtimeLog.debug('AgentHost', `skip self-caused resource event kind=${event.kind ?? 'unknown'} resourceId=${event.resourceId ?? 'null'}`);
+      return;
+    }
+
+    // A `message` resource event is the second channel for news the message
+    // push already delivered — the backend emits BOTH a `chat:message` frame
+    // and a `resource_changed {kind:'message', resourceId: messageId}` for
+    // every send. The resource frame exists for offline recovery (queue +
+    // launcher wake); when we already processed that messageId live via
+    // handleMessage, waking again just re-runs the brain over handled news
+    // (every inbound chat message cost a second wake). Unseen ids still wake:
+    // that's the recovery path working.
+    if (
+      event.kind === 'message' &&
+      typeof event.resourceId === 'string' &&
+      this.seenMessages.has(event.resourceId)
+    ) {
+      runtimeLog.debug('AgentHost', `skip resource event for already-handled message ${event.resourceId}`);
+      return;
+    }
+
     // Map the event to a candidate session key using the configured resolver
     // on a synthetic normalized-event shape. Default resolver buckets by
     // chatId; agents using a different sessionResolver (agreementId, taskId,
@@ -416,7 +525,37 @@ export class AgentHost {
     if (!this.sessions.has(laneKey)) {
       this.sessions.set(laneKey, { sessionId, ownAgentId });
     }
-    return this.eventQueue.enqueue(normalized.event, laneKey);
+    const enqueued = this.eventQueue.enqueue(normalized.event, laneKey);
+    // ZIG-832 P4: advance this chat's inbox watermark for a message handled on
+    // the LIVE push path. Without it, only catch-up acks — so on a re-host the
+    // server watermark still sits before this message and catch-up re-delivers
+    // it, re-running a finished pipeline (the cross-wake token burn). Mirrors
+    // catch-up's ack-on-delivery; newer messages carry a later ts and still
+    // deliver, so a genuinely new turn in the same chat is not lost. Best-effort:
+    // never block or fail the wake.
+    const msgTs = (metadata.createdAt ?? metadata.timestamp ?? metadata.sentTimestamp) as string | undefined;
+    if (normalized.chatId && typeof msgTs === 'string' && msgTs) {
+      void this._ackChatWatermark(normalized.chatId, msgTs);
+    } else if (normalized.chatId) {
+      // ZIG-860: this ack silently not firing is exactly how the re-delivery
+      // bug hid — a live message with no usable timestamp must be loud.
+      runtimeLog.warn('AgentHost', `live-ack skipped: no timestamp on message chatId=${normalized.chatId} messageId=${messageId ?? 'null'}`);
+    }
+    return enqueued;
+  }
+
+  /** Best-effort: advance the inbox watermark for a chat handled live (ZIG-832 P4). */
+  private async _ackChatWatermark(chatId: string, upTo: string): Promise<void> {
+    try {
+      if (!this._inbox) {
+        this._inbox = new InboxClient(this.options.operatorKey!, this.options.agentId!);
+      }
+      await this._inbox.ack([{ kind: 'chat', id: chatId, upTo }]);
+    } catch (e: unknown) {
+      // warn, not debug (ZIG-860): a failing live-ack means catch-up will
+      // re-deliver this chat's backlog after the next host eviction.
+      runtimeLog.warn('AgentHost', `live-ack chat ${chatId} failed: ${(e as Error)?.message ?? e}`);
+    }
   }
 
   private async _processEvent(event: unknown, laneKey: string): Promise<void> {
@@ -452,17 +591,52 @@ export class AgentHost {
       laneKey,
     };
 
+    // The watchdog timer must be cleared once the tick settles — leaving it
+    // armed pinned one live 2-minute timer per tick (and kept short-lived
+    // processes/tests alive until it fired).
+    let tickWatchdog: ReturnType<typeof setTimeout> | undefined;
     try {
       const result = await Promise.race([
         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),
-        ),
+        new Promise<never>((_, reject) => {
+          tickWatchdog = setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs);
+        }),
       ]);
       session.ctx = result.ctx;
       session.state = result.state;
       this.sessions.set(laneKey, session);
 
+      // One line per wake that actually spent LLM budget — the handle for
+      // tracking a hosted agent live (grep `agent=<id>`). Parked no-op ticks
+      // (FSM exits, wake-rate-skipped Claude wakes) report zero tokens and
+      // stay quiet. A regressed self-wake loop shows here as a rapid stream of
+      // these lines for one lane. Tokens are billable input (incl. cache).
+      const m = result.metrics;
+      if (m && (m.tokens?.total ?? 0) > 0) {
+        runtimeLog.info(
+          'AgentHost',
+          `wake agent=${identity.agentId} lane=${laneKey} llmCalls=${m.llmCalls} ` +
+            `tokens_in=${m.tokens.input} tokens_out=${m.tokens.output} total=${m.tokens.total}`,
+        );
+      }
+
+      // Single source of truth for usage/cost (ZIG-813): emit the tick's
+      // authoritative token metrics once, for every cognition. Never let an
+      // observability failure break the tick.
+      if (this.options.metricsTap && result.metrics) {
+        try {
+          this.options.metricsTap({
+            agentId: identity.agentId,
+            sessionId: session.sessionId,
+            model: this.options.model ?? 'unknown',
+            cognition: this.options.cognition ?? 'fsm',
+            metrics: result.metrics,
+          });
+        } catch (err: unknown) {
+          runtimeLog.warn('AgentHost', `metricsTap failed: ${(err as Error)?.message || err}`);
+        }
+      }
+
       if (this.sessionStore) {
         this.sessionStore.save(laneKey, { ctx: session.ctx, state: session.state }).catch((err: unknown) => {
           runtimeLog.warn('AgentHost', `sessionStore.save failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
@@ -488,6 +662,8 @@ export class AgentHost {
       if (senderId && senderType === 'USER') {
         this.eff({ kind: 'send-message', sessionId: session.sessionId, receiverId: senderId, text: 'Something went wrong. Please try again.' }).catch(() => {});
       }
+    } finally {
+      clearTimeout(tickWatchdog);
     }
   }
 
@@ -514,9 +690,102 @@ export class AgentHost {
       await new Promise((r) => setTimeout(r, 750));
       this.catchUpInFlight = null;
       await this._ensureCatchUp();
+      await this._bootstrapAssignedActiveTasks();
     }
     return this;
   }
+  private async _bootstrapAssignedActiveTasks(): Promise<void> {
+    const agentId = this.options.agentId;
+    if (!agentId || !this.taskService) return;
+
+    let tasks: Array<{ taskId?: string; assigneeId?: string | null }> = [];
+    try {
+      tasks = await this.taskService.getActiveTasksForAgent(agentId);
+    } catch (err: unknown) {
+      runtimeLog.warn(
+        this.options.name || 'agent',
+        `active-task bootstrap skipped: ${(err as Error)?.message ?? err}`,
+      );
+      return;
+    }
+
+    for (const row of tasks) {
+      const taskId = row.taskId;
+      if (!taskId) continue;
+      if (row.assigneeId && row.assigneeId !== agentId) continue;
+
+      let full: Record<string, unknown>;
+      try {
+        full = (await this.taskService.getTask(taskId)) as unknown as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      const state = String(full.state ?? '');
+      if (state !== 'active' && state !== 'in-progress') continue;
+
+      const sessionId =
+        (full.agreementId as string | undefined) ||
+        (full.originChatId as string | undefined) ||
+        'default';
+      const laneKey = `${agentId}:${sessionId}`;
+      if (!this.sessions.has(laneKey)) {
+        this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
+      }
+
+      runtimeLog.info(
+        this.options.name || 'agent',
+        `bootstrap task-assigned ${taskId} (state=${state})`,
+      );
+      await this.eventQueue.enqueue(
+        {
+          type: 'task_result',
+          result: {
+            ...full,
+            taskId: (full.taskId as string | undefined) ?? taskId,
+            state,
+            providerIsYou: true,
+          },
+          chatId: full.originChatId as string | undefined,
+        },
+        laneKey,
+      );
+    }
+  }
+
+  /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+  async wakeTaskAssignment(taskId: string): Promise<void> {
+    const agentId = this.options.agentId;
+    if (!agentId || !this.taskService) {
+      throw new Error('wakeTaskAssignment: agent not configured');
+    }
+    const full = (await this.taskService.getTask(taskId)) as unknown as Record<string, unknown>;
+    const state = String(full.state ?? '');
+    if (state !== 'active' && state !== 'in-progress') {
+      throw new Error(`wakeTaskAssignment: task ${taskId} is ${state}, not active`);
+    }
+    const sessionId =
+      (full.agreementId as string | undefined) ||
+      (full.originChatId as string | undefined) ||
+      'default';
+    const laneKey = `${agentId}:${sessionId}`;
+    if (!this.sessions.has(laneKey)) {
+      this.sessions.set(laneKey, { sessionId, ownAgentId: agentId });
+    }
+    await this.eventQueue.enqueue(
+      {
+        type: 'task_result',
+        result: {
+          ...full,
+          taskId: (full.taskId as string | undefined) ?? taskId,
+          state,
+          providerIsYou: true,
+        },
+        chatId: full.originChatId as string | undefined,
+      },
+      laneKey,
+    );
+  }
+
   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); }

package/src/adapters/AnthropicAdapter.ts

@@ -48,13 +48,7 @@ export class AnthropicAdapter {
     _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;
+    const anthropicTools = toAnthropicTools(tools);
 
     try {
       const res = await this.client.messages.create({
@@ -114,7 +108,7 @@ export class AnthropicAdapter {
   async chatMessagesStream(
     messages: LlmMessage[],
     onChunk: (text: string) => void,
-  ): Promise<string> {
+  ): Promise<{ text: string; usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | undefined }> {
     const { system, anthropicMessages } = translateMessages(messages);
     const stream = this.client.messages.stream({
       model: this.model,
@@ -127,11 +121,49 @@ export class AnthropicAdapter {
       text += delta;
       onChunk(delta);
     });
-    await stream.finalMessage();
-    return text;
+    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: LlmToolSchema[] = []): Anthropic.Tool[] | undefined {
+  if (!tools.length) return undefined;
+  return tools.map(t => {
+    const td = t as unknown as {
+      schema?: { function?: Record<string, unknown> };
+      function?: Record<string, unknown>;
+    };
+    const fn = (td.schema?.function ?? td.function ?? {}) as Record<string, unknown>;
+    return {
+      name: fn['name'] as string,
+      description: (fn['description'] as string) ?? '',
+      input_schema: (fn['parameters'] ?? { type: 'object' }) as Anthropic.Tool.InputSchema,
+    };
+  });
+}
+
 /**
  * OpenAI-wire-shaped LlmMessage[] → Anthropic { system, messages }.
  * - system messages concatenate into the top-level system param