@spendgraph/graph 0.5.0 → 0.7.0

package/dist/execute/outcome.js

@@ -1,44 +1 @@
-import { stringify } from "./step.js";
-function isOutcome(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const v = value;
-    return (typeof v.output === "string" ||
-        typeof v.inputTokens === "number" ||
-        typeof v.outputTokens === "number" ||
-        Array.isArray(v.steps));
-}
-export function outputOf(value) {
-    const outcome = isOutcome(value) ? value : undefined;
-    return outcome && typeof outcome.output === "string" ? outcome.output : stringify(value);
-}
-export function tokensOf(value) {
-    if (!isOutcome(value))
-        return {};
-    const nested = Array.isArray(value.steps) && value.steps.length > 0;
-    return {
-        ...(!nested && typeof value.inputTokens === "number" ? { inputTokens: value.inputTokens } : {}),
-        ...(!nested && typeof value.outputTokens === "number"
-            ? { outputTokens: value.outputTokens }
-            : {}),
-        ...(value.model ? { model: value.model } : {}),
-    };
-}
-export function nestedSteps(value, from, source) {
-    if (!isOutcome(value) || !Array.isArray(value.steps))
-        return [];
-    return value.steps.map((step, at) => ({
-        ...step,
-        index: from + at,
-        source: `${source}.${step.source}`,
-    }));
-}
-export function totalTokens(steps) {
-    let inputTokens = 0;
-    let outputTokens = 0;
-    for (const step of steps) {
-        inputTokens += step.inputTokens ?? 0;
-        outputTokens += step.outputTokens ?? 0;
-    }
-    return { inputTokens, outputTokens };
-}
+import{sealed as u,stringify as f}from"./steps.js";function r(t){if(!t||typeof t!="object"||Array.isArray(t))return!1;const n=t;return typeof n.output=="string"||typeof n.inputTokens=="number"||typeof n.outputTokens=="number"||Array.isArray(n.steps)}function k(t){return r(t)&&typeof t.output=="string"?t.output:f(t)}function s(t){if(!(typeof t!="number"||!Number.isFinite(t)||t<0))return Math.trunc(t)}const p=["cacheReadTokens","cacheWriteTokens","citationTokens","reasoningTokens"];function c(t){const n={};for(const o of p)t[o]!==void 0&&(n[o]=s(t[o])??0);return n}function m(t){if(!r(t))return{};const n=Array.isArray(t.steps)&&t.steps.length>0,o=n?void 0:s(t.inputTokens),e=n?void 0:s(t.outputTokens);return{...o===void 0?{}:{inputTokens:o},...e===void 0?{}:{outputTokens:e},...n?{}:c(t),...t.model?{model:t.model}:{}}}const d=t=>!!t&&typeof t=="object"&&!Array.isArray(t);function A(t,n,o){return!r(t)||!Array.isArray(t.steps)?[]:t.steps.filter(d).map((e,i)=>u({...e,index:n+i,source:`${o}.${e.source??"step"}`}))}import{totalTokens as g}from"@spendgraph/sdk";export{A as nestedSteps,k as outputOf,m as tokensOf,g as totalTokens};

package/dist/execute/resume.d.ts

@@ -0,0 +1,16 @@
+import type { GraphResult, GraphRunOptions } from "../types/index.js";
+/**
+ * How to re-enter a graph at the node that stopped to ask.
+ *
+ * The steps it hands back stop short of that node: a nested run resumed by its
+ * own id comes back carrying its whole history, the half before the pause
+ * included, so seeding that half again would record it twice. What the outer
+ * run owns is everything before the node; what the node did is the node's to
+ * report.
+ *
+ * The **last** time the node ran, not the first. A cycle visits it more than
+ * once, and a run that went round three times before stopping paused on the
+ * third — cutting at the first would throw away every round it had already
+ * paid for.
+ */
+export declare function resumingAt(result: GraphResult, node: string): GraphRunOptions;

package/dist/execute/resume.js

