@abot-ai/runtime 1.5.0 → 1.7.0

package/plugins/memory/src/index.cjs

@@ -106,8 +106,28 @@ function defineRuntimePlugin(definition) {
   return definition;
 }
 
+// src/capabilities/tool-context-text.ts
+function hasValidToolContextText(carrier) {
+  const fields = carrier.contextTextFields;
+  if (fields === void 0) return true;
+  if (!Array.isArray(fields) || fields.length === 0 || fields.length > 3)
+    return false;
+  if (new Set(fields).size !== fields.length) return false;
+  for (const field of fields) {
+    if (!isContextTextField(field)) return false;
+    if (typeof carrier[field] !== "string") return false;
+  }
+  return true;
+}
+function isContextTextField(value) {
+  return value === "output" || value === "stdout" || value === "stderr";
+}
+
+// src/capabilities/result-budget.ts
+var CAPABILITY_RESULT_ENVELOPE_MAX_BYTES = 256 * 1024;
+
 // src/plugin-sdk/results.ts
-var PLUGIN_RESULT_SERIALIZED_MAX_BYTES = 128 * 1024;
+var PLUGIN_RESULT_SERIALIZED_MAX_BYTES = CAPABILITY_RESULT_ENVELOPE_MAX_BYTES;
 function resultBoundsFailure(code, message) {
   return {
     ok: false,
@@ -117,9 +137,27 @@ function resultBoundsFailure(code, message) {
     errorCode: code
   };
 }
-function enforcePluginResultByteBudget(result) {
-  let serialized;
+function enforcePluginResultByteBudget(result, resultBudget) {
+  let requiresContextTextHost = false;
+  let serializedBytes;
+  let envelopeBytes;
+  let maxBytes = PLUGIN_RESULT_SERIALIZED_MAX_BYTES;
+  let fitsDeclaredBudget = true;
   try {
+    if (!hasValidToolContextText(result)) {
+      return resultBoundsFailure(
+        "plugin_context_text_invalid",
+        "The plugin declared invalid context text fields."
+      );
+    }
+    requiresContextTextHost = result.contextTextFields !== void 0;
+    const lacksContextTextHost = requiresContextTextHost && resultBudget?.acceptsContextText !== true;
+    if (lacksContextTextHost) {
+      return resultBoundsFailure(
+        "plugin_context_text_unavailable",
+        "The host does not support context-managed tool text."
+      );
+    }
     const candidate = JSON.stringify(result);
     if (candidate === void 0) {
       return resultBoundsFailure(
@@ -127,50 +165,60 @@ function enforcePluginResultByteBudget(result) {
         "The plugin produced a result that is not JSON-safe."
       );
     }
-    serialized = candidate;
+    const assessment = resultBudget?.assess(result);
+    serializedBytes = assessment?.serializedBytes ?? Buffer.byteLength(candidate, "utf8");
+    envelopeBytes = assessment?.envelopeBytes ?? serializedBytes;
+    maxBytes = Math.min(assessment?.maxBytes ?? maxBytes, maxBytes);
+    fitsDeclaredBudget = assessment?.fits ?? true;
   } catch {
     return resultBoundsFailure(
       "plugin_result_not_json_safe",
       "The plugin produced a result that is not JSON-safe."
     );
   }
-  if (Buffer.byteLength(serialized, "utf8") > PLUGIN_RESULT_SERIALIZED_MAX_BYTES) {
-    return resultBoundsFailure(
-      "plugin_result_too_large",
-      `The plugin result exceeds the ${PLUGIN_RESULT_SERIALIZED_MAX_BYTES}-byte safety limit.`
-    );
+  const hasResultDeliveryHeadroom = fitsDeclaredBudget && envelopeBytes <= maxBytes;
+  if (!hasResultDeliveryHeadroom) {
+    const message = requiresContextTextHost ? `The plugin result envelope is ${envelopeBytes} bytes (${serializedBytes} total bytes) and exceeds the ${maxBytes}-byte delivery limit.` : `The plugin result is ${serializedBytes} bytes and exceeds the ${maxBytes}-byte delivery limit.`;
+    return resultBoundsFailure("plugin_result_too_large", message);
   }
   return result;
 }
-function successResult(input) {
-  return enforcePluginResultByteBudget({
-    ok: true,
-    ...input.media !== void 0 ? { media: input.media } : {},
-    output: input.output,
-    producedNewInformation: input.producedNewInformation ?? true,
-    ...input.progress !== void 0 ? { progress: input.progress } : {},
-    ...input.actions !== void 0 ? { actions: input.actions } : {},
-    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
-    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
-    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
-    ...input.data !== void 0 ? { data: input.data } : {}
-  });
+function successResult(input, resultBudget) {
+  return enforcePluginResultByteBudget(
+    {
+      ok: true,
+      ...input.media !== void 0 ? { media: input.media } : {},
+      output: input.output,
+      producedNewInformation: input.producedNewInformation ?? true,
+      ...input.progress !== void 0 ? { progress: input.progress } : {},
+      ...input.actions !== void 0 ? { actions: input.actions } : {},
+      ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+      ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+      ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+      ...input.data !== void 0 ? { data: input.data } : {}
+    },
+    resultBudget
+  );
 }
-function failureResult(input) {
-  return enforcePluginResultByteBudget({
-    ok: false,
-    ...input.media !== void 0 ? { media: input.media } : {},
-    output: input.output ?? input.message,
-    producedNewInformation: false,
-    ...input.progress !== void 0 ? { progress: input.progress } : {},
-    ...input.actions !== void 0 ? { actions: input.actions } : {},
-    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
-    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
-    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
-    ...input.data !== void 0 ? { data: input.data } : {},
-    error: input.message,
-    errorCode: input.errorCode
-  });
+function failureResult(input, resultBudget) {
+  return enforcePluginResultByteBudget(
+    {
+      ok: false,
+      ...input.interruption ? { interruption: input.interruption } : {},
+      ...input.media !== void 0 ? { media: input.media } : {},
+      output: input.output ?? input.message,
+      producedNewInformation: false,
+      ...input.progress !== void 0 ? { progress: input.progress } : {},
+      ...input.actions !== void 0 ? { actions: input.actions } : {},
+      ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+      ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+      ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+      ...input.data !== void 0 ? { data: input.data } : {},
+      error: input.message,
+      errorCode: input.errorCode
+    },
+    resultBudget
+  );
 }
 function failureFromError(error, options) {
   const pathCode = runtimeToolPathErrorCode(error);

package/plugins/project-orientation/source/index.ts

@@ -36,10 +36,15 @@ export default defineRuntimePlugin((context) => {
 
   return {
     handlers: {
-      async inspect_project(params) {
+      async inspect_project(params, executionContext = undefined) {
+        const pathContext = {
+          ...context,
+          runtimePathResolver:
+            executionContext?.runtimePathResolver ?? context.runtimePathResolver,
+        };
         try {
           const requestedPath = readOptionalString(params.path) ?? ".";
-          const target = resolvePluginPath(context, requestedPath, {
+          const target = resolvePluginPath(pathContext, requestedPath, {
             defaultPath: ".",
             allowedLocations: ["agent_work", "workspace"],
           });
@@ -63,8 +68,8 @@ export default defineRuntimePlugin((context) => {
             name: "maxEntries",
           });
           const [tree, manifests] = await Promise.all([
-            collectProjectTree(context, target, depth, maxEntries),
-            readProjectManifests(context, target),
+            collectProjectTree(pathContext, target, depth, maxEntries),
+            readProjectManifests(pathContext, target),
           ]);
           const packageManifest = manifests.find(
             ({ file }) => file === "package.json",

package/plugins/project-orientation/src/index.cjs

@@ -223,8 +223,28 @@ function defineRuntimePlugin(definition) {
   return definition;
 }
 
+// src/capabilities/tool-context-text.ts
+function hasValidToolContextText(carrier) {
+  const fields = carrier.contextTextFields;
+  if (fields === void 0) return true;
+  if (!Array.isArray(fields) || fields.length === 0 || fields.length > 3)
+    return false;
+  if (new Set(fields).size !== fields.length) return false;
+  for (const field of fields) {
+    if (!isContextTextField(field)) return false;
+    if (typeof carrier[field] !== "string") return false;
+  }
+  return true;
+}
+function isContextTextField(value) {
+  return value === "output" || value === "stdout" || value === "stderr";
+}
+
+// src/capabilities/result-budget.ts
+var CAPABILITY_RESULT_ENVELOPE_MAX_BYTES = 256 * 1024;
+
 // src/plugin-sdk/results.ts
-var PLUGIN_RESULT_SERIALIZED_MAX_BYTES = 128 * 1024;
+var PLUGIN_RESULT_SERIALIZED_MAX_BYTES = CAPABILITY_RESULT_ENVELOPE_MAX_BYTES;
 function resultBoundsFailure(code, message) {
   return {
     ok: false,
@@ -234,9 +254,27 @@ function resultBoundsFailure(code, message) {
     errorCode: code
   };
 }
-function enforcePluginResultByteBudget(result) {
-  let serialized;
+function enforcePluginResultByteBudget(result, resultBudget) {
+  let requiresContextTextHost = false;
+  let serializedBytes;
+  let envelopeBytes;
+  let maxBytes = PLUGIN_RESULT_SERIALIZED_MAX_BYTES;
+  let fitsDeclaredBudget = true;
   try {
+    if (!hasValidToolContextText(result)) {
+      return resultBoundsFailure(
+        "plugin_context_text_invalid",
+        "The plugin declared invalid context text fields."
+      );
+    }
+    requiresContextTextHost = result.contextTextFields !== void 0;
+    const lacksContextTextHost = requiresContextTextHost && resultBudget?.acceptsContextText !== true;
+    if (lacksContextTextHost) {
+      return resultBoundsFailure(
+        "plugin_context_text_unavailable",
+        "The host does not support context-managed tool text."
+      );
+    }
     const candidate = JSON.stringify(result);
     if (candidate === void 0) {
       return resultBoundsFailure(
@@ -244,50 +282,60 @@ function enforcePluginResultByteBudget(result) {
         "The plugin produced a result that is not JSON-safe."
       );
     }
-    serialized = candidate;
+    const assessment = resultBudget?.assess(result);
+    serializedBytes = assessment?.serializedBytes ?? Buffer.byteLength(candidate, "utf8");
+    envelopeBytes = assessment?.envelopeBytes ?? serializedBytes;
+    maxBytes = Math.min(assessment?.maxBytes ?? maxBytes, maxBytes);
+    fitsDeclaredBudget = assessment?.fits ?? true;
   } catch {
     return resultBoundsFailure(
       "plugin_result_not_json_safe",
       "The plugin produced a result that is not JSON-safe."
     );
   }
-  if (Buffer.byteLength(serialized, "utf8") > PLUGIN_RESULT_SERIALIZED_MAX_BYTES) {
-    return resultBoundsFailure(
-      "plugin_result_too_large",
-      `The plugin result exceeds the ${PLUGIN_RESULT_SERIALIZED_MAX_BYTES}-byte safety limit.`
-    );
+  const hasResultDeliveryHeadroom = fitsDeclaredBudget && envelopeBytes <= maxBytes;
+  if (!hasResultDeliveryHeadroom) {
+    const message = requiresContextTextHost ? `The plugin result envelope is ${envelopeBytes} bytes (${serializedBytes} total bytes) and exceeds the ${maxBytes}-byte delivery limit.` : `The plugin result is ${serializedBytes} bytes and exceeds the ${maxBytes}-byte delivery limit.`;
+    return resultBoundsFailure("plugin_result_too_large", message);
   }
   return result;
 }
-function successResult(input) {
-  return enforcePluginResultByteBudget({
-    ok: true,
-    ...input.media !== void 0 ? { media: input.media } : {},
-    output: input.output,
-    producedNewInformation: input.producedNewInformation ?? true,
-    ...input.progress !== void 0 ? { progress: input.progress } : {},
-    ...input.actions !== void 0 ? { actions: input.actions } : {},
-    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
-    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
-    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
-    ...input.data !== void 0 ? { data: input.data } : {}
-  });
+function successResult(input, resultBudget) {
+  return enforcePluginResultByteBudget(
+    {
+      ok: true,
+      ...input.media !== void 0 ? { media: input.media } : {},
+      output: input.output,
+      producedNewInformation: input.producedNewInformation ?? true,
+      ...input.progress !== void 0 ? { progress: input.progress } : {},
+      ...input.actions !== void 0 ? { actions: input.actions } : {},
+      ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+      ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+      ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+      ...input.data !== void 0 ? { data: input.data } : {}
+    },
+    resultBudget
+  );
 }
-function failureResult(input) {
-  return enforcePluginResultByteBudget({
-    ok: false,
-    ...input.media !== void 0 ? { media: input.media } : {},
-    output: input.output ?? input.message,
-    producedNewInformation: false,
-    ...input.progress !== void 0 ? { progress: input.progress } : {},
-    ...input.actions !== void 0 ? { actions: input.actions } : {},
-    ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
-    ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
-    ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
-    ...input.data !== void 0 ? { data: input.data } : {},
-    error: input.message,
-    errorCode: input.errorCode
-  });
+function failureResult(input, resultBudget) {
+  return enforcePluginResultByteBudget(
+    {
+      ok: false,
+      ...input.interruption ? { interruption: input.interruption } : {},
+      ...input.media !== void 0 ? { media: input.media } : {},
+      output: input.output ?? input.message,
+      producedNewInformation: false,
+      ...input.progress !== void 0 ? { progress: input.progress } : {},
+      ...input.actions !== void 0 ? { actions: input.actions } : {},
+      ...input.exitCode !== void 0 ? { exitCode: input.exitCode } : {},
+      ...input.stdout !== void 0 ? { stdout: input.stdout } : {},
+      ...input.stderr !== void 0 ? { stderr: input.stderr } : {},
+      ...input.data !== void 0 ? { data: input.data } : {},
+      error: input.message,
+      errorCode: input.errorCode
+    },
+    resultBudget
+  );
 }
 function failureFromError(error, options) {
   const pathCode = runtimeToolPathErrorCode(error);
@@ -511,10 +559,14 @@ var index_default = defineRuntimePlugin((context) => {
   });
   return {
     handlers: {
-      async inspect_project(params) {
+      async inspect_project(params, executionContext = void 0) {
+        const pathContext = {
+          ...context,
+          runtimePathResolver: executionContext?.runtimePathResolver ?? context.runtimePathResolver
+        };
         try {
           const requestedPath = readOptionalString(params.path) ?? ".";
-          const target = resolvePluginPath(context, requestedPath, {
+          const target = resolvePluginPath(pathContext, requestedPath, {
             defaultPath: ".",
             allowedLocations: ["agent_work", "workspace"]
           });
@@ -538,8 +590,8 @@ var index_default = defineRuntimePlugin((context) => {
             name: "maxEntries"
           });
           const [tree, manifests] = await Promise.all([
-            collectProjectTree(context, target, depth, maxEntries),
-            readProjectManifests(context, target)
+            collectProjectTree(pathContext, target, depth, maxEntries),
+            readProjectManifests(pathContext, target)
           ]);
           const packageManifest = manifests.find(
             ({ file }) => file === "package.json"

package/plugins/system/README.md

@@ -9,6 +9,49 @@ configuration. Ask and Full retain exact-action approvals; Full+ retains its nor
 approval policy. OS accessibility, screen-recording and portal permissions still
 apply. An available shell or connected companion does not prove desktop readiness.
 
+## Local command output
+
+Local `system_command` execution, including Windows through WSL interop, writes
+stdout and stderr to private files under the plugin state directory. Capture
+uses bounded stream buffers with disk backpressure. The completed observation is
+then loaded for delivery; full text is still materialized in memory at that point.
+The existing SDK context-text contract lets the Runtime admit or compact that
+text using its normal model-context budget. Small-result text is unchanged.
+
+`extensions["ai.abot.runtime"].settings.defaults.outputRetentionMs` in the plugin's
+`plugin.json` controls retention; the default is seven days after capture completes. Cleanup protects active captures and removes expired
+captures during plugin initialization and periodic maintenance. Reads do not renew
+retention. Completed captures keep the retention recorded at creation across
+Companion reconnects and later configuration changes. Each capture has an opaque
+ID, byte counts and a saved process receipt;
+files are private implementation storage, not user-authored artifacts or model
+instructions. No wait/cancel operation or automatic command replay is added.
+
+A storage failure before dispatch prevents the command from starting. A capture
+write failure stops observation of that command and reports incomplete output;
+external descendants are not assumed terminated. Delivery failures retain the
+capture receipt, recorded helper PID, process status and exit code when available.
+This does not grant a new model-facing operation for reading retained captures.
+
+Application launch, target probes and desktop images retain their existing behavior.
+
+## Companion command output
+
+Updated companions advertise `system_command_output_v1`. SYSTEM then uses private
+capture/read/close operations over the existing connection: the Companion stores
+both streams in its private state directory using the same capture implementation,
+returns the process receipt, and serves 64 KiB byte chunks. SYSTEM verifies the
+capture ID, stream, offset, byte count and SHA-256 before delivering text through
+the existing context-text contract. UTF-8 characters may cross chunk boundaries.
+The model receives one tool result; transport chunks do not invoke a model.
+
+Output references belong to the authenticated Companion connection. Transfers
+protect their captures from expiry until closed or disconnected; the configured
+SYSTEM retention then continues on disk. A failed transfer preserves the command
+receipt and never repeats execution. Old companions keep their existing bounded
+command path. This transfer does not add model-facing tools or change screenshot
+handling, and final text delivery still materializes the streams in memory.
+
 ## Shared connection
 
 Use **Home → Computer access** for one installation shared
@@ -108,6 +151,3 @@ source compilation where available. They prove transport, identity, cancellation
 image lifetime and projection invariants. Interactive acceptance on each actual OS,
 permission configuration, compositor and provider remains a distinct live check;
 unit checks alone do not establish all native integrations work on a user's machine.
-The Windows helper has been compiled on Windows; its interactive behavior has not
-been exercised. macOS native compilation and interactive Linux/macOS checks remain
-unverified in this Windows/WSL development environment.

package/plugins/system/plugin.json

@@ -7,6 +7,11 @@
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",
+      "settings": {
+        "defaults": {
+          "outputRetentionMs": 604800000
+        }
+      },
       "catalogGroups": [
         "system"
       ],
@@ -76,7 +81,7 @@
           ],
           "operations": {
             "run_system_command": {
-              "summary": "Run an OS shell command on an available target with an absolute cwd in that target namespace. Can inspect application or browser page text, including signed-in pages, through native accessibility APIs such as Windows UI Automation when exposed to the current OS session. Verify the target document and returned text. Capability references are not shell commands. Exit zero alone is not effect evidence.",
+              "summary": "Run a shell command on an available OS target with absolute cwd in its namespace. The complete command, including inline file content, is limited to 4096 characters. File payload tools support larger bodies in the runtime-host namespace. Can read exposed application/browser text via native accessibility APIs, including signed-in pages. Verify the document and text. Capability references are not commands; exit zero is not effect evidence.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -767,7 +772,7 @@
               }
             },
             "computer_press_keys": {
-              "summary": "Press an explicit chord of named keys, for example [Control, L] or [Enter]. Keys are released after injection; no command-string parsing. Fresh observation and same desktop are required; no uncertain action is replayed.",
+              "summary": "Press a chord: [Command,L] on macOS or [Control,L] on Windows/Linux. Names: A-Z, 0-9, F1-F12, Control/Ctrl, Shift, Alt, Meta/Super, Enter/Return, Tab, Esc/Escape, Space, Backspace, Delete, ArrowLeft,ArrowRight,ArrowUp,ArrowDown, Home, End, PageUp/PageDown. macOS also accepts Command/Cmd and Option; Mac names ignore case. Keys release after injection; no chord-string parsing. Fresh observation and same desktop required; no uncertain action is replayed. Use computer_type_text for literal text.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,

package/plugins/system/source/companion-command-output.ts

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { StringDecoder } from "node:string_decoder";
+import { deliverPluginTextResult, failureResult, type ToolExecutionContext,
+  type ToolImplementationOutput } from "../../../src/plugin-sdk/index.js";
+import { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer,
+  type ComputerAccessConnection, type HostOperation } from "../../../src/plugin-sdk/computer-access.js";
+import type { SystemRequestRoute } from "./request-target-snapshot.js";
+
+type CompanionRoute = Extract<SystemRequestRoute, { kind: "companion" }>;
+type Transfer = ReturnType<typeof readSystemOutputTransfer>;
+type HostCall = (operation: HostOperation, params: Record<string, unknown>, signal?: AbortSignal) => Promise<ToolImplementationOutput>;
+
+export function supportsCompanionCommandOutput(route: CompanionRoute): boolean {
+  return route.capabilities?.includes(SYSTEM_OUTPUT_CAPABILITY) === true;
+}
+
+/** Transfer is private adapter IO; the model receives one settled tool result. */
+export async function executeCompanionCommand(input: {
+  rootDir: string;
+  route: CompanionRoute;
+  connection: ComputerAccessConnection;
+  params: Record<string, unknown>;
+  outputRetentionMs?: number;
+  context?: ToolExecutionContext;
+}): Promise<ToolImplementationOutput> {
+  const { route, context } = input;
+  const call: HostCall = (operation, params, signal) => input.connection.executeHostOperation(input.rootDir, {
+    hostId: route.hostId, connectionId: route.connectionId, operation,
+    params: { ...params, target: route.target }, ...(signal ? { abortSignal: signal } : {}),
+  });
+  const receipt = await call("system_command_capture", {
+    ...input.params, ...(input.outputRetentionMs !== undefined ? { outputRetentionMs: input.outputRetentionMs } : {}),
+  }, context?.abortSignal);
+  if (!receipt.data?.outputTransfer && !receipt.ok) return receipt;
+  let transfer: Transfer | undefined;
+  try {
+    transfer = readSystemOutputTransfer(receipt.data?.outputTransfer);
+    const stdout = await readStream(call, transfer, "stdout", context?.abortSignal);
+    const stderr = await readStream(call, transfer, "stderr", context?.abortSignal);
+    const { outputTransfer: _transfer, ...data } = receipt.data ?? {};
+    const delivered = deliverPluginTextResult({ ...receipt, stdout, stderr: stderr || receipt.stderr,
+      data: { ...data, outputDelivery: "complete", summaryOmittedChars: { stdout: stdout.length, stderr: stderr.length } },
+    }, ["stdout", "stderr"], context?.resultBudget);
+    if (delivered.errorCode === "plugin_result_too_large") return transferFailure(receipt, context);
+    return delivered;
+  } catch {
+    return transferFailure(receipt, context);
+  } finally {
+    if (transfer) await call("system_command_output_close", { captureId: transfer.id }, AbortSignal.timeout(3_000)).catch(() => undefined);
+  }
+}
+
+async function readStream(call: HostCall, transfer: Transfer, stream: "stdout" | "stderr", signal?: AbortSignal): Promise<string> {
+  const size = stream === "stdout" ? transfer.stdoutBytes : transfer.stderrBytes;
+  const digest = stream === "stdout" ? transfer.stdoutSha256 : transfer.stderrSha256;
+  const hash = createHash("sha256");
+  const decoder = new StringDecoder("utf8");
+  let text = "";
+  for (let offset = 0; offset < size; offset += SYSTEM_OUTPUT_CHUNK_BYTES) {
+    signal?.throwIfAborted();
+    const part = await call("system_command_output", { captureId: transfer.id, stream, offset }, signal);
+    if (!part.ok) throw new Error("system_output_transfer_failed");
+    const data = part.data;
+    if (data?.captureId !== transfer.id || data.stream !== stream || data.offset !== offset) throw new Error("system_output_chunk_binding_invalid");
+    if (typeof data.bytes !== "string" || data.bytes.length > SYSTEM_OUTPUT_CHUNK_BYTES * 2) throw new Error("system_output_chunk_invalid");
+    const bytes = Buffer.from(data.bytes, "base64");
+    if (bytes.toString("base64") !== data.bytes) throw new Error("system_output_chunk_invalid");
+    if (bytes.length !== Math.min(SYSTEM_OUTPUT_CHUNK_BYTES, size - offset)) throw new Error("system_output_chunk_size_invalid");
+    hash.update(bytes);
+    text += decoder.write(bytes);
+  }
+  if (hash.digest("hex") !== digest) throw new Error("system_output_digest_invalid");
+  return text + decoder.end();
+}
+
+function transferFailure(receipt: ToolImplementationOutput, context?: ToolExecutionContext): ToolImplementationOutput {
+  return failureResult({ errorCode: "system_output_delivery_pending",
+    message: "The command settled, but its retained output could not be delivered completely. Process receipt is preserved; the command was not replayed.",
+    ...(receipt.exitCode !== undefined ? { exitCode: receipt.exitCode } : {}),
+    data: { ...receipt.data, outputDelivery: "pending", commandOk: receipt.ok, commandErrorCode: receipt.errorCode ?? null },
+  }, context?.resultBudget);
+}

package/plugins/system/source/computer/observation-output.ts

@@ -1,4 +1,4 @@
-/** Leaves room for JSON-string escaping and result metadata in the SDK's 128 KiB envelope. */
+/** Leaves room for JSON-string escaping and result metadata in the SDK's 256 KiB envelope. */
 export const COMPUTER_OBSERVATION_OUTPUT_MAX_BYTES = 48 * 1024;
 
 type Observation = Record<string, unknown>;

package/plugins/system/source/host-dispatch.ts

@@ -1,3 +1,4 @@
+import { executeCompanionCommand, supportsCompanionCommandOutput } from "./companion-command-output.js";
 import type { ComputerAccessConnection } from "../../../src/plugin-sdk/computer-access.js";
 import {
   failureResult,
@@ -32,6 +33,7 @@ export function createBoundSystemHandlers(
     snapshot: SystemTargetSnapshot;
     nativeHandlers: Readonly<Record<string, ToolImplementation>>;
     connection: SystemHostConnection;
+    outputRetentionMs?: number;
   }>,
 ): Record<string, ToolImplementation> {
   return Object.fromEntries(
@@ -67,6 +69,8 @@ function boundOperation(
       const route = requireSystemRequestRoute(input.snapshot, params.target);
       if (route.kind === "native")
         return await input.nativeHandlers[operation]!(params, context);
+      if (operation === "system_command" && supportsCompanionCommandOutput(route))
+        return await executeCompanionCommand({ ...input, route, params, context });
       return await input.connection.executeHostOperation(input.rootDir, {
         hostId: route.hostId,
         connectionId: route.connectionId,

package/plugins/system/source/index.ts

@@ -1,10 +1,16 @@
 import { defineRuntimePlugin } from "../../../src/plugin-sdk/index.js";
 import { createSystemHandlers } from "../../../src/plugin-sdk/computer-access.js";
 import { prepareSystemRequestModules } from "./request-system-modules.js";
+import { createLocalSystemCommandOutput, systemCommandOutputRetentionMs } from "./local-command-output.js";
 import { unboundComputerHandlers } from "./computer/request-modules.js";
 
-export default defineRuntimePlugin(({ rootDir }) => ({
-  handlers: { ...createSystemHandlers(), ...unboundComputerHandlers() },
-  prepareRequest: (modules, preparation) =>
-    prepareSystemRequestModules(rootDir, modules, {}, preparation),
-}));
+export default defineRuntimePlugin((context) => {
+  const output = createLocalSystemCommandOutput(context);
+  return {
+    handlers: { ...createSystemHandlers(undefined, undefined, output), ...unboundComputerHandlers() },
+    prepareRequest: (modules, preparation) => prepareSystemRequestModules(context.rootDir, modules, {
+      outputRetentionMs: systemCommandOutputRetentionMs(context),
+      createNativeHandlers: (resolve) => createSystemHandlers(undefined, resolve, output),
+    }, preparation),
+  };
+});