@abot-ai/runtime 1.8.0 → 1.9.0

package/dist/src/model-gateway/client/chat.js

@@ -1,6 +1,7 @@
 import { traceDebug } from "../../runtime/observability/debug-logger.js";
 import { permitsModelContentTrace } from "../observability/content-trace-policy.js";
 import { buildModelInvocationMetrics } from "./invocation-metrics.js";
+import { fetchModelGatewayResponse, ModelGatewayInvocationError, } from "./invocation-error.js";
 import { buildChatGatewayRequestBody, resolveMetricMessages, resolveRequestMessages, } from "./message-projection.js";
 import { resolveClientOptions } from "./options.js";
 import { ChatStreamAccumulator, classifyEmptyResponse, InactivityBoundStreamReader, } from "./stream-consumer.js";
@@ -24,14 +25,16 @@ export async function invokeModelGatewayWithOptions(params, options = {}) {
         textLength: typeof params.text === "string" ? params.text.length : 0,
         messageCount: requestMessages.length,
     });
-    const response = await fetch(url + "/chat", {
+    const serializedRequestBody = JSON.stringify(requestBody);
+    const response = await fetchModelGatewayResponse(url + "/chat", {
         method: "POST",
         headers: {
             "Content-Type": "application/json",
         },
         signal: params.abortSignal,
-        body: JSON.stringify(requestBody),
-    });
+        body: serializedRequestBody,
+    }, params.abortSignal);
+    params.abortSignal.throwIfAborted();
     traceDebug("model-gateway.client", "chat.response.received", {
         requestId,
         status: response.status,
@@ -39,6 +42,7 @@ export async function invokeModelGatewayWithOptions(params, options = {}) {
     });
     if (!response.ok) {
         const errorText = await response.text().catch(() => "");
+        params.abortSignal.throwIfAborted();
         traceDebug("model-gateway.client", "chat.response.error", {
             requestId,
             status: response.status,
@@ -47,13 +51,13 @@ export async function invokeModelGatewayWithOptions(params, options = {}) {
                 ? { bodyPreview: errorText.slice(0, 400) }
                 : { contentOmitted: true }),
         });
-        throw new Error(`bridge_request_failed:${response.status}:${permitsModelContentTrace(params.modelStep, params.messages) ? errorText || "empty error body" : "content omitted"}`);
+        throw new ModelGatewayInvocationError("http", `bridge_request_failed:${response.status}:${permitsModelContentTrace(params.modelStep, params.messages) ? errorText || "empty error body" : "content omitted"}`);
     }
     if (!response.body) {
         traceDebug("model-gateway.client", "chat.response.no_body", {
             requestId,
         });
-        throw new Error("no stream");
+        throw new ModelGatewayInvocationError("missing_stream", "no stream");
     }
     const streamReader = new InactivityBoundStreamReader(response.body.getReader(), params.abortSignal, clientOptions.getStreamInactivityTimeoutMs);
     const stream = new ChatStreamAccumulator(params);

package/dist/src/model-gateway/client/invocation-error.d.ts

@@ -0,0 +1,9 @@
+export type ModelGatewayInvocationFailureKind = "network" | "http" | "stream" | "inactivity" | "missing_stream";
+/** A failed transport attempt, distinct from local validation or callbacks. */
+export declare class ModelGatewayInvocationError extends Error {
+    readonly kind: ModelGatewayInvocationFailureKind;
+    constructor(kind: ModelGatewayInvocationFailureKind, message: string, options?: ErrorOptions);
+}
+export declare function wrapModelGatewayTransportError(kind: "network" | "stream", cause: unknown): ModelGatewayInvocationError;
+/** Only fetch rejection is classified; request construction stays with callers. */
+export declare function fetchModelGatewayResponse(url: string, init: RequestInit, abortSignal: AbortSignal): Promise<Response>;

package/dist/src/model-gateway/client/invocation-error.js

@@ -0,0 +1,30 @@
+/** A failed transport attempt, distinct from local validation or callbacks. */
+export class ModelGatewayInvocationError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.name = "ModelGatewayInvocationError";
+    }
+}
+export function wrapModelGatewayTransportError(kind, cause) {
+    return new ModelGatewayInvocationError(kind, readTransportFailureMessage(kind, cause), { cause });
+}
+function readTransportFailureMessage(kind, cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    if (typeof cause === "string")
+        return cause;
+    return `model_gateway_${kind}_failed`;
+}
+/** Only fetch rejection is classified; request construction stays with callers. */
+export async function fetchModelGatewayResponse(url, init, abortSignal) {
+    try {
+        return await fetch(url, init);
+    }
+    catch (error) {
+        if (abortSignal.aborted)
+            throw error;
+        throw wrapModelGatewayTransportError("network", error);
+    }
+}

