@chainingintention/pi-web-cn 2.0.0 → 2.202610.1

package/dist/pi-packages/captains-log/dist/store.js

@@ -0,0 +1,75 @@
+// Generated from pi-packages/captains-log/src/store.ts. Do not edit directly.
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readdir, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { isLogEntry } from "./browser/protocol.js";
+/** Only host-resolved ids enter the scope hash; peer input is never a filesystem path. */
+export function logScope(projectId, workspaceId) {
+    return createHash("sha256").update(JSON.stringify([projectId, workspaceId])).digest("hex");
+}
+export class LogStore {
+    dataDirectory;
+    constructor(dataDirectory) {
+        this.dataDirectory = dataDirectory;
+    }
+    async directory(scope) {
+        if (!/^[a-f0-9]{64}$/.test(scope))
+            throw new Error("Invalid captain scope");
+        const directory = join(this.dataDirectory, scope);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error("LogEntry directory must not be a symlink");
+        return directory;
+    }
+    async save(scope, captain) {
+        if (!isLogEntry(captain))
+            throw new Error("Invalid captain record");
+        const directory = await this.directory(scope);
+        const temporary = join(directory, `.${randomUUID()}.tmp`);
+        try {
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(captain));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, join(directory, `${captain.id}.json`));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async read(scope, id) {
+        if (typeof id !== "string" || !/^[a-f0-9-]{36}$/.test(id))
+            throw new Error("Invalid captain id");
+        const path = join(await this.directory(scope), `${id}.json`);
+        // O_NOFOLLOW is not enforced on Windows; reject existing links there too.
+        if (!(await lstat(path)).isFile())
+            throw new Error("Invalid captain file");
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > 300_000)
+                throw new Error("Invalid captain file");
+            const value = JSON.parse(await file.readFile("utf8"));
+            if (!isLogEntry(value) || value.id !== id)
+                throw new Error("Invalid saved captain");
+            return value;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    async list(scope) {
+        const names = await readdir(await this.directory(scope));
+        const captains = [];
+        for (const name of names) {
+            if (/^[a-f0-9-]{36}\.json$/.test(name))
+                captains.push(await this.read(scope, name.slice(0, -5)));
+        }
+        return captains.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+    }
+}

package/dist/pi-packages/captains-log/docs/usage.md

@@ -0,0 +1,29 @@
+# 使用船长日志
+
+在当前机器和工作区选择普通会话，打开“船长日志”，点击“让船长转述”。伴随扩展读取源会话当前分支最新已完成的助手文本回复，不发送提示、不修改源转录。独立的船长会话使用你配置的模型转述文本，以海盗船长的风格保留事实、警告、下一步以及原始代码和命令。
+
+船长首次收到角色介绍；后续请求复用仍由 daemon 承载的船长会话。只有在发送请求前明确确认旧船长未被承载时才自动创建新会话，不因超时或任意连接失败重试、重发或替换会话。daemon 重启后，如需保留旧船长的上下文，先在会话列表打开最近的船长日志会话，等待加载完成，再选择需要转述的源会话。
+
+## 结果与连接
+
+- “打开源会话”按照记录的机器、项目、工作区和源会话 ID 返回聊天。目标不可用时显示常规错误，不自动创建替代会话。
+- 结果支持 Markdown 标题、列表、强调、链接、表格和代码块。内嵌 HTML 按文本显示，危险链接不可点击，图片不会自动加载。“历史转述”和“诊断”默认折叠。
+- 打开面板或选择“打开船长转述”不会消耗模型令牌。只有点击转述按钮才提交任务。
+- 浏览器使用双向 peer 通道接收后端进度，无轮询。连接或重连会读取快照；进度不是逐令牌输出，船长完成后才收到最终转述。
+- 关闭面板或浏览器不会取消已被后端接收的工作。重新连接可恢复结果；接收状态不确定时绝不自动重发。
+
+## 无法运行时
+
+源会话必须属于当前机器和工作区，未归档、非临时会话，且不是船长本身。等待源会话空闲，并确保当前分支存在已完成的助手文本回复；未完成、中止、失败及仅包含工具调用的回复不能转述。现有会话缺少伴随扩展时，执行 `/reload` 后重试。
+
+每个工作区同时只运行一个面板转述任务。船长忙碌、转述时直接向其发送其他消息、提供方错误、中止或截断回复、运行时替换均报告失败，不当作成功。接收超时或完成超时仅移除监听，不停止 Pi；不确定请求须先检查船长会话再手动重试。过大的源回复或结果会被拒绝，不静默截断。
+
+转述和元数据保存在宿主提供的插件数据目录，按项目和工作区隔离。会话转录仍由 Pi 管理。中断记录保留，但没有持久任务恢复或自动清理策略。源文本会发送给船长使用的模型提供方；此代码受信任，不提供工具沙箱。
+
+## 安装与激活
+
+在目标机器“设置 → Pi 包 → 可用包”中安装，再到“设置 → PI WEB 插件”显式启用。本包已编译；手动安装可用 `pi install /absolute/path/to/dist/pi-packages/captains-log`。
+
+从承载会话之外手动重启目标 session daemon，再刷新浏览器。仅重启 Web/API 不能激活后端。现有会话执行 `/reload` 加载或更新伴随扩展；项目级包仍须经过正常的项目信任流程。
+
+禁用 PI WEB 插件仅控制面板和后端，不移除原生扩展。移除 Pi 包会移除两种资源声明，但保留会话与插件数据。旧 Workspace Reviews 示例拥有独立插件 ID，须另外禁用或移除。

