@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/runtime/validateWorkflow.ts

@@ -0,0 +1,165 @@
+import type { Ctx, OutcomeKind, Workflow, ThinkingState } from '../types.js';
+
+const PROBE_CTX: Ctx = {
+  identity: { agentId: '', sessionId: '', laneKey: '' },
+  activeAgreementId: null,
+  activeTaskId: null,
+  pendingProposalAgreementId: null,
+  delegatedAgreementIds: [],
+  delegatedTaskIds: [],
+  toolResults: [],
+  lastOutcome: { kind: 'enter' },
+};
+
+const KNOWN_OUTCOME_KINDS = new Set<OutcomeKind>([
+  'enter',
+  'wait',
+  'timeout',
+  'message-sent',
+  'message-received',
+  'task-assigned',
+  'task-delegated',
+  'task-closed',
+  'subtask-finished',
+  'proposal-made',
+  'proposal-resolved',
+  'tool-result',
+  'error',
+  'extension',
+]);
+
+export class WorkflowValidationError extends Error {
+  readonly issues: string[];
+  constructor(issues: string[]) {
+    super(`Workflow validation failed:\n  - ${issues.join('\n  - ')}`);
+    this.name = 'WorkflowValidationError';
+    this.issues = issues;
+  }
+}
+
+export interface ValidationResult {
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Synchronous structural validation. Errors throw; warnings are returned for
+ * the caller to log. defineAgent runs this on construction, so misconfigured
+ * workflows fail loudly at load instead of mysteriously misbehaving at runtime.
+ */
+export function validateWorkflow(workflow: Workflow): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!workflow || typeof workflow !== 'object') {
+    throw new WorkflowValidationError(['workflow must be an object']);
+  }
+  if (!workflow.id) errors.push('workflow.id is required');
+  if (!workflow.initial) errors.push('workflow.initial is required');
+  if (!workflow.states || typeof workflow.states !== 'object') {
+    errors.push('workflow.states is required');
+  }
+
+  if (errors.length) throw new WorkflowValidationError(errors);
+
+  const stateNames = new Set(Object.keys(workflow.states));
+  if (!stateNames.has(workflow.initial)) {
+    errors.push(`workflow.initial "${workflow.initial}" is not a defined state`);
+  }
+
+  for (const [name, state] of Object.entries(workflow.states)) {
+    if (!state || typeof state !== 'object') {
+      errors.push(`state "${name}" is not an object`);
+      continue;
+    }
+    if (state.kind !== 'parked' && state.kind !== 'thinking') {
+      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking'`);
+      continue;
+    }
+
+    // Shape rejects mixing
+    if (state.kind === 'parked') {
+      if ((state as unknown as ThinkingState).prompt) {
+        errors.push(`state "${name}" is parked but has a prompt — parked states are event-driven only`);
+      }
+      if ((state as unknown as ThinkingState).actions) {
+        errors.push(`state "${name}" is parked but has actions — parked states are event-driven only`);
+      }
+    }
+    if (state.kind === 'thinking') {
+      if (!state.prompt) errors.push(`thinking state "${name}" requires a prompt`);
+      if (!state.actions || Object.keys(state.actions).length === 0) {
+        errors.push(`thinking state "${name}" requires at least one action`);
+      }
+    }
+
+    if (!Array.isArray(state.transitions)) {
+      errors.push(`state "${name}" requires a transitions array`);
+      continue;
+    }
+
+    for (let i = 0; i < state.transitions.length; i++) {
+      const t = state.transitions[i];
+      if (!t || typeof t !== 'object') {
+        errors.push(`state "${name}" transition[${i}] is not an object`);
+        continue;
+      }
+      if (typeof t.to !== 'string') {
+        errors.push(`state "${name}" transition[${i}] is missing string "to"`);
+        continue;
+      }
+      if (!stateNames.has(t.to)) {
+        errors.push(`state "${name}" transition[${i}] points to unknown state "${t.to}"`);
+      }
+      if (t.when !== undefined && typeof t.when !== 'function') {
+        errors.push(`state "${name}" transition[${i}].when must be a function or omitted`);
+      }
+    }
+
+    if (state.kind === 'thinking') {
+      for (const [actionName, action] of Object.entries(state.actions)) {
+        if (!action || typeof action !== 'object') {
+          errors.push(`state "${name}" action "${actionName}" is not an object`);
+          continue;
+        }
+        if (!action.prompt || !action.prompt.instruction) {
+          errors.push(`state "${name}" action "${actionName}" requires prompt.instruction`);
+        }
+        const p = action.produces;
+        if (typeof p === 'string') {
+          if (!KNOWN_OUTCOME_KINDS.has(p as OutcomeKind)) {
+            errors.push(
+              `state "${name}" action "${actionName}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`,
+            );
+          }
+        } else if (typeof p !== 'function') {
+          errors.push(`state "${name}" action "${actionName}" requires produces (OutcomeKind or fn)`);
+        }
+      }
+
+      // Soft check: thinking state should have a wait action and a fallthrough.
+      // Authors can opt out via allowNoWait when intentionally building a
+      // looping or always-progressing state.
+      if (!state.allowNoWait) {
+        if (!state.actions?.wait) {
+          warnings.push(
+            `thinking state "${name}" has no "wait" action — did you forget to spread thinkingDefaults({ initial: '${workflow.initial}' })? Set allowNoWait: true to silence.`,
+          );
+        }
+        const hasWaitFallthrough = state.transitions.some(t => {
+          if (!t.when) return true;
+          try { return t.when({ kind: 'wait' }, PROBE_CTX); }
+          catch { return false; }
+        });
+        if (!hasWaitFallthrough) {
+          warnings.push(
+            `thinking state "${name}" has no fallthrough for { kind: 'wait' } — agent may stall when LLM picks wait. Spread thinkingDefaults().transitions or add explicitly.`,
+          );
+        }
+      }
+    }
+  }
+
+  if (errors.length) throw new WorkflowValidationError(errors);
+  return { errors, warnings };
+}

