@darqlabs/curator-sdk 0.1.6 → 0.2.0

package/README.md

@@ -304,12 +304,30 @@ Same send, streamed. Yields events as they arrive:
 | `state` | `metadata`, complete structured snapshot for this turn | no |
 | `plan_progress` | `phase`, `message`, `completed`/`total`, `labels` | no |
 | `tool_call.started` / `tool_call.completed` | tool call id / name | no |
+| `tool_call.failed` | tool call id / name, `reason` | no |
 | `done` | `message` (with `message.metadata`) | yes |
 | `error` | `failureClass`, `message` | yes |
 | `paused_for_approval` | `approval` | yes |
 
 `state` fires on every turn the agent reports structured state, see [Structured results](#structured-results-metadata).
 
+Tool calls have a symmetrical lifecycle: every `tool_call.started` is followed by exactly one `tool_call.completed` or `tool_call.failed` carrying the same `toolCallId`, so you can always close the right pending indicator:
+
+```ts
+for await (const event of chat.stream("Find the Q3 contract")) {
+  if (event.type === "tool_call.started") pending.add(event.toolCallId)
+  else if (event.type === "tool_call.completed") pending.delete(event.toolCallId)
+  else if (event.type === "tool_call.failed") {
+    pending.delete(event.toolCallId)
+    setNotice(event.reason === "policy_denied"
+      ? "This action wasn't allowed."
+      : "The tool couldn't complete.")
+  }
+}
+```
+
+`tool_call.failed` is **not** terminal — a tool failing doesn't end the run, and the agent usually keeps working. Its `reason` is a closed vocabulary (`policy_denied` for a policy or budget gate, `tool_error` for a tool that ran and failed); there is deliberately no free-text detail, since the underlying reason can reference internal policies and user identifiers. Treat an unrecognised `reason` as a generic failure — more may be added.
+
 `plan_progress` fires for **planned** agents (ones that decompose a request into a task plan). It reports coarse progress through `phase` (`planning` → `executing` → `finalizing`) with a user-facing `message` (e.g. "Working on 3 tasks") and, once tasks are running, `completed`/`total`. A planned run is otherwise quiet until the finalizer streams `delta`s, so handle this to show progress while it works:
 
 ```ts

package/dist/cjs/graph.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Flow-graph authoring + run surface for the Curator SDK.
+ *
+ *   import { Curator, reducers, agentNode, toolNode, transformNode, edge, branch, when } from "@darqlabs/curator-sdk"
+ *
+ *   const draft = curator.defineGraph({
+ *     name: "copy-loop",
+ *     state: { messages: reducers.append(), draft: reducers.lastValue(), revisions: reducers.counter() },
+ *     nodes: {
+ *       write:  agentNode("copywriter"),
+ *       review: toolNode("api.grammar.check"),
+ *       score:  transformNode({ transformId: "tf_quality", version: 1 }),
+ *     },
+ *     entry: "write",
+ *     edges: [
+ *       edge("write", "review"),
+ *       edge("review", "score"),
+ *       branch("score", when("draft_ok", "==", true).then("END").else("write")),
+ *     ],
+ *     recursionLimit: 12,
+ *   })
+ *
+ *   const graph = await curator.graphs.create(draft)   // POST /api/graphs
+ *   await graph.deploy({ expectedDraftRevision: 1 })   // versioned snapshot
+ *
+ *   // run + stream node/state events
+ *   for await (const ev of graph.stream({ messages: [] })) {
+ *     if (ev.type === "node.completed") console.log("done:", ev.node)
+ *     if (ev.type === "done") console.log("final:", ev.state)
+ *   }
+ *
+ * These graph types are SDK-owned (the SDK is published and cannot depend on the
+ * private @darq/shared-types); they mirror the backend spec shape exactly so the
+ * assembled JSON validates + compiles server-side.
+ */
+import type { HttpClient } from "./http.js";
+import type { Environment } from "./types.js";
+export interface TransformRef {
+    transformId: string;
+    version: number;
+    autoUpdate?: boolean;
+}
+export type ReducerKind = "append" | "lastValue" | "merge" | "counter" | "custom";
+export interface ChannelDescriptor {
+    reducer: ReducerKind;
+    reducerRef?: TransformRef;
+    initialValue?: unknown;
+    description?: string;
+}
+export type JoinPolicy = "all" | "any";
+export interface NodeCommon {
+    inputChannels?: string[];
+    inputTransform?: TransformRef;
+    outputTransform?: TransformRef;
+    join?: JoinPolicy;
+    timeout?: number;
+    maxVisits?: number;
+    label?: string;
+}
+export interface AgentGraphNode extends NodeCommon {
+    type: "agent";
+    agentId: string;
+    instructions?: string;
+}
+export interface ToolGraphNode extends NodeCommon {
+    type: "tool";
+    action: string;
+    parameters?: Record<string, unknown>;
+}
+export interface TransformGraphNode extends NodeCommon {
+    type: "transform";
+    transform: TransformRef;
+}
+/**
+ * Fans its inline `body` out over the elements of the `over` channel (an array),
+ * appending each body output into `collect`. Body params/instructions can reference
+ * the current element via `{{item}}` / `{{item.field}}` / `{{index}}`. Body may be
+ * an agent/tool/transform node — not another forEach (no nesting).
+ */
+export interface ForEachGraphNode extends NodeCommon {
+    type: "forEach";
+    over: string;
+    body: GraphNode;
+    collect?: string;
+    itemAs?: string;
+}
+export type GraphNode = AgentGraphNode | ToolGraphNode | TransformGraphNode | ForEachGraphNode;
+export type BranchOp = "==" | "!=" | ">" | ">=" | "<" | "<=" | "in" | "not_in" | "exists" | "truthy" | "falsy";
+export interface BranchPredicate {
+    channel: string;
+    op: BranchOp;
+    value?: unknown;
+}
+export type Branch = {
+    kind: "predicate";
+    predicate: BranchPredicate;
+    then: string;
+    else: string;
+} | {
+    kind: "router";
+    transform: TransformRef;
+    targets: string[];
+};
+export interface StaticEdge {
+    kind: "static";
+    from: string;
+    to: string;
+}
+export interface ConditionalEdge {
+    kind: "conditional";
+    from: string;
+    branch: Branch;
+}
+export type GraphEdge = StaticEdge | ConditionalEdge;
+export interface GraphSpec {
+    state: Record<string, ChannelDescriptor>;
+    nodes: Record<string, GraphNode>;
+    entry: string;
+    edges: GraphEdge[];
+    recursionLimit?: number;
+    toolFailureMode?: "strict" | "best_effort";
+}
+/** The `END` sentinel target. */
+export declare const GRAPH_END: "END";
+export type GraphRunStatus = "running" | "paused" | "succeeded" | "failed" | "cancelled";
+export type GraphNodeRunStatus = "pending" | "ready" | "running" | "succeeded" | "failed" | "skipped";
+export interface GraphNodeRunView {
+    key: string;
+    type: GraphNode["type"];
+    status: GraphNodeRunStatus;
+    visits: number;
+    childRunId?: string;
+}
+export interface GraphRunView {
+    runId: string;
+    graphId: string;
+    versionId: string;
+    status: GraphRunStatus;
+    spec: GraphSpec;
+    nodes: GraphNodeRunView[];
+    hops: number;
+    recursionLimit: number;
+    state: Record<string, unknown>;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/** Streamed node/state lifecycle, derived from run-view snapshots. */
+export type GraphRunEvent = {
+    type: "run.started";
+    runId: string;
+} | {
+    type: "node.started";
+    node: string;
+    visit: number;
+} | {
+    type: "node.completed";
+    node: string;
+} | {
+    type: "node.failed";
+    node: string;
+} | {
+    type: "state.delta";
+    channels: Record<string, unknown>;
+} | {
+    type: "done";
+    status: GraphRunStatus;
+    state: Record<string, unknown>;
+} | {
+    type: "error";
+    message: string;
+};
+export declare const reducers: {
+    append: () => ChannelDescriptor;
+    lastValue: () => ChannelDescriptor;
+    merge: () => ChannelDescriptor;
+    counter: () => ChannelDescriptor;
+    /** A custom fold `(prev, update) => next`, run as a sandboxed transform. */
+    custom: (transform: TransformRef) => ChannelDescriptor;
+};
+export declare function agentNode(agentId: string, opts?: Omit<AgentGraphNode, "type" | "agentId">): AgentGraphNode;
+export declare function toolNode(action: string, opts?: Omit<ToolGraphNode, "type" | "action">): ToolGraphNode;
+export declare function transformNode(transform: TransformRef, opts?: Omit<TransformGraphNode, "type" | "transform">): TransformGraphNode;
+/**
+ * A `forEach` (map) node: run `body` per element of the `over` channel, appending
+ * each output into `collect`. Body params can reference the element via
+ * `{{item}}` / `{{item.field}}` / `{{index}}`.
+ */
+export declare function forEachNode(over: string, body: GraphNode, opts?: Omit<ForEachGraphNode, "type" | "over" | "body">): ForEachGraphNode;
+export declare function edge(from: string, to: string): StaticEdge;
+/** Attach a conditional edge to `from`. Pass a predicate builder or a router. */
+export declare function branch(from: string, spec: Branch | PredicateBuilder): ConditionalEdge;
+/** A sandboxed router transform that returns a next-node key (or END). */
+export declare function router(transform: TransformRef, targets: string[]): Branch;
+/**
+ * Fluent declarative predicate: `when("draft_ok", "==", true).then("END").else("write")`.
+ * Unary ops (`exists`/`truthy`/`falsy`) omit the value.
+ */
+export declare function when(channel: string, op: BranchOp, value?: unknown): PredicateBuilder;
+export declare class PredicateBuilder {
+    private readonly predicate;
+    private thenKey?;
+    private elseKey?;
+    constructor(predicate: BranchPredicate);
+    then(nodeKey: string): this;
+    else(nodeKey: string): this;
+    /** @internal */
+    build(): Branch;
+}
+export interface DefineGraphConfig {
+    name: string;
+    description?: string;
+    state: Record<string, ChannelDescriptor>;
+    nodes: Record<string, GraphNode>;
+    entry: string;
+    edges: GraphEdge[];
+    recursionLimit?: number;
+    toolFailureMode?: "strict" | "best_effort";
+    tags?: string[];
+}
+/** A locally-assembled graph, ready to `curator.graphs.create(...)`. */
+export interface GraphDraft {
+    name: string;
+    description?: string;
+    tags?: string[];
+    spec: GraphSpec;
+}
+/** Assemble a serializable graph spec locally. Pure — no network. */
+export declare function defineGraph(config: DefineGraphConfig): GraphDraft;
+export interface GraphRunOptions {
+    /** Target environment for the deployed spec (default: the client default). */
+    environment?: Environment;
+    /** Run the draft spec instead of the live deployed version. */
+    useDraft?: boolean;
+    /** Sync-wait timeout, in ms (server-capped). Only used by `run` (non-stream). */
+    timeoutMs?: number;
+}
+export interface GraphRunResult {
+    runId: string;
+    status: GraphRunStatus | "timeout";
+    state?: Record<string, unknown>;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface DeployGraphOptions {
+    environment?: Environment;
+    slug?: string;
+    changeSummary?: string;
+    /** Optimistic-concurrency token — the draft revision you reviewed. */
+    expectedDraftRevision: number;
+}
+/** A handle to one graph resource, addressed by its `graph_id`. */
+export declare class Graph {
+    private readonly http;
+    private readonly baseUrl;
+    private readonly defaultTimeoutMs;
+    readonly graphId: string;
+    private readonly defaultEnvironment;
+    /** @internal */
+    constructor(http: HttpClient, baseUrl: string, defaultTimeoutMs: number, graphId: string, defaultEnvironment: Environment);
+    private get base();
+    /** Deploy the current draft as an immutable versioned snapshot. */
+    deploy(opts: DeployGraphOptions): Promise<{
+        versionId: string;
+        versionNumber: number;
+        slug: string;
+    }>;
+    /**
+     * Start a run and, unless `{ wait: false }`, block until it settles.
+     * Returns the terminal channel state (or `status: "timeout"` if the wait
+     * expires — the run keeps going server-side).
+     */
+    run(input: Record<string, unknown>, opts?: GraphRunOptions & {
+        wait?: boolean;
+    }): Promise<GraphRunResult>;
+    /**
+     * Start a run and stream node/state lifecycle events until it settles.
+     * Events (`run.started` / `node.started` / `node.completed` / `node.failed`
+     * / `state.delta` / `done` / `error`) are derived from the server's run-view
+     * snapshot stream. Breaking out of the loop closes the connection; the run
+     * continues server-side.
+     */
+    stream(input: Record<string, unknown>, opts?: GraphRunOptions): AsyncGenerator<GraphRunEvent, void, void>;
+    /** Fetch the read-only run projection (spec + per-node status + state). */
+    runStatus(runId: string): Promise<GraphRunView>;
+    /** List this graph's version snapshots (newest first). */
+    versions(): Promise<Array<{
+        versionId: string;
+        versionNumber: number;
+        createdAt: string;
+    }>>;
+}
+/** Collection surface for creating + addressing graphs. */
+export declare class Graphs {
+    private readonly http;
+    private readonly baseUrl;
+    private readonly defaultTimeoutMs;
+    private readonly defaultEnvironment;
+    /** @internal */
+    constructor(http: HttpClient, baseUrl: string, defaultTimeoutMs: number, defaultEnvironment: Environment);
+    /** Create a new graph resource from a draft (or inline config). Returns a
+     *  handle bound to the new `graph_id`. */
+    create(draft: GraphDraft | DefineGraphConfig): Promise<Graph>;
+    /** Reattach to an existing graph by id. */
+    get(graphId: string): Graph;
+    private handle;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/cjs/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/graph.ts"],"names":[],"mappings":"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"}

package/dist/cjs/graph.js

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Flow-graph authoring + run surface for the Curator SDK.
+ *
+ *   import { Curator, reducers, agentNode, toolNode, transformNode, edge, branch, when } from "@darqlabs/curator-sdk"
+ *
+ *   const draft = curator.defineGraph({
+ *     name: "copy-loop",
+ *     state: { messages: reducers.append(), draft: reducers.lastValue(), revisions: reducers.counter() },
+ *     nodes: {
+ *       write:  agentNode("copywriter"),
+ *       review: toolNode("api.grammar.check"),
+ *       score:  transformNode({ transformId: "tf_quality", version: 1 }),
+ *     },
+ *     entry: "write",
+ *     edges: [
+ *       edge("write", "review"),
+ *       edge("review", "score"),
+ *       branch("score", when("draft_ok", "==", true).then("END").else("write")),
+ *     ],
+ *     recursionLimit: 12,
+ *   })
+ *
+ *   const graph = await curator.graphs.create(draft)   // POST /api/graphs
+ *   await graph.deploy({ expectedDraftRevision: 1 })   // versioned snapshot
+ *
+ *   // run + stream node/state events
+ *   for await (const ev of graph.stream({ messages: [] })) {
+ *     if (ev.type === "node.completed") console.log("done:", ev.node)
+ *     if (ev.type === "done") console.log("final:", ev.state)
+ *   }
+ *
+ * These graph types are SDK-owned (the SDK is published and cannot depend on the
+ * private @darq/shared-types); they mirror the backend spec shape exactly so the
+ * assembled JSON validates + compiles server-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Graphs = exports.Graph = exports.PredicateBuilder = exports.reducers = exports.GRAPH_END = void 0;
+exports.agentNode = agentNode;
+exports.toolNode = toolNode;
+exports.transformNode = transformNode;
+exports.forEachNode = forEachNode;
+exports.edge = edge;
+exports.branch = branch;
+exports.router = router;
+exports.when = when;
+exports.defineGraph = defineGraph;
+const errors_js_1 = require("./errors.js");
+const sse_js_1 = require("./sse.js");
+/** The `END` sentinel target. */
+exports.GRAPH_END = "END";
+// ── Builders (pure) ───────────────────────────────────────────────
+exports.reducers = {
+    append: () => ({ reducer: "append" }),
+    lastValue: () => ({ reducer: "lastValue" }),
+    merge: () => ({ reducer: "merge" }),
+    counter: () => ({ reducer: "counter" }),
+    /** A custom fold `(prev, update) => next`, run as a sandboxed transform. */
+    custom: (transform) => ({ reducer: "custom", reducerRef: transform }),
+};
+function agentNode(agentId, opts = {}) {
+    return { type: "agent", agentId, ...opts };
+}
+function toolNode(action, opts = {}) {
+    return { type: "tool", action, ...opts };
+}
+function transformNode(transform, opts = {}) {
+    return { type: "transform", transform, ...opts };
+}
+/**
+ * A `forEach` (map) node: run `body` per element of the `over` channel, appending
+ * each output into `collect`. Body params can reference the element via
+ * `{{item}}` / `{{item.field}}` / `{{index}}`.
+ */
+function forEachNode(over, body, opts = {}) {
+    return { type: "forEach", over, body, ...opts };
+}
+function edge(from, to) {
+    return { kind: "static", from, to };
+}
+/** Attach a conditional edge to `from`. Pass a predicate builder or a router. */
+function branch(from, spec) {
+    const b = spec instanceof PredicateBuilder ? spec.build() : spec;
+    return { kind: "conditional", from, branch: b };
+}
+/** A sandboxed router transform that returns a next-node key (or END). */
+function router(transform, targets) {
+    return { kind: "router", transform, targets };
+}
+/**
+ * Fluent declarative predicate: `when("draft_ok", "==", true).then("END").else("write")`.
+ * Unary ops (`exists`/`truthy`/`falsy`) omit the value.
+ */
+function when(channel, op, value) {
+    return new PredicateBuilder({ channel, op, value });
+}
+class PredicateBuilder {
+    predicate;
+    thenKey;
+    elseKey;
+    constructor(predicate) {
+        this.predicate = predicate;
+    }
+    then(nodeKey) {
+        this.thenKey = nodeKey;
+        return this;
+    }
+    else(nodeKey) {
+        this.elseKey = nodeKey;
+        return this;
+    }
+    /** @internal */
+    build() {
+        if (this.thenKey === undefined || this.elseKey === undefined) {
+            throw new errors_js_1.CuratorError("A `when(...)` branch requires both `.then(...)` and `.else(...)`.");
+        }
+        return { kind: "predicate", predicate: this.predicate, then: this.thenKey, else: this.elseKey };
+    }
+}
+exports.PredicateBuilder = PredicateBuilder;
+/** Assemble a serializable graph spec locally. Pure — no network. */
+function defineGraph(config) {
+    const { name, description, tags, state, nodes, entry, edges, recursionLimit, toolFailureMode } = config;
+    return {
+        name,
+        description,
+        tags,
+        spec: { state, nodes, entry, edges, recursionLimit, toolFailureMode },
+    };
+}
+// ── Client handles ────────────────────────────────────────────────
+/** A handle to one graph resource, addressed by its `graph_id`. */
+class Graph {
+    http;
+    baseUrl;
+    defaultTimeoutMs;
+    graphId;
+    defaultEnvironment;
+    /** @internal */
+    constructor(http, baseUrl, defaultTimeoutMs, graphId, defaultEnvironment) {
+        this.http = http;
+        this.baseUrl = baseUrl;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.graphId = graphId;
+        this.defaultEnvironment = defaultEnvironment;
+    }
+    get base() {
+        return `${this.baseUrl}/api/graphs/${encodeURIComponent(this.graphId)}`;
+    }
+    /** Deploy the current draft as an immutable versioned snapshot. */
+    async deploy(opts) {
+        const env = opts.environment ?? this.defaultEnvironment;
+        const res = await this.http.request(`${this.base}/deploy`, {
+            method: "POST",
+            body: {
+                environment: env,
+                slug: opts.slug,
+                change_summary: opts.changeSummary,
+                expected_draft_revision: opts.expectedDraftRevision,
+            },
+        });
+        return {
+            versionId: res.data.version.version_id,
+            versionNumber: res.data.version.version_number,
+            slug: res.data.deployment.slug,
+        };
+    }
+    /**
+     * Start a run and, unless `{ wait: false }`, block until it settles.
+     * Returns the terminal channel state (or `status: "timeout"` if the wait
+     * expires — the run keeps going server-side).
+     */
+    async run(input, opts = {}) {
+        const wait = opts.wait !== false;
+        const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+        const res = await this.http.request(`${this.base}/run`, {
+            method: "POST",
+            body: {
+                input,
+                environment: opts.environment ?? this.defaultEnvironment,
+                use_draft: opts.useDraft,
+                wait,
+                timeout_ms: wait ? timeoutMs : undefined,
+            },
+            signalTimeoutMs: wait ? timeoutMs + 10_000 : undefined,
+        });
+        return {
+            runId: res.data.run_id,
+            status: res.data.status ?? "running",
+            state: res.data.state,
+            errorCode: res.data.errorCode,
+            errorMessage: res.data.errorMessage,
+        };
+    }
+    /**
+     * Start a run and stream node/state lifecycle events until it settles.
+     * Events (`run.started` / `node.started` / `node.completed` / `node.failed`
+     * / `state.delta` / `done` / `error`) are derived from the server's run-view
+     * snapshot stream. Breaking out of the loop closes the connection; the run
+     * continues server-side.
+     */
+    async *stream(input, opts = {}) {
+        // Start async (no wait) to get a run id, then attach to the snapshot stream.
+        const started = await this.run(input, { ...opts, wait: false });
+        const runId = started.runId;
+        yield { type: "run.started", runId };
+        const controller = new AbortController();
+        const response = await this.http.streamPost(`${this.base}/runs/${encodeURIComponent(runId)}/stream`, { query: { stream: "true" }, signal: controller.signal });
+        const differ = new SnapshotDiffer();
+        try {
+            for await (const frame of (0, sse_js_1.parseSseStream)(response.body)) {
+                if (frame.event === "snapshot") {
+                    const view = safeParse(frame.data);
+                    if (!view)
+                        continue;
+                    for (const ev of differ.diff(view))
+                        yield ev;
+                }
+                else if (frame.event === "done") {
+                    const done = safeParse(frame.data);
+                    const last = differ.lastView;
+                    yield {
+                        type: "done",
+                        status: done?.status ?? last?.status ?? "succeeded",
+                        state: last?.state ?? {},
+                    };
+                    return;
+                }
+            }
+        }
+        finally {
+            try {
+                controller.abort();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    /** Fetch the read-only run projection (spec + per-node status + state). */
+    async runStatus(runId) {
+        const res = await this.http.request(`${this.base}/runs/${encodeURIComponent(runId)}`);
+        return res.data;
+    }
+    /** List this graph's version snapshots (newest first). */
+    async versions() {
+        const res = await this.http.request(`${this.base}/versions`);
+        return res.data.map((v) => ({
+            versionId: v.version_id,
+            versionNumber: v.version_number,
+            createdAt: v.created_at,
+        }));
+    }
+}
+exports.Graph = Graph;
+/** Collection surface for creating + addressing graphs. */
+class Graphs {
+    http;
+    baseUrl;
+    defaultTimeoutMs;
+    defaultEnvironment;
+    /** @internal */
+    constructor(http, baseUrl, defaultTimeoutMs, defaultEnvironment) {
+        this.http = http;
+        this.baseUrl = baseUrl;
+        this.defaultTimeoutMs = defaultTimeoutMs;
+        this.defaultEnvironment = defaultEnvironment;
+    }
+    /** Create a new graph resource from a draft (or inline config). Returns a
+     *  handle bound to the new `graph_id`. */
+    async create(draft) {
+        const normalized = "spec" in draft ? draft : defineGraph(draft);
+        const res = await this.http.request(`${this.baseUrl}/api/graphs`, {
+            method: "POST",
+            body: {
+                name: normalized.name,
+                description: normalized.description,
+                tags: normalized.tags,
+                spec: normalized.spec,
+            },
+        });
+        return this.handle(res.data.graph_id);
+    }
+    /** Reattach to an existing graph by id. */
+    get(graphId) {
+        return this.handle(graphId);
+    }
+    handle(graphId) {
+        return new Graph(this.http, this.baseUrl, this.defaultTimeoutMs, graphId, this.defaultEnvironment);
+    }
+}
+exports.Graphs = Graphs;
+// ── Snapshot → event diffing ──────────────────────────────────────
+class SnapshotDiffer {
+    lastView = null;
+    prevStatuses = new Map();
+    prevState = {};
+    diff(view) {
+        const events = [];
+        for (const node of view.nodes) {
+            const prev = this.prevStatuses.get(node.key);
+            if (prev !== node.status) {
+                if (node.status === "running") {
+                    events.push({ type: "node.started", node: node.key, visit: node.visits });
+                }
+                else if (node.status === "succeeded") {
+                    events.push({ type: "node.completed", node: node.key });
+                }
+                else if (node.status === "failed") {
+                    events.push({ type: "node.failed", node: node.key });
+                }
+                this.prevStatuses.set(node.key, node.status);
+            }
+        }
+        const changed = {};
+        for (const [k, v] of Object.entries(view.state)) {
+            if (JSON.stringify(this.prevState[k]) !== JSON.stringify(v))
+                changed[k] = v;
+        }
+        if (Object.keys(changed).length > 0) {
+            events.push({ type: "state.delta", channels: changed });
+        }
+        this.prevState = view.state;
+        this.lastView = view;
+        return events;
+    }
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=graph.js.map