package/dist/pi-packages/captains-log/i18n.js

@@ -0,0 +1,7 @@
+// Generated from pi-packages/captains-log/i18n.ts. Do not edit directly.
+let translate;
+export function setTranslator(value) {
+    translate = value;
+}
+export const t = (key, fallback, params) => translate?.(key, fallback, params)
+    ?? fallback.replace(/\{([A-Za-z0-9_]+)\}/g, (match, name) => String(params?.[name] ?? match));

package/dist/pi-packages/captains-log/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@chainingintention/pi-captains-log",
+  "version": "0.1.0",
+  "description": "可选船长日志：通过原生 Pi 伴随扩展和 PI WEB 面板转述选中会话的最后一条回复",
+  "private": true,
+  "type": "module",
+  "keywords": ["pi-package"],
+  "files": ["dist", "src", "docs", "test", "tsconfig.json", "vite.config.mjs"],
+  "scripts": { "build": "tsc -p tsconfig.json && vite build", "test": "node --test test/*.test.mjs" },
+  "dependencies": {
+    "marked": "^18.1.1"
+  },
+  "devDependencies": {
+    "@chainingintention/pi-web-cn": "^1.202609.1",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@types/node": "^24.19.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.4"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@chainingintention/pi-web-cn": "^1.202609.1"
+  },
+  "pi": { "extensions": ["./dist/companion.js"] },
+  "piWeb": {
+    "plugins": [{
+      "id": "captains-log",
+      "defaultEnabled": false,
+      "browserRoot": "dist/browser",
+      "module": "dist/browser/index.js",
+      "serverModule": "dist/server.js",
+      "machineSpecific": true
+    }]
+  }
+}

package/dist/pi-packages/captains-log/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/dist/pi-packages/captains-log/vite.config.mjs

@@ -0,0 +1,28 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+
+const packageDir = fileURLToPath(new URL(".", import.meta.url));
+
+export default defineConfig({
+  root: packageDir,
+  base: "./",
+  publicDir: false,
+  build: {
+    outDir: "dist/browser",
+    // Retain the transpiled filenames for existing package/install consumers.
+    emptyOutDir: false,
+    copyPublicDir: false,
+    target: "es2022",
+    sourcemap: false,
+    rollupOptions: {
+      input: fileURLToPath(new URL("src/browser/index.ts", import.meta.url)),
+      preserveEntrySignatures: "strict",
+      output: {
+        format: "es",
+        entryFileNames: "index.js",
+        chunkFileNames: "assets/[name]-[hash].js",
+        assetFileNames: "assets/[name]-[hash][extname]",
+      },
+    },
+  },
+});