package/src/server/ConnectionPool.ts

@@ -0,0 +1,155 @@
+/**
+ * ConnectionPool — multi-agent fleet manager.
+ *
+ * Holds N `AgentHostOptions` configs but only constructs/wakes an
+ * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
+ * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
+ * eviction drops the oldest if the cap is reached. With `startControl`, a
+ * separate "launcher" socket receives backend-driven wake hints so the pool
+ * spins up the right host on demand.
+ *
+ * This is how a single Node process serves a fleet of agents without
+ * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
+ */
+import { ConnectionManager } from '@ziggs-ai/api-client';
+import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+// Inlined from api-client (not re-exported there). Sync if the upstream
+// types change.
+interface ConnectionManagerMeta {
+  domain?: string;
+  expertise?: string[];
+  tags?: string[];
+  [key: string]: unknown;
+}
+
+interface QueryFilter {
+  domain?: string;
+  expertise?: string[];
+  tags?: string[];
+}
+
+export interface PoolOptions {
+  maxActive?: number;
+  idleTimeoutMs?: number;
+}
+
+export interface SendToOptions {
+  timeoutMs?: number;
+}
+
+export interface ControlOptions {
+  wsUrl?: string;
+  operatorKey?: string;
+}
+
+export class ConnectionPool {
+  private readonly manager: ConnectionManager;
+  private readonly configs = new Map<string, AgentHostOptions>();
+
+  constructor({ maxActive = 50, idleTimeoutMs = 60_000 }: PoolOptions = {}) {
+    this.manager = new ConnectionManager({ maxActive, idleTimeoutMs });
+  }
+
+  /**
+   * Register N agent configs. Each will be lazily woken (a fresh
+   * `AgentHost` constructed + connected) the first time it's referenced.
+   */
+  register(configs: AgentHostOptions[], metaArr: ConnectionManagerMeta[] = []): void {
+    const metaByAgentId = new Map<string, ConnectionManagerMeta>();
+    for (const m of metaArr) {
+      const id = m['agentId'] as string | undefined;
+      if (id) metaByAgentId.set(id, m);
+    }
+    for (const config of configs) {
+      const agentId = config.agentId ?? config.workflow?.id;
+      if (!agentId) {
+        runtimeLog.warn('ConnectionPool', 'skipping config with no resolvable agentId');
+        continue;
+      }
+      this.configs.set(agentId, config);
+      this.manager.register(
+        agentId,
+        async () => {
+          const host = new AgentHost(this.configs.get(agentId)!);
+          await host.connectAsync();
+          runtimeLog.debug(
+            'ConnectionPool',
+            `woke "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`,
+          );
+          return host;
+        },
+        async (host) => {
+          (host as AgentHost).disconnect();
+          runtimeLog.debug('ConnectionPool', `slept "${agentId}"`);
+        },
+        metaByAgentId.get(agentId),
+      );
+    }
+  }
+
+  async wake(agentId: string): Promise<AgentHost> {
+    return await this.manager.wake(agentId) as AgentHost;
+  }
+
+  async sleep(agentId: string): Promise<void> {
+    return this.manager.sleep(agentId);
+  }
+
+  async disconnectAll(): Promise<void> {
+    return this.manager.sleepAll();
+  }
+
+  /**
+   * Wake the named agent and deliver one wire frame to it. Returns once the
+   * host has finished processing.
+   *
+   * Note: does not return the agent's response. Capturing responses
+   * synchronously required internal-buffer poking the Agent/Server split
+   * removed. For request/response semantics, run the agent under an
+   * AgentHost with an injected EffectHandler that records sends.
+   */
+  async sendTo(agentId: string, text: string, metadata: Record<string, unknown> = {}, { timeoutMs = 30_000 }: SendToOptions = {}): Promise<null> {
+    const host = await this.wake(agentId);
+    const timeoutPromise = new Promise<never>((_, reject) =>
+      setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs),
+    );
+    await Promise.race([host.handleMessage(text, metadata), timeoutPromise]);
+    this.manager.touch(agentId);
+    return null;
+  }
+
+  /**
+   * Open a launcher (control) socket that the backend uses to push wake
+   * hints for any of the registered agents. Pool spins up the right host
+   * lazily when a hint arrives.
+   */
+  startControl({ wsUrl, operatorKey }: ControlOptions = {}): void {
+    if (!wsUrl || !operatorKey) {
+      runtimeLog.warn(
+        'ConnectionPool',
+        'startControl: wsUrl and operatorKey are required — skipping',
+      );
+      return;
+    }
+    // ConnectionManager only accepts `control` at construction; mutating its
+    // private field is the smallest way to add it later. (Cleaner fix lives
+    // in api-client: expose a `setControl` setter.)
+    (this.manager as unknown as Record<string, unknown>)['_controlOpts'] = { wsUrl, operatorKey };
+    this.manager.start();
+  }
+
+  stopControl(): void {
+    const m = this.manager as unknown as Record<string, unknown>;
+    (m['_controlHandle'] as { close?: () => void } | null)?.close?.();
+    m['_controlHandle'] = null;
+  }
+
+  query(filter: QueryFilter): string[] { return this.manager.query(filter); }
+  list(): string[] { return this.manager.list(); }
+  listActive(): string[] { return this.manager.listActive(); }
+  get size(): number { return this.manager.size; }
+  get maxActive(): number { return (this.manager as unknown as { maxActive: number }).maxActive; }
+  getMeta(id: string): ConnectionManagerMeta | undefined { return this.manager.getMeta(id); }
+}

