@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/compute/strategies/tree-of-thoughts.ts

@@ -0,0 +1,293 @@
+/**
+ * src/compute/strategies/tree-of-thoughts.ts
+ *
+ * Tree-of-Thoughts (ToT) compute strategy.
+ *
+ * Reference: Yao et al. 2023, "Tree of Thoughts: Deliberate Problem Solving
+ * with Large Language Models", arXiv:2305.10601.
+ *
+ * Algorithm (paper §3):
+ *   1. Build a tree of partial-solution states, root = empty/initial state.
+ *   2. Expand each node into up to `branchFactor` children via the generator.
+ *   3. Evaluate each state with a lightweight heuristic (no extra LLM call).
+ *   4. BFS expands level-by-level; DFS goes depth-first with backtracking
+ *      when score < pruning threshold.
+ *   5. Bound total expansions by `maxCalls` (== generator-call budget).
+ *   6. Return the highest-scoring leaf output.
+ *
+ * Default state-evaluator (no LLM):
+ *   - string outputs : monotone progress score based on length (caps at 200)
+ *   - number outputs : closeness to plausible-answer band [0, 100]
+ *   - other          : 0.5 (neutral)
+ *
+ * @experimental Public-experimental API per `contract-stability.md` (sprint-582).
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "../types.js";
+
+// ─── Public types ────────────────────────────────────────────────────────────
+
+export type ToTSearchPolicy = "bfs" | "dfs";
+
+export interface ToTConfig {
+  /** BFS or DFS. Default: "bfs". */
+  searchPolicy: ToTSearchPolicy;
+  /** Max tree depth (steps). Default: 3. */
+  maxDepth: number;
+  /** Max branching factor (children per node). Default: 3. */
+  branchFactor: number;
+  /** Hard cap on total generator calls. Default: maxDepth * branchFactor. */
+  maxCalls: number;
+  /** State evaluator → score in [0,1]. Default: heuristic on output shape. */
+  evaluateState?: (state: unknown) => number;
+  /** Prune any node whose evaluator score is below this. Default: 0.2. */
+  pruneThreshold: number;
+}
+
+const STRATEGY_NAME = "tree-of-thoughts";
+
+const VALID_POLICIES: ReadonlySet<string> = new Set(["bfs", "dfs"]);
+
+// ─── Default evaluator ───────────────────────────────────────────────────────
+
+function defaultEvaluator(state: unknown): number {
+  if (typeof state === "string") {
+    const len = state.length;
+    if (len === 0) return 0;
+    // Monotone, saturates at 200 chars → 1.0
+    return Math.min(1, len / 200);
+  }
+  if (typeof state === "number" && Number.isFinite(state)) {
+    if (state < 0 || state > 200) return 0.1;
+    // Centered around 50 for plausibility (synthetic-task heuristic)
+    return 0.5 + 0.5 * (1 / (1 + Math.abs(state - 50)));
+  }
+  return 0.5;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : new DOMException("Aborted", "AbortError");
+  }
+}
+
+interface TreeNode<O> {
+  state: O;
+  depth: number;
+  score: number;
+}
+
+// ─── Strategy factory ────────────────────────────────────────────────────────
+
+/**
+ * Construct a Tree-of-Thoughts {@link Strategy}.
+ *
+ * @throws RangeError when `maxDepth`, `branchFactor`, or `maxCalls` is < 1.
+ * @throws Error when `searchPolicy` is not "bfs" or "dfs".
+ */
+export function treeOfThoughtsStrategy<TInput, TOutput>(
+  config?: Partial<ToTConfig>,
+): Strategy<TInput, TOutput> {
+  const searchPolicy: ToTSearchPolicy = config?.searchPolicy ?? "bfs";
+  const maxDepth = config?.maxDepth ?? 3;
+  const branchFactor = config?.branchFactor ?? 3;
+  const maxCalls = config?.maxCalls ?? maxDepth * branchFactor;
+  const pruneThreshold = config?.pruneThreshold ?? 0.2;
+  const evaluateState = config?.evaluateState ?? defaultEvaluator;
+
+  if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+    throw new RangeError(`treeOfThoughtsStrategy: maxDepth must be >=1, got ${maxDepth}`);
+  }
+  if (!Number.isInteger(branchFactor) || branchFactor < 1) {
+    throw new RangeError(`treeOfThoughtsStrategy: branchFactor must be >=1, got ${branchFactor}`);
+  }
+  if (!Number.isInteger(maxCalls) || maxCalls < 1) {
+    throw new RangeError(`treeOfThoughtsStrategy: maxCalls must be >=1, got ${maxCalls}`);
+  }
+  if (!VALID_POLICIES.has(searchPolicy)) {
+    throw new Error(
+      `treeOfThoughtsStrategy: searchPolicy must be "bfs" or "dfs", got "${searchPolicy}"`,
+    );
+  }
+
+  const strategyLabel = `${STRATEGY_NAME}-${searchPolicy}`;
+
+  return {
+    name: strategyLabel,
+
+    async run(
+      input: TInput,
+      generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+      ctx: ComputeContext = {},
+    ): Promise<StrategyResult<TOutput>> {
+      const start = performance.now();
+      const signal = ctx.signal;
+      throwIfAborted(signal);
+
+      const childCtx: ComputeContext = signal ? { signal } : {};
+
+      let callsUsed = 0;
+      const allLeaves: TreeNode<TOutput>[] = [];
+      const allScores: number[] = [];
+
+      // Helper: expand one parent into up to branchFactor children.
+      // Each child = 1 generator call.
+      const expandNode = async (
+        _parent: TreeNode<TOutput> | null,
+        depth: number,
+      ): Promise<TreeNode<TOutput>[]> => {
+        const childrenToMake = Math.min(branchFactor, maxCalls - callsUsed);
+        if (childrenToMake <= 0) return [];
+
+        // Parallel sampling at this level.
+        throwIfAborted(signal);
+        const samples = await Promise.all(
+          Array.from({ length: childrenToMake }, () => generator(input, childCtx)),
+        );
+        callsUsed += childrenToMake;
+
+        const nodes: TreeNode<TOutput>[] = samples.map((state) => {
+          const score = clamp01(evaluateState(state));
+          return { state, depth, score };
+        });
+
+        for (const n of nodes) allScores.push(n.score);
+
+        // Pruned nodes are still recorded as leaves (score known) but not expanded.
+        return nodes;
+      };
+
+      if (searchPolicy === "bfs") {
+        // ── BFS ───────────────────────────────────────────────────────────
+        let frontier: TreeNode<TOutput>[] = [];
+
+        // Depth-1 children from root.
+        const initial = await expandNode(null, 1);
+        frontier = initial;
+        // Leaves at maxDepth or pruned go into allLeaves.
+        for (const n of initial) {
+          if (n.depth >= maxDepth || n.score < pruneThreshold) {
+            allLeaves.push(n);
+          }
+        }
+
+        while (frontier.length > 0 && callsUsed < maxCalls) {
+          // Filter out pruned/leaf nodes — only expand survivors.
+          const survivors = frontier.filter((n) => n.score >= pruneThreshold && n.depth < maxDepth);
+          if (survivors.length === 0) break;
+
+          const nextFrontier: TreeNode<TOutput>[] = [];
+          for (const parent of survivors) {
+            if (callsUsed >= maxCalls) break;
+            const children = await expandNode(parent, parent.depth + 1);
+            for (const c of children) {
+              if (c.depth >= maxDepth || c.score < pruneThreshold) {
+                allLeaves.push(c);
+              } else {
+                nextFrontier.push(c);
+              }
+            }
+          }
+
+          // If BFS terminates with un-expanded frontier (budget hit), those are leaves too.
+          if (callsUsed >= maxCalls) {
+            for (const n of nextFrontier) allLeaves.push(n);
+            break;
+          }
+          frontier = nextFrontier;
+        }
+        // Any remaining frontier nodes at end-of-budget = leaves.
+        for (const n of frontier) {
+          if (!allLeaves.includes(n)) allLeaves.push(n);
+        }
+      } else {
+        // ── DFS with backtracking ─────────────────────────────────────────
+        const stack: TreeNode<TOutput>[] = [];
+        const initial = await expandNode(null, 1);
+        // Push so highest score is explored first.
+        const sortedInitial = [...initial].sort((a, b) => b.score - a.score);
+        stack.push(...sortedInitial.reverse()); // reverse so highest pops first
+
+        for (const n of initial) {
+          if (n.depth >= maxDepth || n.score < pruneThreshold) {
+            allLeaves.push(n);
+          }
+        }
+
+        while (stack.length > 0 && callsUsed < maxCalls) {
+          const node = stack.pop();
+          if (!node) break;
+          // Backtrack if pruned or terminal.
+          if (node.score < pruneThreshold || node.depth >= maxDepth) {
+            // Already recorded as leaf above (or will be).
+            if (!allLeaves.includes(node)) allLeaves.push(node);
+            continue;
+          }
+          // Expand survivor.
+          const children = await expandNode(node, node.depth + 1);
+          const sortedChildren = [...children].sort((a, b) => b.score - a.score);
+          for (const c of sortedChildren.reverse()) {
+            if (c.depth >= maxDepth || c.score < pruneThreshold) {
+              allLeaves.push(c);
+            } else {
+              stack.push(c);
+            }
+          }
+        }
+        // Any unexplored stack nodes = leaves (budget-bound).
+        for (const n of stack) {
+          if (!allLeaves.includes(n)) allLeaves.push(n);
+        }
+      }
+
+      // ── Pick highest-scoring leaf ─────────────────────────────────────
+      if (allLeaves.length === 0) {
+        // Should never happen: root expansion always produces ≥1 leaf
+        // unless maxCalls=0 (which we reject). Defensive fallback.
+        const fallback = await generator(input, childCtx);
+        callsUsed++;
+        allScores.push(clamp01(evaluateState(fallback)));
+        const latency_ms = performance.now() - start;
+        return {
+          result: fallback,
+          metadata: {
+            strategy: strategyLabel,
+            candidates: 1,
+            verifier_scores: allScores,
+            cost: { calls: callsUsed },
+            latency_ms,
+          },
+        };
+      }
+
+      let best = allLeaves[0];
+      for (let i = 1; i < allLeaves.length; i++) {
+        const n = allLeaves[i] as TreeNode<TOutput>;
+        if (n.score > best.score) best = n;
+      }
+
+      const latency_ms = performance.now() - start;
+      return {
+        result: best.state,
+        metadata: {
+          strategy: strategyLabel,
+          candidates: callsUsed,
+          verifier_scores: allScores,
+          cost: { calls: callsUsed },
+          latency_ms,
+        },
+      };
+    },
+  };
+}
+
+function clamp01(x: number): number {
+  if (!Number.isFinite(x)) return 0;
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}