package/dist/src/model-gateway/client/stream-consumer.js

@@ -1,4 +1,5 @@
 import { applyStreamLine, } from "../client-stream-parser.js";
+import { ModelGatewayInvocationError, wrapModelGatewayTransportError, } from "./invocation-error.js";
 function resolveAbortMessage(reason) {
     if (reason instanceof Error) {
         return reason.message;
@@ -53,9 +54,15 @@ export class InactivityBoundStreamReader {
                 void this.reader
                     .cancel("llm_stream_inactivity_timeout")
                     .catch(() => { });
-                settle(reject, createAbortError("llm_stream_inactivity_timeout"));
+                settle(reject, new ModelGatewayInvocationError("inactivity", "llm_stream_inactivity_timeout"));
             }, inactivityTimeoutMs);
-            void this.reader.read().then((result) => settle(resolve, result), (error) => settle(reject, error));
+            void this.reader.read().then((result) => settle(resolve, result), (error) => {
+                if (this.abortSignal.aborted) {
+                    settle(reject, createAbortError(this.abortSignal.reason));
+                    return;
+                }
+                settle(reject, wrapModelGatewayTransportError("stream", error));
+            });
         });
     }
 }

package/dist/src/model-gateway/client/stream-parser.js

@@ -1,4 +1,5 @@
 import { normalizeModelTokenUsage } from "../protocol/usage.js";
+import { ModelGatewayInvocationError } from "./invocation-error.js";
 function readText(value) {
     return typeof value === "string" ? value : "";
 }
@@ -51,7 +52,7 @@ function throwStreamError(message, data, callbacks) {
         kind: "error",
         text: errorText,
     });
