pi-loop-graph-sdk 0.2.0

package/dist/replay/store.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile, appendFile, readdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+export class FileRunStore {
+    rootDir;
+    constructor(options = {}) {
+        this.rootDir = resolve(typeof options === "string" ? options : (options.rootDir ?? ".loop-graph/runs"));
+    }
+    location(runId) {
+        return this.runDir(runId);
+    }
+    async appendJournal(runId, line) {
+        const dir = this.runDir(runId);
+        await mkdir(dir, { recursive: true });
+        await appendFile(join(dir, "journal.jsonl"), line.endsWith("\n") ? line : `${line}\n`, "utf8");
+    }
+    readJournal(runId) {
+        return readFile(join(this.runDir(runId), "journal.jsonl"), "utf8");
+    }
+    async writeArtifact(runId, artifactId, content, mediaType = "application/json") {
+        const safeId = safeSegment(artifactId, "artifactId");
+        const dir = join(this.runDir(runId), "artifacts");
+        await mkdir(dir, { recursive: true });
+        await atomicWrite(join(dir, safeId), content);
+        return Object.freeze({
+            artifactId: safeId,
+            mediaType,
+            byteSize: Buffer.byteLength(content, "utf8"),
+            sha256: createHash("sha256").update(content).digest("hex"),
+        });
+    }
+    readArtifact(runId, artifactId) {
+        return readFile(join(this.runDir(runId), "artifacts", safeSegment(artifactId, "artifactId")), "utf8");
+    }
+    async writeCheckpoint(runId, checkpointId, content) {
+        const dir = join(this.runDir(runId), "checkpoints");
+        await mkdir(dir, { recursive: true });
+        await atomicWrite(join(dir, safeSegment(checkpointId, "checkpointId")), content);
+    }
+    readCheckpoint(runId, checkpointId) {
+        return readFile(join(this.runDir(runId), "checkpoints", safeSegment(checkpointId, "checkpointId")), "utf8");
+    }
+    async listCheckpoints(runId) {
+        try {
+            return Object.freeze((await readdir(join(this.runDir(runId), "checkpoints"), { withFileTypes: true }))
+                .filter((entry) => entry.isFile())
+                .map((entry) => entry.name)
+                .sort());
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return Object.freeze([]);
+            throw error;
+        }
+    }
+    async pruneCheckpoints(runId, keep) {
+        const retained = new Set(keep.map((id) => safeSegment(id, "checkpointId")));
+        for (const id of await this.listCheckpoints(runId)) {
+            if (!retained.has(id))
+                await this.deleteCheckpoint(runId, id);
+        }
+    }
+    async deleteCheckpoint(runId, checkpointId) {
+        await rm(join(this.runDir(runId), "checkpoints", safeSegment(checkpointId, "checkpointId")), { force: true });
+    }
+    async writeReplay(runId, content) {
+        const dir = this.runDir(runId);
+        await mkdir(dir, { recursive: true });
+        await atomicWrite(join(dir, "replay.json"), content);
+    }
+    readReplay(runId) {
+        return readFile(join(this.runDir(runId), "replay.json"), "utf8");
+    }
+    runDir(runId) {
+        return join(this.rootDir, safeSegment(runId, "runId"));
+    }
+}
+async function atomicWrite(target, content) {
+    const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporary, content, "utf8");
+    try {
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function safeSegment(value, name) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value) || value === "." || value === "..") {
+        throw new TypeError(`${name} contains unsafe path characters`);
+    }
+    return value;
+}

package/dist/router.d.ts

@@ -0,0 +1,4 @@
+import type { Edge, NodeRouting, NodeCompletion, AgentInstance } from "./type.js";
+import type { Connection, NodeCompletion as CoreNodeCompletion, Route } from "./core/graph.js";
+export declare function selectConnection(route: Route, completion: CoreNodeCompletion): Promise<Connection | null>;
+export declare function selectEdge(routing: NodeRouting, completion: NodeCompletion, instance: AgentInstance): Promise<Edge | null>;

package/dist/router.js