@@ -0,0 +1 @@
+function n(t,e){for(let s=t.steps.length-1;s>=0;s--)if(t.steps[s].source===e)return s;return-1}function p(t,e){const s=n(t,e);return{entry:e,steps:s<0?t.steps:t.steps.slice(0,s),outputs:t.outputs}}export{p as resumingAt};

package/dist/execute/run.d.ts

@@ -0,0 +1,33 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Edge, GraphEvent, GraphResult, GraphRunOptions, Node, Paused } from "../types/index.js";
+export type Narrator = (event: GraphEvent) => void;
+/** A graph as compiled: what `execute` and `stream` walk. */
+export interface Compiled {
+    entry: string;
+    maxSteps: number;
+    nodes: Map<string, Node<never>>;
+    edgesFrom: Map<string, Edge[]>;
+    onFailure?: string;
+    now: () => number;
+}
+export interface Run {
+    compiled: Compiled;
+    values: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    steps: RolloutStep[];
+    visited: number;
+    /** The node the walk arrived from, kept on the run so every context reads the same one. */
+    cameFrom: string | null;
+    /** What sent the walk to the failure node, or null while nothing has fallen over. */
+    failure: {
+        node: string;
+        error: string;
+    } | null;
+    lastOutput: string;
+    startedAt: number;
+    narrate: Narrator;
+}
+export declare function beginRun(compiled: Compiled, values: Record<string, unknown>, opts: GraphRunOptions, narrate: Narrator): Run;
+export declare function finished(run: Run, status: "completed" | "failed", error?: string): GraphResult;
+/** A run stopped at a node that asked something: said once for the stream, once on the result. */
+export declare function parked(run: Run, asked: Paused, node: string, index: number): GraphResult;

package/dist/execute/run.js

@@ -0,0 +1 @@
+import{totalTokens as p}from"./outcome.js";import{sealed as i}from"./steps.js";function l(t,n,e,o){const u=(e.steps??[]).map(i);return{compiled:t,values:n,outputs:{...e.outputs},steps:u,visited:0,cameFrom:null,failure:null,lastOutput:"",startedAt:t.now(),narrate:o}}function r(t,n,e){return{status:n,output:n==="completed"?t.lastOutput:"",error:e,steps:t.steps,outputs:t.outputs,latencyMs:t.compiled.now()-t.startedAt,...p(t.steps)}}function d(t,n,e,o){return t.narrate({type:"paused",node:e,index:o,waitingOn:n.waitingOn,...n.runId?{runId:n.runId}:{}}),{...r(t,"completed"),waitingOn:n.waitingOn,...n.runId?{waitingFor:n.runId}:{}}}export{l as beginRun,r as finished,d as parked};

package/dist/execute/steps.d.ts

@@ -0,0 +1,7 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+/** A string is itself, anything else is JSON; what cannot be written says so rather than reading as nothing. */
+export declare function stringify(value: unknown): string;
+export declare function reasonOf(err: unknown): string;
+export declare function failedStep(index: number, source: string, input: Record<string, unknown>, latencyMs: number, error: string): RolloutStep;
+/** Frozen, so a node handed the record cannot rewrite an earlier step's output or cost. */
+export declare function sealed(step: RolloutStep): RolloutStep;

package/dist/execute/steps.js

@@ -0,0 +1 @@
+function f(t){if(t==null)return"";if(typeof t=="string")return t;try{const n=JSON.stringify(t);return n===void 0?`[not recordable: ${typeof t}]`:n}catch(n){return`[not recordable: ${i(n)}]`}}function i(t){return t instanceof Error?t.message:String(t)}function u(t,n,r,e,o){return{index:t,source:n,input:r,output:"",status:"failed",error:o,latencyMs:e}}function c(t){return Object.freeze(t)}export{u as failedStep,i as reasonOf,c as sealed,f as stringify};

package/dist/execute/visit.d.ts

@@ -0,0 +1,10 @@
+import type { Node } from "../types/index.js";
+import type { Run } from "./run.js";
+export type Visited = {
+    value: unknown;
+} | {
+    error: string;
+    why: string;
+};
+/** Runs one node: builds its input, checks its args, runs it, and records a step whichever way it went. */
+export declare function visit(run: Run, node: Node<never>): Promise<Visited>;

