@comput/pi-intercom 0.5.2 → 0.8.1

package/dist/pane-close.js

@@ -0,0 +1,166 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { constants } from 'node:fs';
+import { open, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+const rejected = () => new Error('PiIntercom: worker pane identity could not be verified; no close submitted.');
+const exec = async (file, args) => (await promisify(execFile)(file, args, {
+    windowsHide: true, timeout: 4000, maxBuffer: 1024 * 1024,
+})).stdout;
+/** Linux process start ticks distinguish a reused PID from the original worker. */
+export async function linuxProcessIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw rejected();
+    let stat;
+    try {
+        stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw rejected();
+    }
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/);
+    if (!/^[0-9]+$/.test(fields[19] ?? '') || !/^[A-Za-z]$/.test(fields[0] ?? ''))
+        throw rejected();
+    return { start: fields[19], state: fields[0] };
+}
+async function verifySessionHeader(file, id) {
+    if (!path.isAbsolute(file) || file.length > 4096 || file.includes('\0'))
+        throw rejected();
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            throw rejected();
+        // Inspect only the first session-header line, never transcript messages.
+        const buffer = Buffer.alloc(4096);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const end = buffer.subarray(0, bytesRead).indexOf(10);
+        if (end < 0)
+            throw rejected();
+        const header = JSON.parse(buffer.subarray(0, end).toString('utf8'));
+        if (header?.type !== 'session' || header.id !== id)
+            throw rejected();
+    }
+    finally {
+        await handle.close();
+    }
+}
+const alive = (identity, start) => !!identity && identity.start === start && !['Z', 'X', 'x'].includes(identity.state);
+/** Linux Herdr only. Identity-checked best effort; Herdr has no atomic compare-and-close API. */
+export function createCloseProvider(options) {
+    const env = options.env ?? process.env;
+    if ((options.platform ?? process.platform) !== 'linux' || env.HERDR_ENV !== '1' || !env.HERDR_PANE_ID)
+        return;
+    const run = options.run ?? exec;
+    const processIdentity = options.processIdentity ?? linuxProcessIdentity;
+    const verifySession = options.verifySession ?? verifySessionHeader;
+    const ownPid = options.pid ?? process.pid;
+    const verificationMs = Math.max(0, Math.min(2000, options.verificationMs ?? 1500));
+    async function query(args) {
+        const output = await run('herdr', args);
+        if (Buffer.byteLength(output) > 1024 * 1024)
+            throw rejected();
+        return JSON.parse(output)?.result;
+    }
+    async function caller() {
+        const pane = (await query(['pane', 'current', '--current']))?.pane;
+        if (!pane || typeof pane.pane_id !== 'string' || typeof pane.workspace_id !== 'string' || typeof pane.terminal_id !== 'string')
+            throw rejected();
+        return pane;
+    }
+    async function verifyPane(pane, identity) {
+        if (!pane || pane.pane_id !== identity.paneId || pane.workspace_id !== identity.workspaceId ||
+            pane.terminal_id !== identity.terminalId || pane.agent !== 'pi' ||
+            pane.agent_session?.source !== 'herdr:pi' || pane.agent_session?.kind !== 'path' ||
+            typeof pane.agent_session.value !== 'string' || !path.isAbsolute(identity.sessionFile) ||
+            !Number.isSafeInteger(identity.pid) || identity.pid <= 0 || !/^[0-9]+$/.test(identity.processStart))
+            throw rejected();
+        if (await realpath(pane.agent_session.value) !== await realpath(identity.sessionFile))
+            throw rejected();
+        await verifySession(identity.sessionFile, identity.sessionId);
+        const info = (await query(['pane', 'process-info', '--pane', identity.paneId]))?.process_info;
+        if (info?.pane_id !== identity.paneId || !Array.isArray(info.foreground_processes) ||
+            !info.foreground_processes.some((p) => p.pid === identity.pid) ||
+            !alive(await processIdentity(identity.pid), identity.processStart))
+            throw rejected();
+    }
+    async function inspect(identity, expectedSessionId, assertCurrent) {
+        assertCurrent();
+        if (identity.sessionId !== expectedSessionId || expectedSessionId === options.sessionId() || identity.pid === ownPid)
+            throw rejected();
+        const own = await caller();
+        assertCurrent();
+        if (own.pane_id === identity.paneId || own.workspace_id !== identity.workspaceId)
+            throw rejected();
+        await verifyPane((await query(['pane', 'get', identity.paneId]))?.pane, identity);
+        assertCurrent();
+    }
+    return {
+        async getIdentity() {
+            try {
+                const sessionId = options.sessionId(), sessionFile = options.sessionFile();
+                if (!sessionFile)
+                    throw rejected();
+                const pane = await caller();
+                const process = await processIdentity(ownPid);
+                if (!process || !alive(process, process.start))
+                    throw rejected();
+                const identity = { workspaceId: pane.workspace_id, paneId: pane.pane_id,
+                    terminalId: pane.terminal_id, sessionId, sessionFile, pid: ownPid, processStart: process.start };
+                await verifyPane(pane, identity);
+                if (options.sessionId() !== sessionId || options.sessionFile() !== sessionFile)
+                    throw rejected();
+                return identity;
+            }
+            catch {
+                throw rejected();
+            }
+        },
+        async inspect(identity, expectedSessionId, assertCurrent) {
+            try {
+                await inspect(identity, expectedSessionId, assertCurrent);
+            }
+            catch {
+                throw rejected();
+            }
+        },
+        async close(identity, expectedSessionId, assertCurrent, beforeSubmit) {
+            try {
+                await inspect(identity, expectedSessionId, assertCurrent);
+            }
+            catch {
+                throw rejected();
+            }
+            assertCurrent();
+            // Revalidate worker settlement only AFTER potentially slow ownership reads.
+            // Herdr still has no atomic cross-process identity/idle compare-and-close.
+            await beforeSubmit();
+            assertCurrent();
+            // Exactly one explicit pane target. No tab/workspace close, retry, or force kill.
+            // A CLI timeout can mean the mutation happened: caller must persist uncertainty.
+            try {
+                await run('herdr', ['pane', 'close', identity.paneId]);
+            }
+            catch {
+                throw new Error('PiIntercom: pane close outcome uncertain; inspect before any retry.');
+            }
+            let paneClosed = false, workerExited = false;
+            try {
+                const panes = (await query(['pane', 'list', '--workspace', identity.workspaceId]))?.panes;
+                paneClosed = Array.isArray(panes) && panes.every(p => typeof p?.pane_id === 'string') &&
+                    !panes.some(p => p.pane_id === identity.paneId);
+                const deadline = Date.now() + verificationMs;
+                do {
+                    workerExited = !alive(await processIdentity(identity.pid), identity.processStart);
+                    if (workerExited || Date.now() >= deadline)
+                        break;
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                } while (true);
+            }
+            catch { /* Verification failure is uncertainty, never an automatic retry. */ }
+            return { paneClosed, workerExited };
+        },
+    };
+}
+//# sourceMappingURL=pane-close.js.map

