@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/{plugins/system/source → src/computer-access}/companion/connection.d.ts

@@ -1,15 +1,21 @@
 import WebSocket from "ws";
-import { type ToolImplementationOutput } from "../../../../src/plugin-sdk/index.js";
+import { type ToolImplementationOutput } from "../../plugin-sdk/index.js";
 import { type HostOperation, type HostStatus } from "./protocol.js";
 import { HostPairingStore } from "./pairing-store.js";
+import { HostObservationConnection } from "./observation-connection.js";
 export declare class HostConnection {
     private readonly store;
+    private readonly connectionChanged;
+    readonly observations: HostObservationConnection;
     private client?;
     private connectionId?;
+    private observedCompanion?;
+    private capabilities;
     private readonly sockets;
     private readonly pending;
-    constructor(store: HostPairingStore);
+    constructor(store: HostPairingStore, connectionChanged?: () => void);
     status(): HostStatus;
+    private releaseForPairedHost;
     accept(client: WebSocket, token: string): void;
     private acceptHello;
     private acceptResult;

package/dist/{plugins/system/source → src/computer-access}/companion/connection.js

@@ -1,9 +1,12 @@
 import { randomUUID } from "node:crypto";
 import WebSocket from "ws";
-import { failureResult, } from "../../../../src/plugin-sdk/index.js";
+import { failureResult, } from "../../plugin-sdk/index.js";
 import { attachHostEvidence } from "../host-evidence.js";
 import { hasMatchingHostIdentity, isHostIdentifier, isHostIdentity, isHostRecord, isHostToolResult, } from "./protocol.js";
 import { monitorHostLiveness } from "./liveness.js";
+import { HostObservationConnection } from "./observation-connection.js";
+import { OBSERVATION_CAPABILITY } from "./observation-protocol.js";
+import { companionReleaseStatus } from "./release-version.js";
 function unavailable(message) {
     return failureResult({ errorCode: "system_host_unavailable", message });
 }
@@ -16,12 +19,17 @@ function uncertain() {
 }
 export class HostConnection {
     store;
+    connectionChanged;
+    observations = new HostObservationConnection();
     client;
     connectionId;
+    observedCompanion;
+    capabilities = [];
     sockets = new Set();
     pending = new Map();
-    constructor(store) {
+    constructor(store, connectionChanged = () => { }) {
         this.store = store;
+        this.connectionChanged = connectionChanged;
     }
     status() {
         const host = this.store.host();
@@ -31,12 +39,23 @@ export class HostConnection {
             paired: true,
             hostId: host.hostId,
             identity: host.identity,
+            ...this.releaseForPairedHost(host.hostId),
         };
         if (!this.connectionId)
             return { ...identity, connected: false };
         if (this.client?.readyState !== WebSocket.OPEN)
             return { ...identity, connected: false };
-        return { ...identity, connected: true, connectionId: this.connectionId };
+        return {
+            ...identity,
+            connected: true,
+            connectionId: this.connectionId,
+            capabilities: this.capabilities,
+        };
+    }
+    releaseForPairedHost(hostId) {
+        if (this.observedCompanion?.hostId !== hostId)
+            return {};
+        return { companion: { ...this.observedCompanion.release } };
     }
     accept(client, token) {
         this.sockets.add(client);
@@ -49,10 +68,12 @@ export class HostConnection {
             this.sockets.delete(client);
             if (this.client !== client)
                 return;
+            this.observations.disconnect();
             this.client = undefined;
             this.connectionId = undefined;
             for (const operation of this.pending.values())
                 operation.finish(uncertain());
+            this.connectionChanged();
         });
         client.on("message", (bytes, binary) => {
             try {
@@ -67,6 +88,10 @@ export class HostConnection {
                         clearTimeout(helloDeadline);
                     return;
                 }
+                if (message.type === "observation_event") {
+                    this.observations.receive(client, message);
+                    return;
+                }
                 this.acceptResult(client, message);
             }
             catch {
@@ -84,6 +109,7 @@ export class HostConnection {
         const authorization = this.store.authenticate(token);
         if (authorization === "pairing") {
             const grant = this.store.consume(token, message.identity);
+            this.connectionChanged();
             client.send(JSON.stringify({ type: "paired", ...grant }));
             client.close(1000, "reconnect_with_credential");
             return false;
@@ -101,7 +127,17 @@ export class HostConnection {
         }
         this.client = client;
         this.connectionId = randomUUID();
+        this.observedCompanion = {
+            hostId: host.hostId,
+            release: companionReleaseStatus(message.companionVersion),
+        };
+        this.capabilities = Array.isArray(message.capabilities)
+            ? message.capabilities.filter((value) => typeof value === "string").slice(0, 16)
+            : [];
+        this.observations.attach(client, host.hostId, Array.isArray(message.capabilities) &&
+            message.capabilities.includes(OBSERVATION_CAPABILITY));
         client.send(JSON.stringify({ type: "ready", hostId: host.hostId }));
+        this.connectionChanged();
         return true;
     }
     acceptResult(client, message) {
@@ -160,14 +196,17 @@ export class HostConnection {
         });
     }
     disconnect() {
+        this.observations.disconnect();
         for (const operation of this.pending.values())
             operation.finish(uncertain());
         this.client = undefined;
         this.connectionId = undefined;
         for (const socket of this.sockets)
             socket.close(1008, "host_disconnected");
+        this.connectionChanged();
     }
     close() {
+        this.observations.disconnect();
         for (const operation of this.pending.values())
             operation.finish(uncertain());
         this.client = undefined;
@@ -178,5 +217,6 @@ export class HostConnection {
             deadline.unref();
             socket.once("close", () => clearTimeout(deadline));
         }
+        this.connectionChanged();
     }
 }

package/dist/src/computer-access/companion/local-installation.d.ts

@@ -0,0 +1,13 @@
+import { type LocalSetupProcessDependencies } from "./local-setup-process.js";
+export { LocalCompanionSetupError } from "./local-setup-process.js";
+export type LocalCompanionInstallationDependencies = LocalSetupProcessDependencies & Readonly<{
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+}>;
+/** Install trusted server-owned bytes and reuse the existing native setup entry. */
+export declare function installLocalMacCompanion(input: Readonly<{
+    bundle: Buffer;
+    url: string;
+    code: string;
+    upgradeHostId?: string;
+}>, dependencies?: LocalCompanionInstallationDependencies): Promise<void>;

package/dist/src/computer-access/companion/local-installation.js

@@ -0,0 +1,142 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { assertPrivateRuntimeAccess } from "../../runtime/local-host/private-access.js";
+import { ensurePrivateRuntimeDirectory } from "../../runtime/local-host/private-directory.js";
+import { LocalCompanionSetupError, runLocalCompanionSetup, } from "./local-setup-process.js";
+export { LocalCompanionSetupError } from "./local-setup-process.js";
+function isMissingCachePath(error) {
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    return error.code === "ENOENT";
+}
+function isExistingCachePath(error) {
+    if (!error || typeof error !== "object" || !("code" in error))
+        return false;
+    return error.code === "EEXIST";
+}
+function hasOwnedInstallationAncestor(stat) {
+    if (!stat.isDirectory())
+        return false;
+    if (stat.isSymbolicLink())
+        return false;
+    if (stat.uid !== process.getuid?.())
+        return false;
+    return (stat.mode & 0o022) === 0;
+}
+async function requireOwnedInstallationAncestor(path) {
+    if (!hasOwnedInstallationAncestor(await lstat(path)))
+        throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+}
+async function prepareInstallationDirectory(homeDir) {
+    await requireOwnedInstallationAncestor(homeDir);
+    let directory = homeDir;
+    for (const segment of ["Library", "Application Support", "ABot"]) {
+        directory = join(directory, segment);
+        await mkdir(directory, { mode: 0o700 }).catch((error) => {
+            if (!isExistingCachePath(error))
+                throw error;
+        });
+        await requireOwnedInstallationAncestor(directory);
+    }
+    directory = join(directory, "HostCompanion");
+    await ensurePrivateRuntimeDirectory(directory);
+    return directory;
+}
+function bundleDigest(bundle) {
+    return createHash("sha256").update(bundle).digest("hex");
+}
+function hasRegularSingleLinkBundle(stat, expectedSize) {
+    if (!stat.isFile())
+        return false;
+    if (stat.nlink !== 1)
+        return false;
+    return stat.size === expectedSize;
+}
+function hasSameBundleIdentity(left, right) {
+    if (left.dev !== right.dev)
+        return false;
+    return left.ino === right.ino;
+}
+async function verifyCachedBundle(path, bundle, digest) {
+    const identity = await lstat(path).catch((error) => {
+        if (isMissingCachePath(error))
+            return undefined;
+        throw error;
+    });
+    if (!identity)
+        return false;
+    if (!hasRegularSingleLinkBundle(identity, bundle.length))
+        throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+    await assertPrivateRuntimeAccess(path, identity, "host_local_setup_unsafe_cache");
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat();
+        if (!hasSameBundleIdentity(identity, opened))
+            throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+        if (!hasRegularSingleLinkBundle(opened, bundle.length))
+            throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+        await assertPrivateRuntimeAccess(path, opened, "host_local_setup_unsafe_cache");
+        if (bundleDigest(await handle.readFile()) !== digest)
+            throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+        if (!hasSameBundleIdentity(opened, await lstat(path)))
+            throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+        return true;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function publishImmutableBundle(directory, path, bundle) {
+    const staged = join(directory, ".companion-" + randomUUID() + ".tmp");
+    const handle = await open(staged, constants.O_WRONLY |
+        constants.O_CREAT |
+        constants.O_EXCL |
+        constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(bundle);
+        await handle.sync();
+        await handle.close();
+        await link(staged, path).catch((error) => {
+            if (!isExistingCachePath(error))
+                throw error;
+        });
+    }
+    finally {
+        await handle.close();
+        await unlink(staged);
+    }
+}
+async function installVerifiedBundle(homeDir, bundle) {
+    try {
+        const directory = await prepareInstallationDirectory(homeDir);
+        const digest = bundleDigest(bundle);
+        const path = join(directory, "companion-" + digest + ".mjs");
+        if (!(await verifyCachedBundle(path, bundle, digest)))
+            await publishImmutableBundle(directory, path, bundle);
+        await ensurePrivateRuntimeDirectory(directory);
+        if (!(await verifyCachedBundle(path, bundle, digest)))
+            throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+        return path;
+    }
+    catch {
+        throw new LocalCompanionSetupError("host_local_setup_unsafe_cache");
+    }
+}
+/** Install trusted server-owned bytes and reuse the existing native setup entry. */
+export async function installLocalMacCompanion(input, dependencies = {}) {
+    if ((dependencies.platform ?? process.platform) !== "darwin")
+        throw new LocalCompanionSetupError("host_local_setup_unavailable");
+    const homeDir = dependencies.homeDir ?? homedir();
+    const bundlePath = await installVerifiedBundle(homeDir, input.bundle);
+    const payload = JSON.stringify({
+        url: input.url,
+        code: input.code,
+        ...(input.upgradeHostId === undefined
+            ? {}
+            : { upgradeHostId: input.upgradeHostId }),
+    });
+    await runLocalCompanionSetup({ bundlePath, homeDir, payload }, dependencies);
+}

package/dist/src/computer-access/companion/local-setup-process.d.ts

@@ -0,0 +1,18 @@
+import { spawn } from "node:child_process";
+export type LocalCompanionSetupErrorCode = "host_local_setup_unavailable" | "host_local_setup_unsafe_cache" | "host_local_setup_timeout" | "host_local_setup_failed";
+export declare class LocalCompanionSetupError extends Error {
+    readonly code: LocalCompanionSetupErrorCode;
+    constructor(code: LocalCompanionSetupErrorCode, message?: string);
+}
+export type LocalSetupProcessDependencies = Readonly<{
+    spawn?: typeof spawn;
+    timeoutMs?: number;
+    terminationTimeoutMs?: number;
+    killProcessGroup?: (pid: number) => void;
+}>;
+/** Only the bundled setup entry sees pairing data; the parent never logs output. */
+export declare function runLocalCompanionSetup(input: Readonly<{
+    bundlePath: string;
+    homeDir: string;
+    payload: string;
+}>, dependencies: LocalSetupProcessDependencies): Promise<void>;

package/dist/src/computer-access/companion/local-setup-process.js

@@ -0,0 +1,127 @@
+import { spawn } from "node:child_process";
+import { NATIVE_RUNTIME_INSTALLATION_FAILURE } from "./native-runtime-installation.js";
+const SETUP_MESSAGES = {
+    host_local_setup_unavailable: "Local computer setup is available only on a Mac running ABot.",
+    host_local_setup_unsafe_cache: "The companion installation could not be verified. Check its private installation folder before trying again.",
+    host_local_setup_timeout: "Computer setup timed out. Check the computer connection in ABot Settings before trying again.",
+    host_local_setup_failed: "Computer setup did not complete. Check the computer connection in ABot Settings before trying again.",
+};
+const KNOWN_SETUP_FAILURES = new Set([
+    NATIVE_RUNTIME_INSTALLATION_FAILURE,
+    "A Runtime is already paired. Use 'abot host disconnect' before pairing another.",
+    "The paired computer connection is missing. Reconnect from ABot Settings.",
+    "This upgrade belongs to a different paired computer connection.",
+    "Pairing did not complete. Check ABot Settings and use a fresh pairing code.",
+    "The updated host companion did not connect. The saved pairing is preserved; run setup again to retry.",
+]);
+export class LocalCompanionSetupError extends Error {
+    code;
+    constructor(code, message = SETUP_MESSAGES[code]) {
+        super(message);
+        this.code = code;
+        this.name = "LocalCompanionSetupError";
+    }
+}
+function safeSetupFailure(stderr) {
+    const finalLine = stderr.trim().split(/\r?\n/u).at(-1);
+    const knownMessage = finalLine && KNOWN_SETUP_FAILURES.has(finalLine);
+    return new LocalCompanionSetupError("host_local_setup_failed", knownMessage ? finalLine : undefined);
+}
+function terminateSetupProcessGroup(child, dependencies) {
+    if (child.pid === undefined) {
+        child.kill("SIGKILL");
+        return;
+    }
+    const killGroup = dependencies.killProcessGroup ??
+        ((pid) => {
+            process.kill(-pid, "SIGKILL");
+        });
+    try {
+        killGroup(child.pid);
+    }
+    catch {
+        child.kill("SIGKILL");
+    }
+}
+/** Only the bundled setup entry sees pairing data; the parent never logs output. */
+export async function runLocalCompanionSetup(input, dependencies) {
+    const launch = dependencies.spawn ?? spawn;
+    let child;
+    try {
+        child = launch(process.execPath, [input.bundlePath, "setup"], {
+            cwd: input.homeDir,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            detached: true,
+        });
+    }
+    catch {
+        throw new LocalCompanionSetupError("host_local_setup_failed");
+    }
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        let outputBytes = 0;
+        let stderr = "";
+        let stoppingError;
+        let terminationDeadline;
+        const deadline = setTimeout(() => stop(new LocalCompanionSetupError("host_local_setup_timeout")), dependencies.timeoutMs ?? 120_000);
+        function finish(error) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(deadline);
+            clearTimeout(terminationDeadline);
+            stderr = "";
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        }
+        function stop(error) {
+            if (settled)
+                return;
+            if (stoppingError)
+                return;
+            stoppingError = error;
+            clearTimeout(deadline);
+            stderr = "";
+            terminationDeadline = setTimeout(() => finish(error), dependencies.terminationTimeoutMs ?? 2_000);
+            terminateSetupProcessGroup(child, dependencies);
+            child.stdin.destroy();
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }
+        function acceptOutput(chunk) {
+            if (settled)
+                return false;
+            if (stoppingError)
+                return false;
+            outputBytes += chunk.length;
+            if (outputBytes <= 65_536)
+                return true;
+            stop(new LocalCompanionSetupError("host_local_setup_failed"));
+            return false;
+        }
+        child.stdout.on("data", (chunk) => acceptOutput(chunk));
+        child.stderr.on("data", (chunk) => {
+            if (!acceptOutput(chunk))
+                return;
+            stderr += chunk.toString("utf8");
+        });
+        child.once("error", () => stop(new LocalCompanionSetupError("host_local_setup_failed")));
+        child.once("close", (code) => {
+            if (stoppingError) {
+                finish(stoppingError);
+                return;
+            }
+            if (code === 0) {
+                finish();
+                return;
+            }
+            finish(safeSetupFailure(stderr));
+        });
+        child.stdin.on("error", () => stop(new LocalCompanionSetupError("host_local_setup_failed")));
+        child.stdin.end(input.payload);
+    });
+}

package/dist/{plugins/system/source → src/computer-access}/companion/native-address.d.ts

@@ -5,8 +5,8 @@ export type NativeAddress = Readonly<{
 export type NativeHostResolver = (hostname: string) => Promise<readonly NativeAddress[]>;
 export declare function isNativeLoopbackAddress(value: string): boolean;
 export declare function normalizeNativeRuntimeUrl(value: string): string;
-/** Resolve once, reject mixed/public answers, then pin this exact address at connect. */
+/** Resolve once, reject mixed/public answers, then pin only these addresses at connect. */
 export declare function resolveNativeRuntimeAddress(value: string, resolveHost?: NativeHostResolver): Promise<Readonly<{
     url: string;
-    address: NativeAddress;
+    addresses: readonly NativeAddress[];
 }>>;

package/dist/{plugins/system/source → src/computer-access}/companion/native-address.js

@@ -24,18 +24,35 @@ export function normalizeNativeRuntimeUrl(value) {
     url.protocol = ["https:", "wss:"].includes(url.protocol) ? "wss:" : "ws:";
     return url.origin;
 }
-/** Resolve once, reject mixed/public answers, then pin this exact address at connect. */
+function isLocalhostName(hostname) {
+    if (hostname === "localhost")
+        return true;
+    return hostname.endsWith(".localhost");
+}
+function hasValidLoopbackFamily(candidate) {
+    if (isIP(candidate.address) !== candidate.family)
+        return false;
+    return isNativeLoopbackAddress(candidate.address);
+}
+async function nativeAddressCandidates(hostname, resolveHost) {
+    if (isLocalhostName(hostname))
+        return [{ address: "127.0.0.1", family: 4 }, { address: "::1", family: 6 }];
+    const family = isIP(hostname);
+    if (family)
+        return [{ address: hostname, family }];
+    return resolveHost(hostname);
+}
+/** Resolve once, reject mixed/public answers, then pin only these addresses at connect. */
 export async function resolveNativeRuntimeAddress(value, resolveHost = (hostname) => lookupHost(hostname, { all: true })) {
     const origin = normalizeNativeRuntimeUrl(value);
     const url = new URL(origin);
-    const hostname = url.hostname.replace(/^\[|\]$/gu, "").toLowerCase();
-    const addresses = hostname === "localhost" || hostname.endsWith(".localhost")
-        ? [{ address: "127.0.0.1", family: 4 }]
-        : await resolveHost(hostname);
+    const hostname = url.hostname.replace(/^\[|\]$/gu, "").toLowerCase().replace(/\.$/u, "");
+    const answers = await nativeAddressCandidates(hostname, resolveHost);
+    const addresses = Object.freeze(answers.map(({ address, family }) => Object.freeze({ address, family })));
     if (addresses.length === 0)
         throw new Error("The local Runtime address did not resolve.");
-    if (!addresses.every(({ address }) => isNativeLoopbackAddress(address)))
+    if (!addresses.every(hasValidLoopbackFamily))
         throw new Error("The host companion connects only to a Runtime on this computer's loopback interface.");
     url.pathname = HOST_SOCKET_PATH;
-    return { url: url.toString(), address: addresses[0] };
+    return { url: url.toString(), addresses };
 }

package/dist/src/computer-access/companion/native-build-identity.d.ts

@@ -0,0 +1,2 @@
+/** Identifies the exact entry bundle used by setup and the running companion. */
+export declare function readNativeCompanionBuildId(cliPath: string): Promise<string>;

package/dist/src/computer-access/companion/native-build-identity.js

@@ -0,0 +1,8 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+/** Identifies the exact entry bundle used by setup and the running companion. */
+export async function readNativeCompanionBuildId(cliPath) {
+    return createHash("sha256")
+        .update(await readFile(cliPath))
+        .digest("hex");
+}

package/dist/src/computer-access/companion/native-loopback-lookup.d.ts

@@ -0,0 +1,7 @@
+import type { TcpNetConnectOpts } from "node:net";
+import type { NativeAddress } from "./native-address.js";
+/** Socket-family selection is restricted to the resolver's immutable, vetted set. */
+export declare function nativeLoopbackSocketOptions(endpoint: Readonly<{
+    url: string;
+    addresses: readonly NativeAddress[];
+}>): Pick<TcpNetConnectOpts, "family" | "autoSelectFamily" | "autoSelectFamilyAttemptTimeout" | "lookup">;

package/dist/src/computer-access/companion/native-loopback-lookup.js

@@ -0,0 +1,33 @@
+function matchesLookupFamily(address, family) {
+    if (family === 4 || family === "IPv4")
+        return address.family === 4;
+    if (family === 6 || family === "IPv6")
+        return address.family === 6;
+    return family === undefined || family === 0;
+}
+/** Socket-family selection is restricted to the resolver's immutable, vetted set. */
+export function nativeLoopbackSocketOptions(endpoint) {
+    const expectedHostname = new URL(endpoint.url).hostname.toLowerCase();
+    return {
+        family: 0,
+        autoSelectFamily: true,
+        autoSelectFamilyAttemptTimeout: 250,
+        lookup(hostname, options, callback) {
+            const hasExpectedHostname = hostname.toLowerCase() === expectedHostname;
+            if (!hasExpectedHostname) {
+                callback(Object.assign(new Error("Unexpected Runtime lookup hostname."), { code: "ENOTFOUND" }), []);
+                return;
+            }
+            const addresses = endpoint.addresses.filter((address) => matchesLookupFamily(address, options.family));
+            if (addresses.length === 0) {
+                callback(Object.assign(new Error("No validated Runtime address for this family."), { code: "ENOTFOUND" }), []);
+                return;
+            }
+            if (options.all) {
+                callback(null, addresses.map(({ address, family }) => ({ address, family })));
+                return;
+            }
+            callback(null, addresses[0].address, addresses[0].family);
+        },
+    };
+}

package/dist/{plugins/system/source → src/computer-access}/companion/native-messages.js

@@ -1,5 +1,6 @@
 import { isNativeCredential } from "./native-state.js";
-import { isHostIdentifier, isHostOperation, isHostRecord, } from "./protocol.js";
+import { isObservationControl } from "./observation-protocol.js";
+import { isHostIdentifier, isHostWireOperation, isHostRecord, } from "./protocol.js";
 function hasOnlyFields(value, fields) {
     return Object.keys(value).every((key) => fields.includes(key));
 }
@@ -7,6 +8,8 @@ export function readNativeServerMessage(text) {
     const value = JSON.parse(text);
     if (!isHostRecord(value))
         throw new Error("Invalid host protocol message.");
+    if (isObservationControl(value))
+        return value;
     if (value.type === "paired") {
         if (!hasOnlyFields(value, ["type", "hostId", "credential"]))
             throw new Error("Unexpected pairing fields.");
@@ -42,7 +45,7 @@ export function readNativeServerMessage(text) {
         throw new Error("Invalid operation identity.");
     if (!isHostIdentifier(value.hostId))
         throw new Error("Invalid operation host identity.");
-    if (!isHostOperation(value.operation))
+    if (!isHostWireOperation(value.operation))
         throw new Error("Unsupported native operation.");
     if (!isHostRecord(value.params))
         throw new Error("Invalid native operation parameters.");
@@ -55,10 +58,15 @@ export function readNativeServerMessage(text) {
     };
 }
 const NATIVE_OPERATION_FIELDS = {
+    macos_permissions: ["target", "action", "permission"],
+    desktop_notification: ["target", "notificationId", "title", "body", "url"],
     system_targets: [],
     system_command: ["target", "command", "cwd", "elevated", "timeout_ms"],
     system_applications: ["target", "query", "limit"],
     system_launch: ["target", "application_id", "arguments"],
+    computer_execute: ["target", "sessionId", "request"],
+    computer_frame: ["target", "sessionId", "frameId", "offset"],
+    computer_close: ["target", "sessionId"],
 };
 export class NativeOperationInputError extends Error {
     code;

package/dist/src/computer-access/companion/native-notifications.d.ts

@@ -0,0 +1,16 @@
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+import type { HostIdentity } from "./protocol.js";
+import { type DesktopNotification } from "./notification-protocol.js";
+import { type NotificationLocations } from "./notification-locations.js";
+export type NativeNotificationSession = Readonly<{
+    ready: boolean;
+    refreshReadiness?(signal: AbortSignal): Promise<boolean>;
+    handlers(): Record<string, ToolImplementation>;
+    close(): void | Promise<void>;
+}>;
+export type NativeNotificationRenderer = Readonly<{
+    send(notification: DesktopNotification, signal?: AbortSignal): Promise<void>;
+    close(): void | Promise<void>;
+}>;
+export declare function createNotificationSession(platform: HostIdentity["os"], runtimeUrl: string, ready: boolean, renderer: NativeNotificationRenderer, probe?: (signal: AbortSignal) => Promise<boolean>): NativeNotificationSession;
+export declare function createNativeNotificationSession(platform: HostIdentity["os"], runtimeUrl: string, locations?: NotificationLocations, signal?: AbortSignal): Promise<NativeNotificationSession>;