@adriane-ai/graph-sdk 0.1.0 → 1.0.0

package/dist/index.d.ts

@@ -1803,11 +1803,24 @@ type CompiledGraphParts = {
      * graphs with no component nodes.
      */
     componentConfigs?: Map<string, RustComponentConfig>;
+    /**
+     * Child graphs that `subgraph`-type nodes resolve into (their node handlers /
+     * conditions / agent / component configs are already merged into the maps above, by
+     * global node id). Carried to the Rust engine as `EngineSpec.subgraphs` and to the TS
+     * engine as a `subgraphResolver`. Empty for graphs with no subgraph nodes.
+     */
+    subgraphs?: GraphDefinition[];
 };
 /** Options accepted by {@link CompiledGraph.run} / {@link CompiledGraph.stream}. */
 type RunOptions = {
     /** Provide a stable run id (e.g. to correlate with an external system). */
     runId?: RunId;
+    /**
+     * Pre-queue dynamic-message inputs (`send`) before the run: per node id, a FIFO list
+     * each consumed by that node's next execution via the reserved `__injected` channel
+     * (read it with {@link import("./send.js").readInjected}). The map-reduce seam.
+     */
+    inbox?: Record<string, unknown[]>;
 };
 /**
  * A validated, runnable graph. Holds the engine wiring (registries, checkpointer,
@@ -1906,6 +1919,17 @@ declare class CompiledGraph<TState extends ChannelValues = ChannelValues> {
      * tools; this is the human seam.
      */
     approveAndResume(runId: RunId, options: ApproveAndResumeOptions): Promise<TypedGraphState<TState>>;
+    /**
+     * 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`).
+     */
+    signal(runId: RunId, name: string, payload?: unknown): Promise<TypedGraphState<TState>>;
     /**
      * 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
@@ -1924,13 +1948,30 @@ declare class CompiledGraph<TState extends ChannelValues = ChannelValues> {
     private approvePendingThroughEngines;
     /**
      * 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: InitialData<TState>, mode: StreamMode, options?: RunOptions): AsyncIterable<StreamEvent>;
-    /** Single-shot stream for the Rust path: run to terminal state, emit it once. */
+    /** Seed a running channel map from the graph's channel defaults + the run's input. */
+    private seedChannels;
+    /** Apply a node delta to the running channels via the declared reducers (engine parity). */
+    private applyDelta;
+    /**
+     * 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.
+     */
     private streamViaRust;
+    /** A channels-only synthetic GraphState for a `values` stream step. */
+    private syntheticState;
     /** Subscribe to the run-event lifecycle stream. Returns an unsubscribe function. */
     onEvent(handler: (event: RunEvent) => void): () => void;
     /**
@@ -2022,6 +2063,8 @@ declare class GraphBuilder<TState extends ChannelValues = EmptyChannels> {
     private readonly agentApprovals;
     /** Per component node, the `{ kind, params }` carrier the Rust engine bridge needs. */
     private readonly componentConfigs;
+    /** Child graphs registered as `subgraph` nodes, keyed by their (global) graph id. */
+    private readonly subgraphDefs;
     private entryNodeId;
     constructor(options: CreateGraphOptions);
     /** Reinterpret `this` under a wider channel type after declaring a new channel. */