package/dist/pane-close.js.map

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

package/dist/reminders.d.ts

@@ -0,0 +1,28 @@
+export declare const REMINDER_INTERVAL_MS: number;
+export declare const REMINDER_TEXT = "Intercom reminder: Review outstanding delegated work and worker reports. If follow-up is needed, take the next appropriate action. Do not assume workers have finished or stopped.\n\nIf there is genuinely nothing to follow up on, call intercom_stop_reminders. Otherwise, reminders continue every five minutes; a new worker call resets the timer.\n\nThis reminder does not authorize new work, retries, worker closure, or publication.";
+export interface ReminderClock {
+    schedule(callback: () => void, milliseconds: number): () => void;
+}
+interface ReminderHost {
+    isCoordinator(): Promise<boolean>;
+    busy(): boolean;
+    deliver(text: string): void;
+}
+/** Ephemeral reminder only: never worker actions, network retries or a backlog. */
+export declare class CoordinatorReminders {
+    private readonly host;
+    private readonly timer;
+    private generation;
+    private tick;
+    private checking;
+    private disposed;
+    private cancel?;
+    private detachOwner?;
+    constructor(host: ReminderHost, timer?: ReminderClock);
+    arm(signal?: AbortSignal): void;
+    stop(): void;
+    dispose(): void;
+    private current;
+    private schedule;
+}
+export {};

package/dist/reminders.js

