@abot-ai/runtime 1.6.0 → 1.8.0

package/dist/src/computer-access/command-output-capture.js

@@ -0,0 +1,202 @@
+import { createHash, randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { createWriteStream } from "node:fs";
+import { mkdir, open, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { finished } from "node:stream/promises";
+import { SystemOperationError } from "./contracts.js";
+import { CapturedOutputProtectionError, discardCapturedOutput, protectCapturedOutput } from "./command-output-protection.js";
+import { activeSystemCaptures, scheduleSystemOutputCleanup } from "./command-output-retention.js";
+const STREAMS = ["stdout", "stderr"];
+const OUTPUT_IO_CHUNK_BYTES = 64 * 1024;
+/** Private backpressured capture. No read is admitted before complete checks. */
+export async function createSystemOutputCapture(root, retentionMs, redact) {
+    if (!hasOutputProtection(redact))
+        throw new SystemOperationError("system_output_protection_failed", "Command output protection is unavailable. The command was not dispatched.");
+    const id = randomUUID();
+    const directory = join(root, id);
+    activeSystemCaptures.add(directory);
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        activeSystemCaptures.delete(directory);
+        throw new SystemOperationError("system_output_storage_failed", "Output storage could not be prepared. The command was not dispatched.");
+    }
+    let storageFailure, securityFailure;
+    let stop;
+    let ended = false, retained = false, admitted = false;
+    let receipt;
+    let processResult;
+    let finishing;
+    const sources = [];
+    const completeStreams = new Set();
+    const paths = { stdout: join(directory, "stdout.bytes"), stderr: join(directory, "stderr.bytes") };
+    const streams = STREAMS.map((name) => {
+        const sink = createWriteStream(paths[name], { flags: "wx", mode: 0o600, highWaterMark: OUTPUT_IO_CHUNK_BYTES, flush: true });
+        const completion = finished(sink).catch(() => { storageFailure ??= "write_failed"; stop?.(); });
+        return { sink, completion };
+    });
+    try {
+        await Promise.all(streams.map(({ sink }) => once(sink, "open")));
+    }
+    catch {
+        for (const { sink } of streams)
+            sink.destroy();
+        await Promise.all(streams.map(({ completion }) => completion));
+        activeSystemCaptures.delete(directory);
+        scheduleSystemOutputCleanup(root, retentionMs);
+        throw new SystemOperationError("system_output_storage_failed", "Output files could not be opened. The command was not dispatched.");
+    }
+    scheduleSystemOutputCleanup(root, retentionMs);
+    const failure = () => storageFailure ?? securityFailure;
+    const capture = {
+        attach(stdout, stderr, onFailure) {
+            if (!canAttachCapture()) {
+                securityFailure ??= "output_protection_failed";
+                onFailure();
+                return;
+            }
+            stop = onFailure;
+            sources.push(stdout, stderr);
+            for (const [index, source] of sources.entries()) {
+                source.once("end", () => completeStreams.add(STREAMS[index]));
+                source.once("error", () => { securityFailure ??= "output_incomplete"; stop?.(); });
+                source.pipe(streams[index].sink);
+            }
+            if (failure())
+                onFailure();
+        },
+        end() {
+            if (ended)
+                return;
+            ended = true;
+            if (!hasCompleteStreams())
+                securityFailure ??= "output_incomplete";
+            for (const source of sources) {
+                source.unpipe();
+                source.destroy();
+            }
+            for (const { sink } of streams)
+                if (!sink.destroyed && !sink.writableEnded)
+                    sink.end();
+        },
+    };
+    function canAttachCapture() { return sources.length === 0 && !ended; }
+    function hasCompleteStreams() { return completeStreams.size === 2; }
+    function protectProcess(result) {
+        if (!result)
+            return;
+        let spawnedProcess = result.spawnedProcess;
+        if (spawnedProcess) {
+            let executable = "[REDACTED]";
+            try {
+                executable = redact(spawnedProcess.executable);
+                if (!hasProtectedIdentity(executable))
+                    throw new Error("output_protection_failed");
+            }
+            catch {
+                securityFailure ??= "output_protection_failed";
+                executable = "[REDACTED]";
+            }
+            spawnedProcess = { ...spawnedProcess, executable };
+        }
+        processResult = { exitCode: result.exitCode, status: result.status, outputTruncated: result.outputTruncated,
+            stdout: "", stderr: "", ...(spawnedProcess ? { spawnedProcess } : {}) };
+    }
+    async function finish(result, materialize = true) {
+        capture.end();
+        await Promise.all(streams.map(({ completion }) => completion));
+        protectProcess(result);
+        let protectedBytes;
+        try {
+            if (!failure()) {
+                try {
+                    protectedBytes = await protectCapturedOutput(paths, redact);
+                }
+                catch (error) {
+                    if (isOutputStorageFailure(error))
+                        storageFailure ??= "write_failed";
+                    else
+                        securityFailure ??= "output_protection_failed";
+                }
+            }
+            if (failure() && !await discardCapturedOutput(paths))
+                storageFailure = "capture_purge_failed";
+            receipt = { id, stdoutBytes: protectedBytes?.stdout.length ?? 0, stderrBytes: protectedBytes?.stderr.length ?? 0,
+                completedAt: new Date().toISOString(), retentionMs, complete: !failure(), ...(!materialize && protectedBytes ? {
+                    stdoutSha256: createHash("sha256").update(protectedBytes.stdout).digest("hex"),
+                    stderrSha256: createHash("sha256").update(protectedBytes.stderr).digest("hex"),
+                } : {}) };
+            try {
+                const temporary = join(directory, "receipt.tmp");
+                await writeFile(temporary, JSON.stringify({ kind: "system_command_output_v1", ...receipt,
+                    processStatus: processResult?.status, exitCode: processResult?.exitCode, spawnedProcess: processResult?.spawnedProcess,
+                    ...(securityFailure ? { securityFailure } : {}), ...(storageFailure ? { storageFailure } : {}) }), { flag: "wx", mode: 0o600, flush: true });
+                await rename(temporary, join(directory, "receipt.json"));
+            }
+            catch {
+                storageFailure ??= "receipt_write_failed";
+                receipt = { ...receipt, complete: false };
+            }
+            admitted = receipt.complete;
+            if (!admitted || !materialize || !protectedBytes)
+                return { stdout: "", stderr: "" };
+            return { stdout: protectedBytes.stdout.toString("utf8"), stderr: protectedBytes.stderr.toString("utf8") };
+        }
+        finally {
+            protectedBytes?.stdout.fill(0);
+            protectedBytes?.stderr.fill(0);
+            if (!retained)
+                activeSystemCaptures.delete(directory);
+        }
+    }
+    return {
+        capture,
+        get receipt() { return receipt; },
+        get failure() { return failure(); },
+        get failureKind() {
+            if (storageFailure)
+                return "storage";
+            return securityFailure ? "security" : undefined;
+        },
+        get processResult() { return processResult; },
+        retain() { retained = true; activeSystemCaptures.add(directory); },
+        release() { retained = false; activeSystemCaptures.delete(directory); },
+        async read(stream, offset, length) {
+            if (!admitted)
+                throw new Error("system_output_unavailable");
+            if (!isAdmittedOutputRead(stream, offset, length, receipt))
+                throw new Error("system_output_reference_invalid");
+            const file = await open(paths[stream], "r");
+            try {
+                const size = stream === "stdout" ? receipt.stdoutBytes : receipt.stderrBytes;
+                const bytes = Buffer.alloc(Math.min(length, size - offset));
+                const { bytesRead } = await file.read(bytes, 0, bytes.length, offset);
+                return bytes.subarray(0, bytesRead);
+            }
+            finally {
+                await file.close();
+            }
+        },
+        finish(result, materialize = true) {
+            finishing ??= finish(result, materialize);
+            return finishing;
+        },
+    };
+}
+function hasOutputProtection(value) { return typeof value === "function"; }
+function hasProtectedIdentity(value) { return typeof value === "string"; }
+function isOutputStorageFailure(error) {
+    return error instanceof CapturedOutputProtectionError && error.reason === "output_storage_failed";
+}
+function isAdmittedOutputRead(stream, offset, length, receipt) {
+    if (stream !== "stdout" && stream !== "stderr")
+        return false;
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        return false;
+    if (!Number.isSafeInteger(length) || length < 0)
+        return false;
+    const size = stream === "stdout" ? receipt.stdoutBytes : receipt.stderrBytes;
+    return offset <= size;
+}

package/dist/src/computer-access/command-output-protection.d.ts

@@ -0,0 +1,17 @@
+export type CapturedOutputPaths = Readonly<{
+    stdout: string;
+    stderr: string;
+}>;
+export type ProtectedOutputBytes = Readonly<{
+    stdout: Buffer;
+    stderr: Buffer;
+}>;
+export type OutputProtectionFailure = "output_protection_failed" | "output_storage_failed";
+export declare class CapturedOutputProtectionError extends Error {
+    readonly reason: OutputProtectionFailure;
+    constructor(reason: OutputProtectionFailure);
+}
+/** Check both complete private streams before replacing either source. */
+export declare function protectCapturedOutput(paths: CapturedOutputPaths, redact: (text: string) => string): Promise<ProtectedOutputBytes>;
+/** A failed check makes the private sources unavailable, including later reads. */
+export declare function discardCapturedOutput(paths: CapturedOutputPaths): Promise<boolean>;

package/dist/src/computer-access/command-output-protection.js

@@ -0,0 +1,59 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+export class CapturedOutputProtectionError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+/** Check both complete private streams before replacing either source. */
+export async function protectCapturedOutput(paths, redact) {
+    let stdout, stderr;
+    try {
+        stdout = await protectStream(paths.stdout, redact);
+        stderr = await protectStream(paths.stderr, redact);
+        const writes = await Promise.allSettled([
+            writeFile(paths.stdout, stdout, { flag: "w", mode: 0o600, flush: true }),
+            writeFile(paths.stderr, stderr, { flag: "w", mode: 0o600, flush: true }),
+        ]);
+        if (hasRejectedOutputWrite(writes))
+            throw new CapturedOutputProtectionError("output_storage_failed");
+        return { stdout, stderr };
+    }
+    catch (error) {
+        stdout?.fill(0);
+        stderr?.fill(0);
+        throw error;
+    }
+}
+async function protectStream(path, redact) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        throw new CapturedOutputProtectionError("output_storage_failed");
+    }
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        const protectedText = redact(text);
+        if (!isProtectedOutputText(protectedText))
+            throw new Error("output_protection_failed");
+        return Buffer.from(protectedText, "utf8");
+    }
+    catch {
+        throw new CapturedOutputProtectionError("output_protection_failed");
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+/** A failed check makes the private sources unavailable, including later reads. */
+export async function discardCapturedOutput(paths) {
+    const removed = await Promise.allSettled(Object.values(paths).map((path) => rm(path, { force: true })));
+    return removed.every((entry) => entry.status === "fulfilled");
+}
+function isProtectedOutputText(value) { return typeof value === "string"; }
+function hasRejectedOutputWrite(writes) {
+    return writes.some((entry) => entry.status === "rejected");
+}

package/dist/src/computer-access/command-output-retention.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_SYSTEM_OUTPUT_RETENTION_MS: number;
+export declare const activeSystemCaptures: Set<string>;
+export declare function cleanupSystemOutput(root: string, retentionMs: number): Promise<number>;
+/** One cleanup job per storage root; the supplied policy also covers incomplete captures. */
+export declare function scheduleSystemOutputCleanup(root: string, retentionMs: number): void;

package/dist/src/computer-access/command-output-retention.js

@@ -0,0 +1,90 @@
+import { readFile, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+export const DEFAULT_SYSTEM_OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+export const activeSystemCaptures = new Set();
+const jobs = new Map();
+const CAPTURE_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+export async function cleanupSystemOutput(root, retentionMs) {
+    const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !CAPTURE_ID.test(entry.name))
+            continue;
+        const directory = join(root, entry.name);
+        if (activeSystemCaptures.has(directory))
+            continue;
+        const files = await readdir(directory);
+        const times = await Promise.all(files.map(async (file) => (await stat(join(directory, file))).mtimeMs));
+        const completedAt = Math.max((await stat(directory)).mtimeMs, ...times);
+        const captureRetentionMs = await readCaptureRetention(directory, entry.name, retentionMs);
+        if (Date.now() - completedAt < captureRetentionMs)
+            continue;
+        if (activeSystemCaptures.has(directory))
+            continue;
+        await rm(directory, { recursive: true });
+        removed += 1;
+    }
+    return removed;
+}
+/** Completed captures keep the policy recorded by their producer across reconnects. */
+async function readCaptureRetention(directory, id, fallbackMs) {
+    let receipt;
+    try {
+        receipt = JSON.parse(await readFile(join(directory, "receipt.json"), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallbackMs;
+        if (error instanceof SyntaxError)
+            return fallbackMs;
+        throw error;
+    }
+    if (receipt === null || typeof receipt !== "object")
+        return fallbackMs;
+    if (!("kind" in receipt) || receipt.kind !== "system_command_output_v1")
+        return fallbackMs;
+    if (!("id" in receipt) || receipt.id !== id)
+        return fallbackMs;
+    if (!("retentionMs" in receipt) || typeof receipt.retentionMs !== "number")
+        return fallbackMs;
+    if (!Number.isSafeInteger(receipt.retentionMs) || receipt.retentionMs < 1)
+        return fallbackMs;
+    return receipt.retentionMs;
+}
+/** One cleanup job per storage root; the supplied policy also covers incomplete captures. */
+export function scheduleSystemOutputCleanup(root, retentionMs) {
+    const previous = jobs.get(root);
+    if (previous) {
+        previous.retentionMs = retentionMs;
+        previous.requested = true;
+        return;
+    }
+    const job = { retentionMs, requested: false };
+    jobs.set(root, job);
+    const sweep = async () => {
+        job.requested = false;
+        let empty = false;
+        try {
+            await cleanupSystemOutput(root, job.retentionMs);
+            empty = (await readdir(root).catch((error) => {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            })).length === 0;
+        }
+        catch {
+            process.emitWarning("SYSTEM output cleanup failed; retained output was not confirmed removed.", { code: "SYSTEM_OUTPUT_CLEANUP_FAILED" });
+        }
+        if (empty && !job.requested) {
+            jobs.delete(root);
+            return;
+        }
+        const timer = setTimeout(() => { void sweep(); }, Math.max(1, Math.min(job.retentionMs, 60 * 60_000)));
+        timer.unref();
+    };
+    void sweep();
+}

package/dist/src/computer-access/command-output.d.ts

@@ -0,0 +1,7 @@
+import type { ToolExecutionContext, ToolImplementationOutput } from "../plugin-sdk/index.js";
+import type { SystemProcessResult, SystemProcessRunner, SystemTarget } from "./contracts.js";
+/** Allocated per command; probes and companion calls retain their existing runner. */
+export type SystemCommandOutputFactory = (context?: ToolExecutionContext) => Readonly<{
+    run: SystemProcessRunner;
+    present(target: SystemTarget, result: SystemProcessResult): Promise<ToolImplementationOutput>;
+}>;

package/dist/src/computer-access/command-output.js

@@ -0,0 +1 @@
+export {};

package/dist/src/computer-access/commands.d.ts

@@ -3,5 +3,6 @@ export declare function executeSystemCommand(input: {
     target: SystemTarget;
     params: Record<string, unknown>;
     run: SystemProcessRunner;
+    runCommand?: SystemProcessRunner;
     abortSignal?: AbortSignal;
 }): Promise<SystemProcessResult>;

package/dist/src/computer-access/commands.js

@@ -32,7 +32,7 @@ export async function executeSystemCommand(input) {
     const plan = params.elevated === true
         ? await elevatedSystemCommand({ target, command, cwd, run })
         : unprivilegedSystemCommand(target, command, cwd);
-    return run({
+    return (input.runCommand ?? run)({
         ...plan,
         timeoutMs,
         ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),

package/dist/src/computer-access/companion/command-output-protocol.d.ts

@@ -0,0 +1,12 @@
+export declare const SYSTEM_OUTPUT_CAPABILITY = "system_command_output_v1";
+/** Base64 plus receipts stay below both Companion and broker message limits. */
+export declare const SYSTEM_OUTPUT_CHUNK_BYTES: number;
+export type SystemOutputTransfer = Readonly<{
+    kind: typeof SYSTEM_OUTPUT_CAPABILITY;
+    id: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdoutSha256: string;
+    stderrSha256: string;
+}>;
+export declare function readSystemOutputTransfer(value: unknown): SystemOutputTransfer;

package/dist/src/computer-access/companion/command-output-protocol.js

@@ -0,0 +1,28 @@
+import { isHostIdentifier, isHostRecord } from "./protocol.js";
+export const SYSTEM_OUTPUT_CAPABILITY = "system_command_output_v1";
+/** Base64 plus receipts stay below both Companion and broker message limits. */
+export const SYSTEM_OUTPUT_CHUNK_BYTES = 64 * 1024;
+function isStreamByteCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isStreamDigest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+export function readSystemOutputTransfer(value) {
+    if (!isHostRecord(value))
+        throw new Error("system_output_receipt_invalid");
+    if (value.kind !== SYSTEM_OUTPUT_CAPABILITY)
+        throw new Error("system_output_receipt_invalid");
+    if (!isHostIdentifier(value.id))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamByteCount(value.stdoutBytes))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamByteCount(value.stderrBytes))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamDigest(value.stdoutSha256))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamDigest(value.stderrSha256))
+        throw new Error("system_output_receipt_invalid");
+    return { kind: SYSTEM_OUTPUT_CAPABILITY, id: value.id, stdoutBytes: value.stdoutBytes,
+        stderrBytes: value.stderrBytes, stdoutSha256: value.stdoutSha256, stderrSha256: value.stderrSha256 };
+}

package/dist/src/computer-access/companion/command-output.d.ts

@@ -0,0 +1,14 @@
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+/** References belong to this authenticated connection; no arbitrary file access. */
+export declare class CompanionCommandOutput {
+    private readonly stateDir;
+    private readonly captures;
+    private closed;
+    constructor(stateDir: string);
+    hasTransfers(): boolean;
+    close(): void;
+    handlers(): Record<string, ToolImplementation>;
+    private command;
+    private hasRegisteredTransfer;
+    private read;
+}

package/dist/src/computer-access/companion/command-output.js

@@ -0,0 +1,127 @@
+import { join } from "node:path";
+import { failureResult, readBoundedInteger, successResult } from "../../plugin-sdk/index.js";
+import { createSystemHandlers } from "../handlers.js";
+import { createSystemOutputCapture } from "../command-output-capture.js";
+import { DEFAULT_SYSTEM_OUTPUT_RETENTION_MS, scheduleSystemOutputCleanup } from "../command-output-retention.js";
+import { runSystemProcess } from "../process-runner.js";
+import { buildSystemProcessResult } from "../process-result.js";
+import { isHostIdentifier } from "./protocol.js";
+import { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer } from "./command-output-protocol.js";
+import { redactSecretText } from "../security/secret-text.js";
+import { systemResultProtection } from "../security/system-results.js";
+/** References belong to this authenticated connection; no arbitrary file access. */
+export class CompanionCommandOutput {
+    stateDir;
+    captures = new Map();
+    closed = false;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        scheduleSystemOutputCleanup(join(stateDir, "command-output"), DEFAULT_SYSTEM_OUTPUT_RETENTION_MS);
+    }
+    hasTransfers() { return this.captures.size > 0; }
+    close() {
+        this.closed = true;
+        for (const capture of this.captures.values())
+            capture.release();
+        this.captures.clear();
+    }
+    handlers() {
+        return {
+            system_command_capture: (params, context) => this.command(params, context),
+            system_command_output: async (params) => {
+                try {
+                    return await this.read(params);
+                }
+                catch {
+                    return failureResult({ errorCode: "system_output_unavailable", message: "Retained command output is unavailable in this connection. The command was not replayed." });
+                }
+            },
+            system_command_output_close: async (params) => {
+                if (!isHostIdentifier(params.captureId))
+                    return failureResult({ errorCode: "system_output_reference_invalid", message: "Invalid output reference." });
+                this.captures.get(params.captureId)?.release();
+                this.captures.delete(params.captureId);
+                return successResult({ output: "Output transfer closed; disk retention remains in effect." });
+            },
+        };
+    }
+    async command(params, context) {
+        if (this.closed)
+            return failureResult({ errorCode: "system_output_closed", message: "The connection closed before dispatch." });
+        const retentionMs = readBoundedInteger(params.outputRetentionMs, {
+            name: "outputRetentionMs", defaultValue: DEFAULT_SYSTEM_OUTPUT_RETENTION_MS,
+            minimum: 1, maximum: Number.MAX_SAFE_INTEGER,
+        });
+        let captured;
+        const handlers = createSystemHandlers(undefined, undefined, () => ({
+            run: async (input) => {
+                if (input.abortSignal?.aborted)
+                    return runSystemProcess(input);
+                captured = await createSystemOutputCapture(join(this.stateDir, "command-output"), retentionMs, redactSecretText);
+                captured.retain();
+                try {
+                    const result = await runSystemProcess(input, captured.capture);
+                    await captured.finish(result, false);
+                    return { ...captured.processResult, outputTruncated: Boolean(captured.failure) };
+                }
+                catch (error) {
+                    await captured.finish(undefined, false);
+                    captured.release();
+                    throw error;
+                }
+            },
+            present: async (target, result) => {
+                const receipt = buildSystemProcessResult(target, result, "command_process_completion");
+                if (!captured?.receipt)
+                    return receipt;
+                const data = { ...receipt.data, outputCapture: captured.receipt };
+                if (captured.failure) {
+                    captured.release();
+                    const errorCode = captured.failureKind === "security" ? "system_output_protection_failed" : "system_output_storage_failed";
+                    return failureResult({ errorCode, message: "Command output could not be admitted after dispatch; inspect the process receipt before another action. The command was not replayed.",
+                        data: { ...data, ...(captured.failureKind === "security"
+                                ? { securityFailure: captured.failure } : { storageFailure: captured.failure }) },
+                        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}) });
+                }
+                if (this.closed || context?.abortSignal?.aborted) {
+                    captured.release();
+                    return { ...receipt, data };
+                }
+                const transfer = readSystemOutputTransfer({ kind: SYSTEM_OUTPUT_CAPABILITY, ...captured.receipt });
+                this.captures.set(transfer.id, captured);
+                return { ...receipt, output: receipt.output.split("\nSTDOUT excerpt:")[0] + "\nSTDOUT excerpt:\nStreams retained for exact transfer.",
+                    data: { ...data, outputTransfer: transfer } };
+            },
+        }), systemResultProtection);
+        const { outputRetentionMs: _retention, ...command } = params;
+        try {
+            return await handlers.system_command(command, context);
+        }
+        finally {
+            if (!this.hasRegisteredTransfer(captured))
+                captured?.release();
+        }
+    }
+    hasRegisteredTransfer(capture) {
+        const id = capture?.receipt?.id;
+        if (!id)
+            return false;
+        return this.captures.get(id) === capture;
+    }
+    async read(params) {
+        if (!isHostIdentifier(params.captureId))
+            throw new Error("system_output_reference_invalid");
+        const capture = this.captures.get(params.captureId);
+        if (!capture?.receipt)
+            throw new Error("system_output_reference_unknown");
+        if (params.stream !== "stdout" && params.stream !== "stderr")
+            throw new Error("system_output_stream_invalid");
+        const stream = params.stream;
+        const size = stream === "stdout" ? capture.receipt.stdoutBytes : capture.receipt.stderrBytes;
+        const offset = readBoundedInteger(params.offset, { name: "offset", minimum: 0, maximum: size });
+        const bytes = await capture.read(stream, offset, Math.min(SYSTEM_OUTPUT_CHUNK_BYTES, size - offset));
+        return successResult({ output: "Private command-output chunk.", data: {
+                captureId: params.captureId, stream, offset, bytes: bytes.toString("base64"),
+            } });
+    }
+}

