pi-loop-graph-sdk 0.2.0

package/dist/runtime/invocation-budget.d.ts

@@ -0,0 +1,22 @@
+import type { InvocationLimits } from "../core/limits.js";
+export interface InvocationBudgetUsage {
+    readonly graphInvocations: number;
+    readonly nodeVisits: number;
+    readonly maxDepthReached: number;
+}
+export declare class InvocationBudgetExceededError extends Error {
+    readonly kind: "graph-depth" | "graph-invocations" | "node-visits";
+    constructor(kind: "graph-depth" | "graph-invocations" | "node-visits", message: string);
+}
+export declare class InvocationBudget {
+    readonly limits: InvocationLimits;
+    private graphInvocations;
+    private nodeVisits;
+    private maxDepthReached;
+    constructor(limits: InvocationLimits);
+    enterGraph(depth: number): void;
+    enterNode(): void;
+    get usage(): InvocationBudgetUsage;
+    /** Restore budget position from a saved checkpoint. New usage must be at least as high. */
+    restore(usage: InvocationBudgetUsage): void;
+}

package/dist/runtime/invocation-budget.js

@@ -0,0 +1,52 @@
+export class InvocationBudgetExceededError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "InvocationBudgetExceededError";
+    }
+}
+export class InvocationBudget {
+    limits;
+    graphInvocations = 0;
+    nodeVisits = 0;
+    maxDepthReached = 0;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    enterGraph(depth) {
+        if (depth > this.limits.maxGraphDepth) {
+            throw new InvocationBudgetExceededError("graph-depth", `Graph depth ${depth} exceeds maxGraphDepth ${this.limits.maxGraphDepth}`);
+        }
+        if (this.graphInvocations + 1 > this.limits.maxGraphInvocations) {
+            throw new InvocationBudgetExceededError("graph-invocations", `Graph invocation count exceeds maxGraphInvocations ${this.limits.maxGraphInvocations}`);
+        }
+        this.graphInvocations += 1;
+        this.maxDepthReached = Math.max(this.maxDepthReached, depth);
+    }
+    enterNode() {
+        if (this.nodeVisits + 1 > this.limits.maxTotalNodeVisits) {
+            throw new InvocationBudgetExceededError("node-visits", `Node visit count exceeds maxTotalNodeVisits ${this.limits.maxTotalNodeVisits}`);
+        }
+        this.nodeVisits += 1;
+    }
+    get usage() {
+        return Object.freeze({
+            graphInvocations: this.graphInvocations,
+            nodeVisits: this.nodeVisits,
+            maxDepthReached: this.maxDepthReached,
+        });
+    }
+    /** Restore budget position from a saved checkpoint. New usage must be at least as high. */
+    restore(usage) {
+        if (usage.graphInvocations < 0 || usage.nodeVisits < 0 || usage.maxDepthReached < 0) {
+            throw new Error("Invalid budget usage");
+        }
+        if (usage.maxDepthReached > this.limits.maxGraphDepth) {
+            throw new InvocationBudgetExceededError("graph-depth", `Checkpoint depth ${usage.maxDepthReached} exceeds maxGraphDepth ${this.limits.maxGraphDepth}`);
+        }
+        this.graphInvocations = Math.max(this.graphInvocations, usage.graphInvocations);
+        this.nodeVisits = Math.max(this.nodeVisits, usage.nodeVisits);
+        this.maxDepthReached = Math.max(this.maxDepthReached, usage.maxDepthReached);
+    }
+}

package/dist/runtime/mechanism-runtime.d.ts