@@ -0,0 +1,81 @@
+export const REMINDER_INTERVAL_MS = 5 * 60 * 1000;
+export const REMINDER_TEXT = 'Intercom reminder: Review outstanding delegated work and worker reports. If follow-up is needed, take the next appropriate action. Do not assume workers have finished or stopped.\n\nIf there is genuinely nothing to follow up on, call intercom_stop_reminders. Otherwise, reminders continue every five minutes; a new worker call resets the timer.\n\nThis reminder does not authorize new work, retries, worker closure, or publication.';
+const clock = {
+    schedule(callback, milliseconds) {
+        const timer = setTimeout(callback, milliseconds);
+        timer.unref();
+        return () => clearTimeout(timer);
+    },
+};
+/** Ephemeral reminder only: never worker actions, network retries or a backlog. */
+export class CoordinatorReminders {
+    host;
+    timer;
+    generation = 0;
+    tick = 0;
+    checking = false;
+    disposed = false;
+    cancel;
+    detachOwner;
+    constructor(host, timer = clock) {
+        this.host = host;
+        this.timer = timer;
+    }
+    arm(signal) {
+        if (this.disposed || signal?.aborted)
+            return;
+        this.stop();
+        const generation = this.generation;
+        if (signal) {
+            const abort = () => { if (this.generation === generation)
+                this.stop(); };
+            signal.addEventListener('abort', abort, { once: true });
+            this.detachOwner = () => signal.removeEventListener('abort', abort);
+        }
+        this.schedule(generation);
+    }
+    stop() {
+        this.generation++;
+        this.tick++;
+        this.cancel?.();
+        this.cancel = undefined;
+        this.detachOwner?.();
+        this.detachOwner = undefined;
+    }
+    dispose() { this.stop(); this.disposed = true; }
+    current(generation, tick) {
+        return !this.disposed && this.generation === generation && this.tick === tick;
+    }
+    schedule(generation) {
+        this.cancel = this.timer.schedule(() => {
+            if (this.disposed || generation !== this.generation)
+                return;
+            this.cancel = undefined;
+            const tick = ++this.tick;
+            this.schedule(generation);
+            // A slow role read never creates concurrent reads or a queued reminder.
+            // Advancing tick also invalidates any read from the preceding interval.
+            if (this.checking)
+                return;
+            this.checking = true;
+            void (async () => {
+                try {
+                    const coordinator = await this.host.isCoordinator();
+                    if (!this.current(generation, tick))
+                        return;
+                    if (!coordinator) {
+                        this.stop();
+                        return;
+                    }
+                    if (!this.host.busy())
+                        this.host.deliver(REMINDER_TEXT);
+                }
+                catch { /* Unknown role/read/delivery outcome: no blind immediate replay. */ }
+                finally {
+                    this.checking = false;
+                }
+            })();
+        }, REMINDER_INTERVAL_MS);
+    }
+}
+//# sourceMappingURL=reminders.js.map

package/dist/reminders.js.map

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

package/dist/runtime.d.ts

@@ -2,7 +2,9 @@ import { type Observer, type EventType, type EventMetadata } from './observabili
 import { ConfigStore, type Agent, type Config } from './config.js';
 import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.js';
 import { probeWorker } from './connections.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).";
+import { type CloseProvider } from './handoff.js';
+import { type ReminderClock } from './reminders.js';
+export declare const UNSUPPORTED_CANCELLATION = "Unsupported Pi host: stop_worker and legacy graceful-close control 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. close_worker uses a separate supported-provider owned-pane closure contract, not graceful cancellation. See references/implementation-blocker.md. A verified supported host API is required for graceful cancellation (no version-only override).";
 export interface Host {
     sessionId(): string;
     cwd: string;
@@ -14,6 +16,7 @@ export interface Host {
 export interface LaunchRequest {
     multiplexer: 'herdr' | 'none';
     cwd: string;
+    workspaceRoot: string;
     sessionId?: string;
 }
 export interface RuntimeOptions {
@@ -23,6 +26,12 @@ export interface RuntimeOptions {
     probe?: typeof probeWorker;
     store?: (root: string) => ConfigStore;
     observe?: (root: string, sessionId: string) => Observer;
+    closeProvider?: CloseProvider;
+    /** Test seam; production defaults to 120 seconds, values above that are capped. */
+    closeTimeoutMs?: number;
+    reminderClock?: ReminderClock;
+    /** Explicit launcher-provided root must equal canonical cwd; no parent-root exception. */
+    workspaceRoot?: string;
 }
 export declare class Intercom {
     readonly host: Host;
@@ -32,6 +41,8 @@ export declare class Intercom {
     private active;
     private generation;
     private initialId;
+    private configuredRoot?;
+    private configuredFile?;
     responsibility?: Agent;
     private observer?;
     private closing?;
@@ -39,6 +50,12 @@ export declare class Intercom {
     private pendingReports;
     private probeController;
     private resumeFences;
+    private handoff?;
+    private reminders?;
+    private reminderRevision;
+    private reminderInvocation;
+    workerStarted(): void;
+    workerSettled(successfulToolCallIds: ReadonlySet<string>): void;
     private captureObserver;
     recordObservation(event: EventType, metadata?: EventMetadata): void;
     constructor(host: Host, options: RuntimeOptions);
@@ -58,6 +75,6 @@ export declare class Intercom {
     report(): Promise<void>;
     receive(message: Envelope): Promise<void>;
     private handleReceive;
-    tool(operation: string, args: Record<string, unknown>): Promise<unknown>;
+    tool(operation: string, args: Record<string, unknown>, toolCallId?: string, reminderSignal?: AbortSignal): Promise<unknown>;
     private launchObserved;
 }