package/dist/pi-packages/relays/extensions/index.js

@@ -0,0 +1,61 @@
+// Generated from pi-packages/relays/extensions/index.ts. Do not edit directly.
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { prepareRelayDispatch } from "../relayDispatch.js";
+import { requireRelayLeg } from "../relayIdentity.js";
+const DispatchParams = Type.Object({
+    packet: Type.String({ description: "Saved Relay packet directory containing charter.md, status.md and log.md. Relative paths resolve in the target workspace." }),
+    leg: Type.String({
+        pattern: "^[a-zA-Z0-9][a-zA-Z0-9._-]{0,31}$",
+        description: 'String identity of the leg being dispatched, for example "2" or "R1-a". Numbers and other non-string values are rejected, not converted.',
+    }),
+    cwd: Type.Optional(Type.String({ description: "Target workspace of the same registered project. Omit to use this session's workspace." })),
+    model: Type.Optional(Type.String({ description: 'Exact provider/model-id override. Set only when instructed to select a specific model or choose an appropriate one; otherwise omit to inherit.' })),
+    thinkingLevel: Type.Optional(Type.Enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"], {
+        type: "string",
+        description: "Thinking-level override. Set only when instructed to select a level or choose an appropriate one; otherwise omit to inherit. Pi clamps valid levels to the selected model.",
+    })),
+}, { additionalProperties: false });
+export default function relayExtension(pi) {
+    pi.registerTool(defineTool({
+        name: "dispatch_relay",
+        label: "Dispatch Relay",
+        description: "Start one independent Relay leg from its saved packet. Requires explicit human approval before initial dispatch. Save the actual baton in status.md first; this tool generates the handover and records Relay identity itself. There is no free-form prompt parameter. Use once as the final operational action, then report a brief summary.",
+        promptSnippet: "dispatch_relay: dispatch one Relay leg from its saved packet; approval before initial dispatch; final operational action",
+        exposure: "model-only",
+        parameters: DispatchParams,
+        prepareArguments(args) {
+            const leg = typeof args === "object" && args !== null && !Array.isArray(args) ? Reflect.get(args, "leg") : undefined;
+            requireRelayLeg(leg);
+            // Guard identity before Pi's coercion. Its schema validation checks the
+            // remaining fields next; retain the raw object, including unknown keys.
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+            return args;
+        },
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            signal?.throwIfAborted();
+            const prepared = await prepareRelayDispatch(ctx.cwd, params);
+            signal?.throwIfAborted();
+            const result = await dispatchThroughHost(pi, prepared, {
+                ...(params.model === undefined ? {} : { model: params.model }),
+                ...(params.thinkingLevel === undefined ? {} : { thinkingLevel: params.thinkingLevel }),
+            });
+            const modelNote = result.model === undefined ? "" : ` using model ${result.model}`;
+            return {
+                content: [{ type: "text", text: `Started Relay ${JSON.stringify(prepared.identity.relayName)} leg ${prepared.identity.leg} as independent session ${result.sessionId} in ${result.cwd}${modelNote}. The saved packet is the handover.` }],
+                details: result,
+            };
+        },
+    }));
+}
+/** Documented generic in-process host protocol; unavailable hosts reject before dispatch. */
+async function dispatchThroughHost(pi, prepared, overrides) {
+    let accepted;
+    pi.events.emit("pi-web:session-dispatch:v1", {
+        input: { prompt: prepared.prompt, cwd: prepared.cwd, name: prepared.name, metadata: prepared.metadata, ...overrides },
+        accept: (result) => { accepted = result; },
+    });
+    if (accepted === undefined)
+        throw new Error("Relay dispatch requires PI WEB's session dispatch bridge. Update PI WEB and restart the session daemon when safe; no session was dispatched.");
+    return accepted;
+}

package/dist/pi-packages/relays/i18n.js