package/src/server/EventQueue.ts

@@ -0,0 +1,119 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export type ProcessEventFn = (event: unknown, laneKey: string) => Promise<void>;
+
+interface QueuedEntry {
+  event: unknown;
+  resolve: () => void;
+}
+
+interface LaneState {
+  events: QueuedEntry[];
+  processing: boolean;
+}
+
+interface QueueMetrics {
+  enqueued: number;
+  dropped: number;
+  processedBatches: number;
+  processedEvents: number;
+  errors: number;
+}
+
+export interface EventQueueOptions {
+  maxQueueLengthPerLane?: number;
+}
+
+/**
+ * Serializes events per lane and coalesces multiple queued events into one
+ * batch dispatch. The runtime sees at most one in-flight processEvent call
+ * per laneKey at a time; multiple events arriving while busy are merged
+ * into a single { type: 'batch', events: [...] } frame on the next pass.
+ */
+export class EventQueue {
+  private _processEvent: ProcessEventFn;
+  private _maxQueueLengthPerLane: number;
+  private _state: Map<string, LaneState> = new Map();
+  private _metrics: QueueMetrics = {
+    enqueued: 0, dropped: 0, processedBatches: 0, processedEvents: 0, errors: 0,
+  };
+
+  constructor(processEventFn: ProcessEventFn, options: EventQueueOptions = {}) {
+    this._processEvent = processEventFn;
+    this._maxQueueLengthPerLane = Number.isFinite(options.maxQueueLengthPerLane)
+      ? Math.max(1, options.maxQueueLengthPerLane!)
+      : 100;
+  }
+
+  enqueue(event: unknown, laneKey: string): Promise<void> {
+    if (!laneKey) {
+      runtimeLog.warn('EventQueue', 'enqueue called without laneKey, skipping');
+      return Promise.resolve();
+    }
+
+    let state = this._state.get(laneKey);
+    if (!state) {
+      state = { events: [], processing: false };
+      this._state.set(laneKey, state);
+    }
+
+    return new Promise<void>((resolve) => {
+      this._metrics.enqueued += 1;
+      state!.events.push({ event, resolve });
+      this._trimQueueIfNeeded(state!, laneKey);
+      this._processIfNeeded(laneKey);
+    });
+  }
+
+  private _processIfNeeded(laneKey: string): void {
+    const state = this._state.get(laneKey);
+    if (!state || state.processing || state.events.length === 0) return;
+    state.processing = true;
+    this._processLoop(laneKey);
+  }
+
+  private async _processLoop(laneKey: string): Promise<void> {
+    const state = this._state.get(laneKey);
+    if (!state) return;
+
+    while (state.events.length > 0) {
+      const batch = state.events.splice(0, state.events.length);
+      const events = batch.map(e => e.event);
+      const resolvers = batch.map(e => e.resolve);
+
+      const coalesced = events.length === 1
+        ? events[0]
+        : { type: 'batch', events };
+
+      try {
+        await this._processEvent(coalesced, laneKey);
+      } catch (error: unknown) {
+        this._metrics.errors += 1;
+        runtimeLog.error('EventQueue', `processEvent error for laneKey=${laneKey}: ${(error as Error)?.message || error}`);
+      }
+      this._metrics.processedBatches += 1;
+      this._metrics.processedEvents += events.length;
+
+      for (const r of resolvers) r();
+    }
+
+    state.processing = false;
+  }
+
+  private _trimQueueIfNeeded(state: LaneState, laneKey: string): void {
+    while (state.events.length > this._maxQueueLengthPerLane) {
+      const dropped = state.events.shift();
+      this._metrics.dropped += 1;
+      dropped?.resolve();
+      runtimeLog.warn('EventQueue', `dropped oldest event laneKey=${laneKey} max=${this._maxQueueLengthPerLane}`);
+    }
+  }
+
+  getMetrics() {
+    return {
+      ...this._metrics,
+      lanes: this._state.size,
+      queuedEvents: [...this._state.values()].reduce((sum, lane) => sum + lane.events.length, 0),
+    };
+  }
+}

