@abot-ai/runtime 1.5.0 → 1.6.0

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,8 +1,9 @@
-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;
@@ -10,6 +11,7 @@ type ToolExecutorOptions = {
     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,32 +1,27 @@
 import { traceDebug } from "../runtime/observability/debug-logger.js";
-import { isToolResultMedia } from "./tool-media.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" ||
-        !isToolResultMedia(value.media)) {
-        const error = new TypeError("tool implementations must return ok, output, and producedNewInformation");
-        error.code = "tool_result_invalid";
-        throw error;
-    }
-    const output = value.output;
-    return {
-        ...(value.media ? { media: value.media } : {}),
-        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;
@@ -103,6 +98,7 @@ export async function executeToolCall(call, options = {}) {
             requestWork: options.requestWork,
             requestState: options.requestState,
             media: options.media,
+            resultBudget: options.resultBudget,
             onRequestDispose: options.onRequestDispose,
             abortSignal: options.abortSignal,
             sharedState: options.sharedState,
@@ -110,31 +106,13 @@ export async function executeToolCall(call, options = {}) {
             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.media ? { media: normalized.media } : {}),
-            ...(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)) {
@@ -146,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-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;

package/dist/src/capabilities/tool-result-normalization.js

@@ -0,0 +1,68 @@
+import { isToolResultMedia } from "./tool-media.js";
+import { hasValidToolContextText } from "./tool-context-text.js";
+export function normalizeImplementationOutput(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.ok !== "boolean" ||
+        typeof value.output !== "string" ||
+        typeof value.producedNewInformation !== "boolean" ||
+        !isToolResultMedia(value.media) ||
+        !hasValidToolContextText(value)) {
+        const error = new TypeError("tool implementations must return ok, output, and producedNewInformation");
+        error.code = "tool_result_invalid";
+        throw error;
+    }
+    const output = value.output;
+    const hasFailedInterruption = !value.ok && value.interruption === "aborted";
+    return {
+        ...(value.contextTextFields
+            ? { contextTextFields: Object.freeze([...value.contextTextFields]) }
+            : {}),
+        ...(hasFailedInterruption ? { interruption: value.interruption } : {}),
+        ...(value.media ? { media: value.media } : {}),
+        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,
+    };
+}
+export function projectToolExecutionResult(tool, rawOutput) {
+    const normalized = normalizeImplementationOutput(rawOutput);
+    return {
+        ok: normalized.ok,
+        ...(normalized.contextTextFields
+            ? { contextTextFields: normalized.contextTextFields }
+            : {}),
+        ...(normalized.interruption
+            ? { interruption: normalized.interruption }
+            : {}),
+        tool,
+        output: normalized.output,
+        progress: normalized.ok ? normalized.progress : false,
+        producedNewInformation: normalized.ok
+            ? normalized.producedNewInformation
+            : false,
+        ...(normalized.media ? { media: normalized.media } : {}),
+        ...(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 } : {}),
+    };
+}

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

@@ -1,3 +1,5 @@
+import type { ToolResultBudget } from "./result-budget.js";
+import type { ToolContextTextField } from "./tool-context-text.js";
 import type { ToolRequestWork, ToolRequestState, ToolRequestPreparationContext } from "./tool-request-resources.js";
 import type { ToolPermissionMode, ToolRequiredPermissionMode } from "./tool-permission-mode.js";
 import type { ModelStep } from "../shared/types.js";
@@ -5,13 +7,22 @@ import type { RuntimeAttachmentKind } from "../shared/attachments.js";
 import type { ToolImageEvidence, ToolMediaWriter, ToolRequestDisposer } from "./tool-media.js";
 import type { ToolNormalInvocationContract } from "./normal-invocation/contracts.js";
 import type { ToolFileOutputReporter } from "./file-output-presentation.js";