@@ -0,0 +1,7 @@
+// Generated from pi-packages/relays/i18n.ts. Do not edit directly.
+let translate;
+export function setTranslator(value) {
+    translate = value;
+}
+export const t = (key, fallback, params) => translate?.(key, fallback, params)
+    ?? fallback.replace(/\{([A-Za-z0-9_]+)\}/g, (match, name) => String(params?.[name] ?? match));

package/dist/{pi-web-plugins → pi-packages}/relays/markdownDocument.js

@@ -1,4 +1,5 @@
-// Generated from pi-web-plugins/relays/markdownDocument.ts. Do not edit directly.
+// Generated from pi-packages/relays/markdownDocument.ts. Do not edit directly.
+import { t } from "./i18n.js";
 import { marked } from "./vendor/marked.esm.js";
 // Raw HTML inside relay documents is escaped before sanitizing, so the
 // sanitizer only ever sees marked-generated markup. This mirrors the safety
@@ -63,7 +64,7 @@ function wrapTablesInScrollRegions(root) {
         const wrapper = document.createElement("div");
         wrapper.className = TABLE_SCROLL_CLASS;
         wrapper.setAttribute("role", "region");
-        wrapper.setAttribute("aria-label", "表格");
+        wrapper.setAttribute("aria-label", t("bundled.relays.table.22d9e7", "Table"));
         wrapper.setAttribute("tabindex", "0");
         table.before(wrapper);
         wrapper.append(table);

package/dist/pi-packages/relays/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@jmfederico/pi-relay",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Goal-led Relay method, durable baton and history, and human-approved preparation prompts for independent Pi session chains.",
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions/index.js"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"]
+  },
+  "piWeb": {
+    "plugins": [
+      { "id": "relays", "browserRoot": ".", "module": "pi-web-plugin.js" }
+    ]
+  }
+}

package/dist/pi-packages/relays/pi-web-plugin.js

@@ -0,0 +1,96 @@
+// Generated from pi-packages/relays/pi-web-plugin.ts. Do not edit directly.
+import { t, setTranslator } from "./i18n.js";
+import { RELAYS_ROOT } from "./relayDiscovery.js";
+import { relayIdentityFromMetadata } from "./relayIdentity.js";
+import { defineRelaysPanelElement, RELAY_SELECTION_QUERY_KEY } from "./relaysPanelElement.js";
+const stylesheetIntegrationCapability = {
+    pluginId: "pi-web", id: "stylesheet-integration", version: 1,
+    parse(value) {
+        if (!isStylesheetIntegration(value)) {
+            throw new Error("Stylesheet integration capability v1 requires registerRoot and createController");
+        }
+        return value;
+    },
+};
+function isStylesheetIntegration(value) {
+    return typeof value === "object" && value !== null
+        && "registerRoot" in value && typeof value.registerRoot === "function"
+        && "createController" in value && typeof value.createController === "function"
+        && "subscribe" in value && typeof value.subscribe === "function";
+}
+const plugin = {
+    apiVersion: 4,
+    name: t("bundled.relays.relays.715ce8", "Relays"),
+    requires: [stylesheetIntegrationCapability],
+    activate: ({ runtimePluginId, html, svg, translate }) => {
+        setTranslator(translate);
+        defineRelaysPanelElement();
+        let stylesheetIntegration;
+        return {
+            start: ({ capabilities }) => {
+                stylesheetIntegration = capabilities.resolve(stylesheetIntegrationCapability);
+            },
+            contributions: {
+                actions: [
+                    {
+                        id: "workspace.open-relays",
+                        title: t("bundled.relays.open.workspace.relays.ead958", "Open workspace relays"),
+                        description: t("bundled.relays.open.the.workspace.relays.tab.relays.are.stored.in.3d8901", "Open the workspace relays tab. Relays are stored in {value1}.", { value1: RELAYS_ROOT }),
+                        group: t("bundled.workspace-tasks.workspace.379798", "Workspace"),
+                        enabled: (context) => context.state.selectedWorkspace !== undefined,
+                        run: (context) => {
+                            if (context.state.selectedWorkspace === undefined)
+                                return;
+                            context.selectWorkspaceTool(`${runtimePluginId}:workspace.relays`);
+                        },
+                    },
+                ],
+                sessionLabels: [
+                    {
+                        id: "session.relay",
+                        items: (context) => {
+                            const identity = relayIdentityFromMetadata(context.session.metadata);
+                            if (identity === undefined)
+                                return [];
+                            return [{
+                                    type: "render",
+                                    render: () => html `
+                  <button
+                    type="button"
+                    style="border:0; padding:0; background:transparent; color:var(--pi-accent); font:inherit; text-align:start; overflow-wrap:anywhere; cursor:pointer"
+                    title=${identity.packetPath}
+                    aria-label=${t("bundled.relays.open.packet", "Open Relay {name}, leg {leg}", { name: identity.relayName, leg: identity.leg })}
+                    @click=${() => context.navigate({
+                                        machineId: context.machine.id,
+                                        projectId: context.workspace.projectId,
+                                        workspaceId: context.workspace.id,
+                                        view: "workspace",
+                                        tool: `${runtimePluginId}:workspace.relays`,
+                                        query: { [RELAY_SELECTION_QUERY_KEY]: identity.packetPath },
+                                    }, { mode: "patch" })}
+                  >${t("bundled.relays.label", "relay")}</button>
+                `,
+                                }];
+                        },
+                    },
+                ],
+                workspacePanels: [
+                    {
+                        id: "workspace.relays",
+                        title: t("bundled.relays.relays.715ce8", "Relays"),
+                        icon: svg `
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                <path d="M9 17H7A5 5 0 0 1 7 7h2"></path>
+                <path d="M15 7h2a5 5 0 1 1 0 10h-2"></path>
+                <line x1="8" y1="12" x2="16" y2="12"></line>
+              </svg>
+            `,
+                        order: 50,
+                        render: (context) => html `<pi-web-relays-panel .stylesheetIntegration=${stylesheetIntegration} .context=${context}></pi-web-relays-panel>`,
+                    },
+                ],
+            },
+        };
+    },
+};
+export default plugin;

