pi-loop-graph-sdk 0.2.0

package/dist/adapter/projection.d.ts

@@ -0,0 +1,121 @@
+import type { ContextFrame, Node } from "../type.js";
+import type { NodeScopeDescriptor } from "../runtime.js";
+export interface EdgeChoice {
+    id: string;
+    description: string;
+    priority: number;
+    target: string;
+}
+export interface ProjectionInput {
+    messages: MessageEntry[];
+    frames: ContextFrame[];
+    currentNode: Node | null;
+    activeScope?: NodeScopeDescriptor | null;
+    /** agent-choice 路由下可供 agent 选择的边列表，渲染在 CURRENT 段 */
+    availableEdges?: EdgeChoice[];
+    /** 自定义帧折叠后的 COMPLETED 段内容格式。
+     *  接收所有已完成帧，返回完整文本注入上下文。
+     *  返回 null 则跳过 COMPLETED 段（不折叠）。
+     *  默认：保持当前 JSON 格式（向后兼容）。 */
+    frameFormatter?: (frames: ContextFrame[]) => string | null;
+    /** 活动图已经历 compaction；原生 summary 是此前上下文的权威替代。 */
+    compactionActive?: boolean;
+    /** node-enter 时已冻结的 SDK 合成上下文。仅在活动 scope 锚点缺失时恢复，
+     *  不包含 live ReAct，也不接管 GraphCallScope/compaction 清洗。 */
+    renderedContext?: readonly MessageEntry[];
+}
+export interface MessageEntry {
+    id?: string;
+    role?: string;
+    content?: unknown;
+    /** pi CustomMessage 的 UI 展示标记。 */
+    display?: boolean;
+    /** pi compactionSummary / branchSummary 使用 summary 而不是 content。 */
+    summary?: string;
+    timestamp?: number;
+    customType?: string;
+    details?: unknown;
+}
+export declare function projectMessages(input: ProjectionInput): MessageEntry[];
+/**
+ * 从消息数组中删除已闭合的图调用区段。
+ *
+ * compose / call 子图运行时在当前 session 的 transcript 中产生内部消息（NodeScope、
+ * skill、mechanism、prompt 和 live ReAct）。这些消息由 loop_graph_call_start / end
+ * 区段包围。子图结束后调用方不应再看到这些内部消息——它们必须从上下文中删除。
+ *
+ * 算法：
+ *   1. 从 tail 向 head 扫描，为每个 call_end 寻找最近的前驱 call_start（按 callId 匹配）
+ *   2. 已闭合区段内的全部消息标记为删除
+ *   3. 未闭合的 call_start（图仍在运行中）对应的区段保留
+ *
+ * 此函数始终执行（无论当前是否有活动图），因为之前图调用的闭合区段需要在后续对话中持续清洗。
+ */
+export declare function stripClosedGraphCalls(messages: MessageEntry[]): MessageEntry[];
+/** 默认帧格式化器：保持向后兼容的 JSON 格式（=== COMPLETED === / === END === 包裹）。 */
+export declare const defaultFrameFormatter: (frames: ContextFrame[]) => string;
+type NodeInfoLike = Pick<Node, "id" | "kind" | "subGoal"> & {
+    tools?: readonly string[];
+    skill?: string;
+};
+export declare function buildNodeInfoContent(node: NodeInfoLike, availableEdges?: EdgeChoice[]): string;
+export type RenderedContextContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface RenderedContextMessage {
+    content: string | readonly RenderedContextContentBlock[];
+    kind?: "current" | "completed" | "skill" | "instruction";
+}
+export interface GraphContextView {
+    readonly id: string;
+    readonly goal: string;
+}
+export interface NodeContextView {
+    readonly id: string;
+    readonly kind: Node["kind"];
+    readonly subGoal: string;
+    readonly skill?: string;
+    readonly tools: readonly string[];
+    readonly boundary?: import("../type.js").GraphInvocationBoundary;
+    readonly childGraphId?: string;
+}
+export interface NodeInputView {
+    readonly data: Readonly<Record<string, unknown>>;
+    readonly source: Readonly<import("../type.js").NodeInput["source"]>;
+}
+export interface NodeContextRenderInput {
+    graph: GraphContextView;
+    node: NodeContextView;
+    input: NodeInputView;
+    /** node-enter 时 Runtime 已选择的 frame 快照。COMPLETED 主投影仍由
+     * frameFormatter 管理，避免 compaction 后重复投影旧 frame。 */
+    frames: readonly ContextFrame[];
+    availableEdges: readonly EdgeChoice[];
+    skill: {
+        ref: string;
+        content: string;
+        message: RenderedContextMessage | null;
+        showRefInCurrent: boolean;
+    } | null;
+    completion: {
+        toolName: "__graph_complete__";
+        statuses: readonly ["ok", "failed", "cancelled"];
+    };
+    reason: "node-enter";
+}
+export interface RenderedNodeContext {
+    /** NodeScope 锚点的模型可见正文。null 表示使用空正文，但安全锚点仍存在。 */
+    anchor: RenderedContextMessage | null;
+    /** 锚点之后追加的其它 SDK 合成消息。 */
+    additional?: readonly RenderedContextMessage[];
+}
+export type NodeContextRenderer = (input: NodeContextRenderInput) => RenderedNodeContext | null;
+/** 兼容 renderer：保持当前 CURRENT 与 skill 消息的正文格式。历史 frames 继续
+ * 由 frameFormatter 投影，使 compaction baseline 可以独立推进。 */
+export declare const defaultNodeContextRenderer: NodeContextRenderer;
+export {};