@@ -0,0 +1,92 @@
+import type { ContextContribution } from "../core/context.js";
+import { type JsonValue } from "../core/json.js";
+import type { Mechanism, MechanismCompletionDecision, MechanismContext, MechanismDecisionTrace, MechanismFailurePolicy, MechanismHookName, MechanismInstallation, MechanismScope } from "../core/mechanism.js";
+export interface MechanismRuntimeOptions {
+    readonly hookTimeoutMs?: number;
+    readonly execRoot?: string;
+    readonly execTimeoutMs?: number;
+    readonly execMaxOutputBytes?: number;
+    readonly allowExecOutsideRoot?: boolean;
+    readonly pi?: unknown;
+}
+export interface MechanismFailureRecord {
+    readonly mechanismName: string;
+    readonly installation: MechanismInstallation;
+    readonly hook: MechanismHookName | "createState" | "cleanup";
+    readonly policy: MechanismFailurePolicy;
+    readonly message: string;
+    readonly error: unknown;
+    readonly scopeId: string;
+}
+export declare class MechanismRuntimeError extends Error {
+    readonly failure: MechanismFailureRecord;
+    constructor(failure: MechanismFailureRecord);
+}
+interface Invocation {
+    readonly definition: Mechanism;
+    readonly installation: MechanismInstallation;
+    readonly context: MechanismContext;
+    readonly scope: ManagedScope;
+}
+export interface MechanismChain {
+    readonly invocations: readonly Invocation[];
+}
+export declare class MechanismRuntime {
+    private readonly warn?;
+    private readonly options;
+    private readonly activeNames;
+    private readonly decisions;
+    private readonly failures;
+    private unmanagedWarningEmitted;
+    private readonly contributions;
+    private agentRunHandles;
+    private naturalLifetime;
+    constructor(options?: MechanismRuntimeOptions, warn?: ((message: string) => void) | undefined);
+    get decisionTrace(): readonly MechanismDecisionTrace[];
+    get failureTrace(): readonly MechanismFailureRecord[];
+    get contextContributions(): readonly ContextContribution[];
+    open(installation: MechanismInstallation, scopeId: string, definitions: readonly Mechanism[], identity: {
+        rootRunId: string;
+        graphInvocationId?: string;
+        nodeVisitId?: string;
+        stageId?: string;
+    }, _contextState?: import("../core/context.js").ContextState): Promise<MechanismChain>;
+    beforeAgentRun(chains: readonly MechanismChain[], agentRunId: string, prompt: string): Promise<void>;
+    afterAgentRun(chains: readonly MechanismChain[], agentRunId: string): Promise<void>;
+    enter(chains: readonly MechanismChain[], hookName: "onRootEnter" | "onGraphEnter" | "onNodeEnter"): Promise<void>;
+    validateCompletion(chains: readonly MechanismChain[], agentRunId: string, completion: JsonValue): Promise<MechanismCompletionDecision>;
+    nodeExit(chains: readonly MechanismChain[], completion: JsonValue): Promise<void>;
+    nodeError(chains: readonly MechanismChain[], error: unknown): Promise<void>;
+    graphExit(chains: readonly MechanismChain[], error?: unknown): Promise<void>;
+    rootExit(chain: MechanismChain): Promise<void>;
+    close(chain: MechanismChain): Promise<void>;
+    /** Yield JSON-compatible snapshots for all mechanisms that implement snapshot. */
+    snapshotAll(chains: readonly MechanismChain[]): readonly {
+        readonly name: string;
+        readonly snapshot: JsonValue;
+    }[];
+    /** Restore mechanism state from a checkpoint. A declared restore hook is fail-closed. */
+    restoreState(chains: readonly MechanismChain[], saved: readonly {
+        readonly name: string;
+        readonly snapshot: JsonValue;
+    }[]): void;
+    private observe;
+    private observeInvocation;
+    private control;
+    private createContext;
+    private exec;
+    private validateDuplicates;
+    private record;
+    private error;
+    private failure;
+}
+declare class ManagedScope {
+    readonly scopeId: string;
+    private active;
+    private readonly controller;
+    private readonly cleanups;
+    readonly view: MechanismScope;
+    constructor(scopeId: string, installation: MechanismInstallation);
+    close(): Promise<unknown[]>;
+}
+export {};

package/dist/runtime/mechanism-runtime.js