package/dist/pi-packages/relays/prompts/relay-worktree.md

@@ -0,0 +1,18 @@
+---
+description: Clarify a goal with the human, then dispatch a Relay in a fresh worktree
+argument-hint: "<what the relay should achieve>"
+---
+
+Prepare a Relay from the request below in a fresh worktree. Load the `relay` and `relay-runner` skills. This differs from `/relay` only in working location; if the request names an existing target, resolve that choice with the human.
+
+Help the human put into words what they want built, what counts as done, and the relay-specific boundaries, limitations, and conditions. Read supplied specifications and inspect the project only as needed to understand that intent. If the request is empty, ask what they want to achieve with `ask_user`.
+
+Draft `.pi-web/relays/<name>/charter.md`, `status.md`, and `log.md` in this checkout under the runner skill's packet convention. Mark status **Draft — awaiting approval; not dispatched**. Capture the requested outcome and any details the human explicitly asks to include, not an agent-invented implementation plan. Leave project rules and skill discovery to each runner; do not turn them into relay instructions. The first runner chooses the first useful slice.
+
+Point the human to the draft, summarize the goal, boundaries, and proposed working location, and resolve material questions together through `ask_user`. Once the goal is understood, ask **Approve and dispatch**, **Revise**, or **Do not dispatch** against the final draft. Drafting and the initial request are not dispatch approval.
+
+On revision, update the draft and obtain approval. On refusal, record that it was not dispatched and stop. After explicit approval, create the worktree and move the packet there as described in the runner skill. Record approval, mark status **Active**, seed leg 1, and finalize the packet with the actual baton saved in `status.md`. Call the dedicated `dispatch_relay` tool once with the moved directory as `packet`, `leg: "1"`, and the new worktree as `cwd`, following the runner skill's handoff mechanics. The tool generates the handover; do not supply a free-form prompt. Dispatch is the final operational action; afterward provide only a brief summary.
+
+<relay_task>
+$ARGUMENTS
+</relay_task>

package/dist/pi-packages/relays/prompts/relay.md

