@abot-ai/runtime 1.6.0 → 1.8.0

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

@@ -8,16 +8,63 @@ import { SystemOperationError, } from "./contracts.js";
 import { runSystemProcess } from "./process-runner.js";
 import { systemProcessResult } from "./process-result.js";
 import { readSystemTargetId, resolveSystemTarget } from "./targets.js";
-function withSystemOperationErrors(operation) {
+const PROTECTION_FAILURE = "The system result could not be protected for delivery.";
+function protectSystemResult(operation) {
+    try {
+        return operation();
+    }
+    catch {
+        throw new SystemOperationError("system_result_protection_failed", PROTECTION_FAILURE);
+    }
+}
+function failedSystemProtectionReceipt(target, result, evidenceScope) {
+    const safeProcess = {
+        status: result.status,
+        exitCode: result.exitCode,
+        outputTruncated: result.outputTruncated,
+        stdout: "[UNAVAILABLE: result protection failed]",
+        stderr: "[UNAVAILABLE: result protection failed]",
+        ...(result.spawnedProcess ? {
+            spawnedProcess: {
+                pid: result.spawnedProcess.pid,
+                pidNamespace: result.spawnedProcess.pidNamespace,
+                identitySource: result.spawnedProcess.identitySource,
+                executable: "[REDACTED]",
+            },
+        } : {}),
+    };
+    const receipt = systemProcessResult(target, safeProcess, evidenceScope);
+    return failureResult({
+        errorCode: "system_result_protection_failed",
+        message: PROTECTION_FAILURE,
+        output: "The operation was dispatched. Inspect the process receipt before another action; the command was not replayed.\n" + receipt.output,
+        stdout: safeProcess.stdout,
+        stderr: safeProcess.stderr,
+        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        data: receipt.data,
+    });
+}
+function withSystemOperationErrors(operation, protection) {
     return async (params, context) => {
         try {
             return await operation(params, context);
         }
         catch (error) {
+            let message = error instanceof Error ? error.message : undefined;
+            try {
+                if (protection && message !== undefined)
+                    message = protection.protectMessage(message);
+            }
+            catch {
+                return failureResult({
+                    errorCode: "system_result_protection_failed",
+                    message: PROTECTION_FAILURE,
+                });
+            }
             if (error instanceof SystemOperationError)
                 return failureResult({
                     errorCode: error.code,
-                    message: error.message,
+                    message: message,
                     data: {
                         humanActionRequired: error.code === "system_authorization_required",
                     },
@@ -30,9 +77,10 @@ function withSystemOperationErrors(operation) {
         }
     };
 }
-export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run)) {
+export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run), commandOutput, protection) {
     const targets = async () => {
-        const observation = await observeSystemTargets(run);
+        const observed = await observeSystemTargets(run);
+        const observation = protection ? protectSystemResult(() => protection.protectTargets(observed)) : observed;
         return successResult({
             output: JSON.stringify(observation),
             data: {
@@ -43,12 +91,24 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
     };
     const command = async (params, context) => {
         const target = await resolveTarget(readSystemTargetId(params.target));
-        const result = await executeSystemCommand({
+        const output = commandOutput?.(context);
+        const observed = await executeSystemCommand({
             target,
             params,
             run,
+            ...(output ? { runCommand: output.run } : {}),
             ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
         });
+        let result = observed;
+        try {
+            if (protection)
+                result = protection.protectProcess(observed);
+        }
+        catch {
+            return failedSystemProtectionReceipt(target, observed, "command_process_completion");
+        }
+        if (output)
+            return output.present(target, result);
         return systemProcessResult(target, result, "command_process_completion");
     };
     const applications = async (params) => {
@@ -61,7 +121,8 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
                 minimum: 1,
                 maximum: 100,
             });
-        const catalog = await readSystemApplications(target, run);
+        const observed = await readSystemApplications(target, run);
+        const catalog = protection ? protectSystemResult(() => protection.protectCatalog(observed)) : observed;
         const { output, data } = systemApplicationObservation(target, catalog, query, limit);
         return successResult({
             output,
@@ -79,12 +140,23 @@ export function createSystemHandlers(run = runSystemProcess, resolveTarget = (id
             run,
             ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
         });
-        return systemProcessResult(target, result.process, "launch_request_dispatch", result.application);
+        let process = result.process;
+        let application = result.application;
+        try {
+            if (protection) {
+                process = protection.protectProcess(result.process);
+                application = protection.protectApplication(result.application);
+            }
+        }
+        catch {
+            return failedSystemProtectionReceipt(target, result.process, "launch_request_dispatch");
+        }
+        return systemProcessResult(target, process, "launch_request_dispatch", application);
     };
     return {
-        system_targets: withSystemOperationErrors(targets),
-        system_command: withSystemOperationErrors(command),
-        system_applications: withSystemOperationErrors(applications),
-        system_launch: withSystemOperationErrors(launch),
+        system_targets: withSystemOperationErrors(targets, protection),
+        system_command: withSystemOperationErrors(command, protection),
+        system_applications: withSystemOperationErrors(applications, protection),
+        system_launch: withSystemOperationErrors(launch, protection),
     };
 }

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: SystemTargetId | "unsupported";
+    readonly runtimeOs: "unsupported" | SystemTargetId;
     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: SystemTargetId | "unsupported";
+    readonly runtimeOs: "unsupported" | SystemTargetId;
     readonly kernelRelease: string;
     readonly environment: "wsl_guest" | "not_identified_as_wsl";
-    readonly inferredHostOs: SystemTargetId | "unsupported";
+    readonly inferredHostOs: "unsupported" | SystemTargetId;
     readonly hostInferenceSource: "wsl_kernel_signature" | "runtime_platform_only";
     readonly windowsExecutionRequiresProbe: boolean;
     readonly guiSessionStatus: "not_checked";

package/dist/src/computer-access/native-observation-connection.d.ts

@@ -0,0 +1,12 @@
+import type { HostObservationSubscription } from "../shared/passive-observation.js";
+import { startDesktopCollector } from "./companion/observation-process.js";
+import { acquireNativeObservationOwnership } from "./native-observation-ownership.js";
+type NativeObservationDependencies = Readonly<{
+    acquireOwnership?: typeof acquireNativeObservationOwnership;
+    startCollector?: typeof startDesktopCollector;
+}>;
+/** Local transport retains the existing collector's filtering and the source's owner/lease contract. */
+export declare function connectNativeObservations(options: HostObservationSubscription, dependencies?: NativeObservationDependencies): Promise<Readonly<{
+    close(): void;
+}>>;
+export {};

package/dist/src/computer-access/native-observation-connection.js

@@ -0,0 +1,78 @@
+import { startDesktopCollector } from "./companion/observation-process.js";
+import { acquireNativeObservationOwnership } from "./native-observation-ownership.js";
+import { createNativeObservationShutdown, waitForNativeObservationShutdown } from "./native-observation-shutdown.js";
+function canPublishNativeObservation(closed, signal) {
+    if (closed)
+        return false;
+    return !signal.aborted;
+}
+/** Local transport retains the existing collector's filtering and the source's owner/lease contract. */
+export async function connectNativeObservations(options, dependencies = {}) {
+    await waitForNativeObservationShutdown(options.rootDir, options.ownerId, options.abortSignal);
+    options.abortSignal.throwIfAborted();
+    const ownership = await (dependencies.acquireOwnership ?? acquireNativeObservationOwnership)(options.rootDir);
+    const shutdown = createNativeObservationShutdown(options.rootDir, options.ownerId);
+    let collector;
+    let closed = false;
+    let starting = true;
+    let stopped = false;
+    function onStopped() {
+        if (stopped)
+            return;
+        stopped = true;
+        closed = true;
+        options.abortSignal.removeEventListener("abort", close);
+        shutdown.begin();
+        void ownership.release().then(() => shutdown.confirmReleased()).catch(() => process.emitWarning("Native collection ownership could not be released.", { code: "NATIVE_OBSERVATION_RELEASE_FAILED" }));
+    }
+    function stopCollector() {
+        if (stopped)
+            return;
+        try {
+            collector?.close();
+        }
+        catch {
+            process.emitWarning("Native collector stop was not confirmed; its ownership is retained.", { code: "NATIVE_OBSERVATION_STOP_UNCONFIRMED" });
+        }
+    }
+    function close() {
+        if (closed)
+            return;
+        closed = true;
+        shutdown.begin();
+        options.abortSignal.removeEventListener("abort", close);
+        if (!starting)
+            stopCollector();
+    }
+    function onEvent(event) {
+        if (!canPublishNativeObservation(closed, options.abortSignal))
+            return;
+        try {
+            options.onEvent({ ...event, deviceId: ownership.deviceId, ownerId: options.ownerId, leaseId: options.leaseId });
+        }
+        catch {
+            process.emitWarning("Native observation delivery failed; collection is closing.", { code: "NATIVE_OBSERVATION_DELIVERY_FAILED" });
+            close();
+        }
+    }
+    options.abortSignal.addEventListener("abort", close, { once: true });
+    if (options.abortSignal.aborted) {
+        onStopped();
+        options.abortSignal.throwIfAborted();
+    }
+    try {
+        collector = (dependencies.startCollector ?? startDesktopCollector)({
+            excludedApplications: options.excludedApplications ?? [], onEvent, onStopped,
+        });
+    }
+    catch {
+        onEvent({ type: "status", state: "failed", reason: "collector_start_failed" });
+        close();
+    }
+    finally {
+        starting = false;
+        if (closed)
+            stopCollector();
+    }
+    return { close };
+}

package/dist/src/computer-access/native-observation-ownership.d.ts

@@ -0,0 +1,6 @@
+export type NativeObservationOwnership = Readonly<{
+    deviceId: string;
+    release(): Promise<void>;
+}>;
+/** One installation shares a device identity and exclusive collector across environment processes. */
+export declare function acquireNativeObservationOwnership(rootDir: string): Promise<NativeObservationOwnership>;

package/dist/src/computer-access/native-observation-ownership.js

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
+import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
+import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity } from "./companion/process-owner-identity.js";
+import { hostStateDirectory, readHostPrivateJson, writeHostPrivateJson } from "./companion/private-store.js";
+import { isHostIdentifier, isHostRecord } from "./companion/protocol.js";
+function isNativeDeviceIdentity(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (value.version !== 1)
+        return false;
+    return isHostIdentifier(value.deviceId);
+}
+function isNativeObservationOwnershipConflict(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.message === "long_term_memory_store_lock_timeout";
+}
+function readNativeDeviceId(directory) {
+    const path = join(directory, "native-device.json");
+    const value = readHostPrivateJson(path);
+    if (value === undefined) {
+        const deviceId = randomUUID();
+        writeHostPrivateJson(path, { version: 1, deviceId });
+        return deviceId;
+    }
+    if (!isNativeDeviceIdentity(value))
+        throw new Error("native_observation_identity_invalid");
+    return value.deviceId;
+}
+/** One installation shares a device identity and exclusive collector across environment processes. */
+export async function acquireNativeObservationOwnership(rootDir) {
+    const directory = hostStateDirectory(rootDir);
+    await ensurePrivateRuntimeDirectory(directory);
+    const ownerIdentity = await requireCurrentProcessOwnerIdentity();
+    let release;
+    try {
+        release = await acquireFileLock(join(directory, "native-observation-owner.lock"), {
+            waitMs: 0, ownerIdentity, processIsAlive: isProcessOwnerAlive, releaseMode: "synchronous",
+        });
+    }
+    catch (error) {
+        if (isNativeObservationOwnershipConflict(error))
+            throw new Error("host_observations_already_owned");
+        throw error;
+    }
+    try {
+        return { deviceId: readNativeDeviceId(directory), release };
+    }
+    catch (error) {
+        await release();
+        throw error;
+    }
+}

package/dist/src/computer-access/native-observation-shutdown.d.ts

@@ -0,0 +1,7 @@
+/** A replacement waits only for this process's same installation and environment owner. */
+export declare function waitForNativeObservationShutdown(rootDir: string, ownerId: string, signal: AbortSignal): Promise<void>;
+/** The caller confirms release only after helper exit and successful physical lock cleanup. */
+export declare function createNativeObservationShutdown(rootDir: string, ownerId: string): {
+    begin(): void;
+    confirmReleased(): void;
+};

package/dist/src/computer-access/native-observation-shutdown.js

@@ -0,0 +1,58 @@
+import { resolve } from "node:path";
+const stoppingLeases = new Map();
+const NATIVE_OBSERVATION_SHUTDOWN_WAIT_MS = 2_000;
+function shutdownKey(rootDir, ownerId) {
+    const root = resolve(rootDir);
+    return JSON.stringify([process.platform === "win32" ? root.toLowerCase() : root, ownerId]);
+}
+/** A replacement waits only for this process's same installation and environment owner. */
+export async function waitForNativeObservationShutdown(rootDir, ownerId, signal) {
+    signal.throwIfAborted();
+    const previous = stoppingLeases.get(shutdownKey(rootDir, ownerId));
+    if (!previous)
+        return;
+    const waiters = previous.waiters;
+    await new Promise((resolveWait, rejectWait) => {
+        let finished = false;
+        function finish(error) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            waiters.delete(released);
+            if (error !== undefined)
+                rejectWait(error);
+            else
+                resolveWait();
+        }
+        function abort() { finish(signal.reason ?? new Error("host_observation_cancelled")); }
+        function released() { finish(); }
+        const timer = setTimeout(() => finish(new Error("host_observations_already_owned")), NATIVE_OBSERVATION_SHUTDOWN_WAIT_MS);
+        signal.addEventListener("abort", abort, { once: true });
+        waiters.add(released);
+        if (signal.aborted)
+            abort();
+    });
+}
+/** The caller confirms release only after helper exit and successful physical lock cleanup. */
+export function createNativeObservationShutdown(rootDir, ownerId) {
+    const key = shutdownKey(rootDir, ownerId);
+    let released = false;
+    const entry = { waiters: new Set() };
+    return {
+        begin() {
+            if (!released)
+                stoppingLeases.set(key, entry);
+        },
+        confirmReleased() {
+            if (released)
+                return;
+            released = true;
+            if (stoppingLeases.get(key) === entry)
+                stoppingLeases.delete(key);
+            for (const waiter of entry.waiters)
+                waiter();
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+export type RuntimeCollectionSource = Readonly<{
+    mode: "native" | "companion";
+    platform: "windows" | "macos" | "linux" | "unsupported";
+}>;
+/** The Runtime process selects the source; the browser and paired computer do not. */
+export declare function readRuntimeCollectionSource(platform?: NodeJS.Platform): RuntimeCollectionSource;

package/dist/src/computer-access/observation-source.js

@@ -0,0 +1,10 @@
+/** The Runtime process selects the source; the browser and paired computer do not. */
+export function readRuntimeCollectionSource(platform = process.platform) {
+    if (platform === "win32")
+        return { mode: "native", platform: "windows" };
+    if (platform === "darwin")
+        return { mode: "companion", platform: "macos" };
+    if (platform === "linux")
+        return { mode: "companion", platform: "linux" };
+    return { mode: "companion", platform: "unsupported" };
+}

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>;

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

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 const STREAM_MAX_CHARS = 16_000;
 /** Bounded process observation; exit zero proves command completion, not effects. */
-export function runSystemProcess(input) {
+export function runSystemProcess(input, capture) {
     if (input.abortSignal?.aborted)
         return Promise.resolve({
             exitCode: null,
@@ -29,6 +29,7 @@ export function runSystemProcess(input) {
             if (stopGrace)
                 clearTimeout(stopGrace);
             input.abortSignal?.removeEventListener("abort", abort);
+            capture?.end();
             resolve(Object.freeze({
                 exitCode,
                 stdout,
@@ -76,18 +77,25 @@ export function runSystemProcess(input) {
             stopGrace.unref();
         };
         const abort = () => stop("aborted");
-        child.stdout.setEncoding("utf8");
-        child.stderr.setEncoding("utf8");
-        child.stdout.on("data", (chunk) => {
-            const remaining = streamMaxChars - stdout.length;
-            truncated ||= chunk.length > remaining;
-            stdout += chunk.slice(0, remaining);
-        });
-        child.stderr.on("data", (chunk) => {
-            const remaining = streamMaxChars - stderr.length;
-            truncated ||= chunk.length > remaining;
-            stderr += chunk.slice(0, remaining);
-        });
+        const attachOutput = () => {
+            if (capture) {
+                capture.attach(child.stdout, child.stderr, () => stop("output_failed"));
+                return;
+            }
+            child.stdout.setEncoding("utf8");
+            child.stderr.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                const remaining = streamMaxChars - stdout.length;
+                truncated ||= chunk.length > remaining;
+                stdout += chunk.slice(0, remaining);
+            });
+            child.stderr.on("data", (chunk) => {
+                const remaining = streamMaxChars - stderr.length;
+                truncated ||= chunk.length > remaining;
+                stderr += chunk.slice(0, remaining);
+            });
+        };
+        attachOutput();
         child.once("error", (error) => {
             status = "spawn_failed";
             stderr = error.message.slice(0, STREAM_MAX_CHARS);

package/dist/src/computer-access/security/desktop-result.d.ts

@@ -0,0 +1,8 @@
+import type { NativeComputerResult } from "../computer/native-protocol.js";
+type TextScanner = (input: string) => string;
+/**
+ * Best-effort text protection before frame retention or result projection.
+ * Pixels are not inspected: a text match withholds the associated entire image.
+ */
+export declare function protectDesktopResult(result: NativeComputerResult, scan?: TextScanner): NativeComputerResult;
+export {};