@@ -0,0 +1,387 @@
+import { execFile } from "node:child_process";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { isJsonValue } from "../core/json.js";
+const execFileAsync = promisify(execFile);
+export class MechanismRuntimeError extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.message);
+        this.failure = failure;
+        this.name = "MechanismRuntimeError";
+    }
+}
+export class MechanismRuntime {
+    warn;
+    options;
+    activeNames = [];
+    decisions = [];
+    failures = [];
+    unmanagedWarningEmitted = false;
+    contributions = new Map();
+    agentRunHandles = null;
+    naturalLifetime;
+    constructor(options = {}, warn) {
+        this.warn = warn;
+        this.options = {
+            hookTimeoutMs: options.hookTimeoutMs ?? 30_000,
+            execRoot: path.resolve(options.execRoot ?? process.cwd()),
+            execTimeoutMs: options.execTimeoutMs ?? 30_000,
+            execMaxOutputBytes: options.execMaxOutputBytes ?? 64 * 1024,
+            allowExecOutsideRoot: options.allowExecOutsideRoot ?? false,
+            pi: options.pi,
+        };
+    }
+    get decisionTrace() { return Object.freeze([...this.decisions]); }
+    get failureTrace() { return Object.freeze([...this.failures]); }
+    get contextContributions() { return Object.freeze([...this.contributions.values()]); }
+    async open(installation, scopeId, definitions, identity, _contextState) {
+        this.validateDuplicates(definitions);
+        const invocations = [];
+        try {
+            for (const definition of definitions) {
+                if (!definition.allowMultiple && this.activeNames.includes(definition.name)) {
+                    throw this.error(definition, installation, "createState", scopeId, new Error(`Mechanism is already installed in the active chain: ${definition.name}`));
+                }
+                let state;
+                try {
+                    state = definition.createState?.() ?? {};
+                    if (!isJsonValue(state))
+                        throw new Error("Mechanism state must be JSON-compatible");
+                }
+                catch (error) {
+                    throw this.error(definition, installation, "createState", scopeId, error);
+                }
+                const scope = new ManagedScope(scopeId, installation);
+                const context = this.createContext(definition, installation, identity, state, scope);
+                invocations.push({ definition, installation, context, scope });
+                this.activeNames.push(definition.name);
+            }
+            return Object.freeze({ invocations: Object.freeze(invocations) });
+        }
+        catch (error) {
+            await this.close(Object.freeze({ invocations: Object.freeze(invocations) }));
+            throw error;
+        }
+    }
+    async beforeAgentRun(chains, agentRunId, prompt) {
+        this.agentRunHandles = [];
+        for (const invocation of flatten(chains)) {
+            const hook = invocation.definition.beforeAgentRun;
+            if (!hook)
+                continue;
+            this.naturalLifetime = "agent-run";
+            try {
+                await this.control(invocation, "beforeAgentRun", () => hook(Object.freeze({ ...invocation.context, agentRunId, prompt })));
+            }
+            finally {
+                this.naturalLifetime = undefined;
+            }
+        }
+    }
+    async afterAgentRun(chains, agentRunId) {
+        for (const invocation of [...flatten(chains)].reverse()) {
+            const hook = invocation.definition.afterAgentRun;
+            if (!hook)
+                continue;
+            await this.observeInvocation(invocation, "afterAgentRun", () => hook(Object.freeze({ ...invocation.context, agentRunId })));
+        }
+        for (const handle of this.agentRunHandles ?? [])
+            handle.dispose();
+        this.agentRunHandles = null;
+    }
+    async enter(chains, hookName) {
+        for (const invocation of flatten(chains)) {
+            const hook = invocation.definition[hookName];
+            if (hook)
+                await this.observeInvocation(invocation, hookName, () => hook(invocation.context));
+        }
+    }
+    async validateCompletion(chains, agentRunId, completion) {
+        for (const invocation of [...flatten(chains)].reverse()) {
+            const hook = invocation.definition.validateCompletion;
+            if (!hook)
+                continue;
+            const decision = await this.control(invocation, "validateCompletion", () => hook(Object.freeze({ ...invocation.context, agentRunId, completion })));
+            this.decisions.push(Object.freeze({
+                mechanismName: invocation.definition.name,
+                hook: "validateCompletion",
+                decision: decision.action,
+                reason: "reason" in decision ? decision.reason : undefined,
+                timestamp: Date.now(),
+            }));
+            if (decision.action !== "allow")
+                return decision;
+        }
+        return { action: "allow" };
+    }
+    async nodeExit(chains, completion) {
+        for (const invocation of [...flatten(chains)].reverse()) {
+            const hook = invocation.definition.onNodeExit;
+            if (hook)
+                await this.observeInvocation(invocation, "onNodeExit", () => hook(Object.freeze({ ...invocation.context, completion })));
+        }
+    }
+    async nodeError(chains, error) {
+        for (const invocation of [...flatten(chains)].reverse()) {
+            const hook = invocation.definition.onNodeError;
+            if (hook)
+                await this.observeInvocation(invocation, "onNodeError", () => hook(Object.freeze({ ...invocation.context, error })));
+        }
+    }
+    async graphExit(chains, error) {
+        for (const invocation of [...flatten(chains)].reverse()) {
+            const hook = error === undefined ? invocation.definition.onGraphExit : invocation.definition.onGraphError;
+            const name = error === undefined ? "onGraphExit" : "onGraphError";
+            if (hook)
+                await this.observeInvocation(invocation, name, () => hook(Object.freeze({ ...invocation.context, ...(error === undefined ? {} : { error }) })));
+        }
+    }
+    async rootExit(chain) {
+        for (const invocation of [...chain.invocations].reverse()) {
+            const hook = invocation.definition.onRootExit;
+            if (hook)
+                await this.observeInvocation(invocation, "onRootExit", () => hook(invocation.context));
+        }
+    }
+    async close(chain) {
+        for (const invocation of [...chain.invocations].reverse()) {
+            const errors = await invocation.scope.close();
+            for (const error of errors)
+                this.record(invocation, "cleanup", error);
+            const index = this.activeNames.lastIndexOf(invocation.definition.name);
+            if (index >= 0)
+                this.activeNames.splice(index, 1);
+        }
+    }
+    /** Yield JSON-compatible snapshots for all mechanisms that implement snapshot. */
+    snapshotAll(chains) {
+        const snapshots = [];
+        for (const invocation of flatten(chains)) {
+            if (invocation.definition.snapshot) {
+                try {
+                    const snapshot = invocation.definition.snapshot(invocation.context.state);
+                    if (!isJsonValue(snapshot))
+                        throw new Error("Mechanism snapshot must be JSON-compatible");
+                    snapshots.push({ name: invocation.definition.name, snapshot });
+                }
+                catch (error) {
+                    // Observation: snapshots are best-effort; failure does not alter control flow.
+                    const message = `Mechanism "${invocation.definition.name}" snapshot failed: ${error instanceof Error ? error.message : String(error)}`;
+                    this.warn?.(message);
+                }
+            }
+        }
+        return Object.freeze(snapshots);
+    }
+    /** Restore mechanism state from a checkpoint. A declared restore hook is fail-closed. */
+    restoreState(chains, saved) {
+        const snapshotMap = new Map(saved.map((s) => [s.name, s.snapshot]));
+        for (const invocation of flatten(chains)) {
+            if (!invocation.definition.restore)
+                continue;
+            const snapshot = snapshotMap.get(invocation.definition.name);
+            if (snapshot === undefined)
+                continue;
+            try {
+                const restored = invocation.definition.restore(snapshot);
+                if (!isJsonValue(restored))
+                    throw new Error("Restored mechanism state must be JSON-compatible");
+                invocation.context.state = restored;
+            }
+            catch (error) {
+                throw this.error(invocation.definition, invocation.installation, "createState", invocation.scope.scopeId, new Error(`checkpoint restore failed: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+    }
+    async observe(chain, hookName) {
+        for (const invocation of chain.invocations) {
+            const hook = invocation.definition[hookName];
+            if (hook)
+                await this.observeInvocation(invocation, hookName, () => hook(invocation.context));
+        }
+    }
+    async observeInvocation(invocation, hook, run) {
+        try {
+            await withTimeout(Promise.resolve(run()), this.options.hookTimeoutMs, hook);
+        }
+        catch (error) {
+            this.record(invocation, hook, error);
+        }
+    }
+    async control(invocation, hook, run) {
+        try {
+            return await withTimeout(Promise.resolve(run()), this.options.hookTimeoutMs, hook);
+        }
+        catch (error) {
+            throw this.error(invocation.definition, invocation.installation, hook, invocation.scope.scopeId, error);
+        }
+    }
+    createContext(definition, installation, identity, state, scope) {
+        const maxLifetime = installation === "host" ? "root-run" : installation === "graph" ? "graph-invocation" : "node-visit";
+        const defaultLifetime = installation === "host" ? "root-run" : installation === "graph" ? "graph-invocation" : "node-visit";
+        const context = {
+            add: (id, content, options = {}) => {
+                const lifetime = options.lifetime ?? this.naturalLifetime ?? defaultLifetime;
+                if (!lifetimeAllowed(lifetime, maxLifetime))
+                    throw new Error(`${installation} Mechanism cannot create ${lifetime} contribution`);
+                const contributionId = `${scope.scopeId}:${definition.name}:${id}`;
+                if (this.contributions.has(contributionId))
+                    throw new Error(`Context contribution already exists: ${contributionId}`);
+                const contribution = Object.freeze({
+                    id: contributionId,
+                    owner: installation,
+                    scopeId: scope.scopeId,
+                    lifetime,
+                    retention: options.retention ?? "sticky",
+                    content,
+                });
+                this.contributions.set(contributionId, contribution);
+                let active = true;
+                const handle = Object.freeze({
+                    id: contributionId,
+                    update: (next) => {
+                        if (!active)
+                            throw new Error(`Context contribution is disposed: ${contributionId}`);
+                        this.contributions.set(contributionId, Object.freeze({ ...contribution, content: next }));
+                    },
+                    dispose: () => {
+                        if (!active)
+                            return;
+                        active = false;
+                        this.contributions.delete(contributionId);
+                    },
+                });
+                scope.view.onCleanup(() => handle.dispose());
+                if (lifetime === "agent-run")
+                    this.agentRunHandles?.push(handle);
+                return handle;
+            },
+        };
+        const result = {
+            ...identity,
+            state,
+            scope: scope.view,
+            context: Object.freeze(context),
+            exec: Object.freeze({ run: (file, args, options) => this.exec(file, args, options) }),
+        };
+        if (this.options.pi !== undefined)
+            Object.defineProperty(result, "pi", {
+                enumerable: true,
+                get: () => {
+                    if (!this.unmanagedWarningEmitted) {
+                        this.unmanagedWarningEmitted = true;
+                        this.warn?.("Mechanism accessed unmanaged ctx.pi; scope, replay, and cleanup guarantees do not apply");
+                    }
+                    return this.options.pi;
+                },
+            });
+        return Object.freeze(result);
+    }
+    async exec(file, args = [], options = {}) {
+        const cwd = path.resolve(options.cwd ?? this.options.execRoot);
+        if (!this.options.allowExecOutsideRoot && !within(this.options.execRoot, cwd))
+            throw new Error("Mechanism exec cwd is outside execRoot");
+        try {
+            const result = await execFileAsync(file, [...args], { cwd, timeout: options.timeoutMs ?? this.options.execTimeoutMs, maxBuffer: this.options.execMaxOutputBytes * 2 });
+            return output(0, result.stdout, result.stderr, this.options.execMaxOutputBytes);
+        }
+        catch (error) {
+            const value = error;
+            return output(typeof value.code === "number" ? value.code : 1, value.stdout ?? "", value.stderr ?? String(error), this.options.execMaxOutputBytes);
+        }
+    }
+    validateDuplicates(definitions) {
+        const names = new Set();
+        for (const definition of definitions) {
+            if (!definition.name.trim())
+                throw new Error("Mechanism name is required");
+            if (!definition.allowMultiple && names.has(definition.name))
+                throw new Error(`Duplicate Mechanism installation: ${definition.name}`);
+            names.add(definition.name);
+        }
+    }
+    record(invocation, hook, error) {
+        const failure = this.failure(invocation.definition, invocation.installation, hook, invocation.scope.scopeId, error);
+        this.failures.push(failure);
+        return failure;
+    }
+    error(definition, installation, hook, scopeId, error) {
+        const failure = this.failure(definition, installation, hook, scopeId, error);
+        this.failures.push(failure);
+        return new MechanismRuntimeError(failure);
+    }
+    failure(definition, installation, hook, scopeId, error) {
+        return Object.freeze({
+            mechanismName: definition.name,
+            installation,
+            hook,
+            policy: definition.failurePolicy ?? (installation === "node" ? "fail-node" : "fail-graph"),
+            message: `Mechanism "${definition.name}" ${hook} failed: ${error instanceof Error ? error.message : String(error)}`,
+            error,
+            scopeId,
+        });
+    }
+}
+class ManagedScope {
+    scopeId;
+    active = true;
+    controller = new AbortController();
+    cleanups = [];
+    view;
+    constructor(scopeId, installation) {
+        this.scopeId = scopeId;
+        this.view = Object.freeze({
+            scopeId, installation, signal: this.controller.signal,
+            isActive: () => this.active,
+            onCleanup: (cleanup) => {
+                if (!this.active)
+                    throw new Error("Mechanism scope is closed");
+                this.cleanups.push(cleanup);
+            },
+        });
+    }
+    async close() {
+        if (!this.active)
+            return [];
+        this.active = false;
+        this.controller.abort();
+        const errors = [];
+        for (const cleanup of [...this.cleanups].reverse())
+            try {
+                await cleanup();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        return errors;
+    }
+}
+function flatten(chains) { return chains.flatMap((chain) => [...chain.invocations]); }
+function lifetimeAllowed(requested, maximum) {
+    const order = ["agent-run", "node-visit", "graph-invocation", "root-run"];
+    return order.indexOf(requested) <= order.indexOf(maximum);
+}
+function within(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function output(exitCode, stdout, stderr, max) {
+    const truncate = (value) => {
+        const buffer = Buffer.from(value, "utf8");
+        return buffer.length <= max ? { value, truncated: false } : { value: buffer.subarray(0, max).toString("utf8"), truncated: true };
+    };
+    const out = truncate(stdout);
+    const err = truncate(stderr);
+    return Object.freeze({ exitCode, stdout: out.value, stderr: err.value, truncated: out.truncated || err.truncated });
+}
+async function withTimeout(promise, timeoutMs, hook) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`${hook} timed out after ${timeoutMs}ms`)), timeoutMs); })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,91 @@
+import type { AgentInstance, ContextFrame, Graph, Mechanism, Node, NodeCompletion, NodeInput } from "./type.js";
+export interface CallFrame {
+    instance: AgentInstance;
+    graph: Graph;
+    /** 图调用的上下文边界。 */
+    boundary: "root" | "call" | "compose";
+    /** compose 复用父 Instance，但 child Graph 的目标/机制只在此调用帧生效。 */
+    localGoal: string;
+    localMechanisms: readonly Mechanism[];
+    callBackground: Record<string, unknown>;
+    parentNodeId?: string;
+    /** 每个调用帧独立计数，避免同名子图节点污染 visit。 */
+    nodeVisits: Map<string, number>;
+    currentNodeId: string | null;
+    /**
+     * 节点瞬态状态也归属调用帧。子图返回时必须恢复仍在执行的父 graph node，
+     * 否则 context 投影会错误地认为父节点已经结束。
+     */
+    activeNode: Node | null;
+    activeInput: NodeInput | null;
+    activeScope: NodeScopeDescriptor | null;
+    isNodeActive: boolean;
+    /** 已被最近一次 pi compaction 原生上下文取代的 frame 前缀长度。 */
+    projectedFrameBase: number;
+}
+/** compose 调用在父 frames 上建立的受 Runtime 管理的临时区间。 */
+export interface FrameSegmentScope {
+    id: string;
+    graphId: string;
+    parentNodeId: string;
+    instanceId: string;
+    baseIndex: number;
+    depth: number;
+}
+export interface NodeScopeDescriptor {
+    protocol: 2;
+    graphRunId: string;
+    instanceId: string;
+    scopeId: string;
+    graphId: string;
+    nodeId: string;
+    visit: number;
+    depth: number;
+}
+export declare class GraphRuntime {
+    callStack: CallFrame[];
+    isNodeActive: boolean;
+    /** 当前节点的语义作用域。details 用于匹配，不依赖消息正文。 */
+    currentScope: NodeScopeDescriptor | null;
+    currentNode: Node | null;
+    currentInput: NodeInput | null;
+    readonly graphRunId: `${string}-${string}-${string}-${string}-${string}`;
+    /** 当前 graph run 已发生的 compaction 次数，仅用于诊断和 checkpoint 观测。 */
+    compactionGeneration: number;
+    /**
+     * 共享 call/compose 活跃期间异常收到 session_compact 时设为 true。
+     * 此后本 session 投影中将持续过滤 compactionSummary，优先保证不泄漏。
+     */
+    compactionBoundaryViolated: boolean;
+    /** Runtime 控制平面的 frame → NodeScope 对齐表，不进入开发者 frame/LLM。 */
+    private readonly frameScopes;
+    get top(): CallFrame | null;
+    get topInstance(): AgentInstance | null;
+    get topGraph(): Graph | null;
+    get currentNodeId(): string | null;
+    pushGraph(graph: Graph, background: Record<string, unknown>, boundary?: CallFrame["boundary"], sharedInstance?: AgentInstance, parentNodeId?: string): AgentInstance;
+    popGraph(): CallFrame | undefined;
+    beginFrameSegment(graphId: string, parentNodeId: string): FrameSegmentScope;
+    readFrameSegment(scope: FrameSegmentScope): readonly ContextFrame[];
+    rollbackFrameSegment(scope: FrameSegmentScope): void;
+    closeFrameSegment(scope: FrameSegmentScope, completion: NodeCompletion): NodeCompletion;
+    nextScope(nodeId: string): NodeScopeDescriptor;
+    enterNode(nodeId: string, scope: NodeScopeDescriptor, input: NodeInput): Node;
+    exitNode(frame: ContextFrame): void;
+    /**
+     * 记录一次 session compaction。NodeScope 的身份（scopeId）不变。
+     * Runtime 只推进 projectedFrameBase；pi 原生 summary 与 recent messages
+     * 是压缩历史的权威替代，SDK 不重发 scope，也不遮挡 summary。
+     */
+    recordCompaction(projectedFrameBase?: number): number;
+    /** 当前 callStack 是否存在嵌套 call/compose（非 root-only）。 */
+    get hasActiveSharedCall(): boolean;
+    /** 共享调用边界被 compaction 切断后，继续运行会泄漏无法归属的 transcript。 */
+    assertNoCompactionBoundaryViolation(): void;
+    get completedFrameScopes(): readonly NodeScopeDescriptor[];
+    /** 只返回最近一次 compaction 后新生长、仍需单独投影的开发者 frames。 */
+    get projectedFrames(): ContextFrame[];
+    reset(): void;
+    private assertSegmentOwner;
+    private restoreActiveNodeFromTop;
+}