@@ -2083,6 +2126,50 @@ declare class GraphBuilder<TState extends ChannelValues = EmptyChannels> {
     component(id: string, descriptor: ComponentDescriptor, options?: {
         label?: string;
     }): 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<TChild extends ChannelValues>(id: string, child: GraphBuilder<TChild>, options?: {
+        inputMapping?: Record<string, string>;
+        outputMapping?: Record<string, string>;
+        label?: string;
+    }): 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(): {
+        definition: GraphDefinition;
+        handlers: Map<string, NodeHandler>;
+        conditions: Map<string, ConditionFn>;
+        agentConfigs: Map<string, RustAgentConfig>;
+        agentApprovals: Map<string, AgentApprovalBinding>;
+        componentConfigs: Map<string, RustComponentConfig>;
+        subgraphDefs: Map<string, GraphDefinition>;
+    };
     /** Add an unconditional edge from one node to another. */
     edge(from: string, to: string): this;
     /**
@@ -2101,6 +2188,76 @@ declare class GraphBuilder<TState extends ChannelValues = EmptyChannels> {
 /** Entry point: start building a graph. */
 declare const createGraph: (options: CreateGraphOptions) => GraphBuilder<EmptyChannels>;
 
+/**
+ * Durable-timer / external-signal helpers for node handlers (ADR 0009). A node handler
+ * returns one of these to make the run SUSPEND after applying its channel update:
+ * - {@link sleepUntil} — a durable timer: the run waits until an external scheduler
+ *   resumes it at `wakeAt` (the engine never sleeps — `wakeAt` is opaque data).
+ * - {@link waitForSignal} — wait for a named external signal delivered via
+ *   {@link import("./compiled-graph.js").CompiledGraph.signal}; optionally with a
+ *   timeout `wakeAt` (signal-or-timeout).
+ *
+ * Both are reserved-key markers the Rust engine recognises across the napi seam; they
+ * run on the Rust engine (the production runtime), not the TypeScript dev fallback.
+ */
+/** Reserved handler-return key requesting a durable-timer suspension. */
+declare const SLEEP_UNTIL_KEY = "__sleepUntil";
+/** Reserved handler-return key requesting a signal-wait suspension. */
+declare const WAIT_FOR_SIGNAL_KEY = "__waitForSignal";
+/** Channel key carrying the suspend reason + scheduler hints on a suspended run. */
+declare const SUSPEND_META_KEY = "__suspend";
+/** Channel key carrying delivered signal payloads, keyed by signal name. */
+declare const SIGNALS_KEY = "__signals";
+/** Why a run is suspended, with any timer / signal scheduler hints. */
+type SuspendMeta = {
+    /** `"human-gate" | "interrupt" | "timer" | "signal"`. */
+    reason: string;
+    /** For a durable timer (or signal-or-timeout): when to resume. Opaque to the engine. */
+    wakeAt?: string;
+    /** For a signal wait: the signal name a `signal(...)` must deliver. */
+    awaitingSignal?: string;
+};
+/**
+ * Node-handler return: suspend as a **durable timer** until `wakeAt`, applying `update`
+ * to the channels first. `wakeAt` is an opaque deadline (e.g. ISO-8601) — the engine
+ * stores it and never reads a clock; the control-plane scheduler resumes the run then.
+ * On resume the run advances past this node.
+ */
+declare const sleepUntil: (wakeAt: string, update?: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Node-handler return: suspend awaiting the external signal `name`, applying `update`
+ * first. Deliver it with {@link import("./compiled-graph.js").CompiledGraph.signal};
+ * the payload lands in `__signals[name]`. Pass `wakeAt` for a signal-OR-timeout (the
+ * run also wakes at `wakeAt` if the signal never arrives).
+ */
+declare const waitForSignal: (name: string, options?: {
+    wakeAt?: string;
+    update?: Record<string, unknown>;
+}) => Record<string, unknown>;
+/**
+ * Read the suspend metadata off a (suspended) run state — the control-plane scheduler
+ * uses `wakeAt` to know when to resume a timer and `awaitingSignal` to route a signal.
+ * Returns `undefined` when the run is not suspended on a timer / signal.
+ */
+declare const readSuspendMeta: (state: Pick<GraphState, "channels">) => SuspendMeta | undefined;
+/** Read a delivered signal's payload from a run state's `__signals` channel. */
+declare const readSignal: (state: Pick<GraphState, "channels">, name: string) => unknown;
+
+/**
+ * Dynamic-message (`send`) helpers. Pre-queue inputs for a node via
+ * {@link import("./compiled-graph.js").RunOptions.inbox}; each node execution consumes
+ * the next queued input, exposed under the reserved `__injected` channel. A node handler
+ * reads it with {@link readInjected}. The map-reduce / dynamic-dispatch seam.
+ */
+/** Reserved channel exposing a `send`-injected input to a node handler (per execution). */
+declare const INJECTED_KEY = "__injected";
+/**
+ * Read the `send`-injected input from a node's state, if the node consumed a queued
+ * input this execution; `undefined` otherwise. The value is visible to the handler only
+ * and is never persisted into the run's channels.
+ */
+declare const readInjected: (state: Pick<GraphState, "channels">) => unknown;
+
 /**
  * Canonical example graphs authored with the SDK. Shipped so the Studio can render
  * them and the control plane can seed them — one source of truth for both. Only the
@@ -2583,7 +2740,7 @@ type ApprovedToolWire = {
  *   - an AGENT node carries `node.metadata.agent = { provider?, model?, tier?, system?,
  *     toolNames?, maxIterations?, suspendForApproval?, approvalToolNames?, outputChannel? }`
  *
- * This is the seam a control plane uses to EXECUTE a graph built from
+ * This is the seam the control plane (`apps/api`) uses to EXECUTE a graph built from
  * the catalog: it reads each node's metadata, assembles the engine's
  * `EngineSpec.componentNodes` + `agents` maps + the `jsNodeIds` for plain
  * action/tool nodes, and drives the run on the **Rust engine** via `@adriane-ai/napi`.
@@ -2671,7 +2828,7 @@ declare const resumeCatalogGraph: (definition: GraphDefinition, state: GraphStat
      * Human-granted tools to unlock on resume, each carrying its `{ name, requestedBy,
      * resolvedBy }` provenance. Passed straight through to the Rust bridge, which
      * re-validates the no-self-approval invariant per tool on `Entry::Resume` and writes
-     * only the validated names into `__approvedTools`. A control plane
+     * only the validated names into `__approvedTools`. The control plane (`apps/api`)
      * is the authority on which tools were approved (drawn from the ApprovalEngine), but
      * the engine re-checks the provenance here — defence in depth on the PRODUCTION
      * resume path. Omitted/empty: an ordinary resume that unlocks no tools.
@@ -2681,4 +2838,4 @@ declare const resumeCatalogGraph: (definition: GraphDefinition, state: GraphStat
 /** Type guard a node carries either catalog carrier. Useful to decide the run path. */
 declare const isCatalogGraph: (definition: GraphDefinition) => boolean;
 
-export { AGENT_APPROVAL_INTERRUPT, type AIMessage, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, AdrianeSdkError, type AgentApprovalBinding, type AgentCarrier, type AgentNodeConfig, type AgentPromptSource, type AgentResult, type AnswerBuilderParams, AnthropicProviderAdapter, type ApproveAndResumeOptions, type ApprovedToolWire, type Bm25RetrieverParams, type CatalogRunOutcome, type ChannelInput, type ChannelReducer, type ChannelUpdate, type ChannelValues, type ChatMessageBuilderParams, type ChatMessageSpec, type Command, CompiledGraph, type CompiledGraphParts, type ComponentCarrier, type ComponentCatalogEntry, type ComponentCategory, type ComponentDescriptor, type ComponentKind, type ComponentParamMeta, type ConditionFn, type ConditionalRouterBranch, type ConditionalRouterParams, type CreateEmbeddingsOptions, type CreateGraphOptions, type CreateVectorStoreOptions, type CsvParserParams, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_REFERENCE_CORPUS, DEFAULT_TIER_TABLE, type DeduplicatorParams, DefaultLLMGateway, type DocQaReferenceOptions, type DocumentJoinerParams, type DocumentSplitterParams, type DocumentWriterParams, DuplicateNodeError, DynamicInterrupt, type Embeddings, type EmbeddingsRequestBody, EmbeddingsResponseError, type EmbeddingsTransport, type EmptyChannels, type EvaluatorParams, type ExampleGraph, type FieldMapperParams, GraphBuilder, GraphCompileError, type GraphDefinition, type GraphState, type GraphStatus, type HtmlToTextParams, type HttpFetchImpl, type HttpFetchParams, type HttpFetchRequestInit, type HttpFetchResponseLike, type HttpFetchResult, InMemoryCheckpointer, InMemoryPromptRegistry, InMemoryToolRegistry, type InitialData, type IntegrationComponentHandler, type JsonValidatorParams, type KeywordRetrieverParams, type LLMGateway, type LLMProvider, type LLMResponse, type LLMStreamChunk, type LLMToolCall, type LanguageDetectorParams, type LexicalDoc, type ListJoinerParams, MODEL_TIERS, type MergeRankerParams, type Message, type MessageId, type MetadataFilterParams, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, type ModelChoice, ModelPolicy, type ModelTier, type ModelTierInfo, type NodeHandler, type NodeId, type NodeInput, type OpenAIChatRequestBody, type OpenAIChatResponse, type OpenAICompatibleAdapterOptions, OpenAICompatibleProviderAdapter, type OpenAICompatibleTransportPort, type OutputParserParams, type PrebuiltAgentCatalogEntry, type PrebuiltOptions, type PredicateOp, type PromptBuilderParams, type PromptRegistry, type RagAnswererOptions, type RegexExtractorParams, type RerankerParams, type ResolveOverride, type Result, type RetrieverDoc, type RetrieverParams, type RouterParams, type RouterRule, type RunCatalogGraphOptions, type RunEvent, type RunId, type RunOptions, type RustAgentConfig, type RustComponentConfig, RustEngineUnavailableError, type RustToolBinding, type SemanticRetrieverDoc, type SemanticRetrieverParams, type SentenceWindowSplitterParams, type StreamAgentConfig, type StreamEvent, type StreamMode, type TextCleanerParams, type TierModelTable, type ToolCall, type ToolDefinition, type ToolId, type ToolNodeConfig, type ToolRegistry, type TruncatorParams, type TypedCondition, type TypedGraphState, type TypedNodeHandler, type VectorStore, type VectorStoreItem, type VectorStoreMatch, type WebSearchImpl, type WebSearchOutcome, type WebSearchParams, type WebSearchResult, type WebSearchTransport, buildDocQaReference, componentCatalog, components, 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, type AIMessage, APPROVAL_IDS_CHANNEL, APPROVED_TOOLS_CHANNEL, AdrianeSdkError, type AgentApprovalBinding, type AgentCarrier, type AgentNodeConfig, type AgentPromptSource, type AgentResult, type AnswerBuilderParams, AnthropicProviderAdapter, type ApproveAndResumeOptions, type ApprovedToolWire, type Bm25RetrieverParams, type CatalogRunOutcome, type ChannelInput, type ChannelReducer, type ChannelUpdate, type ChannelValues, type ChatMessageBuilderParams, type ChatMessageSpec, type Command, CompiledGraph, type CompiledGraphParts, type ComponentCarrier, type ComponentCatalogEntry, type ComponentCategory, type ComponentDescriptor, type ComponentKind, type ComponentParamMeta, type ConditionFn, type ConditionalRouterBranch, type ConditionalRouterParams, type CreateEmbeddingsOptions, type CreateGraphOptions, type CreateVectorStoreOptions, type CsvParserParams, DEFAULT_AGENT_OUTPUT_CHANNEL, DEFAULT_PREFERENCE, DEFAULT_REFERENCE_CORPUS, DEFAULT_TIER_TABLE, type DeduplicatorParams, DefaultLLMGateway, type DocQaReferenceOptions, type DocumentJoinerParams, type DocumentSplitterParams, type DocumentWriterParams, DuplicateNodeError, DynamicInterrupt, type Embeddings, type EmbeddingsRequestBody, EmbeddingsResponseError, type EmbeddingsTransport, type EmptyChannels, type EvaluatorParams, type ExampleGraph, type FieldMapperParams, GraphBuilder, GraphCompileError, type GraphDefinition, type GraphState, type GraphStatus, type HtmlToTextParams, type HttpFetchImpl, type HttpFetchParams, type HttpFetchRequestInit, type HttpFetchResponseLike, type HttpFetchResult, INJECTED_KEY, InMemoryCheckpointer, InMemoryPromptRegistry, InMemoryToolRegistry, type InitialData, type IntegrationComponentHandler, type JsonValidatorParams, type KeywordRetrieverParams, type LLMGateway, type LLMProvider, type LLMResponse, type LLMStreamChunk, type LLMToolCall, type LanguageDetectorParams, type LexicalDoc, type ListJoinerParams, MODEL_TIERS, type MergeRankerParams, type Message, type MessageId, type MetadataFilterParams, MissingEmbeddingsKeyError, MissingHandlerError, MockLLMProviderAdapter, type ModelChoice, ModelPolicy, type ModelTier, type ModelTierInfo, type NodeHandler, type NodeId, type NodeInput, type OpenAIChatRequestBody, type OpenAIChatResponse, type OpenAICompatibleAdapterOptions, OpenAICompatibleProviderAdapter, type OpenAICompatibleTransportPort, type OutputParserParams, type PrebuiltAgentCatalogEntry, type PrebuiltOptions, type PredicateOp, type PromptBuilderParams, type PromptRegistry, type RagAnswererOptions, type RegexExtractorParams, type RerankerParams, type ResolveOverride, type Result, type RetrieverDoc, type RetrieverParams, type RouterParams, type RouterRule, type RunCatalogGraphOptions, type RunEvent, type RunId, type RunOptions, type RustAgentConfig, type RustComponentConfig, RustEngineUnavailableError, type RustToolBinding, SIGNALS_KEY, SLEEP_UNTIL_KEY, SUSPEND_META_KEY, type SemanticRetrieverDoc, type SemanticRetrieverParams, type SentenceWindowSplitterParams, type StreamAgentConfig, type StreamEvent, type StreamMode, type SuspendMeta, type TextCleanerParams, type TierModelTable, type ToolCall, type ToolDefinition, type ToolId, type ToolNodeConfig, type ToolRegistry, type TruncatorParams, type TypedCondition, type TypedGraphState, type TypedNodeHandler, type VectorStore, type VectorStoreItem, type VectorStoreMatch, WAIT_FOR_SIGNAL_KEY, type WebSearchImpl, type WebSearchOutcome, type WebSearchParams, type WebSearchResult, type WebSearchTransport, buildDocQaReference, componentCatalog, components, 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 };