@abot-ai/runtime 1.4.0 → 1.6.0

package/README.md

@@ -12,7 +12,10 @@ hardcoded defaults.
 
 - Configurable local and hosted model providers
 - Persistent conversations, request events, and replay
-- Optional passive long-term memory across sessions
+- Optional long-term memory with protected saves and reviewed automatic candidates
+- ABot Spark for optional desktop learning and proactive conversation suggestions
+- Desktop observation and control through shared Computer access
+- A notification inbox and optional native desktop alerts
 - Local scheduled requests bound to their conversations
 - Planning, execution, and review workflows
 - Manifest-based tools and plugins with explicit runtime boundaries
@@ -28,23 +31,25 @@ local runtime backend by default, so an external bridge is not required.
 
 The Web UI supports:
 
-- creating, reopening, and deleting conversations
+- creating, pinning, reordering, archiving, reopening, and deleting conversations
 - choosing the active environment, model, and reasoning mode
 - uploading files and images
 - streaming messages, current activity, tool progress, and failures
-- steering an active request or queuing the next message
+- steering or stopping an active request, or queuing the next message
 - editing runtime configuration
 - configuring passive long-term memory with a consumer-selected embedding model
-- managing schedules, their saved models, and run history in the Schedules workspace
+- managing scheduled Jobs, their saved models and permissions, and run history
+- controlling Spark collection, learning, proactive suggestions, and application exclusions
+- reviewing saved memories and opening notification sources
 - inspecting runtime status, logs, and health
 
 The UI is a client of the runtime; persisted sessions, events, and request state
 remain owned by the runtime.
 
 Schedules can also be managed through the model's built-in `schedules` capability.
-Every Job belongs to a conversation and runs there with its saved model and FULL
-tool permissions. The chat shows a compact run card; expand it to read the exact
-historical prompt. ABot must be running at the scheduled time. Missed offline
+Every Job belongs to a conversation and runs there with its saved model and Full
+or FULL+ tool permissions. New Jobs default to Full. The chat shows a compact run
+card; expand it to read the exact historical prompt. ABot must be running at the scheduled time. Missed offline
 occurrences and failed runs are not retried. Cancelling a Job or deleting its
 conversation prevents pending starts; an already-started run continues.
 
@@ -98,7 +103,7 @@ OpenAI profiles created by `abot init` or `abot add-model` use the recommended
 the user explicitly requests replacement.
 
 Passive long-term memory is disabled by default. After configuring a provider,