package/dist/src/computer-access/companion/install-link-macos.d.ts

@@ -0,0 +1,7 @@
+import type { NativeAutostartOptions } from "./autostart.js";
+export declare function renderMacInstallLinkHandler(options: NativeAutostartOptions): string;
+export declare const MAC_INSTALL_LINK_BUNDLE_ID = "com.abot.install-links";
+export declare const MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT = "ObjC.import('CoreServices');\nfunction run(argv) {\n  var handler = ObjC.castRefToObject($.LSCopyDefaultHandlerForURLScheme($(argv[0])));\n  if (handler.isNil()) return '';\n  return ObjC.unwrap(handler);\n}\n";
+export declare function requireAvailableMacInstallScheme(): Promise<void>;
+/** Preserve the executable and scripting metadata emitted by osacompile. */
+export declare const MAC_INSTALL_LINK_PLIST_SCRIPT = "ObjC.import('Foundation');\nfunction run(argv) {\n  var plist = $.NSMutableDictionary.alloc.initWithContentsOfFile($(argv[0]));\n  if (!plist) throw new Error('Installation-link bundle has no property list.');\n  var updates = {\n    CFBundleIdentifier: 'com.abot.install-links',\n    CFBundleName: 'ABot Install',\n    LSUIElement: true,\n    CFBundleURLTypes: [{CFBundleURLName: 'ABot installation links', CFBundleURLSchemes: ['abot']}]\n  };\n  Object.keys(updates).forEach(function(key) { plist.setObjectForKey($(updates[key]), $(key)); });\n  if (!plist.writeToFileAtomically($(argv[0]), true)) throw new Error('Could not register installation links.');\n}\n";

