@abot-ai/runtime 1.5.0 → 1.7.0

package/README.md

@@ -8,6 +8,8 @@ plugins, model routing, persisted events, and a local graphical interface. It
 does not choose a model for you or hide model-provider behavior behind
 hardcoded defaults.
 
+[Website](https://abot-ai.com/) · [Documentation](#documentation) · [GitHub](https://github.com/Dorshitrit/abot-runtime)
+
 ## Features
 
 - Configurable local and hosted model providers

package/dist/src/bridge/request-steering.js

@@ -1,4 +1,4 @@
-import { traceDebug } from "../runtime/observability/debug-logger.js";
+import { createRequestControlDiagnosticId, diagnosticErrorType, traceRequestControl, } from "../runtime/observability/request-control-diagnostics.js";
 import { createRequestSteeringInbox, } from "../runtime/request/request-steering.js";
 const LOG_SCOPE = "agent-bridge.request_steering";
 export function createBridgeRequestSteeringRegistry(steer) {
@@ -8,10 +8,16 @@ export function createBridgeRequestSteeringRegistry(steer) {
             const current = active.get(requestId);
             if (current?.inbox === inbox) {
                 active.delete(requestId);
+                traceRequestControl(LOG_SCOPE, "request.removed", {
+                    requestId,
+                    inboxId: current.inboxId,
+                    source: "bridge_handler_settled",
+                });
             }
             await inbox.close();
-            traceDebug(LOG_SCOPE, "request.closed", {
+            traceRequestControl(LOG_SCOPE, "request.closed", {
                 requestId,
+                inboxId: current?.inboxId,
                 activeRequestCount: active.size,
             });
         },
@@ -23,13 +29,33 @@ export function createBridgeRequestSteeringRegistry(steer) {
             const steerId = readString(message.steerId).trim();
             const text = readString(message.text).trim();
             const current = active.get(requestId);
-            const result = (steer && current
-                ? await steer(requestId, { steerId, text })
-                : current?.inbox.append({ steerId, text })) ??
-                Object.freeze({
-                    ok: false,
-                    reason: "request_not_active",
+            const diagnosticScope = {
+                requestId,
+                steerId,
+                inboxId: current?.inboxId,
+                registryPresent: Boolean(current),
+                ownerSteerAvailable: Boolean(steer),
+                textLength: text.length,
+            };
+            traceRequestControl(LOG_SCOPE, "message.received", diagnosticScope);
+            let result;
+            try {
+                result =
+                    (steer && current
+                        ? await steer(requestId, { steerId, text })
+                        : current?.inbox.append({ steerId, text })) ??
+                        Object.freeze({
+                            ok: false,
+                            reason: "request_not_active",
+                        });
+            }
+            catch (error) {
+                traceRequestControl(LOG_SCOPE, "message.failed", {
+                    ...diagnosticScope,
+                    errorType: diagnosticErrorType(error),
                 });
+                throw error;
+            }
             const response = result.ok
                 ? {
                     type: "steer_ack",
@@ -45,10 +71,9 @@ export function createBridgeRequestSteeringRegistry(steer) {
                     accepted: false,
                     reason: result.reason,
                 };
-            await sendJson(ws, response);
-            traceDebug(LOG_SCOPE, result.ok ? "message.accepted" : "message.rejected", {
-                requestId,
-                steerId,
+            traceRequestControl(LOG_SCOPE, result.ok ? "message.accepted" : "message.rejected", {
+                ...diagnosticScope,
+                registryUnchanged: active.get(requestId) === current,
                 accepted: result.ok,
                 ...(result.ok
                     ? {
@@ -58,6 +83,21 @@ export function createBridgeRequestSteeringRegistry(steer) {
                     }
                     : { reason: result.reason }),
             });
+            traceRequestControl(LOG_SCOPE, "ack.dispatch_attempted", {
+                ...diagnosticScope,
+                accepted: result.ok,
+                readyState: ws.readyState,
+            });
+            try {
+                await sendJson(ws, response);
+            }
+            catch (error) {
+                traceRequestControl(LOG_SCOPE, "ack.dispatch_failed", {
+                    ...diagnosticScope,
+                    errorType: diagnosticErrorType(error),
+                });
+                throw error;
+            }
             return true;
         },
         open(requestId) {
@@ -67,10 +107,15 @@ export function createBridgeRequestSteeringRegistry(steer) {
             if (active.has(requestId)) {
                 throw new Error("request_steering_request_already_active");
             }
-            const inbox = createRequestSteeringInbox({ requestId });
-            active.set(requestId, Object.freeze({ inbox, requestId }));
-            traceDebug(LOG_SCOPE, "request.opened", {
+            const inboxId = createRequestControlDiagnosticId("inbox");
+            const inbox = createRequestSteeringInbox({
+                requestId,
+                diagnostics: { inboxId, origin: "bridge_projection" },
+            });
+            active.set(requestId, Object.freeze({ inbox, requestId, inboxId }));
+            traceRequestControl(LOG_SCOPE, "request.opened", {
                 requestId,
+                inboxId,
                 activeRequestCount: active.size,
             });
             return inbox;

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,8 @@
+import type { ToolNormalInvocationOutputChannels } from "./output-channels.js";
+export type { ToolNormalInvocationOutputChannels, ToolNormalInvocationOutputChannelRole } from "./output-channels.js";
 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,13 +54,24 @@ 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;
+    outputChannels?: ToolNormalInvocationOutputChannels;
     input: ToolNormalInvocationInput;
     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/output-channels.d.ts

@@ -0,0 +1,10 @@
+/** Passive descriptions of saved Studio output; not execution guarantees or binding defaults. */
+export type ToolNormalInvocationOutputChannelRole = "content" | "metadata" | "conditional";
+export type ToolNormalInvocationOutputChannels = Readonly<{
+    text: ToolNormalInvocationOutputChannelRole;
+    data: ToolNormalInvocationOutputChannelRole;
+}>;
+/** Shared by manifest and normal-invocation validation; omission stays undeclared. */
+export declare function parseOptionalToolOutputChannels(value: unknown, path: string): Readonly<{
+    outputChannels?: ToolNormalInvocationOutputChannels;
+}>;

package/dist/src/capabilities/normal-invocation/output-channels.js

@@ -0,0 +1,29 @@
+function isOutputChannelsRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function hasExactOutputChannelKeys(value) {
+    if (Object.keys(value).length !== 2)
+        return false;
+    return Object.hasOwn(value, "text") && Object.hasOwn(value, "data");
+}
+function requireOutputChannelRole(value, path) {
+    if (value === "content" || value === "metadata" || value === "conditional")
+        return value;
+    throw new Error(`${path} must be content, metadata, or conditional`);
+}
+/** Shared by manifest and normal-invocation validation; omission stays undeclared. */
+export function parseOptionalToolOutputChannels(value, path) {
+    if (value === undefined)
+        return {};
+    if (!isOutputChannelsRecord(value))
+        throw new Error(`${path} must be an object`);
+    if (!hasExactOutputChannelKeys(value))
+        throw new Error(`${path} must contain only text and data`);
+    return { outputChannels: Object.freeze({
+            text: requireOutputChannelRole(value.text, `${path}.text`),
+            data: requireOutputChannelRole(value.data, `${path}.data`),
+        }) };
+}

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

@@ -1,10 +1,10 @@
-import { TOOL_NORMAL_INVOCATION_IDENTIFIER_MAX_LENGTH, TOOL_NORMAL_INVOCATION_PAYLOAD_MAX_BYTES, TOOL_NORMAL_INVOCATION_VERSION, } from "./contracts.js";
+import { parseOptionalToolOutputChannels } from "./output-channels.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 +250,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", "outputChannels"])) {
+        fail(toolName, path, "operation must contain operationId/summary/input/effect/approval and optional selectionControlIds/fixedParams/payload/attachmentInput/outputChannels");
     }
     if (raw.effect !== "read_only" &&
         raw.effect !== "mutating" &&
@@ -267,6 +302,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)) {
@@ -280,10 +316,12 @@ function parseOperation(toolName, path, raw) {
     return Object.freeze({
         operationId: identifier(toolName, `${path}.operationId`, raw.operationId),
         summary: boundedText(toolName, `${path}.summary`, raw.summary, MAX_SUMMARY_LENGTH),
+        ...parseOptionalToolOutputChannels(raw.outputChannels, `${toolName}.${path}.outputChannels`),
         input,
         ...(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;