@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0 — 2026-07-16
+
+### Added (ZIG-784)
+
+- Public brain selection API: `ziggsBrain()`, `claudeBrain()`, and `Brain` interface (`tick()`).
+- `AgentHost` / `createAgent` accept `brain` — preferred over legacy `cognition: 'fsm' | 'claude-sdk'`.
+- README operator flow for picking Ziggs vs Claude brain.
+- `npm run build` + `prepack` for npm publish (compiled `dist/` + `.d.ts`).
+
+### Deprecated
+
+- `cognition` option on `AgentHost` — use `brain: ziggsBrain()` or `brain: claudeBrain()` instead.

package/README.md

@@ -47,6 +47,44 @@ The `wait` action is built-in: `defineAgent` automatically injects it into every
 
 ---
 
+## Pick a brain
+
+The **host** (`AgentHost` / `createAgent`) is the product — identity, WebSocket, tasks, agreements, tools. The **brain** is only *how the agent decides* on each wake.
+
+| Brain | Factory | When to use |
+|--------|---------|-------------|
+| **Ziggs** (workflow / FSM) | `ziggsBrain({ model?, openaiKey?, anthropicKey? })` | Author a workflow; deterministic, controllable routing via `runTurn`. |
+| **Claude** (Agent SDK) | `claudeBrain({ anthropicKey, model?, maxTurns?, specialization? })` | Hand the loop to Claude `query()`; fewer knobs, more autonomy. |
+
+Both brains share the same host, tools, and Ziggs protocol. Pick control vs autonomy.
+
+```ts
+import { createAgent, defineAgent, ziggsBrain, claudeBrain } from '@ziggs-ai/agent-sdk';
+
+// Ziggs brain — workflow required (states + initial or explicit workflow)
+const ziggsHost = createAgent({
+  ...defineAgent({ agentId: 'my-agent', description: '…', initial: 'idle', states: { … } }),
+  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
+  brain: ziggsBrain({ openaiKey: process.env.OPENAI_API_KEY }),
+});
+
+// Claude brain — no workflow needed (host synthesizes a parked state)
+const claudeHost = createAgent({
+  agentId: 'claude-agent',
+  description: 'A hired Claude specialist',
+  operatorKey: process.env.ZIGGS_OPERATOR_KEY,
+  brain: claudeBrain({ anthropicKey: process.env.ANTHROPIC_API_KEY }),
+});
+
+await claudeHost.connectAsync();
+```
+
+Legacy `cognition: 'fsm' | 'claude-sdk'` still works but is deprecated — prefer `brain`.
+
+The public **`Brain`** interface is `tick(TickInput): Promise<TickOutput>`. Built-in implementations: `Agent` (Ziggs) and `ClaudeSdkAgent` (Claude).
+
+---
+
 ## How you usually run an agent
 
 1. **`defineAgent({ ... })`** → options object including `workflow`.
@@ -60,6 +98,7 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 ## Main exports (entry: `src/index.js`)
 
 - **`AgentHost`**, **`createAgent`**, **`createAgentPool`**, **`defineAgent`**
+- **Brains:** `ziggsBrain`, `claudeBrain`, type `Brain`
 - **`Agent`**, **`AgentMachine`**, **`runTurn`**
 - **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
 - **Tools come in two tiers — single home: `server/tools/`:**
@@ -68,14 +107,14 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
 - **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly.)
 
-Package export: `"."` → `src/index.js` (see `package.json`).
+Package export: `"."` → `dist/index.js` (see `package.json`; `npm run build` before publish or monorepo tests).
 
 ---
 
 ## Requirements
 
 - **Node** ≥ 18
-- Env: **`OPENAI_API_KEY`** (and optionally **`OPENAI_MODEL`**) for `defineAgent` defaults; Ziggs **`ZIGGS_OPERATOR_KEY`** (operator token, scope `agents:impersonate`) for platform features.
+- Env: **`OPENAI_API_KEY`** for the Ziggs brain; **`ANTHROPIC_API_KEY`** for the Claude brain; Ziggs **`ZIGGS_OPERATOR_KEY`** (operator token, scope `agents:impersonate`) for platform features.
 
 ---
 

package/dist/AgentHost.d.ts

