@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/runtime/AgentMachine.ts

@@ -0,0 +1,364 @@
+import type { Ctx, Outcome, Workflow, Identity, EffectHandler } from '../types.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { applyOutcomeToCtx, outcomeFromEvent, type RawEvent } from './buildOutcome.js';
+import type { runTurn as RunTurnFn } from './runTurn.js';
+import { PromptBuilder } from './PromptBuilder.js';
+import type { MemoryStore } from '../memory/MemoryStore.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+
+export interface MachineSnapshot {
+  value: string;
+  ctx: Ctx;
+  status: 'active' | 'stopped';
+}
+
+export type TransitionEvent =
+  | { kind: 'transition'; fromState: string; toState: string; outcomeKind: string; depth: number }
+  | { kind: 'no-match'; state: string; outcomeKind: string; depth: number }
+  | { kind: 'depth-guard'; state: string; depth: number }
+  | { kind: 'error-escape'; fromState: string; toState: string };
+
+interface MachineInput {
+  identity: Identity;
+  /** Server-provided ctx for an existing session. If omitted, a fresh ctx is built. */
+  ctx?: Ctx;
+  /** Server-provided state name for an existing session. Defaults to workflow.initial. */
+  state?: string;
+}
+
+interface MachineOptions {
+  workflow: Workflow;
+  executionCore: typeof RunTurnFn;
+  /** Side channel for all I/O. Provided by the Server. */
+  eff: EffectHandler;
+  /** Pure tool metadata (schemas, flags). Owned by the Agent. */
+  toolManager: ToolManager;
+  promptBuilder: PromptBuilder;
+  /** Agent-private long-term memory. Operator-provided. */
+  memory?: MemoryStore;
+  input: MachineInput;
+  /** Optional tap for FSM transition events — called synchronously on each transition. */
+  transitionTap?: (event: TransitionEvent) => void;
+}
+
+interface IncomingFrame {
+  event?: RawEvent;
+  identity?: Identity;
+}
+
+type Subscriber = (snapshot: MachineSnapshot) => void;
+
+/**
+ * Per-lane interpreter. Holds (current state name, Ctx). Re-entry is the
+ * single primitive: every external event and every turn produces exactly
+ * one Outcome that re-enters the current state.
+ *
+ * Parked states stop on entry. Thinking states run an LLM turn → produce an
+ * outcome → re-enter. Transitions are evaluated against the new outcome
+ * (first matching `when` wins; no `when` is fallthrough).
+ *
+ * `_running` guards against concurrent turns on the same machine — outer
+ * runtime is expected to serialize via EventQueue, but we belt-and-suspenders.
+ */
+export class AgentMachine {
+  workflow: Workflow;
+  executionCore: typeof RunTurnFn;
+  eff: EffectHandler;
+  toolManager: ToolManager;
+  promptBuilder: PromptBuilder;
+  memory?: MemoryStore;
+  state: string;
+  status: 'active' | 'stopped' = 'active';
+  ctx: Ctx;
+  _running = false;
+  _subscribers = new Set<Subscriber>();
+  _prevSnapshot: MachineSnapshot | null = null;
+  _pendingFrames: IncomingFrame[] = [];
+  _draining = false;
+  _llmCalls = 0;
+  _tokens = { total: 0, input: 0, output: 0 };
+  _lastUserSenderId: string | null = null;
+  _transitionTap: ((event: TransitionEvent) => void) | undefined;
+
+  get llmCalls(): number { return this._llmCalls; }
+  get tokens(): { total: number; input: number; output: number } { return this._tokens; }
+
+  constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap }: MachineOptions) {
+    this.workflow = workflow;
+    this.executionCore = executionCore;
+    this.eff = eff;
+    this.toolManager = toolManager;
+    this.promptBuilder = promptBuilder;
+    this.memory = memory;
+    this._transitionTap = transitionTap;
+    this.state = input.state || workflow.initial;
+    this.ctx = input.ctx
+      ? { ...input.ctx, identity: input.identity }
+      : {
+          identity: input.identity,
+          activeAgreementId: null,
+          activeTaskId: null,
+          pendingProposalAgreementId: null,
+          delegatedAgreementIds: [],
+          delegatedTaskIds: [],
+          toolResults: [],
+          lastOutcome: { kind: 'enter' },
+        };
+  }
+
+  getSnapshot(): MachineSnapshot {
+    return { value: this.state, ctx: this.ctx, status: this.status };
+  }
+
+  /** Parked = currently in a parked state and not executing a turn. */
+  get isParked(): boolean {
+    if (this._running) return false;
+    const sd = this.workflow.states[this.state];
+    return sd?.kind === 'parked';
+  }
+
+  subscribe(fn: Subscriber): { unsubscribe: () => void } {
+    this._subscribers.add(fn);
+    return { unsubscribe: () => this._subscribers.delete(fn) };
+  }
+
+  /**
+   * Process an incoming wire event: convert to outcome → apply to ctx →
+   * evaluate current state's transitions → re-enter or stop.
+   *
+   * Serialized via a single-slot queue: if a turn is already in flight, the
+   * frame is held until the running turn settles, then drained. Without this,
+   * an inbound event mid-turn re-entered _step with a stale state and a hot
+   * `_running=true`, which spawned overlapping turns and re-created the
+   * clarifyingDuringApproval feedback loop even after fixing the workflow
+   * fall-through (ZIG-181).
+   */
+  async send(frame: IncomingFrame): Promise<void> {
+    if (this.status !== 'active') return;
+    this._pendingFrames.push(frame);
+    if (this._draining) return;
+    this._draining = true;
+    try {
+      while (this._pendingFrames.length) {
+        const next = this._pendingFrames.shift()!;
+        await this._handleFrame(next);
+      }
+    } finally {
+      this._draining = false;
+    }
+  }
+
+  async _handleFrame(frame: IncomingFrame): Promise<void> {
+    if (this.status !== 'active') return;
+    if (frame.identity) this.ctx.identity = frame.identity;
+
+    const ev = frame.event;
+    this._lastIncomingEvent = ev ?? null;
+    if (ev?.senderId && String(ev?.senderType ?? '').toUpperCase() === 'USER') {
+      this._lastUserSenderId = String(ev.senderId);
+    }
+    runtimeLog.debug(
+      'FSM',
+      `_handleFrame ev.type=${ev?.type} ev.senderId=${ev?.senderId} ev.receiverId=${ev?.receiverId} myId=${this.ctx.identity?.agentId}`,
+    );
+    const outcome = outcomeFromEvent(ev, this.ctx.identity.agentId);
+
+    // `outcomeFromEvent` never returns null — it falls back to `{ kind: 'enter' }`
+    // when all events in a batch are no-ops (resource_changed, self-echo, etc.).
+    // If a real raw event produced `enter`, that means the event carried no
+    // meaningful signal for the FSM, so skip it entirely.  Without this guard
+    // `idle`'s unconditional `{ to: 'understanding' }` transition fires on every
+    // resource_changed wake-up, kicking off an LLM turn that sends a duplicate
+    // message, which triggers another resource_changed, and so on.
+    if (ev && outcome.kind === 'enter') return;
+
+    if (
+      outcome.kind === 'subtask-finished' &&
+      ev?.type === 'task_result' &&
+      ev?.result?.taskId &&
+      this.ctx.delegatedTaskIds.includes(ev.result.taskId)
+    ) {
+      // Already correctly classified — no override needed.
+    }
+
+    applyOutcomeToCtx(this.ctx, outcome);
+    await this._step(outcome);
+  }
+
+  async _step(outcome: Outcome, depth = 0): Promise<void> {
+    const fromState = this.state;
+    const target = this._evaluateTransitions(outcome);
+    const o = outcome as Record<string, unknown>;
+    runtimeLog.debug(
+      'FSM',
+      `_step from=${fromState} outcome.kind=${o?.kind} senderId=${o?.senderId ?? '<none>'} myId=${this.ctx.identity?.agentId ?? '<none>'} → target=${target ?? '(stay)'} depth=${depth}`,
+    );
+    if (target && target !== this.state) {
+      this._transitionTap?.({ kind: 'transition', fromState, toState: target, outcomeKind: (outcome as Record<string, unknown>).kind as string, depth });
+      this.state = target;
+      this._notify();
+    }
+
+    const sd = this.workflow.states[this.state];
+    if (!sd) return;
+    if (sd.kind === 'parked') {
+      runtimeLog.debug('FSM', `_step parked state=${this.state} — exit`);
+      // Notify so runtime detects park and resolves the wait promise.
+      this._notify();
+      return;
+    }
+
+    // A thinking turn that yields an outcome no transition handles must not
+    // silently re-enter the same state and burn another LLM call (ZIG-303).
+    // Explicit self-loops still match (target is non-null, even if target === state).
+    if (
+      sd.kind === 'thinking' &&
+      depth > 0 &&
+      fromState === this.state &&
+      !target
+    ) {
+      if (this._escapeToInitialParked(outcome, fromState)) return;
+      runtimeLog.warn(
+        'AgentMachine',
+        `state=${fromState} outcome.kind=${(outcome as Record<string, unknown>).kind} matched no transition; parking (depth=${depth})`,
+      );
+      this._transitionTap?.({ kind: 'no-match', state: fromState, outcomeKind: (outcome as Record<string, unknown>).kind as string, depth });
+      await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+      this._notify();
+      return;
+    }
+
+    // Recursion / runaway-turn guard. Without this, a thinking state whose
+    // transitions don't match the turn outcome (e.g. `delegating` not
+    // catching `tool-result` from an agent_network search) re-enters the
+    // same state forever — the LLM keeps re-rolling search/dummy actions
+    // until something accidentally matches, burning tokens and emitting
+    // duplicate side effects (ZIG-181: ziggs ran `discoverSpecialist` six
+    // times before finally invoking `delegate`). 12 is well above any
+    // legitimate same-state turn chain we exercise in tests; if we trip
+    // it, treat the state as wedged and park.
+    if (depth >= 12) {
+      runtimeLog.warn(
+        'AgentMachine',
+        `state=${this.state} runaway turn loop (depth=${depth}); parking`,
+      );
+      this._transitionTap?.({ kind: 'depth-guard', state: this.state, depth });
+      await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+      this._notify();
+      return;
+    }
+    runtimeLog.debug('FSM', `_step thinking state=${this.state} — run turn`);
+
+    // Thinking: run a turn, produce an outcome, re-step.
+    this._running = true;
+    try {
+      const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await this.executionCore({
+        stateId: this.state,
+        statePrompt: sd.prompt,
+        actions: sd.actions,
+        incomingEvent: this._lastIncomingEvent,
+        ctx: this.ctx,
+        eff: this.eff,
+        toolManager: this.toolManager,
+        promptBuilder: this.promptBuilder,
+        memory: this.memory,
+        definition: this.workflow,
+      });
+
+      this.ctx.toolResults = toolResults;
+      this._llmCalls += llmCalls;
+      this._tokens.total += tokens.total;
+      this._tokens.input += tokens.input;
+      this._tokens.output += tokens.output;
+      applyOutcomeToCtx(this.ctx, turnOutcome);
+      this._running = false;
+      this._notify();
+
+      await this._step(turnOutcome, depth + 1);
+    } catch (error: unknown) {
+      runtimeLog.error('AgentMachine', `state=${this.state} error: ${(error as Error)?.message || error}`);
+      const errOutcome: Outcome = {
+        kind: 'error',
+        source: 'unknown',
+        cause: (error as Error)?.message || String(error),
+        retryable: false,
+      };
+      applyOutcomeToCtx(this.ctx, errOutcome);
+      this._running = false;
+      this._notify();
+      // Try to fall through using current state's transitions; if none match
+      // the error outcome the machine just parks (next event will re-enter).
+      const fallback = this._evaluateTransitions(errOutcome);
+      if (fallback && fallback !== this.state) {
+        this.state = fallback;
+        this._notify();
+      } else {
+        await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+      }
+    }
+  }
+
+  /** Error with no author-defined escape: park at workflow.initial if it is parked. */
+  _escapeToInitialParked(outcome: Outcome, fromState: string): boolean {
+    if (outcome.kind !== 'error') return false;
+    const initial = this.workflow.initial;
+    const initialSd = this.workflow.states[initial];
+    if (!initialSd || initialSd.kind !== 'parked' || initial === fromState) {
+      return false;
+    }
+    runtimeLog.warn(
+      'AgentMachine',
+      `state=${fromState} error outcome had no transition — escaped to parked initial "${initial}"`,
+    );
+    this._transitionTap?.({ kind: 'error-escape', fromState, toState: initial });
+    this.state = initial;
+    this._notify();
+    return true;
+  }
+
+  /** Sends a short fallback to the last known human user when the machine parks unexpectedly. Best-effort — never throws. */
+  async _sendFallbackIfUserWaiting(text: string): Promise<void> {
+    const userId = this._lastUserSenderId;
+    if (!userId) return;
+    try {
+      await this.eff({ kind: 'send-message', sessionId: this.ctx.identity.sessionId, receiverId: userId, text });
+    } catch { /* best-effort */ }
+  }
+
+  _evaluateTransitions(outcome: Outcome): string | null {
+    const sd = this.workflow.states[this.state];
+    if (!sd?.transitions?.length) {
+      runtimeLog.debug('FSM', `evaluate state=${this.state}: NO TRANSITIONS DEFINED`);
+      return null;
+    }
+    for (let i = 0; i < sd.transitions.length; i++) {
+      const rule = sd.transitions[i]!;
+      let matched: boolean;
+      let err: unknown = null;
+      if (!rule.when) {
+        matched = true;
+      } else {
+        try { matched = !!rule.when(outcome, this.ctx); }
+        catch (e) { matched = false; err = e; }
+      }
+      runtimeLog.debug(
+        'FSM',
+        `evaluate state=${this.state} rule[${i}] to=${rule.to} when=${rule.when ? 'fn' : 'always'} → ${matched}${err ? ` ERR=${(err as Error).message}` : ''}`,
+      );
+      if (matched) return rule.to;
+    }
+    runtimeLog.debug('FSM', `evaluate state=${this.state}: NONE matched`);
+    return null;
+  }
+
+  _notify(): void {
+    const snapshot = this.getSnapshot();
+    for (const fn of this._subscribers) {
+      try { fn(snapshot); } catch {}
+    }
+  }
+
+  // Held so PromptBuilder/runTurn can render the original wire event in <event>.
+  // Set by the runtime layer when it calls send(); we don't classify it twice.
+  _lastIncomingEvent: RawEvent | null = null;
+}