@ziggs-ai/agent-sdk 0.1.10 → 0.1.11

package/package.json

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

package/src/AgentHost.ts

@@ -1,6 +1,7 @@
 import type { AgentConfig, Ctx, EffectHandler, Identity, Workflow } from './types.js';
 import { Agent } from './agent/Agent.js';
 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,6 +22,7 @@ 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,
@@ -65,6 +67,7 @@ interface AgentServices {
 
 export interface AgentHostOptions {
   openaiKey?: string;
+  anthropicKey?: string;
   model?: string;
   operatorKey?: string;
   agentId?: string;
@@ -124,9 +127,12 @@ 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
-    : new OpenAIAdapter({ key: options.openaiKey, model: (options.services?.llm as { model?: string } | undefined)?.model || options.model });
+    : 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);
@@ -180,12 +186,14 @@ export class AgentHost {
   private agreementService!: AgreementService;
   private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
   private seenMessages = new SeenMessages();
+  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,
+      anthropicKey: options.anthropicKey || process.env.ANTHROPIC_API_KEY,
       model: options.model || (!isLlmAdapter(options.services?.llm) ? options.services?.llm?.model : undefined) || 'gpt-5.4',
       operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
       agentId: options.agentId || '',
@@ -215,7 +223,13 @@ export class AgentHost {
   }
 
   private _validate(): void {
-    if (!this.options.openaiKey) throw new Error('openaiKey is required');
+    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');
   }
@@ -278,6 +292,7 @@ export class AgentHost {
     });
 
     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>));
@@ -408,6 +423,15 @@ export class AgentHost {
     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) {
@@ -430,7 +454,7 @@ export class AgentHost {
 
     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 }),
+        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),
         ),
@@ -444,11 +468,37 @@ export class AgentHost {
           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(() => {});
+      }
     }
   }
 
