pi-loop-graph-sdk 0.2.0

package/dist/adapter/debug-log.js

@@ -0,0 +1,151 @@
+// ============================================================
+//  Debug Logger — 记录每层的输入、输出、帧栈
+// ============================================================
+//
+//  输出到项目根目录 loop-graph-debug.log（JSONL 格式）。
+//  每条日志含 timestamp + type + data。
+// ============================================================
+import * as fs from "node:fs";
+import * as path from "node:path";
+const LOG_PATH = path.resolve("loop-graph-debug.log");
+let fileOpened = false;
+/** 截断序列化帧的预览，避免日志爆量。 */
+export function safePreview(value, maxLength = 500) {
+    try {
+        const s = JSON.stringify(value);
+        if (s === undefined)
+            return "[unserializable]";
+        return s.length <= maxLength ? s : s.slice(0, maxLength) + "…";
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+function log(entry) {
+    // 文件调试是显式 opt-in；正常 SDK 使用不产生工作区文件。
+    if (process.env.PI_LOOP_GRAPH_DEBUG !== "1")
+        return;
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry });
+    if (!fileOpened) {
+        fs.writeFileSync(LOG_PATH, "", "utf-8");
+        fileOpened = true;
+    }
+    fs.appendFileSync(LOG_PATH, line + "\n", "utf-8");
+}
+export const debugLog = {
+    preview(value, maxLength) {
+        return safePreview(value, maxLength);
+    },
+    /** 图启动 */
+    graphStart(graphId, trigger) {
+        log({ type: "graph_start", graphId, trigger });
+    },
+    /** 进入节点 */
+    enterNode(depth, nodeId, scopeId, input, frames) {
+        log({
+            type: "enter_node",
+            depth,
+            nodeId,
+            scopeId,
+            inputData: input.data,
+            frameCount: frames.length,
+        });
+    },
+    /** 退出节点（折叠帧）。控制信息来自 completion；frame 作为 opaque payload。 */
+    exitNode(depth, nodeId, completion, frame, allFrames) {
+        log({
+            type: "exit_node",
+            depth,
+            nodeId,
+            status: completion.status,
+            resultKeys: Object.keys(completion.result),
+            framePreview: safePreview(frame),
+            totalFrames: allFrames.length,
+        });
+    },
+    /** context 钩子投影 */
+    projection(input, output) {
+        log({
+            type: "projection",
+            messageCount: input.messages.length,
+            scopeId: input.activeScope?.scopeId ?? null,
+            splitFound: input.activeScope
+                ? input.messages.some((m) => m.customType === "loop_graph_node_scope" &&
+                    m.details?.scopeId === input.activeScope?.scopeId)
+                : false,
+            frameCount: input.frames.length,
+            currentNode: input.currentNode?.id ?? null,
+            frameMsgCount: output.filter((m) => typeof m.content === "string" && m.content.startsWith("=== COMPLETED")).length,
+            currentMsgCount: output.filter((m) => typeof m.content === "string" && m.content.startsWith("=== CURRENT")).length,
+            otherCount: output.filter((m) => typeof m.content !== "string" || !m.content.startsWith("===")).length,
+            messageTypes: output.slice(0, 8).map((m) => m.customType ?? m.role ?? "?"),
+        });
+    },
+    /** 图运行期间发生 compaction 后记录 checkpoint 信息。 */
+    scopeCheckpoint(scopeId, generation, reason, willRetry) {
+        log({ type: "scope_checkpoint", scopeId, generation, reason, willRetry });
+    },
+    /** 共享 Session 的嵌套调用期间阻止 compaction 跨越 GraphCallScope。 */
+    compactionBlocked(reason, depth) {
+        log({ type: "compaction_blocked", reason, depth });
+    },
+    /** agent 完成（__graph_complete__ 被调用） */
+    agentComplete(nodeId, completion) {
+        log({
+            type: "agent_complete",
+            nodeId,
+            status: completion.status,
+            resultKeys: Object.keys(completion.result),
+        });
+    },
+    /** agent 未调用 __graph_complete__ 就结束 */
+    agentIncomplete(nodeId) {
+        log({ type: "agent_incomplete", nodeId });
+    },
+    /** 完成验证不通过，触发重试 */
+    agentRetry(nodeId, reason) {
+        log({ type: "agent_retry", nodeId, reason });
+    },
+    /** 图结束。控制信息来自 result；frames 作为 opaque payload。 */
+    graphEnd(graphId, steps, resultStatus, resultPreview, frames) {
+        log({
+            type: "graph_end",
+            graphId,
+            steps,
+            status: resultStatus,
+            resultPreview,
+            frameCount: frames.length,
+        });
+    },
+    /** 图错误 */
+    graphError(graphId, error) {
+        log({ type: "graph_error", graphId, error });
+    },
+    /** 子图 push */
+    subgraphPush(parentNodeId, childGraphId) {
+        log({ type: "subgraph_push", parentNodeId, childGraphId });
+    },
+    /** 子图 pop */
+    subgraphPop(parentNodeId, childGraphId, result) {
+        log({ type: "subgraph_pop", parentNodeId, childGraphId, resultKeys: typeof result === "object" && result ? Object.keys(result) : [] });
+    },
+    frameSegmentStart(graphId, parentNodeId, baseIndex, depth) {
+        log({ type: "frame_segment_start", graphId, parentNodeId, baseIndex, depth });
+    },
+    frameSegmentClose(graphId, parentNodeId, frames, completion) {
+        log({
+            type: "frame_segment_close",
+            graphId,
+            parentNodeId,
+            frameCount: frames.length,
+            foldedCompletion: completion,
+        });
+    },
+    frameSegmentRollback(graphId, parentNodeId, reason) {
+        log({ type: "frame_segment_rollback", graphId, parentNodeId, reason });
+    },
+    /** 工具切换 */
+    toolsChanged(nodeId, tools) {
+        log({ type: "tools_changed", nodeId, tools });
+    },
+};

