@yefengr/pi-reach 0.0.6 → 0.0.8

package/README.md

@@ -1,62 +1,73 @@
-<h1 align="center">Pi Reach</h1>
+# Pi Reach
 
-> A Pi Extension for controlling the current Pi process from the browser through a Relay.
+Control your running Pi coding agent from your phone or any browser.
 
-`/pi-reach` connects the current Pi process to a Relay, supports Owner pairing, and exposes the live timeline plus typed session actions to the Pi Reach PWA.
+When you step away from your computer, Pi Reach lets you follow Pi's live responses and tool calls, send another prompt or a file, and stop the current task. Pi keeps running on your computer; the browser is its remote interface.
 
-## Endpoint model
+![Pi Reach desktop workspace with multiple online Pi sessions and a live conversation](https://raw.githubusercontent.com/yefengr/pi-reach/main/docs/assets/screenshot-desktop-en.png)
 
-```text
-device -> endpoint -> runtime -> session / history generation
-```
+## Features
 
-- **Device**: the computer's Ed25519 identity.
-- **Endpoint and runtime**: generated randomly when a Pi process loads the Extension. They remain stable across Extension reloads in that process and are regenerated for the next Pi process.
-- **Session / generation**: the active Pi conversation and its current history branch. Pi Reach does not list or resume historical sessions.
+- **Pair without an account**: scan a QR code or enter an 8-character pairing code. Pair each computer once; later Pi processes on that computer appear automatically.
+- **Switch between computers and Pi sessions**: connect to multiple computers and choose among the Pi processes currently running on each one.
+- **Follow and control a live conversation**: stream responses and tool calls, send prompts and file attachments, or stop the current task. Attachments reach your computer as original files for Pi to read; image previews do not automatically become model vision input.
+- **Manage the current session**: start a new conversation, compact context, or change the model and thinking level.
+- **Use an installable PWA**: add the browser app to your home screen, choose light or dark mode, and use English or Chinese. Previously received conversations remain available for read-only viewing in that browser while offline.
 
-The endpoint never derives from the working directory. Pairing QR codes target the current endpoint and runtime, while the resulting Owner authorization is stored at device scope. Later Pi processes on that computer are discovered without pairing again.
+![Pi Reach mobile conversation with tool activity and the message composer](https://raw.githubusercontent.com/yefengr/pi-reach/main/docs/assets/screenshot-mobile-en.png)
 
 ## Quick start
 
-Install the Extension once:
+1. Install the Extension:
 
-```bash
-pi install npm:@yefengr/pi-reach
-```
+   ```bash
+   pi install npm:@yefengr/pi-reach
+   ```
 
-Open Pi in the project you want to control. When the session starts, the Extension automatically connects to the configured Relay. Pair the browser device from Pi:
+2. Open Pi in the project you want to control. The Extension automatically connects to the configured Relay when the session starts.
+3. Open the public [Pi Reach PWA](https://pi-reach.yefengr.cn/app) on your phone or another browser.
+4. Run this command in Pi, then scan the terminal QR code from the PWA or enter the 8-character pairing code:
 
-```text
-/pi-reach pair
-```
+   ```text
+   /pi-reach pair
+   ```
 
-Open the public [Pi Reach PWA](https://pi-reach.yefengr.cn/app) on your phone or another browser, scan the QR code or type the 8-character pairing code, then pick an online Pi and send a prompt. Each computer only needs to be paired once, and pairings are local to the computer that creates them:
+5. Pick an online Pi in the PWA and send your first prompt.
 
-```text
-/pi-reach devices
-/pi-reach revoke <shortid>
-```
+Each computer only needs to be paired once. Pairings apply to the computer that creates them, not to every computer you use.
+
+The public PWA and the default Relay are run by the maintainer. For sensitive work, [self-host the PWA and Relay](https://github.com/yefengr/pi-reach/blob/main/README.en.md#self-hosting).
+
+## Security and limits
 
-The public PWA and the default Relay are run by the maintainer. For sensitive work, self-host both; see [Self-hosting](../README.en.md#self-hosting) and [Pairing and security](#pairing-and-security).
+**Pi Reach has no application-layer end-to-end encryption. The Relay is fully trusted.** TLS protects transport, but the Relay operator can read conversation content, including code, commands, and output. The operator could also impersonate a paired browser and send prompts that Pi executes on your computer. Use a Relay you control for sensitive work.
+
+- Pi must already be running with the Extension loaded. Pi Reach cannot remotely start, wake, or keep Pi running in the background.
+- Browser history is a local, read-only cache of received conversations, not a cloud backup or a way to browse and resume old Pi sessions on your computer.
+- Sending prompts and files requires a live connection. There is no offline send queue or push notifications, and phone lock-screen connectivity is not guaranteed.
+- Browser identity, pairings, and received history stay in that browser's local storage. Clearing site data removes them and requires pairing again. There are no cloud accounts or cross-browser history synchronization.
+- Revoke browsers you no longer use from Pi with `/pi-reach revoke <shortid>`; list them with `/pi-reach devices`.
+
+Report vulnerabilities through GitHub's [private vulnerability reporting](https://github.com/yefengr/pi-reach/security/advisories/new); see the [security policy](https://github.com/yefengr/pi-reach/blob/main/SECURITY.md).
 
 ## Commands
 
 | Command | Description |
 |---|---|
-| `/pi-reach` | Connect the current Pi endpoint after it was stopped |
-| `/pi-reach start` / `/pi-reach stop` | Connect or disconnect this endpoint |
-| `/pi-reach status` | Show Relay, endpoint, runtime, and Owner state |
-| `/pi-reach pair` | Show an endpoint-aware pairing QR |
-| `/pi-reach devices` | List locally paired Owners |
-| `/pi-reach revoke <shortid>` | Revoke one locally stored Owner |
-| `/pi-reach set-relay <url>` | Persist the Relay URL |
+| `/pi-reach` | Reconnect this Pi after `/pi-reach stop` |
+| `/pi-reach start` / `/pi-reach stop` | Connect or disconnect this Pi |
+| `/pi-reach status` | Show Relay, endpoint, runtime, and paired-browser state |
+| `/pi-reach pair` | Show a pairing QR code and pairing code for this Pi |
+| `/pi-reach devices` | List browsers paired with this computer |
+| `/pi-reach revoke <shortid>` | Revoke a browser's pairing on this computer |
+| `/pi-reach set-relay <url>` | Save the Relay URL |
 | `/pi-reach config` | Show the resolved Relay URL |
 
-The Extension handles remote `session_new` requests in-process through Pi's session API. There is no standalone `pi-reach` CLI, background process, scheduler, or service installation command.
-
 ## Relay configuration
 
-The effective Relay URL resolves in this order:
+Pi and the PWA must use the same Relay. The pairing QR code does not carry a Relay address.
+
+The Extension resolves its Relay URL in this order:
 
 1. `PI_REACH_RELAY`
 2. `~/.pi/pi-reach/config.json`
@@ -69,27 +80,30 @@ Set and inspect it from Pi:
 /pi-reach config
 ```
 
-Only `http://` and `https://` are accepted at the command boundary; WebSocket conversion happens inside the Extension. The Relay forwards opaque payloads and retains endpoint routing state in memory.
+In the PWA, set the same URL under **Settings → Connection → Relay URL**. Use `https://` for a deployed Relay; `http://` is accepted for local development. The Extension converts the URL to WebSocket form internally. The Relay retains routing state in memory and does not persist conversations.
+
+## Endpoint model and local state
+
+```text
+device -> endpoint -> runtime -> session / history generation
+```
+
+- **Device**: the computer's Ed25519 identity and the scope of pairing authorization.
+- **Endpoint and runtime**: generated randomly when a Pi process loads the Extension. They remain stable across Extension reloads in that process and are regenerated for the next Pi process. The endpoint is not derived from the working directory.
+- **Session / generation**: the active Pi conversation and its current history branch. Pi Reach does not list or resume historical Pi sessions.
 
-## Pairing and security
+Pairing QR codes target the current endpoint and runtime; the resulting browser authorization is stored at device scope. Owner messages are trusted only through the Relay-injected `source_owner_id`. Pairing and revocation update the Relay endpoint ACL with `authorized_owner_ids`.
 
-- There is no application-layer end-to-end encryption, so the Relay is fully trusted. Its operator can read every conversation and, because Owner identity comes only from the Relay-injected `source_owner_id`, could impersonate a paired browser and send prompts that Pi executes on your computer.
-- Report vulnerabilities privately through GitHub's [private vulnerability reporting](https://github.com/yefengr/pi-reach/security/advisories/new); see the [security policy](https://github.com/yefengr/pi-reach/blob/main/SECURITY.md).
-- `device_id` is the Host Ed25519 public key in canonical Base64 form.
-- Owner messages are trusted only through the Relay-injected `source_owner_id`.
-- Pairing and revocation update the Relay endpoint ACL with `authorized_owner_ids`.
-- Relay loss enters reconnecting state; the Extension does not restart Pi to recover.
-- Device private keys, pairing tokens, encrypted payloads, and message bodies are not logged.
-- Concurrent Pi processes coordinate device identity initialization through a local lock. If initialization is interrupted, follow the [identity storage and lock recovery rules](../docs/reference/protocol/pairing.md#host); do not delete identity or pairing data to retry.
+The Extension handles remote `session_new` requests in-process through Pi's session API. There is no standalone `pi-reach` CLI, background process, scheduler, or service installation command. Relay loss triggers reconnection, not a Pi restart.
 
-## Local state
+Pi Reach stores global configuration, identity files, and pairings under `~/.pi/pi-reach`, and project display configuration under `.pi/pi-reach`. Its platform keyring service is `dev.pireach.pi`. Device private keys, pairing tokens, and message bodies are not logged.
 
-Pi Reach stores global configuration, identity files, and pairings under `~/.pi/pi-reach`, and project display configuration under `.pi/pi-reach`. Its platform keyring service is `dev.pireach.pi`.
+Concurrent Pi processes coordinate device identity initialization through a local lock. If initialization is interrupted, follow the [identity storage and lock recovery rules](https://github.com/yefengr/pi-reach/blob/main/docs/reference/protocol/pairing.md#host); do not delete identity or pairing data to retry.
 
 ## Development
 
 Install dependencies from the repository root with `pnpm install --frozen-lockfile`.
-The root workspace owns dependency catalogs, build approvals, and the lockfile. The private workspace package [`@pi-reach/protocol`](../packages/protocol/) provides the shared protocol build artifacts; the Extension uses it as a development dependency, while installed users receive vendored artifacts and need neither the workspace nor a separately published shared package. Its module and distribution boundary is defined in [ARCHITECTURE](../docs/ARCHITECTURE.md#工程与构建边界).
+The root workspace owns dependency catalogs, build approvals, and the lockfile. The private workspace package [`@pi-reach/protocol`](https://github.com/yefengr/pi-reach/tree/main/packages/protocol) provides the shared protocol build artifacts; the Extension uses it as a development dependency, while installed users receive vendored artifacts and need neither the workspace nor a separately published shared package. Its module and distribution boundary is defined in [ARCHITECTURE](https://github.com/yefengr/pi-reach/blob/main/docs/ARCHITECTURE.md#工程与构建边界).
 
 The root `prepare` script and an Extension `pnpm build` build the shared package first. After changing shared sources, run `pnpm --filter @pi-reach/protocol build` from the repository root before an Extension-only `typecheck` or `test`, or use the corresponding root command.
 

package/dist/files/content-type.d.ts

@@ -0,0 +1,16 @@
+import type { FileHandle } from "node:fs/promises";
+import { type Dimensions } from "./image-structure.js";
+type Preview = ({
+    kind: "image";
+} & Dimensions) | {
+    kind: "text";
+} | {
+    kind: "none";
+};
+type Inspection = {
+    mimeType: string;
+    preview: Preview;
+};
+/** 有界头识别不是完整解码认证；HTML/SVG 与所有文本都只能由消费端转义显示。 */
+export declare function inspectFile(handle: FileHandle, byteLength: number, fileName: string): Promise<Inspection>;
+export {};

package/dist/files/content-type.js

@@ -0,0 +1,98 @@
+import { extname } from "node:path";
+import { FileAccessError } from "./safe-open.js";
+import { ImageStructureReader, MAX_INSPECTION_READS, staticGif, staticPng, staticWebp } from "./image-structure.js";
+const HEAD_MAX_BYTES = 256 * 1024;
+const MAX_IMAGE_PIXELS = 20_000_000;
+const NONE = { kind: "none" };
+function image(mimeType, dimensions) {
+    if (!dimensions || dimensions.width <= 0 || dimensions.height <= 0 || dimensions.width * dimensions.height > MAX_IMAGE_PIXELS) {
+        return { mimeType, preview: NONE };
+    }
+    return { mimeType, preview: { kind: "image", ...dimensions } };
+}
+function jpegDimensions(head) {
+    let offset = 2;
+    while (offset < head.length) {
+        if (head[offset++] !== 0xff)
+            return undefined;
+        while (head[offset] === 0xff)
+            offset++;
+        if (offset >= head.length)
+            return undefined;
+        const marker = head[offset++];
+        if (marker === 0xd9 || marker === 0xda || marker === 0x00 || marker === 0xd8)
+            return undefined;
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7))
+            continue;
+        if (offset + 2 > head.length)
+            return undefined;
+        const length = head.readUInt16BE(offset);
+        if (length < 2 || offset + length > head.length)
+            return undefined;
+        const sof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+        if (sof) {
+            if (length < 8)
+                return undefined;
+            const components = head[offset + 7];
+            if (components < 1 || components > 4 || length !== 8 + 3 * components || ![8, 12, 16].includes(head[offset + 2]))
+                return undefined;
+            return { width: head.readUInt16BE(offset + 5), height: head.readUInt16BE(offset + 3) };
+        }
+        offset += length;
+    }
+    return undefined;
+}
+function isText(head, truncated) {
+    for (const byte of head) {
+        if ((byte < 0x20 && ![9, 10, 13].includes(byte)) || byte === 0x7f)
+            return false;
+    }
+    try {
+        // 仅因头预算截断时允许末尾码点未完整；完整文件仍须 fatal 验证尾部。
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(head, { stream: truncated });
+        return !/[\u0080-\u009f]/u.test(text);
+    }
+    catch {
+        return false;
+    }
+}
+/** 有界头识别不是完整解码认证；HTML/SVG 与所有文本都只能由消费端转义显示。 */
+export async function inspectFile(handle, byteLength, fileName) {
+    if (!Number.isSafeInteger(byteLength) || byteLength < 0)
+        throw new FileAccessError("io_error");
+    const buffer = Buffer.alloc(Math.min(byteLength, HEAD_MAX_BYTES));
+    let offset = 0;
+    let reads = 0;
+    // 保留短 read 的续读语义；实读头字节受 buffer 限制，重试另受操作预算限制。
+    while (offset < buffer.length && reads < MAX_INSPECTION_READS) {
+        const requested = buffer.length - offset;
+        reads++;
+        const { bytesRead } = await handle.read(buffer, offset, requested, offset);
+        if (bytesRead === 0)
+            throw new FileAccessError("file_changed");
+        if (!Number.isInteger(bytesRead) || bytesRead < 0 || bytesRead > requested)
+            throw new FileAccessError("io_error");
+        offset += bytesRead;
+    }
+    const head = buffer.subarray(0, offset);
+    const completeHead = offset === buffer.length;
+    const reader = new ImageStructureReader(handle, head, byteLength, reads);
+    if (head.length >= 8 && head.toString("hex", 0, 8) === "89504e470d0a1a0a")
+        return image("image/png", completeHead ? await staticPng(reader) : undefined);
+    if (head.length >= 3 && head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)
+        return image("image/jpeg", completeHead ? jpegDimensions(head) : undefined);
+    if (head.length >= 6 && ["GIF87a", "GIF89a"].includes(head.toString("latin1", 0, 6)))
+        return image("image/gif", completeHead ? staticGif(head, byteLength) : undefined);
+    if (head.length >= 12 && head.toString("latin1", 0, 4) === "RIFF" && head.toString("latin1", 8, 12) === "WEBP") {
+        return image("image/webp", completeHead ? await staticWebp(reader) : undefined);
+    }
+    if (head.length >= 5 && head.toString("latin1", 0, 5) === "%PDF-")
+        return { mimeType: "application/pdf", preview: NONE };
+    if (head.length >= 4 && ["504b0304", "504b0506", "504b0708"].includes(head.toString("hex", 0, 4)))
+        return { mimeType: "application/zip", preview: NONE };
+    if (!completeHead || !isText(head, byteLength > head.length))
+        return { mimeType: "application/octet-stream", preview: NONE };
+    const markdown = [".md", ".markdown"].includes(extname(fileName).toLowerCase());
+    return { mimeType: markdown ? "text/markdown" : "text/plain", preview: { kind: "text" } };
+}
+//# sourceMappingURL=content-type.js.map

package/dist/files/content-type.js.map

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

package/dist/files/image-structure.d.ts

@@ -0,0 +1,21 @@
+import type { FileHandle } from "node:fs/promises";
+export type Dimensions = {
+    width: number;
+    height: number;
+};
+export declare const MAX_INSPECTION_READS = 4096;
+/** 只读取结构元数据；压缩数据按长度跳过，不认证像素内容或 CRC。 */
+export declare class ImageStructureReader {
+    private readonly handle;
+    readonly head: Buffer;
+    readonly byteLength: number;
+    private reads;
+    private steps;
+    private metadataBytes;
+    constructor(handle: FileHandle, head: Buffer, byteLength: number, reads: number);
+    step(): boolean;
+    get(position: number, length: number): Promise<Buffer | undefined>;
+}
+export declare function staticPng(reader: ImageStructureReader): Promise<Dimensions | undefined>;
+export declare function staticWebp(reader: ImageStructureReader): Promise<Dimensions | undefined>;
+export declare function staticGif(head: Buffer, byteLength: number): Dimensions | undefined;

package/dist/files/image-structure.js

@@ -0,0 +1,269 @@
+import { FileAccessError } from "./safe-open.js";
+export const MAX_INSPECTION_READS = 4096;
+const MAX_STRUCTURE_STEPS = 4096;
+const MAX_METADATA_BYTES = 64 * 1024;
+const PNG_ANCILLARY = new Set(["cHRM", "gAMA", "iCCP", "sBIT", "sRGB", "bKGD", "hIST", "tRNS", "pHYs", "sPLT", "tIME", "iTXt", "tEXt", "zTXt", "eXIf", "cICP", "mDCV", "cLLI"]);
+/** 只读取结构元数据；压缩数据按长度跳过，不认证像素内容或 CRC。 */
+export class ImageStructureReader {
+    handle;
+    head;
+    byteLength;
+    reads;
+    steps = 0;
+    metadataBytes = 0;
+    constructor(handle, head, byteLength, reads) {
+        this.handle = handle;
+        this.head = head;
+        this.byteLength = byteLength;
+        this.reads = reads;
+    }
+    step() { return ++this.steps <= MAX_STRUCTURE_STEPS; }
+    async get(position, length) {
+        if (!Number.isSafeInteger(position) || position < 0 || length < 0 || position + length > this.byteLength)
+            return undefined;
+        if (position + length <= this.head.length)
+            return this.head.subarray(position, position + length);
+        const buffer = Buffer.alloc(length);
+        let offset = Math.max(0, Math.min(length, this.head.length - position));
+        if (offset)
+            this.head.copy(buffer, 0, position, position + offset);
+        while (offset < length) {
+            const requested = length - offset;
+            // 按请求字节计费，短 read 也不能反复请求而突破 metadata I/O 预算。
+            if (this.reads >= MAX_INSPECTION_READS || this.metadataBytes + requested > MAX_METADATA_BYTES)
+                return undefined;
+            this.reads++;
+            this.metadataBytes += requested;
+            const { bytesRead } = await this.handle.read(buffer, offset, requested, position + offset);
+            if (bytesRead === 0)
+                throw new FileAccessError("file_changed");
+            if (!Number.isInteger(bytesRead) || bytesRead < 0 || bytesRead > requested)
+                throw new FileAccessError("io_error");
+            offset += bytesRead;
+        }
+        return buffer;
+    }
+}
+function pngHeader(head) {
+    if (head.length < 33 || head.readUInt32BE(8) !== 13 || head.toString("latin1", 12, 16) !== "IHDR")
+        return undefined;
+    const depths = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+    if (!depths[head[25]]?.includes(head[24]) || head[26] !== 0 || head[27] !== 0 || head[28] > 1)
+        return undefined;
+    const width = head.readUInt32BE(16);
+    const height = head.readUInt32BE(20);
+    if (width === 0 || height === 0 || width > 0x7fffffff || height > 0x7fffffff)
+        return undefined;
+    return { width, height };
+}
+export async function staticPng(reader) {
+    const dimensions = pngHeader(reader.head);
+    if (!dimensions)
+        return undefined;
+    let position = 33;
+    let dataSeen = false;
+    let dataStarted = false;
+    let dataEnded = false;
+    let paletteSeen = false;
+    while (position < reader.byteLength && reader.step()) {
+        const header = await reader.get(position, 8);
+        if (!header)
+            return undefined;
+        const length = header.readUInt32BE(0);
+        const type = header.toString("latin1", 4, 8);
+        const end = position + 12 + length;
+        if (length > 0x7fffffff || end > reader.byteLength)
+            return undefined;
+        // 动画声明在任何位置都不能放行；IEND 后也不得保留浏览器可解释的尾部。
+        if (["acTL", "fcTL", "fdAT"].includes(type))
+            return undefined;
+        if (type === "IEND") {
+            if (length !== 0 || !dataSeen || end !== reader.byteLength)
+                return undefined;
+            return await reader.get(position + 8, 4) ? dimensions : undefined;
+        }
+        if (type === "IDAT") {
+            if (dataEnded || (reader.head[25] === 3 && !paletteSeen))
+                return undefined;
+            dataStarted = true;
+            if (length > 0)
+                dataSeen = true;
+        }
+        else {
+            if (dataStarted)
+                dataEnded = true;
+            if (type === "PLTE") {
+                if (paletteSeen || dataStarted || !length || length > 768 || length % 3 || [0, 4].includes(reader.head[25]))
+                    return undefined;
+                paletteSeen = true;
+            }
+            else if (!PNG_ANCILLARY.has(type))
+                return undefined;
+        }
+        // 中间 payload/checksum 按长度跳过，最终 IEND checksum 稀疏读确认 EOF。
+        position = end;
+    }
+    return undefined;
+}
+function webpPayload(type, data) {
+    if (type === "VP8 ") {
+        if (data.length < 10 || data[0] & 1 || data.toString("hex", 3, 6) !== "9d012a")
+            return undefined;
+        return { width: data.readUInt16LE(6) & 0x3fff, height: data.readUInt16LE(8) & 0x3fff };
+    }
+    if (data.length < 5 || data[0] !== 0x2f)
+        return undefined;
+    const bits = data.readUInt32LE(1);
+    if (bits >>> 29 !== 0)
+        return undefined;
+    return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+}
+export async function staticWebp(reader) {
+    if (reader.head.readUInt32LE(4) + 8 !== reader.byteLength)
+        return undefined;
+    let position = 12;
+    let canvas;
+    let dimensions;
+    let flags = 0;
+    let imageType;
+    const seen = new Set();
+    let losslessAlpha = false;
+    while (position < reader.byteLength && reader.step()) {
+        const header = await reader.get(position, 8);
+        if (!header)
+            return undefined;
+        const type = header.toString("latin1", 0, 4);
+        const length = header.readUInt32LE(4);
+        const start = position + 8;
+        const end = start + length + (length & 1);
+        if (end > reader.byteLength || seen.has(type) || type === "ANIM" || type === "ANMF")
+            return undefined;
+        seen.add(type);
+        if (type === "VP8X") {
+            const data = length === 10 && position === 12 ? await reader.get(start, 10) : undefined;
+            if (!data || data[0] & 0xc3 || data[1] || data[2] || data[3])
+                return undefined;
+            flags = data[0];
+            canvas = { width: data.readUIntLE(4, 3) + 1, height: data.readUIntLE(7, 3) + 1 };
+        }
+        else if (type === "VP8 " || type === "VP8L") {
+            if (dimensions || (seen.has("ALPH") && type !== "VP8 "))
+                return undefined;
+            const required = type === "VP8 " ? 10 : 5;
+            const data = length >= required ? await reader.get(start, required) : undefined;
+            if (!data)
+                return undefined;
+            dimensions = webpPayload(type, data);
+            if (!dimensions || !dimensions.width || !dimensions.height)
+                return undefined;
+            imageType = type;
+            losslessAlpha = type === "VP8L" && !!(data[4] & 0x10);
+            if (canvas && (canvas.width !== dimensions.width || canvas.height !== dimensions.height))
+                return undefined;
+        }
+        else if (type === "ICCP" || type === "ALPH" || type === "EXIF" || type === "XMP ") {
+            if (!canvas || !length)
+                return undefined;
+            if ((type === "ICCP" || type === "ALPH") && dimensions)
+                return undefined;
+            if ((type === "EXIF" || type === "XMP ") && !dimensions)
+                return undefined;
+            if (type === "ALPH") {
+                const data = await reader.get(start, 1);
+                if (!data || data[0] & 0xc0 || (data[0] & 3) > 1 || ((data[0] >> 4) & 3) > 1)
+                    return undefined;
+            }
+        }
+        else
+            return undefined;
+        if (length & 1) {
+            const padding = await reader.get(end - 1, 1);
+            if (!padding || padding[0] !== 0)
+                return undefined;
+        }
+        position = end;
+    }
+    if (position !== reader.byteLength || !dimensions)
+        return undefined;
+    if (canvas && (Boolean(flags & 0x20) !== seen.has("ICCP") || Boolean(flags & 0x08) !== seen.has("EXIF")
+        || Boolean(flags & 0x04) !== seen.has("XMP ") || Boolean(flags & 0x10) !== (seen.has("ALPH") || losslessAlpha)))
+        return undefined;
+    if (!canvas && (seen.size !== 1 || (imageType !== "VP8 " && imageType !== "VP8L")))
+        return undefined;
+    // 即使最后一个压缩 payload 没有 padding，也确认声明的文件末字节存在。
+    return await reader.get(reader.byteLength - 1, 1) ? dimensions : undefined;
+}
+export function staticGif(head, byteLength) {
+    // GIF 的压缩块不能稀疏跳过证明帧数；超过已有头预算时仅提供下载。
+    if (head.length !== byteLength || head.length < 13)
+        return undefined;
+    const dimensions = { width: head.readUInt16LE(6), height: head.readUInt16LE(8) };
+    if (!dimensions.width || !dimensions.height)
+        return undefined;
+    const globalTable = !!(head[10] & 0x80);
+    let position = 13 + (globalTable ? 3 * 2 ** ((head[10] & 7) + 1) : 0);
+    let steps = 0;
+    let frames = 0;
+    let controlPending = false;
+    const step = () => ++steps <= MAX_STRUCTURE_STEPS;
+    const subblocks = (requireData) => {
+        let dataSeen = false;
+        while (position < head.length && step()) {
+            const length = head[position++];
+            if (!length)
+                return !requireData || dataSeen;
+            dataSeen = true;
+            position += length;
+            if (position > head.length)
+                return false;
+        }
+        return false;
+    };
+    while (position < head.length && step()) {
+        const type = head[position++];
+        if (type === 0x3b)
+            return frames === 1 && !controlPending && position === head.length ? dimensions : undefined;
+        if (type === 0x21) {
+            const label = head[position++];
+            if (label === 0xf9) {
+                if (controlPending || position + 6 > head.length || head[position] !== 4 || head[position + 5] !== 0)
+                    return undefined;
+                const packed = head[position + 1];
+                if (packed & 0xe0 || ((packed >> 2) & 7) > 3)
+                    return undefined;
+                controlPending = true;
+                position += 6;
+            }
+            else if (label === 0xfe) {
+                if (!subblocks(false))
+                    return undefined;
+            }
+            else {
+                // Plain Text 可产生额外渲染；应用扩展语义未知，不能证明静态。
+                return undefined;
+            }
+            continue;
+        }
+        if (type !== 0x2c || ++frames !== 1 || position + 9 > head.length)
+            return undefined;
+        const left = head.readUInt16LE(position);
+        const top = head.readUInt16LE(position + 2);
+        const width = head.readUInt16LE(position + 4);
+        const height = head.readUInt16LE(position + 6);
+        const packed = head[position + 8];
+        if (!width || !height || left + width > dimensions.width || top + height > dimensions.height || packed & 0x18)
+            return undefined;
+        const localTable = !!(packed & 0x80);
+        if (!globalTable && !localTable)
+            return undefined;
+        position += 9 + (localTable ? 3 * 2 ** ((packed & 7) + 1) : 0);
+        if (position >= head.length || head[position] < 2 || head[position] > 8)
+            return undefined;
+        position++;
+        if (!subblocks(true))
+            return undefined;
+        controlPending = false;
+    }
+    return undefined;
+}
+//# sourceMappingURL=image-structure.js.map

package/dist/files/image-structure.js.map

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

package/dist/files/publications.d.ts

@@ -0,0 +1,26 @@
+import { type SessionManager } from "@earendil-works/pi-coding-agent";
+import { type PublishedFileMetadata } from "../vendor/protocol/session/index.js";
+import { z } from "zod";
+export declare const PUBLISHED_FILE_TOOL_NAME: "publish_file";
+export type ConfirmedPublication = {
+    id: string;
+    sourcePath: string;
+    metadata: PublishedFileMetadata;
+    groupId?: string;
+    timestamp: number;
+    branchPosition: number;
+};
+/** 只存于原生 custom；不能把此 schema 当作 wire payload。 */
+export declare const publicationDataSchema: z.ZodObject<{
+    file_name: z.ZodString;
+    mime_type: z.ZodString;
+    byte_length: z.ZodNumber;
+    tool_call_id: z.ZodString;
+    source_path: z.ZodString;
+    group_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 原生成功 toolResult 是确认点，且 custom/result 两者均须已落盘。
+ * 失败 append 留下的内部孤立记录无资格；不尝试回滚 SDK 的 append-only 树。
+ */
+export declare function collectPublications(manager: SessionManager): Map<string, ConfirmedPublication>;