@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/cli/host-companion-entry.js

@@ -3,31 +3,14 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { isNativeCredential } from "../computer-access/companion/native-state.js";
 import { isHostIdentifier, isHostRecord, } from "../computer-access/companion/protocol.js";
 import { runHostCompanionCli } from "./host-companion.js";
-const SETUP_INPUT_LIMIT_BYTES = 16_384;
-const SETUP_INPUT_TIMEOUT_MS = 10_000;
+import { readHostCompanionInput } from "./host-companion-input.js";
 async function readSetupInput(input) {
-    const chunks = [];
-    let length = 0;
-    const deadline = setTimeout(() => {
-        input.destroy(new Error("Host setup input timed out."));
-    }, SETUP_INPUT_TIMEOUT_MS);
+    const text = await readHostCompanionInput(input);
     try {
-        for await (const chunk of input) {
-            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-            length += bytes.length;
-            if (length > SETUP_INPUT_LIMIT_BYTES)
-                throw new Error("Host setup input exceeds the size limit.");
-            chunks.push(bytes);
-        }
-        try {
-            return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-        }
-        catch {
-            throw new Error("Host setup requires a JSON object on standard input.");
-        }
+        return JSON.parse(text);
     }
-    finally {
-        clearTimeout(deadline);
+    catch {
+        throw new Error("Host setup requires a JSON object on standard input.");
     }
 }
 function readSetupRequest(value) {

package/dist/src/cli/host-companion-input.d.ts

@@ -0,0 +1,3 @@
+import type { Readable } from "node:stream";
+/** Native launchers send short-lived secrets through bounded stdin, never shell arguments. */
+export declare function readHostCompanionInput(input: Readable, maxBytes?: number): Promise<string>;

package/dist/src/cli/host-companion-input.js

@@ -0,0 +1,21 @@
+/** Native launchers send short-lived secrets through bounded stdin, never shell arguments. */
+export async function readHostCompanionInput(input, maxBytes = 16_384) {
+    const chunks = [];
+    let length = 0;
+    const deadline = setTimeout(() => {
+        input.destroy(new Error("Host setup input timed out."));
+    }, 10_000);
+    try {
+        for await (const chunk of input) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            length += bytes.length;
+            if (length > maxBytes)
+                throw new Error("Host setup input exceeds the size limit.");
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+}

package/dist/src/cli/host-companion-lifecycle.d.ts

@@ -0,0 +1,11 @@
+import { type NativeAutostartOptions } from "../computer-access/companion/autostart.js";
+import type { NativeNotificationSession } from "../computer-access/companion/native-notifications.js";
+import type { NativeHostState } from "../computer-access/companion/native-state.js";
+/** Packaging owns OS registration; pairing, ownership and supervision stay shared. */
+export type HostCompanionLifecycle = Readonly<{
+    assertStartupSupported(startup: NativeAutostartOptions): void | Promise<void>;
+    completeStartup(state: NativeHostState, startup: NativeAutostartOptions, hostId: string): Promise<void>;
+    uninstall(state: NativeHostState, startup: NativeAutostartOptions): Promise<void>;
+    createNotifications?(runtimeUrl: string, signal?: AbortSignal): Promise<NativeNotificationSession>;
+}>;
+export declare const defaultHostCompanionLifecycle: HostCompanionLifecycle;

package/dist/src/cli/host-companion-lifecycle.js

@@ -0,0 +1,32 @@
+import { join } from "node:path";
+import { nativeAutostartFile, uninstallNativeAutostart, } from "../computer-access/companion/autostart.js";
+import { uninstallCompanionInstallLinks } from "../computer-access/companion/install-link-registration.js";
+import { uninstallDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
+import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../computer-access/companion/process-owner-identity.js";
+import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
+import { completeHostCompanionStartup } from "./host-companion-startup.js";
+async function uninstallDefaultCompanion(state, startup) {
+    await state.remove();
+    await uninstallNativeAutostart(startup);
+    await uninstallDesktopNotificationIdentity(startup);
+    const ownerIdentity = await requireCurrentProcessOwnerIdentity();
+    const release = await acquireFileLock(join(state.directory, "agent"), {
+        waitMs: 5_000,
+        releaseMode: "synchronous",
+        ownerIdentity,
+        processIsAlive: isProcessOwnerAlive,
+    });
+    await release();
+    await uninstallCompanionInstallLinks(startup).catch((error) => {
+        console.warn("Plugin installation link cleanup needs attention: " +
+            (error instanceof Error ? error.message : String(error)));
+    });
+    console.log("Host companion stopped. Login startup and the saved credential were removed.");
+}
+export const defaultHostCompanionLifecycle = {
+    assertStartupSupported(startup) {
+        nativeAutostartFile(startup);
+    },
+    completeStartup: completeHostCompanionStartup,
+    uninstall: uninstallDefaultCompanion,
+};

package/dist/src/cli/host-companion-setup-target.d.ts

@@ -1,3 +1,7 @@
 import type { NativeHostConnection } from "../computer-access/companion/native-state.js";
 /** Upgrade identity selects existing private state, never a new credential destination. */
 export declare function resolveHostCompanionSetupUrl(saved: NativeHostConnection | undefined, requestedUrl: string, upgradeHostId?: string): string;
+/** Explicit fresh Store consent bypasses resume; other callers keep their saved pairing. */
+export declare function canResumeHostCompanionPairing(saved: NativeHostConnection | undefined, pairingMode?: "fresh-grant"): saved is NativeHostConnection;
+export declare function assertFreshHostPairingGrant(pairingMode: "fresh-grant" | undefined, pairingCode: string | undefined, upgradeHostId: string | undefined): void;
+export declare function requiresFreshHostPairing(pairingMode?: "fresh-grant"): boolean;

package/dist/src/cli/host-companion-setup-target.js

@@ -21,3 +21,20 @@ export function resolveHostCompanionSetupUrl(saved, requestedUrl, upgradeHostId)
         throw new Error("This upgrade belongs to a different paired computer connection.");
     return saved.url;
 }
+/** Explicit fresh Store consent bypasses resume; other callers keep their saved pairing. */
+export function canResumeHostCompanionPairing(saved, pairingMode) {
+    if (!saved)
+        return false;
+    return !requiresFreshHostPairing(pairingMode);
+}
+export function assertFreshHostPairingGrant(pairingMode, pairingCode, upgradeHostId) {
+    if (!requiresFreshHostPairing(pairingMode))
+        return;
+    if (!pairingCode)
+        throw new Error("A fresh connection requires a pairing grant.");
+    if (upgradeHostId !== undefined)
+        throw new Error("A fresh connection cannot carry an upgrade identity.");
+}
+export function requiresFreshHostPairing(pairingMode) {
+    return pairingMode === "fresh-grant";
+}

package/dist/src/cli/host-companion-startup.d.ts

@@ -1,4 +1,6 @@
 import { type NativeAutostartOptions } from "../computer-access/companion/autostart.js";
 import type { NativeHostState } from "../computer-access/companion/native-state.js";
+export declare function startDetachedCompanion(options: NativeAutostartOptions): Promise<void>;
+export declare function waitForNativeConnection(state: NativeHostState, hostId: string, buildId: string, connectedAfter: number): Promise<boolean>;
 /** Startup can be resumed without consuming another grant or changing the saved pairing. */
 export declare function completeHostCompanionStartup(state: NativeHostState, startup: NativeAutostartOptions, hostId: string): Promise<void>;

package/dist/src/cli/host-companion-startup.js

@@ -1,3 +1,4 @@
+import { installCompanionInstallLinks } from "../computer-access/companion/install-link-registration.js";
 import { spawn } from "node:child_process";
 import { installDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
 import { setTimeout as delay } from "node:timers/promises";
@@ -5,7 +6,7 @@ import { installNativeAutostart, existingOwnedRegistration, nativeAutostartFile,
 import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
 import { stopOwnedNativeCompanion } from "../computer-access/companion/native-replacement.js";
 import { prepareNativeCompanionRuntime } from "../computer-access/companion/native-runtime-installation.js";
-async function startDetachedCompanion(options) {
+export async function startDetachedCompanion(options) {
     const child = spawn(options.nodePath, [options.cliPath, "host", "run"], {
         cwd: options.homeDir,
         detached: true,
@@ -18,7 +19,7 @@ async function startDetachedCompanion(options) {
     });
     child.unref();
 }
-async function waitForNativeConnection(state, hostId, buildId, connectedAfter) {
+export async function waitForNativeConnection(state, hostId, buildId, connectedAfter) {
     const deadline = Date.now() + 10_000;
     do {
         if (await state.isConnected(hostId, buildId, connectedAfter))
@@ -39,6 +40,10 @@ export async function completeHostCompanionStartup(state, startup, hostId) {
             console.warn("Desktop notifications setup needs attention: " +
                 (error instanceof Error ? error.message : String(error)));
         });
+    await installCompanionInstallLinks(managedStartup).catch((error) => {
+        console.warn("Plugin installation links need attention: " +
+            (error instanceof Error ? error.message : String(error)));
+    });
     const connectedAfter = Date.now();
     const installed = await installNativeAutostart(managedStartup);
     if (!installed.started)

package/dist/src/cli/host-companion.d.ts

@@ -1,6 +1,12 @@
+import { type NativeHostState } from "../computer-access/companion/native-state.js";
+import { type HostCompanionLifecycle } from "./host-companion-lifecycle.js";
+export declare function createHostCompanionState(): NativeHostState;
 export type HostCompanionCliOptions = Readonly<{
     cliPath?: string;
     pairingCode?: string;
     upgradeHostId?: string;
+    /** Store fresh connection consent must consume its new grant even with stale state. */
+    pairingMode?: "fresh-grant";
+    lifecycle?: HostCompanionLifecycle;
 }>;
 export declare function runHostCompanionCli(args: string[], options?: HostCompanionCliOptions): Promise<void>;

package/dist/src/cli/host-companion.js

@@ -1,10 +1,9 @@
 import { homedir } from "node:os";
-import { uninstallDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
+import { openPluginInstallLink, parsePluginInstallArguments, } from "../computer-access/companion/install-link.js";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
-import { nativeAutostartFile, uninstallNativeAutostart, } from "../computer-access/companion/autostart.js";
 import { normalizeNativeRuntimeUrl, resolveNativeRuntimeAddress, } from "../computer-access/companion/native-address.js";
 import { readNativeHostIdentity } from "../computer-access/companion/native-identity.js";
 import { connectNativeHost } from "../computer-access/companion/native-session.js";
@@ -14,17 +13,21 @@ import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../com
 import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
 import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
 import { assertPrivateRuntimeAccess } from "../runtime/local-host/private-access.js";
-import { completeHostCompanionStartup } from "./host-companion-startup.js";
-import { resolveHostCompanionSetupUrl } from "./host-companion-setup-target.js";
+import { defaultHostCompanionLifecycle, } from "./host-companion-lifecycle.js";
+import { assertFreshHostPairingGrant, canResumeHostCompanionPairing, resolveHostCompanionSetupUrl, requiresFreshHostPairing, } from "./host-companion-setup-target.js";
+import { stopOwnedNativeCompanion } from "../computer-access/companion/native-replacement.js";
 import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
+import { runHostPermissionsCli } from "./host-permissions.js";
 function printHostHelp() {
     console.log([
         "Usage:",
         "  abot host connect --url http://localhost:5177",
         "  abot host status",
+        "  abot host permissions [--request screen-recording|accessibility]",
         "  abot host disconnect",
         "  abot host uninstall",
         "  abot host run",
+        "  abot host open-link <abot://install link>",
         "",
         "Connect asks for a one-time code from ABot Settings, saves a private credential,",
         "and starts the companion now and at future Windows/macOS/Linux desktop logins.",
@@ -33,7 +36,7 @@ function printHostHelp() {
         "Revoke the host in ABot Settings to remove Runtime-side pairing too.",
     ].join("\n"));
 }
-function nativeState() {
+export function createHostCompanionState() {
     return createNativeHostState(join(homedir(), ".abot", "host-companion"), {
         ensureDirectory: ensurePrivateRuntimeDirectory,
         assertFile: (path, stat) => assertPrivateRuntimeAccess(path, stat, "host_companion_state_not_private"),
@@ -77,14 +80,20 @@ async function connectHost(args, state, options) {
     if (args.length !== 2 || args[0] !== "--url")
         throw new Error("Usage: abot host connect --url http://localhost:5177");
     const startup = autostartOptions(state, options);
-    nativeAutostartFile(startup);
+    const lifecycle = options.lifecycle ?? defaultHostCompanionLifecycle;
+    await lifecycle.assertStartupSupported(startup);
+    assertFreshHostPairingGrant(options.pairingMode, options.pairingCode, options.upgradeHostId);
     const saved = await state.read();
     const url = resolveHostCompanionSetupUrl(saved, normalizeNativeRuntimeUrl(args[1]), options.upgradeHostId);
     await resolveNativeRuntimeAddress(url);
-    if (saved) {
-        await completeHostCompanionStartup(state, startup, saved.hostId);
+    if (canResumeHostCompanionPairing(saved, options.pairingMode)) {
+        await lifecycle.completeStartup(state, startup, saved.hostId);
         return;
     }
+    // The old process must exit before its credential is replaced; its in-flight
+    // authorization failure must not race with the new saved connection.
+    if (requiresFreshHostPairing(options.pairingMode))
+        await stopOwnedNativeCompanion(state.directory);
     const code = options.pairingCode ?? (await readPairingCode());
     let pairedHostId;
     let interrupted = false;
@@ -118,10 +127,11 @@ async function connectHost(args, state, options) {
         throw new Error("Host setup was interrupted before startup installation.");
     if (!pairedHostId)
         throw new Error("Pairing did not complete. Check ABot Settings and use a fresh pairing code.");
-    await completeHostCompanionStartup(state, startup, pairedHostId);
+    await lifecycle.completeStartup(state, startup, pairedHostId);
 }
 async function runHost(state, options) {
-    if (!(await state.read()))
+    const saved = await state.read();
+    if (!saved)
         return;
     const buildId = await readNativeCompanionBuildId(autostartOptions(state, options).cliPath);
     const ownerIdentity = await requireCurrentProcessOwnerIdentity();
@@ -141,42 +151,41 @@ async function runHost(state, options) {
         throw error;
     }
     try {
-        await withStopSignals((signal) => runNativeHostSupervisor({
+        await withStopSignals(async (signal) => runNativeHostSupervisor({
             state,
             identity: readNativeHostIdentity(),
             signal,
             buildId,
+            ...(options.lifecycle?.createNotifications
+                ? {
+                    notifications: await options.lifecycle.createNotifications(saved.url, signal),
+                }
+                : {}),
         }));
     }
     finally {
         await release();
     }
 }
-async function disconnectHost(state) {
-    await state.remove();
-    await uninstallNativeAutostart(autostartOptions(state));
-    await uninstallDesktopNotificationIdentity(autostartOptions(state));
-    const ownerIdentity = await requireCurrentProcessOwnerIdentity();
-    const release = await acquireFileLock(join(state.directory, "agent"), {
-        waitMs: 5_000,
-        releaseMode: "synchronous",
-        ownerIdentity,
-        processIsAlive: isProcessOwnerAlive,
-    });
-    await release();
-    console.log("Host companion stopped. Login startup and the saved credential were removed.");
-}
 export async function runHostCompanionCli(args, options = {}) {
     const [command, ...rest] = args;
     if (!command || ["help", "--help", "-h"].includes(command)) {
         printHostHelp();
         return;
     }
-    const state = nativeState();
+    if (command === "permissions") {
+        await runHostPermissionsCli(rest);
+        return;
+    }
+    const state = createHostCompanionState();
     if (command === "connect") {
         await connectHost(rest, state, options);
         return;
     }
+    if (command === "open-link") {
+        await openPluginInstallLink(state, parsePluginInstallArguments(rest));
+        return;
+    }
     if (rest.length > 0)
         throw new Error(`Unknown host argument: ${rest[0]}`);
     if (command === "run") {
@@ -184,7 +193,7 @@ export async function runHostCompanionCli(args, options = {}) {
         return;
     }
     if (command === "disconnect" || command === "uninstall") {
-        await disconnectHost(state);
+        await (options.lifecycle ?? defaultHostCompanionLifecycle).uninstall(state, autostartOptions(state, options));
         return;
     }
     if (command === "status") {

package/dist/src/cli/host-permissions.d.ts

@@ -0,0 +1,7 @@
+import { prepareMacPermissions } from "../computer-access/companion/native-permissions.js";
+/** Run from the same Terminal/app that starts ABot; never starts a companion. */
+export declare function runHostPermissionsCli(args: readonly string[], dependencies?: {
+    prepare?: typeof prepareMacPermissions;
+    print?: (message: string) => void;
+    platform?: string;
+}): Promise<void>;

package/dist/src/cli/host-permissions.js

@@ -0,0 +1,24 @@
+import { prepareMacPermissions } from "../computer-access/companion/native-permissions.js";
+function permissionCliAction(args) {
+    if (args.length === 0)
+        return { action: "check" };
+    if (args.length !== 2 || args[0] !== "--request")
+        throw new Error("Usage: abot host permissions [--request screen-recording|accessibility]");
+    if (args[1] === "screen-recording")
+        return { action: "request", permission: "screen_recording" };
+    if (args[1] === "accessibility")
+        return { action: "request", permission: "accessibility" };
+    throw new Error("Usage: abot host permissions [--request screen-recording|accessibility]");
+}
+/** Run from the same Terminal/app that starts ABot; never starts a companion. */
+export async function runHostPermissionsCli(args, dependencies = {}) {
+    const action = permissionCliAction(args);
+    if ((dependencies.platform ?? process.platform) !== "darwin")
+        throw new Error("Mac permission preparation is available only on macOS.");
+    const result = await (dependencies.prepare ?? prepareMacPermissions)(action);
+    (dependencies.print ?? console.log)(JSON.stringify({
+        scope: "calling_application",
+        ...result,
+        guidance: "These permissions belong to the Terminal/app running this command, not the installed companion. Run ABot from this same application. If macOS asks you to quit and reopen it, do so before starting a model session, then check again. App-specific Automation permissions are separate.",
+    }, null, 2));
+}

package/dist/src/cli/windows-companion-store-entry.d.ts

@@ -0,0 +1,9 @@
+import type { Readable } from "node:stream";
+import { createHostCompanionState, runHostCompanionCli } from "./host-companion.js";
+/** Store-specific activation; all pairing, state and tool execution remain in the shared CLI. */
+export declare function runWindowsCompanionStoreEntry(args: string[], options?: Readonly<{
+    input?: Readable;
+    cliPath?: string;
+    runCli?: typeof runHostCompanionCli;
+    createState?: typeof createHostCompanionState;
+}>): Promise<void>;

package/dist/src/cli/windows-companion-store-entry.js

@@ -0,0 +1,67 @@
+import { stdin } from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { normalizeNativeRuntimeUrl, resolveNativeRuntimeAddress } from "../computer-access/companion/native-address.js";
+import { parseStoreConnectionLink, STORE_CONNECTION_LINK_MAX_BYTES } from "../computer-access/companion/windows-store/connection-link.js";
+import { WINDOWS_COMPANION_AUMID } from "../computer-access/companion/windows-store/identity.js";
+import { createWindowsStoreLifecycle } from "../computer-access/companion/windows-store/lifecycle.js";
+import { hasMissingStoreUpgradeConnection, MissingStoreConnectionError, serializeStoreConnectionError } from "../computer-access/companion/windows-store/connection-error.js";
+import { createHostCompanionState, runHostCompanionCli } from "./host-companion.js";
+import { readHostCompanionInput } from "./host-companion-input.js";
+import { resolveHostCompanionSetupUrl } from "./host-companion-setup-target.js";
+function browserOrigin(runtimeUrl) {
+    const url = new URL(runtimeUrl);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    return url.origin;
+}
+/** Store-specific activation; all pairing, state and tool execution remain in the shared CLI. */
+export async function runWindowsCompanionStoreEntry(args, options = {}) {
+    const [command, ...rest] = args;
+    const cliPath = options.cliPath ?? fileURLToPath(import.meta.url);
+    const runCli = options.runCli ?? runHostCompanionCli;
+    const lifecycle = createWindowsStoreLifecycle({ appUserModelId: WINDOWS_COMPANION_AUMID });
+    if (command === "host") {
+        if (!['run', 'status', 'disconnect', 'uninstall', '--help'].includes(rest[0] ?? '') || rest.length !== 1)
+            throw new Error("Unsupported Companion command.");
+        await runCli(rest, { cliPath, lifecycle });
+        return;
+    }
+    if (rest.length !== 0)
+        throw new Error("Companion links must be sent on standard input.");
+    if (!["inspect-link", "setup-link", "open-plugin-link"].includes(command ?? ""))
+        throw new Error("Unsupported Companion command.");
+    const link = await readHostCompanionInput(options.input ?? stdin, STORE_CONNECTION_LINK_MAX_BYTES);
+    if (command === "open-plugin-link") {
+        await runCli(["open-link", link], { cliPath, lifecycle });
+        return;
+    }
+    const invitation = parseStoreConnectionLink(link);
+    const state = (options.createState ?? createHostCompanionState)();
+    const saved = await state.read();
+    if (hasMissingStoreUpgradeConnection(invitation.upgradeHostId, saved))
+        throw new MissingStoreConnectionError();
+    const target = resolveHostCompanionSetupUrl(saved, normalizeNativeRuntimeUrl(invitation.url), invitation.upgradeHostId);
+    await resolveNativeRuntimeAddress(target);
+    if (command === "inspect-link") {
+        console.log(JSON.stringify({
+            runtimeUrl: browserOrigin(target),
+            expiresAt: invitation.expiresAt,
+            paired: Boolean(saved),
+            ...(saved ? { existingRuntimeUrl: browserOrigin(saved.url) } : {}),
+        }));
+        return;
+    }
+    // Revalidated by the CLI immediately before pairing; inspection never grants consent itself.
+    await runCli(["connect", "--url", invitation.url], {
+        cliPath, lifecycle, pairingCode: invitation.code,
+        ...(invitation.upgradeHostId
+            ? { upgradeHostId: invitation.upgradeHostId }
+            : { pairingMode: "fresh-grant" }),
+    });
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void runWindowsCompanionStoreEntry(process.argv.slice(2)).catch((error) => {
+        // Neither activation URI nor one-time authorization may appear in process output.
+        console.error(serializeStoreConnectionError(error));
+        process.exitCode = 1;
+    });
+}

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

@@ -0,0 +1,37 @@
+import type { Readable } from "node:stream";
+import { type SystemProcessResult } from "./contracts.js";
+export type SystemOutputReceipt = Readonly<{
+    id: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+    completedAt: string;
+    retentionMs: number;
+    complete: boolean;
+    stdoutSha256?: string;
+    stderrSha256?: string;
+}>;
+/** One synchronous command capture; no resumable-process or cursor state. */
+export declare function createSystemOutputCapture(root: string, retentionMs: number): Promise<{
+    capture: Readonly<{
+        attach(stdout: Readable, stderr: Readable, onFailure: () => void): void;
+        end(): void;
+    }>;
+    readonly receipt: Readonly<{
+        id: string;
+        stdoutBytes: number;
+        stderrBytes: number;
+        completedAt: string;
+        retentionMs: number;
+        complete: boolean;
+        stdoutSha256?: string;
+        stderrSha256?: string;
+    }> | undefined;
+    readonly failure: string | undefined;
+    retain(): void;
+    release(): void;
+    read(stream: "stdout" | "stderr", offset: number, length: number): Promise<Buffer>;
+    finish(result?: SystemProcessResult, materialize?: boolean): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}>;

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

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { createWriteStream } from "node:fs";
+import { mkdir, open, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { finished } from "node:stream/promises";
+import { SystemOperationError } from "./contracts.js";
+import { activeSystemCaptures, scheduleSystemOutputCleanup } from "./command-output-retention.js";
+const OUTPUT_IO_CHUNK_BYTES = 64 * 1024;
+/** One synchronous command capture; no resumable-process or cursor state. */
+export async function createSystemOutputCapture(root, retentionMs) {
+    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 failure;
+    let stop;
+    let ended = false;
+    let retained = false;
+    const sources = [];
+    const streams = ["stdout", "stderr"].map((name) => {
+        const path = join(directory, name + ".bytes");
+        const sink = createWriteStream(path, { flags: "wx", mode: 0o600, highWaterMark: OUTPUT_IO_CHUNK_BYTES, flush: true });
+        const completion = finished(sink).catch(() => {
+            failure ??= "write_failed";
+            stop?.();
+        });
+        return { name, path, sink, completion, hash: createHash("sha256") };
+    });
+    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 capture = {
+        attach(stdout, stderr, onFailure) {
+            stop = onFailure;
+            sources.push(stdout, stderr);
+            stdout.on("data", (bytes) => streams[0].hash.update(bytes));
+            stderr.on("data", (bytes) => streams[1].hash.update(bytes));
+            stdout.pipe(streams[0].sink);
+            stderr.pipe(streams[1].sink);
+            if (failure)
+                onFailure();
+        },
+        end() {
+            if (ended)
+                return;
+            ended = true;
+            for (const source of sources) {
+                source.unpipe();
+                source.destroy();
+            }
+            for (const { sink } of streams)
+                if (!sink.destroyed && !sink.writableEnded)
+                    sink.end();
+        },
+    };
+    let receipt;
+    return {
+        capture,
+        get receipt() { return receipt; },
+        get failure() { return failure; },
+        retain() { retained = true; activeSystemCaptures.add(directory); },
+        release() { retained = false; activeSystemCaptures.delete(directory); },
+        async read(stream, offset, length) {
+            const path = streams.find((entry) => entry.name === stream).path;
+            const file = await open(path, "r");
+            try {
+                const bytes = Buffer.alloc(length);
+                const { bytesRead } = await file.read(bytes, 0, length, offset);
+                return bytes.subarray(0, bytesRead);
+            }
+            finally {
+                await file.close();
+            }
+        },
+        async finish(result, materialize = true) {
+            capture.end();
+            try {
+                await Promise.all(streams.map(({ completion }) => completion));
+                const sizes = await Promise.all(streams.map(async ({ path }) => {
+                    try {
+                        return (await stat(path)).size;
+                    }
+                    catch {
+                        failure ??= "read_failed";
+                        return 0;
+                    }
+                }));
+                let stdout = "", stderr = "";
+                if (!failure && materialize) {
+                    try {
+                        [stdout, stderr] = await Promise.all(streams.map(({ path }) => readFile(path, "utf8")));
+                    }
+                    catch {
+                        failure = "read_failed";
+                    }
+                }
+                const completedAt = Date.now();
+                receipt = { id, stdoutBytes: sizes[0], stderrBytes: sizes[1],
+                    completedAt: new Date(completedAt).toISOString(), retentionMs, complete: !failure,
+                    ...(!materialize ? { stdoutSha256: streams[0].hash.digest("hex"), stderrSha256: streams[1].hash.digest("hex") } : {}) };
+                try {
+                    const temporary = join(directory, "receipt.tmp");
+                    await writeFile(temporary, JSON.stringify({ kind: "system_command_output_v1", ...receipt,
+                        processStatus: result?.status, exitCode: result?.exitCode, spawnedProcess: result?.spawnedProcess,
+                        ...(failure ? { storageFailure: failure } : {}) }), { flag: "wx", mode: 0o600, flush: true });
+                    await rename(temporary, join(directory, "receipt.json"));
+                }
+                catch {
+                    failure ??= "receipt_write_failed";
+                    receipt = { ...receipt, complete: false };
+                }
+                return { stdout, stderr };
+            }
+            finally {
+                if (!retained)
+                    activeSystemCaptures.delete(directory);
+            }
+        },
+    };
+}

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;