@yefengr/pi-reach 0.0.6 → 0.0.8

package/dist/files/publications.js

@@ -0,0 +1,136 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { parseSessionEntries } from "@earendil-works/pi-coding-agent";
+import { idSchema, PUBLISHED_FILE_TYPE, publishedFileMetadataSchema } from "../vendor/protocol/session/index.js";
+import { z } from "zod";
+export const PUBLISHED_FILE_TOOL_NAME = "publish_file";
+/** 只存于原生 custom；不能把此 schema 当作 wire payload。 */
+export const publicationDataSchema = publishedFileMetadataSchema.extend({
+    source_path: z.string().min(1).refine((path) => !path.includes("\0") && isAbsolute(path) && resolve(path) === path),
+    group_id: idSchema.optional(),
+}).strict();
+const resultDetailsSchema = z.object({ publication_id: idSchema }).strict();
+// 一个 manager 最多保留一个文件的解析结果；manager 回收时缓存随之回收。
+const diskProofs = new WeakMap();
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function diskEntries(manager) {
+    try {
+        const path = manager.getSessionFile();
+        if (!path)
+            return null;
+        const before = statSync(path, { bigint: true });
+        if (!before.isFile())
+            return null;
+        const cached = diskProofs.get(manager);
+        if (cached?.path === path && sameFile(cached.stat, before))
+            return cached.entries;
+        const entries = parseSessionEntries(readFileSync(path, "utf8"));
+        const after = statSync(path, { bigint: true });
+        if (!after.isFile() || !sameFile(before, after))
+            return null;
+        diskProofs.set(manager, { path, stat: after, entries });
+        return entries;
+    }
+    catch {
+        diskProofs.delete(manager);
+        return null;
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** JSONL 不存 undefined 字段；比较完整原生记录而非只比较 publication_id。 */
+function samePersistedEntry(current, persisted) {
+    return isDeepStrictEqual(JSON.parse(JSON.stringify(current)), persisted);
+}
+function addByCall(map, callId, value) {
+    if (typeof callId !== "string")
+        return;
+    const matches = map.get(callId) ?? [];
+    matches.push(value);
+    map.set(callId, matches);
+}
+/**
+ * 原生成功 toolResult 是确认点，且 custom/result 两者均须已落盘。
+ * 失败 append 留下的内部孤立记录无资格；不尝试回滚 SDK 的 append-only 树。
+ */
+export function collectPublications(manager) {
+    const confirmed = new Map();
+    try {
+        const persisted = diskEntries(manager);
+        if (!persisted)
+            return confirmed;
+        const headers = persisted.filter((entry) => record(entry) && entry.type === "session");
+        const header = manager.getHeader();
+        if (headers.length !== 1 || persisted[0] !== headers[0] || !header
+            || header.id !== manager.getSessionId() || !samePersistedEntry(header, headers[0]))
+            return confirmed;
+        const diskById = new Map();
+        for (const entry of persisted) {
+            if (!record(entry) || !idSchema.safeParse(entry.id).success || diskById.has(entry.id))
+                return confirmed;
+            diskById.set(entry.id, entry);
+        }
+        const branch = manager.getBranch();
+        const customs = new Map();
+        const results = new Map();
+        const branchIds = new Set();
+        const persistedPrefixes = [];
+        let persistedPrefix = true;
+        for (let index = 0; index < branch.length; index++) {
+            const entry = branch[index];
+            if (branchIds.has(entry.id) || entry.parentId !== (index === 0 ? null : branch[index - 1].id))
+                return confirmed;
+            branchIds.add(entry.id);
+            const diskEntry = diskById.get(entry.id);
+            persistedPrefix = persistedPrefix && diskEntry?.type === entry.type
+                && "parentId" in diskEntry && diskEntry.parentId === entry.parentId;
+            persistedPrefixes.push(persistedPrefix);
+            if (entry.type === "custom" && entry.customType === PUBLISHED_FILE_TYPE) {
+                addByCall(customs, record(entry.data) ? entry.data.tool_call_id : undefined, { entry, index });
+            }
+            else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === PUBLISHED_FILE_TOOL_NAME) {
+                addByCall(results, entry.message.toolCallId, { entry, index });
+            }
+        }
+        const candidates = [];
+        for (const [callId, matches] of customs) {
+            const tools = results.get(callId);
+            if (matches.length !== 1 || tools?.length !== 1)
+                continue;
+            const custom = matches[0];
+            const result = tools[0];
+            const data = publicationDataSchema.safeParse(custom.entry.data);
+            const message = result.entry.message;
+            if (!data.success || message.role !== "toolResult" || message.isError !== false
+                || result.index <= custom.index || !persistedPrefixes[result.index])
+                continue;
+            const details = resultDetailsSchema.safeParse(message.details);
+            const timestamp = Date.parse(custom.entry.timestamp);
+            if (!details.success || details.data.publication_id !== custom.entry.id || !Number.isFinite(timestamp) || timestamp < 0)
+                continue;
+            if (!samePersistedEntry(custom.entry, diskById.get(custom.entry.id))
+                || !samePersistedEntry(result.entry, diskById.get(result.entry.id)))
+                continue;
+            const { source_path, group_id, ...metadata } = data.data;
+            candidates.push({
+                id: custom.entry.id, sourcePath: source_path, metadata, timestamp,
+                ...(group_id === undefined ? {} : { groupId: group_id }),
+                branchPosition: result.index + 0.5,
+            });
+        }
+        candidates.sort((left, right) => left.branchPosition - right.branchPosition);
+        for (const candidate of candidates)
+            confirmed.set(candidate.id, candidate);
+        return confirmed;
+    }
+    catch {
+        // 不可信或无法读取的原生记录只能拒绝资格，不能降级为内存证明。
+        return new Map();
+    }
+}
+//# sourceMappingURL=publications.js.map

package/dist/files/publications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publications.js","sourceRoot":"","sources":["../../src/files/publications.ts"],"names":[],"mappings":"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"}

package/dist/files/publish-tool.d.ts

@@ -0,0 +1,23 @@
+import type { SessionManager, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+declare const parameters: Type.TObject<{
+    path: Type.TString;
+}>;
+export type PublishFileToolOptions = {
+    getManager: () => SessionManager | null;
+    isCurrent: () => boolean;
+    getGeneration: () => number;
+    getGroupId: () => string | null;
+    /** 仅在共享资源账目中完成 inspection 并关闭句柄后 resolve。 */
+    inspect: (absolutePath: string) => Promise<{
+        sourcePath: string;
+        fileName: string;
+        mimeType: string;
+        byteLength: number;
+    }>;
+};
+export type PublishFileToolDetails = {
+    publication_id: string;
+};
+export declare function createPublishFileTool(options: PublishFileToolOptions): ToolDefinition<typeof parameters, PublishFileToolDetails>;
+export {};

package/dist/files/publish-tool.js

@@ -0,0 +1,70 @@
+import { resolve } from "node:path";
+import { statSync } from "node:fs";
+import { PUBLISHED_FILE_TYPE } from "../vendor/protocol/session/index.js";
+import { Type } from "typebox";
+import { publicationDataSchema, PUBLISHED_FILE_TOOL_NAME } from "./publications.js";
+const parameters = Type.Object({ path: Type.String({ minLength: 1 }) }, { additionalProperties: false });
+const FAILURE_TEXT = "文件发布失败";
+function storedSession(manager, file) {
+    try {
+        return manager.isPersisted() && !!file && statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function createPublishFileTool(options) {
+    // SDK sequential 是调度约束；此门禁也阻止意外重入或嵌套直接调用。
+    let executing = false;
+    return {
+        name: PUBLISHED_FILE_TOOL_NAME,
+        label: "发布文件",
+        description: "仅发布面向用户交付的成果，或用户明确要求的文件；不要自动发布所有读取、修改或临时文件。已授权 PWA 可能自动获取受支持的小图片。path 相对当前工作目录或为绝对路径，允许项目外的普通文件；只保存引用，不复制原件。",
+        parameters,
+        executionMode: "sequential",
+        async execute(toolCallId, args, signal, _onUpdate, ctx) {
+            if (executing)
+                throw new Error(FAILURE_TEXT);
+            executing = true;
+            try {
+                const manager = options.getManager();
+                const generation = options.getGeneration();
+                const groupId = options.getGroupId();
+                if (!manager)
+                    throw new Error(FAILURE_TEXT);
+                const sessionId = manager.getSessionId();
+                const sessionFile = manager.getSessionFile();
+                const valid = () => options.isCurrent() && !signal?.aborted && !ctx.signal?.aborted
+                    && options.getGeneration() === generation && options.getManager() === manager
+                    && ctx.sessionManager === manager && ctx.sessionManager.getSessionId() === sessionId
+                    && manager.getSessionId() === sessionId && manager.getSessionFile() === sessionFile
+                    && storedSession(manager, sessionFile);
+                if (!valid() || typeof args.path !== "string" || !args.path || args.path.includes("\0"))
+                    throw new Error(FAILURE_TEXT);
+                const inspected = await options.inspect(resolve(ctx.cwd, args.path));
+                const data = publicationDataSchema.parse({
+                    source_path: inspected.sourcePath,
+                    file_name: inspected.fileName,
+                    mime_type: inspected.mimeType,
+                    byte_length: inspected.byteLength,
+                    tool_call_id: toolCallId,
+                    ...(groupId === null ? {} : { group_id: groupId }),
+                });
+                if (!valid())
+                    throw new Error(FAILURE_TEXT);
+                const text = `已发布文件引用：${data.file_name} · ${data.mime_type} · ${data.byte_length} B`;
+                const publicationId = manager.appendCustomEntry(PUBLISHED_FILE_TYPE, data);
+                // append 后没有可失败的 await；正式资格由随后落盘的成功原生 toolResult 建立。
+                return { content: [{ type: "text", text }], details: { publication_id: publicationId } };
+            }
+            catch {
+                // SDK 会将 throw 转为 isError；不把内部路径或 I/O 异常暴露给消息与日志。
+                throw new Error(FAILURE_TEXT);
+            }
+            finally {
+                executing = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=publish-tool.js.map

package/dist/files/publish-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-tool.js","sourceRoot":"","sources":["../../src/files/publish-tool.ts"],"names":[],"mappings":"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"}

package/dist/files/reader.d.ts

@@ -0,0 +1,66 @@
+import { type ClientFrame, type ServerFrame } from "../vendor/protocol/session/index.js";
+export type FileScope = {
+    ownerId: string;
+    channelId: string;
+    runtimeId: string;
+    sessionId: string;
+    generation: number;
+};
+type Request = Extract<ClientFrame, {
+    type: "file_open" | "file_read" | "file_close";
+}>;
+type Response = Extract<ServerFrame, {
+    type: "file_opened" | "file_chunk" | "file_closed" | "file_error";
+}>;
+type Options = {
+    resolve: (scope: FileScope, publicationId: string) => {
+        sourcePath: string;
+    } | null | Promise<{
+        sourcePath: string;
+    } | null>;
+    isCurrent: (scope: FileScope) => boolean;
+    idleMs?: number;
+    maxResources?: number;
+};
+/** 所有异步任务共享额度；失效不等于内核 I/O 已停止或句柄已关闭。 */
+export declare class FileReaderRuntime {
+    private readonly options;
+    private readonly resources;
+    private readonly opens;
+    private readonly idleMs;
+    private readonly maxResources;
+    private timer?;
+    private timerDeadline?;
+    private disposed;
+    constructor(options: Options);
+    get resourceCount(): number;
+    private reserve;
+    private schedule;
+    private invalidate;
+    private assertCurrent;
+    private eligible;
+    private checked;
+    private release;
+    private closeHandle;
+    private cleanup;
+    private finish;
+    private reply;
+    private failure;
+    handle(frame: Request, suppliedScope: FileScope): Promise<Response>;
+    private open;
+    private openResponse;
+    private openTask;
+    private verify;
+    private readTask;
+    private read;
+    inspectForPublication(path: string): Promise<{
+        sourcePath: string;
+        fileName: string;
+        mimeType: string;
+        byteLength: number;
+    }>;
+    private inspectTask;
+    closeWhere(predicate: (scope: FileScope) => boolean): Promise<void>;
+    dispose(): Promise<void>;
+}
+export {};