@ziggs-ai/agent-sdk 0.1.12 → 0.2.1

package/src/runtime/validateWorkflow.ts

@@ -1,221 +0,0 @@
-import type { Ctx, OutcomeKind, Workflow, ThinkingState, ParkedState, MechanicalState } from '../types.js';
-import { bootstrapCtx } from './bootstrapCtx.js';
-
-/** Static probe ctx for evaluating transition `when` guards during validation. */
-export const PROBE_CTX: Ctx = bootstrapCtx({ agentId: '', sessionId: '', laneKey: '' });
-
-// 'state-timeout' is intentionally absent: it is a runtime-generated liveness
-// outcome, never something an action's `produces` may declare.
-const KNOWN_OUTCOME_KINDS = new Set<OutcomeKind>([
-  'enter',
-  'wait',
-  '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' && state.kind !== 'mechanical') {
-      errors.push(`state "${name}" must declare kind: 'parked' | 'thinking' | 'mechanical'`);
-      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`);
-      }
-      const tm = (state as ParkedState).timeoutMs;
-      if (tm !== undefined && (typeof tm !== 'number' || !Number.isFinite(tm) || tm <= 0)) {
-        errors.push(`state "${name}" timeoutMs must be a finite number > 0 (got ${String(tm)})`);
-      }
-      if (typeof tm === 'number' && Number.isFinite(tm) && tm > 0) {
-        const handled = state.transitions.some(t => {
-          if (!t.when) return true;
-          try { return t.when({ kind: 'state-timeout', state: name, waitedMs: tm }, PROBE_CTX); }
-          catch { return false; }
-        });
-        if (!handled) {
-          warnings.push(`parked state "${name}" declares timeoutMs=${tm} but no transition matches { kind: 'state-timeout' } — the timeout will park loudly (runtimeLog.error) instead of routing to a recovery state.`);
-        }
-      }
-    }
-    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 ((state as unknown as ParkedState).timeoutMs !== undefined) {
-        errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
-      }
-    }
-    if (state.kind === 'mechanical') {
-      const mech = state as MechanicalState;
-      if (!mech.tool || typeof mech.tool !== 'string') {
-        errors.push(`mechanical state "${name}" requires a tool name`);
-      }
-      if (mech.buildArgs !== undefined && typeof mech.buildArgs !== 'function') {
-        errors.push(`mechanical state "${name}" buildArgs must be a function`);
-      }
-      if ((mech as unknown as ThinkingState).prompt) {
-        errors.push(`state "${name}" is mechanical but has a prompt — use kind: 'thinking' instead`);
-      }
-      if ((mech as unknown as ThinkingState).actions) {
-        errors.push(`state "${name}" is mechanical but has actions — use kind: 'thinking' instead`);
-      }
-      const p = mech.produces;
-      if (p === 'state-timeout') {
-        errors.push(`mechanical state "${name}" produces "state-timeout" — reserved for runtime liveness timers`);
-      } else if (typeof p === 'string') {
-        if (!KNOWN_OUTCOME_KINDS.has(p as OutcomeKind)) {
-          errors.push(
-            `mechanical state "${name}" produces unknown outcome kind "${p}" — use one of: ${[...KNOWN_OUTCOME_KINDS].join(', ')}`,
-          );
-        }
-      } else if (typeof p !== 'function') {
-        errors.push(`mechanical state "${name}" requires produces (OutcomeKind or fn)`);
-      }
-    }
-
-    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 (p === 'state-timeout') {
-          errors.push(`state "${name}" action "${actionName}" produces "state-timeout" — reserved for runtime liveness timers; actions cannot produce it`);
-        } else 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. Add an error transition or spread thinkingDefaults().transitions.`,
-          );
-        }
-      }
-    }
-  }
-
-  if (errors.length) throw new WorkflowValidationError(errors);
-  return { errors, warnings };
-}

package/src/server/ConnectionPool.ts

@@ -1,206 +0,0 @@
-/**
- * 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>();
-  // Listeners enqueued by requestFrom — drained on outbound send-message effects.
-  private readonly responseListeners = new Map<string, Array<(text: string) => void>>();
-
-  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 cfg = this.configs.get(agentId)!;
-          const originalTap = cfg.effectTap;
-          const pool = this;
-          const host = new AgentHost({
-            ...cfg,
-            effectTap(effect, response) {
-              if (effect.kind === 'send-message') {
-                const listeners = pool.responseListeners.get(agentId);
-                if (listeners?.length) listeners.shift()!(effect.text ?? '');
-              }
-              originalTap?.(effect, response);
-            },
-          });
-          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, deliver a message, and wait for its first outbound
-   * `send-message` effect — i.e. the agent's reply. Returns the reply text.
-   *
-   * The effectTap injected in `register` drains a per-agent listener queue;
-   * this method enqueues one resolver and awaits it. Times out if the agent
-   * does not reply within `timeoutMs` (default 60 s for LLM agents).
-   */
-  async requestFrom(agentId: string, text: string, metadata: Record<string, unknown> = {}, { timeoutMs = 60_000 }: SendToOptions = {}): Promise<string> {
-    const host = await this.wake(agentId);
-    return new Promise<string>((resolve, reject) => {
-      let settled = false;
-      const timer = setTimeout(() => {
-        if (settled) return;
-        settled = true;
-        const ls = this.responseListeners.get(agentId);
-        if (ls) { const i = ls.indexOf(listener); if (i !== -1) ls.splice(i, 1); }
-        reject(new Error(`requestFrom timeout for "${agentId}" after ${timeoutMs}ms`));
-      }, timeoutMs);
-      const listener = (responseText: string) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        resolve(responseText);
-      };
-      const ls = this.responseListeners.get(agentId) ?? [];
-      ls.push(listener);
-      this.responseListeners.set(agentId, ls);
-      host.handleMessage(text, metadata).catch((err: unknown) => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        const ls2 = this.responseListeners.get(agentId);
-        if (ls2) { const i = ls2.indexOf(listener); if (i !== -1) ls2.splice(i, 1); }
-        reject(err);
-      });
-    });
-  }
-
-  /**
-   * 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. For request/response
-   * semantics use `requestFrom`.
-   */
-  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

@@ -1,133 +0,0 @@
-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),
-    };
-  }
-}