package/dist/execute/visit.js

@@ -0,0 +1 @@
+import{FieldValidationError as l,validateFields as m}from"@spendgraph/sdk";import{contextFor as f}from"./context.js";import{givenBadArgs as g,inputThrew as x,nodeFailed as h}from"./errors.js";import{nestedSteps as y,outputOf as O,tokensOf as A}from"./outcome.js";import{failedStep as F,reasonOf as u,sealed as d}from"./steps.js";function M(e,r){if(!e.args?.length)return null;const t=m(r,e.args);return t.length>0?new l(t).message:null}const c=e=>e.run.compiled.now()-e.startedAt;function p(e,r,t,s){const{run:n,node:o,index:a}=e,i=c(e);return n.steps.push(d(F(a,o.name,r,i,t))),n.narrate({type:"node_end",node:o.name,index:a,status:"failed",error:t,latencyMs:i}),{error:s(o.name,t),why:t}}function _(e,r,t){const{run:s,node:n,index:o}=e,a=c(e);s.outputs[n.name]=t,s.lastOutput=O(t),s.steps.push(d({index:o,source:n.name,input:r,output:s.lastOutput,status:"completed",latencyMs:a,...A(t)}));for(const i of y(t,s.steps.length,n.name))s.steps.push(i);return s.narrate({type:"node_end",node:n.name,index:o,status:"completed",output:t,latencyMs:a}),{value:t}}async function B(e,r){e.visited+=1;const t={run:e,node:r,index:e.steps.length,startedAt:e.compiled.now()},s=f(e,r.name);let n;try{n=r.input?r.input(s):e.values}catch(a){return p(t,{},u(a),x)}e.narrate({type:"node_start",node:r.name,index:t.index,input:n});const o=M(r,n);if(o)return p(t,n,o,g);try{return _(t,n,await r.run(n,s))}catch(a){return p(t,n,u(a),h)}}export{B as visit};

package/dist/execute/walk.d.ts

@@ -0,0 +1,4 @@
+import type { GraphResult, GraphRunOptions } from "../types/index.js";
+import { type Compiled, type Narrator } from "./run.js";
+/** Walks a compiled graph. Never throws: every exit is a result carrying the steps taken. */
+export declare function executeGraph(compiled: Compiled, values: Record<string, unknown>, opts?: GraphRunOptions, narrate?: Narrator): Promise<GraphResult>;

package/dist/execute/walk.js

@@ -0,0 +1 @@
+import{pausedInside as x}from"../types/index.js";import{contextFor as g}from"./context.js";import{choosingThrew as p,hitTheCeiling as w,nowhereToStart as y}from"./errors.js";import{beginRun as F,finished as a,parked as v}from"./run.js";import{reasonOf as k}from"./steps.js";import{visit as S}from"./visit.js";function T(e,t){let n;for(const o of e)if(!o.when||(n??=t(),o.when(n)))return o.to;return null}function A(e,t){try{const n=e.compiled.edgesFrom.get(t.name)??[];return{next:T(n,()=>g(e,t.name))}}catch(n){return{error:p(t.name,k(n))}}}async function j(e,t,n={},o=()=>{}){const r=F(e,t,n,o),u=n.entry??e.entry;if(!e.nodes.has(u))return a(r,"failed",y(u,[...e.nodes.keys()]));let i=u,c=null;for(;i;){if(r.visited>=e.maxSteps)return a(r,"failed",w(e.maxSteps,i));const s=e.nodes.get(i),l=r.steps.length;r.cameFrom=c;const f=await S(r,s);if("error"in f){const h=e.onFailure;if(!h||s.name===h)return a(r,"failed",f.error);r.failure={node:s.name,error:f.why},c=s.name,i=h;continue}const d=x(f.value);if(d)return v(r,d,s.name,l);const m=A(r,s);if("error"in m)return a(r,"failed",m.error);c=i,i=m.next}return a(r,"completed")}export{j as executeGraph};

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-export { type Graph, type GraphOptions, graph } from "./compile/index.js";
-export type { GraphStream } from "./execute/index.js";
+export { type Graph, type GraphOptions, GraphSpecError, graph } from "./compile/index.js";
+export { resumingAt } from "./execute/index.js";
 export type { NodeSpec } from "./node/index.js";
 export { edge, end, node } from "./node/index.js";
