@adriane-ai/graph-sdk 0.2.0 → 1.0.0

package/dist/index.js

@@ -2305,7 +2305,7 @@ var createAgentNodeHandler = (nodeId, config) => {
 };
 var createToolNodeHandler = (config) => createToolNode(config.tools, { parallel: config.parallel });
 var cachedNative;
-var hasEngineFns = (mod) => typeof mod === "object" && mod !== null && typeof mod.engineRun === "function" && typeof mod.engineResume === "function" && typeof mod.engineApproveAndResume === "function";
+var hasEngineFns = (mod) => typeof mod === "object" && mod !== null && typeof mod.engineRun === "function" && typeof mod.engineResume === "function" && typeof mod.engineApproveAndResume === "function" && typeof mod.engineSignal === "function";
 var loadNativeEngine = () => {
   if (cachedNative !== void 0) {
     return cachedNative;
@@ -2420,6 +2420,7 @@ var RustGraphRunner = class {
   baseSpec() {
     return {
       graph: this.parts.definition,
+      subgraphs: this.parts.subgraphs,
       agents: this.buildAgentsWire(),
       componentNodes: this.buildComponentsWire(),
       jsNodeIds: [...this.parts.jsNodeIds],
@@ -2427,8 +2428,8 @@ var RustGraphRunner = class {
     };
   }
   /** Start a fresh run on the Rust engine. */
-  async run(runId, initialData) {
-    const spec = { ...this.baseSpec(), runId, initialData };
+  async run(runId, initialData, inbox = {}) {
+    const spec = { ...this.baseSpec(), runId, initialData, inbox };
     const outcomeJson = await this.native.engineRun(
       JSON.stringify(spec),
       this.onNode,
@@ -2472,6 +2473,23 @@ var RustGraphRunner = class {
     );
     return this.outcomeToState(outcomeJson);
   }
+  /**
+   * Deliver an external signal to a suspended run, then resume it. The Rust engine
+   * injects `payload` into `__signals[name]` and advances past the node that awaited
+   * the signal (a `waitForSignal` suspension is one-shot).
+   */
+  async signal(state, name, payload) {
+    const spec = { ...this.baseSpec(), state };
+    const outcomeJson = await this.native.engineSignal(
+      JSON.stringify(spec),
+      name,
+      JSON.stringify(payload ?? null),
+      this.onNode,
+      this.onCondition,
+      this.onEvent
+    );
+    return this.outcomeToState(outcomeJson);
+  }
 };
 var tryCreateRustRunner = (parts) => {
   const native = loadNativeEngine();
@@ -2529,12 +2547,16 @@ var CompiledGraph = class {
     }
     this.checkpointer = new InMemoryCheckpointer();
     this.eventBus = new InMemoryEventBus();
+    const subgraphsById = new Map(
+      (parts.subgraphs ?? []).map((graph) => [String(graph.id), graph])
+    );
     this.runtime = new GraphRuntime({
       graph: parts.definition,
       nodeRegistry,
       conditionRegistry,
       checkpointer: this.checkpointer,
-      eventBus: this.eventBus
+      eventBus: this.eventBus,
+      subgraphResolver: subgraphsById.size === 0 ? void 0 : (graphId) => subgraphsById.get(String(graphId))
     });
     this.rustRunner = this.maybeCreateRustRunner(parts);
     this.rustRunner?.subscribe((event) => {
@@ -2603,6 +2625,7 @@ var CompiledGraph = class {
     const toolFns = this.buildToolFns(agentConfigs);
     const runnerParts = {
       definition: parts.definition,
+      subgraphs: parts.subgraphs ?? [],
       nodeFns: this.buildNodeFns(jsHandlerNodeIds, parts.handlers),
       toolFns,
       conditions: this.buildConditionFns(parts.conditions),
@@ -2660,11 +2683,20 @@ var CompiledGraph = class {
   async run(initialData = {}, options) {
     const runId = options?.runId ?? generateRunId();
     if (this.rustRunner !== null) {
-      const state2 = await this.rustRunner.run(runId, initialData);
+      const state2 = await this.rustRunner.run(
+        runId,
+        initialData,
+        options?.inbox ?? {}
+      );
       this.captureSuspension(state2);
       return state2;
     }
     warnTsEngineOnce();
+    for (const [nodeId, inputs] of Object.entries(options?.inbox ?? {})) {
+      for (const input of inputs) {
+        await this.runtime.send(runId, nodeId, input);
+      }
+    }
     const state = await this.runtime.start(runId, initialData);
     return state;
   }
@@ -2703,6 +2735,27 @@ var CompiledGraph = class {
     await this.runtime.updateState(runId, { [APPROVED_TOOLS_CHANNEL]: names });
     return this.resume(runId);
   }
+  /**
+   * Deliver an external signal to a run suspended on a `waitForSignal` node, then
+   * resume it: the payload is injected into the `__signals` channel under `name` and
+   * the run advances past the waiting node. The seam a control plane uses to wake a
+   * run on an external event (a webhook, a message, an approval-out-of-band).
+   *
+   * Durable timers + external signals run on the **Rust engine** (the production
+   * runtime); the in-process TypeScript fallback does not model them, so this throws
+   * on the TS path. Run with the native addon (or `ADRIANE_SDK_ENGINE=rust`).
+   */
+  async signal(runId, name, payload) {
+    if (this.rustRunner === null) {
+      throw new Error(
+        "CompiledGraph.signal requires the Rust engine (durable timers/signals are not supported on the in-process TypeScript fallback). Install @adriane-ai/napi."
+      );
+    }
+    const suspended = this.requireSuspendedState(runId);
+    const state = await this.rustRunner.signal(suspended, name, payload);
+    this.captureSuspension(state);
+    return state;
+  }
   /**
    * Project granted tool names into the wire shape the Rust engine validates: each
    * tool carries the principal that requested it (the owning agent node) and the
@@ -2746,23 +2799,140 @@ var CompiledGraph = class {
   }
   /**
    * Stream events as the graph executes. See {@link StreamMode} for the available
-   * shapes. The Rust engine has no incremental stream surface yet, so when running on
-   * Rust this drives a full run and yields a single terminal `state_value`. On the TS
-   * engine it streams natively.
+   * shapes. On the TS engine all four modes stream natively. On the **Rust engine** the
+   * modes are projected — incrementally — over the run-event feed that already crosses
+   * napi:
+   * - `updates` — a `state_update` per node completion (`delta` = the node's output).
+   * - `values` — a full `state_value` per node completion, accumulated by replaying the
+   *   node deltas through the channel reducers (the SDK mirrors the engine's reducers),
+   *   plus a final authoritative `state_value` from the resolved run.
+   * - `messages` — a `message_delta` per new entry appended to the `messages` channel
+   *   (message-level; token-level deltas need gateway token streaming — still deferred).
+   * - `debug` — every run-lifecycle event wrapped as a `debug` payload.
    */
   stream(initialData, mode, options) {
     const runId = options?.runId ?? generateRunId();
     if (this.rustRunner !== null) {
-      return this.streamViaRust(runId, initialData);
+      return this.streamViaRust(runId, initialData, mode);
     }
     warnTsEngineOnce();
     return this.runtime.stream(runId, initialData, mode);
   }
-  /** Single-shot stream for the Rust path: run to terminal state, emit it once. */
-  async *streamViaRust(runId, initialData) {
-    const state = await this.rustRunner.run(runId, initialData);
-    this.captureSuspension(state);
-    yield { type: "state_value", state };
+  /** Seed a running channel map from the graph's channel defaults + the run's input. */
+  seedChannels(initialData) {
+    const running = {};
+    for (const [name, def] of Object.entries(this.definition.channels)) {
+      running[name] = initialData[name] ?? def.default ?? null;
+    }
+    for (const [key, value] of Object.entries(initialData)) {
+      if (!(key in running)) {
+        running[key] = value;
+      }
+    }
+    return running;
+  }
+  /** Apply a node delta to the running channels via the declared reducers (engine parity). */
+  applyDelta(running, delta) {
+    for (const [key, value] of Object.entries(delta)) {
+      const reducer = this.definition.channels[key]?.reducer ?? "replace";
+      if (reducer === "append") {
+        const current = running[key];
+        const existing = Array.isArray(current) ? current : current == null ? [] : [current];
+        running[key] = Array.isArray(value) ? [...existing, ...value] : [...existing, value];
+      } else if (reducer === "merge" && value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const current = running[key];
+        const base = current !== null && typeof current === "object" && !Array.isArray(current) ? current : {};
+        running[key] = { ...base, ...value };
+      } else {
+        running[key] = value;
+      }
+    }
+  }
+  /**
+   * Drive the Rust run and project its forwarded run-event feed into {@link StreamEvent}s,
+   * incrementally for every mode. Events arrive via the runner's subscriber while the run
+   * promise is in flight; a small wake/queue interleaves them with the run's completion.
+   */
+  async *streamViaRust(runId, initialData, mode) {
+    const queue = [];
+    let notify = null;
+    const wake = () => {
+      const resume = notify;
+      notify = null;
+      resume?.();
+    };
+    const running = this.seedChannels(initialData);
+    let seenMessages = Array.isArray(running.messages) ? running.messages.length : 0;
+    const shape = (event) => {
+      if (event.type === "node_completed") {
+        const delta = event.output ?? {};
+        if (mode === "updates") {
+          return [{ type: "state_update", delta, nodeId: event.nodeId }];
+        }
+        this.applyDelta(running, delta);
+        if (mode === "values") {
+          return [{ type: "state_value", state: this.syntheticState(runId, event.nodeId, running) }];
+        }
+        if (mode === "messages") {
+          const messages = Array.isArray(running.messages) ? running.messages : [];
+          const fresh = messages.slice(seenMessages);
+          seenMessages = messages.length;
+          return fresh.flatMap((message) => messageDeltas(message, event.nodeId));
+        }
+      }
+      if (mode === "debug") {
+        const nodeId = "nodeId" in event ? event.nodeId : "";
+        return [{ type: "debug", payload: event, nodeId }];
+      }
+      return [];
+    };
+    const unsubscribe = this.rustRunner.subscribe((event) => {
+      const shaped = shape(event);
+      if (shaped.length > 0) {
+        queue.push(...shaped);
+        wake();
+      }
+    });
+    let done = false;
+    const runPromise = this.rustRunner.run(runId, initialData, {}).then((state) => {
+      this.captureSuspension(state);
+      return state;
+    }).finally(() => {
+      done = true;
+      wake();
+    });
+    try {
+      for (; ; ) {
+        while (queue.length > 0) {
+          yield queue.shift();
+        }
+        if (done) {
+          break;
+        }
+        await new Promise((resolve) => {
+          notify = resolve;
+        });
+      }
+      const finalState = await runPromise;
+      if (mode === "values") {
+        yield { type: "state_value", state: finalState };
+      }
+    } finally {
+      unsubscribe();
+    }
+  }
+  /** A channels-only synthetic GraphState for a `values` stream step. */
+  syntheticState(runId, nodeId, channels) {
+    return {
+      runId,
+      graphId: this.definition.id,
+      currentNodeId: nodeId,
+      status: "running",
+      channels: { ...channels },
+      version: 0,
+      createdAt: "",
+      updatedAt: ""
+    };
   }
   /** Subscribe to the run-event lifecycle stream. Returns an unsubscribe function. */
   onEvent(handler) {
@@ -2801,6 +2971,31 @@ var toolNameOfSubject = (request) => {
   return typeof description === "string" && description.startsWith(TOOL_SUBJECT_PREFIX2) ? description.slice(TOOL_SUBJECT_PREFIX2.length) : void 0;
 };
 var syntheticContext = () => ({ memory: void 0 });
+var messageDeltas = (message, nodeId) => {
+  if (message === null || typeof message !== "object") {
+    return [];
+  }
+  const msg = message;
+  const out = [];
+  const messageId = typeof msg.id === "string" ? msg.id : "";
+  if (typeof msg.content === "string" && msg.content.length > 0) {
+    out.push({ type: "message_delta", delta: msg.content, nodeId, messageId });
+  }
+  if (Array.isArray(msg.toolCalls)) {
+    for (const call of msg.toolCalls) {
+      if (call !== null && typeof call === "object") {
+        const c = call;
+        out.push({
+          type: "tool_call",
+          toolId: typeof c.id === "string" ? c.id : typeof c.name === "string" ? c.name : "",
+          input: c.args ?? c.input ?? null,
+          nodeId
+        });
+      }
+    }
+  }
+  return out;
+};
 var toUpdateObject = (value) => {
   if (value === null || typeof value !== "object") {
     return {};
@@ -2885,6 +3080,8 @@ var GraphBuilder = class {
   agentApprovals = /* @__PURE__ */ new Map();
   /** Per component node, the `{ kind, params }` carrier the Rust engine bridge needs. */
   componentConfigs = /* @__PURE__ */ new Map();
+  /** Child graphs registered as `subgraph` nodes, keyed by their (global) graph id. */
+  subgraphDefs = /* @__PURE__ */ new Map();
   entryNodeId;
   constructor(options) {
     this.options = options;
@@ -3013,6 +3210,85 @@ var GraphBuilder = class {
     this.componentConfigs.set(id, { kind: descriptor.kind, params: descriptor.params });
     return this;
   }
+  /**
+   * Add a **subgraph node**: nest another graph (built with its own
+   * {@link GraphBuilder}) as a single node. On entry the parent's channels are
+   * projected into the child via `inputMapping` (`childKey → parentKey`; omit to copy
+   * all parent channels); on completion the child's channels are merged back via
+   * `outputMapping` (`parentKey → childKey`; omit to spread all child channels onto
+   * the parent). If the child suspends (e.g. an internal human gate), the parent
+   * suspends at this node and a parent `resume` re-attaches to the child.
+   *
+   * The child's wiring (node handlers, conditions, agent/component configs) is merged
+   * into the parent — child runs share the parent's registries, keyed by GLOBAL node
+   * id — so child node ids must not collide with the parent's. Declare on the parent
+   * any channels the `outputMapping` writes into.
+   *
+   * ```ts
+   * const child = createGraph({ name: "double", id: "double" })
+   *   .channel("in", { type: "number", default: 0 })
+   *   .channel("out", { type: "number", default: 0 })
+   *   .node("calc", (s) => ({ out: (s.in as number) * 2 }));
+   * createGraph({ name: "parent" })
+   *   .channel("x", { type: "number", default: 21 })
+   *   .channel("y", { type: "number", default: 0 })
+   *   .subgraph("sub", child, { inputMapping: { in: "x" }, outputMapping: { y: "out" } });
+   * ```
+   */
+  subgraph(id, child, options) {
+    if (this.handlers.has(id) || this.nodes.some((node) => String(node.id) === id)) {
+      throw new DuplicateNodeError(id);
+    }
+    const childParts = child.toSubgraphParts();
+    for (const [nodeId, handler] of childParts.handlers) {
+      if (this.handlers.has(nodeId)) {
+        throw new DuplicateNodeError(nodeId);
+      }
+      this.handlers.set(nodeId, handler);
+    }
+    for (const [name, fn] of childParts.conditions) {
+      this.conditions.set(name, fn);
+    }
+    for (const [nodeId, config] of childParts.agentConfigs) {
+      this.agentConfigs.set(nodeId, config);
+    }
+    for (const [nodeId, binding] of childParts.agentApprovals) {
+      this.agentApprovals.set(nodeId, binding);
+    }
+    for (const [nodeId, config] of childParts.componentConfigs) {
+      this.componentConfigs.set(nodeId, config);
+    }
+    this.subgraphDefs.set(String(childParts.definition.id), childParts.definition);
+    for (const [graphId, definition] of childParts.subgraphDefs) {
+      this.subgraphDefs.set(graphId, definition);
+    }
+    this.nodes.push({
+      id,
+      type: "subgraph",
+      label: options?.label ?? id,
+      subgraphId: childParts.definition.id,
+      inputMapping: options?.inputMapping,
+      outputMapping: options?.outputMapping
+    });
+    this.entryNodeId ??= id;
+    return this;
+  }
+  /**
+   * @internal Extract this builder's wiring so it can be nested as a subgraph by a
+   * parent {@link GraphBuilder.subgraph}. Returns live maps (the parent merges them);
+   * not part of the public authoring API.
+   */
+  toSubgraphParts() {
+    return {
+      definition: this.buildDefinition(),
+      handlers: this.handlers,
+      conditions: this.conditions,
+      agentConfigs: this.agentConfigs,
+      agentApprovals: this.agentApprovals,
+      componentConfigs: this.componentConfigs,
+      subgraphDefs: this.subgraphDefs
+    };
+  }
   /** Add an unconditional edge from one node to another. */
   edge(from, to) {
     this.edges.push({
@@ -3059,7 +3335,10 @@ var GraphBuilder = class {
   /** Validate and compile, returning a {@link Result} instead of throwing. */
   safeCompile() {
     const definition = this.buildDefinition();
-    const errors = tryRustValidate(definition) ?? validateGraph(definition);
+    const subgraphs = [...this.subgraphDefs.values()];
+    const errors = [definition, ...subgraphs].flatMap(
+      (graph) => tryRustValidate(graph) ?? validateGraph(graph)
+    );
     if (errors.length > 0) {
       return { success: false, error: new GraphCompileError(errors) };
     }
@@ -3071,7 +3350,8 @@ var GraphBuilder = class {
         conditions: this.conditions,
         agentConfigs: this.agentConfigs,
         agentApprovals: this.agentApprovals,
-        componentConfigs: this.componentConfigs
+        componentConfigs: this.componentConfigs,
+        subgraphs
       })
     };
   }
@@ -3086,6 +3366,33 @@ var GraphBuilder = class {
 };
 var createGraph = (options) => new GraphBuilder(options);
 
+// src/durable.ts
+var SLEEP_UNTIL_KEY = "__sleepUntil";
+var WAIT_FOR_SIGNAL_KEY = "__waitForSignal";
+var SUSPEND_META_KEY = "__suspend";
+var SIGNALS_KEY = "__signals";
+var sleepUntil = (wakeAt, update = {}) => ({ ...update, [SLEEP_UNTIL_KEY]: wakeAt });
+var waitForSignal = (name, options = {}) => ({
+  ...options.update ?? {},
+  [WAIT_FOR_SIGNAL_KEY]: name,
+  ...options.wakeAt === void 0 ? {} : { [SLEEP_UNTIL_KEY]: options.wakeAt }
+});
+var readSuspendMeta = (state) => {
+  const raw = state.channels[SUSPEND_META_KEY];
+  if (raw !== null && typeof raw === "object" && typeof raw.reason === "string") {
+    return raw;
+  }
+  return void 0;
+};
+var readSignal = (state, name) => {
+  const signals = state.channels[SIGNALS_KEY];
+  return signals !== null && typeof signals === "object" ? signals[name] : void 0;
+};
+
+// src/send.ts
+var INJECTED_KEY = "__injected";
+var readInjected = (state) => state.channels[INJECTED_KEY];
+
 // src/components.ts
 var valueToText = (value) => {
   if (typeof value === "string") {
@@ -5433,6 +5740,8 @@ var assembleParts = (definition, usesApprovalEngine) => {
   }
   return {
     definition,
+    // Catalog graphs (assembled from node-metadata carriers) carry no subgraph nodes.
+    subgraphs: [],
     nodeFns: new Map(jsNodeIds.size === 0 ? [] : [...jsNodeIds].map((id) => [id, async () => ({})])),
     toolFns: /* @__PURE__ */ new Map(),
     conditions: /* @__PURE__ */ new Map(),
@@ -5541,6 +5850,6 @@ var isCatalogGraph = (definition) => definition.nodes.some(
   (node) => readComponentCarrier(node.metadata) !== void 0 || readAgentCarrier(node.metadata) !== void 0
 );
 
-export { AGENT_APPROVAL_INTERRUPT, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, AdrianeSdkError, AnthropicProviderAdapter, CompiledGraph, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_REFERENCE_CORPUS, DEFAULT_TIER_TABLE, DefaultLLMGateway, DuplicateNodeError, DynamicInterrupt, EmbeddingsResponseError, GraphBuilder, GraphCompileError, InMemoryCheckpointer, InMemoryPromptRegistry, InMemoryToolRegistry, MODEL_TIERS, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, ModelPolicy, OpenAICompatibleProviderAdapter, RustEngineUnavailableError, buildDocQaReference, componentCatalog, components, cosineSimilarity2 as cosineSimilarity, createAgentNodeHandler, createEmbeddings, createGraph, createToolNodeHandler, createVectorStore, docQaReferenceDefinition, exampleGraphs, isCatalogGraph, prebuilt, prebuiltCatalog, readAgentCarrier, readComponentCarrier, resumeCatalogGraph, runCatalogGraph, rustEngineAvailable, rustValidatorActive, semanticRetriever, streamAgentTokens, tierCatalog, toAgentApprovalBinding, toRustAgentConfig };
+export { AGENT_APPROVAL_INTERRUPT, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, AdrianeSdkError, AnthropicProviderAdapter, CompiledGraph, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_REFERENCE_CORPUS, DEFAULT_TIER_TABLE, DefaultLLMGateway, DuplicateNodeError, DynamicInterrupt, EmbeddingsResponseError, GraphBuilder, GraphCompileError, INJECTED_KEY, InMemoryCheckpointer, InMemoryPromptRegistry, InMemoryToolRegistry, MODEL_TIERS, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, ModelPolicy, OpenAICompatibleProviderAdapter, RustEngineUnavailableError, SIGNALS_KEY, SLEEP_UNTIL_KEY, SUSPEND_META_KEY, WAIT_FOR_SIGNAL_KEY, buildDocQaReference, componentCatalog, components, cosineSimilarity2 as cosineSimilarity, createAgentNodeHandler, createEmbeddings, createGraph, createToolNodeHandler, createVectorStore, docQaReferenceDefinition, exampleGraphs, isCatalogGraph, prebuilt, prebuiltCatalog, readAgentCarrier, readComponentCarrier, readInjected, readSignal, readSuspendMeta, resumeCatalogGraph, runCatalogGraph, rustEngineAvailable, rustValidatorActive, semanticRetriever, sleepUntil, streamAgentTokens, tierCatalog, toAgentApprovalBinding, toRustAgentConfig, waitForSignal };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map