@abot-ai/runtime 1.6.0 → 1.8.0

package/dist/src/model-gateway/providers/openai/structured-message-output.js

@@ -0,0 +1,175 @@
+const IGNORED_OUTPUT_DIAGNOSTIC_LIMIT = 8;
+function readRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function readMessagePhase(value) {
+    if (value === "commentary" || value === "final_answer")
+        return value;
+    return undefined;
+}
+function readOutputIndex(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+function takePendingText(output) {
+    const pending = output.pending;
+    output.pending = [];
+    return pending.map((chunk) => chunk.text);
+}
+function describeOutput(output) {
+    return {
+        itemId: output.itemId?.slice(0, 160) ?? null,
+        outputIndex: output.outputIndex,
+        arrivalOrder: output.arrivalOrder,
+        textByteCount: output.textByteCount,
+        ...(output.phase ? { phase: output.phase } : {}),
+    };
+}
+/** One invocation's structured result; never infer its phase from generated text. */
+export class OpenAIStructuredMessageOutput {
+    outputs = [];
+    byItemId = new Map();
+    byOutputIndex = new Map();
+    unidentifiedOutput;
+    firstTextOutput;
+    selectedOutput;
+    hasExplicitPhase = false;
+    nextOutputOrder = 0;
+    nextChunkSequence = 0;
+    observeItem(event) {
+        const item = readRecord(event.item);
+        if (item.type !== "message")
+            return [];
+        const output = this.resolveOutput(item.id, event.output_index);
+        const phase = readMessagePhase(item.phase);
+        if (!phase)
+            return this.takeSelectedText(output);
+        this.hasExplicitPhase = true;
+        output.phase = phase;
+        if (phase === "commentary") {
+            output.pending = [];
+            return [];
+        }
+        this.selectFinalOutput(output);
+        return this.takeSelectedText(output);
+    }
+    observeResponse(value) {
+        const response = readRecord(value);
+        if (!Array.isArray(response.output))
+            return [];
+        return response.output.flatMap((item, outputIndex) => this.observeItem({ item, output_index: outputIndex }));
+    }
+    consumeDelta(event, text) {
+        const output = this.resolveOutput(event.item_id, event.output_index);
+        this.firstTextOutput ??= output;
+        output.textByteCount += Buffer.byteLength(text, "utf8");
+        if (output.phase === "commentary")
+            return [];
+        output.pending.push({ sequence: this.nextChunkSequence++, text });
+        return this.takeSelectedText(output);
+    }
+    finish() {
+        if (this.selectedOutput) {
+            return { text: takePendingText(this.selectedOutput) };
+        }
+        if (this.hasExplicitPhase) {
+            return { text: [], error: "openai structured response missing final_answer" };
+        }
+        // Older responses have no phase: retain the first text message, never join them.
+        this.selectedOutput = this.firstTextOutput;
+        return {
+            text: this.selectedOutput ? takePendingText(this.selectedOutput) : [],
+        };
+    }
+    diagnostic() {
+        if (!this.selectedOutput || this.outputs.length < 2)
+            return undefined;
+        const ignored = this.outputs.filter((output) => output !== this.selectedOutput);
+        return {
+            outcome: "additional_message_outputs_ignored",
+            outputCount: this.outputs.length,
+            selectedOutput: describeOutput(this.selectedOutput),
+            ignoredOutputCount: ignored.length,
+            sampledIgnoredOutputs: ignored.slice(0, IGNORED_OUTPUT_DIAGNOSTIC_LIMIT).map(describeOutput),
+            omittedIgnoredOutputCount: Math.max(0, ignored.length - IGNORED_OUTPUT_DIAGNOSTIC_LIMIT),
+        };
+    }
+    selectFinalOutput(output) {
+        if (this.selectedOutput)
+            return;
+        this.selectedOutput = output;
+    }
+    takeSelectedText(output) {
+        if (output !== this.selectedOutput)
+            return [];
+        // Keep partial identities buffered until both identifiers can join their chunks.
+        if (output.itemId === null)
+            return [];
+        if (output.outputIndex === null)
+            return [];
+        return takePendingText(output);
+    }
+    mergeOutputs(first, second) {
+        const [output, absorbed] = [first, second].sort((a, b) => a.arrivalOrder - b.arrivalOrder);
+        output.itemId ??= absorbed.itemId;
+        output.outputIndex ??= absorbed.outputIndex;
+        output.phase ??= absorbed.phase;
+        output.textByteCount += absorbed.textByteCount;
+        output.pending = [...output.pending, ...absorbed.pending]
+            .sort((a, b) => a.sequence - b.sequence);
+        this.outputs.splice(this.outputs.indexOf(absorbed), 1);
+        for (const [key, value] of this.byItemId) {
+            if (value === absorbed)
+                this.byItemId.set(key, output);
+        }
+        for (const [key, value] of this.byOutputIndex) {
+            if (value === absorbed)
+                this.byOutputIndex.set(key, output);
+        }
+        if (this.firstTextOutput === absorbed)
+            this.firstTextOutput = output;
+        if (this.selectedOutput === absorbed)
+            this.selectedOutput = output;
+        return output;
+    }
+    reconcileOutputs(itemOutput, indexedOutput) {
+        if (!itemOutput)
+            return indexedOutput;
+        if (!indexedOutput)
+            return itemOutput;
+        if (itemOutput === indexedOutput)
+            return itemOutput;
+        return this.mergeOutputs(itemOutput, indexedOutput);
+    }
+    resolveOutput(itemIdValue, outputIndexValue) {
+        const itemId = typeof itemIdValue === "string" && itemIdValue.length > 0
+            ? itemIdValue : null;
+        const outputIndex = readOutputIndex(outputIndexValue);
+        const itemOutput = itemId === null ? undefined : this.byItemId.get(itemId);
+        const indexedOutput = outputIndex === null ? undefined : this.byOutputIndex.get(outputIndex);
+        let output = this.reconcileOutputs(itemOutput, indexedOutput);
+        if (itemId === null && outputIndex === null)
+            output = this.unidentifiedOutput;
+        if (!output) {
+            output = { itemId, outputIndex, arrivalOrder: ++this.nextOutputOrder,
+                textByteCount: 0, pending: [] };
+            this.outputs.push(output);
+        }
+        if (itemId !== null) {
+            output.itemId = itemId;
+            this.byItemId.set(itemId, output);
+        }
+        if (outputIndex !== null) {
+            output.outputIndex = outputIndex;
+            this.byOutputIndex.set(outputIndex, output);
+        }
+        if (itemId === null && outputIndex === null)
+            this.unidentifiedOutput = output;
+        return output;
+    }
+}

package/dist/src/model-gateway/server/configuration.d.ts

@@ -1,4 +1,6 @@
 import type { ModelGatewayPolicyConfig } from "../types.js";
 import type { ModelGatewayHandlerOptions } from "./contracts.js";
 export declare function resolveModelGatewayPort(environment?: NodeJS.ProcessEnv): number;
+/** Captures gateway inputs without changing its loggers or retaining credentials. */
+export declare function captureModelGatewayConfiguration(options: ModelGatewayHandlerOptions): string | null;
 export declare function configureModelGateway(options: ModelGatewayHandlerOptions): ModelGatewayPolicyConfig;

package/dist/src/model-gateway/server/configuration.js

@@ -1,10 +1,11 @@
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { loadRuntimeConfig } from "../../runtime/config.js";
 import { RUNTIME_LOGS_DIR_NAME } from "../../runtime/config/layout.js";
 import { loadRequestRunnerConfig } from "../../runtime/config/runner/loader.js";
 import { createRequestModelPolicy } from "../../runtime/config/runner/model-policy.js";
 import { configureDebugLogger } from "../../runtime/observability/debug-logger.js";
-import { DEFAULT_MODEL_GATEWAY_URL } from "../../shared/constants.js";
+import { DEFAULT_MODEL_GATEWAY_URL, DEFAULT_OLLAMA_URL, } from "../../shared/constants.js";
 import { configureModelIoTrace } from "../model-io-trace.js";
 const MODEL_GATEWAY_TRACE_FILE_SEGMENTS = ["model-gateway.jsonl"];
 const MODEL_IO_TRACE_FILE_SEGMENTS = ["model-io.jsonl"];
@@ -26,7 +27,7 @@ export function resolveModelGatewayPort(environment = process.env) {
     const parsedUrl = new URL(configuredUrl);
     return Number(parsedUrl.port || "80");
 }
-export function configureModelGateway(options) {
+function resolveModelGatewayConfiguration(options) {
     const runtimeConfig = loadRuntimeConfig({
         rootDir: options.rootDir ?? process.cwd(),
         configPath: options.configPath,
@@ -38,23 +39,74 @@ export function configureModelGateway(options) {
                 configPath: runtimeConfig.requestRunner.configPath,
             }),
         });
-    configureDebugLogger({
-        traceFile: resolveTraceFile({
-            configuredPath: resolveConfiguredTraceFile("MODEL_GATEWAY_TRACE_FILE"),
-            sharedDir: runtimeConfig.paths.sharedDir,
-            segments: MODEL_GATEWAY_TRACE_FILE_SEGMENTS,
-        }),
-        enabled: runtimeConfig.logging?.enabled,
-        rotation: runtimeConfig.logging?.rotation,
-    });
-    configureModelIoTrace({
-        traceFile: resolveTraceFile({
-            configuredPath: resolveConfiguredTraceFile("MODEL_GATEWAY_MODEL_IO_TRACE_FILE"),
-            sharedDir: runtimeConfig.paths.sharedDir,
-            segments: MODEL_IO_TRACE_FILE_SEGMENTS,
-        }),
-        enabled: runtimeConfig.logging?.enabled,
-        rotation: runtimeConfig.logging?.rotation,
-    });
-    return modelPolicy;
+    return {
+        modelGatewayUrl: runtimeConfig.modelGatewayUrl,
+        modelPolicy,
+        debugLogging: {
+            traceFile: resolveTraceFile({
+                configuredPath: resolveConfiguredTraceFile("MODEL_GATEWAY_TRACE_FILE"),
+                sharedDir: runtimeConfig.paths.sharedDir,
+                segments: MODEL_GATEWAY_TRACE_FILE_SEGMENTS,
+            }),
+            enabled: runtimeConfig.logging?.enabled,
+            rotation: runtimeConfig.logging?.rotation,
+        },
+        modelIoLogging: {
+            traceFile: resolveTraceFile({
+                configuredPath: resolveConfiguredTraceFile("MODEL_GATEWAY_MODEL_IO_TRACE_FILE"),
+                sharedDir: runtimeConfig.paths.sharedDir,
+                segments: MODEL_IO_TRACE_FILE_SEGMENTS,
+            }),
+            enabled: runtimeConfig.logging?.enabled,
+            rotation: runtimeConfig.logging?.rotation,
+        },
+    };
+}
+function canonicalConfiguration(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalConfiguration);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, canonicalConfiguration(entry)]));
+    return value;
+}
+function providerEnvironment(options, policy) {
+    const credentialNames = new Set(["OPENAI_API_KEY"]);
+    for (const provider of Object.values(policy.providers ?? {})) {
+        if (provider.type !== "openai")
+            continue;
+        const configuredName = provider.apiKeyEnv?.trim();
+        if (configuredName && /^[A-Za-z_][A-Za-z0-9_]*$/.test(configuredName))
+            credentialNames.add(configuredName);
+    }
+    const numPredict = Number(process.env.OLLAMA_NUM_PREDICT);
+    return {
+        ollamaUrl: options.ollamaUrl ?? (process.env.OLLAMA_URL || DEFAULT_OLLAMA_URL),
+        openAIBaseUrl: process.env.OPENAI_BASE_URL || "https://api.openai.com/v1",
+        ollamaNumPredict: Number.isFinite(numPredict) && numPredict > 0
+            ? Math.trunc(numPredict)
+            : null,
+        credentials: Object.fromEntries([...credentialNames].map((name) => [name, process.env[name] || null])),
+    };
+}
+/** Captures gateway inputs without changing its loggers or retaining credentials. */
+export function captureModelGatewayConfiguration(options) {
+    if (options.providerAdapters || options.additionalProviderAdapters?.length)
+        return null;
+    const configuration = resolveModelGatewayConfiguration(options);
+    const snapshot = {
+        ...configuration,
+        modelGatewayUrl: new URL(configuration.modelGatewayUrl).href,
+        providerEnvironment: providerEnvironment(options, configuration.modelPolicy),
+    };
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalConfiguration(snapshot)))
+        .digest("hex");
+}
+export function configureModelGateway(options) {
+    const configuration = resolveModelGatewayConfiguration(options);
+    configureDebugLogger(configuration.debugLogging);
+    configureModelIoTrace(configuration.modelIoLogging);
+    return configuration.modelPolicy;
 }