package/src/compute/strategies/two-phase-orient.ts

@@ -0,0 +1,147 @@
+/**
+ * src/compute/strategies/two-phase-orient.ts
+ *
+ * Two-Phase Orient pattern.
+ *
+ * Phase 1 — Orient: read-only context gathering, produces an orientation state.
+ * Phase 2 — Act:    state-mutating execution driven by the orientation.
+ *
+ * The separation enforces a hard OODA discipline:
+ * - Phase 1 has no side effects; it may be retried cheaply on failure.
+ * - Phase 2 consumes the orientation and may be retried up to `maxActRetries`.
+ *
+ * Error semantics:
+ * - `TwoPhaseOrientError` (phase: "orient") — Phase 1 threw; Phase 2 is never reached.
+ * - `TwoPhaseOrientError` (phase: "act")    — Phase 2 exhausted all retries.
+ * - Each Phase 2 retry attempt is tracked in `retriesUsed` (0 = first attempt succeeded).
+ */
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class TwoPhaseOrientError extends Error {
+  readonly phase: "orient" | "act";
+  readonly cause: unknown;
+  readonly retriesUsed: number;
+
+  constructor(
+    phase: "orient" | "act",
+    cause: unknown,
+    retriesUsed: number,
+    message: string
+  ) {
+    super(message);
+    this.name = "TwoPhaseOrientError";
+    this.phase = phase;
+    this.cause = cause;
+    this.retriesUsed = retriesUsed;
+    // Restore prototype chain (tsc targets < ES2022)
+    Object.setPrototypeOf(this, TwoPhaseOrientError.prototype);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config + return type
+// ---------------------------------------------------------------------------
+
+export interface TwoPhaseOrientConfig<C, O, R> {
+  /**
+   * Phase 1: orientation (read-only, observe + analyse).
+   * Receives the raw context and returns an orientation state.
+   * Must not produce observable side effects.
+   */
+  orient: (context: C) => Promise<O>;
+
+  /**
+   * Phase 2: act on the orientation.
+   * Receives both the orientation produced by Phase 1 and the original context.
+   * Returns the final result.
+   */
+  act: (orientation: O, context: C) => Promise<R>;
+
+  /**
+   * Maximum number of times Phase 2 may be retried after a recoverable failure.
+   * `maxActRetries = 1` means one initial attempt + one retry = 2 total attempts.
+   * Default: 1.
+   * Must be a non-negative integer; values < 0 are treated as 0.
+   */
+  maxActRetries?: number;
+}
+
+export interface TwoPhaseOrientResult<O, R> {
+  orientation: O;
+  result: R;
+  /** Number of Phase-2 retries consumed (0 = succeeded on first attempt). */
+  retriesUsed: number;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Executes the Two-Phase Orient pattern.
+ *
+ * @param config  Wiring for both phases + optional retry cap.
+ * @param context Opaque context forwarded to both `orient` and `act`.
+ *
+ * @throws {TwoPhaseOrientError} When Phase 1 throws (phase: "orient") or
+ *   Phase 2 exhausts all retries (phase: "act").
+ *
+ * @example
+ * ```ts
+ * const { orientation, result, retriesUsed } = await runTwoPhaseOrient(
+ *   {
+ *     orient: async (ctx) => await gatherSignals(ctx),
+ *     act:    async (orient, ctx) => await executeDecision(orient, ctx),
+ *   },
+ *   requestContext,
+ * );
+ * ```
+ */
+export async function runTwoPhaseOrient<C, O, R>(
+  config: TwoPhaseOrientConfig<C, O, R>,
+  context: C
+): Promise<TwoPhaseOrientResult<O, R>> {
+  const maxRetries = Math.max(0, Math.floor(config.maxActRetries ?? 1));
+
+  // ── Phase 1: Orient ───────────────────────────────────────────────────────
+  let orientation: O;
+  try {
+    orientation = await config.orient(context);
+  } catch (err) {
+    throw new TwoPhaseOrientError(
+      "orient",
+      err,
+      0,
+      `TwoPhaseOrient Phase 1 (orient) failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+
+  // ── Phase 2: Act (with retries) ───────────────────────────────────────────
+  let lastActError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await config.act(orientation, context);
+      return { orientation, result, retriesUsed: attempt };
+    } catch (err) {
+      lastActError = err;
+      // Continue to next attempt if retries remain.
+    }
+  }
+
+  // All attempts exhausted.
+  throw new TwoPhaseOrientError(
+    "act",
+    lastActError,
+    maxRetries,
+    `TwoPhaseOrient Phase 2 (act) failed after ${maxRetries + 1} attempt(s): ${
+      lastActError instanceof Error
+        ? lastActError.message
+        : String(lastActError)
+    }`
+  );
+}

package/src/container/protocol.ts

@@ -0,0 +1,243 @@
+/**
+ * Container Execution Protocol — standard contract for running automations
+ * inside containers or as local binaries.
+ *
+ * Contract:
+ *
+ *   Input (via env vars):
+ *     VAUBAN_EXECUTION_ID    — unique execution identifier (UUID)
+ *     VAUBAN_AUTOMATION_NAME — automation name (kebab-case)
+ *     VAUBAN_INPUT           — JSON-encoded input parameters
+ *     VAUBAN_TIMEOUT         — timeout in seconds
+ *     VAUBAN_MODE            — execution mode (default: "execute")
+ *
+ *   Output (via stdout, last non-empty line, JSON):
+ *     { "status": "completed", "output": <any> }
+ *     { "status": "failed", "error": { "code": "...", "message": "...", "details"?: <any> } }
+ *
+ *   Diagnostics (via stderr, optional, one JSON object per line):
+ *     { "level": "info", "message": "...", "timestamp": "..." }
+ *     { "progress": 0.5, "message": "..." }
+ *
+ * @public @since 1.2.0
+ */
+
+/**
+ * Reserved environment variable names. All caller env merged on top must NOT
+ * shadow these keys, or the automation's view of its own context becomes
+ * undefined.
+ *
+ * @public
+ */
+export const PROTOCOL_ENV = {
+  EXECUTION_ID: "VAUBAN_EXECUTION_ID",
+  AUTOMATION_NAME: "VAUBAN_AUTOMATION_NAME",
+  INPUT: "VAUBAN_INPUT",
+  TIMEOUT: "VAUBAN_TIMEOUT",
+  MODE: "VAUBAN_MODE",
+} as const;
+
+/**
+ * Default protocol mode set when caller does not specify one.
+ * @public
+ */
+export const DEFAULT_PROTOCOL_MODE = "execute";
+
+/**
+ * Final status reported by a container/binary on stdout.
+ * @public
+ */
+export type ProtocolStatus = "completed" | "failed";
+
+/**
+ * Discriminated union of protocol outputs parsed from stdout.
+ * @public
+ */
+export type ProtocolResult<T = unknown> =
+  | { readonly status: "completed"; readonly output: T }
+  | {
+      readonly status: "failed";
+      readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: unknown;
+      };
+    };
+
+/**
+ * Outcome of an execution attempt, combining protocol result with timing,
+ * captured logs, and propagated metadata.
+ *
+ * @public
+ */
+export interface ExecutionResult<T = unknown> {
+  readonly executionId: string;
+  readonly automationName: string;
+  readonly status: "completed" | "failed" | "timeout";
+  readonly input: unknown;
+  readonly output?: T;
+  readonly error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  readonly startedAt: Date;
+  readonly completedAt: Date;
+  readonly durationMs: number;
+  readonly logs: ReadonlyArray<{
+    readonly level: string;
+    readonly message: string;
+    readonly timestamp: string;
+  }>;
+}
+
+/**
+ * Thrown when stdout does not contain a parseable protocol result on its last
+ * non-empty line.
+ *
+ * @public
+ */
+export class ProtocolParseError extends Error {
+  readonly rawTail: string;
+  constructor(reason: string, rawTail: string) {
+    super(`container-protocol: ${reason}`);
+    this.name = "ProtocolParseError";
+    this.rawTail = rawTail;
+  }
+}
+
+/**
+ * Build the protocol's environment variables. Caller `extraEnv` is merged
+ * AFTER protocol env, so it cannot accidentally override reserved keys.
+ *
+ * @public
+ */
+export function buildProtocolEnv(args: {
+  executionId: string;
+  automationName: string;
+  input: unknown;
+  timeoutSeconds: number;
+  mode?: string;
+  extraEnv?: Readonly<Record<string, string>>;
+}): Record<string, string> {
+  const env: Record<string, string> = {};
+  if (args.extraEnv) {
+    for (const [k, v] of Object.entries(args.extraEnv)) {
+      env[k] = v;
+    }
+  }
+  env[PROTOCOL_ENV.EXECUTION_ID] = args.executionId;
+  env[PROTOCOL_ENV.AUTOMATION_NAME] = args.automationName;
+  env[PROTOCOL_ENV.INPUT] = JSON.stringify(args.input);
+  env[PROTOCOL_ENV.TIMEOUT] = String(args.timeoutSeconds);
+  env[PROTOCOL_ENV.MODE] = args.mode ?? DEFAULT_PROTOCOL_MODE;
+  return env;
+}
+
+/**
+ * Parse the last non-empty line of stdout as a {@link ProtocolResult}.
+ *
+ * @throws {@link ProtocolParseError} when stdout is empty, has no JSON tail,
+ *   or the JSON does not match the protocol shape.
+ *
+ * @public
+ */
+export function parseProtocolOutput<T = unknown>(
+  stdout: string
+): ProtocolResult<T> {
+  const trimmed = stdout.trim();
+  if (trimmed.length === 0) {
+    throw new ProtocolParseError("stdout is empty", "");
+  }
+  const lines = trimmed.split("\n");
+  const lastLine = lines[lines.length - 1]!.trim();
+  if (lastLine.length === 0) {
+    throw new ProtocolParseError(
+      "last stdout line is empty",
+      trimmed.slice(-200)
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(lastLine);
+  } catch {
+    throw new ProtocolParseError(
+      "last stdout line is not valid JSON",
+      lastLine.slice(0, 500)
+    );
+  }
+
+  if (typeof parsed !== "object" || parsed === null || !("status" in parsed)) {
+    throw new ProtocolParseError(
+      "protocol JSON missing 'status' field",
+      lastLine.slice(0, 500)
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const status = obj["status"];
+
+  if (status === "completed") {
+    return { status: "completed", output: (obj["output"] ?? null) as T };
+  }
+
+  if (status === "failed") {
+    const err = (obj["error"] as Record<string, unknown> | undefined) ?? {};
+    const code =
+      typeof err["code"] === "string" ? (err["code"] as string) : "UNKNOWN";
+    const message =
+      typeof err["message"] === "string"
+        ? (err["message"] as string)
+        : "(no message)";
+    const details = err["details"];
+    return { status: "failed", error: { code, message, details } };
+  }
+
+  throw new ProtocolParseError(
+    `unknown protocol status: ${String(status)}`,
+    lastLine.slice(0, 500)
+  );
+}
+
+/**
+ * Parse stderr lines as JSON log entries when possible; fall back to plain
+ * text wrapped at level "info". Used by {@link ContainerRuntime} to populate
+ * `ExecutionResult.logs`.
+ *
+ * @public
+ */
+export function parseStderrLogs(stderr: string): Array<{
+  level: string;
+  message: string;
+  timestamp: string;
+}> {
+  const logs: Array<{ level: string; message: string; timestamp: string }> = [];
+  const lines = stderr.split("\n");
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0) continue;
+    try {
+      const obj = JSON.parse(line) as Record<string, unknown>;
+      logs.push({
+        level:
+          typeof obj["level"] === "string" ? (obj["level"] as string) : "info",
+        message:
+          typeof obj["message"] === "string"
+            ? (obj["message"] as string)
+            : line.slice(0, 500),
+        timestamp:
+          typeof obj["timestamp"] === "string"
+            ? (obj["timestamp"] as string)
+            : new Date().toISOString(),
+      });
+    } catch {
+      logs.push({
+        level: "info",
+        message: line.slice(0, 500),
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+  return logs;
+}