@@ -0,0 +1,18 @@
+---
+description: Clarify a goal with the human, then dispatch a Relay
+argument-hint: "<what the relay should achieve>"
+---
+
+Prepare a Relay from the request below. Load the `relay` and `relay-runner` skills. Use the current checkout unless the human chooses another working location.
+
+Help the human put into words what they want built, what counts as done, and the relay-specific boundaries, limitations, and conditions. Read supplied specifications and inspect the project only as needed to understand that intent. If the request is empty, ask what they want to achieve with `ask_user`.
+
+Draft `.pi-web/relays/<name>/charter.md`, `status.md`, and `log.md` under the runner skill's packet convention. Mark status **Draft — awaiting approval; not dispatched**. Capture the requested outcome and any details the human explicitly asks to include, not an agent-invented implementation plan. Leave project rules and skill discovery to each runner; do not turn them into relay instructions. The first runner chooses the first useful slice.
+
+Point the human to the draft, summarize the goal and boundaries, and resolve material questions together through `ask_user`. Once the goal is understood, ask **Approve and dispatch**, **Revise**, or **Do not dispatch** against the final draft. Drafting and the initial request are not dispatch approval.
+
+On revision, update the draft and obtain approval. On refusal, record that it was not dispatched and stop. After explicit approval, record it, mark status **Active**, seed leg 1, and finalize the packet with the actual baton saved in `status.md`. Call the dedicated `dispatch_relay` tool once with the saved directory as `packet`, `leg: "1"`, and the target checkout as `cwd`, following the runner skill's handoff mechanics. The tool generates the handover; do not supply a free-form prompt. Dispatch is the final operational action; afterward provide only a brief summary.
+
+<relay_task>
+$ARGUMENTS
+</relay_task>

package/dist/{pi-web-plugins → pi-packages}/relays/relayDiscovery.js

@@ -1,7 +1,7 @@
-// Generated from pi-web-plugins/relays/relayDiscovery.ts. Do not edit directly.
+// Generated from pi-packages/relays/relayDiscovery.ts. Do not edit directly.
 export const RELAYS_ROOT = ".pi-web/relays";
 /** Documents that anchor a relay packet, in display order. Any other files follow alphabetically. */
-export const RELAY_ANCHOR_DOCUMENTS = ["status.md", "charter.md", "log.md"];
+export const RELAY_ANCHOR_DOCUMENTS = ["status.md", "charter.md", "operations.md", "log.md"];
 /** Deepest node depth listed below the relay root; direct children are depth 0. */
 export const MAX_RELAY_TREE_DEPTH = 5;
 /** Most documents listed across one relay. */

package/dist/pi-packages/relays/relayDispatch.js