package/dist/src/model-gateway/server.js

@@ -1,7 +1,11 @@
+import { pathToFileURL } from "node:url";
+import { recoverRuntimeSetupEdit } from "../web-ui/local-runtime/runtime-setup-edit-recovery.js";
 import { createModelGatewayServer, resolveModelGatewayPort, } from "./server/index.js";
 export * from "./server/index.js";
 export { buildOllamaPayload, buildOllamaRawPayload, resolveFormat, } from "./providers/ollama.js";
-if (import.meta.url === `file://${process.argv[1]}`) {
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    await recoverRuntimeSetupEdit(process.cwd());
     const port = resolveModelGatewayPort();
     createModelGatewayServer().listen(port, () => {
         console.log(`MODEL GATEWAY RUNNING ${port}`);

package/dist/src/plugin-contract/index.d.ts

@@ -1,2 +1,3 @@
 export type * from "./entrypoint.js";
 export * from "./manifest.js";
+export * from "./platform-compatibility.js";

package/dist/src/plugin-contract/index.js

@@ -1 +1,2 @@
 export * from "./manifest.js";
+export * from "./platform-compatibility.js";

package/dist/src/plugin-contract/install-source.d.ts

@@ -0,0 +1,13 @@
+/** Portable installation intent. A source never grants execution authority. */
+export type PluginInstallSource = Readonly<{
+    repository: string;
+    ref?: string;
+    path?: string;
+}>;
+export declare class PluginInstallError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(code: string, message: string, statusCode?: number);
+}
+export declare function parsePluginInstallSource(input: unknown): PluginInstallSource;
+export declare function parsePluginInstallLink(value: string): PluginInstallSource;

package/dist/src/plugin-contract/install-source.js

@@ -0,0 +1,99 @@
+export class PluginInstallError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+function invalidSource(message) {
+    throw new PluginInstallError("plugin_source_invalid", message);
+}
+function hasPublicGitHubOrigin(url) {
+    if (url.protocol !== "https:")
+        return false;
+    if (url.hostname !== "github.com")
+        return false;
+    if (url.port || url.username || url.password)
+        return false;
+    return !url.search && !url.hash;
+}
+function isPluginInstallEndpoint(url) {
+    if (url.protocol !== "abot:")
+        return false;
+    if (url.hostname !== "install")
+        return false;
+    if (!["", "/"].includes(url.pathname))
+        return false;
+    if (url.username || url.password || url.port)
+        return false;
+    return !url.hash;
+}
+function isRepositoryFolderComponent(part) {
+    if (part === "." || part === "..")
+        return false;
+    return /^[A-Za-z0-9_.-]+$/u.test(part);
+}
+export function parsePluginInstallSource(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return invalidSource("Enter a public GitHub repository URL.");
+    const value = input;
+    if (typeof value.repository !== "string" || value.repository.length > 512)
+        return invalidSource("Enter a public GitHub repository URL.");
+    let url;
+    try {
+        url = new URL(value.repository.trim());
+    }
+    catch {
+        return invalidSource("Enter a public GitHub repository URL.");
+    }
+    if (!hasPublicGitHubOrigin(url))
+        return invalidSource("Use an HTTPS repository URL on github.com.");
+    const match = /^\/([A-Za-z0-9][A-Za-z0-9-]{0,38})\/([A-Za-z0-9_.-]{1,100})\/?$/u.exec(url.pathname);
+    if (!match)
+        return invalidSource("Use the repository URL; enter its revision and folder separately.");
+    const repo = match[2].replace(/\.git$/u, "");
+    if (repo === "." || repo === ".." || !repo)
+        return invalidSource("Invalid repository name.");
+    const ref = value.ref === undefined ? "" : value.ref;
+    if (typeof ref !== "string" ||
+        ref.length > 200 ||
+        /[\u0000-\u0020\u007f\\?#]/u.test(ref))
+        return invalidSource("Enter a commit, tag or branch without spaces.");
+    const path = value.path === undefined ? "" : value.path;
+    if (typeof path !== "string" || path.length > 512)
+        return invalidSource("Enter a folder relative to the repository root.");
+    if (path && !path.split("/").every(isRepositoryFolderComponent))
+        return invalidSource("The plugin folder must be a relative path without traversal.");
+    return {
+        repository: `https://github.com/${match[1]}/${repo}`,
+        ...(ref ? { ref } : {}),
+        ...(path ? { path } : {}),
+    };
+}
+export function parsePluginInstallLink(value) {
+    if (value.length > 2048)
+        return invalidSource("The installation link is too long.");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return invalidSource("Invalid ABot installation link.");
+    }
+    if (!isPluginInstallEndpoint(url))
+        return invalidSource("Unsupported ABot installation link.");
+    const allowed = ["kind", "repo", "ref", "path"];
+    for (const key of url.searchParams.keys()) {
+        if (!allowed.includes(key) || url.searchParams.getAll(key).length !== 1)
+            return invalidSource("Unsupported installation link fields.");
+    }
+    if (url.searchParams.get("kind") !== "plugin")
+        return invalidSource("This installation link must select a plugin.");
+    return parsePluginInstallSource({
+        repository: url.searchParams.get("repo"),
+        ref: url.searchParams.get("ref") ?? "",
+        path: url.searchParams.get("path") ?? "",
+    });
+}

package/dist/src/plugin-contract/manifest.d.ts

@@ -1,9 +1,11 @@
-import type { ToolCatalogGroup, ToolDevelopmentRole, ToolEventPresentation, ToolNormalInvocationApproval, ToolNormalInvocationAttachmentInput, ToolNormalInvocationEffect, ToolNormalInvocationFixedValue, ToolNormalInvocationInput, ToolNormalInvocationPayload, ToolPayloadChannelSpec, ToolRoutingCapability, ToolRuntimePathBinding } from "../capabilities/tool-types.js";
+import type { ToolCatalogGroup, ToolDevelopmentRole, ToolEventPresentation, ToolNormalInvocationApproval, ToolNormalInvocationAttachmentInput, ToolNormalInvocationEffect, ToolNormalInvocationFixedValue, ToolNormalInvocationInput, ToolNormalInvocationPayload, ToolNormalInvocationOutputChannels, ToolPayloadChannelSpec, ToolRoutingCapability, ToolRuntimePathBinding } from "../capabilities/tool-types.js";
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, type PluginPlatformDeclaration } from "./platform-compatibility.js";
 export declare const AGENT_PLUGIN_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export declare const ABOT_RUNTIME_EXTENSION = "ai.abot.runtime";
 export declare const ABOT_RUNTIME_EXTENSION_VERSION: 1;
 export type AgentPluginOperationManifest = Readonly<{
     summary: string;
+    outputChannels?: ToolNormalInvocationOutputChannels;
     input: ToolNormalInvocationInput;
     selectionControlIds?: readonly string[];
     effect: ToolNormalInvocationEffect;
@@ -47,6 +49,7 @@ export type AgentPluginManifest = Readonly<{
     description?: string;
     extensions: Readonly<{
         [ABOT_RUNTIME_EXTENSION]: AbotRuntimePluginExtension;
+        [ABOT_PLUGIN_COMPATIBILITY_EXTENSION]?: PluginPlatformDeclaration;
         [namespace: string]: unknown;
     }>;
 }>;

package/dist/src/plugin-contract/manifest.js

@@ -1,3 +1,4 @@
+import { ABOT_PLUGIN_COMPATIBILITY_EXTENSION, } from "./platform-compatibility.js";
 export const AGENT_PLUGIN_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export const ABOT_RUNTIME_EXTENSION = "ai.abot.runtime";
 export const ABOT_RUNTIME_EXTENSION_VERSION = 1;

package/dist/src/plugin-contract/platform-compatibility.d.ts

@@ -0,0 +1,16 @@
+export declare const ABOT_PLUGIN_COMPATIBILITY_EXTENSION = "ai.abot.compatibility";
+export declare const ABOT_PLUGIN_COMPATIBILITY_VERSION: 1;
+export declare const PLUGIN_RUNTIME_PLATFORMS: readonly ["linux", "darwin", "win32"];
+export type PluginRuntimePlatform = (typeof PLUGIN_RUNTIME_PLATFORMS)[number];
+/** The OS running Runtime, independent of a connected computer's OS. */
+export type PluginPlatformDeclaration = Readonly<{
+    version: typeof ABOT_PLUGIN_COMPATIBILITY_VERSION;
+    runtimePlatforms: readonly PluginRuntimePlatform[];
+}>;
+export type PluginPlatformCompatibility = Readonly<{
+    supported: boolean;
+    status: "declared" | "legacy" | "unsupported" | "undeclared";
+    runtimePlatform: NodeJS.Platform;
+    runtimePlatforms?: readonly PluginRuntimePlatform[];
+    reason?: string;
+}>;

package/dist/src/plugin-contract/platform-compatibility.js

@@ -0,0 +1,3 @@
+export const ABOT_PLUGIN_COMPATIBILITY_EXTENSION = "ai.abot.compatibility";
+export const ABOT_PLUGIN_COMPATIBILITY_VERSION = 1;
+export const PLUGIN_RUNTIME_PLATFORMS = ["linux", "darwin", "win32"];

package/dist/src/plugin-sdk/computer-access.d.ts

@@ -1,4 +1,5 @@
 /** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { HOST_SECRET_PROTECTION_CAPABILITY } from "../computer-access/companion/secret-protection-protocol.js";
 export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
 export { HOST_OPERATIONS, type HostIdentity, type HostOperation, type HostStatus, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
 export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";
@@ -11,3 +12,14 @@ export { SystemOperationError, type SystemTarget, type SystemTargetId, } from ".
 export { createSystemHandlers } from "../computer-access/handlers.js";
 export { type SystemTargetObservation, observeSystemTargets, } from "../computer-access/target-observation.js";
 export type { ComputerAccessConnection, CompanionTarget, } from "../computer-access/client.js";
+export { runSystemProcess } from "../computer-access/process-runner.js";
+export { buildSystemProcessResult } from "../computer-access/process-result.js";
+export type { SystemCommandOutputFactory } from "../computer-access/command-output.js";
+export type { SystemProcessCapture } from "../computer-access/process-capture.js";
+export type { SystemProcessResult } from "../computer-access/contracts.js";
+export { createSystemOutputCapture, type SystemOutputReceipt } from "../computer-access/command-output-capture.js";
+export { DEFAULT_SYSTEM_OUTPUT_RETENTION_MS, scheduleSystemOutputCleanup } from "../computer-access/command-output-retention.js";
+export { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer } from "../computer-access/companion/command-output-protocol.js";
+export type { SystemResultProtection } from "../computer-access/system-result-protection.js";
+export type { SystemApplication } from "../computer-access/contracts.js";
+export type { SystemApplicationCatalog, SystemApplicationCatalogScope } from "../computer-access/application-catalog.js";

package/dist/src/plugin-sdk/computer-access.js

@@ -1,4 +1,5 @@
 /** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { HOST_SECRET_PROTECTION_CAPABILITY } from "../computer-access/companion/secret-protection-protocol.js";
 export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
 export { HOST_OPERATIONS, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
 export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";
@@ -9,3 +10,8 @@ export { COMPUTER_CAPABILITY, readNativeComputerResult, } from "../computer-acce
 export { SystemOperationError, } from "../computer-access/contracts.js";
 export { createSystemHandlers } from "../computer-access/handlers.js";
 export { observeSystemTargets, } from "../computer-access/target-observation.js";
+export { runSystemProcess } from "../computer-access/process-runner.js";
+export { buildSystemProcessResult } from "../computer-access/process-result.js";
+export { createSystemOutputCapture } from "../computer-access/command-output-capture.js";
+export { DEFAULT_SYSTEM_OUTPUT_RETENTION_MS, scheduleSystemOutputCleanup } from "../computer-access/command-output-retention.js";
+export { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer } from "../computer-access/companion/command-output-protocol.js";

package/dist/src/plugin-sdk/files-windows/process.d.ts

@@ -0,0 +1,3 @@
+import { spawn } from "node:child_process";
+/** Read-only helper. Never alters execution policy, retries, or reads through a fallback. */
+export declare function runWindowsBoundedRead(request: Readonly<Record<string, unknown>>, maxBytes: number, signal?: AbortSignal, spawnProcess?: typeof spawn): Promise<string>;

package/dist/src/plugin-sdk/files-windows/process.js

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { WINDOWS_BOUNDED_READ_SOURCE } from "./read-script.js";
+import { windowsReadAbortError, windowsReadError } from "./result.js";
+const BOOTSTRAP = [
+    "$ErrorActionPreference='Stop'",
+    'if ($ExecutionContext.SessionState.LanguageMode -ne \'FullLanguage\') { Write-Output \'{"ok":false,"code":"filesystem_windows_policy_blocked"}\'; exit 0 }',
+    "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
+    "[Console]::InputEncoding=[Text.UTF8Encoding]::new($false)",
+    "[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)",
+    "$started=$false",
+    "try {",
+    "$envelope=[Console]::In.ReadToEnd() | ConvertFrom-Json",
+    "Add-Type -ReferencedAssemblies @('System.Web.Extensions') -TypeDefinition $envelope.source",
+    "$started=$true",
+    "[Console]::Write([AbotFilesystem]::Run($envelope.request))",
+    '} catch { if ($started) { [Console]::Write(\'{"ok":false,"code":"filesystem_native_operation_failed"}\') } else { [Console]::Write(\'{"ok":false,"code":"filesystem_windows_helper_unavailable"}\') } }',
+].join(";");
+const UNAVAILABLE = '{"ok":false,"code":"filesystem_windows_helper_unavailable"}';
+/** Read-only helper. Never alters execution policy, retries, or reads through a fallback. */
+export async function runWindowsBoundedRead(request, maxBytes, signal, spawnProcess = spawn) {
+    if (signal?.aborted)
+        throw windowsReadAbortError();
+    const input = JSON.stringify({
+        source: WINDOWS_BOUNDED_READ_SOURCE,
+        request: JSON.stringify(request),
+    });
+    if (Buffer.byteLength(input) > 2 * 1024 * 1024)
+        throw windowsReadError("EINVAL");
+    const outputLimit = 4 * Math.ceil(Math.min(maxBytes, 2_147_483_647) / 3) + 4096;
+    const executable = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return new Promise((resolve, reject) => {
+        const child = spawnProcess(executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", BOOTSTRAP], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+        const chunks = [];
+        let byteCount = 0;
+        let failure;
+        let unavailable = false;
+        const stop = (error) => {
+            failure ??= error;
+            child.kill("SIGKILL");
+        };
+        const abort = () => stop(windowsReadAbortError());
+        const timer = setTimeout(() => stop(windowsReadError("ETIMEDOUT")), 15_000);
+        timer.unref();
+        signal?.addEventListener("abort", abort, { once: true });
+        child.stdout.on("data", (chunk) => {
+            if (failure)
+                return;
+            byteCount += chunk.length;
+            if (byteCount > outputLimit) {
+                stop(windowsReadError("EOVERFLOW"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        // Compiler/native diagnostics may contain private paths. Never expose them.
+        child.stderr.resume();
+        child.stdin.on("error", () => {
+            if (child.pid === undefined)
+                return;
+            stop(windowsReadError("EIO"));
+        });
+        child.once("error", () => {
+            if (child.pid === undefined) {
+                unavailable = true;
+                return;
+            }
+            stop(windowsReadError("EIO"));
+        });
+        child.once("close", (code) => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            if (failure) {
+                reject(failure);
+                return;
+            }
+            if (unavailable) {
+                resolve(UNAVAILABLE);
+                return;
+            }
+            if (code !== 0) {
+                reject(windowsReadError("EIO"));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString("utf8"));
+        });
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
+        child.stdin.end(input, "utf8");
+    });
+}

package/dist/src/plugin-sdk/files-windows/read-script.d.ts

@@ -0,0 +1 @@
+export declare const WINDOWS_BOUNDED_READ_SOURCE: string;