@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/README.md

@@ -62,7 +62,9 @@ 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`
+- **Tools come in two tiers — single home: `server/tools/`:**
+  - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
+  - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **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.5",
   "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.9",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0"

package/src/AgentHost.ts

@@ -0,0 +1,495 @@
+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';
+
+/**
+ * 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 { PROTOCOL_TOOLS } from './server/tools/tier1/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 { runInboxCatchUp } from './server/InboxCatchUp.js';
+import { SeenMessages } from './server/SeenMessages.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 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;
+  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;
+  /**
+   * 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;
+  /** 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;
+}
+
+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 isLlmAdapter(v: unknown): v is LlmAdapter {
+  return typeof v === 'object' && v !== null && typeof (v as LlmAdapter).chatMessages === 'function';
+}
+
+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 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 | LlmAdapter;  // 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;
+  private sessionStore: SessionStore | null;
+  private taskService!: TaskService;
+  private agreementService!: AgreementService;
+  private messageSender!: (message: string, receiverId: string, sessionId: string) => Promise<unknown>;
+  private seenMessages = new SeenMessages();
+  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',
+      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,
+      effectTap: options.effectTap,
+      transitionTap: options.transitionTap,
+      inboxCatchUp: options.inboxCatchUp,
+    } as Required<Pick<AgentHostOptions, 'agentId' | 'operatorKey' | 'openaiKey'>> & AgentHostOptions;
+    this.inboxCatchUpEnabled = options.inboxCatchUp !== false;
+    this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
+    this.tickTimeoutMs = options.tickTimeoutMs ?? 120_000;
+    this.memory = options.memory ?? new InMemoryStore();
+    this.sessionStore = options.sessionStore ?? null;
+    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, messageId?: string): Promise<unknown> => {
+      this.wsClient.send(sessionId, receiverId, message, messageId ? { messageId } : undefined);
+      return Promise.resolve(undefined);
+    };
+    const chunkSender = (sessionId: string, receiverId: string, text: string, messageId: string): void => {
+      this.wsClient.send(sessionId, receiverId, text, { partial: true, messageId });
+    };
+    this.taskService = services.taskService;
+    this.agreementService = services.agreementService;
+    this.messageSender = messageSender;
+
+    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,
+      chunkSender,
+      toolManager: services.toolManager,
+      operatorKey: this.options.operatorKey!,
+      agentId: this.options.agentId!,
+      telemetryClient: services.telemetryClient,
+      telemetryIngest: this.options.telemetryIngest,
+      effectTap: this.options.effectTap,
+    });
+
+    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>));
+
+    if (this.inboxCatchUpEnabled) {
+      this.wsClient.onConnect(() => {
+        void this._ensureCatchUp();
+      });
+    }
+  }
+
+  /**
+   * Coalesce concurrent connect/reconnect bursts into one catch-up pass.
+   */
+  private _ensureCatchUp(): Promise<void> {
+    if (!this.catchUpInFlight) {
+      this.catchUpInFlight = this._runInboxCatchUp().finally(() => {
+        this.catchUpInFlight = null;
+      });
+    }
+    return this.catchUpInFlight;
+  }
+
+  private async _runInboxCatchUp(): Promise<void> {
+    const label = this.options.name || 'agent';
+    try {
+      await runInboxCatchUp({
+        creds: {
+          operatorKey: this.options.operatorKey!,
+          agentId: this.options.agentId!,
+        },
+        ownAgentId: this.options.agentId!,
+        baseUrl: this.options.wsUrl ? undefined : undefined,
+        seen: this.seenMessages,
+        label,
+        onMessage: (text, metadata) => this.handleMessage(text, metadata),
+        onResourceEvent: (event) => this.handleResourceEvent(event),
+      });
+    } catch (err: unknown) {
+      runtimeLog.warn(
+        label,
+        `inbox catch-up failed: ${(err as Error)?.message ?? err}`,
+      );
+    }
+  }
+
+  /**
+   * 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 messageId = metadata.messageId as string | undefined;
+    if (messageId && this.seenMessages.has(messageId)) {
+      runtimeLog.debug('AgentHost', `skip duplicate messageId=${messageId}`);
+      return;
+    }
+    if (messageId) this.seenMessages.mark(messageId);
+
+    const ownAgentId = this._resolveOwnAgentId(metadata);
+    if (!ownAgentId) {
+      runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
+      return;
+    }
+
+    let enrichedText = typeof text === 'string' ? text : '';
+    if (!enrichedText.trim()) {
+      const agreement = metadata.agreement as Record<string, unknown> | undefined;
+      const terms = agreement?.terms as { description?: string } | undefined;
+      if (terms?.description) {
+        enrichedText = String(terms.description);
+      }
+    }
+
+    const normalized = normalizeIncomingEvent({ text: enrichedText, metadata, ownAgentId });
+    if (!normalized.shouldProcess) {
+      const receiverId = (metadata.receiver as Record<string, unknown> | undefined)?.id ?? metadata.receiverId;
+      runtimeLog.warn('AgentHost', `skip reason=${normalized.reason || 'not_relevant'} ownAgentId=${ownAgentId} receiverId=${receiverId ?? 'null'} chatId=${normalized.chatId ?? 'null'}`);
+      return;
+    }
+
+    const sessionId = this.sessionResolver(normalized, ownAgentId);
+    if (!sessionId) {
+      runtimeLog.warn('AgentHost', `session resolver returned null ownAgentId=${ownAgentId} chatId=${normalized.chatId ?? 'null'}`);
+      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;
+
+    // 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) {
+      try {
+        const persisted = await this.sessionStore.load(laneKey);
+        if (persisted) {
+          session.ctx = persisted.ctx;
+          session.state = persisted.state;
+        }
+      } catch (err: unknown) {
+        runtimeLog.warn('AgentHost', `sessionStore.load failed laneKey=${laneKey}: ${(err as Error)?.message || err}`);
+      }
+    }
+
+    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, transitionTap: this.options.transitionTap }),
+        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);
+
+      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}`);
+        });
+      }
+    } 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;
+  }
+
+  async connectAsync(timeout?: number) {
+    await this.wsClient.connectAsync(timeout);
+    if (this.inboxCatchUpEnabled) {
+      await this._ensureCatchUp();
+      // Backend flushPendingMessages can emit after auth; re-poll once so inbox
+      // ack catches stragglers and we don't leave newMessages > 0 (ZIG-462).
+      await new Promise((r) => setTimeout(r, 750));
+      this.catchUpInFlight = null;
+      await this._ensureCatchUp();
+    }
+    return this;
+  }
+  disconnect() { 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); }
+  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,146 @@
+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;
+    }
+  }
+
+  async chatMessagesStream(
+    messages: OpenAI.Chat.ChatCompletionMessageParam[],
+    onChunk: (text: string) => void,
+  ): Promise<string> {
+    const stream = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      stream: true,
+      max_completion_tokens: 3000,
+    });
+    let text = '';
+    for await (const chunk of stream) {
+      const delta = chunk.choices[0]?.delta?.content;
+      if (delta) {
+        text += delta;
+        onChunk(delta);
+      }
+    }
+    return text;
+  }
+}