package/src/server/OutboxBuffer.ts

@@ -0,0 +1,90 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+interface PendingMessage {
+  text: string;
+  receiverId: string;
+  timestamp: number;
+}
+
+export interface OutboxBufferOptions {
+  ttlMs?: number;
+}
+
+interface HistoryEntryShape {
+  entryType?: string;
+  text?: string;
+  sender?: { id?: string; type?: string };
+  receiver?: { id?: string };
+  timestamp?: number;
+}
+
+/**
+ * Tracks outbound messages locally until server history syncs them, then
+ * merges any unmatched ones into the next read context. Prevents the LLM
+ * from re-saying things it already said when the server is slow to publish.
+ */
+export class OutboxBuffer {
+  private _pending: Map<string, PendingMessage[]> = new Map();
+  private _ttlMs: number;
+
+  constructor(options: OutboxBufferOptions = {}) {
+    this._ttlMs = Number.isFinite(options.ttlMs) ? Math.max(1_000, options.ttlMs!) : 10 * 60 * 1000;
+  }
+
+  track(chatId: string, msg: { text: string; receiverId: string }): void {
+    this._gcChat(chatId);
+    if (!this._pending.has(chatId)) this._pending.set(chatId, []);
+    this._pending.get(chatId)!.push({ text: msg.text, receiverId: msg.receiverId, timestamp: Date.now() });
+  }
+
+  merge(chatId: string, history: HistoryEntryShape[], agentId: string | null): void {
+    this._gcChat(chatId);
+    const pending = this._pending.get(chatId);
+    if (!pending || pending.length === 0) return;
+
+    const matchedIndices = new Set<number>();
+    const remaining: PendingMessage[] = [];
+
+    for (const msg of pending) {
+      const matchIdx = history.findIndex((entry, idx) =>
+        !matchedIndices.has(idx) &&
+        entry.text === msg.text &&
+        entry.sender?.id === agentId,
+      );
+      if (matchIdx !== -1) matchedIndices.add(matchIdx);
+      else remaining.push(msg);
+    }
+
+    for (const msg of remaining) {
+      history.push({
+        entryType: 'message',
+        text: msg.text,
+        sender: { id: agentId || undefined, type: 'agent' },
+        receiver: { id: msg.receiverId },
+        timestamp: msg.timestamp,
+      });
+    }
+
+    if (remaining.length === 0) this._pending.delete(chatId);
+    else this._pending.set(chatId, remaining);
+  }
+
+  gc(): void {
+    for (const chatId of this._pending.keys()) this._gcChat(chatId);
+  }
+
+  private _gcChat(chatId: string): void {
+    const pending = this._pending.get(chatId);
+    if (!pending?.length) return;
+    const cutoff = Date.now() - this._ttlMs;
+    const fresh = pending.filter(msg => msg.timestamp >= cutoff);
+    if (fresh.length === 0) {
+      this._pending.delete(chatId);
+      runtimeLog.warn('OutboxBuffer', `expired all pending messages chatId=${chatId}`);
+      return;
+    }
+    if (fresh.length !== pending.length) {
+      this._pending.set(chatId, fresh);
+    }
+  }
+}