pi-loop-graph-sdk 0.2.0

package/dist/adapter/observability.d.ts

@@ -0,0 +1,88 @@
+import type { CompletionValidationStage, NodeCompletion } from "../type.js";
+export interface AgentRunLifecycleContext {
+    timestamp: number;
+    graphRunId: string;
+    graphId: string;
+    nodeId: string;
+    scopeId: string;
+    agentRunId: number;
+}
+export type LoopGraphLifecycleEvent = Readonly<{
+    type: "graph_start";
+    timestamp: number;
+    graphId: string;
+    boundary: string;
+    invocationKind: string;
+} | {
+    type: "graph_end";
+    timestamp: number;
+    graphId: string;
+    status: string;
+    steps: number;
+} | {
+    type: "graph_error";
+    timestamp: number;
+    graphId: string;
+    error: string;
+} | {
+    type: "node_enter";
+    timestamp: number;
+    graphId: string;
+    nodeId: string;
+    scopeId: string;
+    depth: number;
+} | {
+    type: "node_exit";
+    timestamp: number;
+    graphId: string;
+    nodeId: string;
+    scopeId: string;
+    status: string;
+    depth: number;
+} | {
+    type: "compaction";
+    timestamp: number;
+    graphId: string;
+    nodeId: string;
+    scopeId: string;
+    generation: number;
+    reason?: unknown;
+} | (AgentRunLifecycleContext & {
+    type: "output_contract.prepared";
+    schemaFingerprint: string;
+    schemaBytes: number;
+}) | (AgentRunLifecycleContext & {
+    type: "completion.submitted";
+    schemaFingerprint?: string;
+}) | (AgentRunLifecycleContext & {
+    type: "completion.validation_started";
+    validatorStage: CompletionValidationStage;
+    schemaFingerprint?: string;
+}) | (AgentRunLifecycleContext & {
+    type: "completion.accepted";
+    completionStatus: NodeCompletion["status"];
+    schemaFingerprint?: string;
+    durationMs: number;
+}) | (AgentRunLifecycleContext & {
+    type: "completion.rejected";
+    reason: string;
+    validatorStage?: CompletionValidationStage;
+    schemaFingerprint?: string;
+    durationMs: number;
+}) | (AgentRunLifecycleContext & {
+    type: "completion.failed";
+    scope: "node" | "graph";
+    reason: string;
+    validatorStage?: CompletionValidationStage;
+    schemaFingerprint?: string;
+    durationMs: number;
+})>;
+export type LoopGraphTraceSink = (event: LoopGraphLifecycleEvent) => void | Promise<void>;
+export interface LoopGraphLogger {
+    debug?(message: string, event?: LoopGraphLifecycleEvent): void;
+    error?(message: string, event?: LoopGraphLifecycleEvent): void;
+}
+/** 观测失败不得改变图控制流。 */
+export declare function emitLifecycleEvent(event: LoopGraphLifecycleEvent, traceSink?: LoopGraphTraceSink, logger?: LoopGraphLogger): void;
+/** debug 模式使用的 JSONL sink；创建时不会清空已有文件。 */
+export declare function createJsonlTraceSink(filePath?: string): LoopGraphTraceSink;

package/dist/adapter/observability.js

@@ -0,0 +1,31 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** 观测失败不得改变图控制流。 */
+export function emitLifecycleEvent(event, traceSink, logger) {
+    try {
+        const pending = traceSink?.(event);
+        if (pending && typeof pending.catch === "function") {
+            void pending.catch(() => { });
+        }
+    }
+    catch {
+        // observability is best-effort
+    }
+    try {
+        const message = `[loop-graph] ${event.type}`;
+        if (event.type === "graph_error")
+            logger?.error?.(message, event);
+        else
+            logger?.debug?.(message, event);
+    }
+    catch {
+        // logger failures are isolated from execution
+    }
+}
+/** debug 模式使用的 JSONL sink；创建时不会清空已有文件。 */
+export function createJsonlTraceSink(filePath = path.resolve("loop-graph-debug.log")) {
+    const resolved = path.resolve(filePath);
+    return (event) => {
+        fs.appendFileSync(resolved, `${JSON.stringify(event)}\n`, "utf8");
+    };
+}

package/dist/adapter/output-contract.d.ts