-export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphSpec, Node, } from "./types/index.js";
+export type { GraphStream } from "./stream/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphRunOptions, GraphSpec, Node, Note, Paused, Wait, } from "./types/index.js";
+export { pausedInside } from "./types/index.js";

package/dist/index.js

@@ -1,2 +1 @@
-export { graph } from "./compile/index.js";
-export { edge, end, node } from "./node/index.js";
+import{GraphSpecError as o,graph as p}from"./compile/index.js";import{resumingAt as m}from"./execute/index.js";import{edge as f,end as n,node as x}from"./node/index.js";import{pausedInside as g}from"./types/index.js";export{o as GraphSpecError,f as edge,n as end,p as graph,x as node,g as pausedInside,m as resumingAt};

package/dist/node/edge.d.ts

@@ -1,10 +1,5 @@
 import type { Edge } from "../types/index.js";
-/**
- * An edge from one node to the next, or to the end of the run.
- *
- * A helper so the argument order is fixed by something other than memory:
- * `edge("a", "b")` reads in the direction the run travels.
- */
+/** An edge from one node to the next, or to the end of the run. */
 export declare function edge(from: string, to: string | null, when?: Edge["when"]): Edge;
 /** Ends the run after `from`. The same as `edge(from, null)`, said out loud. */
 export declare function end(from: string, when?: Edge["when"]): Edge;

package/dist/node/edge.js

@@ -1,6 +1 @@
-export function edge(from, to, when) {
-    return when ? { from, to, when } : { from, to };
-}
-export function end(from, when) {
-    return edge(from, null, when);
-}
+function t(n,e,r){return r?{from:n,to:e,when:r}:{from:n,to:e}}function u(n,e){return t(n,null,e)}export{t as edge,u as end};

package/dist/node/index.js

@@ -1,2 +1 @@
-export { edge, end } from "./edge.js";
-export { node } from "./node.js";
+import{edge as r,end as d}from"./edge.js";import{node as m}from"./node.js";export{r as edge,d as end,m as node};

package/dist/node/node.d.ts

@@ -5,11 +5,5 @@ export interface NodeSpec<T extends readonly ArgSpec[]> {
     input?: (ctx: GraphContext) => Record<string, unknown>;
     run(input: ArgsOf<T>, ctx: GraphContext): Promise<unknown> | unknown;
 }
-/**
- * Declares a node, checking what a graph cannot check later.
- *
- * The same argument as `tool()`: a duplicated argument silently loses one, and a
- * hyphenated name reads badly in the step record that is the only trace of a
- * failed run.
- */
+/** Declares a node, checking what a graph cannot check later. */
 export declare function node<const T extends readonly ArgSpec[]>(spec: NodeSpec<T>): Node<ArgsOf<T>>;

package/dist/node/node.js

