@abot-ai/runtime 1.5.0 → 1.6.0

package/dist/src/web-ui/session-read-state/visible-messages.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+export function isVisibleMessageReadState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const state = value;
+    if (typeof state.generation !== "string" || !state.generation)
+        return false;
+    if (!Number.isSafeInteger(state.revision) || state.revision < 0)
+        return false;
+    if (!Array.isArray(state.messages))
+        return false;
+    return state.messages.every((message) => typeof message?.messageId === "string" && Number.isFinite(message.createdAt)
+        && (message.requestId === null || typeof message.requestId === "string"));
+}
+export function readVisibleMessageReceipts(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("Invalid visible message receipts.");
+    for (const entry of value) {
+        if (!isVisibleReceiptEntry(entry))
+            throw new Error("Invalid visible message receipts.");
+    }
+    return value;
+}
+function isVisibleReceiptEntry(entry) {
+    if (!Array.isArray(entry) || entry.length !== 2)
+        return false;
+    if (typeof entry[0] !== "string")
+        return false;
+    return isVisibleMessageReadState(entry[1]);
+}
+function ensureVisibleReadState(state, sessionId) {
+    const stored = new Map(state.visibleMessages ?? []);
+    const previous = stored.get(sessionId);
+    if (previous)
+        return previous;
+    const initial = { generation: randomUUID(), revision: 0, messages: [] };
+    stored.set(sessionId, initial);
+    state.visibleMessages = [...stored];
+    return initial;
+}
+function receiptIdentity(messageId, createdAt, requestId) {
+    return JSON.stringify([String(messageId), createdAt, requestId || null]);
+}
+export function visibleReadMessageIds(input) {
+    if (!Array.isArray(input) || input.length > 500)
+        throw new Error("visible_message_ids_invalid");
+    return [...new Set(input.map((id) => {
+            if (typeof id === "number" && Number.isSafeInteger(id) && id >= 0)
+                return String(id);
+            if (typeof id === "string" && id.length > 0 && id.length <= 256)
+                return id;
+            throw new Error("visible_message_ids_invalid");
+        }))];
+}
+export function visibleReadObservations(ids, input) {
+    if (!Array.isArray(input) || input.length !== ids.length)
+        throw new Error("visible_message_receipts_invalid");
+    const observations = input.map((entry) => {
+        if (!entry || typeof entry !== "object")
+            throw new Error("visible_message_receipts_invalid");
+        const id = visibleReadMessageIds([entry.id])[0];
+        if (!ids.includes(id))
+            throw new Error("visible_message_receipts_invalid");
+        if (!Number.isFinite(entry.createdAt))
+            throw new Error("visible_message_receipts_invalid");
+        const requestId = entry.requestId;
+        if (requestId !== null && typeof requestId !== "string")
+            throw new Error("visible_message_receipts_invalid");
+        return { messageId: id, createdAt: entry.createdAt, requestId: requestId || null };
+    });
+    if (new Set(observations.map((receipt) => receipt.messageId)).size !== ids.length)
+        throw new Error("visible_message_receipts_invalid");
+    return observations;
+}
+export function markVisibleAssistantMessages(state, sessionId, messages, observations, generation, now) {
+    const previous = ensureVisibleReadState(state, sessionId);
+    if (generation !== previous.generation)
+        throw new Error("read_generation_changed");
+    const stored = new Map(state.visibleMessages ?? []);
+    const assistants = messages.filter((message) => message.role === "assistant");
+    const canonical = new Set(assistants.map((message) => receiptIdentity(message.id, message.createdAt, message.requestId)));
+    const requested = new Set(observations.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    for (const identity of requested) {
+        if (!canonical.has(identity))
+            throw new Error("visible_message_receipt_stale");
+    }
+    const prior = new Set(previous.messages.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    const receipts = messages.filter((message) => message.role === "assistant").filter((message) => {
+        const identity = receiptIdentity(message.id, message.createdAt, message.requestId);
+        if (requested.has(identity))
+            return true;
+        return prior.has(identity);
+    }).map((message) => ({ messageId: String(message.id), createdAt: message.createdAt, requestId: message.requestId }));
+    if (JSON.stringify(receipts) === JSON.stringify(previous?.messages ?? []))
+        return;
+    stored.set(sessionId, { generation: previous.generation, revision: Math.max(now, previous.revision + 1), messages: receipts });
+    state.visibleMessages = [...stored];
+}
+export function projectVisibleSessionReadState(state, sessionId, messages) {
+    const saved = ensureVisibleReadState(state, sessionId);
+    const assistants = messages.filter((message) => message.role === "assistant");
+    const identities = new Set(saved.messages.map((receipt) => receiptIdentity(receipt.messageId, receipt.createdAt, receipt.requestId)));
+    const wasRead = (message) => identities.has(receiptIdentity(message.id, message.createdAt, message.requestId));
+    const unread = assistants.filter((message) => !wasRead(message));
+    const lastRead = [...assistants].reverse().find(wasRead);
+    return {
+        sessionId, readStateStatus: "available",
+        unreadMessageIds: unread.map((message) => message.id),
+        unreadCount: unread.length, hasUnread: unread.length > 0,
+        readRevision: saved?.revision ?? 0,
+        readGeneration: saved.generation,
+        lastReadAt: saved?.revision ?? state.initializedAt,
+        lastReadMessageId: lastRead?.id ?? null,
+        latestMessageId: messages.at(-1)?.id ?? null,
+        latestAssistantMessageId: assistants.at(-1)?.id ?? null,
+    };
+}

package/dist/src/web-ui/system-host-service.d.ts

@@ -1,15 +1,18 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
+import { type NativePermissionAccess } from "./system-host-setup/native-permission-route.js";
 export declare class WebSystemHostService {
     private readonly rootDir;
     private readonly store;
     private readonly connection;
     private readonly setup;
+    private readonly permissions;
+    private readonly nativePermissions;
     private readonly wss;
     private broker?;
     private starting?;
     private closing;
-    constructor(rootDir: string, connectionChanged?: () => void);
+    constructor(rootDir: string, connectionChanged?: () => void, nativePermissionAccess?: NativePermissionAccess);
     private ensureStarted;
     /** Native upgrade is separate from browser realtime and requires its own credential. */
     handleUpgrade(request: IncomingMessage, socket: Duplex, head: Buffer, listenHost?: string): boolean;

package/dist/src/web-ui/system-host-service.js

@@ -16,6 +16,8 @@ import { readHostReadiness } from "./system-host-setup/readiness.js";
 import { HostSetupRoutes, isHostSetupRoute, sendHostSetupInputError } from "./system-host-setup/routes.js";
 import { reportHostStartupFailure } from "./system-host-startup-diagnostic.js";
 import { withLocalMacSetup } from "./system-host-setup/local-setup-availability.js";
+import { HOST_PERMISSION_PATH, HostPermissionRoute } from "./system-host-setup/permission-route.js";
+import { NativeRuntimePermissionRoute } from "./system-host-setup/native-permission-route.js";
 function isSystemHostRoute(pathname) {
     if (pathname === "/web-api/runtime/system-host")
         return true;
@@ -26,6 +28,8 @@ export class WebSystemHostService {
     store;
     connection;
     setup;
+    permissions;
+    nativePermissions;
     wss = new WebSocketServer({
         noServer: true,
         maxPayload: HOST_WIRE_MAX_BYTES,
@@ -34,10 +38,12 @@ export class WebSystemHostService {
     broker;
     starting;
     closing = false;
-    constructor(rootDir, connectionChanged) {
+    constructor(rootDir, connectionChanged, nativePermissionAccess) {
         this.rootDir = rootDir;
         this.store = new HostPairingStore(rootDir);
         this.connection = new HostConnection(this.store, connectionChanged);
+        this.nativePermissions = new NativeRuntimePermissionRoute(nativePermissionAccess);
+        this.permissions = new HostPermissionRoute(this.connection, this.nativePermissions);
         this.setup = new HostSetupRoutes({
             store: this.store,
             readiness: () => readHostReadiness(this.connection.status()),
@@ -92,10 +98,14 @@ export class WebSystemHostService {
         this.wss.handleUpgrade(request, socket, head, (client) => this.connection.accept(client, token));
     }
     async handleHttp(request, response, pathname) {
-        if (!isSystemHostRoute(pathname) && !isHostSetupRoute(pathname))
+        if (!isSystemHostRoute(pathname) && !isHostSetupRoute(pathname) && pathname !== HOST_PERMISSION_PATH)
             return false;
         response.setHeader("cache-control", "no-store");
         try {
+            if (pathname === HOST_PERMISSION_PATH) {
+                await this.permissions.handle(request, response);
+                return true;
+            }
             if (isHostSetupRoute(pathname)) {
                 await this.setup.handle(request, response, pathname);
                 return true;
@@ -104,7 +114,8 @@ export class WebSystemHostService {
                 pathname === "/web-api/runtime/system-host") {
                 const status = this.connection.status();
                 const readiness = withLocalMacSetup(request, await readHostReadiness(status));
-                sendJson(response, 200, { ok: true, ...status, readiness });
+                const nativePermissions = await this.nativePermissions.status(request);
+                sendJson(response, 200, { ok: true, ...status, readiness, nativePermissions });
                 return true;
             }
             if (!acceptConfigMutationRequest(request, response))

package/dist/src/web-ui/system-host-setup/local-request-authority.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage } from "node:http";
+/** Native preparation controls this listener's Mac, never a remote browser's OS. */
+export declare function hasLocalRuntimeRequestAuthority(request: IncomingMessage): boolean;

package/dist/src/web-ui/system-host-setup/local-request-authority.js

@@ -0,0 +1,15 @@
+import { isNativeLoopbackAddress } from "../../computer-access/companion/native-address.js";
+import { hasLoopbackRequestAuthority } from "../request-authority.js";
+/** Native preparation controls this listener's Mac, never a remote browser's OS. */
+export function hasLocalRuntimeRequestAuthority(request) {
+    if (!hasLoopbackRequestAuthority(request))
+        return false;
+    if (!isNativeLoopbackAddress(request.socket.remoteAddress ?? ""))
+        return false;
+    if (!isNativeLoopbackAddress(request.socket.localAddress ?? ""))
+        return false;
+    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+    const authority = new URL(`${encrypted ? "https" : "http"}://${request.headers.host}`);
+    const port = Number(authority.port || (encrypted ? 443 : 80));
+    return port === request.socket.localPort;
+}

package/dist/src/web-ui/system-host-setup/local-setup-availability.js

@@ -1,7 +1,6 @@
 import { isIP } from "node:net";
 import { hostname } from "node:os";
-import { isNativeLoopbackAddress } from "../../computer-access/companion/native-address.js";
-import { hasLoopbackRequestAuthority } from "../request-authority.js";
+import { hasLocalRuntimeRequestAuthority } from "./local-request-authority.js";
 /** Local setup controls the Runtime's computer, never an inferred browser OS. */
 export function canSetUpLocalMac(request, readiness, platform = process.platform) {
     if (platform !== "darwin")
@@ -12,16 +11,7 @@ export function canSetUpLocalMac(request, readiness, platform = process.platform
         return false;
     if (readiness.ready)
         return false;
-    if (!hasLoopbackRequestAuthority(request))
-        return false;
-    if (!isNativeLoopbackAddress(request.socket.remoteAddress ?? ""))
-        return false;
-    if (!isNativeLoopbackAddress(request.socket.localAddress ?? ""))
-        return false;
-    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
-    const authority = new URL(`${encrypted ? "https" : "http"}://${request.headers.host}`);
-    const port = Number(authority.port || (encrypted ? 443 : 80));
-    return port === request.socket.localPort;
+    return hasLocalRuntimeRequestAuthority(request);
 }
 /** Use only after eligibility validates the loopback listener and authority. */
 export function localMacSetupRuntimeUrl(request) {

package/dist/src/web-ui/system-host-setup/native-permission-route.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type NativePermissionClient } from "../../computer-access/native-permission-contract.js";
+export type NativePermissionAccess = (environmentId: string) => NativePermissionClient | undefined;
+export declare function isNativeRuntimePermissionRequest(value: unknown): value is Record<string, unknown>;
+/** Browser management binds to a running environment owner; it never starts one. */
+export declare class NativeRuntimePermissionRoute {
+    private readonly clients;
+    private readonly platform;
+    constructor(clients?: NativePermissionAccess, platform?: NodeJS.Platform);
+    private unavailableReason;
+    private hasCurrentOwner;
+    status(request: IncomingMessage): Promise<{
+        available: boolean;
+        reason: string;
+        scope: "native_runtime";
+        environmentId: string;
+    } | {
+        available: true;
+        ownerId: string;
+        computerName: string;
+        executablePath: string;
+        scope: "native_runtime";
+        environmentId: string;
+    }>;
+    handle(request: IncomingMessage, response: ServerResponse, body: Record<string, unknown>): Promise<void>;
+}

package/dist/src/web-ui/system-host-setup/native-permission-route.js

@@ -0,0 +1,96 @@
+import { isHostRecord } from "../../computer-access/companion/protocol.js";
+import { isNativePermissionEnvironment, readNativePermissionInput } from "../../computer-access/native-permission-contract.js";
+import { sendJson } from "../local-runtime/http.js";
+import { hasLocalRuntimeRequestAuthority } from "./local-request-authority.js";
+export function isNativeRuntimePermissionRequest(value) {
+    return isHostRecord(value) && value.scope === "native_runtime";
+}
+/** Browser management binds to a running environment owner; it never starts one. */
+export class NativeRuntimePermissionRoute {
+    clients;
+    platform;
+    constructor(clients = () => undefined, platform = process.platform) {
+        this.clients = clients;
+        this.platform = platform;
+    }
+    unavailableReason(request) {
+        if (this.platform !== "darwin")
+            return "native_macos_unavailable";
+        if (!hasLocalRuntimeRequestAuthority(request))
+            return "local_browser_required";
+        return undefined;
+    }
+    hasCurrentOwner(environmentId, client, status, ownerId) {
+        if (!status.available)
+            return false;
+        if (status.ownerId !== ownerId)
+            return false;
+        return this.clients(environmentId) === client;
+    }
+    async status(request) {
+        const environmentId = new URL(request.url ?? "/", "http://localhost").searchParams.get("environment") ?? "";
+        const binding = { scope: "native_runtime", environmentId };
+        const unavailable = this.unavailableReason(request);
+        if (unavailable)
+            return { ...binding, available: false, reason: unavailable };
+        if (!isNativePermissionEnvironment(environmentId))
+            return { ...binding, available: false, reason: "runtime_not_started" };
+        const client = this.clients(environmentId);
+        if (!client)
+            return { ...binding, available: false, reason: "runtime_not_started" };
+        try {
+            const status = await client.status();
+            if (this.clients(environmentId) !== client)
+                return { ...binding, available: false, reason: "runtime_owner_unavailable" };
+            return { ...binding, ...status };
+        }
+        catch {
+            return { ...binding, available: false, reason: "runtime_owner_unavailable" };
+        }
+    }
+    async handle(request, response, body) {
+        const { scope, environmentId, ...fields } = body;
+        const input = readNativePermissionInput(fields);
+        if (scope !== "native_runtime" || !isNativePermissionEnvironment(environmentId) || !input) {
+            sendJson(response, 400, { ok: false, error: "macos_permissions_input_invalid" });
+            return;
+        }
+        const unavailable = this.unavailableReason(request);
+        if (unavailable) {
+            sendJson(response, 409, { ok: false, error: unavailable, message: "Prepare native permissions from this Mac's local ABot page." });
+            return;
+        }
+        const client = this.clients(environmentId);
+        if (!client) {
+            sendJson(response, 409, { ok: false, error: "runtime_not_started", message: "Start the selected Runtime environment, then check its native permissions." });
+            return;
+        }
+        try {
+            const status = await client.status();
+            if (response.destroyed)
+                return;
+            if (!this.hasCurrentOwner(environmentId, client, status, input.ownerId))
+                throw new Error("macos_permissions_owner_changed");
+            const result = await client.prepare(input);
+            if (response.destroyed)
+                return;
+            if (this.clients(environmentId) !== client)
+                throw new Error("macos_permissions_owner_changed");
+            sendJson(response, 200, { ok: true, scope, environmentId, ...result });
+        }
+        catch (error) {
+            if (response.destroyed)
+                return;
+            const code = error instanceof Error ? error.message : "macos_permissions_check_failed";
+            if (code === "macos_permissions_owner_changed") {
+                sendJson(response, 409, { ok: false, error: code, message: "The native Runtime owner changed. Refresh and check its permissions again." });
+                return;
+            }
+            if (code === "macos_permissions_busy") {
+                sendJson(response, 409, { ok: false, error: code, message: "A permission check or request is already in progress for this Runtime." });
+                return;
+            }
+            sendJson(response, 503, { ok: false, error: "macos_permissions_check_failed", message: "Native permission preparation did not complete. Check the running Runtime and Swift developer tools. Any macOS permission prompt already opened is not revoked." });
+        }
+    }
+}

package/dist/src/web-ui/system-host-setup/permission-route.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HostConnection } from "../../computer-access/companion/connection.js";
+import { type NativeRuntimePermissionRoute } from "./native-permission-route.js";
+export declare const HOST_PERMISSION_PATH = "/web-api/runtime/system-host/permissions";
+/** User-only setup endpoint; permission actions are never exposed as model tools. */
+export declare class HostPermissionRoute {
+    private readonly connection;
+    private readonly native?;
+    private busy;
+    constructor(connection: Pick<HostConnection, "status" | "execute">, native?: NativeRuntimePermissionRoute | undefined);
+    private hasCurrentMacBinding;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+}

package/dist/src/web-ui/system-host-setup/permission-route.js

@@ -0,0 +1,102 @@
+import { isHostIdentifier, isHostRecord } from "../../computer-access/companion/protocol.js";
+import { isMacPermissionAction, MACOS_PERMISSION_CAPABILITY, MACOS_PERMISSION_OPERATION, readMacPermissionResult, } from "../../computer-access/companion/permission-protocol.js";
+import { acceptConfigMutationRequest } from "../local-runtime/config-mutation-request.js";
+import { readBody, sendJson } from "../local-runtime/http.js";
+import { isNativeRuntimePermissionRequest } from "./native-permission-route.js";
+export const HOST_PERMISSION_PATH = "/web-api/runtime/system-host/permissions";
+function readPermissionInput(value) {
+    if (!isHostRecord(value))
+        return undefined;
+    const { hostId, connectionId, ...action } = value;
+    if (!isHostIdentifier(hostId))
+        return undefined;
+    if (!isHostIdentifier(connectionId))
+        return undefined;
+    if (!isMacPermissionAction(action))
+        return undefined;
+    return { hostId, connectionId, ...action };
+}
+/** User-only setup endpoint; permission actions are never exposed as model tools. */
+export class HostPermissionRoute {
+    connection;
+    native;
+    busy = false;
+    constructor(connection, native) {
+        this.connection = connection;
+        this.native = native;
+    }
+    hasCurrentMacBinding(input) {
+        const status = this.connection.status();
+        if (!status.connected)
+            return false;
+        if (status.identity?.os !== "macos")
+            return false;
+        if (status.hostId !== input.hostId)
+            return false;
+        return status.connectionId === input.connectionId;
+    }
+    async handle(request, response) {
+        if (request.method !== "POST") {
+            sendJson(response, 405, { ok: false, error: "method_not_allowed" });
+            return;
+        }
+        if (!acceptConfigMutationRequest(request, response))
+            return;
+        let input;
+        let body;
+        try {
+            const raw = await readBody(request, { maxBytes: 1024 });
+            body = JSON.parse(raw.toString());
+            input = readPermissionInput(body);
+        }
+        catch { /* malformed or oversized input is rejected before dispatch */ }
+        if (isNativeRuntimePermissionRequest(body) && this.native) {
+            await this.native.handle(request, response, body);
+            return;
+        }
+        if (!input) {
+            sendJson(response, 400, { ok: false, error: "macos_permissions_input_invalid" });
+            return;
+        }
+        if (!this.hasCurrentMacBinding(input)) {
+            sendJson(response, 409, { ok: false, error: "macos_permissions_host_changed", message: "Refresh Computer access and check the current Mac connection." });
+            return;
+        }
+        if (!this.connection.status().capabilities?.includes(MACOS_PERMISSION_CAPABILITY)) {
+            sendJson(response, 409, { ok: false, error: "macos_permissions_update_required", message: "Update this Mac connection before preparing its permissions." });
+            return;
+        }
+        if (this.busy) {
+            sendJson(response, 409, { ok: false, error: "macos_permissions_busy", message: "A permission check or request is already in progress." });
+            return;
+        }
+        this.busy = true;
+        const stop = new AbortController();
+        const timeout = setTimeout(() => stop.abort(), 50_000);
+        const disconnected = () => { if (!response.writableEnded)
+            stop.abort(); };
+        response.once("close", disconnected);
+        try {
+            const { hostId, connectionId, ...action } = input;
+            const result = await this.connection.execute({
+                hostId, connectionId, operation: MACOS_PERMISSION_OPERATION,
+                params: { target: "macos", ...action }, abortSignal: stop.signal,
+            });
+            if (!this.hasCurrentMacBinding(input)) {
+                sendJson(response, 409, { ok: false, error: "macos_permissions_host_changed", message: "The Mac connection changed. Check its permissions again." });
+                return;
+            }
+            const permissionResult = result.ok ? readMacPermissionResult(result.data) : undefined;
+            if (!permissionResult) {
+                sendJson(response, 503, { ok: false, error: "macos_permissions_check_failed", message: "Permission preparation did not complete. Check the Mac connection and Swift developer tools, then check again." });
+                return;
+            }
+            sendJson(response, 200, { ok: true, hostId, connectionId, scope: "companion", ...permissionResult });
+        }
+        finally {
+            clearTimeout(timeout);
+            response.removeListener("close", disconnected);
+            this.busy = false;
+        }
+    }
+}

package/docs/installation.md

@@ -159,19 +159,51 @@ loopback; a remote Runtime needs a local port forward. Direct connections to a
 remote network address are not supported. Mac desktop tools and Spark collection
 still require local Swift tools and the relevant macOS privacy permissions.
 
-**Spark permissions on macOS:** Computer access **Ready** confirms the connection;
-collection additionally needs Accessibility permission. Companion setup keeps a
+**Prepare macOS permissions before chatting:** The optional Computer setup step
+and **Home → Computer access** show separate preparation for desktop tools through
+the **Companion** and direct **SYSTEM commands through the active Runtime**.
+Connection status and operating-system permission status are separate; grants
+for one route do not establish access for the other. Check Screen Recording and
+Accessibility in each available route, then request its missing permission from
+that section and follow macOS settings. Checking does not capture a screen,
+read window content, type, or start Spark collection. Recheck after granting
+access; if macOS requires a restart, finish it before starting a conversation.
+
+Companion setup keeps a
 private copy of its Node executable at `~/.abot/host-companion/runtime/node` and
-uses that same path at sign-in, independently of NVM version paths. Start Spark
-collection to request consent, then authorize that executable in **System
+uses that same path at sign-in, independently of NVM version paths. Authorize
+the executable identified by the permission panel in **System
 Settings → Privacy & Security → Accessibility** (called **Device Control & Data
 Access** on some macOS versions). Use **+**, **Command–Shift–G**, and the path above
 if needed. The entry may be named `node`; verify the path before approving it.
-The collector checks approval for at most two minutes without reading content.
-After granting access, choose **Restart collection** in Home or Spark to check
-again. Setup reuses identical runtime bytes; replacing the runtime can require
-consent again. Screen recording and input permissions for other desktop tools
-are separate.
+Setup reuses identical runtime bytes; replacing the runtime can require consent
+again. Spark collection remains separately controlled and does not start when
+permissions are prepared.
+
+Native SYSTEM commands launched by ABot through Terminal or another application
+have that caller's permission identity, separate from the Companion. Their panel
+checks the process owning the selected Runtime environment, even when the Web
+server is attached to a different process. Inspect the displayed computer and
+executable, follow the macOS prompt for that route, and recheck after changing
+access. A replaced Runtime or a different environment requires a new check.
+If macOS asks to reopen Terminal or ABot, do that before starting a conversation.
+Permission preparation does not restart either process automatically.
+
+This Runtime preparation is available from a local Web connection on the Mac;
+unsupported or unavailable routes are shown explicitly. The CLI remains useful
+for setup before ABot starts or for diagnosis from the same Terminal/application:
+
+```bash
+abot host permissions
+abot host permissions --request screen-recording
+abot host permissions --request accessibility
+```
+
+The first command only checks. The request commands may show an operating-system
+prompt; approve the identity shown by macOS and check again afterward. They do
+not change Computer access pairing or send a model request. Application-specific
+Automation/Apple Events and protected-file access may still require separate
+consent for the applications or locations used by a later SYSTEM command.
 
 For Windows or Linux, download setup and run it in that computer's graphical
 login. Windows setup installs the companion and a private Node runtime; Linux

package/docs/plugins.md

@@ -307,10 +307,17 @@ explicitly, provide the required string `output` and boolean
 `producedNewInformation`, and place structured operation facts needed by later
 steps in `data`. JSON-safe here means primitives, plain objects, and dense
 arrays with finite numbers: no functions, symbols, accessors, cycles, class
-instances, or other non-plain prototypes. The complete normalized result must
-fit the Runtime's 256 KiB serialized producer boundary. A plugin must return an
-explicit bounded or paginated result, or an explicit failure; neither the
-plugin nor the Runtime may silently remove structured facts.
+instances, or other non-plain prototypes. Results use a 256 KiB serialized
+envelope boundary. A context-aware host exposes `context.resultBudget`; pass it
+to `deliverPluginTextResult(result, ["stdout", "stderr"], context.resultBudget)`
+to hand exact large text to the existing context manager. The helper keeps
+ordinary results unchanged. When needed, it declares `contextTextFields` on
+the original result; metadata and references still count toward the byte limit.
+Only `output`, `stdout`, and `stderr` are eligible string fields. The Runtime
+retains their full content and applies token admission and compaction before
+model invocation. This does not manage the plugin's output storage or RAM.
+Hosts without this contract and plugins that do not opt in retain their
+existing result limit. Neither plugin nor Runtime may silently remove facts.
 
 `ToolRegistry` adds the selected tool identity and creates the canonical
 `ToolExecutionResult`. The Runtime validates and persists that complete result,
@@ -322,6 +329,39 @@ they must not include secrets and they never act as instructions, new user
 intent, or proof that the whole request completed. See
 [tool-execution-result-evidence-contract.md](tool-execution-result-evidence-contract.md).
 
+### EXEC output storage
+
+EXEC captures stdout and stderr in private files under its injected `stateDir`.
+Pipe backpressure bounds queued capture data; the plugin does not accumulate a
+process's entire output in RAM while it runs. Disk writes use 64 KiB chunks, an
+I/O buffer size independent of the model context budget. A storage failure stops
+the producer and returns its process ID, status, cursor and committed byte
+counts; it never claims that incomplete output was successfully delivered.
+
+Delivery materializes the pending observation into the existing text-result
+contract. This still requires memory proportional to that observation; this
+contract is not streaming ingestion by the Runtime. The core owns token
+admission and compaction. It does not read EXEC file paths or manage its storage.
+
+Offsets advance only after the result fits the host's delivery contract. ASK
+state stores plugin-owned, session-bound disk receipts with range hashes, rather
+than copying the full text. Previously saved inline receipts remain readable.
+`outputRetentionMs` defaults to 604,800,000 (seven days) from capture closure,
+including unaccepted output and receipts saved for approval continuation. Reading,
+restoring or accepting a receipt does not extend retention. Active writers and
+readers prevent deletion until they finish. Interrupted and legacy captures
+without a closure timestamp expire using their last captured-file modification.
+
+The plugin sweeps existing storage when loaded and periodically while files
+remain (at most one hour between sweeps). A stopped runtime resumes cleanup when
+the plugin loads again. Expired output returns an explicit tool failure with the
+process ID; it never replays a command. Retention bounds age, not total disk usage.
+Preparation does not create storage directories, and cleanup belongs to EXEC.
+
+Concurrent terminal observations reserve one delivery before leaving the process
+transition. Rejected presentation releases the reservation without consuming any
+output. The same rule applies to restored terminal receipts.
+
 ## Filesystem Roots
 
 `environment.paths.agentWorkDir` is the configured primary work root. Plugins
@@ -406,13 +446,15 @@ searches use procfs; macOS searches inherit the verified current directory of
 an isolated Node child. File content searches use the held input descriptor on
 both platforms. A search fails closed when its authority cannot be established.
 
-All output and structured data must be bounded at the producer. The shared SDK
-reserves wrapper headroom by rejecting plugin results above 128 KiB before they
-reach the Runtime's 256 KiB canonical settlement boundary. Bounds include
-filesystem iteration, file/archive input, collection size, individual labels,
-and rendered text. A truncated success reports machine-readable truncation
-metadata; an operation that cannot produce a truthful bounded result fails
-explicitly.
+Plugins own resource bounds such as filesystem iteration, file/archive input,
+collection size, and buffered process output. Passing `context.resultBudget`
+lets the shared SDK use the Runtime's final envelope accounting, including
+canonical metadata and target references. Without it, the SDK measures the
+plugin object and the Runtime checks the canonical envelope separately.
+Declared context text is preserved separately from that byte
+accounting and remains subject to the complete model-input budget. An explicit
+truncated success reports machine-readable truncation metadata; an operation
+that cannot produce a truthful result fails explicitly.
 
 The bundled `exec` plugin provides trusted, non-interactive `/bin/bash` execution
 on Linux and macOS. Execute, wait and cancel each declare `approval="always"`: