pi-loop-graph-sdk 0.2.0

package/dist/runtime.js

@@ -0,0 +1,258 @@
+// ============================================================
+//  GraphRuntime — 图运行时状态机
+// ============================================================
+export class GraphRuntime {
+    callStack = [];
+    isNodeActive = false;
+    /** 当前节点的语义作用域。details 用于匹配，不依赖消息正文。 */
+    currentScope = null;
+    currentNode = null;
+    currentInput = null;
+    graphRunId = crypto.randomUUID();
+    /** 当前 graph run 已发生的 compaction 次数，仅用于诊断和 checkpoint 观测。 */
+    compactionGeneration = 0;
+    /**
+     * 共享 call/compose 活跃期间异常收到 session_compact 时设为 true。
+     * 此后本 session 投影中将持续过滤 compactionSummary，优先保证不泄漏。
+     */
+    compactionBoundaryViolated = false;
+    /** Runtime 控制平面的 frame → NodeScope 对齐表，不进入开发者 frame/LLM。 */
+    frameScopes = new Map();
+    get top() {
+        return this.callStack.length > 0
+            ? this.callStack[this.callStack.length - 1]
+            : null;
+    }
+    get topInstance() {
+        return this.top?.instance ?? null;
+    }
+    get topGraph() {
+        return this.top?.graph ?? null;
+    }
+    get currentNodeId() {
+        return this.top?.currentNodeId ?? null;
+    }
+    pushGraph(graph, background, boundary = "root", sharedInstance, parentNodeId) {
+        const instance = sharedInstance ?? {
+            id: crypto.randomUUID(),
+            globalGoal: graph.goal,
+            background,
+            frames: [],
+            mechanisms: graph.mechanisms ?? [],
+            scratch: {},
+        };
+        if (!this.frameScopes.has(instance.id))
+            this.frameScopes.set(instance.id, []);
+        this.callStack.push({
+            instance,
+            graph,
+            boundary,
+            localGoal: graph.goal,
+            // root/call 已写入 instance；compose 只在子调用帧叠加，退出即消失。
+            localMechanisms: sharedInstance ? (graph.mechanisms ?? []) : [],
+            callBackground: background,
+            parentNodeId,
+            nodeVisits: new Map(),
+            currentNodeId: null,
+            activeNode: null,
+            activeInput: null,
+            activeScope: null,
+            isNodeActive: false,
+            projectedFrameBase: 0,
+        });
+        return instance;
+    }
+    popGraph() {
+        const popped = this.callStack.pop();
+        this.restoreActiveNodeFromTop();
+        return popped;
+    }
+    beginFrameSegment(graphId, parentNodeId) {
+        const instance = this.topInstance;
+        if (!instance)
+            throw new Error("callStack 为空");
+        return {
+            id: crypto.randomUUID(),
+            graphId,
+            parentNodeId,
+            instanceId: instance.id,
+            baseIndex: instance.frames.length,
+            depth: this.callStack.length + 1,
+        };
+    }
+    readFrameSegment(scope) {
+        const instance = this.assertSegmentOwner(scope);
+        // fold 只能看到独立快照。除顶层 frame 外也复制并冻结 result 的可变数据，
+        // 以免 folder 修改嵌套字段时反向影响 live frames。
+        return Object.freeze(instance.frames.slice(scope.baseIndex).map(snapshotFrame));
+    }
+    rollbackFrameSegment(scope) {
+        const instance = this.assertSegmentOwner(scope);
+        instance.frames.splice(scope.baseIndex);
+        this.frameScopes.get(instance.id)?.splice(scope.baseIndex);
+    }
+    closeFrameSegment(scope, completion) {
+        this.rollbackFrameSegment(scope);
+        return completion;
+    }
+    nextScope(nodeId) {
+        const top = this.top;
+        if (!top)
+            throw new Error("callStack 为空");
+        const visit = (top.nodeVisits.get(nodeId) ?? 0) + 1;
+        top.nodeVisits.set(nodeId, visit);
+        return {
+            protocol: 2,
+            graphRunId: this.graphRunId,
+            instanceId: top.instance.id,
+            scopeId: crypto.randomUUID(),
+            graphId: top.graph.id,
+            nodeId,
+            visit,
+            depth: this.callStack.length,
+        };
+    }
+    enterNode(nodeId, scope, input) {
+        const graph = this.topGraph;
+        if (!graph)
+            throw new Error("callStack 为空");
+        const node = graph.nodes[nodeId];
+        if (!node)
+            throw new Error(`节点未找到: ${nodeId}`);
+        const top = this.top;
+        top.currentNodeId = nodeId;
+        this.currentNode = node;
+        this.currentInput = input;
+        this.currentScope = scope;
+        this.isNodeActive = true;
+        top.activeNode = node;
+        top.activeInput = input;
+        top.activeScope = scope;
+        top.isNodeActive = true;
+        return node;
+    }
+    exitNode(frame) {
+        const instance = this.topInstance;
+        if (!instance)
+            throw new Error("callStack 为空");
+        instance.frames.push(frame);
+        if (this.currentScope)
+            this.frameScopes.get(instance.id)?.push(this.currentScope);
+        this.isNodeActive = false;
+        this.currentNode = null;
+        this.currentInput = null;
+        this.currentScope = null;
+        const top = this.top;
+        if (top) {
+            top.activeNode = null;
+            top.activeInput = null;
+            top.activeScope = null;
+            top.isNodeActive = false;
+        }
+    }
+    /**
+     * 记录一次 session compaction。NodeScope 的身份（scopeId）不变。
+     * Runtime 只推进 projectedFrameBase；pi 原生 summary 与 recent messages
+     * 是压缩历史的权威替代，SDK 不重发 scope，也不遮挡 summary。
+     */
+    recordCompaction(projectedFrameBase) {
+        this.compactionGeneration += 1;
+        const top = this.top;
+        if (top) {
+            const nextBase = projectedFrameBase ?? top.instance.frames.length;
+            top.projectedFrameBase = Math.max(top.projectedFrameBase, Math.min(nextBase, top.instance.frames.length));
+        }
+        return this.compactionGeneration;
+    }
+    /** 当前 callStack 是否存在嵌套 call/compose（非 root-only）。 */
+    get hasActiveSharedCall() {
+        return this.callStack.some((frame) => frame.boundary === "call" || frame.boundary === "compose");
+    }
+    /** 共享调用边界被 compaction 切断后，继续运行会泄漏无法归属的 transcript。 */
+    assertNoCompactionBoundaryViolation() {
+        if (this.compactionBoundaryViolated) {
+            throw new Error("compaction 边界违规：共享 call/compose 已终止，当前 Session 上下文已进入 fail-closed 状态");
+        }
+    }
+    get completedFrameScopes() {
+        const instance = this.topInstance;
+        return instance ? (this.frameScopes.get(instance.id) ?? []) : [];
+    }
+    /** 只返回最近一次 compaction 后新生长、仍需单独投影的开发者 frames。 */
+    get projectedFrames() {
+        const top = this.top;
+        return top ? top.instance.frames.slice(top.projectedFrameBase) : [];
+    }
+    reset() {
+        this.callStack = [];
+        this.isNodeActive = false;
+        this.currentScope = null;
+        this.currentNode = null;
+        this.currentInput = null;
+        this.compactionGeneration = 0;
+        this.compactionBoundaryViolated = false;
+        this.frameScopes.clear();
+    }
+    assertSegmentOwner(scope) {
+        const instance = this.topInstance;
+        if (!instance || instance.id !== scope.instanceId) {
+            throw new Error("FrameSegmentScope 不属于当前调用帧");
+        }
+        if (scope.baseIndex > instance.frames.length) {
+            throw new Error("FrameSegmentScope 的 baseIndex 无效");
+        }
+        return instance;
+    }
+    restoreActiveNodeFromTop() {
+        const top = this.top;
+        this.currentNode = top?.activeNode ?? null;
+        this.currentInput = top?.activeInput ?? null;
+        this.currentScope = top?.activeScope ?? null;
+        this.isNodeActive = top?.isNodeActive ?? false;
+    }
+}
+/** 复制并冻结 compose fold 可见的帧，不向其暴露 live 引用。 */
+function snapshotFrame(frame) {
+    return Object.freeze(snapshotValue(frame));
+}
+/**
+ * NodeCompletion.result 是数据对象。这里不用 structuredClone：业务结果可包含
+ * 无法被它复制的值（例如函数），而函数本身不可通过普通属性写入改变帧数据。
+ * 对常见的对象/数组/Map/Set/Date 递归复制，随后冻结普通对象和数组。
+ */
+function snapshotValue(value, seen = new WeakMap()) {
+    if (value === null || typeof value !== "object")
+        return value;
+    const cached = seen.get(value);
+    if (cached)
+        return cached;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const item of value)
+            copy.push(snapshotValue(item, seen));
+        return Object.freeze(copy);
+    }
+    if (value instanceof Date)
+        return Object.freeze(new Date(value.getTime()));
+    if (value instanceof Map) {
+        const copy = new Map();
+        seen.set(value, copy);
+        for (const [key, item] of value)
+            copy.set(snapshotValue(key, seen), snapshotValue(item, seen));
+        return copy;
+    }
+    if (value instanceof Set) {
+        const copy = new Set();
+        seen.set(value, copy);
+        for (const item of value)
+            copy.add(snapshotValue(item, seen));
+        return copy;
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const [key, item] of Object.entries(value)) {
+        copy[key] = snapshotValue(item, seen);
+    }
+    return Object.freeze(copy);
+}

package/dist/tools-resolve.d.ts

@@ -0,0 +1,20 @@
+export declare const FRAMEWORK_TOOLS: readonly ["read", "__graph_complete__"];
+export interface ToolResolverInput {
+    readonly defaultTools: readonly string[];
+    readonly nodeTools: readonly string[];
+    readonly frameworkTools: typeof FRAMEWORK_TOOLS;
+    readonly graphId?: string;
+    readonly nodeId?: string;
+}
+/** 返回候选工具；SDK 随后统一去重并恢复 framework tools 的首尾不变量。 */
+export type ToolResolver = (input: ToolResolverInput) => readonly string[];
+export declare const defaultToolResolver: ToolResolver;
+/**
+ * 计算节点的最终工具列表。
+ *
+ * 规则：
+ *   [read, ...defaultTools, ...nodeTools, __graph_complete__]
+ *   去重（保留首次出现的位置），read 始终在第一位，
+ *   __graph_complete__ 始终在最后。
+ */
+export declare function resolveNodeTools(defaultTools: readonly string[], nodeTools: readonly string[], resolver?: ToolResolver, identity?: Pick<ToolResolverInput, "graphId" | "nodeId">): string[];

package/dist/tools-resolve.js

@@ -0,0 +1,52 @@
+// ============================================================
+//  工具解析 — 全仓库单一真相源
+// ============================================================
+//
+//  只有一个函数产出最终工具列表。setActiveTools 调它，
+//  debug 日志也调它。
+// ============================================================
+export const FRAMEWORK_TOOLS = ["read", "__graph_complete__"];
+export const defaultToolResolver = ({ defaultTools, nodeTools }) => [
+    ...defaultTools,
+    ...nodeTools,
+];
+/**
+ * 计算节点的最终工具列表。
+ *
+ * 规则：
+ *   [read, ...defaultTools, ...nodeTools, __graph_complete__]
+ *   去重（保留首次出现的位置），read 始终在第一位，
+ *   __graph_complete__ 始终在最后。
+ */
+export function resolveNodeTools(defaultTools, nodeTools, resolver = defaultToolResolver, identity = {}) {
+    const resolved = resolver(Object.freeze({
+        defaultTools: Object.freeze([...defaultTools]),
+        nodeTools: Object.freeze([...nodeTools]),
+        frameworkTools: FRAMEWORK_TOOLS,
+        ...identity,
+    }));
+    if (!Array.isArray(resolved) || resolved.some((name) => typeof name !== "string" || name.length === 0)) {
+        throw new TypeError("toolResolver 必须返回非空工具名数组");
+    }
+    const merged = ["read", ...resolved, "__graph_complete__"];
+    const seen = new Set();
+    const result = [];
+    for (const t of merged) {
+        if (!seen.has(t)) {
+            seen.add(t);
+            result.push(t);
+        }
+    }
+    // 确保 read 在首、__graph_complete__ 在尾
+    const readIdx = result.indexOf("read");
+    if (readIdx > 0) {
+        result.splice(readIdx, 1);
+        result.unshift("read");
+    }
+    const completeIdx = result.indexOf("__graph_complete__");
+    if (completeIdx >= 0 && completeIdx !== result.length - 1) {
+        result.splice(completeIdx, 1);
+        result.push("__graph_complete__");
+    }
+    return result;
+}