@@ -0,0 +1,61 @@
+// ============================================================
+//  路由器 — 单边裁决
+// ============================================================
+export async function selectConnection(route, completion) {
+    const matched = [];
+    for (const connection of route.connections) {
+        try {
+            if (!connection.transition.guard || await connection.transition.guard(completion.result)) {
+                matched.push(connection);
+            }
+        }
+        catch {
+            // A throwing guard does not match.
+        }
+    }
+    return matched[0] ?? null;
+}
+export async function selectEdge(routing, completion, instance) {
+    const matched = routing.edges.filter((e) => {
+        try {
+            return e.guard(completion);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (matched.length === 0)
+        return null;
+    switch (routing.router.kind) {
+        case "first-match":
+            return matched[0] ?? null;
+        case "priority-first":
+            return priorityFirst(matched);
+        case "custom":
+            return (await routing.router.fn(matched, completion, instance)) ?? null;
+        case "agent-choice": {
+            // 单边匹配 → 无需 agent 选择，直接返回
+            if (matched.length === 1)
+                return matched[0];
+            // 从 completion.result 读取 agent 声明的边 ID
+            const field = routing.agentChoiceField ?? "chosen_edge_id";
+            const chosenId = completion.result?.[field];
+            if (typeof chosenId === "string") {
+                const edge = matched.find((e) => e.id === chosenId);
+                if (edge)
+                    return edge;
+            }
+            // 防御性降级：正常情况下 upstream validateCompletion 已拦截并让 agent 重试，
+            // 此处 priority-first 作为兜底不应该被执行到。
+            return priorityFirst(matched);
+        }
+        default:
+            return matched[0] ?? null;
+    }
+}
+function priorityFirst(matched) {
+    return matched
+        .map((edge, index) => ({ edge, index }))
+        .sort((a, b) => b.edge.priority - a.edge.priority || a.index - b.index)[0]
+        ?.edge ?? null;
+}

package/dist/runtime/event-bus.d.ts

@@ -0,0 +1,101 @@
+import type { GraphFailure } from "../core/result.js";
+import type { InvocationBudgetUsage } from "./invocation-budget.js";
+export type RuntimeEvent = {
+    readonly type: "root_started";
+    readonly rootRunId: string;
+    readonly graphId: string;
+    readonly graphVersion: string;
+} | {
+    readonly type: "host_baseline_selected";
+    readonly rootRunId: string;
+    readonly baseline: "isolated" | "inherit" | "custom";
+    readonly id?: string;
+    readonly fingerprint?: string;
+} | {
+    readonly type: "root_finished";
+    readonly rootRunId: string;
+    readonly status: "completed" | "failed" | "cancelled";
+    readonly usage: InvocationBudgetUsage;
+} | {
+    readonly type: "graph_entered";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly parentGraphInvocationId?: string;
+    readonly graphId: string;
+    readonly graphVersion: string;
+    readonly boundary: "root" | "call" | "compose" | "delegate";
+    readonly depth: number;
+} | {
+    readonly type: "graph_exited";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly status: "completed" | "failed" | "cancelled";
+    readonly failure?: GraphFailure;
+} | {
+    readonly type: "node_entered";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+    readonly visit: number;
+} | {
+    readonly type: "node_exited";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+} | {
+    readonly type: "agent_started";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly agentRunId: string;
+    readonly index: number;
+} | {
+    readonly type: "agent_finished";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly agentRunId: string;
+} | {
+    readonly type: "context_snapshot_materialized";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly memoryRevision: number;
+    readonly layerCount: number;
+} | {
+    readonly type: "mechanism_scope_opened" | "mechanism_scope_closed";
+    readonly rootRunId: string;
+    readonly graphInvocationId?: string;
+    readonly nodeVisitId?: string;
+    readonly installation: "host" | "graph" | "node";
+    readonly count: number;
+} | {
+    readonly type: "transition_selected";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly stageId: string;
+    readonly connectionId: string;
+    readonly target: string;
+} | {
+    readonly type: "checkpoint_saved";
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly checkpointId: string;
+    readonly nextStageId: string;
+} | {
+    readonly type: "runtime_warning";
+    readonly rootRunId: string;
+    readonly graphInvocationId?: string;
+    readonly stageId?: string;
+    readonly code: "unsafe-tool-policy-bypass" | "unsafe-host-baseline" | "unmanaged-mechanism-access";
+    readonly message: string;
+};
+export type RuntimeEventListener = (event: RuntimeEvent) => void;
+export declare class RuntimeEventBus {
+    private readonly listeners;
+    subscribe(listener: RuntimeEventListener): () => void;
+    emit(event: RuntimeEvent): void;
+}

package/dist/runtime/event-bus.js

@@ -0,0 +1,18 @@
+export class RuntimeEventBus {
+    listeners = new Set();
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(event) {
+        const frozen = Object.freeze({ ...event });
+        for (const listener of this.listeners) {
+            try {
+                listener(frozen);
+            }
+            catch {
+                // Runtime fact observers cannot change control flow.
+            }
+        }
+    }
+}

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

@@ -0,0 +1,173 @@
+import type { TSchema } from "typebox";
+import type { AgentNodeDefinition, AgentRunRequest, CodeNodeDefinition, Graph, GraphRef, SchemaValue } from "../core/graph.js";
+import type { InvocationLimits } from "../core/limits.js";
+import type { GraphFailure, GraphRunResult } from "../core/result.js";
+import type { JsonValue } from "../core/json.js";
+import type { Mechanism, MechanismCompletionDecision } from "../core/mechanism.js";
+import { type ContextSnapshot } from "../core/context.js";
+import type { ResolvedSkillView } from "../core/skill.js";
+import type { GraphCatalog } from "../host/graph-catalog.js";
+import type { HostBaseline } from "../host/baseline.js";
+import type { SkillCatalog } from "../host/skill-catalog.js";
+import { type ToolCatalog, type ToolImplementation, type UnsafeToolResolver } from "../host/tool-catalog.js";
+import { RuntimeEventBus } from "./event-bus.js";
+import { InvocationBudget } from "./invocation-budget.js";
+import { type MechanismChain, type MechanismRuntimeOptions } from "./mechanism-runtime.js";
+import type { CheckpointStore } from "../replay/store.js";
+export type InvocationBoundary = "root" | "call" | "compose" | "delegate";
+export interface RootRunState {
+    readonly rootRunId: string;
+    readonly startedAt: number;
+    readonly budget: InvocationBudget;
+    readonly signal?: AbortSignal;
+    readonly baseline: HostBaseline;
+}
+export interface GraphInvocationState {
+    readonly graphInvocationId: string;
+    readonly rootRunId: string;
+    readonly parentGraphInvocationId?: string;
+    readonly graph: GraphRef;
+    readonly boundary: InvocationBoundary;
+    readonly depth: number;
+    readonly frames: JsonValue[];
+    readonly frameRevision: {
+        value: number;
+    };
+}
+export interface NodeVisitState {
+    readonly nodeVisitId: string;
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly stageId: string;
+    readonly visit: number;
+}
+export interface AgentRunState {
+    readonly agentRunId: string;
+    readonly rootRunId: string;
+    readonly graphInvocationId: string;
+    readonly nodeVisitId: string;
+    readonly index: number;
+}
+export interface AgentExecutionContext {
+    readonly root: RootRunState;
+    readonly invocation: GraphInvocationState;
+    readonly nodeVisit: NodeVisitState;
+    readonly agentRun: AgentRunState;
+    readonly tools: readonly ToolImplementation[];
+    readonly skills: readonly ResolvedSkillView[];
+    readonly baseline: HostBaseline;
+    readonly snapshot: ContextSnapshot;
+    readonly mechanisms?: MechanismChain;
+    validateNodeCompletion(result: JsonValue): Promise<{
+        readonly valid: boolean;
+        readonly reason?: string;
+    }>;
+    validateRouteStructure(result: JsonValue): Promise<{
+        readonly valid: boolean;
+        readonly reason?: string;
+    }>;
+    validateMechanismCompletion(result: JsonValue): Promise<MechanismCompletionDecision>;
+    validateAgentChoice(result: JsonValue): Promise<{
+        readonly valid: boolean;
+        readonly reason?: string;
+    }>;
+    invokeGraph(ref: GraphRef, input: JsonValue, boundary?: Exclude<InvocationBoundary, "root">): Promise<InvocationOutcome>;
+}
+export interface DelegateGraphRequest {
+    readonly graph: Graph;
+    readonly input: JsonValue;
+    readonly root: RootRunState;
+    readonly parentInvocation: GraphInvocationState;
+    readonly execute: () => Promise<InvocationOutcome>;
+}
+export interface InvocationAgentHost {
+    runAgent?: GraphRuntimeHost["runAgent"];
+    runAgentFromCode?: GraphRuntimeHost["runAgentFromCode"];
+    dispose(): void | Promise<void>;
+}
+export interface InvocationAgentHostRequest {
+    readonly root: RootRunState;
+    readonly invocation: GraphInvocationState;
+}
+export interface GraphRuntimeHost {
+    /** Hard upper bound; per-run limits may only reduce these values. */
+    readonly limits?: InvocationLimits;
+    readonly catalog?: GraphCatalog;
+    readonly eventBus?: RuntimeEventBus;
+    readonly toolCatalog?: ToolCatalog;
+    readonly skillCatalog?: SkillCatalog;
+    readonly unsafeToolResolver?: UnsafeToolResolver;
+    readonly protocolTools?: readonly ToolImplementation[];
+    readonly baseline?: HostBaseline;
+    /** Maximum UTF-8 bytes of canonical sticky context allowed before an Agent Run. */
+    readonly maxStickyContextBytes?: number;
+    readonly mechanisms?: readonly Mechanism[];
+    readonly mechanismRuntime?: MechanismRuntimeOptions;
+    /** Store for persisting node-boundary checkpoints. */
+    readonly checkpointStore?: CheckpointStore;
+    runAgent?(node: AgentNodeDefinition, input: JsonValue, context: AgentExecutionContext): Promise<JsonValue>;
+    runAgentFromCode?(request: AgentRunRequest, node: CodeNodeDefinition, context: AgentExecutionContext): Promise<JsonValue>;
+    resolveGraph?(ref: GraphRef): Graph | undefined;
+    delegateGraph?(request: DelegateGraphRequest): Promise<InvocationOutcome>;
+    /** Creates an Agent execution lane for one call/compose Graph Invocation. */
+    createInvocationAgentHost?(request: InvocationAgentHostRequest): Promise<InvocationAgentHost>;
+}
+/** Lets an Agent host terminate execution with a stable Runtime failure. */
+export declare class AgentExecutionFailure extends Error {
+    readonly failure: GraphFailure;
+    constructor(failure: GraphFailure);
+}
+export interface GraphExecutionOptions {
+    readonly limits?: Partial<InvocationLimits>;
+    readonly signal?: AbortSignal;
+    readonly maxSteps?: number;
+}
+export interface InvocationOutcome {
+    readonly status: "completed" | "failed" | "cancelled";
+    readonly output?: JsonValue;
+    readonly failure?: GraphFailure;
+}
+export declare class GraphRuntime {
+    private readonly host;
+    readonly eventBus: RuntimeEventBus;
+    private readonly mechanismRuns;
+    private readonly invocationAgentHosts;
+    private readonly activeInvocations;
+    private readonly activeGraphMechanisms;
+    constructor(host?: GraphRuntimeHost);
+    execute<TInputSchema extends TSchema, TOutputSchema extends TSchema>(graph: Graph<TInputSchema, TOutputSchema>, input: SchemaValue<TInputSchema>, options?: number | GraphExecutionOptions): Promise<GraphRunResult<SchemaValue<TOutputSchema>>>;
+    private runInvocation;
+    private exitInvocation;
+    private executeNode;
+    private runAgent;
+    private runCodeAgent;
+    private beginAgent;
+    private finishAgent;
+    private createAgentContext;
+    private assertStickyContextBudget;
+    private executeGraphNode;
+    private invokeGraph;
+    private validateGraphTools;
+    private resolveNodeCapabilities;
+    private resolveSkills;
+    private resolveGraph;
+    private buildInvocationStack;
+    private writeNodeCheckpoint;
+    /** Resume a root graph run from the latest checkpoint. */
+    resume<TInputSchema extends TSchema, TOutputSchema extends TSchema>(graph: Graph<TInputSchema, TOutputSchema>, options: {
+        readonly runId: string;
+        readonly signal?: AbortSignal;
+        readonly checkpointMigrator?: (saved: {
+            readonly id: string;
+            readonly version: string;
+        }) => {
+            readonly id: string;
+            readonly version: string;
+        };
+        readonly maxSteps?: number;
+    }): Promise<GraphRunResult<SchemaValue<TOutputSchema>>>;
+    private resumeFromCheckpoint;
+    private executeNodeWithResume;
+    private assertNotCancelled;
+    private validateSchemaBoundary;
+}