+  /** 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;
@@ -467,7 +517,7 @@ export class AgentHost {
     }
     return this;
   }
-  disconnect() { this.wsClient.disconnect(); }
+  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); }

package/src/adapters/AnthropicAdapter.ts

@@ -0,0 +1,206 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { LlmMessage, LlmResponse, LlmToolCall, LlmToolSchema } from '../types.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+interface AdapterOptions {
+  key?: string;
+  model?: string;
+}
+
+// Claude 4.7+ models reject sampling params (temperature/top_p/top_k) with a
+// 400 and run without thinking when the `thinking` param is omitted. We omit
+// both on purpose: the SDK's LlmMessage history cannot round-trip thinking
+// blocks through the tool loop, so thinking must stay off.
+const MAX_COMPLETION_TOKENS = 16000;
+
+/**
+ * Anthropic adapter satisfying the same LlmAdapter contract as OpenAIAdapter:
+ * OpenAI-wire-shaped LlmMessage[] in, { content, tool_calls, usage } out.
+ * Selected by AgentHost when the configured model id starts with "claude".
+ */
+export class AnthropicAdapter {
+  private client: Anthropic;
+  model: string;
+
+  constructor({ key, model = 'claude-opus-4-8' }: AdapterOptions) {
+    this.client = new Anthropic({ apiKey: key });
+    this.model = model;
+  }
+
+  async chat(
+    prompt: string,
+    tools: LlmToolSchema[] = [],
+    _temperature = 0,
+    systemHints: LlmMessage[] = [],
+    options: Record<string, unknown> = {},
+  ): Promise<LlmResponse> {
+    const messages: LlmMessage[] = [
+      { role: 'system', content: 'Respond with valid JSON.' },
+      ...systemHints,
+      { role: 'user', content: prompt },
+    ];
+    return this.chatMessages(messages, tools, options);
+  }
+
+  async chatMessages(
+    messages: LlmMessage[],
+    tools: LlmToolSchema[] = [],
+    _options: Record<string, unknown> = {},
+  ): Promise<LlmResponse> {
+    const { system, anthropicMessages } = translateMessages(messages);
+    const anthropicTools: Anthropic.Tool[] | undefined = tools.length > 0
+      ? tools.map(t => ({
+          name: t.function.name,
+          description: t.function.description ?? '',
+          input_schema: (t.function.parameters ?? { type: 'object' }) as Anthropic.Tool.InputSchema,
+        }))
+      : undefined;
+
+    try {
+      const res = await this.client.messages.create({
+        model: this.model,
+        max_tokens: MAX_COMPLETION_TOKENS,
+        ...(system ? { system } : {}),
+        messages: anthropicMessages,
+        ...(anthropicTools ? { tools: anthropicTools } : {}),
+      });
+
+      if (res.stop_reason === 'refusal') {
+        throw new Error(`LLM refused the request (stop_reason=refusal)`);
+      }
+
+      const content = res.content
+        .filter((b): b is Anthropic.TextBlock => b.type === 'text')
+        .map(b => b.text)
+        .join('')
+        .trim() || null;
+      const toolCalls: LlmToolCall[] | null = (() => {
+        const uses = res.content.filter((b): b is Anthropic.ToolUseBlock => b.type === 'tool_use');
+        if (!uses.length) return null;
+        return uses.map(u => ({
+          id: u.id,
+          function: { name: u.name, arguments: JSON.stringify(u.input ?? {}) },
+        }));
+      })();
+
+      if (!content && !toolCalls && res.stop_reason === 'max_tokens') {
+        throw new Error(
+          `LLM returned no usable output — completion token budget exhausted before any content (stop_reason=max_tokens)`,
+        );
+      }
+
+      return {
+        content: content ?? undefined,
+        tool_calls: toolCalls ?? undefined,
+        usage: res.usage
+          ? {
+              prompt_tokens: res.usage.input_tokens,
+              completion_tokens: res.usage.output_tokens,
+              total_tokens: res.usage.input_tokens + res.usage.output_tokens,
+            }
+          : undefined,
+      };
+    } catch (error) {
+      const err = error as Error & { status?: number };
+      runtimeLog.error('AnthropicAdapter', `LLM API call failed: ${err.message}`, {
+        model: this.model,
+        error: err.message,
+        status: err.status ?? 'unknown',
+      });
+      throw error;
+    }
+  }
+
+  async chatMessagesStream(
+    messages: LlmMessage[],
+    onChunk: (text: string) => void,
+  ): Promise<string> {
+    const { system, anthropicMessages } = translateMessages(messages);
+    const stream = this.client.messages.stream({
+      model: this.model,
+      max_tokens: MAX_COMPLETION_TOKENS,
+      ...(system ? { system } : {}),
+      messages: anthropicMessages,
+    });
+    let text = '';
+    stream.on('text', (delta) => {
+      text += delta;
+      onChunk(delta);
+    });
+    await stream.finalMessage();
+    return text;
+  }
+}
+
+/**
+ * OpenAI-wire-shaped LlmMessage[] → Anthropic { system, messages }.
+ * - system messages concatenate into the top-level system param
+ * - assistant tool_calls become tool_use blocks (arguments JSON-parsed)
+ * - role:"tool" results become user-turn tool_result blocks
+ * Consecutive same-role turns are merged (Anthropic requires alternation to
+ * start with user; the API tolerates consecutive same-role, but tool_result
+ * blocks must open the user turn that answers a tool_use turn).
+ */
+function translateMessages(messages: LlmMessage[]): {
+  system: string | undefined;
+  anthropicMessages: Anthropic.MessageParam[];
+} {
+  const systemParts: string[] = [];
+  const out: Anthropic.MessageParam[] = [];
+
+  for (const m of messages) {
+    if (m.role === 'system') {
+      if (m.content) systemParts.push(m.content);
+      continue;
+    }
+    if (m.role === 'tool') {
+      const block: Anthropic.ToolResultBlockParam = {
+        type: 'tool_result',
+        tool_use_id: m.tool_call_id ?? '',
+        content: m.content ?? '',
+      };
+      const last = out[out.length - 1];
+      if (last && last.role === 'user' && Array.isArray(last.content)) {
+        (last.content as Anthropic.ContentBlockParam[]).push(block);
+      } else {
+        out.push({ role: 'user', content: [block] });
+      }
+      continue;
+    }
+    if (m.role === 'assistant' && m.tool_calls?.length) {
+      const blocks: Anthropic.ContentBlockParam[] = [];
+      if (m.content) blocks.push({ type: 'text', text: m.content });
+      for (const tc of m.tool_calls) {
+        blocks.push({
+          type: 'tool_use',
+          id: tc.id,
+          name: tc.function.name,
+          input: safeParseJson(tc.function.arguments),
+        });
+      }
+      out.push({ role: 'assistant', content: blocks });
+      continue;
+    }
+    out.push({ role: m.role, content: m.content ?? '' });
+  }
+
+  if (!out.length || out[0].role !== 'user') {
+    out.unshift({ role: 'user', content: '(session start)' });
+  }
+
+  return {
+    system: systemParts.length ? systemParts.join('\n\n') : undefined,
+    anthropicMessages: out,
+  };
+}
+
+function safeParseJson(s: string): Record<string, unknown> {
+  try {
+    const v = JSON.parse(s);
+    return typeof v === 'object' && v !== null ? v : {};
+  } catch {
+    // Malformed arguments string from a prior turn's history: replaying it as
+    // an empty input beats crashing the whole turn on someone else's output.
+    return {};
+  }
+}

package/src/adapters/McpAdapter.ts

