@ziggs-ai/agent-sdk 0.1.11 → 0.2.0

package/src/AgentHost.ts

@@ -1,545 +0,0 @@
-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';
-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 { AnthropicAdapter } from './adapters/AnthropicAdapter.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;
-  anthropicKey?: 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 model = (options.services?.llm as { model?: string } | undefined)?.model || options.model;
-  const llm = isLlmAdapter(options.services?.llm)
-    ? options.services!.llm as LlmAdapter
-    : model?.startsWith('claude')
-      ? new AnthropicAdapter({ key: options.anthropicKey, model })
-      : new OpenAIAdapter({ key: options.openaiKey, model });
-  const operatorKey = options.operatorKey!;
-  const agentId = options.agentId!;
-  const messagesClient = new MessagesClient(operatorKey, agentId);
-  const artifactsClient = new ArtifactsClient(operatorKey, agentId);
-  const scopeClient = new ScopeClient(operatorKey, agentId);
-  const 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 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 || '',
-      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 (!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');
-  }
-
-  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.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>));
-
-    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;
-
-    // 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) {
-      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: 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),
-        ),
-      ]);
-      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}`);
-        });
-      }
-
-      // 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;
-    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.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); }
-  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;