@comput/pi-intercom 0.3.0 → 0.4.2

package/dist/reports.js

@@ -0,0 +1,160 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+const MAX_BYTES = 8 * 1024;
+const MAX_IDS = 256;
+const statuses = new Set(['blocked', 'needs_decision', 'ready_for_review', 'clear']);
+const controls = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/;
+function validId(id) {
+    return typeof id === 'string' && id.length > 0 && id.length <= 256 && id.trim().length > 0 && !/[\x00-\x1f\x7f-\x9f]/.test(id);
+}
+function validate(value) {
+    if (!value || typeof value !== 'object')
+        return;
+    const v = value;
+    if (v.version !== 1 || !validId(v.sessionId) || !statuses.has(v.status))
+        return;
+    if (typeof v.summary !== 'string' || v.summary.length > 2000 || controls.test(v.summary))
+        return;
+    if (v.status === 'clear' ? v.summary !== '' : !v.summary.trim())
+        return;
+    if (typeof v.updatedAt !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v.updatedAt))
+        return;
+    const timestamp = Date.parse(v.updatedAt);
+    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== v.updatedAt)
+        return;
+    return { version: 1, sessionId: v.sessionId, status: v.status, summary: v.summary, updatedAt: v.updatedAt };
+}
+function filename(id) {
+    return `${createHash('sha256').update(id).digest('hex')}.json`;
+}
+/** Reject links at the root and both extension-owned directory components. */
+async function directory(root, create, assertCurrent) {
+    if ((await lstat(root)).isSymbolicLink())
+        throw new Error('unsafe root');
+    let current = await realpath(root);
+    for (const segment of ['.pi-intercom', 'reports']) {
+        current = path.join(current, segment);
+        if (create) {
+            assertCurrent?.();
+            try {
+                await mkdir(current, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+        }
+        const info = await lstat(current);
+        if (!info.isDirectory() || info.isSymbolicLink() || path.relative(current, await realpath(current)) !== '')
+            throw new Error('unsafe directory');
+    }
+    return current;
+}
+async function regularOrAbsent(file) {
+    try {
+        const info = await lstat(file);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error('unsafe file');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+/** Persist only the explicitly authored public report; clear is an atomic tombstone. */
+export async function saveWorkerReport(root, report, assertCurrent) {
+    let temporary;
+    let ownsTemporary = false;
+    let dir;
+    try {
+        const safe = validate(report);
+        if (!safe)
+            throw new Error('invalid report');
+        const content = JSON.stringify(safe) + '\n';
+        if (Buffer.byteLength(content) > MAX_BYTES)
+            throw new Error('oversized report');
+        assertCurrent?.();
+        dir = await directory(root, true, assertCurrent);
+        const target = path.join(dir, filename(safe.sessionId));
+        await regularOrAbsent(target);
+        temporary = path.join(dir, `.${filename(safe.sessionId)}.${randomUUID()}.tmp`);
+        assertCurrent?.();
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+        ownsTemporary = true;
+        try {
+            assertCurrent?.();
+            await handle.writeFile(content, 'utf8');
+        }
+        finally {
+            await handle.close();
+        }
+        if (await directory(root, false) !== dir)
+            throw new Error('directory changed');
+        await regularOrAbsent(target);
+        assertCurrent?.();
+        await rename(temporary, target);
+        temporary = undefined;
+    }
+    catch {
+        throw new Error('Worker report could not be saved.');
+    }
+    finally {
+        if (temporary && ownsTemporary && dir) {
+            // Cleanup only our own unpublished temporary file, even if authorization expired.
+            try {
+                if (await directory(root, false) === dir)
+                    await unlink(temporary);
+            }
+            catch { /* No raw filesystem errors or unsafe cleanup. */ }
+        }
+    }
+}
+/** Read at most 256 configured IDs; no directory scan, repair, transport, or host access. */
+export async function readWorkerReports(root, sessionIds) {
+    const reports = [];
+    let dir;
+    try {
+        dir = await directory(root, false);
+    }
+    catch {
+        return reports;
+    }
+    const seen = new Set();
+    for (const id of sessionIds.slice(0, MAX_IDS)) {
+        if (!validId(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        try {
+            if (await directory(root, false) !== dir)
+                break;
+            const file = path.join(dir, filename(id));
+            const info = await lstat(file);
+            if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_BYTES)
+                continue;
+            const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+            let text;
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size > MAX_BYTES)
+                    continue;
+                // One extra byte detects concurrent growth, while keeping reads bounded.
+                const buffer = Buffer.alloc(MAX_BYTES + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > MAX_BYTES)
+                    continue;
+                text = buffer.subarray(0, bytesRead).toString('utf8');
+            }
+            finally {
+                await handle.close();
+            }
+            const report = validate(JSON.parse(text));
+            if (report?.sessionId === id)
+                reports.push(report);
+        }
+        catch { /* Missing, unsafe, malformed or concurrently replaced evidence is unavailable. */ }
+    }
+    return reports;
+}
+//# sourceMappingURL=reports.js.map

package/dist/reports.js.map

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

package/dist/runtime.d.ts

@@ -0,0 +1,59 @@
+import { type Observer, type EventType, type EventMetadata } from './observability.js';
+import { ConfigStore, type Agent, type Config } from './config.js';
+import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.js';
+export declare const UNSUPPORTED_CANCELLATION = "Unsupported Pi host: stop_worker and close_worker are disabled. Pi 0.84.4 extension abort does not cancel retry backoff/continuations; graceful shutdown cannot guarantee no queued work restarts. No cancellation or shutdown was performed. See references/implementation-blocker.md. A verified supported host API is required (no version-only override).";
+export interface Host {
+    sessionId(): string;
+    cwd: string;
+    busy(): boolean;
+    deliver(text: string, busy: boolean): void;
+    setName(name: string): Promise<void>;
+    notify(text: string): void;
+}
+export interface LaunchRequest {
+    multiplexer: 'herdr' | 'none';
+    cwd: string;
+    sessionId?: string;
+}
+export interface RuntimeOptions {
+    launch(request: LaunchRequest): Promise<unknown>;
+    listen?: typeof listen;
+    send?: typeof send;
+    store?: (root: string) => ConfigStore;
+    observe?: (root: string, sessionId: string) => Observer;
+}
+export declare class Intercom {
+    readonly host: Host;
+    readonly options: RuntimeOptions;
+    store: ConfigStore;
+    endpoint?: Endpoint;
+    private active;
+    private generation;
+    private initialId;
+    responsibility?: Agent;
+    private observer?;
+    private closing?;
+    private reportWrites;
+    private pendingReports;
+    private captureObserver;
+    recordObservation(event: EventType, metadata?: EventMetadata): void;
+    constructor(host: Host, options: RuntimeOptions);
+    private id;
+    private validity;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    state(): Promise<{
+        id: string;
+        config: Config;
+        me?: Agent;
+    }>;
+    /** Accept old configs, but retire the removed browser dashboard's discovery metadata. */
+    retireDashboardMetadata(): Promise<void>;
+    reload(): Promise<void>;
+    transmit(to: string, kind: Kind, payload?: Record<string, unknown>): Promise<void>;
+    report(): Promise<void>;
+    receive(message: Envelope): Promise<void>;
+    private handleReceive;
+    tool(operation: string, args: Record<string, unknown>): Promise<unknown>;
+    private launchObserved;
+}