package/dist/adapter/projection.js

@@ -0,0 +1,169 @@
+// ============================================================
+//  投影 — context 钩子的消息组装（纯函数）
+// ============================================================
+export function projectMessages(input) {
+    const { messages, frames, currentNode, activeScope } = input;
+    const currentIdx = activeScope ? findLastMatchingScope(messages, activeScope) : -1;
+    const result = [];
+    const summaryIdx = input.compactionActive ? findLastCompactionSummary(messages) : -1;
+    // pi 的 summary + recent messages 是压缩后上下文的权威表达。若活动 scope
+    // 仍在保留区，只保留 summary 与该 scope 后内容；若 scope 已被压缩，则在
+    // summary 后恢复 CURRENT，并保留所有 recent messages。
+    if (summaryIdx >= 0)
+        result.push(messages[summaryIdx]);
+    // frame 段
+    if (frames.length > 0) {
+        const fmt = input.frameFormatter ?? defaultFrameFormatter;
+        const content = fmt(frames);
+        if (content != null) {
+            result.push({
+                role: "user",
+                content,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    if (currentIdx >= 0) {
+        const includeAnchor = messages[currentIdx]?.customType === "loop_graph_node_scope";
+        result.push(...messages.slice(currentIdx + (includeAnchor ? 0 : 1)));
+    }
+    else if (currentNode) {
+        const recovered = input.renderedContext?.length
+            ? input.renderedContext
+            : [buildNodeInfo(currentNode, input.availableEdges)];
+        result.push(...recovered);
+        if (summaryIdx >= 0) {
+            result.push(...messages.slice(summaryIdx + 1).filter((message) => message.customType !== "loop_graph_mechanism" ||
+                (activeScope != null && isScopedMechanismMessage(message, activeScope))));
+        }
+        else if (activeScope) {
+            // scope anchor 丢失时只恢复带 SDK 固定 scope 元数据的 mechanism 消息。
+            // prompt/live ReAct 没有可证明归属，继续 fail closed。
+            result.push(...messages.filter((message) => isScopedMechanismMessage(message, activeScope)));
+        }
+    }
+    return result;
+}
+function isScopedMechanismMessage(message, activeScope) {
+    if (message.customType !== "loop_graph_mechanism")
+        return false;
+    const details = message.details;
+    return details?.protocol === 1 && details.scopeId === activeScope.scopeId;
+}
+// ── GraphCallScope 清洗（Phase 9）─────────────────────────
+/**
+ * 从消息数组中删除已闭合的图调用区段。
+ *
+ * compose / call 子图运行时在当前 session 的 transcript 中产生内部消息（NodeScope、
+ * skill、mechanism、prompt 和 live ReAct）。这些消息由 loop_graph_call_start / end
+ * 区段包围。子图结束后调用方不应再看到这些内部消息——它们必须从上下文中删除。
+ *
+ * 算法：
+ *   1. 从 tail 向 head 扫描，为每个 call_end 寻找最近的前驱 call_start（按 callId 匹配）
+ *   2. 已闭合区段内的全部消息标记为删除
+ *   3. 未闭合的 call_start（图仍在运行中）对应的区段保留
+ *
+ * 此函数始终执行（无论当前是否有活动图），因为之前图调用的闭合区段需要在后续对话中持续清洗。
+ */
+export function stripClosedGraphCalls(messages) {
+    // 从尾部收集已闭合的区段
+    const closedRanges = [];
+    const endStack = [];
+    // tail → head 单次扫描：遇到 call_end 压栈，遇到匹配的 call_start 弹出并记录区段
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.customType === "loop_graph_call_end") {
+            const d = m.details;
+            if (d?.callId && typeof d.callId === "string") {
+                endStack.push({ callId: d.callId, endIdx: i });
+            }
+        }
+        else if (m.customType === "loop_graph_call_start") {
+            const d = m.details;
+            if (d?.callId && typeof d.callId === "string") {
+                // 找最近匹配的 call_end
+                for (let j = endStack.length - 1; j >= 0; j--) {
+                    if (endStack[j].callId === d.callId) {
+                        closedRanges.push([i, endStack[j].endIdx]);
+                        endStack.splice(j, 1);
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    if (closedRanges.length === 0)
+        return messages;
+    // 构建排除索引集合
+    const exclude = new Set();
+    for (const [start, end] of closedRanges) {
+        for (let i = start; i <= end; i++)
+            exclude.add(i);
+    }
+    return messages.filter((_, i) => !exclude.has(i));
+}
+function findLastMatchingScope(messages, activeScope) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        if (isMatchingScope(messages[index], activeScope))
+            return index;
+    }
+    return -1;
+}
+function isMatchingScope(message, activeScope) {
+    if (message.customType !== "loop_graph_node_scope")
+        return false;
+    const details = message.details;
+    return details?.protocol === 2 && details.scopeId === activeScope.scopeId;
+}
+/** 默认帧格式化器：保持向后兼容的 JSON 格式（=== COMPLETED === / === END === 包裹）。 */
+export const defaultFrameFormatter = (frames) => `=== COMPLETED ===\n${JSON.stringify(frames)}\n=== END ===`;
+function findLastCompactionSummary(messages) {
+    for (let index = messages.length - 1; index >= 0; index--) {
+        if (messages[index].role === "compactionSummary")
+            return index;
+    }
+    return -1;
+}
+export function buildNodeInfoContent(node, availableEdges) {
+    const lines = ["=== CURRENT ==="];
+    lines.push(`nodeId: ${node.id}`);
+    lines.push(`subGoal: ${node.subGoal}`);
+    if (node.kind === "code") {
+        if (node.tools?.length)
+            lines.push(`tools: ${node.tools.join(", ")}`);
+        if (node.skill)
+            lines.push(`skill: ${node.skill}`);
+    }
+    // agent-choice 路由：渲染可用边列表供 agent 决策
+    if (availableEdges && availableEdges.length > 0) {
+        lines.push("");
+        lines.push("availableEdges（请在 __graph_complete__ 的 result.chosen_edge_id 中选择一条）:");
+        for (const e of availableEdges) {
+            const targetLabel = e.target === "Symbol(graph.end)" ? "END" : (e.target || "?");
+            lines.push(`  • ${e.id} (priority: ${e.priority}) → ${targetLabel}`);
+            lines.push(`    ${e.description}`);
+        }
+    }
+    lines.push("completeWith: __graph_complete__({ status, result })");
+    lines.push("=== END ===");
+    return lines.join("\n");
+}
+/** 兼容 renderer：保持当前 CURRENT 与 skill 消息的正文格式。历史 frames 继续
+ * 由 frameFormatter 投影，使 compaction baseline 可以独立推进。 */
+export const defaultNodeContextRenderer = (input) => {
+    const additional = [];
+    if (input.skill?.message)
+        additional.push(input.skill.message);
+    return {
+        anchor: {
+            kind: "current",
+            content: buildNodeInfoContent(input.skill && !input.skill.showRefInCurrent
+                ? { ...input.node, skill: undefined }
+                : input.node, [...input.availableEdges]),
+        },
+        additional,
+    };
+};
+function buildNodeInfo(node, availableEdges) {
+    return { role: "user", content: buildNodeInfoContent(node, availableEdges), timestamp: Date.now() };
+}

package/dist/adapter/skill-content.d.ts

@@ -0,0 +1,16 @@
+import type { GraphContextView, NodeContextView, NodeInputView, RenderedContextMessage } from "./projection.js";
+export interface SkillLoadContext {
+    readonly graph: GraphContextView;
+    readonly node: NodeContextView;
+    readonly input: NodeInputView;
+    readonly basePath: string;
+}
+export type SkillContentProvider = (ref: string, context: SkillLoadContext) => Promise<string | null>;
+export type SkillContentRenderer = (ref: string, content: string, context: SkillLoadContext) => RenderedContextMessage | null;
+export type SkillFailurePolicy = "ignore" | "fail";
+export interface SkillFailurePolicies {
+    missing?: SkillFailurePolicy;
+    error?: SkillFailurePolicy;
+}
+export declare const defaultSkillContentProvider: SkillContentProvider;
+export declare const defaultSkillContentRenderer: SkillContentRenderer;

package/dist/adapter/skill-content.js

@@ -0,0 +1,16 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const defaultSkillContentProvider = async (ref, context) => {
+    try {
+        return await readFile(join(context.basePath, ref, "SKILL.md"), "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        throw error;
+    }
+};
+export const defaultSkillContentRenderer = (ref, content) => ({
+    kind: "skill",
+    content: `[skill: ${ref}]\n\n${content}`,
+});

package/dist/advanced.d.ts

@@ -0,0 +1,32 @@
+/** Advanced, opt-in runtime and extension points. */
+export { AgentExecutionFailure, GraphRuntime } from "./runtime/graph-runtime.js";
+export type { GraphRuntimeHost, AgentExecutionContext, InvocationBoundary, InvocationOutcome } from "./runtime/graph-runtime.js";
+export { ContextState, materializeProjection } from "./core/context.js";
+export type { ContextProjection } from "./core/graph.js";
+export type { ContextContribution, ContextContributionHandle, ContextLayer, ContextLifetime, ContextRetention, ContextSnapshot, ContextStateOptions, NodeContextMaterialization, } from "./core/context.js";
+export { validateGraph, assertValidGraph, validateGraphTools } from "./validate.js";
+export type { GraphValidationIssue, GraphValidationOptions } from "./validate.js";
+export { selectEdge } from "./router.js";
+export type { ToolResolver, ToolResolverInput } from "./tools-resolve.js";
+export { defaultToolResolver, resolveNodeTools, FRAMEWORK_TOOLS } from "./tools-resolve.js";
+export type { UnsafeToolResolver, UnsafeToolResolverInput } from "./host/tool-catalog.js";
+export { resolveHostBaseline } from "./host/baseline.js";
+export type { HostBaseline } from "./host/baseline.js";
+export type { GraphExecutionHost, IsolatedGraphSession, IsolatedSessionGraphHostOptions } from "./adapter/graph-execution-host.js";
+export { IsolatedSessionGraphHost } from "./adapter/graph-execution-host.js";
+export { ToolCatalog } from "./host/tool-catalog.js";
+export type { ToolImplementation } from "./host/tool-catalog.js";
+export { SkillCatalog } from "./host/skill-catalog.js";
+export type { SkillResolver } from "./host/skill-catalog.js";
+export { GraphCatalog } from "./host/graph-catalog.js";
+export { createJsonlTraceSink } from "./adapter/observability.js";
+export type { AgentRunLifecycleContext, LoopGraphLifecycleEvent, LoopGraphLogger, LoopGraphTraceSink, } from "./adapter/observability.js";
+export { defaultCompletionFeedbackFormatter, } from "./adapter/loop-graph-extension.js";
+export type { CompletionFeedbackFormatter, CompletionFeedbackInput, ContextRendererRegistry, } from "./adapter/loop-graph-extension.js";
+export { DEFAULT_OUTPUT_CONTRACT_MAX_BYTES, OUTPUT_CONTRACT_MESSAGE_TYPE, prepareOutputContract, } from "./adapter/output-contract.js";
+export type { PreparedOutputContract } from "./adapter/output-contract.js";
+export type { DeadRunMessageInput, GraphFailureMessageInput, IncompleteNodeMessageInput, ModelMessageFormatter, } from "./adapter/model-messages.js";
+export { defaultSkillContentProvider, defaultSkillContentRenderer, } from "./adapter/skill-content.js";
+export type { SkillContentProvider, SkillContentRenderer, SkillFailurePolicies, SkillFailurePolicy, SkillLoadContext, } from "./adapter/skill-content.js";
+export { DEFAULT_HOST_BASELINE } from "./host/baseline.js";
+export { DEFAULT_INVOCATION_LIMITS, resolveInvocationLimits } from "./core/limits.js";

package/dist/advanced.js

@@ -0,0 +1,17 @@
+/** Advanced, opt-in runtime and extension points. */
+export { AgentExecutionFailure, GraphRuntime } from "./runtime/graph-runtime.js";
+export { ContextState, materializeProjection } from "./core/context.js";
+export { validateGraph, assertValidGraph, validateGraphTools } from "./validate.js";
+export { selectEdge } from "./router.js";
+export { defaultToolResolver, resolveNodeTools, FRAMEWORK_TOOLS } from "./tools-resolve.js";
+export { resolveHostBaseline } from "./host/baseline.js";
+export { IsolatedSessionGraphHost } from "./adapter/graph-execution-host.js";
+export { ToolCatalog } from "./host/tool-catalog.js";
+export { SkillCatalog } from "./host/skill-catalog.js";
+export { GraphCatalog } from "./host/graph-catalog.js";
+export { createJsonlTraceSink } from "./adapter/observability.js";
+export { defaultCompletionFeedbackFormatter, } from "./adapter/loop-graph-extension.js";
+export { DEFAULT_OUTPUT_CONTRACT_MAX_BYTES, OUTPUT_CONTRACT_MESSAGE_TYPE, prepareOutputContract, } from "./adapter/output-contract.js";
+export { defaultSkillContentProvider, defaultSkillContentRenderer, } from "./adapter/skill-content.js";
+export { DEFAULT_HOST_BASELINE } from "./host/baseline.js";
+export { DEFAULT_INVOCATION_LIMITS, resolveInvocationLimits } from "./core/limits.js";

package/dist/builders/graph.d.ts

@@ -0,0 +1,27 @@
+import type { TSchema } from "typebox";
+import type { Graph, GraphDefinition, NodeDefinition } from "../core/graph.js";
+export { defineGraph } from "../core/graph.js";
+export declare function defineSingleAgentGraph<TInputSchema extends TSchema, TOutputSchema extends TSchema, TBackground extends import("../core/json.js").JsonValue, TMemory extends import("../core/json.js").JsonValue = import("../core/json.js").JsonValue>(input: {
+    id: string;
+    version: string;
+    goal: string;
+    input: TInputSchema;
+    output: TOutputSchema;
+    context: GraphDefinition<TInputSchema, TOutputSchema, TBackground, TMemory>["context"];
+    node: Extract<NodeDefinition, {
+        kind: "agent";
+    }>;
+    tools?: GraphDefinition<TInputSchema, TOutputSchema>["tools"];
+    skills?: GraphDefinition<TInputSchema, TOutputSchema>["skills"];
+}): Graph<TInputSchema, TOutputSchema, TBackground, TMemory>;
+export declare function defineLinearGraph<TInputSchema extends TSchema, TOutputSchema extends TSchema, TBackground extends import("../core/json.js").JsonValue, TMemory extends import("../core/json.js").JsonValue = import("../core/json.js").JsonValue>(input: {
+    id: string;
+    version: string;
+    goal: string;
+    input: TInputSchema;
+    output: TOutputSchema;
+    context: GraphDefinition<TInputSchema, TOutputSchema, TBackground, TMemory>["context"];
+    nodes: readonly NodeDefinition[];
+    tools?: GraphDefinition<TInputSchema, TOutputSchema>["tools"];
+    skills?: GraphDefinition<TInputSchema, TOutputSchema>["skills"];
+}): Graph<TInputSchema, TOutputSchema, TBackground, TMemory>;

package/dist/builders/graph.js

@@ -0,0 +1,39 @@
+import { defineGraph } from "../core/graph.js";
+export { defineGraph } from "../core/graph.js";
+export function defineSingleAgentGraph(input) {
+    const stages = {
+        main: {
+            node: input.node,
+            route: {
+                kind: "first-match",
+                connections: [{
+                        id: "finish",
+                        to: "__graph_finish__",
+                        transition: { output: ({ completion }) => completion.result },
+                    }],
+            },
+        },
+    };
+    return defineGraph({ ...input, entries: [{ id: "main", to: "main" }], stages });
+}
+export function defineLinearGraph(input) {
+    const stages = {};
+    input.nodes.forEach((node, index) => {
+        const id = node.identity?.name ?? `stage-${index + 1}`;
+        const next = input.nodes[index + 1]?.identity?.name ?? (index + 1 < input.nodes.length ? `stage-${index + 2}` : "__graph_finish__");
+        stages[id] = {
+            node,
+            route: {
+                kind: "first-match",
+                connections: [{
+                        id: next === "__graph_finish__" ? "finish" : `to-${next}`,
+                        to: next,
+                        transition: next === "__graph_finish__"
+                            ? { output: ({ completion }) => completion.result }
+                            : { map: ({ completion }) => completion.result },
+                    }],
+            },
+        };
+    });
+    return defineGraph({ ...input, entries: [{ id: "main", to: Object.keys(stages)[0] ?? "" }], stages });
+}

package/dist/builders/node.d.ts

@@ -0,0 +1,8 @@
+import type { TSchema } from "typebox";
+import type { AgentNodeDefinition, CodeNodeDefinition, GraphNodeDefinition } from "../core/graph.js";
+import type { JsonValue } from "../core/json.js";
+export declare function agentNode<TInputSchema extends TSchema, TOutputSchema extends TSchema, TFocus extends JsonValue = JsonValue>(input: Omit<AgentNodeDefinition<TInputSchema, TOutputSchema, TFocus>, "kind">): AgentNodeDefinition<TInputSchema, TOutputSchema, TFocus>;
+export declare function codeNode<TInputSchema extends TSchema, TOutputSchema extends TSchema, TFocus extends JsonValue = JsonValue>(input: Omit<CodeNodeDefinition<TInputSchema, TOutputSchema, TFocus>, "kind">): CodeNodeDefinition<TInputSchema, TOutputSchema, TFocus>;
+export declare function graphNode<TInputSchema extends TSchema, TOutputSchema extends TSchema>(input: Omit<GraphNodeDefinition<TInputSchema, TOutputSchema>, "kind" | "boundary"> & {
+    boundary?: GraphNodeDefinition["boundary"];
+}): GraphNodeDefinition<TInputSchema, TOutputSchema>;

package/dist/builders/node.js

@@ -0,0 +1,9 @@
+export function agentNode(input) {
+    return Object.freeze({ ...input, kind: "agent" });
+}
+export function codeNode(input) {
+    return Object.freeze({ ...input, kind: "code" });
+}
+export function graphNode(input) {
+    return Object.freeze({ ...input, kind: "graph", boundary: input.boundary ?? "call" });
+}

package/dist/builders/refs.d.ts

@@ -0,0 +1,5 @@
+import type { SkillRef } from "../core/skill.js";
+export type { SkillRef } from "../core/skill.js";
+export type ToolSet<TNames extends readonly string[] = readonly string[]> = TNames;
+export declare function skillRef(name: string, version?: string, required?: boolean): SkillRef;
+export declare function toolSet<const TNames extends readonly string[]>(...names: TNames): ToolSet<TNames>;

package/dist/builders/refs.js

@@ -0,0 +1,10 @@
+export function skillRef(name, version, required = true) {
+    if (!name)
+        throw new Error("SkillRef requires a name");
+    return Object.freeze({ name, version, required });
+}
+export function toolSet(...names) {
+    if (new Set(names).size !== names.length)
+        throw new Error("ToolSet contains duplicate names");
+    return Object.freeze([...names]);
+}

package/dist/builders/route.d.ts

@@ -0,0 +1,11 @@
+import type { JsonValue } from "../core/json.js";
+import type { Connection, Entry, Route, Transition } from "../core/graph.js";
+export interface ConnectionDraft<TCompletion extends JsonValue = JsonValue, TFrame extends JsonValue = JsonValue, TInput extends JsonValue = JsonValue> {
+    readonly to: Connection["to"];
+    readonly transition: Transition<TCompletion, TFrame, TInput>;
+}
+export declare function entry<TInput = JsonValue>(id: string, config: Omit<Entry<TInput>, "id">): Entry<TInput>;
+export declare function defineTransition<TCompletion extends JsonValue = JsonValue, TFrame extends JsonValue = JsonValue, TInput extends JsonValue = JsonValue>(transition: Transition<TCompletion, TFrame, TInput>): Transition<TCompletion, TFrame, TInput>;
+export declare function connect<TCompletion extends JsonValue = JsonValue, TFrame extends JsonValue = JsonValue, TInput extends JsonValue = JsonValue>(to: string, transition?: Transition<TCompletion, TFrame, TInput>): ConnectionDraft<TCompletion, TFrame, TInput>;
+export declare function finish<TCompletion extends JsonValue = JsonValue, TFrame extends JsonValue = JsonValue>(transition?: Transition<TCompletion, TFrame, never>): ConnectionDraft<TCompletion, TFrame, never>;
+export declare function firstMatch(connections: Readonly<Record<string, ConnectionDraft<any, any, any>>>): Route;

package/dist/builders/route.js

@@ -0,0 +1,18 @@
+export function entry(id, config) {
+    return Object.freeze({ id, ...config });
+}
+export function defineTransition(transition) {
+    return Object.freeze({ ...transition });
+}
+export function connect(to, transition = {}) {
+    return Object.freeze({ to, transition });
+}
+export function finish(transition = {}) {
+    return Object.freeze({ to: "__graph_finish__", transition });
+}
+export function firstMatch(connections) {
+    return Object.freeze({
+        kind: "first-match",
+        connections: Object.freeze(Object.entries(connections).map(([id, connection]) => Object.freeze({ id, ...connection }))),
+    });
+}

package/dist/core/context.d.ts

@@ -0,0 +1,73 @@
+import type { ContextContent, ContextProjection, Graph, Stage } from "./graph.js";
+import type { JsonValue } from "./json.js";
+import type { ResolvedSkillView } from "./skill.js";
+export type ContextRetention = "sticky" | "foldable" | "transient";
+export type ContextLifetime = "agent-run" | "node-visit" | "graph-invocation" | "root-run";
+export interface ContextContribution {
+    readonly id: string;
+    readonly owner: "host" | "graph" | "node" | "agent-run" | "runtime";
+    readonly scopeId: string;
+    readonly lifetime: ContextLifetime;
+    readonly retention: ContextRetention;
+    readonly content: ContextContent;
+}
+export interface ContextContributionHandle {
+    readonly id: string;
+    update(content: ContextContent): void;
+    dispose(): void;
+}
+export interface ContextLayer {
+    readonly name: "host" | "graph" | "memory" | "node" | "mechanism" | "output-contract" | "prompt";
+    readonly scopeId: string;
+    readonly retention: ContextRetention;
+    readonly content: ContextContent;
+}
+export interface ContextSnapshot {
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId?: string;
+    readonly agentRunId?: string;
+    readonly graphId: string;
+    readonly graphVersion: string;
+    readonly memoryRevision: number;
+    readonly layers: readonly ContextLayer[];
+    readonly contributions: readonly ContextContribution[];
+}
+export interface ContextStateOptions {
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly graph: Graph;
+    readonly graphInput: JsonValue;
+    readonly graphSkills: readonly ResolvedSkillView[];
+    readonly frames: readonly JsonValue[];
+    readonly hostContent?: ContextContent | null;
+    readonly frameRevision?: {
+        value: number;
+    };
+    readonly externalContributions?: (nodeVisitId?: string) => readonly ContextContribution[];
+}
+export interface NodeContextMaterialization {
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+    readonly snapshot: ContextSnapshot;
+}
+/** Canonical, scope-owned context state for one Graph Invocation. */
+export declare class ContextState {
+    private readonly options;
+    private graphLayers;
+    private readonly contributions;
+    private readonly frameRevision;
+    private memoryCache;
+    constructor(options: ContextStateOptions);
+    initialize(): Promise<void>;
+    bumpMemoryRevision(): void;
+    materializeNode(nodeVisitId: string, stageId: string, stage: Stage, nodeInput: JsonValue, nodeSkills: readonly ResolvedSkillView[]): Promise<NodeContextMaterialization>;
+    snapshot(nodeVisitId?: string, layers?: readonly ContextLayer[]): ContextSnapshot;
+    refreshSnapshot(snapshot: ContextSnapshot, agentRunId?: string): ContextSnapshot;
+    addContribution(contribution: ContextContribution): ContextContributionHandle;
+    private materializeMemory;
+}
+export declare function materializeProjection<TSource, TSelected extends JsonValue, TMeta>(projection: ContextProjection<TSource, TSelected, TMeta>, source: TSource, meta: TMeta, fallback: (input: {
+    readonly selected: Readonly<TSelected> | null;
+    readonly meta: Readonly<TMeta>;
+}) => ContextContent | null): Promise<ContextContent | null>;