@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/README.md

@@ -62,7 +62,7 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 - **`ZiggsAgent`**, **`createAgent`**, **`defineAgent`**
 - **`Agent`**, **`AgentMachine`**, **`runTurn`**
 - **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
-- **Task tools:** `taskMakeTaskTool`, `taskUpdateTaskTool`, `taskRespondProposalTool`, `taskMakeSubTasksTool`, `taskUpdatePlanStepTool`, `TASK_PROTOCOL_TOOLS`
+- **Protocol tools:** `agreementProposeTool`, `agreementDelegateTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`, `PROTOCOL_TOOLS`
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
 - **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReader`, `ContextWriter`, URL helpers, etc.
 

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
-  "main": "src/index.js",
+  "main": "src/index.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.ts"
   },
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-test-module-mocks --import tsx/esm --test --test-reporter=spec test/*.test.ts",
+    "test:watch": "node --experimental-test-module-mocks --import tsx/esm --test --watch test/*.test.ts"
+  },
   "dependencies": {
-    "@ziggs-ai/api-client": "^0.1.3",
+    "@ziggs-ai/api-client": "^0.1.4",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0"

package/src/AgentHost.ts

@@ -0,0 +1,342 @@
+import type { AgentConfig, Ctx, EffectHandler, Identity, Workflow } from './types.js';
+import { Agent } from './agent/Agent.js';
+import { EventQueue } from './server/EventQueue.js';
+import { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
+import { normalizeIncomingEvent, type NormalizedEvent } from './ingress/normalizeIncoming.js';
+import { PromptBuilder } from './runtime/PromptBuilder.js';
+import { InMemoryStore, type MemoryStore } from './memory/MemoryStore.js';
+import { ToolManager } from './tools/ToolManager.js';
+import type { ToolDefinition } from './tools/defineTool.js';
+import { PROTOCOL_TOOLS } from './server/tasks/protocolTools.js';
+import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import {
+  WebSocketClient,
+  MessagesClient,
+  ArtifactsClient,
+  ScopeClient,
+  TelemetryClient,
+  type MessageMetadata,
+} from '@ziggs-ai/api-client';
+import { TaskService } from './server/tasks/TaskService.js';
+import { AgreementService } from './server/agreements/AgreementService.js';
+import { runtimeLog } from './shared/runtimeLog.js';
+
+// 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> {
+  const modPath = './server/ConnectionPool.js';
+  const mod = await import(/* @vite-ignore */ modPath) as { ConnectionPool: new (opts?: { maxActive?: number; idleTimeoutMs?: number }) => unknown };
+  return mod.ConnectionPool;
+}
+
+/**
+ * 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;
+
+const DEFAULT_SESSION_RESOLVER: SessionResolver = (normalized) => normalized.chatId;
+
+interface AgentServices {
+  tools?: ToolDefinition[];
+  llm?: { model?: string };
+  [key: string]: unknown;
+}
+
+export interface AgentHostOptions {
+  openaiKey?: string;
+  model?: string;
+  operatorKey?: string;
+  agentId?: string;
+  name?: string | null;
+  wsUrl?: string;
+  description?: string;
+  specialization?: string | null;
+  tools?: ToolDefinition[];
+  taskTools?: 'all' | 'none' | string[];
+  services?: AgentServices;
+  workflow?: Workflow;
+  // Convenience: states + initial without an explicit 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;
+}
+
+function createToolManager(options: AgentHostOptions): ToolManager {
+  const toolManager = new ToolManager();
+  const userTools = options.tools || options.services?.tools || [];
+  let taskTools: ToolDefinition[];
+  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 : [])]);
+  return toolManager;
+}
+
+function createBackendServices(options: AgentHostOptions) {
+  const toolManager = createToolManager(options);
+  const llm = new OpenAIAdapter({ key: options.openaiKey, model: options.services?.llm?.model || options.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 promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
+  const taskService = new TaskService(operatorKey, agentId);
+  const agreementService = new AgreementService(operatorKey, agentId);
+  const telemetryClient = new TelemetryClient(operatorKey, agentId);
+  return {
+    toolManager,
+    llm,
+    messagesClient,
+    artifactsClient,
+    scopeClient,
+    promptBuilder,
+    taskService,
+    agreementService,
+    telemetryClient,
+  };
+}
+
+interface LaneSession {
+  sessionId: string;
+  ownAgentId: string;
+  ctx?: Ctx;
+  state?: string;
+}
+
+/**
+ * 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 class AgentHost {
+  options: Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+  toolManager!: ToolManager;
+  llm!: OpenAIAdapter;  // retained for external inspection
+  agent!: Agent;
+  wsClient!: WebSocketClient;
+  private eff!: EffectHandler;
+  private eventQueue!: EventQueue;
+  private sessions = new Map<string, LaneSession>();
+  private sessionResolver: SessionResolver;
+  private tickTimeoutMs: number;
+  private memory: MemoryStore;
+
+  constructor(options: AgentHostOptions = {}) {
+    this.options = {
+      openaiKey: options.openaiKey || process.env.OPENAI_API_KEY,
+      model: options.model || options.services?.llm?.model || 'gpt-5.4',
+      operatorKey: options.operatorKey || process.env.ZIGGS_OPERATOR_KEY || undefined,
+      agentId: options.agentId || '',
+      name: options.name || null,
+      wsUrl: options.wsUrl,
+      description: options.description || 'A helpful assistant',
+      specialization: options.specialization ?? null,
+      tools: options.tools || [],
+      taskTools: options.taskTools,
+      states: options.states,
+      initial: options.initial,
+      services: options.services,
+      workflow: options.workflow,
+      tickTimeoutMs: options.tickTimeoutMs,
+      sessionResolver: options.sessionResolver,
+    } as Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+    this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
+    this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
+    this.memory = options.memory ?? new InMemoryStore();
+    this._validate();
+    this._setup();
+  }
+
+  private _validate(): void {
+    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');
+  }
+
+  private _setup(): void {
+    const services = createBackendServices(this.options);
+    this.toolManager = services.toolManager;
+    this.llm = services.llm;
+
+    this.wsClient = new WebSocketClient({
+      wsUrl: this.options.wsUrl,
+      operatorKey: this.options.operatorKey,
+      agentId: this.options.agentId,
+      label: this.options.name || 'agent',
+    });
+
+    const messageSender = (message: string, receiverId: string, sessionId: string): Promise<unknown> => {
+      this.wsClient.send(sessionId, receiverId, message);
+      return Promise.resolve(undefined);
+    };
+
+    let workflow = this.options.workflow;
+    if (!workflow && this.options.states) {
+      workflow = {
+        id: this.options.agentId,
+        description: this.options.description!,
+        initial: this.options.initial || 'idle',
+        states: this.options.states,
+      };
+    }
+    if (!workflow?.states) 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,
+      taskService: services.taskService,
+      agreementService: services.agreementService,
+      messageSender,
+      toolManager: services.toolManager,
+      operatorKey: this.options.operatorKey!,
+      agentId: this.options.agentId!,
+      telemetryClient: services.telemetryClient,
+    });
+
+    this.agent = new Agent({
+      workflow,
+      toolManager: services.toolManager,
+      promptBuilder: services.promptBuilder,
+    });
+
+    this.eventQueue = new EventQueue((event, laneKey) => this._processEvent(event, 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>));
+  }
+
+  /**
+   * 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.
+   */
+  async handleResourceEvent(event: Record<string, unknown>): Promise<void> {
+    if (!event || typeof event !== 'object') return;
+    const ownAgentId = this.options.agentId;
+    if (!ownAgentId) 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,
+    // counterpartyId) will get the right lane here as long as the wire
+    // event carries the corresponding id.
+    const fakeNormalized = {
+      chatId: event.chatId as string | null,
+      event: { type: 'message' as const, timestamp: Date.now(), text: '' },
+      shouldProcess: true,
+      reason: null,
+    } as NormalizedEvent;
+    const sessionId = this.sessionResolver(fakeNormalized, ownAgentId);
+    if (!sessionId) return;
+
+    const laneKey = `${ownAgentId}:${sessionId}`;
+    if (!this.sessions.has(laneKey)) {
+      this.sessions.set(laneKey, { sessionId, ownAgentId });
+    }
+    return this.eventQueue.enqueue({ type: 'resource_changed', resource: event, chatId: event.chatId, taskId: event.taskId, agreementId: event.agreementId }, laneKey);
+  }
+
+  /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
+  async handleMessage(text: string, metadata: Record<string, unknown> = {}): Promise<void> {
+    const ownAgentId = this._resolveOwnAgentId(metadata);
+    if (!ownAgentId) {
+      runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
+      return;
+    }
+
+    const normalized = normalizeIncomingEvent({ text, metadata, ownAgentId });
+    if (!normalized.shouldProcess) {
+      runtimeLog.info('AgentHost', `skip reason=${normalized.reason || 'not_relevant'}`);
+      return;
+    }
+
+    const sessionId = this.sessionResolver(normalized, ownAgentId);
+    if (!sessionId) {
+      runtimeLog.warn('AgentHost', 'session resolver returned null, skipping');
+      return;
+    }
+
+    const laneKey = `${ownAgentId}:${sessionId}`;
+    if (!this.sessions.has(laneKey)) {
+      this.sessions.set(laneKey, { sessionId, ownAgentId });
+    }
+    return this.eventQueue.enqueue(normalized.event, laneKey);
+  }
+
+  private async _processEvent(event: unknown, laneKey: string): Promise<void> {
+    const session = this.sessions.get(laneKey);
+    if (!session?.sessionId) return;
+
+    const identity: Identity = {
+      agentId: session.ownAgentId || this.options.agentId,
+      sessionId: session.sessionId,
+      laneKey,
+    };
+
+    try {
+      const result = await Promise.race([
+        this.agent.tick({ event, ctx: session.ctx, state: session.state, identity, eff: this.eff, memory: this.memory }),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error('tick timeout')), this.tickTimeoutMs),
+        ),
+      ]);
+      session.ctx = result.ctx;
+      session.state = result.state;
+      this.sessions.set(laneKey, session);
+    } catch (err: unknown) {
+      runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+    }
+  }
+
+  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;
+    return this.options.agentId || (self?.id as string) || (agent?.id as string) || (metadata.ziggsAgentId as string) || null;
+  }
+
+  connectAsync(timeout?: number) { return this.wsClient.connectAsync(timeout); }
+  disconnect() { this.wsClient.disconnect(); }
+  registerTool(tool: ToolDefinition) { return this.toolManager.register(tool); }
+  isConnected() { return this.wsClient.isConnected(); }
+}
+
+/**
+ * createAgent(config)            → AgentHost
+ * createAgentPool([cfg, ...])    → ConnectionPool (lazy fleet, async-loaded)
+ */
+export function createAgent(options: AgentHostOptions | AgentConfig = {}): AgentHost {
+  return new AgentHost(options as AgentHostOptions);
+}
+
+export async function createAgentPool(
+  configs: AgentHostOptions[] | AgentConfig[],
+  opts: { poolOptions?: { maxActive?: number; idleTimeoutMs?: number } } = {},
+): Promise<unknown> {
+  const ConnectionPool = await loadConnectionPool();
+  const pool = new ConnectionPool(opts.poolOptions);
+  (pool as { register: (configs: unknown[]) => void }).register(configs);
+  return pool;
+}
+
+export default AgentHost;

package/src/adapters/OpenAIAdapter.ts

@@ -0,0 +1,125 @@
+import OpenAI from 'openai';
+import type { ToolDefinition } from '../tools/defineTool.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+interface ChatResult {
+  content: string | null;
+  tool_calls: OpenAI.Chat.ChatCompletionMessageToolCall[] | null;
+  message: OpenAI.Chat.ChatCompletionMessage;
+  usage: OpenAI.CompletionUsage | undefined;
+}
+
+interface AdapterOptions {
+  key?: string;
+  model?: string;
+}
+
+export class OpenAIAdapter {
+  private client: OpenAI;
+  model: string;
+
+  constructor({ key, model = 'gpt-5.4' }: AdapterOptions) {
+    this.client = new OpenAI({ apiKey: key });
+    this.model = model;
+  }
+
+  async chat(
+    prompt: string,
+    tools: ToolDefinition[] = [],
+    temperature = 0.2,
+    systemHints: OpenAI.Chat.ChatCompletionMessageParam[] = [],
+    options: Record<string, unknown> = {},
+  ): Promise<ChatResult> {
+    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+      { role: 'system', content: 'Respond with valid JSON.' },
+      ...systemHints,
+      { role: 'user', content: prompt },
+    ];
+    return this.chatMessages(messages, tools, { ...options, temperature });
+  }
+
+  async chatMessages(
+    messages: OpenAI.Chat.ChatCompletionMessageParam[],
+    tools: ToolDefinition[] = [],
+    options: Record<string, unknown> = {},
+  ): Promise<ChatResult> {
+    const openAITools: OpenAI.Chat.ChatCompletionTool[] | undefined = tools.length > 0
+      ? tools.map(t => {
+          const fn = (t.schema.function || t.schema) as Record<string, unknown>;
+          const tAny = t as unknown as Record<string, unknown>;
+          const usageWhen = tAny['usage']
+            ? ` Use when: ${(tAny['usage'] as Record<string, unknown>)['when']}`
+            : '';
+          return {
+            type: 'function' as const,
+            function: {
+              name: fn['name'] as string,
+              description: ((fn['description'] as string) || '') + usageWhen,
+              parameters: fn['parameters'] as Record<string, unknown>,
+            },
+          };
+        })
+      : undefined;
+
+    try {
+      const { usage: _u, ...restOptions } = options as Record<string, unknown>;
+      // Verbose LLM request/response logging — commented out to reduce log noise.
+      // Re-enable by uncommenting to see full prompt/output blocks per LLM call.
+      // const divider = '─'.repeat(80);
+      // console.log(`\n${divider}`);
+      // console.log(`📤 LLM REQUEST → ${this.model}  (${messages.length} msg${messages.length === 1 ? '' : 's'})`);
+      // console.log(divider);
+      // for (const m of messages) {
+      //   const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+      //   const len = content?.length ?? 0;
+      //   console.log(`\n[${m.role.toUpperCase()}]  ${len} chars`);
+      //   console.log(content ?? '');
+      // }
+      // console.log(`${divider}\n`);
+      const res = await this.client.chat.completions.create({
+        model: this.model,
+        messages,
+        stream: false,
+        max_completion_tokens: 3000,
+        response_format: openAITools ? undefined : ((restOptions['response_format'] as OpenAI.ResponseFormatJSONObject) ?? { type: 'json_object' }),
+        ...(openAITools && { tools: openAITools }),
+        ...restOptions,
+      } as OpenAI.Chat.ChatCompletionCreateParamsNonStreaming);
+
+      const msg = res.choices[0].message;
+      const content = msg.content?.trim() ?? null;
+      const toolCalls = msg.tool_calls?.length ? msg.tool_calls : null;
+      // Verbose LLM response logging — commented out to reduce log noise.
+      // console.log(`\n${divider}`);
+      // console.log(`📥 LLM RESPONSE ← ${this.model}`);
+      // console.log(divider);
+      // if (content) {
+      //   console.log(`\n[CONTENT]  ${content.length} chars`);
+      //   console.log(content);
+      // }
+      // if (toolCalls) {
+      //   console.log(`\n[TOOL CALLS]  ${toolCalls.length}`);
+      //   for (const tc of toolCalls) {
+      //     console.log(`  → ${tc.function.name}(${tc.function.arguments})`);
+      //   }
+      // }
+      // if (!content && !toolCalls) console.log('\n(no content, no tool calls)');
+      // console.log(`${divider}\n`);
+      return {
+        content,
+        tool_calls: toolCalls,
+        message: msg,
+        usage: res.usage,
+      };
+    } catch (error) {
+      const err = error as Error & { status?: number; code?: string };
+      runtimeLog.error('OpenAIAdapter', `LLM API call failed: ${err.message}`, {
+        model: this.model,
+        error: err.message,
+        status: err.status || 'unknown',
+        code: err.code || 'unknown',
+      });
+      throw error;
+    }
+  }
+}

package/src/agent/Agent.ts

@@ -0,0 +1,98 @@
+import type { Ctx, Identity, Workflow, EffectHandler } from '../types.js';
+import { AgentMachine } from '../runtime/AgentMachine.js';
+import { runTurn } from '../runtime/runTurn.js';
+import { PromptBuilder } from '../runtime/PromptBuilder.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type { RawEvent } from '../runtime/buildOutcome.js';
+
+export interface AgentOptions {
+  workflow: Workflow;
+  toolManager: ToolManager;
+  promptBuilder?: PromptBuilder;
+}
+
+export interface TickInput {
+  /** Wire event (already normalized: a `message` or `task_result`-style envelope). */
+  event: unknown;
+  /** Server-provided per-session state. Omit on the first tick — a fresh ctx is constructed. */
+  ctx?: Ctx;
+  /** Server-provided workflow state name. Omit on the first tick — defaults to `workflow.initial`. */
+  state?: string;
+  /** Who am I and what session am I running in. The Agent carries this through Ctx. */
+  identity: Identity;
+  /** The single side channel for I/O — LLM, context, tools, send, record. */
+  eff: EffectHandler;
+  /**
+   * Agent-private long-term memory. Operator-provided (default
+   * `InMemoryStore` when omitted by `AgentHost`). Key shape is the agent's
+   * choice — `counterparty:<id>`, `agreement:<id>:notes`, etc.
+   */
+  memory?: MemoryStore;
+}
+
+export interface TickOutput {
+  /** Updated ctx — Server persists this against the session. */
+  ctx: Ctx;
+  /** Workflow state name after the tick — Server persists this against the session. */
+  state: string;
+  /** Whether the machine settled at a parked state. */
+  parked: boolean;
+  /** Accumulated LLM call count and token usage for this tick. */
+  metrics: { llmCalls: number; tokens: { total: number; input: number; output: number } };
+}
+
+/**
+ * Pure agent: workflow definition + cognition machinery. No I/O, no transport,
+ * no services. The Agent's only side channel is the `eff` handler it receives
+ * on each `tick`. Server-side state (sessions, lanes, queue, outbox) lives in
+ * `AgentHost` — not here.
+ *
+ * The contract:
+ *
+ *   `tick({ event, ctx, state, identity, eff })` →
+ *   `{ ctx, state, parked }`
+ *
+ * Reads top-to-bottom like a synchronous function. Every `await eff(...)`
+ * inside the cognition core is a yield to the Server, which performs the
+ * impure operation and resumes the Agent with the result.
+ */
+export class Agent {
+  workflow: Workflow;
+  toolManager: ToolManager;
+  promptBuilder: PromptBuilder;
+
+  constructor({ workflow, toolManager, promptBuilder }: AgentOptions) {
+    if (!workflow?.states) throw new Error('Agent: workflow with states is required');
+    if (!toolManager) throw new Error('Agent: toolManager is required');
+    this.workflow = workflow;
+    this.toolManager = toolManager;
+    this.promptBuilder = promptBuilder || new PromptBuilder();
+  }
+
+  async tick({ event, ctx, state, identity, eff, memory }: TickInput): Promise<TickOutput> {
+    if (!identity?.sessionId) throw new Error('Agent.tick: identity.sessionId is required');
+    if (!eff) throw new Error('Agent.tick: eff is required');
+
+    const machine = new AgentMachine({
+      workflow: this.workflow,
+      executionCore: runTurn,
+      eff,
+      toolManager: this.toolManager,
+      promptBuilder: this.promptBuilder,
+      memory,
+      input: { identity, ctx, state },
+    });
+
+    // `send` awaits the recursive _step until the machine settles at a
+    // parked state (or stops). When it returns, we have the final state.
+    await machine.send({ event: event as RawEvent | undefined, identity });
+
+    return {
+      ctx: machine.ctx,
+      state: machine.state,
+      parked: machine.isParked,
+      metrics: { llmCalls: machine.llmCalls, tokens: machine.tokens },
+    };
+  }
+}