package/dist/adapter/extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function loopGraphDebugExtension(pi: ExtensionAPI): void;

package/dist/adapter/extension.js

@@ -0,0 +1,11 @@
+// ============================================================
+//  Loop Graph Extension — pi 自动加载入口
+// ============================================================
+//
+//  业务 extension 通常应直接使用 createLoopGraphExtension(pi)，
+//  注册自己的图并显式暴露 command/tool。
+// ============================================================
+import { createLoopGraphExtension } from "./loop-graph-extension.js";
+export default function loopGraphDebugExtension(pi) {
+    createLoopGraphExtension(pi);
+}

package/dist/adapter/graph-execution-host.d.ts

@@ -0,0 +1,73 @@
+import type { Graph, GraphInvocationBoundary, GraphRunRequest, GraphRunResult } from "../type.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** 为旧调用（仅有 invocationKind，无 boundary）填补默认值。
+ *  旧 `"subgraph"` → `graph-node` + `call`。 */
+export declare function normalizeGraphRunRequest(partial: {
+    background: Record<string, unknown>;
+    invocationKind: string;
+    boundary?: GraphInvocationBoundary;
+    signal?: AbortSignal;
+}): GraphRunRequest;
+/** 图执行载体。不同实现可以承载进程内子会话、子进程或远程 worker。 */
+export interface GraphExecutionHost {
+    run(graph: Graph, request: GraphRunRequest): Promise<GraphRunResult>;
+    dispose(): Promise<void>;
+}
+/** 创建 delegate host 时可用的调用现场；不包含外层 transcript。 */
+export interface GraphHostContext {
+    pi: ExtensionAPI;
+    extensionContext?: ExtensionContext;
+    graph: Graph;
+    request: GraphRunRequest;
+}
+export type DelegateHostFactory = (context: GraphHostContext) => Promise<GraphExecutionHost>;
+/** 入口无关的统一图调用器。第三个参数只提供运行配置，不改变业务请求。 */
+export interface GraphInvoker {
+    invoke(graph: Graph, request: GraphRunRequest, extensionContext?: ExtensionContext): Promise<GraphRunResult>;
+}
+/** 每次 invoke 创建一次性 host，并固定执行 run → abort/dispose 生命周期。 */
+export declare class DelegateGraphInvoker implements GraphInvoker {
+    private readonly pi;
+    private readonly createHost;
+    constructor(pi: ExtensionAPI, createHost: DelegateHostFactory);
+    invoke(graph: Graph, request: GraphRunRequest, extensionContext?: ExtensionContext): Promise<GraphRunResult>;
+}
+/**
+ * IsolatedSessionGraphHost 使用的最小子会话句柄。
+ *
+ * sessionFactory 后续由 pi adapter 通过 createAgentSession() 构造，并在
+ * runtime-only extension factory 中绑定 executeGraph。Host 本身只负责严格的
+ * run/abort/dispose 生命周期，不依赖 pi 的私有 API。
+ */
+export interface IsolatedGraphSession {
+    run(graph: Graph, request: GraphRunRequest): Promise<GraphRunResult>;
+    abort(): Promise<void>;
+    dispose(): void;
+}
+export type IsolatedGraphSessionFactory = (request: GraphRunRequest) => Promise<IsolatedGraphSession>;
+export interface IsolatedSessionGraphHostOptions {
+    createSession: IsolatedGraphSessionFactory;
+}
+/**
+ * 为一次 graph-tool 调用持有一个独立子 AgentSession 的生命周期外壳。
+ *
+ * 契约：
+ * - 一个 host 同时只运行一张图；并发调用应创建多个 host。
+ * - outer AbortSignal 会转发给子会话 abort()。
+ * - dispose 顺序固定为 abort() -> dispose()。
+ * - dispose 后拒绝 run()，弥补 AgentSession.dispose() 仍允许 prompt 的行为。
+ */
+export declare class IsolatedSessionGraphHost implements GraphExecutionHost {
+    private readonly options;
+    private session;
+    private sessionPromise;
+    private cleanedSession;
+    private disposed;
+    private running;
+    private disposing;
+    constructor(options: IsolatedSessionGraphHostOptions);
+    run(graph: Graph, request: GraphRunRequest): Promise<GraphRunResult>;
+    dispose(): Promise<void>;
+    private assertUsable;
+    private cleanupSession;
+}