@@ -0,0 +1,201 @@
+import type { AgentConfig, Ctx, Workflow } from './types.js';
+import { Agent } from './agent/Agent.js';
+import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
+import { type BrainSelection } from './brain/index.js';
+export type { CognitionKind };
+import { type NormalizedEvent } from './ingress/normalizeIncoming.js';
+import { type MemoryStore } from './memory/MemoryStore.js';
+/**
+ * Operator-provided FSM session persistence.
+ *
+ * AgentHost calls load() before each tick when a lane has no in-memory state
+ * (e.g. after a container restart) and save() after every successful tick.
+ * A null return from load() means "no prior state — start fresh."
+ */
+export interface SessionStore {
+    load(laneKey: string): Promise<{
+        ctx?: Ctx;
+        state?: string;
+    } | null | undefined>;
+    save(laneKey: string, session: {
+        ctx?: Ctx;
+        state?: string;
+    }): Promise<void>;
+}
+import { ToolManager } from './tools/ToolManager.js';
+import type { ToolDefinition } from './tools/defineTool.js';
+import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import { WebSocketClient } from '@ziggs-ai/api-client';
+/**
+ * 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 declare const DEFAULT_MODEL = "claude-haiku-4-5";
+/**
+ * Given a normalized event, return the sessionId for this agent. Return
+ * `null` to skip processing. Lets each Agent define what "session" means —
+ * chat-scoped agents bucket by chatId (the default), task-scoped agents
+ * could bucket by taskId, cron agents by schedule id, etc.
+ */
+export type SessionResolver = (normalized: NormalizedEvent, ownAgentId: string) => string | null;
+interface LlmAdapter {
+    chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
+}
+interface AgentServices {
+    tools?: ToolDefinition[];
+    llm?: {
+        model?: string;
+    } | LlmAdapter;
+    [key: string]: unknown;
+}
+export interface AgentHostOptions {
+    openaiKey?: string;
+    anthropicKey?: string;
+    model?: string;
+    operatorKey?: string;
+    agentId?: string;
+    name?: string | null;
+    wsUrl?: string;
+    description?: string;
+    specialization?: string | null;
+    tools?: ToolDefinition[];
+    taskTools?: 'all' | 'none' | string[];
+    /**
+     * Brain selection — preferred over legacy `cognition`.
+     * `ziggsBrain()` for the workflow/FSM loop; `claudeBrain()` for Claude Agent SDK.
+     */
+    brain?: BrainSelection;
+    /**
+     * @deprecated Use `brain: ziggsBrain()` or `brain: claudeBrain()` instead.
+     * Internal mapping: `fsm` → Ziggs brain, `claude-sdk` → Claude brain.
+     */
+    cognition?: CognitionKind;
+    /** Max agentic turns per Claude SDK wake. Default 30. */
+    claudeMaxTurns?: number;
+    services?: AgentServices;
+    workflow?: Workflow;
+    states?: Workflow['states'];
+    initial?: string;
+    tickTimeoutMs?: number;
+    /** Per-agent session keying. Defaults to `(n) => n.chatId`. */
+    sessionResolver?: SessionResolver;
+    /**
+     * Agent-private long-term memory. Operator-provided. Default: a fresh
+     * `InMemoryStore` (non-durable; lost on process restart). For durability,
+     * pass `new FileMemoryStore(path)` or your own implementation.
+     */
+    memory?: MemoryStore;
+    /**
+     * FSM session persistence. Operator-provided. When set, AgentHost loads
+     * prior state before each tick (cold-start recovery) and saves after every
+     * successful tick. Omit to keep state in-process only (default behaviour).
+     */
+    sessionStore?: SessionStore;
+    /** Observability tap: called after every effect with the effect and its response. */
+    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;
+    /**
+     * Pull inbox on every WS connect/reconnect (ZIG-454). Default true.
+     * Recovers messages lost when backend in-memory pending queues are dropped.
+     */
+    inboxCatchUp?: boolean;
+}
+/**
+ * AgentHost — the Server. Owns a pure {@link Agent}, an {@link EffectHandler},
+ * a transport (Ziggs WebSocket), and the lane router (per-session FIFO queue
+ * + in-memory session state).
+ *
+ *   transport (WS)  →  handleMessage  →  agent.tick(... , eff)  →  ...
+ */
+export declare class AgentHost {
+    options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+    toolManager: ToolManager;
+    llm?: OpenAIAdapter | LlmAdapter;
+    agent: Agent | ClaudeSdkAgent;
+    wsClient: WebSocketClient;
+    private eff;
+    private eventQueue;
+    private sessions;
+    private sessionResolver;
+    private tickTimeoutMs;
+    private memory;
+    private sessionStore;
+    private taskService;
+    private agreementService;
+    private messageSender;
+    private seenMessages;
+    /** Lazy inbox client for advancing the watermark on the live-push path (ZIG-832 P4). */
+    private _inbox?;
+    private stateTimers;
+    private catchUpInFlight;
+    private inboxCatchUpEnabled;
+    constructor(options?: AgentHostOptions);
+    private _validate;
+    private _setup;
+    /**
+     * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
+     */
+    private _ensureCatchUp;
+    private _runInboxCatchUp;
+    /**
+     * Push notification handler — invoked when the backend sees a relevant
+     * resource change (artifact created, task state transition, agreement
+     * updated). The agent decides which session/lane to wake based on the
+     * event payload; it pulls the actual data via the primitive endpoints
+     * from inside the tick.
+     *
+     * Lightweight: defers all work to a tick by enqueueing a synthetic event
+     * carrying just enough context for the agent to route it.
+     */
+    handleResourceEvent(event: Record<string, unknown>): Promise<void>;
+    /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
+    handleMessage(text: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Best-effort: advance the inbox watermark for a chat handled live (ZIG-832 P4). */
+    private _ackChatWatermark;
+    private _processEvent;
+    /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
+    private _armIfTimedParked;
+    private _resolveOwnAgentId;
+    connectAsync(timeout?: number): Promise<this>;
+    private _bootstrapAssignedActiveTasks;
+    /** ZIG-802: replay task-assigned for an existing active task (demo recovery). */
+    wakeTaskAssignment(taskId: string): Promise<void>;
+    disconnect(): void;
+    /** Waits for all in-flight ticks to complete. Call before process.exit() on SIGTERM. */
+    drain(timeoutMs?: number): Promise<void>;
+    registerTool(tool: ToolDefinition): string;
+    isConnected(): boolean;
+}
+/**
+ * createAgent(config)            → AgentHost
+ * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
+ */
+export declare function createAgent(options?: AgentHostOptions | AgentConfig): AgentHost;
+export declare function createAgentPool(configs: AgentHostOptions[] | AgentConfig[], opts?: {
+    poolOptions?: {
+        maxActive?: number;
+        idleTimeoutMs?: number;
+    };
+}): Promise<unknown>;
+export default AgentHost;