@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/runtime/validateWorkflow.ts

@@ -0,0 +1,181 @@
+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.`,
+          );
+        }
+        const hasErrorFallthrough = state.transitions.some(t => {
+          if (!t.when) return true;
+          try {
+            return t.when(
+              { kind: 'error', source: 'unknown', cause: 'probe', retryable: false },
+              PROBE_CTX,
+            );
+          } catch {
+            return false;
+          }
+        });
+        if (!hasErrorFallthrough) {
+          warnings.push(
+            `thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard (ZIG-303). Add an error transition or spread thinkingDefaults().transitions.`,
+          );
+        }
+      }
+    }
+  }
+
+  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,133 @@
+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}`);
+    }
+  }
+
+  get isIdle(): boolean {
+    return [...this._state.values()].every(s => !s.processing && s.events.length === 0);
+  }
+
+  /** Resolves when all lanes finish processing, or after timeoutMs. Best-effort — never throws. */
+  async waitForIdle(timeoutMs = 30_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (this.isIdle) return;
+      await new Promise<void>(r => setTimeout(r, 50));
+    }
+    runtimeLog.warn('EventQueue', `waitForIdle timed out after ${timeoutMs}ms`);
+  }
+
+  getMetrics() {
+    return {
+      ...this._metrics,
+      lanes: this._state.size,
+      queuedEvents: [...this._state.values()].reduce((sum, lane) => sum + lane.events.length, 0),
+    };
+  }
+}