@@ -1,25 +1 @@
-const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export function node(spec) {
-    if (!VALID_NAME.test(spec.name)) {
-        throw new Error(`Node name "${spec.name}" must be letters, digits and underscores, starting with a letter.`);
-    }
-    const seen = new Set();
-    for (const arg of spec.args ?? []) {
-        if (!VALID_NAME.test(arg.name)) {
-            throw new Error(`Node "${spec.name}" argument "${arg.name}" is not a usable name.`);
-        }
-        if (seen.has(arg.name)) {
-            throw new Error(`Node "${spec.name}" declares "${arg.name}" twice.`);
-        }
-        seen.add(arg.name);
-        if (arg.type === "enum" && !arg.options?.length) {
-            throw new Error(`Node "${spec.name}" argument "${arg.name}" is an enum with no options, so nothing can satisfy it.`);
-        }
-    }
-    return {
-        name: spec.name,
-        args: spec.args?.map((a) => ({ ...a, options: a.options ? [...a.options] : undefined })),
-        input: spec.input,
-        run: spec.run,
-    };
-}
+const o=/^[A-Za-z_][A-Za-z0-9_]*$/;function a(e){if(!o.test(e.name))throw new Error(`Node name "${e.name}" must be letters, digits and underscores, starting with a letter.`);const t=new Set;for(const n of e.args??[]){if(!o.test(n.name))throw new Error(`Node "${e.name}" argument "${n.name}" is not a usable name.`);if(t.has(n.name))throw new Error(`Node "${e.name}" declares "${n.name}" twice.`);if(t.add(n.name),n.type==="enum"&&!n.options?.length)throw new Error(`Node "${e.name}" argument "${n.name}" is an enum with no options, so nothing can satisfy it.`)}return{name:e.name,args:e.args?.map(n=>({...n,options:n.options?[...n.options]:void 0})),input:e.input,run:e.run}}export{a as node};

package/dist/stream/events.d.ts

@@ -0,0 +1,22 @@
+import type { GraphEvent } from "../types/index.js";
+/** Events queued between the run and its one reader; a run never waits on a slow reader. */
+export declare class Events {
+    private queued;
+    private head;
+    private wake;
+    private closed;
+    private draining;
+    push(event: GraphEvent): void;
+    close(): void;
+    private release;
+    private takeNext;
+    /**
+     * The events, once.
+     *
+     * A second reader is refused rather than served: both take from the same
+     * queue, so each would see roughly half the run — which reads as a graph that
+     * dropped tokens rather than as the mistake it is. Two watchers want one
+     * reader writing into something they can both read, not two readers.
+     */
+    drain(): AsyncGenerator<GraphEvent>;
+}

package/dist/stream/events.js

@@ -0,0 +1 @@
+class s{queued=[];head=0;wake=null;closed=!1;draining=!1;push(e){this.queued.push(e),this.release()}close(){this.closed=!0,this.release()}release(){const e=this.wake;this.wake=null,e?.()}takeNext(){const e=this.queued[this.head++];return this.head===this.queued.length&&(this.queued=[],this.head=0),e}async*drain(){if(this.draining)throw new Error("This stream is already being read. Iterate it once, or await `result` instead \u2014 to show a run to more than one watcher, keep the events somewhere they can both read.");for(this.draining=!0;;){for(;this.head<this.queued.length;)yield this.takeNext();if(this.closed)return;await new Promise(e=>{this.wake=e})}}}export{s as Events};

package/dist/stream/index.d.ts

@@ -0,0 +1,2 @@
+export type { GraphStream } from "./stream.js";
+export { streamGraph } from "./stream.js";

package/dist/stream/index.js

@@ -0,0 +1 @@
+import{streamGraph as e}from"./stream.js";export{e as streamGraph};

package/dist/stream/stream.d.ts

@@ -0,0 +1,9 @@
+import { type Compiled } from "../execute/index.js";
+import type { GraphEvent, GraphResult, GraphRunOptions } from "../types/index.js";
+/** A run as it happens, and the same run once it is over. Iterable once. */
+export interface GraphStream extends AsyncIterable<GraphEvent> {
+    /** Resolves whether or not anyone iterated. */
+    result: Promise<GraphResult>;
+}
+/** Runs a compiled graph, narrating it; the run starts on the call, not on the first read. */
+export declare function streamGraph(compiled: Compiled, values: Record<string, unknown>, opts?: GraphRunOptions): GraphStream;

package/dist/stream/stream.js

@@ -0,0 +1 @@
+import{executeGraph as c}from"../execute/index.js";import{Events as u}from"./events.js";function l(n,o,s={}){const t=new u,r=(async()=>{try{const e=await c(n,o,s,a=>t.push(a));return t.push({type:"result",result:e}),e}finally{t.close()}})();return r.catch(()=>{}),{result:r,[Symbol.asyncIterator]:()=>t.drain()}}export{l as streamGraph};

package/dist/types/args.d.ts

@@ -1,12 +1,5 @@
 import type { FieldType } from "@spendgraph/sdk";
