@abot-ai/runtime 1.6.0 → 1.8.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,8 +13,9 @@ 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() {
@@ -27,6 +27,7 @@ function printHostHelp() {
         "  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.",
@@ -35,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"),
@@ -79,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;
@@ -120,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();
@@ -143,31 +151,22 @@ 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)) {
@@ -178,11 +177,15 @@ export async function runHostCompanionCli(args, options = {}) {
         await runHostPermissionsCli(rest);
         return;
     }
-    const state = nativeState();
+    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") {
@@ -190,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/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/collection-consent.d.ts

@@ -0,0 +1,9 @@
+export type CollectionConsent = Readonly<{
+    accepted: boolean;
+    acceptedAt?: string;
+}>;
+/** Installation data, shared across environments and independent of app versions or pairing. */
+export declare function readCollectionConsent(rootDir: string): CollectionConsent;
+/** Acknowledgment records awareness only; it does not change activity permissions or start collection. */
+export declare function acceptCollectionConsent(rootDir: string): Promise<CollectionConsent>;
+export declare function requireCollectionConsent(rootDir: string): void;

package/dist/src/computer-access/collection-consent.js

@@ -0,0 +1,47 @@
+import { join } from "node:path";
+import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
+import { hostStateDirectory, readHostPrivateJson, writeHostPrivateJson, } from "./companion/private-store.js";
+function isSavedCollectionConsent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    if (record.version !== 1)
+        return false;
+    if (typeof record.acceptedAt !== "string")
+        return false;
+    return Number.isFinite(Date.parse(record.acceptedAt));
+}
+function collectionConsentPath(rootDir) {
+    return join(hostStateDirectory(rootDir), "collection-consent.json");
+}
+/** Installation data, shared across environments and independent of app versions or pairing. */
+export function readCollectionConsent(rootDir) {
+    let record;
+    try {
+        record = readHostPrivateJson(collectionConsentPath(rootDir));
+    }
+    catch (error) {
+        // A malformed record never authorizes collection. Filesystem safety errors remain visible.
+        if (error instanceof SyntaxError)
+            return { accepted: false };
+        throw error;
+    }
+    if (!isSavedCollectionConsent(record))
+        return { accepted: false };
+    return { accepted: true, acceptedAt: record.acceptedAt };
+}
+/** Acknowledgment records awareness only; it does not change activity permissions or start collection. */
+export async function acceptCollectionConsent(rootDir) {
+    await ensurePrivateRuntimeDirectory(hostStateDirectory(rootDir));
+    const existing = readCollectionConsent(rootDir);
+    if (existing.accepted)
+        return existing;
+    const acceptedAt = new Date().toISOString();
+    writeHostPrivateJson(collectionConsentPath(rootDir), { version: 1, acceptedAt });
+    return { accepted: true, acceptedAt };
+}
+export function requireCollectionConsent(rootDir) {
+    if (readCollectionConsent(rootDir).accepted)
+        return;
+    throw new Error("collection_consent_required");
+}

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

@@ -0,0 +1,48 @@
+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;
+}>;
+type OutputStreams = {
+    stdout: string;
+    stderr: string;
+};
+/** Private backpressured capture. No read is admitted before complete checks. */
+export declare function createSystemOutputCapture(root: string, retentionMs: number, redact: (text: string) => string): 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;
+    readonly failureKind: "storage" | "security" | undefined;
+    readonly processResult: Readonly<{
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+        status: "completed" | "timeout" | "aborted" | "spawn_failed" | "output_failed";
+        outputTruncated: boolean;
+        spawnedProcess?: import("./contracts.js").SystemSpawnObservation;
+    }> | undefined;
+    retain(): void;
+    release(): void;
+    read(stream: "stdout" | "stderr", offset: number, length: number): Promise<Buffer>;
+    finish(result?: SystemProcessResult, materialize?: boolean): Promise<OutputStreams>;
+}>;
+export {};