@@ -8,7 +8,17 @@ import type { Workflow } from '../types.js';
 
 export type McpTransportConfig =
   | { type: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
-  | { type: 'http'; url: 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
@@ -120,6 +130,28 @@ export interface CreateMcpAgentOptions extends Omit<AgentHostOptions, 'tools' |
   extraTools?: ToolDefinition[];
   /** Override the default single-state thinking workflow. */
   workflow?: Workflow;
+  /**
+   * Max tools to bind to the LLM per turn. LLM providers cap the `tools` array
+   * (OpenAI: 128); an MCP server exposing more (e.g. PostHog: 146) makes every
+   * turn fail with `400 ... array too long`. When the server's tool count
+   * exceeds this budget the list is truncated (and logged). Defaults to 128.
+   * See ZIG-759; Phase 2 will replace truncation with query-aware selection.
+   */
+  maxTools?: number;
+}
+
+/** Provider `tools` array cap (OpenAI's is 128). */
+const DEFAULT_MAX_TOOLS = 128;
+/** Headroom reserved for control actions (wait/respond) + future additions. */
+const CONTROL_TOOL_RESERVE = 4;
+
+/**
+ * How many MCP tools may be bound to the LLM, given the provider cap and the
+ * number of extra (non-MCP) tools the agent also carries. Always >= 1 so a
+ * pathological config still binds something rather than nothing. ZIG-759.
+ */
+export function mcpToolBudget(maxTools: number, extraToolCount: number): number {
+  return Math.max(1, maxTools - CONTROL_TOOL_RESERVE - extraToolCount);
 }
 
 export interface McpAgentHandle {
@@ -130,7 +162,7 @@ export interface McpAgentHandle {
   toolNames: string[];
 }
 
-function buildTransport(config: McpTransportConfig, defaults: { agentId?: string }) {
+export function buildTransport(config: McpTransportConfig, defaults: { agentId?: string } = {}) {
   if (config.type === 'stdio') {
     return new StdioClientTransport({
       command: config.command,
@@ -145,7 +177,12 @@ function buildTransport(config: McpTransportConfig, defaults: { agentId?: string
       fetch: wrapGatewayFetch(),
     });
   }
-  return new StreamableHTTPClientTransport(new URL(config.url));
+  return new StreamableHTTPClientTransport(
+    new URL(config.url),
+    config.headers && Object.keys(config.headers).length > 0
+      ? { requestInit: { headers: config.headers } }
+      : undefined,
+  );
 }
 
 type McpTool = {
@@ -276,17 +313,26 @@ function buildDefaultWorkflow(description: string, mcpTools: McpTool[]): Workflo
  *   });
  */
 export async function createMcpAgent(options: CreateMcpAgentOptions): Promise<McpAgentHandle> {
-  const { transport: transportConfig, extraTools = [], workflow, ...hostOptions } = options;
+  const { transport: transportConfig, extraTools = [], workflow, maxTools = DEFAULT_MAX_TOOLS, ...hostOptions } = options;
 
   const transport = buildTransport(transportConfig, { agentId: hostOptions.agentId });
   const client = new Client({ name: 'ziggs-mcp-agent', version: '1.0.0' });
 
   await client.connect(transport);
 
-  const { tools: rawTools } = await client.listTools();
-  const mcpTools = mapMcpTools(client, rawTools as McpTool[]);
+  const listed = (await client.listTools()).tools as McpTool[];
+  // Cap the tool set bound to the LLM: providers reject a `tools` array longer
+  // than their limit (OpenAI 128). Truncate — never crash — and log what dropped
+  // so a large server (e.g. PostHog: 146 tools) still answers. ZIG-759 Phase 1.
+  const budget = mcpToolBudget(maxTools, extraTools.length);
+  let rawTools = listed;
+  if (listed.length > budget) {
+    rawTools = listed.slice(0, budget);
+    console.warn(`[McpAdapter] ${hostOptions.agentId}: MCP server exposes ${listed.length} tools, over the ${maxTools}-tool LLM cap; binding the first ${rawTools.length}, dropping ${listed.length - rawTools.length}. (ZIG-759 Phase 2 will select per query.)`);
+  }
+  const mcpTools = mapMcpTools(client, rawTools);
 
-  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools as McpTool[]);
+  const resolvedWorkflow = workflow ?? buildDefaultWorkflow(hostOptions.description ?? '', rawTools);
 
   const host = new AgentHost({
     ...hostOptions,

package/src/adapters/OpenAIAdapter.ts

@@ -14,6 +14,13 @@ interface AdapterOptions {
   model?: string;
 }
 
+/** OpenAI completion-token cap varies by model family (e.g. gpt-4o-mini max 16384). */
+export function maxCompletionTokensForModel(model: string): number {
+  const m = model.toLowerCase();
+  if (m.includes('gpt-4o')) return 16384;
+  return 25000;
+}
+
 export class OpenAIAdapter {
   private client: OpenAI;
   model: string;
@@ -99,11 +106,9 @@ export class OpenAIAdapter {
         model: this.model,
         messages: finalMessages,
         stream: false,
-        // 25000 reserves room for hidden reasoning tokens on reasoning models
-        // (gpt-5.x/o-series) — they're billed against this cap before any
-        // visible content, so a low cap can exhaust the budget and return
-        // empty content with finish_reason "length".
-        max_completion_tokens: 25000,
+        // Reasoning models (gpt-5.x/o-series) need a high cap for hidden
+        // reasoning tokens; gpt-4o family is capped lower by the API.
+        max_completion_tokens: maxCompletionTokensForModel(this.model),
         response_format: responseFormat,
         ...(openAITools && { tools: openAITools }),
         ...restOptions,
@@ -167,7 +172,7 @@ export class OpenAIAdapter {
       model: this.model,
       messages,
       stream: true,
-      max_completion_tokens: 25000,
+      max_completion_tokens: maxCompletionTokensForModel(this.model),
     });
     let text = '';
     for await (const chunk of stream) {

package/src/adapters/index.ts

@@ -1 +1,2 @@
 export { OpenAIAdapter } from './OpenAIAdapter.js';
+export { AnthropicAdapter } from './AnthropicAdapter.js';

package/src/agent/Agent.ts

@@ -40,6 +40,8 @@ export interface TickOutput {
   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. */
   metrics: { llmCalls: number; tokens: { total: number; input: number; output: number } };
 }
@@ -95,6 +97,7 @@ export class Agent {
       ctx: machine.ctx,
       state: machine.state,
       parked: machine.isParked,
+      stateTimeoutUnhandled: machine.stateTimeoutUnhandled,
       metrics: { llmCalls: machine.llmCalls, tokens: machine.tokens },
     };
   }

package/src/defineAgent.ts

@@ -1,12 +1,16 @@
 import type { AgentConfig, DefineAgentInput, Workflow } from './types.js';
 import { validateWorkflow } from './runtime/validateWorkflow.js';
+import { injectKickoffDefault } from './runtime/kickoff.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
- * returns a frozen AgentConfig. Does NOT mutate the input — `wait` action and
- * `activeWait` transitions are the workflow author's responsibility (visible
- * spread of `thinkingDefaults`).
+ * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
+ * the author's visible spread of `thinkingDefaults`. ONE default is injected (as
+ * new objects): the agreement-kickoff state `kickingOff` plus a last-position
+ * transition into it, appended to every state that does not already handle a
+ * proposer-side proposal-resolved/approve outcome (runtime/kickoff.ts). The
+ * state name 'kickingOff' is reserved; defining it throws.
  *
  * Validation throws WorkflowValidationError on hard problems and logs warnings
  * on soft ones (e.g. missing wait fallthrough).
@@ -17,12 +21,14 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
   if (!input?.states) throw new Error('[defineAgent] states is required');
   if (!input?.initial) throw new Error('[defineAgent] initial state is required');
 
-  const workflow: Workflow = {
+  // Agreement-kickoff default (see runtime/kickoff.ts): injected BEFORE
+  // validation so the injected state/transitions are validated too.
+  const workflow: Workflow = injectKickoffDefault({
     id: input.agentId,
     description: input.description,
     initial: input.initial,
     states: input.states,
-  };
+  });
 
   const { warnings } = validateWorkflow(workflow);
   for (const w of warnings) runtimeLog.warn('defineAgent', w);
@@ -34,6 +40,7 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
 
   const model =
     input.services?.llm?.model ||
+    process.env.LLM_MODEL ||
     process.env.OPENAI_MODEL ||
     'gpt-5.4';
 
@@ -46,6 +53,7 @@ export function defineAgent(input: DefineAgentInput): AgentConfig {
 
   const config: AgentConfig = {
     openaiKey: process.env.OPENAI_API_KEY,
+    anthropicKey: process.env.ANTHROPIC_API_KEY,
     ...(operatorKey ? { operatorKey } : {}),
     agentId,
     description,

package/src/index.ts

@@ -18,6 +18,8 @@ export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
+export { StateTimers } from './server/StateTimers.js';
+export type { StateTimeoutEvent } from './server/StateTimers.js';
 export { OutboxBuffer } from './server/OutboxBuffer.js';
 export { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 
@@ -26,6 +28,7 @@ export { AgentMachine, type TransitionEvent } from './runtime/AgentMachine.js';
 export { runTurn } from './runtime/runTurn.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
+export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';