-choose and probe an embedding model from the Config workspace or CLI:
+choose and probe an embedding model from **Memory → Setup** or the CLI:
 
 ```bash
 npx abot memory enable --provider <provider-id> --model <embedding-model-id>
@@ -106,6 +111,13 @@ npx abot memory enable --provider <provider-id> --model <embedding-model-id>
 
 See [Passive Long-Term Memory](docs/long-term-memory.md) for its privacy,
 storage, retrieval, and management contracts.
+[ABot Spark](docs/long-term-memory.md#learning-from-computer-activity) adds optional
+computer-activity learning and proactive suggestions, with separate controls and
+daily usage limits. Collection and proactive messages are off by default.
+
+[Computer access and notifications](docs/installation.md#computer-access-during-setup)
+use one paired Companion. Desktop tools require the [SYSTEM platform dependencies
+and permissions](plugins/system/README.md#execution-environments).
 
 ## Quick Start From Source
 

package/dist/scripts/runtime-model-addition.d.ts

@@ -1,6 +1,6 @@
 import { type JsonObject } from "./runtime-setup-files.js";
 export declare function parseRuntimeModelProfileId(value: string): string;
-/** Shared additive merge for CLI file references and Web inline model profiles. */
+/** Shared additive profile-declaration merge for CLI and Web model setup. */
 export declare function mergeRuntimeModelAddition(runtimeConfig: JsonObject, input: {
     profileId: string;
     providerId: string;

package/dist/scripts/runtime-model-addition.js

@@ -14,7 +14,7 @@ function readConfigMap(parent, key) {
         throw new Error(`${key} must be a JSON object`);
     return value;
 }
-/** Shared additive merge for CLI file references and Web inline model profiles. */
+/** Shared additive profile-declaration merge for CLI and Web model setup. */
 export function mergeRuntimeModelAddition(runtimeConfig, input) {
     const models = readConfigMap(runtimeConfig, "models");
     const providers = readConfigMap(models, "providers");

package/dist/src/bridge/start-agent-bridge.js

@@ -1,4 +1,6 @@
 import WebSocket from "ws";
+import { assertInteractiveSession as assertGlobalInteractiveSession } from "../sessions/index.js";
+import { isAutomationSessionLockedError } from "../sessions/automation-session-origin.js";
 import { handleRunRequest } from "../runtime/request/handler.js";
 import { traceDebug } from "../runtime/observability/debug-logger.js";
 import { normalizeRuntimeId } from "../shared/agent.js";
@@ -340,7 +342,27 @@ export function startAgentBridge(options = {}) {
             }
             if (msg.type !== "run_request")
                 return;
+            const sessionId = getString(msg.sessionId).trim();
             const requestId = getString(msg.requestId).trim();
+            try {
+                if (sessionId) {
+                    if (options.sessionStore)
+                        await options.sessionStore.assertInteractiveSession?.(sessionId);
+                    else
+                        await assertGlobalInteractiveSession(sessionId);
+                }
+            }
+            catch (error) {
+                if (!isAutomationSessionLockedError(error))
+                    throw error;
+                currentWs.send(JSON.stringify({
+                    type: "failed",
+                    requestId,
+                    sessionId,
+                    error: "automation_session_locked",
+                }));
+                return;
+            }
             const steeringInbox = requestSteering.open(requestId);
             try {
                 await requestHandler.handle(currentWs, msg, {

package/dist/src/capabilities/normal-invocation/contracts.d.ts

@@ -1,5 +1,6 @@
 export declare const TOOL_NORMAL_INVOCATION_VERSION: 1;
 export declare const TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH = 64;
+export declare const TOOL_NORMAL_INVOCATION_STRING_MAX_LENGTH = 8192;
 export declare const TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES: number;
 export type ToolNormalInvocationEffect = "read_only" | "mutating" | "mixed";
 export type ToolNormalInvocationApproval = "request_policy" | "always";
@@ -51,6 +52,15 @@ export type ToolNormalInvocationPayload = Readonly<{
     minBytes?: number;
     maxBytes: number;
 }>;
+/** A declared operation input that can resolve a request-owned attachment ID. */
+export type ToolNormalInvocationAttachmentInput = Readonly<{
+    param: string;
+    acceptedMimeTypes: readonly string[];
+    mode?: Readonly<{
+        param: string;
+        value: string;
+    }>;
+}>;
 export type ToolNormalInvocationOperation = Readonly<{
     operationId: string;
     summary: string;
@@ -58,6 +68,7 @@ export type ToolNormalInvocationOperation = Readonly<{
     selectionControlIds?: readonly string[];
     fixedParams?: Readonly<Record<string, ToolNormalInvocationFixedValue>>;
     payload?: ToolNormalInvocationPayload;
+    attachmentInput?: ToolNormalInvocationAttachmentInput;
     effect: ToolNormalInvocationEffect;
     approval: ToolNormalInvocationApproval;
 }>;

package/dist/src/capabilities/normal-invocation/contracts.js

@@ -1,3 +1,4 @@
 export const TOOL_NORMAL_INVOCATION_VERSION = 1;
 export const TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH = 64;
+export const TOOL_NORMAL_INVOCATION_STRING_MAX_LENGTH = 8_192;
 export const TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES = 16 * 1_024 * 1_024;

package/dist/src/capabilities/normal-invocation/validator.js

@@ -1,10 +1,9 @@
-import { TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH, TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES, TOOL_NORMAL_INVOCATION_VERSION, } from "./contracts.js";
+import { TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH, TOOL_NORMAL_INVOCATION_STRING_MAX_LENGTH as MAX_STRING_LENGTH_BOUND, TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES, TOOL_NORMAL_INVOCATION_VERSION, } from "./contracts.js";
 const MAX_OPERATIONS = 32;
 const MAX_SUMMARY_LENGTH = 512;
 const MAX_INSTRUCTIONS_LENGTH = 1_024;
 const MAX_PROPERTIES = 16;
 const MAX_FIXED_PARAMS = 16;
-const MAX_STRING_LENGTH_BOUND = 4_096;
 const MAX_ENUM_VALUES = 64;
 const MAX_ENUM_VALUE_LENGTH = 256;
 const MAX_ARRAY_ITEMS_BOUND = 64;
@@ -250,10 +249,45 @@ function parsePayload(toolName, path, raw) {
         maxBytes,
     });
 }
+function parseAttachmentInput(toolName, path, input, value) {
+    if (value === undefined)
+        return undefined;
+    if (!isPlainObject(value) ||
+        !hasExactKeys(value, ["param", "acceptedMimeTypes"], ["mode"]))
+        fail(toolName, path, "expected param, acceptedMimeTypes and optional mode");
+    const param = identifier(toolName, `${path}.param`, value.param);
+    const source = input.properties[param];
+    if (!source || source.type !== "string")
+        fail(toolName, `${path}.param`, "expected a string input property");
+    const rawTypes = value.acceptedMimeTypes;
+    if (!Array.isArray(rawTypes) || rawTypes.length < 1 || rawTypes.length > 32 ||
+        rawTypes.some((mime) => typeof mime !== "string" ||
+            !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/u.test(mime)) ||
+        new Set(rawTypes).size !== rawTypes.length)
+        fail(toolName, `${path}.acceptedMimeTypes`, "expected 1-32 distinct MIME types");
+    let mode;
+    if (value.mode !== undefined) {
+        if (!isPlainObject(value.mode) ||
+            !hasExactKeys(value.mode, ["param", "value"]))
+            fail(toolName, `${path}.mode`, "expected param and value");
+        const modeParam = identifier(toolName, `${path}.mode.param`, value.mode.param);
+        const modeValue = identifier(toolName, `${path}.mode.value`, value.mode.value);
+        const modeInput = input.properties[modeParam];
+        if (!modeInput || modeInput.type !== "string" ||
+            ("enum" in modeInput && !modeInput.enum.includes(modeValue)))
+            fail(toolName, `${path}.mode`, "expected a permitted string input value");
+        mode = Object.freeze({ param: modeParam, value: modeValue });
+    }
+    return Object.freeze({
+        param,
+        acceptedMimeTypes: Object.freeze([...rawTypes]),
+        ...(mode ? { mode } : {}),
+    });
+}
 function parseOperation(toolName, path, raw) {
     if (!isPlainObject(raw) ||
-        !hasExactKeys(raw, ["operationId", "summary", "input", "effect", "approval"], ["selectionControlIds", "fixedParams", "payload"])) {
-        fail(toolName, path, "operation must contain operationId/summary/input/effect/approval and optional selectionControlIds/fixedParams/payload");
+        !hasExactKeys(raw, ["operationId", "summary", "input", "effect", "approval"], ["selectionControlIds", "fixedParams", "payload", "attachmentInput"])) {
+        fail(toolName, path, "operation must contain operationId/summary/input/effect/approval and optional selectionControlIds/fixedParams/payload/attachmentInput");
     }
     if (raw.effect !== "read_only" &&
         raw.effect !== "mutating" &&
@@ -267,6 +301,7 @@ function parseOperation(toolName, path, raw) {
     const selectionControlIds = parseSelectionControlIds(toolName, `${path}.selectionControlIds`, input, raw.selectionControlIds);
     const fixedParams = parseFixedParams(toolName, `${path}.fixedParams`, raw.fixedParams);
     const payload = parsePayload(toolName, `${path}.payload`, raw.payload);
+    const attachmentInput = parseAttachmentInput(toolName, `${path}.attachmentInput`, input, raw.attachmentInput);
     const overlaps = new Set(Object.keys(input.properties));
     for (const fixedName of Object.keys(fixedParams ?? {})) {
         if (overlaps.has(fixedName)) {
@@ -284,6 +319,7 @@ function parseOperation(toolName, path, raw) {
         ...(selectionControlIds ? { selectionControlIds } : {}),
         ...(fixedParams ? { fixedParams } : {}),
         ...(payload ? { payload } : {}),
+        ...(attachmentInput ? { attachmentInput } : {}),
         effect: raw.effect,
         approval: raw.approval,
     });

package/dist/src/capabilities/result-budget.d.ts

@@ -0,0 +1,17 @@
+import type { ToolImplementationOutput } from "./tool-types.js";
+/** Bounds receipt/metadata bytes; declared context text uses model admission. */
+export declare const CAPABILITY_RESULT_ENVELOPE_MAX_BYTES: number;
+export type ToolResultBudgetAssessment = Readonly<{
+    fits: boolean;
+    serializedBytes: number;
+    envelopeBytes?: number;
+    contextTextBytes?: number;
+    maxBytes: number;
+}>;
+/** Bound by the host to this invocation's complete delivery envelope. */
+export type ToolResultBudget = Readonly<{
+    /** Host support for exact text admitted later by its existing context gate. */
+    acceptsContextText?: true;
+    assess(result: ToolImplementationOutput): ToolResultBudgetAssessment;
+}>;
+export declare function assessResultEnvelopeBytes(envelope: unknown, contextTextBytes?: number): ToolResultBudgetAssessment;

package/dist/src/capabilities/result-budget.js

@@ -0,0 +1,21 @@
+/** Bounds receipt/metadata bytes; declared context text uses model admission. */
+export const CAPABILITY_RESULT_ENVELOPE_MAX_BYTES = 256 * 1024;
+export function assessResultEnvelopeBytes(envelope, contextTextBytes = 0) {
+    const serialized = JSON.stringify(envelope);
+    if (serialized === undefined)
+        throw new TypeError("result_envelope_not_json_safe");
+    const serializedBytes = Buffer.byteLength(serialized, "utf8");
+    const envelopeBytes = serializedBytes - contextTextBytes;
+    const hasValidEnvelopeAccounting = Number.isSafeInteger(contextTextBytes) &&
+        contextTextBytes >= 0 &&
+        envelopeBytes >= 0;
+    if (!hasValidEnvelopeAccounting)
+        throw new TypeError("result_envelope_accounting_invalid");
+    return Object.freeze({
+        fits: envelopeBytes <= CAPABILITY_RESULT_ENVELOPE_MAX_BYTES,
+        serializedBytes,
+        envelopeBytes,
+        contextTextBytes,
+        maxBytes: CAPABILITY_RESULT_ENVELOPE_MAX_BYTES,
+    });
+}

package/dist/src/capabilities/tool-context-text.d.ts

@@ -0,0 +1,16 @@
+/** Exact tool text whose model admission belongs to the runtime context gate. */
+export type ToolContextTextField = "output" | "stdout" | "stderr";
+type ContextTextCarrier = Readonly<{
+    contextTextFields?: unknown;
+    output?: unknown;
+    stdout?: unknown;
+    stderr?: unknown;
+}>;
+/** The declaration changes byte accounting only, never evidence or authority. */
+export declare function hasValidToolContextText(carrier: ContextTextCarrier): boolean;
+/**
+ * Counts only JSON-encoded text content. Property names and string delimiters
+ * remain charged to the envelope. No original text is removed or rewritten.
+ */
+export declare function measureToolContextTextBytes(carrier: ContextTextCarrier): number;
+export {};

package/dist/src/capabilities/tool-context-text.js

@@ -0,0 +1,30 @@
+/** The declaration changes byte accounting only, never evidence or authority. */
+export function hasValidToolContextText(carrier) {
+    const fields = carrier.contextTextFields;
+    if (fields === undefined)
+        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";
+}
+/**
+ * Counts only JSON-encoded text content. Property names and string delimiters
+ * remain charged to the envelope. No original text is removed or rewritten.
+ */
+export function measureToolContextTextBytes(carrier) {
+    if (!hasValidToolContextText(carrier))
+        throw new TypeError("tool_context_text_invalid");
+    const fields = carrier.contextTextFields;
+    return (fields ?? []).reduce((total, field) => total + Buffer.byteLength(JSON.stringify(carrier[field]), "utf8") - 2, 0);
+}

package/dist/src/capabilities/tool-definition-validator/definition-parser.js

@@ -8,6 +8,7 @@ export function parseToolDefinition(raw) {
         throw new Error("Invalid tool definition entry (not an object)");
     }
     const name = raw.name;
+    const pluginName = raw.pluginName;
     const description = raw.description;
     const routingCapability = raw.routingCapability;
     const controlsRefinement = raw.controlsRefinement;
@@ -22,6 +23,10 @@ export function parseToolDefinition(raw) {
     if (description !== undefined && typeof description !== "string") {
         throw new Error(`Invalid tool definition for ${name} (description)`);
     }
+    if (pluginName !== undefined &&
+        (typeof pluginName !== "string" || pluginName.trim().length === 0)) {
+        throw new Error(`Invalid tool definition for ${name} (pluginName)`);
+    }
     if (!isRoutingCapability(routingCapability)) {
         throw new Error(`Invalid tool definition for ${name} (routingCapability)`);
     }
@@ -49,6 +54,7 @@ export function parseToolDefinition(raw) {
     const parsedEventPresentation = parseEventPresentation(name, eventPresentation);
     return {
         name,
+        ...(typeof pluginName === "string" ? { pluginName } : {}),
         requiredPermissionMode: parseRequiredToolPermissionMode(raw.requiredPermissionMode, `${name}.requiredPermissionMode`),
         ...(typeof description === "string" ? { description } : {}),
         routingCapability,

package/dist/src/capabilities/tool-definition-validator/event-input-text-options.js

@@ -1,3 +1,4 @@
+import { TOOL_EVENT_INPUT_TEXT_MAX_LENGTH } from "../tool-event-input-text.js";
 /** The same optional input-text contract applies to manifests and tool modules. */
 export function parseEventInputTextOptions(projection, path) {
     const { maxLength, preserveWhitespace } = projection;
@@ -10,7 +11,7 @@ export function parseEventInputTextOptions(projection, path) {
         throw new Error(`${path}.maxLength requires kind string`);
     }
     if (!hasSupportedInputTextLength(maxLength)) {
-        throw new Error(`${path}.maxLength must be an integer from 1 to 4096`);
+        throw new Error(`${path}.maxLength must be an integer from 1 to ${TOOL_EVENT_INPUT_TEXT_MAX_LENGTH}`);
     }
     if (!hasSupportedWhitespaceOption(preserveWhitespace)) {
         throw new Error(`${path}.preserveWhitespace must be a boolean`);
@@ -25,7 +26,7 @@ function hasSupportedInputTextLength(value) {
         return true;
     if (typeof value !== "number" || !Number.isInteger(value))
         return false;
-    return value >= 1 && value <= 4_096;
+    return value >= 1 && value <= TOOL_EVENT_INPUT_TEXT_MAX_LENGTH;
 }
 function hasSupportedWhitespaceOption(value) {
     if (value === undefined)

package/dist/src/capabilities/tool-event-input-text.d.ts

@@ -1,4 +1,5 @@
 import type { ToolEventMetadataProjection } from "./tool-types.js";
+export declare const TOOL_EVENT_INPUT_TEXT_MAX_LENGTH = 8192;
 /** Opt-in exact text stays display-only and never replaces the accepted input. */
 export declare function projectDeclaredInputText(raw: unknown, projection: ToolEventMetadataProjection): Readonly<{
     text: string;

package/dist/src/capabilities/tool-event-input-text.js

@@ -1,3 +1,4 @@
+export const TOOL_EVENT_INPUT_TEXT_MAX_LENGTH = 8_192;
 /** Opt-in exact text stays display-only and never replaces the accepted input. */
 export function projectDeclaredInputText(raw, projection) {
     if (typeof raw !== "string")
@@ -5,7 +6,7 @@ export function projectDeclaredInputText(raw, projection) {
     const text = projection.preserveWhitespace === true ? raw : raw.trim();
     if (text.length === 0)
         return undefined;
-    const limit = Math.min(4_096, projection.maxLength ?? 500);
+    const limit = Math.min(TOOL_EVENT_INPUT_TEXT_MAX_LENGTH, projection.maxLength ?? 500);
     let end = Math.min(text.length, limit);
     if (splitsInputTextSurrogatePair(text, end))
         end -= 1;

package/dist/src/capabilities/tool-executor.d.ts

@@ -1,11 +1,17 @@
-import type { ToolCall, ToolExecutionContext, ToolExecutionResult, ToolImplementation } from "./tool-types.js";
+import type { ToolCall, ToolExecutionContext, ToolExecutionResult, ToolImplementation, ToolUnderlyingSettlement } from "./tool-types.js";
 type ToolExecutorOptions = {
+    requestWork?: ToolExecutionContext["requestWork"];
+    requestState?: ToolExecutionContext["requestState"];
+    media?: ToolExecutionContext["media"];
+    resultBudget?: ToolExecutionContext["resultBudget"];
+    onRequestDispose?: ToolExecutionContext["onRequestDispose"];
     implementations?: Record<string, ToolImplementation>;
     abortSignal?: AbortSignal;
     sharedState?: ToolExecutionContext["sharedState"];
     modelInvoker?: ToolExecutionContext["modelInvoker"];
     runtimePathResolver?: ToolExecutionContext["runtimePathResolver"];
     reportFileOutput?: ToolExecutionContext["reportFileOutput"];
+    onUnderlyingSettlement?: (settled: Promise<ToolUnderlyingSettlement>) => void;
 };
 export declare function executeToolCall(call: ToolCall, options?: ToolExecutorOptions): Promise<ToolExecutionResult>;
 export {};

package/dist/src/capabilities/tool-executor.js

@@ -1,29 +1,27 @@
 import { traceDebug } from "../runtime/observability/debug-logger.js";
-function normalizeImplementationOutput(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        Array.isArray(value) ||
-        typeof value.ok !== "boolean" ||
-        typeof value.output !== "string" ||
-        typeof value.producedNewInformation !== "boolean") {
-        const error = new TypeError("tool implementations must return ok, output, and producedNewInformation");
-        error.code = "tool_result_invalid";
-        throw error;
-    }
-    const output = value.output;
-    return {
-        ok: value.ok,
-        output,
-        progress: value.progress === true,
-        producedNewInformation: value.producedNewInformation === true,
-        actions: Array.isArray(value.actions) ? value.actions : undefined,
-        exitCode: typeof value.exitCode === "number" ? value.exitCode : undefined,
-        stdout: typeof value.stdout === "string" ? value.stdout : undefined,
-        stderr: typeof value.stderr === "string" ? value.stderr : undefined,
-        data: value.data,
-        error: typeof value.error === "string" ? value.error : undefined,
-        errorCode: typeof value.errorCode === "string" ? value.errorCode : undefined,
-    };
+import { normalizeImplementationOutput, projectToolExecutionResult } from "./tool-result-normalization.js";
+function safeErrorCode(value) {
+    return typeof value === "string" && /^[a-z][a-z0-9_]{0,127}$/u.test(value)
+        ? value
+        : "tool_execution_failed";
+}
+function underlyingSettlement(execution) {
+    return execution.then((raw) => {
+        try {
+            const output = normalizeImplementationOutput(raw);
+            return {
+                status: "fulfilled",
+                ok: output.ok,
+                ...(output.errorCode ? { errorCode: safeErrorCode(output.errorCode) } : {}),
+            };
+        }
+        catch (error) {
+            return { status: "rejected", errorCode: safeErrorCode(error?.code) };
+        }
+    }, (error) => ({
+        status: "rejected",
+        errorCode: safeErrorCode(error?.code),
+    }));
 }
 function finalizeToolExecutionResult(result) {
     const progress = result.ok ? result.progress : false;
@@ -97,36 +95,24 @@ export async function executeToolCall(call, options = {}) {
             throw createToolAbortError(options.abortSignal.reason);
         }
         const execution = execute(call.params, {
+            requestWork: options.requestWork,
+            requestState: options.requestState,
+            media: options.media,
+            resultBudget: options.resultBudget,
+            onRequestDispose: options.onRequestDispose,
             abortSignal: options.abortSignal,
             sharedState: options.sharedState,
             modelInvoker: options.modelInvoker,
             runtimePathResolver: options.runtimePathResolver,
             reportFileOutput: options.reportFileOutput,
         });
+        // The public result may win the abort race while the implementation still
+        // owns a live external effect. Automation admission tracks that promise.
+        options.onUnderlyingSettlement?.(underlyingSettlement(execution));
         const rawOutput = options.abortSignal
             ? await raceWithAbort(execution, options.abortSignal)
             : await execution;
-        const normalized = normalizeImplementationOutput(rawOutput);
-        return finalizeToolExecutionResult({
-            ok: normalized.ok,
-            tool: call.tool,
-            output: normalized.output,
-            progress: normalized.progress,
-            producedNewInformation: normalized.producedNewInformation,
-            ...(normalized.actions ? { actions: normalized.actions } : {}),
-            ...(typeof normalized.exitCode === "number"
-                ? { exitCode: normalized.exitCode }
-                : {}),
-            ...(typeof normalized.stdout === "string"
-                ? { stdout: normalized.stdout }
-                : {}),
-            ...(typeof normalized.stderr === "string"
-                ? { stderr: normalized.stderr }
-                : {}),
-            ...(normalized.data ? { data: normalized.data } : {}),
-            ...(normalized.error ? { error: normalized.error } : {}),
-            ...(normalized.errorCode ? { errorCode: normalized.errorCode } : {}),
-        });
+        return finalizeToolExecutionResult(projectToolExecutionResult(call.tool, rawOutput));
     }
     catch (error) {
         if (options.abortSignal?.aborted || isAbortLikeError(error)) {
@@ -138,6 +124,7 @@ export async function executeToolCall(call, options = {}) {
                 producedNewInformation: false,
                 error: "tool execution aborted",
                 errorCode: "request_aborted",
+                interruption: "aborted",
             });
         }
         const message = error?.message || "tool execution failed";

package/dist/src/capabilities/tool-interruption.d.ts

@@ -0,0 +1,3 @@
+import type { ToolExecutionResult } from "./tool-types.js";
+/** Adapter provenance and the executor's legacy abort receipt share one meaning. */
+export declare function hasToolAbortReceipt(result: Pick<ToolExecutionResult, "ok" | "errorCode" | "interruption">): boolean;

package/dist/src/capabilities/tool-interruption.js

@@ -0,0 +1,6 @@
+/** Adapter provenance and the executor's legacy abort receipt share one meaning. */
+export function hasToolAbortReceipt(result) {
+    if (result.ok)
+        return false;
+    return result.interruption === "aborted" || result.errorCode === "request_aborted";
+}

package/dist/src/capabilities/tool-media.d.ts

@@ -0,0 +1,21 @@
+/** Opaque image evidence issued by an admitted execution, never a file path. */
+export type ToolImageEvidence = Readonly<{
+    kind: "tool_image_v1";
+    id: string;
+    mimeType: "image/png";
+    size: number;
+    width: number;
+    height: number;
+    sha256: string;
+}>;
+export type ToolMediaWriter = Readonly<{
+    writeImage(input: Readonly<{
+        bytes: Uint8Array;
+        mimeType: string;
+    }>): Promise<ToolImageEvidence>;
+}>;
+export type ToolRequestDisposer = (callback: () => void | Promise<void>) => void;
+export declare const TOOL_IMAGE_MAX_BYTES: number;
+export declare const TOOL_RESULT_IMAGE_LIMIT = 4;
+export declare function isToolImageEvidence(value: unknown): value is ToolImageEvidence;
+export declare function isToolResultMedia(value: unknown): value is readonly ToolImageEvidence[] | undefined;

package/dist/src/capabilities/tool-media.js

@@ -0,0 +1,39 @@
+export const TOOL_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+export const TOOL_RESULT_IMAGE_LIMIT = 4;
+const IMAGE_FIELDS = new Set([
+    "kind", "id", "mimeType", "size", "width", "height", "sha256",
+]);
+export function isToolImageEvidence(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const item = value;
+    if (Object.keys(item).some((key) => !IMAGE_FIELDS.has(key)))
+        return false;
+    if (item.kind !== "tool_image_v1" || item.mimeType !== "image/png")
+        return false;
+    if (typeof item.id !== "string" || !/^image-[a-f0-9-]{36}$/u.test(item.id))
+        return false;
+    if (typeof item.sha256 !== "string" || !/^[a-f0-9]{64}$/u.test(item.sha256))
+        return false;
+    if (!isBoundedImageInteger(item.size, TOOL_IMAGE_MAX_BYTES))
+        return false;
+    if (!isBoundedImageInteger(item.width, 32768))
+        return false;
+    if (!isBoundedImageInteger(item.height, 32768))
+        return false;
+    return item.width * item.height <= 64 * 1024 * 1024;
+}
+function isBoundedImageInteger(value, maximum) {
+    if (!Number.isSafeInteger(value))
+        return false;
+    return value > 0 && value <= maximum;
+}
+export function isToolResultMedia(value) {
+    if (value === undefined)
+        return true;
+    if (!Array.isArray(value) || value.length > TOOL_RESULT_IMAGE_LIMIT)
+        return false;
+    if (!value.every(isToolImageEvidence))
+        return false;
+    return new Set(value.map(({ id }) => id)).size === value.length;
+}

package/dist/src/capabilities/tool-request-resources.d.ts

@@ -0,0 +1,17 @@
+import type { ToolRequestDisposer } from "./tool-media.js";
+/** Request-local effects that remain active after a tool returned. */
+export type ToolRequestWork = Readonly<{
+    trackUntil(settled: Promise<void>): void;
+}>;
+/** Plugin-owned JSON data, restored only when the owner is instantiated. */
+export type ToolRequestState = Readonly<{
+    read(key: string): unknown;
+    register(key: string, codec: Readonly<{
+        snapshot(): unknown;
+        dispose?(): void | Promise<void>;
+    }>): void;
+}>;
+export type ToolRequestPreparationContext = Readonly<{
+    requestState?: ToolRequestState;
+    onRequestDispose?: ToolRequestDisposer;
+}>;

package/dist/src/capabilities/tool-request-resources.js

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

package/dist/src/capabilities/tool-result-normalization.d.ts

@@ -0,0 +1,18 @@
+import type { ToolImplementationOutput, ToolExecutionResult, ToolActionSummary } from "./tool-types.js";
+export declare function normalizeImplementationOutput(value: ToolImplementationOutput): {
+    contextTextFields?: ToolImplementationOutput["contextTextFields"];
+    interruption?: ToolImplementationOutput["interruption"];
+    media?: ToolImplementationOutput["media"];
+    ok: boolean;
+    output: string;
+    progress: boolean;
+    producedNewInformation: boolean;
+    actions?: ToolActionSummary[];
+    exitCode?: number;
+    stdout?: string;
+    stderr?: string;
+    data?: ToolExecutionResult["data"];
+    error?: string;
+    errorCode?: string;
+};
+export declare function projectToolExecutionResult(tool: string, rawOutput: ToolImplementationOutput): ToolExecutionResult;