@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/dist/compute/strategies/tree-of-thoughts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { Strategy } from "../types.js";
+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;
+}
+/**
+ * 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 declare function treeOfThoughtsStrategy<TInput, TOutput>(config?: Partial<ToTConfig>): Strategy<TInput, TOutput>;
+//# sourceMappingURL=tree-of-thoughts.d.ts.map

package/dist/compute/strategies/tree-of-thoughts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-of-thoughts.d.ts","sourceRoot":"","sources":["../../../src/compute/strategies/tree-of-thoughts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAkB,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAI5E,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5C,MAAM,WAAW,SAAS;IACxB,kCAAkC;IAClC,YAAY,EAAE,eAAe,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IAC3C,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;CACxB;AAyCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EACpD,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAgM3B"}

package/dist/compute/strategies/tree-of-thoughts.js

@@ -0,0 +1,242 @@
+/**
+ * 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).
+ */
+const STRATEGY_NAME = "tree-of-thoughts";
+const VALID_POLICIES = new Set(["bfs", "dfs"]);
+// ─── Default evaluator ───────────────────────────────────────────────────────
+function defaultEvaluator(state) {
+    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) {
+    if (signal?.aborted) {
+        throw signal.reason instanceof Error
+            ? signal.reason
+            : new DOMException("Aborted", "AbortError");
+    }
+}
+// ─── 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(config) {
+    const searchPolicy = 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, generator, ctx = {}) {
+            const start = performance.now();
+            const signal = ctx.signal;
+            throwIfAborted(signal);
+            const childCtx = signal ? { signal } : {};
+            let callsUsed = 0;
+            const allLeaves = [];
+            const allScores = [];
+            // Helper: expand one parent into up to branchFactor children.
+            // Each child = 1 generator call.
+            const expandNode = async (_parent, depth) => {
+                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 = 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 = [];
+                // 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 = [];
+                    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 = [];
+                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];
+                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) {
+    if (!Number.isFinite(x))
+        return 0;
+    if (x < 0)
+        return 0;
+    if (x > 1)
+        return 1;
+    return x;
+}
+//# sourceMappingURL=tree-of-thoughts.js.map

package/dist/compute/strategies/tree-of-thoughts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-of-thoughts.js","sourceRoot":"","sources":["../../../src/compute/strategies/tree-of-thoughts.ts"],"names":[],"mappings":"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"}