@@ -0,0 +1,12 @@
+import type { CompletionValidationResult, JsonSchema } from "../type.js";
+export declare const DEFAULT_OUTPUT_CONTRACT_MAX_BYTES: number;
+export declare const OUTPUT_CONTRACT_MESSAGE_TYPE = "loop_graph_output_contract";
+export interface PreparedOutputContract {
+    readonly schema: JsonSchema;
+    readonly serialized: string;
+    readonly modelText: string;
+    readonly fingerprint: string;
+    readonly byteSize: number;
+    validate(result: Record<string, unknown>): CompletionValidationResult;
+}
+export declare function prepareOutputContract(schema: JsonSchema | undefined, maxBytes?: number): PreparedOutputContract | null;

package/dist/adapter/output-contract.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import Schema from "typebox/schema";
+export const DEFAULT_OUTPUT_CONTRACT_MAX_BYTES = 64 * 1024;
+export const OUTPUT_CONTRACT_MESSAGE_TYPE = "loop_graph_output_contract";
+export function prepareOutputContract(schema, maxBytes = DEFAULT_OUTPUT_CONTRACT_MAX_BYTES) {
+    if (schema == null)
+        return null;
+    if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+        throw new TypeError(`outputContractMaxBytes 必须是正整数，收到: ${String(maxBytes)}`);
+    }
+    const normalized = normalizeJsonValue(schema, "$", new Set());
+    const serialized = JSON.stringify(normalized, null, 2);
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    if (bytes > maxBytes) {
+        throw new Error(`outputSchema 序列化后为 ${bytes} bytes，超过 outputContractMaxBytes (${maxBytes})`);
+    }
+    const validator = Schema.Compile(normalized);
+    const fingerprint = createHash("sha256").update(serialized).digest("hex");
+    return Object.freeze({
+        schema: deepFreeze(normalized),
+        serialized,
+        fingerprint,
+        byteSize: bytes,
+        modelText: [
+            "=== OUTPUT CONTRACT ===",
+            "提交到 __graph_complete__.result 的值必须严格符合以下 JSON Schema：",
+            serialized,
+            "=== END OUTPUT CONTRACT ===",
+        ].join("\n"),
+        validate(result) {
+            const [isValid, errors] = validator.Errors(result);
+            if (isValid)
+                return { isValid: true };
+            const summary = errors.slice(0, 5).map((error) => {
+                const path = error.instancePath || "$";
+                return `${path} ${error.message}`;
+            }).join("; ");
+            return { isValid: false, reason: `输出不符合 outputSchema: ${summary}` };
+        },
+    });
+}
+function normalizeJsonValue(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${path} 包含非有限数字`);
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError(`${path} 包含不可序列化的 ${typeof value}`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError(`${path} 包含循环引用`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.keys(value).length !== value.length) {
+                throw new TypeError(`${path} 包含稀疏数组或非索引属性`);
+            }
+            return value.map((entry, index) => normalizeJsonValue(entry, `${path}[${index}]`, ancestors));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`${path} 必须是普通 JSON 对象`);
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError(`${path} 包含 JSON 无法表示的 symbol key`);
+        }
+        const output = {};
+        for (const key of Object.keys(value).sort()) {
+            output[key] = normalizeJsonValue(value[key], `${path}.${key}`, ancestors);
+        }
+        return output;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}

package/dist/adapter/pi-node-context.d.ts

@@ -0,0 +1,132 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ContextSnapshot } from "../core/context.js";
+import type { ReplayEventScope } from "../replay/events.js";
+import type { CompletionSubmissionDecision, CompletionValidationStage, NodeCompletion, NodeContext } from "../type.js";
+import type { AgentRunRequest } from "../type.js";
+import { type ModelMessageFormatter } from "./model-messages.js";
+export interface AgentRunMechanismLifecycle {
+    beforeAgentRun(agentRunId: number, request: AgentRunRequest): Promise<{
+        blocked: boolean;
+        reason?: string;
+    }>;
+    validateCompletion(agentRunId: number, completion: NodeCompletion): Promise<{
+        action: "allow";
+        verifiedResult?: NodeCompletion["verifiedResult"];
+    } | {
+        action: "reject" | "fail-node" | "fail-graph";
+        reason: string;
+    }>;
+    afterAgentRun(agentRunId: number): void;
+}
+export type AgentRunTelemetryEvent = {
+    type: "output_contract.prepared";
+    agentRunId: number;
+    schemaFingerprint: string;
+    schemaBytes: number;
+} | {
+    type: "completion.submitted";
+    agentRunId: number;
+    schemaFingerprint?: string;
+} | {
+    type: "completion.validation_started";
+    agentRunId: number;
+    validatorStage: CompletionValidationStage;
+    schemaFingerprint?: string;
+} | {
+    type: "completion.accepted";
+    agentRunId: number;
+    completionStatus: NodeCompletion["status"];
+    schemaFingerprint?: string;
+    durationMs: number;
+} | {
+    type: "completion.rejected";
+    agentRunId: number;
+    reason: string;
+    validatorStage?: CompletionValidationStage;
+    schemaFingerprint?: string;
+    durationMs: number;
+} | {
+    type: "completion.failed";
+    agentRunId: number;
+    scope: "node" | "graph";
+    reason: string;
+    validatorStage?: CompletionValidationStage;
+    schemaFingerprint?: string;
+    durationMs: number;
+};
+type CompletionState = "submitted" | "validating" | "accepted" | "rejected" | "failed";
+export declare const CONTEXT_SNAPSHOT_MESSAGE_TYPE = "loop_graph_context";
+export declare class PiNodeContext implements NodeContext {
+    private readonly outputContractMaxBytes;
+    private readonly telemetry?;
+    readonly signal: AbortSignal;
+    private pi;
+    private currentNodeId;
+    /** __graph_complete__ 捕获的 completion 列表（同节点内可能调多次） */
+    private pendingCompletions;
+    private readonly completionFingerprints;
+    /** 活跃 run 的 resolve */
+    private activeResolve;
+    private activeRunId;
+    private nextRunId;
+    private readonly agentRunTimeoutMs;
+    private readonly messageFormatter;
+    private readonly completionValidationTimeoutMs;
+    private nodeValidateFn;
+    private routeValidateFn;
+    private postMechanismValidateFn;
+    private mechanismLifecycle;
+    private validationInFlight;
+    private activeOutputContract;
+    private activeOutputContractMessage;
+    private activeContextSnapshot;
+    private contextProjectionCount;
+    private foldableContextCompacted;
+    private submissionQueue;
+    private rejectionCount;
+    private completionState;
+    get completionSubmissionState(): CompletionState;
+    constructor(pi: ExtensionAPI, agentRunTimeoutMs?: number, messageFormatter?: ModelMessageFormatter, completionValidationTimeoutMs?: number, outputContractMaxBytes?: number, telemetry?: ((event: AgentRunTelemetryEvent) => void) | undefined);
+    private runValidateFn;
+    runAgent(request: AgentRunRequest): Promise<NodeCompletion>;
+    /**
+     * 直接执行 pi 平台上的工具。当前占用位，未实现。
+     *
+     * 纯代码节点不需要此方法——你可以在 execute 里直接
+     * import 并使用任何 Node.js 或第三方库：
+     *
+     * ```typescript
+     * execute: async (instance, input, ctx) => {
+     *   const data = fs.readFileSync(input.data.path, "utf-8");
+     *   const result = await fetch("https://api.example.com", {...});
+     *   return { nodeId: "parse", status: "ok", result: { data, result } };
+     * }//讨论在有纯代码节点的前提下该功能是否必要
+     * ```
+     */
+    callTool(_name: string, _input: Record<string, unknown>): Promise<unknown>;
+    /** 当前节点内调用 __graph_complete__ 的次数 */
+    get completeCount(): number;
+    getActiveOutputContractMessage(): Readonly<Record<string, unknown>> | null;
+    setContextSnapshot(snapshot: ContextSnapshot | null): void;
+    markContextCompacted(): void;
+    getContextSnapshotMessage(): Readonly<Record<string, unknown>> | null;
+    getReplayScope(): ReplayEventScope | null;
+    submitCompletion(params: {
+        result: Record<string, unknown>;
+    }): Promise<CompletionSubmissionDecision>;
+    onAgentEnd(): Promise<void>;
+    private processAgentEnd;
+    private processCompletionSubmission;
+    private rejectOrExhaust;
+    setCurrentNodeId(nodeId: string): void;
+    setNodeCompletionValidator(validate: AgentRunRequest["validateCompletion"]): void;
+    setRouteCompletionValidator(validate: AgentRunRequest["validateCompletion"]): void;
+    setPostMechanismCompletionValidator(validate: AgentRunRequest["validateCompletion"]): void;
+    setMechanismLifecycle(lifecycle: AgentRunMechanismLifecycle | null): void;
+    private runValidationStage;
+    private emitValidationStarted;
+    private emitTelemetry;
+    private clearAgentRunArtifacts;
+    reset(): void;
+}
+export {};