@ziggs-ai/agent-sdk 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",
@@ -16,11 +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.9",
+    "@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,6 +1,12 @@
 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';
 import { normalizeIncomingEvent, type NormalizedEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
@@ -21,12 +27,13 @@ import { ToolManager } from './tools/ToolManager.js';
 import type { ToolDefinition } from './tools/defineTool.js';
 import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
 import {
   WebSocketClient,
-  MessagesClient,
   ArtifactsClient,
-  ScopeClient,
+  ContextReadClient,
   TelemetryClient,
+  InboxClient,
   type MessageMetadata,
 } from '@ziggs-ai/api-client';
 import { TaskService } from './server/tasks/TaskService.js';
@@ -35,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> {
@@ -63,8 +79,10 @@ interface AgentServices {
   [key: string]: unknown;
 }
 
+
 export interface AgentHostOptions {
   openaiKey?: string;
+  anthropicKey?: string;
   model?: string;
   operatorKey?: string;
   agentId?: string;
@@ -74,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.
@@ -98,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;
   /**
@@ -114,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;
 }
 
@@ -124,14 +162,23 @@ function isLlmAdapter(v: unknown): v is LlmAdapter {
 
 function createBackendServices(options: AgentHostOptions) {
   const toolManager = createToolManager(options);
-  const llm = isLlmAdapter(options.services?.llm)
-    ? options.services!.llm as LlmAdapter
-    : new OpenAIAdapter({ key: options.openaiKey, model: (options.services?.llm as { model?: string } | undefined)?.model || options.model });
+  const model = (options.services?.llm as { model?: string } | undefined)?.model || options.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);
@@ -139,9 +186,8 @@ function createBackendServices(options: AgentHostOptions) {
   return {
     toolManager,
     llm,
-    messagesClient,
     artifactsClient,
-    scopeClient,
+    contextReadClient,
     promptBuilder,
     taskService,
     agreementService,
@@ -166,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;
@@ -180,13 +228,17 @@ 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;
 
   constructor(options: AgentHostOptions = {}) {
     this.options = {
       openaiKey: options.openaiKey || process.env.OPENAI_API_KEY,
-      model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || 'gpt-5.4',
+      anthropicKey: options.anthropicKey || process.env.ANTHROPIC_API_KEY,
+      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,
@@ -203,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;
@@ -215,7 +270,17 @@ export class AgentHost {
   }
 
   private _validate(): void {
-    if (!this.options.openaiKey) throw new Error('openaiKey is required');
+    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) {
+        throw new Error('openaiKey is required');
+      }
+    }
     if (!this.options.operatorKey) throw new Error('operatorKey is required — pass { operatorKey } or set ZIGGS_OPERATOR_KEY');
     if (!this.options.agentId) throw new Error('agentId is required');
   }
@@ -252,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,
@@ -271,13 +349,32 @@ 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); });
 
     this.wsClient.setMessageHandler((text: string, metadata: MessageMetadata) => this.handleMessage(text, metadata as unknown as Record<string, unknown>));
     this.wsClient.setResourceEventHandler((event) => this.handleResourceEvent(event as unknown as Record<string, unknown>));
@@ -339,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,
@@ -401,13 +525,52 @@ 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> {
     const session = this.sessions.get(laneKey);
     if (!session?.sessionId) return;
 
+    // Stale timer frames (superseded epoch) are dropped BEFORE touching the
+    // live timer — a pure-stale frame must not reset a freshly armed countdown.
+    const frame = this.stateTimers.stripStale(event, laneKey);
+    if (frame === null) return;
+
+    // Any event reaching the machine invalidates the countdown ("clear on any
+    // event for the lane"); re-armed below if the tick settles parked+timed.
+    this.stateTimers.clear(laneKey);
+
     // Cold-start recovery: restore FSM state from sessionStore when the
     // in-memory lane has no prior context (e.g. after a container restart).
     if (this.sessionStore && session.ctx === undefined && session.state === undefined) {
@@ -428,27 +591,90 @@ 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, 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),
-        ),
+        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) => {
+          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}`);
         });
       }
+
+      // Arm only when the timeout was handled: an unhandled state-timeout must
+      // not re-arm, or the lane would runtimeLog.error every timeoutMs forever.
+      if (!result.stateTimeoutUnhandled) this._armIfTimedParked(laneKey, result.state);
     } catch (err: unknown) {
       runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+      // Deliberate re-arm on failure. Exact scenario: the tick timed out at
+      // tickTimeoutMs (or sessionStore.load threw) leaving session.state at a
+      // timed parked state — without re-arming, that lane would never wake
+      // again unless a real event happens to arrive.
+      this._armIfTimedParked(laneKey, session.state ?? this.agent.workflow.initial);
+      // Best-effort: also notify the user so the conversation isn't silently
+      // stuck (ZIG-607). Complements the timer re-arm above — that recovers a
+      // parked lane; this tells a waiting human.
+      const ev = event as Record<string, unknown> | undefined;
+      const senderType = String(ev?.senderType ?? '').toUpperCase();
+      const senderId = ev?.senderId as string | undefined;
+      if (senderId && senderType === 'USER') {
+        this.eff({ kind: 'send-message', sessionId: session.sessionId, receiverId: senderId, text: 'Something went wrong. Please try again.' }).catch(() => {});
+      }
+    } finally {
+      clearTimeout(tickWatchdog);
     }
   }
 
+  /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
+  private _armIfTimedParked(laneKey: string, stateName: string | undefined): void {
+    if (!stateName) return;
+    const sd = this.agent.workflow.states[stateName];
+    if (sd?.kind !== 'parked' || sd.timeoutMs === undefined) return;
+    this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
+  }
+
   private _resolveOwnAgentId(metadata: Record<string, unknown> = {}): string | null {
     const self = metadata.self as Record<string, unknown> | undefined;
     const agent = metadata.agent as Record<string, unknown> | undefined;
@@ -464,10 +690,103 @@ export class AgentHost {
       await new Promise((r) => setTimeout(r, 750));
       this.catchUpInFlight = null;
       await this._ensureCatchUp();
+      await this._bootstrapAssignedActiveTasks();
     }
     return this;
   }
-  disconnect() { this.wsClient.disconnect(); }
+  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); }
   registerTool(tool: ToolDefinition) { return this.toolManager.register(tool); }