@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/computer-access/companion/spark-notification-query.js

@@ -0,0 +1,62 @@
+const SPARK_NOTIFICATION_QUERY_KEYS = new Set([
+    "environment",
+    "spark",
+    "message",
+    "messageCreatedAt",
+    "request",
+]);
+function hasSingleAllowedSparkParameters(parameters) {
+    for (const key of parameters.keys()) {
+        if (!SPARK_NOTIFICATION_QUERY_KEYS.has(key))
+            return false;
+        if (parameters.getAll(key).length !== 1)
+            return false;
+    }
+    return true;
+}
+function isSparkNotificationReference(value) {
+    if (value === null)
+        return false;
+    if (value.trim() !== value)
+        return false;
+    if (!value.length)
+        return false;
+    if (value.length > 512)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function hasCanonicalSparkMessageTimestamp(value) {
+    if (value === null)
+        return false;
+    const timestamp = Number(value);
+    if (!Number.isSafeInteger(timestamp))
+        return false;
+    if (timestamp < 0)
+        return false;
+    return String(timestamp) === value;
+}
+function hasSparkMessageReference(parameters) {
+    return ["message", "messageCreatedAt", "request"].some((key) => parameters.has(key));
+}
+/** Validate the SPARK source link before the native host opens it. */
+export function hasBoundSparkNotificationQuery(url) {
+    if (url.pathname !== "/home")
+        return false;
+    const parameters = url.searchParams;
+    if (!hasSingleAllowedSparkParameters(parameters))
+        return false;
+    if (!isSparkNotificationReference(parameters.get("environment")))
+        return false;
+    if (parameters.get("spark") !== "1")
+        return false;
+    if (!hasSparkMessageReference(parameters))
+        return true;
+    if (!isSparkNotificationReference(parameters.get("message")))
+        return false;
+    if (!hasCanonicalSparkMessageTimestamp(parameters.get("messageCreatedAt")))
+        return false;
+    const request = parameters.get("request");
+    if (request === null)
+        return true;
+    return isSparkNotificationReference(request);
+}

package/dist/src/computer-access/companion/windows-store/connection-error.d.ts

@@ -0,0 +1,7 @@
+import type { NativeHostConnection } from "../native-state.js";
+export declare function hasMissingStoreUpgradeConnection(upgradeHostId: string | undefined, saved: NativeHostConnection | undefined): boolean;
+/** Fixed Store helper failure codes. Never serialize underlying errors or invitations. */
+export declare class MissingStoreConnectionError extends Error {
+    constructor();
+}
+export declare function serializeStoreConnectionError(error: unknown): string;

package/dist/src/computer-access/companion/windows-store/connection-error.js

@@ -0,0 +1,19 @@
+export function hasMissingStoreUpgradeConnection(upgradeHostId, saved) {
+    if (upgradeHostId === undefined)
+        return false;
+    return saved === undefined;
+}
+/** Fixed Store helper failure codes. Never serialize underlying errors or invitations. */
+export class MissingStoreConnectionError extends Error {
+    constructor() {
+        super("companion_local_pairing_missing");
+        this.name = "MissingStoreConnectionError";
+    }
+}
+export function serializeStoreConnectionError(error) {
+    return JSON.stringify({
+        error: error instanceof MissingStoreConnectionError
+            ? "companion_local_pairing_missing"
+            : "companion_request_failed",
+    });
+}

package/dist/src/computer-access/companion/windows-store/connection-link.d.ts

@@ -0,0 +1,13 @@
+export declare const STORE_CONNECTION_LINK_MAX_BYTES = 8192;
+export type StoreConnectionInvitation = Readonly<{
+    version: 1;
+    url: string;
+    code: string;
+    expiresAt: string;
+    companionRelease: number;
+    upgradeHostId?: string;
+}>;
+export declare function readStoreConnectionInvitation(value: unknown, now?: number): StoreConnectionInvitation;
+export declare function normalizeStoreConnectionOrigin(value: unknown): string;
+export declare function createStoreConnectionLink(invitation: StoreConnectionInvitation): string;
+export declare function parseStoreConnectionLink(link: string, now?: number): StoreConnectionInvitation;

package/dist/src/computer-access/companion/windows-store/connection-link.js

@@ -0,0 +1,109 @@
+import { isNativeLoopbackAddress, normalizeNativeRuntimeUrl } from "../native-address.js";
+import { isHostIdentifier, isHostRecord } from "../protocol.js";
+import { COMPANION_RELEASE_VERSION } from "../release-version.js";
+import { WINDOWS_COMPANION_STORE } from "./identity.js";
+export const STORE_CONNECTION_LINK_MAX_BYTES = 8_192;
+function invalidInvitation() {
+    // Incoming links contain a secret. Never include their text in an error.
+    return new Error("Invalid Companion connection invitation. Open Computer access in ABot and request a new connection.");
+}
+function isLoopbackInvitationOrigin(url) {
+    if (url.protocol !== "http:")
+        return false;
+    if (url.hostname === "localhost")
+        return true;
+    if (url.hostname.endsWith(".localhost"))
+        return true;
+    return isNativeLoopbackAddress(url.hostname);
+}
+export function readStoreConnectionInvitation(value, now = Date.now()) {
+    if (!isHostRecord(value))
+        throw invalidInvitation();
+    const fields = ["version", "url", "code", "expiresAt", "companionRelease", "upgradeHostId"];
+    if (Object.keys(value).some((key) => !fields.includes(key)))
+        throw invalidInvitation();
+    if (value.version !== 1)
+        throw invalidInvitation();
+    const origin = normalizeStoreConnectionOrigin(value.url);
+    if (typeof value.code !== "string" || !/^[A-Za-z0-9_-]{43}$/u.test(value.code))
+        throw invalidInvitation();
+    if (typeof value.expiresAt !== "string")
+        throw invalidInvitation();
+    const expiresAt = Date.parse(value.expiresAt);
+    if (!Number.isFinite(expiresAt))
+        throw invalidInvitation();
+    if (expiresAt <= now)
+        throw new Error("This connection invitation has expired. Click Connect in ABot again.");
+    if (!Number.isSafeInteger(value.companionRelease))
+        throw invalidInvitation();
+    if (Number(value.companionRelease) < 1)
+        throw invalidInvitation();
+    if (Number(value.companionRelease) > COMPANION_RELEASE_VERSION)
+        throw new Error("Update ABot AI Companion in Microsoft Store, then connect again.");
+    if (value.upgradeHostId !== undefined && !isHostIdentifier(value.upgradeHostId))
+        throw invalidInvitation();
+    return {
+        version: 1,
+        url: origin,
+        code: value.code,
+        expiresAt: new Date(expiresAt).toISOString(),
+        companionRelease: Number(value.companionRelease),
+        ...(value.upgradeHostId === undefined ? {} : { upgradeHostId: value.upgradeHostId }),
+    };
+}
+export function normalizeStoreConnectionOrigin(value) {
+    if (typeof value !== "string" || value.length > 4_096)
+        throw invalidInvitation();
+    let url;
+    try {
+        url = new URL(value);
+        normalizeNativeRuntimeUrl(value);
+    }
+    catch {
+        throw invalidInvitation();
+    }
+    if (!isLoopbackInvitationOrigin(url))
+        throw invalidInvitation();
+    if (/[\x00-\x20\x7f]/u.test(value))
+        throw invalidInvitation();
+    return url.origin;
+}
+export function createStoreConnectionLink(invitation) {
+    const data = readStoreConnectionInvitation(invitation);
+    const link = new URL(`${WINDOWS_COMPANION_STORE.protocol}//connect`);
+    link.searchParams.set("invitation", Buffer.from(JSON.stringify(data)).toString("base64url"));
+    if (Buffer.byteLength(link.href) > STORE_CONNECTION_LINK_MAX_BYTES)
+        throw invalidInvitation();
+    return link.href;
+}
+export function parseStoreConnectionLink(link, now = Date.now()) {
+    if (Buffer.byteLength(link) > STORE_CONNECTION_LINK_MAX_BYTES)
+        throw invalidInvitation();
+    let url;
+    try {
+        url = new URL(link);
+    }
+    catch {
+        throw invalidInvitation();
+    }
+    if (url.protocol !== WINDOWS_COMPANION_STORE.protocol)
+        throw invalidInvitation();
+    if (url.hostname !== "connect" || url.port || url.username || url.password || url.hash)
+        throw invalidInvitation();
+    if (url.pathname !== "" && url.pathname !== "/")
+        throw invalidInvitation();
+    const entries = [...url.searchParams];
+    if (entries.length !== 1 || entries[0][0] !== "invitation")
+        throw invalidInvitation();
+    const encoded = entries[0][1];
+    if (!/^[A-Za-z0-9_-]+$/u.test(encoded))
+        throw invalidInvitation();
+    let data;
+    try {
+        data = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    }
+    catch {
+        throw invalidInvitation();
+    }
+    return readStoreConnectionInvitation(data, now);
+}

package/dist/src/computer-access/companion/windows-store/identity.d.ts

@@ -0,0 +1,13 @@
+/** Store-assigned identity. Build tooling and the packaged Companion share it. */
+export declare const WINDOWS_COMPANION_STORE: Readonly<{
+    name: "ABot-AI.ABotAICompanion";
+    publisher: "CN=5497306F-2434-4801-8B3F-4B721B2A2606";
+    publisherDisplayName: "ABot-AI";
+    displayName: "ABot AI Companion";
+    familyName: "ABot-AI.ABotAICompanion_9b4v4r6by2e32";
+    applicationId: "Companion";
+    productId: "9PK2FDQQLQS9";
+    protocol: "abot-companion:";
+}>;
+export declare const WINDOWS_COMPANION_AUMID: string;
+export declare const WINDOWS_COMPANION_STORE_URL: string;

package/dist/src/computer-access/companion/windows-store/identity.js

@@ -0,0 +1,13 @@
+/** Store-assigned identity. Build tooling and the packaged Companion share it. */
+export const WINDOWS_COMPANION_STORE = Object.freeze({
+    name: "ABot-AI.ABotAICompanion",
+    publisher: "CN=5497306F-2434-4801-8B3F-4B721B2A2606",
+    publisherDisplayName: "ABot-AI",
+    displayName: "ABot AI Companion",
+    familyName: "ABot-AI.ABotAICompanion_9b4v4r6by2e32",
+    applicationId: "Companion",
+    productId: "9PK2FDQQLQS9",
+    protocol: "abot-companion:",
+});
+export const WINDOWS_COMPANION_AUMID = `${WINDOWS_COMPANION_STORE.familyName}!${WINDOWS_COMPANION_STORE.applicationId}`;
+export const WINDOWS_COMPANION_STORE_URL = `https://apps.microsoft.com/detail/${WINDOWS_COMPANION_STORE.productId}`;

package/dist/src/computer-access/companion/windows-store/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { HostCompanionLifecycle } from "../../../cli/host-companion-lifecycle.js";
+/** MSIX owns startup/protocol registration and updates; the shared CLI owns pairing. */
+export declare function createWindowsStoreLifecycle(options: Readonly<{
+    appUserModelId: string;
+}>): HostCompanionLifecycle;

package/dist/src/computer-access/companion/windows-store/lifecycle.js

@@ -0,0 +1,90 @@
+import { startDetachedCompanion, waitForNativeConnection, } from "../../../cli/host-companion-startup.js";
+import { existingOwnedRegistration, nativeAutostartFile, uninstallNativeAutostart, } from "../autostart.js";
+import { uninstallCompanionInstallLinks } from "../install-link-registration.js";
+import { readNativeCompanionBuildId } from "../native-build-identity.js";
+import { createNotificationSession } from "../native-notifications.js";
+import { stopOwnedNativeCompanion } from "../native-replacement.js";
+import { uninstallDesktopNotificationIdentity } from "../notification-installation.js";
+import { runNotificationProcess } from "../notification-process.js";
+import { powershellNotificationArguments, sendWindowsNotification, } from "../notification-windows.js";
+const STORE_NOTIFICATION_READINESS_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false)
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+try {
+  $Payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+  [void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
+  $Notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier([string]$Payload.appUserModelId)
+  [Console]::Out.Write([string]$Notifier.Setting)
+} catch {
+  [Console]::Error.WriteLine($_.Exception.GetBaseException().Message)
+  exit 1
+}
+`;
+function assertWindowsStoreStartup(startup) {
+    if (startup.platform !== "win32")
+        throw new Error("The Store companion requires Windows.");
+}
+function requireStoreApplicationIdentity(appUserModelId) {
+    if (!/^[A-Za-z0-9.-]+_[A-Za-z0-9]+![A-Za-z0-9.-]+$/u.test(appUserModelId))
+        throw new Error("Invalid Store companion application identity.");
+}
+async function hasWindowsStoreNotificationSupport(appUserModelId, signal) {
+    signal?.throwIfAborted();
+    try {
+        const setting = await runNotificationProcess({
+            file: "powershell.exe",
+            args: powershellNotificationArguments(STORE_NOTIFICATION_READINESS_SCRIPT),
+            input: JSON.stringify({ appUserModelId }),
+            signal,
+        });
+        signal?.throwIfAborted();
+        return setting.trim() === "Enabled";
+    }
+    catch {
+        signal?.throwIfAborted();
+        return false;
+    }
+}
+/** Called only after the Store connection dialog has obtained the user's consent. */
+async function retireOwnedLegacyRegistration(startup) {
+    await existingOwnedRegistration(nativeAutostartFile(startup));
+    await stopOwnedNativeCompanion(startup.stateDir);
+    await uninstallNativeAutostart(startup);
+    await uninstallCompanionInstallLinks(startup);
+    await uninstallDesktopNotificationIdentity(startup);
+}
+/** MSIX owns startup/protocol registration and updates; the shared CLI owns pairing. */
+export function createWindowsStoreLifecycle(options) {
+    requireStoreApplicationIdentity(options.appUserModelId);
+    return {
+        assertStartupSupported: assertWindowsStoreStartup,
+        async completeStartup(state, startup, hostId) {
+            assertWindowsStoreStartup(startup);
+            const buildId = await readNativeCompanionBuildId(startup.cliPath);
+            await retireOwnedLegacyRegistration(startup);
+            const connectedAfter = Date.now();
+            await startDetachedCompanion(startup);
+            if (!(await waitForNativeConnection(state, hostId, buildId, connectedAfter)))
+                throw new Error("The Store companion did not connect. The saved pairing is preserved; use Connect computer again to retry.");
+            console.log("ABot AI Companion connected.");
+        },
+        async uninstall(state, startup) {
+            assertWindowsStoreStartup(startup);
+            await state.remove();
+            await stopOwnedNativeCompanion(state.directory);
+            console.log("Host companion disconnected and its saved credential was removed. Remove ABot AI Companion in Windows Settings to uninstall the app.");
+        },
+        async createNotifications(runtimeUrl, signal) {
+            signal?.throwIfAborted();
+            const { appUserModelId } = options;
+            // The supervisor already refreshes readiness and renegotiates capabilities.
+            // A slow Windows notification probe must not consume the pairing startup deadline.
+            return createNotificationSession("windows", runtimeUrl, false, {
+                send: (notification, sendSignal) => sendWindowsNotification(notification, sendSignal, runNotificationProcess, appUserModelId),
+                close() { },
+            }, (refreshSignal) => hasWindowsStoreNotificationSupport(appUserModelId, refreshSignal));
+        },
+    };
+}

package/dist/src/computer-access/computer/macos-desktop.js

@@ -29,7 +29,7 @@ func capability(_ available: Bool,_ reason: String = "",supported: Bool = true)
   return result
 }
 func rectJSON(_ rect: CGRect) -> [String:Any] {
-  return ["x":rect.minX,"y":rect.minY,"width":rect.width,"height":rect.height]
+  return ["x":Double(rect.minX),"y":Double(rect.minY),"width":Double(rect.width),"height":Double(rect.height)]
 }
 func boundedText(_ value:String,_ limit:Int=256) -> String {
   var result="",length=0

package/dist/src/computer-access/computer/macos-input.js

@@ -28,12 +28,9 @@ final class CancellationFlag {
     }
   }
 }
-let keyCodes:[String:CGKeyCode] = ["a":0,"s":1,"d":2,"f":3,"h":4,"g":5,"z":6,"x":7,"c":8,"v":9,"b":11,"q":12,"w":13,"e":14,"r":15,"y":16,"t":17,"1":18,"2":19,"3":20,"4":21,"6":22,"5":23,"=":24,"9":25,"7":26,"-":27,"8":28,"0":29,"]":30,"o":31,"u":32,"[":33,"i":34,"p":35,"l":37,"j":38,"'":39,"k":40,";":41,"\\":42,",":43,"/":44,"n":45,"m":46,".":47,"\u{60}":50,"Enter":36,"Return":36,"Tab":48,"Space":49,"Backspace":51,"Delete":117,"Esc":53,"Escape":53,"Meta":55,"Super":55,"Command":55,"Shift":56,"Alt":58,"Option":58,"Ctrl":59,"Control":59,"F1":122,"F2":120,"F3":99,"F4":118,"F5":96,"F6":97,"F7":98,"F8":100,"F9":101,"F10":109,"F11":103,"F12":111,"Home":115,"End":119,"PageUp":116,"PageDown":121,"ArrowLeft":123,"ArrowRight":124,"ArrowDown":125,"ArrowUp":126]
+let keyCodes:[String:CGKeyCode] = ["a":0,"s":1,"d":2,"f":3,"h":4,"g":5,"z":6,"x":7,"c":8,"v":9,"b":11,"q":12,"w":13,"e":14,"r":15,"y":16,"t":17,"1":18,"2":19,"3":20,"4":21,"6":22,"5":23,"=":24,"9":25,"7":26,"-":27,"8":28,"0":29,"]":30,"o":31,"u":32,"[":33,"i":34,"p":35,"l":37,"j":38,"'":39,"k":40,";":41,"\\":42,",":43,"/":44,"n":45,"m":46,".":47,"\u{60}":50,"enter":36,"return":36,"tab":48,"space":49,"backspace":51,"delete":117,"esc":53,"escape":53,"meta":55,"super":55,"command":55,"cmd":55,"shift":56,"alt":58,"option":58,"ctrl":59,"control":59,"f1":122,"f2":120,"f3":99,"f4":118,"f5":96,"f6":97,"f7":98,"f8":100,"f9":101,"f10":109,"f11":103,"f12":111,"home":115,"end":119,"pageup":116,"pagedown":121,"arrowleft":123,"arrowright":124,"arrowdown":125,"arrowup":126]
 func nativeKey(_ value:String) throws -> CGKeyCode {
-  if let key=keyCodes[value] {
-    return key
-  }
-  if value.count==1,let key=keyCodes[value.lowercased()] {
+  if let key=keyCodes[value.lowercased()] {
     return key
   }
   throw NativeFailure("macos_key_unsupported")

package/dist/src/computer-access/computer/macos-permission-helper.d.ts

@@ -0,0 +1,4 @@
+/** Permission checks never enumerate windows, capture pixels, or inject input. */
+export declare const MACOS_PERMISSION_GATE: string;
+export declare const MACOS_PERMISSION_INPUT: string;
+export declare const MACOS_PERMISSION_HELPER: string;

package/dist/src/computer-access/computer/macos-permission-helper.js

@@ -0,0 +1,38 @@
+/** Permission checks never enumerate windows, capture pixels, or inject input. */
+export const MACOS_PERMISSION_GATE = String.raw `
+func prepareMacPermissions(
+  action: String,
+  screenGranted: () -> Bool,
+  accessibilityGranted: () -> Bool,
+  requestScreen: () -> Void,
+  requestAccessibility: () -> Void
+) -> [String: String] {
+  if action == "screen_recording" && !screenGranted() { requestScreen() }
+  if action == "accessibility" && !accessibilityGranted() { requestAccessibility() }
+  return ["screenRecording": screenGranted() ? "granted" : "required",
+    "accessibility": accessibilityGranted() ? "granted" : "required"]
+}
+`;
+export const MACOS_PERMISSION_INPUT = String.raw `
+let action = CommandLine.arguments.last ?? "check"
+guard ["check", "screen_recording", "accessibility"].contains(action) else { exit(2) }
+`;
+export const MACOS_PERMISSION_HELPER = String.raw `
+import Foundation
+import CoreGraphics
+import ApplicationServices
+${MACOS_PERMISSION_GATE}
+${MACOS_PERMISSION_INPUT}
+let result = prepareMacPermissions(
+  action: action,
+  screenGranted: { CGPreflightScreenCaptureAccess() },
+  accessibilityGranted: { AXIsProcessTrusted() },
+  requestScreen: { _ = CGRequestScreenCaptureAccess() },
+  requestAccessibility: {
+    let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true] as CFDictionary
+    _ = AXIsProcessTrustedWithOptions(options)
+  }
+)
+let data = try JSONSerialization.data(withJSONObject: result)
+print(String(data: data, encoding: .utf8)!)
+`;

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

@@ -22,7 +22,7 @@ export type SystemProcessResult = Readonly<{
     exitCode: number | null;
     stdout: string;
     stderr: string;
-    status: "completed" | "timeout" | "aborted" | "spawn_failed";
+    status: "completed" | "timeout" | "aborted" | "spawn_failed" | "output_failed";
     outputTruncated: boolean;
     spawnedProcess?: SystemSpawnObservation;
 }>;

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

@@ -1,3 +1,4 @@
 import { type ToolImplementation } from "../plugin-sdk/index.js";
 import { type SystemProcessRunner, type SystemTarget, type SystemTargetId } from "./contracts.js";
-export declare function createSystemHandlers(run?: SystemProcessRunner, resolveTarget?: (id: SystemTargetId) => Promise<SystemTarget>): Record<string, ToolImplementation>;
+import type { SystemCommandOutputFactory } from "./command-output.js";
+export declare function createSystemHandlers(run?: SystemProcessRunner, resolveTarget?: (id: SystemTargetId) => Promise<SystemTarget>, commandOutput?: SystemCommandOutputFactory): Record<string, ToolImplementation>;

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

@@ -30,7 +30,7 @@ function withSystemOperationErrors(operation) {
         }
     };
 }
-export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run)) {
+export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run), commandOutput) {
     const targets = async () => {
         const observation = await observeSystemTargets(run);
         return successResult({
@@ -43,12 +43,16 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
     };
     const command = async (params, context) => {
         const target = await resolveTarget(readSystemTargetId(params.target));
+        const output = commandOutput?.(context);
         const result = await executeSystemCommand({
             target,
             params,
             run,
+            ...(output ? { runCommand: output.run } : {}),
             ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
         });
+        if (output)
+            return output.present(target, result);
         return systemProcessResult(target, result, "command_process_completion");
     };
     const applications = async (params) => {

package/dist/src/computer-access/host-observation.d.ts

@@ -7,7 +7,7 @@ export type SystemHostFacts = Readonly<{
 export declare function readSystemHostFacts(): SystemHostFacts;
 export declare function isWslHostRuntime(facts: SystemHostFacts): boolean;
 export declare function observeSystemHost(facts?: SystemHostFacts): {
-    readonly runtimeOs: "unsupported" | SystemTargetId;
+    readonly runtimeOs: SystemTargetId | "unsupported";
     readonly kernelRelease: string;
     readonly environment: "container";
     readonly inferredHostOs: "unknown";
@@ -15,10 +15,10 @@ export declare function observeSystemHost(facts?: SystemHostFacts): {
     readonly windowsExecutionRequiresProbe: false;
     readonly guiSessionStatus: "not_checked";
 } | {
-    readonly runtimeOs: "unsupported" | SystemTargetId;
+    readonly runtimeOs: SystemTargetId | "unsupported";
     readonly kernelRelease: string;
     readonly environment: "wsl_guest" | "not_identified_as_wsl";
-    readonly inferredHostOs: "unsupported" | SystemTargetId;
+    readonly inferredHostOs: SystemTargetId | "unsupported";
     readonly hostInferenceSource: "wsl_kernel_signature" | "runtime_platform_only";
     readonly windowsExecutionRequiresProbe: boolean;
     readonly guiSessionStatus: "not_checked";

package/dist/src/computer-access/native-permission-contract.d.ts

@@ -0,0 +1,23 @@
+import { type MacPermissionAction, type MacPermissionResult } from "./companion/permission-protocol.js";
+export type NativePermissionStatus = Readonly<{
+    available: true;
+    ownerId: string;
+    computerName: string;
+    executablePath: string;
+}> | Readonly<{
+    available: false;
+    reason: string;
+}>;
+export type NativePermissionInput = MacPermissionAction & Readonly<{
+    ownerId: string;
+}>;
+export type NativePermissionResult = MacPermissionResult & Readonly<{
+    ownerId: string;
+}>;
+export type NativePermissionClient = Readonly<{
+    status(): Promise<NativePermissionStatus>;
+    prepare(input: NativePermissionInput): Promise<NativePermissionResult>;
+}>;
+export declare function readNativePermissionInput(value: unknown): NativePermissionInput | undefined;
+export declare function isNativePermissionEnvironment(value: unknown): value is string;
+export declare function isNativePermissionStatus(value: unknown): value is NativePermissionStatus;

package/dist/src/computer-access/native-permission-contract.js

@@ -0,0 +1,38 @@
+import { isHostIdentifier, isHostRecord } from "./companion/protocol.js";
+import { isMacPermissionAction } from "./companion/permission-protocol.js";
+export function readNativePermissionInput(value) {
+    if (!isHostRecord(value))
+        return undefined;
+    const { ownerId, ...action } = value;
+    if (!isHostIdentifier(ownerId))
+        return undefined;
+    if (!isMacPermissionAction(action))
+        return undefined;
+    return { ownerId, ...action };
+}
+export function isNativePermissionEnvironment(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.trim() || value.length > 256)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+export function isNativePermissionStatus(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (value.available === false)
+        return typeof value.reason === "string" && value.reason.length <= 256;
+    if (value.available !== true)
+        return false;
+    if (!isHostIdentifier(value.ownerId))
+        return false;
+    if (typeof value.computerName !== "string" || value.computerName.length > 256)
+        return false;
+    if (!value.computerName.trim() || /[\u0000-\u001f\u007f]/u.test(value.computerName))
+        return false;
+    if (typeof value.executablePath !== "string" || value.executablePath.length > 4096)
+        return false;
+    if (/[\u0000-\u001f\u007f]/u.test(value.executablePath))
+        return false;
+    return value.executablePath.startsWith("/");
+}

package/dist/src/computer-access/process-capture.d.ts

@@ -0,0 +1,6 @@
+import type { Readable } from "node:stream";
+/** Optional local output sink. Its owner handles storage, retention and delivery. */
+export type SystemProcessCapture = Readonly<{
+    attach(stdout: Readable, stderr: Readable, onFailure: () => void): void;
+    end(): void;
+}>;

package/dist/src/computer-access/process-capture.js

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

package/dist/src/computer-access/process-result.d.ts

@@ -2,3 +2,5 @@ import { type ToolImplementationOutput } from "../plugin-sdk/index.js";
 import type { SystemApplication, SystemProcessResult, SystemTarget } from "./contracts.js";
 export type SystemEvidenceScope = "command_process_completion" | "launch_request_dispatch";
 export declare function systemProcessResult(target: SystemTarget, result: SystemProcessResult, evidenceScope: SystemEvidenceScope, application?: SystemApplication): ToolImplementationOutput;
+/** Unmeasured receipt for invocation-aware local delivery through the SDK. */
+export declare function buildSystemProcessResult(target: SystemTarget, result: SystemProcessResult, evidenceScope: SystemEvidenceScope, application?: SystemApplication): ToolImplementationOutput;

package/dist/src/computer-access/process-result.js

@@ -1,4 +1,4 @@
-import { failureResult, successResult, } from "../plugin-sdk/index.js";
+import { enforcePluginResultByteBudget, } from "../plugin-sdk/index.js";
 const STREAM_EXCERPT_CHARS = 2_000;
 const IDENTITY_EXCERPT_CHARS = 512;
 const LEGACY_EVIDENCE_LABELS = {
@@ -6,6 +6,10 @@ const LEGACY_EVIDENCE_LABELS = {
     launch_request_dispatch: "application launch request dispatch",
 };
 export function systemProcessResult(target, result, evidenceScope, application) {
+    return enforcePluginResultByteBudget(buildSystemProcessResult(target, result, evidenceScope, application));
+}
+/** Unmeasured receipt for invocation-aware local delivery through the SDK. */
+export function buildSystemProcessResult(target, result, evidenceScope, application) {
     const stdoutOmittedChars = Math.max(0, result.stdout.length - STREAM_EXCERPT_CHARS);
     const stderrOmittedChars = Math.max(0, result.stderr.length - STREAM_EXCERPT_CHARS);
     const data = {
@@ -46,20 +50,24 @@ export function systemProcessResult(target, result, evidenceScope, application)
         `Summary omitted characters: stdout=${stdoutOmittedChars}, stderr=${stderrOmittedChars}. Raw stream capture truncated: ${result.outputTruncated}.`,
     ].join("\n");
     if (hasSuccessfulSystemObservation(result)) {
-        return successResult({
+        return {
+            ok: true,
+            producedNewInformation: true,
             output,
             stdout: result.stdout,
             stderr: result.stderr,
             exitCode: 0,
             data,
-        });
+        };
     }
     const errorCode = result.status === "completed"
         ? "system_command_failed"
         : `system_${result.status}`;
-    return failureResult({
+    return {
+        ok: false,
+        producedNewInformation: false,
         errorCode,
-        message: hasUncertainDescendantState(result)
+        error: hasUncertainDescendantState(result)
             ? "System command observation stopped. External or detached descendants may remain; inspect the target before retrying."
             : "The target did not report successful command completion.",
         output,
@@ -67,7 +75,7 @@ export function systemProcessResult(target, result, evidenceScope, application)
         stderr: result.stderr,
         ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
         data,
-    });
+    };
 }
 function hasSuccessfulSystemObservation(result) {
     if (result.status !== "completed")

package/dist/src/computer-access/process-runner.d.ts

@@ -1,3 +1,4 @@
+import type { SystemProcessCapture } from "./process-capture.js";
 import type { SystemProcessInput, SystemProcessResult } from "./contracts.js";
 /** Bounded process observation; exit zero proves command completion, not effects. */
-export declare function runSystemProcess(input: SystemProcessInput): Promise<SystemProcessResult>;
+export declare function runSystemProcess(input: SystemProcessInput, capture?: SystemProcessCapture): Promise<SystemProcessResult>;