package/dist/adapter/graph-execution-host.js

@@ -0,0 +1,181 @@
+/** 为旧调用（仅有 invocationKind，无 boundary）填补默认值。
+ *  旧 `"subgraph"` → `graph-node` + `call`。 */
+export function normalizeGraphRunRequest(partial) {
+    let kind;
+    if (partial.invocationKind === "subgraph") {
+        kind = "graph-node";
+    }
+    else if (partial.invocationKind === "command" ||
+        partial.invocationKind === "tool" ||
+        partial.invocationKind === "graph-node" ||
+        partial.invocationKind === "api") {
+        kind = partial.invocationKind;
+    }
+    else {
+        throw new Error(`未知 GraphInvocationKind: ${partial.invocationKind}`);
+    }
+    const boundary = partial.boundary ?? (kind === "tool" || kind === "command" ? "delegate" : "call");
+    return { background: partial.background, invocationKind: kind, boundary, signal: partial.signal };
+}
+/** 每次 invoke 创建一次性 host，并固定执行 run → abort/dispose 生命周期。 */
+export class DelegateGraphInvoker {
+    pi;
+    createHost;
+    constructor(pi, createHost) {
+        this.pi = pi;
+        this.createHost = createHost;
+    }
+    async invoke(graph, request, extensionContext) {
+        if (request.boundary !== "delegate") {
+            throw new Error(`DelegateGraphInvoker 只接受 delegate boundary，收到: ${request.boundary}`);
+        }
+        const host = await this.createHost({
+            pi: this.pi,
+            extensionContext,
+            graph,
+            request,
+        });
+        let runError;
+        try {
+            return await host.run(graph, request);
+        }
+        catch (error) {
+            runError = error;
+            throw error;
+        }
+        finally {
+            try {
+                await host.dispose();
+            }
+            catch (disposeError) {
+                if (runError != null) {
+                    runError.suppressed = disposeError;
+                }
+                else {
+                    throw disposeError;
+                }
+            }
+        }
+    }
+}
+/**
+ * 为一次 graph-tool 调用持有一个独立子 AgentSession 的生命周期外壳。
+ *
+ * 契约：
+ * - 一个 host 同时只运行一张图；并发调用应创建多个 host。
+ * - outer AbortSignal 会转发给子会话 abort()。
+ * - dispose 顺序固定为 abort() -> dispose()。
+ * - dispose 后拒绝 run()，弥补 AgentSession.dispose() 仍允许 prompt 的行为。
+ */
+export class IsolatedSessionGraphHost {
+    options;
+    session = null;
+    sessionPromise = null;
+    cleanedSession = null;
+    disposed = false;
+    running = false;
+    disposing = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async run(graph, request) {
+        this.assertUsable();
+        if (this.running) {
+            throw new Error("IsolatedSessionGraphHost 已有图正在运行；并发调用必须创建独立 host");
+        }
+        if (request.signal?.aborted)
+            throw createAbortError();
+        this.running = true;
+        try {
+            const sessionPromise = this.options.createSession(request);
+            this.sessionPromise = sessionPromise;
+            let session;
+            try {
+                session = await sessionPromise;
+            }
+            finally {
+                if (this.sessionPromise === sessionPromise)
+                    this.sessionPromise = null;
+            }
+            // createSession 期间也可能收到 dispose/abort。
+            if (this.disposed || request.signal?.aborted) {
+                await this.cleanupSession(session);
+                if (request.signal?.aborted)
+                    throw createAbortError();
+                throw new Error("IsolatedSessionGraphHost 已释放");
+            }
+            this.session = session;
+            const onAbort = () => {
+                void session.abort().catch(() => undefined);
+            };
+            request.signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                return await session.run(graph, request);
+            }
+            finally {
+                request.signal?.removeEventListener("abort", onAbort);
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async dispose() {
+        if (this.disposing)
+            return this.disposing;
+        this.disposed = true;
+        this.disposing = (async () => {
+            const pendingSession = this.sessionPromise;
+            const session = this.session;
+            this.session = null;
+            if (session) {
+                await this.cleanupSession(session);
+                return;
+            }
+            if (pendingSession) {
+                try {
+                    await this.cleanupSession(await pendingSession);
+                }
+                catch {
+                    // createSession 自身失败时没有可清理的 session。
+                }
+            }
+        })();
+        return this.disposing;
+    }
+    assertUsable() {
+        if (this.disposed)
+            throw new Error("IsolatedSessionGraphHost 已释放");
+    }
+    async cleanupSession(session) {
+        if (this.cleanedSession === session)
+            return;
+        this.cleanedSession = session;
+        await abortThenDispose(session);
+    }
+}
+async function abortThenDispose(session) {
+    let abortError = undefined;
+    try {
+        await session.abort();
+    }
+    catch (e) {
+        abortError = e;
+    }
+    try {
+        session.dispose();
+    }
+    catch (disposeError) {
+        if (abortError != null) {
+            abortError.suppressed = disposeError;
+        }
+        throw abortError ?? disposeError;
+    }
+    if (abortError != null)
+        throw abortError;
+}
+function createAbortError() {
+    const error = new Error("Graph execution aborted");
+    error.name = "AbortError";
+    return error;
+}

package/dist/adapter/isolated-graph-session.d.ts

@@ -0,0 +1,75 @@
+import { type AuthStorage, type CompactionSettings, type CreateAgentSessionOptions, type ModelRegistry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ContextFrame } from "../type.js";
+import type { Graph as CoreGraph } from "../core/graph.js";
+import type { NodeContextRenderer } from "./projection.js";
+import { type LoopGraphLimits, type CompletionFeedbackFormatter, type ContextRendererRegistry } from "./loop-graph-extension.js";
+import type { ModelMessageFormatter } from "./model-messages.js";
+import type { ToolResolver } from "../tools-resolve.js";
+import type { LoopGraphLogger, LoopGraphTraceSink } from "./observability.js";
+import type { SkillContentProvider, SkillContentRenderer, SkillFailurePolicies } from "./skill-content.js";
+import type { DelegateHostFactory, IsolatedGraphSessionFactory } from "./graph-execution-host.js";
+import type { HostBaseline } from "../host/baseline.js";
+import type { SkillCatalog } from "../host/skill-catalog.js";
+import type { ToolCatalog, UnsafeToolResolver } from "../host/tool-catalog.js";
+import { type GraphHost } from "../host/graph-host.js";
+import type { RecordingMode } from "../core/result.js";
+import type { RunStore } from "../replay/store.js";
+import type { PricingResolver } from "../replay/events.js";
+import type { Recorder } from "../replay/recorder.js";
+import type { InvocationAgentHost } from "../runtime/graph-runtime.js";
+export interface IsolatedGraphSessionFactoryOptions {
+    authStorage: AuthStorage;
+    modelRegistry: ModelRegistry;
+    cwd?: string;
+    agentDir?: string;
+    model?: CreateAgentSessionOptions["model"];
+    customTools?: ToolDefinition[];
+    toolCatalog?: ToolCatalog;
+    skillCatalog?: SkillCatalog;
+    unsafeToolResolver?: UnsafeToolResolver;
+    baseline?: HostBaseline;
+    skillBasePath?: string;
+    frameFormatter?: (frames: ContextFrame[]) => string | null;
+    limits?: LoopGraphLimits;
+    contextRenderer?: NodeContextRenderer;
+    modelMessageFormatter?: Partial<ModelMessageFormatter>;
+    completionFeedbackFormatter?: CompletionFeedbackFormatter;
+    outputContractMaxBytes?: number;
+    skillProvider?: SkillContentProvider;
+    skillRenderer?: SkillContentRenderer;
+    skillFailure?: SkillFailurePolicies;
+    contextRenderers?: ContextRendererRegistry;
+    toolResolver?: ToolResolver;
+    traceSink?: LoopGraphTraceSink;
+    logger?: LoopGraphLogger;
+    debug?: boolean;
+    debugLogPath?: string;
+    thinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
+    /** 省略时遵循 pi 默认 compaction；可由 host 显式覆盖。 */
+    compaction?: CompactionSettings;
+    recording?: RecordingMode;
+    recordingRequired?: boolean;
+    runStore?: RunStore;
+    artifactThresholdBytes?: number;
+    pricingResolver?: PricingResolver;
+    /** 供子图继续使用 delegate；runtime-only adapter 不注册对外入口。 */
+    createDelegateHost?: DelegateHostFactory;
+    /** Core graphs made available to GraphRef resolution in this isolated Host. */
+    graphs?: readonly CoreGraph[];
+}
+/**
+ * 使用 pi 官方 in-memory AgentSession 创建隔离图执行环境。
+ *
+ * 子会话通过 inline extension factory 安装同一套 LoopGraph Runtime，避免维护
+ * 第二套 graph loop。runtimeOnly 模式只保留运行钩子，不注册对外命令或资源通知。
+ */
+export declare function createIsolatedGraphSessionFactory(options: IsolatedGraphSessionFactoryOptions): IsolatedGraphSessionFactory;
+/**
+ * 构造可递归 delegate 的一次性 host factory。每次调用创建新 host/session，
+ * 子 session 内的 delegate graph-node 继续复用同一份认证、模型与真实工具实现。
+ */
+export declare function createIsolatedDelegateHostFactory(options: Omit<IsolatedGraphSessionFactoryOptions, "createDelegateHost">): DelegateHostFactory;
+/** Creates one Pi Session that only executes Agent Runs for a Core Graph Invocation. */
+export declare function createPiInvocationAgentHost(options: IsolatedGraphSessionFactoryOptions, recorder?: Recorder | null): Promise<InvocationAgentHost>;
+/** Creates a Core GraphHost backed by one isolated Pi AgentSession. */
+export declare function createPiGraphHost(options: IsolatedGraphSessionFactoryOptions): Promise<GraphHost>;