-    throw new Error(`model_stream_error: ${errorText}`);
+    throw new ModelGatewayInvocationError("stream", `model_stream_error: ${errorText}`);
 }
 function readContentText(message, data) {
     return (readText(message.text) ||

package/dist/src/model-gateway/protocol/message-contract.d.ts

@@ -6,6 +6,7 @@ export declare function isModelGatewayToolCall(value: unknown): value is ModelGa
 export declare function isAssistantToolCallMessage(value: unknown): value is ChatAssistantToolCallMessage;
 export declare function isToolResultMessage(value: unknown): value is ChatToolResultMessage;
 export declare function isTextChatMessage(value: unknown): value is ChatTextMessage;
+export declare function isStrictTextChatMessage(value: unknown): value is ChatTextMessage;
 export declare function hasModelGatewayToolInteractionLane(value: unknown): boolean;
 /**
  * Enforces the native tool-call continuation protocol whenever any tool-lane

package/dist/src/model-gateway/protocol/message-contract.js

@@ -115,7 +115,7 @@ export function isTextChatMessage(value) {
         typeof value.content === "string" &&
         !Object.prototype.hasOwnProperty.call(value, "toolCalls"));
 }
-function isStrictTextChatMessage(value) {
+export function isStrictTextChatMessage(value) {
     if (!isRecord(value) ||
         !hasOnlyKeys(value, TEXT_MESSAGE_KEYS) ||
         !isTextChatMessage(value)) {

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

@@ -1,5 +1,6 @@
 import { resolveModelInvocation } from "../policy/invocation-policy.js";
 import { respondToGatewayHandlerError } from "./errors.js";
+import { writeChatStreamResponse } from "./chat-stream-response.js";
 import { sendText } from "./http-response.js";
 import { applyConfiguredModelPolicy, emitResolvedModelInvocation, validateImageInvocationSupport, validateMessageInteractionRequest, } from "./invocation-validation.js";
 import { createContextGuardedProviderFetch } from "./provider-fetch.js";
@@ -62,14 +63,11 @@ export function createChatHandler(options = {}, inputTokenMeasurements) {
             if (result.kind !== "chat") {
                 throw new Error("model_provider_adapter_chat_result_invalid");
             }
-            response.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
-            response.setHeader("Cache-Control", "no-cache");
-            await result.stream({
-                emit(event) {
-                    response.write(`${JSON.stringify(event)}\n`);
-                },
+            await writeChatStreamResponse({
+                invocation: result,
+                response,
+                abortSignal,
             });
-            response.end();
         }
         catch (error) {
             respondToGatewayHandlerError({

package/dist/src/model-gateway/server/chat-stream-response.d.ts

@@ -0,0 +1,7 @@
+import type { ModelProviderChatInvocation } from "../providers/contracts.js";
+import type { GatewayResponse } from "./contracts.js";
+export declare function writeChatStreamResponse(params: {
+    invocation: ModelProviderChatInvocation;
+    response: GatewayResponse;
+    abortSignal: AbortSignal;
+}): Promise<void>;

package/dist/src/model-gateway/server/chat-stream-response.js

@@ -0,0 +1,25 @@
+export async function writeChatStreamResponse(params) {
+    const { invocation, response, abortSignal } = params;
+    let hasEmittedEvent = false;
+    response.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
+    response.setHeader("Cache-Control", "no-cache");
+    try {
+        await invocation.stream({
+            emit(event) {
+                response.write(`${JSON.stringify(event)}\n`);
+                hasEmittedEvent = true;
+            },
+        });
+    }
+    catch (error) {
+        if (abortSignal.aborted)
+            return;
+        // Before the first write, the handler can still send its normal HTTP error.
+        if (!hasEmittedEvent)
+            throw error;
+        console.error(error);
+        response.end(`${JSON.stringify({ type: "error", error: "server error" })}\n`);
+        return;
+    }
+    response.end();
+}

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/approval.d.ts

@@ -1,7 +1,9 @@
 import type { ToolCall } from "../../../../capabilities/tool-types.js";
 import { type ToolEventExecutorIdentity } from "../shared/event-metadata.js";
 import type { ToolApprovalController, ToolApprovalRequest, ToolApprovalDecision, ToolPermissionMode } from "../../../ports.js";
-import type { RegisteredToolNormalInvocationRejection } from "../shared/contracts.js";
+import type { BoundOperation, RegisteredToolNormalInvocationRejection } from "../shared/contracts.js";
+/** Both accepted source and normalized target must share the core read exemption. */
+export declare function requiresRegisteredToolActionApproval(mode: ToolPermissionMode, source: BoundOperation, target: BoundOperation): boolean;
 export declare function requestNormalInvocationApproval(params: {
     preparedRequest?: ToolApprovalRequest;
     decision?: ToolApprovalDecision;
@@ -17,6 +19,8 @@ export declare function requestNormalInvocationApproval(params: {
     call: ToolCall;
     eventMeta?: Record<string, unknown>;
     force: boolean;
+    /** Captured operation policy; omitted for ordinary direct approval callers. */
+    requiredByOperationPolicy?: boolean;
 }): Promise<Readonly<{
     ok: true;
 }> | Readonly<{

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/approval.js

@@ -1,13 +1,27 @@
 import { requiresToolActionApproval } from "../../../../capabilities/tool-permission-mode.js";
+import { isCoreToolAutomaticRead } from "../../../capabilities/core-tool-contracts.js";
 import { buildToolExecutorEventMetadata, } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
+/** Both accepted source and normalized target must share the core read exemption. */
+export function requiresRegisteredToolActionApproval(mode, source, target) {
+    const force = source.operation.approval === "always" || target.operation.approval === "always";
+    if (!requiresToolActionApproval(mode, force))
+        return false;
+    if (force)
+        return true;
+    if (!isCoreToolAutomaticRead(source.registration.toolName, source.operation))
+        return true;
+    return !isCoreToolAutomaticRead(target.registration.toolName, target.operation);
+}
 function recommendsFullPlusForForcedAction(mode, force) {
     if (mode !== "full_access")
         return false;
     return force;
 }
 export async function requestNormalInvocationApproval(params) {
-    if (!requiresToolActionApproval(params.toolPermissionMode, params.force)) {
+    const required = params.requiredByOperationPolicy ??
+        requiresToolActionApproval(params.toolPermissionMode, params.force);
+    if (!required) {
         return Object.freeze({ ok: true });
     }
     const approvalId = params.preparedRequest?.approvalId ?? params.nextApprovalId();

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/prepared-execution.js

@@ -1,17 +1,17 @@
 import { createRegisteredToolResultBudget, assertRegisteredToolResultMetadataFits, } from "./result-budget.js";
 import { randomUUID } from "node:crypto";
-import { requiresToolActionApproval } from "../../../../capabilities/tool-permission-mode.js";
 import { buildToolCompletedEventActions, buildToolCompletedEventMetadata, buildToolLifecycleEventCopy, } from "../../../../capabilities/tool-event-metadata.js";
 import { buildToolExecutorEventMetadata, } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
-import { requestNormalInvocationApproval } from "./approval.js";
+import { requestNormalInvocationApproval, requiresRegisteredToolActionApproval } from "./approval.js";
 import { createPreparedInvocationRejectionEmitter } from "./rejection-event.js";
 import { createFileOutputPresentation } from "./file-output-presentation.js";
 import { executeWithToolResources } from "./tool-media-execution.js";
 export function createPreparedNormalInvocation(params) {
-    const force = params.source.operation.approval === "always" ||
-        params.target.operation.approval === "always";
-    const approvalRequest = requiresToolActionApproval(params.executor.toolPermissionMode, force)
+    // Keep an already-recorded approval pending across upgrades; new core reads skip it.
+    const requiresApproval = params.restoredApprovalRequest !== undefined ||
+        requiresRegisteredToolActionApproval(params.executor.toolPermissionMode, params.source, params.target);
+    const approvalRequest = requiresApproval
         ? Object.freeze({
             ...(params.restoredApprovalRequest ?? {
                 requestId: params.executor.requestId,
@@ -82,6 +82,8 @@ async function executePreparedNormalInvocation(params) {
     });
     assertRegisteredToolResultMetadataFits(resultBudget);
     const approval = await requestNormalInvocationApproval({
+        requiredByOperationPolicy: params.approvalRequest !== undefined ||
+            requiresRegisteredToolActionApproval(params.executor.toolPermissionMode, params.source, params.target),
         ...(params.approvalRequest
             ? { preparedRequest: params.approvalRequest }
             : {}),

package/dist/src/runtime/adapters/registered-tool-normal-invocations/execution/prepared-snapshot.js

@@ -3,6 +3,7 @@ import { createRegisteredToolActionFingerprint } from "../shared/action-fingerpr
 import { captureToolCall, resolveExactTargetOperation, validateCompleteCall, } from "./call-binding.js";
 import { captureExecutionBinding } from "./execution-binding.js";
 import { createPreparedNormalInvocation } from "./prepared-execution.js";
+import { requiresRegisteredToolActionApproval } from "./approval.js";
 /** Validate a saved exact call; restoration never invokes normalization or payload authoring. */
 export function restoreNormalInvocation(params) {
     const value = params.snapshot;
@@ -48,8 +49,14 @@ export function restoreNormalInvocation(params) {
         throw invalid();
     const force = source.operation.approval === "always" ||
         target.operation.approval === "always";
-    const required = requiresToolActionApproval(params.executor.toolPermissionMode, force);
-    if (required !== Boolean(value.approvalRequest))
+    const required = requiresRegisteredToolActionApproval(params.executor.toolPermissionMode, source, target);
+    const missingRequiredApproval = required && !value.approvalRequest;
+    if (missingRequiredApproval)
+        throw invalid();
+    // Existing ASK approvals remain valid even when core reads no longer need new ones.
+    const unexpectedRecordedApproval = value.approvalRequest &&
+        !requiresToolActionApproval(params.executor.toolPermissionMode, force);
+    if (unexpectedRecordedApproval)
         throw invalid();
     if (value.approvalRequest) {
         if (!isRequestApproval(value.approvalRequest, params.executor.requestId))

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.d.ts

@@ -1,8 +1,8 @@
 import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
 import type { WorkerCapabilityAdapterResult, WorkerCapabilityExecutionFreshness } from "../../orchestration/worker-capabilities/index.js";
 import type { PayloadLifecycleEmitter } from "./payload-observability.js";
-export declare const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION: "steering_superseded_before_external_execution";
-export declare const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+import { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY } from "../../orchestration/worker-capabilities/execution/execution-freshness.js";
+export { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, };
 export type PayloadLifecycleContext = Readonly<Omit<Parameters<PayloadLifecycleEmitter["emitPayloadLifecycle"]>[0], "phase" | "errorCode">>;
 export declare function rejectPayloadLifecycle(params: {
     executor: PayloadLifecycleEmitter;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.js

@@ -1,7 +1,7 @@
 import { boundedSummary, requireCapabilityAdapterResult, } from "./result-observer.js";
 import { createRegisteredToolWorkerFailureOutcomeFingerprint } from "./failure-outcome-fingerprint.js";
-export const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION = "steering_superseded_before_external_execution";
-export const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+import { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, } from "../../orchestration/worker-capabilities/execution/execution-freshness.js";
+export { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, };
 export function rejectPayloadLifecycle(params) {
     const failed = params.executor.emitPayloadLifecycle({
         ...params.lifecycle,

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/prepared-execution.js

@@ -1,9 +1,23 @@
 import { traceRegisteredToolWorkerCapabilityExecutionStarted, traceRegisteredToolWorkerCapabilityExecutionCompleted, traceRegisteredToolWorkerCapabilityExecutionFailed, } from "../registered-tool-worker-capability-diagnostics.js";
 import { executionFreshnessRejection } from "./payload-lifecycle.js";
+import { payloadRejection } from "./payload-rejection.js";
 import { RegisteredToolWorkerCapabilityExecutionError } from "./errors.js";
 import { observeExternalResult, attachTargetReferences, } from "./result-observer.js";
 export function createPreparedWorkerInvocation(params, input, normalPreparation, selectedTargetReferences, payloadObservability) {
     const operationId = params.projection.operation.operationId;
+    const rejectBeforeExecution = (executionId, code, message) => {
+        payloadObservability.release(executionId);
+        const rejectedExecution = payloadRejection(code, message);
+        normalPreparation.emitRejection({
+            executionId,
+            executorIdentity: input.call,
+            errorCode: code,
+        });
+        return attachTargetReferences({
+            ...rejectedExecution.result,
+            exactResult: rejectedExecution.exactResult,
+        }, selectedTargetReferences);
+    };
     return Object.freeze({
         actionFingerprint: normalPreparation.actionFingerprint,
         acceptedControls: normalPreparation.acceptedControls,
@@ -18,22 +32,14 @@ export function createPreparedWorkerInvocation(params, input, normalPreparation,
             : {}),
         applyApprovalDecision: normalPreparation.applyApprovalDecision,
         onAdmitted: payloadObservability.release,
+        rejectBeforeExecution,
         execute: async (executionId) => {
             try {
                 payloadObservability.release(executionId);
                 traceRegisteredToolWorkerCapabilityExecutionStarted(params.diagnostic, operationId, input.call, executionId, input.intent.length, Object.keys(input.controls).length);
                 const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
-                if (rejectedExecution) {
-                    normalPreparation.emitRejection({
-                        executionId,
-                        executorIdentity: input.call,
-                        errorCode: rejectedExecution.sourceIssueCode,
-                    });
-                    return attachTargetReferences({
-                        ...rejectedExecution.result,
-                        exactResult: rejectedExecution.exactResult,
-                    }, selectedTargetReferences);
-                }
+                if (rejectedExecution)
+                    return rejectBeforeExecution(executionId, rejectedExecution.sourceIssueCode, rejectedExecution.result.summary);
                 const externalResult = await normalPreparation.execute(executionId, input.call, selectedTargetReferences);
                 const observed = observeExternalResult(externalResult, params.projection.operation.effect, input.call.parentCallId === null, selectedTargetReferences);
                 const observedResult = observed.result;

package/dist/src/runtime/automations/service.d.ts

@@ -15,7 +15,7 @@ export declare function createAutomationService(options: {
         latestRunId?: string | undefined;
         latestRunStatus?: import("../scheduler/contracts.js").SchedulerRunStatus | "stopping" | "completed_with_skips" | undefined;
         publishedRevision?: number;
-        status: "active" | "paused" | "draft" | "archived";
+        status: "archived" | "active" | "paused" | "draft";
         id: string;
         title: string;
         draftRevision: number;

package/dist/src/runtime/capabilities/automation-builder/tool-module.js

@@ -1,9 +1,9 @@
+import { CORE_TOOL_CONTRACTS } from "../core-tool-contracts.js";
 import { Buffer } from "node:buffer";
 import { AUTOMATION_TOOL_EVENT_PRESENTATION } from "../automations/event-presentation.js";
 import { automationDraftPreparationReceipt } from "../automations/draft-operation-refs.js";
 import { AutomationDraftReceiptCapacityError, prepareAutomationDraftReceipt } from "../automations/draft-receipt-admission.js";
 import { AUTOMATION_DRAFT_BATCH_LIMITS, AutomationDraftBatchError, AutomationDraftBatchGraphError } from "../../automations/draft-batch.js";
-import { automationBuilderToolContract } from "./tool-contract.js";
 import { AUTOMATION_BUILDER_PAYLOAD_FORMAT } from "./payload-schema.js";
 import { compileAutomationCreationRecipe, hasAutomationCreationRecipe } from "./creation-recipe.js";
 function requiredText(params, key) {
@@ -41,7 +41,7 @@ function requireAcceptedDraftReceipt(output) {
 async function execute(service, params) {
     const action = requiredText(params, "action");
     const plan = parsePlanPayload(params);
-    const operation = automationBuilderToolContract.operations.find(({ operationId }) => operationId === action);
+    const operation = CORE_TOOL_CONTRACTS.automationBuilder.normalInvocation.operations.find(({ operationId }) => operationId === action);
     if (!operation)
         throw new Error("automation_action_unknown");
     let acceptedOutput;
@@ -76,7 +76,7 @@ function failureDetails(error) {
 export function createAutomationBuilderToolModule(getService, ready) {
     return {
         definition: {
-            name: "automation_builder",
+            name: CORE_TOOL_CONTRACTS.automationBuilder.name,
             eventPresentation: {
                 ...AUTOMATION_TOOL_EVENT_PRESENTATION,
                 metadata: {
@@ -91,7 +91,7 @@ export function createAutomationBuilderToolModule(getService, ready) {
             payloadChannelSpec: { params: ["planJson"], outputParam: "planJson", generationMode: "raw_text",
                 stages: [{ outputParam: "planJson", responseFormat: AUTOMATION_BUILDER_PAYLOAD_FORMAT }] },
         },
-        normalInvocation: automationBuilderToolContract,
+        normalInvocation: CORE_TOOL_CONTRACTS.automationBuilder.normalInvocation,
         async implementation(params, context) {
             try {
                 await ready();

package/dist/src/runtime/capabilities/automations/draft-index.d.ts

@@ -7,7 +7,7 @@ export declare function readAutomationDraftIndex(service: AutomationService, off
         automationId: string;
         title: string;
         revision: number;
-        status: "active" | "paused" | "draft" | "archived";
+        status: "archived" | "active" | "paused" | "draft";
     }[];
     nextOffset: number | null;
     omittedCount: number;

package/dist/src/runtime/capabilities/automations/tool-module.js

@@ -1,9 +1,9 @@
+import { CORE_TOOL_CONTRACTS } from "../core-tool-contracts.js";
 import { Buffer } from "node:buffer";
 import { AUTOMATION_TOOL_EVENT_PRESENTATION } from "./event-presentation.js";
 import { automationDraftPreparationReceipt } from "./draft-operation-refs.js";
 import { AutomationDraftReceiptCapacityError, prepareAutomationDraftReceipt } from "./draft-receipt-admission.js";
 import { readAutomationDraftIndex } from "./draft-index.js";
-import { automationModelToolContract } from "./model-tool-contract.js";
 import { readAutomationAuthoringPreparation } from "./authoring-preparation.js";
 import { automationAuthoringCatalogScope, readAutomationAuthoringCatalog, readAutomationAuthoringCatalogIndex } from "./authoring-catalog.js";
 import { AUTOMATION_AUTHORING_REFERENCE } from "../automation-builder/authoring-reference.js";
@@ -254,7 +254,7 @@ async function execute(service, params) {
 export function createAutomationDraftToolModule(getService, ready) {
     return {
         definition: {
-            name: "automations",
+            name: CORE_TOOL_CONTRACTS.automations.name,
             eventPresentation: AUTOMATION_TOOL_EVENT_PRESENTATION,
             description: "Inspect and make targeted edits to ABot Studio drafts. For a complete connected workflow or several related edits, prefer automation_builder create_automation_draft or apply_automation_draft_changes. Catalog discovery lists tools for the FUTURE workflow, not Studio editing commands; fetch operation detail only when needed. Successful edits return exact revision and newNodeIds for reuse; read_draft when state is unknown or after a revision conflict. Draft authoring only: the user grants permissions, publishes and runs automations.",
             routingCapability: "semantic_mutation",
@@ -262,14 +262,14 @@ export function createAutomationDraftToolModule(getService, ready) {
             developmentRoles: ["auxiliary"],
             controlsRefinement: "mechanical_when_complete",
         },
-        normalInvocation: automationModelToolContract,
+        normalInvocation: CORE_TOOL_CONTRACTS.automations.normalInvocation,
         async implementation(params, context) {
             try {
                 await ready();
                 context?.abortSignal?.throwIfAborted();
                 const result = await execute(getService(), params);
                 if (params.action === "read_draft") {
-                    const operation = automationModelToolContract.operations.find(({ operationId }) => operationId === "read_draft");
+                    const operation = CORE_TOOL_CONTRACTS.automations.normalInvocation.operations.find(({ operationId }) => operationId === "read_draft");
                     return prepareAutomationDraftReceipt(result, { tool: "automations", operation, params, mutationEvidence: false });
                 }
                 const isDraftMutation = !["list_drafts", "read_draft", "catalog", "browse_catalog", "prepare_draft", "validate_draft"].includes(String(params.action));

package/dist/src/runtime/capabilities/core-tool-contracts.d.ts

@@ -0,0 +1,29 @@
+import type { ToolNormalInvocationContract, ToolNormalInvocationOperation } from "../../capabilities/tool-types.js";
+/** One source for native definitions and their reserved plugin identities. */
+export declare const CORE_TOOL_CONTRACTS: Readonly<{
+    skills: Readonly<{
+        name: string;
+        normalInvocation: ToolNormalInvocationContract;
+        readApproval: "request_policy" | "automatic";
+    }>;
+    scheduling: Readonly<{
+        name: string;
+        normalInvocation: ToolNormalInvocationContract;
+        readApproval: "request_policy" | "automatic";
+    }>;
+    automations: Readonly<{
+        name: string;
+        normalInvocation: ToolNormalInvocationContract;
+        readApproval: "request_policy" | "automatic";
+    }>;
+    automationBuilder: Readonly<{
+        name: string;
+        normalInvocation: ToolNormalInvocationContract;
+        readApproval: "request_policy" | "automatic";
+    }>;
+}>;
+/** Core policy only; public plugins cannot opt out of request approval. */
+export declare function isCoreToolAutomaticRead(toolName: string, operation: Pick<ToolNormalInvocationOperation, "operationId" | "effect">): boolean;
+export declare function hasCoreToolContractCollision(capabilities: Readonly<Record<string, {
+    operations: Readonly<Record<string, unknown>>;
+}>>): boolean;

package/dist/src/runtime/capabilities/core-tool-contracts.js

@@ -0,0 +1,38 @@
+import { schedulingToolContract } from "./scheduling/tool-contract.js";
+import { automationModelToolContract } from "./automations/model-tool-contract.js";
+import { automationBuilderToolContract } from "./automation-builder/tool-contract.js";
+import { knowledgeSkillsToolContract } from "./knowledge-skills/tool-contract.js";
+function coreToolContract(name, normalInvocation, readApproval = "request_policy") {
+    return Object.freeze({ name, normalInvocation, readApproval });
+}
+/** One source for native definitions and their reserved plugin identities. */
+export const CORE_TOOL_CONTRACTS = Object.freeze({
+    skills: coreToolContract("abot_skills", knowledgeSkillsToolContract, "automatic"),
+    scheduling: coreToolContract("schedules", schedulingToolContract),
+    automations: coreToolContract("automations", automationModelToolContract),
+    automationBuilder: coreToolContract("automation_builder", automationBuilderToolContract),
+});
+const coreTools = Object.values(CORE_TOOL_CONTRACTS);
+const coreToolNames = new Set(coreTools.map(({ name }) => name));
+const coreOperationIds = new Set(coreTools.flatMap(({ normalInvocation }) => normalInvocation.operations.map(({ operationId }) => operationId)));
+/** Core policy only; public plugins cannot opt out of request approval. */
+export function isCoreToolAutomaticRead(toolName, operation) {
+    const core = coreTools.find(({ name }) => name === toolName);
+    if (core?.readApproval !== "automatic")
+        return false;
+    if (operation.effect !== "read_only")
+        return false;
+    return core.normalInvocation.operations.some((candidate) => candidate.operationId === operation.operationId && candidate.effect === "read_only");
+}
+export function hasCoreToolContractCollision(capabilities) {
+    for (const [name, capability] of Object.entries(capabilities)) {
+        const hasReservedToolName = coreToolNames.has(name);
+        if (hasReservedToolName)
+            return true;
+        const hasReservedOperationId = Object.keys(capability.operations)
+            .some((operationId) => coreOperationIds.has(operationId));
+        if (hasReservedOperationId)
+            return true;
+    }
+    return false;
+}

package/dist/src/runtime/capabilities/knowledge-skills/read-many.d.ts

@@ -0,0 +1,4 @@
+import type { ToolImplementationOutput } from "../../../capabilities/tool-types.js";
+import { type KnowledgeSkillStore } from "../../knowledge-skills/store.js";
+/** One ordinary read result; never report a partial document set as success. */
+export declare function executeKnowledgeSkillsReadMany(store: KnowledgeSkillStore, skillIds: unknown): ToolImplementationOutput;

package/dist/src/runtime/capabilities/knowledge-skills/read-many.js

@@ -0,0 +1,21 @@
+import { KNOWLEDGE_SKILL_READ_MAX_ITEMS, } from "../../knowledge-skills/store.js";
+import { knowledgeSkillDocumentsReadOutput, knowledgeSkillFailure } from "./tool-output.js";
+import { isKnowledgeSkillReadReference, resolveKnowledgeSkillReadTargets } from "./read-targets.js";
+function hasValidSkillIds(value) {
+    if (!Array.isArray(value))
+        return false;
+    if (value.length === 0 || value.length > KNOWLEDGE_SKILL_READ_MAX_ITEMS)
+        return false;
+    if (!value.every(isKnowledgeSkillReadReference))
+        return false;
+    return new Set(value).size === value.length;
+}
+/** One ordinary read result; never report a partial document set as success. */
+export function executeKnowledgeSkillsReadMany(store, skillIds) {
+    if (!hasValidSkillIds(skillIds))
+        return knowledgeSkillFailure("knowledge_skill_ids_invalid");
+    const resolved = resolveKnowledgeSkillReadTargets(store, skillIds);
+    if (!resolved.ok)
+        return knowledgeSkillFailure(resolved.errorCode);
+    return knowledgeSkillDocumentsReadOutput(resolved.skills);
+}

package/dist/src/runtime/capabilities/knowledge-skills/read-targets.d.ts

@@ -0,0 +1,13 @@
+import { type KnowledgeSkillDocument, type KnowledgeSkillStore } from "../../knowledge-skills/store.js";
+export declare const KNOWLEDGE_SKILL_READ_REFERENCE_MAX_LENGTH: number;
+export declare function isKnowledgeSkillReadReference(value: unknown): value is string;
+type ResolvedSkillRead = Readonly<{
+    ok: true;
+    skills: readonly KnowledgeSkillDocument[];
+}> | Readonly<{
+    ok: false;
+    errorCode: string;
+}>;
+/** Resolve exact IDs first, then full names, against the same Store used for discovery. */
+export declare function resolveKnowledgeSkillReadTargets(store: KnowledgeSkillStore, references: readonly string[]): ResolvedSkillRead;
+export {};