package/dist/compute/strategies/two-phase-orient.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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).
+ */
+export declare class TwoPhaseOrientError extends Error {
+    readonly phase: "orient" | "act";
+    readonly cause: unknown;
+    readonly retriesUsed: number;
+    constructor(phase: "orient" | "act", cause: unknown, retriesUsed: number, message: string);
+}
+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;
+}
+/**
+ * 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 declare function runTwoPhaseOrient<C, O, R>(config: TwoPhaseOrientConfig<C, O, R>, context: C): Promise<TwoPhaseOrientResult<O, R>>;
+//# sourceMappingURL=two-phase-orient.d.ts.map

package/dist/compute/strategies/two-phase-orient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-phase-orient.d.ts","sourceRoot":"","sources":["../../../src/compute/strategies/two-phase-orient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAG3B,KAAK,EAAE,QAAQ,GAAG,KAAK,EACvB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM;CAUlB;AAMD,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3C;;;;OAIG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC;IACxC,WAAW,EAAE,CAAC,CAAC;IACf,MAAM,EAAE,CAAC,CAAC;IACV,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC7C,MAAM,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACrC,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAyCrC"}

package/dist/compute/strategies/two-phase-orient.js

@@ -0,0 +1,85 @@
+/**
+ * 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 {
+    phase;
+    cause;
+    retriesUsed;
+    constructor(phase, cause, retriesUsed, message) {
+        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);
+    }
+}
+// ---------------------------------------------------------------------------
+// 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(config, context) {
+    const maxRetries = Math.max(0, Math.floor(config.maxActRetries ?? 1));
+    // ── Phase 1: Orient ───────────────────────────────────────────────────────
+    let orientation;
+    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;
+    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)}`);
+}
+//# sourceMappingURL=two-phase-orient.js.map

package/dist/compute/strategies/two-phase-orient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-phase-orient.js","sourceRoot":"","sources":["../../../src/compute/strategies/two-phase-orient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,KAAK,CAAmB;IACxB,KAAK,CAAU;IACf,WAAW,CAAS;IAE7B,YACE,KAAuB,EACvB,KAAc,EACd,WAAmB,EACnB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,iDAAiD;QACjD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF;AAqCD,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAqC,EACrC,OAAU;IAEV,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC;IAEtE,6EAA6E;IAC7E,IAAI,WAAc,CAAC;IACnB,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,mBAAmB,CAC3B,QAAQ,EACR,GAAG,EACH,CAAC,EACD,2CACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,IAAI,YAAqB,CAAC;IAC1B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YACtD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;QACvD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,YAAY,GAAG,GAAG,CAAC;YACnB,8CAA8C;QAChD,CAAC;IACH,CAAC;IAED,0BAA0B;IAC1B,MAAM,IAAI,mBAAmB,CAC3B,KAAK,EACL,YAAY,EACZ,UAAU,EACV,6CAA6C,UAAU,GAAG,CAAC,gBACzD,YAAY,YAAY,KAAK;QAC3B,CAAC,CAAC,YAAY,CAAC,OAAO;QACtB,CAAC,CAAC,MAAM,CAAC,YAAY,CACzB,EAAE,CACH,CAAC;AACJ,CAAC"}

package/dist/constitution/types.d.ts

@@ -147,30 +147,30 @@ export declare const cycleSnapshotSchema: z.ZodObject<{
         costUsd: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         type: string;
-        index: number;
         phase: string;
+        index: number;
         model?: {
             provider: string;
             name: string;
             version: string;
         } | undefined;
+        costUsd?: number | undefined;
         output?: unknown;
         storedInput?: unknown;
         toolName?: string | undefined;
-        costUsd?: number | undefined;
     }, {
         type: string;
-        index: number;
         phase: string;
+        index: number;
         model?: {
             provider: string;
             name: string;
             version: string;
         } | undefined;
+        costUsd?: number | undefined;
         output?: unknown;
         storedInput?: unknown;
         toolName?: string | undefined;
-        costUsd?: number | undefined;
     }>, "many">;
     budgetUsdMax: z.ZodNumber;
     budgetUsdSpent: z.ZodNumber;
@@ -221,23 +221,23 @@ export declare const cycleSnapshotSchema: z.ZodObject<{
     rootHash: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     runId: string;
+    rootHash: string;
     steps: {
         type: string;
-        index: number;
         phase: string;
+        index: number;
         model?: {
             provider: string;
             name: string;
             version: string;
         } | undefined;
+        costUsd?: number | undefined;
         output?: unknown;
         storedInput?: unknown;
         toolName?: string | undefined;
-        costUsd?: number | undefined;
     }[];
     budgetUsdMax: number;
     budgetUsdSpent: number;
-    rootHash: string;
     metadata?: z.objectOutputType<{
         rso_veto: z.ZodOptional<z.ZodBoolean>;
         hash_primitive: z.ZodOptional<z.ZodString>;
@@ -257,23 +257,23 @@ export declare const cycleSnapshotSchema: z.ZodObject<{
     scope_id?: string | undefined;
 }, {
     runId: string;
+    rootHash: string;
     steps: {
         type: string;
-        index: number;
         phase: string;
+        index: number;
         model?: {
             provider: string;
             name: string;
             version: string;
         } | undefined;
+        costUsd?: number | undefined;
         output?: unknown;
         storedInput?: unknown;
         toolName?: string | undefined;
-        costUsd?: number | undefined;
     }[];
     budgetUsdMax: number;
     budgetUsdSpent: number;
-    rootHash: string;
     metadata?: z.objectInputType<{
         rso_veto: z.ZodOptional<z.ZodBoolean>;
         hash_primitive: z.ZodOptional<z.ZodString>;