@@ -0,0 +1,67 @@
+// Generated from pi-packages/relays/relayDispatch.ts. Do not edit directly.
+import { open, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isRelayPacketPath, RELAY_METADATA_NAMESPACE, relaySessionName, requireRelayLeg } from "./relayIdentity.js";
+const MAX_PACKET_DOCUMENT_BYTES = 256 * 1024;
+const PACKET_DOCUMENTS = ["charter.md", "status.md", "log.md"];
+/** Validate the durable packet on disk, not handover prose authored by the caller. */
+export async function prepareRelayDispatch(spawningCwd, request) {
+    const leg = requireRelayLeg(request.leg);
+    const cwd = await realpath(resolve(spawningCwd, request.cwd ?? "."));
+    if (typeof request.packet !== "string" || request.packet.trim() === "")
+        throw new Error("A saved Relay packet directory is required");
+    const packet = await realpath(resolve(cwd, request.packet));
+    const packetPath = relative(cwd, packet).split(sep).join("/");
+    if (!isRelayPacketPath(packetPath))
+        throw new Error("Relay packet must be a directory inside the target workspace");
+    for (const document of PACKET_DOCUMENTS)
+        await validateDocument(packet, document);
+    const identity = { version: 1, packetPath, relayName: basename(packet), leg };
+    return {
+        cwd,
+        identity,
+        name: relaySessionName(identity),
+        metadata: { [RELAY_METADATA_NAMESPACE]: identity },
+        prompt: relayHandoverInstructions(cwd, packet, identity),
+    };
+}
+function relayHandoverInstructions(cwd, packet, identity) {
+    return [
+        `Continue Relay ${JSON.stringify(identity.relayName)}, leg ${identity.leg}, in ${JSON.stringify(cwd)}.`,
+        "Load the `relay` and `relay-runner` skills.",
+        `Read ${JSON.stringify(join(packet, "charter.md"))} and ${JSON.stringify(join(packet, "status.md"))}.`,
+        "The charter is the agreed goal and status.md is the actual baton. Consult the saved history and supporting documents only as needed; do not substitute dispatch prose for the packet.",
+        "Check the finish line against the current work and choose the next useful slice.",
+        "Make progress and the record durable, then hand off once, complete, or signal that you need help.",
+    ].join("\n");
+}
+async function validateDocument(packet, document) {
+    const path = await realpath(join(packet, document));
+    const inside = relative(packet, path);
+    if (isAbsolute(inside) || inside === ".." || inside.startsWith(`..${sep}`))
+        throw new Error(`Relay ${document} must stay inside the packet`);
+    const info = await stat(path);
+    if (!info.isFile() || info.size === 0 || info.size > MAX_PACKET_DOCUMENT_BYTES) {
+        throw new Error(`Relay ${document} must be a non-empty regular file of at most ${String(MAX_PACKET_DOCUMENT_BYTES)} bytes`);
+    }
+    const file = await open(path, "r");
+    try {
+        // Bound reads even if another process grows the document after stat.
+        const buffer = Buffer.alloc(MAX_PACKET_DOCUMENT_BYTES + 1);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_PACKET_DOCUMENT_BYTES)
+            throw new Error(`Relay ${document} exceeds the document size limit`);
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, bytesRead));
+        }
+        catch {
+            throw new Error(`Relay ${document} must be UTF-8 text`);
+        }
+        if (text.trim() === "" || text.includes("\0"))
+            throw new Error(`Relay ${document} must contain saved text`);
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/pi-packages/relays/relayIdentity.js

@@ -0,0 +1,37 @@
+// Generated from pi-packages/relays/relayIdentity.ts. Do not edit directly.
+/** Relay owns this schema; core treats it as opaque browser-public JSON. */
+export const RELAY_METADATA_NAMESPACE = "@jmfederico/pi-relay";
+export function relayIdentityFromMetadata(metadata) {
+    const value = metadata?.[RELAY_METADATA_NAMESPACE];
+    if (value?.["version"] !== 1)
+        return undefined;
+    const packetPath = value["packetPath"];
+    const relayName = value["relayName"];
+    const leg = value["leg"];
+    if (typeof packetPath !== "string" || !isRelayPacketPath(packetPath)
+        || typeof relayName !== "string" || relayName !== packetPath.split("/").at(-1)
+        || typeof leg !== "string" || !isRelayLeg(leg))
+        return undefined;
+    return { version: 1, packetPath, relayName, leg };
+}
+export function isRelayPacketPath(value) {
+    // eslint-disable-next-line no-control-regex -- packet paths must not contain control characters.
+    return value.length > 0 && value.length <= 4096 && !/[\\\u0000-\u001f\u007f]/u.test(value)
+        && value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== ".." && segment === segment.trim());
+}
+export function isRelayLeg(value) {
+    return /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,31}$/u.test(value);
+}
+export function requireRelayLeg(value) {
+    if (typeof value !== "string" || !isRelayLeg(value)) {
+        throw new Error("Relay leg must be a string of 1–32 letters, digits, dots, underscores or hyphens, starting with a letter or digit");
+    }
+    return value;
+}
+/** Keep the leg first so host and sidebar truncation only shorten the Relay name. */
+export function relaySessionName(identity) {
+    const prefix = `Leg ${identity.leg} – Relay `;
+    const room = 60 - prefix.length;
+    const name = identity.relayName.slice(0, room).replace(/[\s._-]+$/u, "") || identity.relayName.slice(0, room);
+    return `${prefix}${name}`;
+}