-/**
- * A declared argument, as written.
- *
- * Structurally a `FieldSpec` with every field readonly, because that is what an
- * `as const` array produces — and `FieldSpec.options` being a mutable `string[]`
- * is enough to make the whole tuple fail the constraint and inference fall back
- * to nothing, silently.
- */
+/** A declared argument as written: a readonly `FieldSpec`, which is what an `as const` array produces. */
 export interface ArgSpec {
     readonly name: string;
     readonly type: FieldType;
@@ -41,13 +34,7 @@ type Required<T> = T extends {
 type Optional<T> = T extends {
     required: true;
 } ? never : T;
-/**
- * The object `run` is handed, derived from the args you declared.
- *
- * Declare `args` with `as const` and the handler's parameter types follow, so a
- * renamed argument is a compile error rather than an `undefined` discovered
- * halfway through a graph.
- */
+/** The object `run` is handed, derived from the args declared `as const`. */
 export type ArgsOf<T extends readonly ArgSpec[]> = {
     [F in Required<T[number]> as F["name"]]: ArgValue<F>;
 } & {

package/dist/types/args.js

@@ -1 +0,0 @@
-export {};

package/dist/types/context.d.ts

@@ -1,25 +1,50 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-import type { Emit } from "./event.js";
-/**
- * What a node can see while it decides and while it runs.
- *
- * `outputs` is the only channel between nodes. A shared mutable bag would let
- * node four depend on a key node two happens to set — a dependency the graph
- * does not declare and compilation cannot check.
- */
+import type { Emit, Note } from "./event.js";
+/** What a node can see while it decides and while it runs; `outputs` is the only channel between nodes. */
 export interface GraphContext {
     /** The object `execute` was called with. */
     values: Record<string, unknown>;
-    /** What each node that has finished returned, by name. */
+    /**
+     * What each node that has finished returned, by name.
+     *
+     * By name, so a node a cycle comes back to overwrites what it returned last
+     * time — a retry reads the attempt it just made, not the first one. Keeping
+     * every pass would make `outputs` a different shape for a cyclic graph than a
+     * straight one, and every reader would owe a check it usually does not need.
+     */
     outputs: Record<string, unknown>;
+    /**
+     * The node that routed here, or null on the entry node.
+     *
+     * What a node reached from more than one place otherwise has to guess at, by
+     * probing `outputs` for whichever branch's node happens to have run. That
+     * guess is wrong in a graph with a cycle: `outputs` keeps the last value a
+     * node returned for the rest of the run, so a join reached a second time
+     * reads a branch it did not come through this pass.
+     */
+    from: string | null;
+    /**
+     * What failed on the way here, for a node reached by `onFailure`.
+     *
+     * Null everywhere else, and on the failure node itself when the run reached
+     * it through an ordinary edge — which is how a compensating node tells "I am
+     * cleaning up after a crash" from "I was walked through in the normal way".
+     */
+    failure: {
+        node: string;
+        error: string;
+    } | null;
     /** The steps recorded so far, in order. A copy; writing to it does nothing. */
     steps: RolloutStep[];
+    /** Sends a token out of the run, tagged with this node. A no-op unless someone is streaming. */
+    emit: Emit;
     /**
-     * Sends a token out of the run, tagged with the node that emitted it.
+     * Sends structured progress out of the run, tagged with this node.
      *
-     * Hand it straight to a model call as its `onText` and the deltas leave the
-     * graph as they arrive. Always present, and a no-op unless someone is
-     * streaming, so a node never has to ask whether anyone is listening.
+     * `emit` is for what the model is saying; this is for what the run is doing —
+     * which step of how many, what it found, how far along. A node reaches it
+     * through the context rather than closing over the caller's, so a step defined
+     * in another module can report progress without being handed a channel.
      */
-    emit: Emit;
+    note: Note;
 }

package/dist/types/context.js

@@ -1 +0,0 @@
-export {};

package/dist/types/edge.d.ts

@@ -4,9 +4,6 @@ export interface Edge {
     from: string;
     /** The next node, or null to end the run here. */
     to: string | null;
-    /**
-     * Taken only when true. Tried in declaration order, first match wins — so an
-     * unconditional edge is the default branch and belongs last.
-     */
+    /** Taken only when true. */
     when?: (ctx: GraphContext) => boolean;
 }

package/dist/types/edge.js

@@ -1 +0,0 @@
-export {};

package/dist/types/event.d.ts

@@ -1,11 +1,6 @@
 import type { GraphResult } from "./result.js";
-/**
- * What a run says about itself while it is still running.
- *
- * Every event names the node it came from, because a stream carrying tokens
- * from four nodes is unreadable without it — and which nodes are worth showing
- * is the consumer's decision, not the graph's.
- */
+import type { Wait } from "./wait.js";
+/** What a run says about itself while it is still running; every event names its node. */
 export type GraphEvent = {
     type: "node_start";
     node: string;
@@ -16,6 +11,11 @@ export type GraphEvent = {
     type: "token";
     node: string;
     text: string;
+} | {
+    /** Whatever a node chose to say about its own progress, as data. */
+    type: "note";
+    node: string;
+    data: unknown;
 } | {
     type: "node_end";
     node: string;
@@ -24,9 +24,19 @@ export type GraphEvent = {
     output?: unknown;
     error?: string;
     latencyMs: number;
+} | {
+    /** A node returned a run that stopped to ask; the walk stops here. */
+    type: "paused";
+    node: string;
+    index: number;
+    waitingOn: Wait;
+    /** The nested run to resume, where it named one. */
+    runId?: string;
 } | {
     type: "result";
     result: GraphResult;
 };
 /** Where a node's tokens go. A run that nobody is streaming drops them. */
 export type Emit = (text: string) => void;
+/** Where a node's structured progress goes. Dropped the same way when nobody is listening. */
+export type Note = (data: unknown) => void;

package/dist/types/event.js

@@ -1 +0,0 @@
-export {};

package/dist/types/index.d.ts

@@ -1,7 +1,8 @@
 export type { ArgSpec, ArgsOf, ArgValue } from "./args.js";
 export type { GraphContext } from "./context.js";
 export type { Edge } from "./edge.js";
-export type { Emit, GraphEvent } from "./event.js";
+export type { Emit, GraphEvent, Note } from "./event.js";
 export type { Node } from "./node.js";
-export type { GraphResult } from "./result.js";
+export type { GraphResult, GraphRunOptions } from "./result.js";
 export type { GraphSpec } from "./spec.js";
+export { type Paused, pausedInside, type Wait } from "./wait.js";

package/dist/types/index.js

@@ -1 +1 @@
-export {};
+import{pausedInside as o}from"./wait.js";export{o as pausedInside};

package/dist/types/node.d.ts

@@ -1,18 +1,10 @@
 import type { FieldSpec } from "@spendgraph/sdk";
 import type { GraphContext } from "./context.js";
-/**
- * One unit of work in a graph.
- *
- * `input` is what makes a node reusable: the node says what it needs, the graph
- * says where it comes from. Without it every node has to know the whole run.
- */
+/** One unit of work in a graph. */
 export interface Node<Args = Record<string, unknown>> {
     /** Unique in the graph, and the key its output is stored under. */
     name: string;
-    /**
-     * What this node needs, validated before `run` does any work. Halfway through
-     * a graph is the most expensive place to discover a typo.
-     */
+    /** What this node needs, validated before `run` does any work. */
     args?: FieldSpec[];
     /** The edge's data half: an edge says what runs next, this says on what. */
     input?: (ctx: GraphContext) => Record<string, unknown>;

package/dist/types/node.js

@@ -1 +0,0 @@
-export {};

package/dist/types/result.d.ts

@@ -1,10 +1,6 @@
 import type { RolloutStep } from "@spendgraph/sdk";
-/**
- * What one run produced, in the shape of a rollout.
- *
- * A graph run is a rollout with several steps, so this hands straight to
- * `report()` rather than being translated first.
- */
+import type { Wait } from "./wait.js";
+/** What one run produced, in the shape of a rollout. */
 export interface GraphResult {
     status: "completed" | "failed";
     /** The last node's return, stringified the way a tool result is. */
@@ -17,4 +13,17 @@ export interface GraphResult {
     /** Summed across every step, nested ones included. */
     inputTokens: number;
     outputTokens: number;
+    /** The question a node stopped to ask, where one did; `status` still says the graph itself ran. */
+    waitingOn?: Wait;
+    /** The nested run to resume, where it named one. */
+    waitingFor?: string;
+}
+/** What a run may be given beyond its values, mostly for picking up where an earlier run stopped. */
+export interface GraphRunOptions {
+    /** What nodes that already ran returned; seeded into `outputs`, not re-run, no steps of their own. */
+    outputs?: Record<string, unknown>;
+    /** Steps an earlier run already took; `index` carries on from them, `maxSteps` does not count them. */
+    steps?: RolloutStep[];
+    /** Where the walk starts instead of the compiled entry; only has to exist, reachability was checked at build. */
+    entry?: string;
 }

package/dist/types/result.js

@@ -1 +0,0 @@
-export {};

package/dist/types/spec.d.ts

@@ -1,15 +1,24 @@
 import type { Edge } from "./edge.js";
 import type { Node } from "./node.js";
 export interface GraphSpec {
-    /** Where a run starts. */
+    /** Where a run starts, unless `GraphRunOptions.entry` names somewhere else. */
     entry: string;
     nodes: Node<never>[];
     edges?: Edge[];
+    /** How many nodes a run may visit before it is called a loop; a nested run's steps do not count. */
+    maxSteps?: number;
     /**
-     * How many nodes a run may execute before it is called a loop. Default 25.
+     * Where the walk goes when a node fails, instead of ending the run.
+     *
+     * A node that throws otherwise ends the walk where it stands, which is the
+     * wrong ending for a run that has already done something outside itself: the
+     * seat is held, the card is charged, and nothing is left to put them back.
+     * Naming a node here gives those steps somewhere to be undone, and the
+     * handler reads `ctx.failure` for what fell over and why.
      *
-     * A backwards edge is a feature and also how a graph hangs. Nothing tells the
-     * two apart statically, so the guard is a count and a clear failure.
+     * It does not catch its own failure — a handler that throws ends the run, or
+     * a graph could compensate forever — and it does not catch an edge condition
+     * throwing, since choosing where to go next is the part that is broken there.
      */
-    maxSteps?: number;
+    onFailure?: string;
 }

package/dist/types/spec.js

@@ -1 +0,0 @@
-export {};

package/dist/types/wait.d.ts

@@ -0,0 +1,24 @@
+/** A run that stopped to ask something. Structural, so `harness`'s own `Wait` satisfies it without an import. */
+export interface Wait {
+    question: string;
+    /** Whatever answering it needs — options to pick from, a diff, an id. */
+    detail?: unknown;
+}
+/** A paused run found inside a node's return. */
+export interface Paused {
+    waitingOn: Wait;
+    /** The id the inner run is stored under — the one a caller has to resume. */
+    runId?: string;
+}
+/**
+ * A node's return that is really a question, recognised by its shape rather than
+ * a marker.
+ *
+ * The id is read from `runId` or from `waitingFor`, which are the same thing
+ * under two names: a stored run calls it `runId`, and a graph that parked on one
+ * reports it as `waitingFor`. Reading only the first lost it at the second level
+ * of nesting — a graph inside a graph surfaced the question and not the run to
+ * answer it against, which is the one part of a pause a caller cannot work out
+ * for itself.
+ */
+export declare function pausedInside(value: unknown): Paused | null;

package/dist/types/wait.js

@@ -0,0 +1 @@
+function o(r){if(!r||typeof r!="object")return null;const n=r,t=n.waitingOn;if(!t||typeof t!="object"||typeof t.question!="string")return null;const i=typeof n.runId=="string"?n.runId:n.waitingFor;return{waitingOn:t,...typeof i=="string"?{runId:i}:{}}}export{o as pausedInside};