package/dist/src/computer-access/companion/install-link-macos.js

@@ -0,0 +1,49 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+export function renderMacInstallLinkHandler(options) {
+    const literal = (value) => JSON.stringify(value);
+    return `ObjC.import('Foundation');
+function openDocuments() {}
+// JXA dispatches the macOS Get URL (GURL/GURL) AppleEvent to this exact name.
+function GURLGURL(url) {
+  var task = $.NSTask.alloc.init;
+  task.launchPath = ${literal(options.nodePath)};
+  task.arguments = [${literal(options.cliPath)}, 'host', 'open-link', String(url)];
+  task.launch;
+}
+`;
+}
+export const MAC_INSTALL_LINK_BUNDLE_ID = "com.abot.install-links";
+export const MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT = `ObjC.import('CoreServices');
+function run(argv) {
+  var handler = ObjC.castRefToObject($.LSCopyDefaultHandlerForURLScheme($(argv[0])));
+  if (handler.isNil()) return '';
+  return ObjC.unwrap(handler);
+}
+`;
+const executeFile = promisify(execFile);
+function isAvailableMacInstallScheme(handler) {
+    if (!handler)
+        return true;
+    return handler === MAC_INSTALL_LINK_BUNDLE_ID;
+}
+export async function requireAvailableMacInstallScheme() {
+    const { stdout } = await executeFile("/usr/bin/osascript", ["-l", "JavaScript", "-e", MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT, "abot"], { timeout: 30_000, maxBuffer: 16_384 });
+    if (!isAvailableMacInstallScheme(stdout.trim()))
+        throw new Error("The abot URL scheme belongs to another application.");
+}
+/** Preserve the executable and scripting metadata emitted by osacompile. */
+export const MAC_INSTALL_LINK_PLIST_SCRIPT = `ObjC.import('Foundation');
+function run(argv) {
+  var plist = $.NSMutableDictionary.alloc.initWithContentsOfFile($(argv[0]));
+  if (!plist) throw new Error('Installation-link bundle has no property list.');
+  var updates = {
+    CFBundleIdentifier: '${MAC_INSTALL_LINK_BUNDLE_ID}',
+    CFBundleName: 'ABot Install',
+    LSUIElement: true,
+    CFBundleURLTypes: [{CFBundleURLName: 'ABot installation links', CFBundleURLSchemes: ['abot']}]
+  };
+  Object.keys(updates).forEach(function(key) { plist.setObjectForKey($(updates[key]), $(key)); });
+  if (!plist.writeToFileAtomically($(argv[0]), true)) throw new Error('Could not register installation links.');
+}
+`;

package/dist/src/computer-access/companion/install-link-registration.d.ts

@@ -0,0 +1,4 @@
+import type { NativeAutostartOptions } from "./autostart.js";
+export declare function renderLinuxInstallLinkDesktop(options: NativeAutostartOptions): string;
+export declare function installCompanionInstallLinks(options: NativeAutostartOptions): Promise<void>;
+export declare function uninstallCompanionInstallLinks(options: NativeAutostartOptions): Promise<void>;