-export type { ToolNormalInvocationApproval, ToolNormalInvocationArrayInput, ToolNormalInvocationBooleanInput, ToolNormalInvocationBoundedStringInput, ToolNormalInvocationContract, ToolNormalInvocationEnumInput, ToolNormalInvocationEffect, ToolNormalInvocationFixedValue, ToolNormalInvocationInput, ToolNormalInvocationInputValidation, ToolNormalInvocationNumberInput, ToolNormalInvocationOperation, ToolNormalInvocationPayload, ToolNormalInvocationPropertyInput, ToolNormalInvocationScalarInput, ToolNormalInvocationUnboundedStringInput, } from "./normal-invocation/contracts.js";
+export type { ToolNormalInvocationApproval, ToolNormalInvocationAttachmentInput, ToolNormalInvocationArrayInput, ToolNormalInvocationBooleanInput, ToolNormalInvocationBoundedStringInput, ToolNormalInvocationContract, ToolNormalInvocationEnumInput, ToolNormalInvocationEffect, ToolNormalInvocationFixedValue, ToolNormalInvocationInput, ToolNormalInvocationInputValidation, ToolNormalInvocationNumberInput, ToolNormalInvocationOperation, ToolNormalInvocationPayload, ToolNormalInvocationPropertyInput, ToolNormalInvocationScalarInput, ToolNormalInvocationUnboundedStringInput, } from "./normal-invocation/contracts.js";
 export type ToolRoutingCapability = "filesystem_inspection" | "filesystem_mutation" | "semantic_lookup" | "semantic_mutation" | "web_lookup";
 export type ToolDevelopmentRole = "inspect" | "establish" | "mutate" | "verify" | "auxiliary";
 export declare const TOOL_CATALOG_GROUP_ID_MAX_LENGTH = 128;
 export type ToolCatalogGroup = string;
 export declare function isToolCatalogGroupId(input: unknown): input is ToolCatalogGroup;
 export type ToolExecutionEffect = "read_only" | "mutating" | "mixed";
+/** Bounded, content-free evidence from an implementation after its public abort race. */
+export type ToolUnderlyingSettlement = Readonly<{
+    status: "fulfilled";
+    ok: boolean;
+    errorCode?: string;
+} | {
+    status: "rejected";
+    errorCode: string;
+}>;
 export type ToolControlsRefinement = "mechanical_when_complete";
 export type ToolEventMetadataProjection = Readonly<{
     param: string;
@@ -94,6 +105,8 @@ export type ToolRuntimePathBinding = Readonly<{
 export type ToolDefinition = {
     requiredPermissionMode?: ToolRequiredPermissionMode;
     name: string;
+    /** Runtime-owned provenance used when presenting tools by plugin. */
+    pluginName?: string;
     description?: string;
     routingCapability: ToolRoutingCapability;
     controlsRefinement?: ToolControlsRefinement;
@@ -156,7 +169,7 @@ export type ToolExecutionSharedState = {
 export type RuntimeToolPathLocation = "agent_work" | "workspace" | "runtime_root"
 /** Explicit opt-in for read-only tools that inspect arbitrary host paths. */
  | "host_system";
-export type RuntimeToolPathErrorCode = "runtime_tool_path_required" | "runtime_tool_path_null_byte" | "runtime_tool_path_location_required" | "runtime_tool_path_root_unavailable" | "runtime_tool_path_workspace_unavailable" | "runtime_tool_path_outside_configured_roots" | "runtime_tool_path_symlink_escape" | "runtime_tool_path_canonicalization_failed" | "runtime_tool_path_traversal" | "runtime_tool_path_outside_working_directory";
+export type RuntimeToolPathErrorCode = "runtime_tool_path_required" | "runtime_tool_path_null_byte" | "runtime_tool_path_namespace_invalid" | "runtime_tool_path_location_required" | "runtime_tool_path_root_unavailable" | "runtime_tool_path_workspace_unavailable" | "runtime_tool_path_outside_configured_roots" | "runtime_tool_path_symlink_escape" | "runtime_tool_path_canonicalization_failed" | "runtime_tool_path_traversal" | "runtime_tool_path_outside_working_directory";
 export type RuntimeToolPathError = TypeError & Readonly<{
     code: RuntimeToolPathErrorCode;
 }>;
@@ -184,6 +197,8 @@ export type ToolModelInvoker = Readonly<{
     }>): Promise<string>;
 }>;
 export type ToolExecutionContext = {
+    /** Delivery-envelope measurement; unrelated to the model context budget. */
+    resultBudget?: ToolResultBudget;
     requestWork?: ToolRequestWork;
     requestState?: ToolRequestState;
     media?: ToolMediaWriter;
@@ -266,6 +281,10 @@ export type ParsedToolCall = {
     repairHint?: string;
 };
 export type ToolExecutionResult = {
+    /** Exact text remains in its field; the runtime owns its context budget. */
+    contextTextFields?: readonly ToolContextTextField[];
+    /** Definite caller interruption; does not prove that a mutating effect was undone. */
+    interruption?: "aborted";
     media?: readonly ToolImageEvidence[];
     ok: boolean;
     tool: string;
@@ -291,6 +310,10 @@ export type ToolExecutionResult = {
     errorCode?: string;
 };
 export type ToolImplementationOutput = {
+    /** Opt-in delivery contract, supported only by a context-aware host. */
+    contextTextFields?: readonly ToolContextTextField[];
+    /** Set only when this failed operation was interrupted by its caller's signal. */
+    interruption?: "aborted";
     media?: readonly ToolImageEvidence[];
     ok: boolean;
     output: string;