@agent-native/core 0.169.1 → 0.171.0

package/corpus/templates/tasks/vitest.config.ts

@@ -14,7 +14,13 @@ export default mergeConfig(
     },
     test: {
       include: ["**/*.{test,spec}.?(c|m)[jt]s?(x)"],
-      exclude: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/e2e/**"],
+      exclude: [
+        "**/node_modules/**",
+        "**/.git/**",
+        "**/dist/**",
+        "**/.react-router/**",
+        "**/e2e/**",
+      ],
       environment: "node",
     },
   }),

package/dist/action.d.ts

@@ -415,6 +415,49 @@ interface DefineActionWithSchema<TSchema extends StandardSchemaV1, TReturn = any
      *  tool list. Distinct from `toolCallable`, which only governs the sandboxed
      *  extension ("tools") iframe bridge. See `packages/core/docs/content/actions.mdx`. */
     agentTool?: boolean;
+    /** Whether this action is exposed to EXTERNAL agents over MCP (and the direct
+     *  A2A action surface, which shares the same policy).
+     *
+     *  **Defaults to `agentTool`, not to `true`**: an action hidden from the
+     *  agent is hidden from outside agents too, so one flag stays one decision.
+     *  Declaring `mcpTool` overrides that inheritance in both directions.
+     *
+     *  - `false` — hard veto. The action is absent from `tools/list` AND from
+     *    `tools/call` on every MCP tier, including the rare `--full-catalog`
+     *    opt-in, while the in-app agent still calls it normally. Use it for
+     *    actions that only make sense with an in-app screen, a live session, or
+     *    the framework's own UI on the other end.
+     *  - `true` — the action-owned form of `mcp.connectorCatalog` membership:
+     *    this action is served on the curated external catalog. Declaring it on
+     *    any action activates the connector tier for the app, which is what lets
+     *    a template delete its hand-maintained `connectorCatalog` name list.
+     *    Paired with `agentTool: false` it makes the action MCP-only — external
+     *    agents get it, the app's own agent does not.
+     *  - `undefined` (default) — follows `agentTool`; the tier rules then decide
+     *    whether it is advertised up front or found through `tool-search`.
+     *
+     *  Membership is not permission: an external caller still passes the OAuth
+     *  scope, `externalAgents` policy, and `publicAgent` checks. Resolved by
+     *  `isActionExposedToExternalAgents` below, which every external surface
+     *  reads instead of testing these two fields itself. */
+    mcpTool?: boolean;
+    /** Whether this action's schema is held back from the agent's FIRST-REQUEST
+     *  tool list and loaded on demand through `tool-search` instead. The
+     *  action-owned form of the plugin's `initialToolNames` array, so the app's
+     *  starter surface is declared beside each action rather than in a list that
+     *  drifts as actions are renamed.
+     *
+     *  - `false` — always in the initial set. As soon as ANY action declares
+     *    this, the derived default flips from "every one of the app's own
+     *    actions" to "the ones that opted in", which is what makes deleting
+     *    `initialToolNames` a real trim rather than a rename.
+     *  - `true` — never in the DERIVED set. An explicit `initialToolNames` entry
+     *    still wins, so a stale list is never silently overridden.
+     *  - `undefined` (default) — unchanged behavior.
+     *
+     *  This is about first-turn context cost, not access: a deferred action is
+     *  still callable the moment `tool-search` returns it. */
+    deferLoading?: boolean;
     /** If true, the framework will NOT emit a screen-refresh change event after a
      *  successful call. Auto-inferred as `true` when `http.method === "GET"`.
      *  Only set this manually when you need to override the inference — e.g. a
@@ -566,6 +609,15 @@ interface DefineActionWithParams<TParams extends Record<string, ParameterSchema>
      *  explicit `false` hides it from every agent tool list while keeping it
      *  frontend/HTTP-callable. See the schema overload above and actions.md. */
     agentTool?: boolean;
+    /** Whether this action is exposed to external agents over MCP / direct A2A.
+     *  Defaults to `agentTool`. `false` is a hard veto on every MCP tier; `true`
+     *  declares curated connector-catalog membership, and with `agentTool:
+     *  false` makes the action MCP-only. See the schema overload above. */
+    mcpTool?: boolean;
+    /** Whether this action's schema is held back from the agent's first-request
+     *  tool list and loaded through `tool-search` instead. The action-owned form
+     *  of the plugin's `initialToolNames`. See the schema overload above. */
+    deferLoading?: boolean;
     /** If true, the framework will NOT emit a screen-refresh change event after a
      *  successful call. Auto-inferred as `true` when `http.method === "GET"`. */
     readOnly?: boolean;
@@ -635,6 +687,8 @@ export interface ActionDefinition<TInput, TReturn> {
     readonly requiresAuth?: boolean;
     readonly maxBodyBytes?: number;
     readonly agentTool?: boolean;
+    readonly mcpTool?: boolean;
+    readonly deferLoading?: boolean;
     readonly readOnly?: boolean;
     readonly grounding?: boolean;
     readonly allowInPlanMode?: boolean;
@@ -706,6 +760,43 @@ export interface ActionDefinition<TInput, TReturn> {
  */
 export declare function defineAction<TSchema extends StandardSchemaV1, TReturn, TOutputSchema extends StandardSchemaV1 | undefined = undefined>(options: DefineActionWithSchema<TSchema, TReturn, TOutputSchema>): ActionDefinition<StandardSchemaV1.InferInput<TSchema>, TReturn>;
 export declare function defineAction<TParams extends Record<string, ParameterSchema> | undefined, TReturn>(options: DefineActionWithParams<TParams, TReturn>): ActionDefinition<InferParams<TParams>, TReturn>;
+/**
+ * Whether an action is exposed to EXTERNAL agents — MCP and the direct A2A
+ * action surface. The one resolver every surface asks; nothing downstream
+ * re-derives this from the two raw fields.
+ *
+ * `mcpTool` DEFAULTS TO `agentTool` rather than to a flat `true`, so hiding an
+ * action from the agent hides it from outside agents too and one flag stays
+ * one decision. Declaring `mcpTool` overrides that inheritance in both
+ * directions:
+ *
+ *   agentTool: false                → hidden from every agent surface
+ *   agentTool: false, mcpTool: true → MCP-only: external agents get it, the
+ *                                     app's own agent does not
+ *   mcpTool: false                  → in-app only, whatever `agentTool` says
+ *
+ * The MCP-only combination needs the plugin to route those actions around the
+ * `filterAgentTools` gate — see `mcpOnlyActions` in `agent-chat-plugin.ts`.
+ */
+export declare function isActionExposedToExternalAgents(entry: {
+    agentTool?: boolean;
+    mcpTool?: boolean;
+}): boolean;
+/**
+ * Whether an action is hidden from EVERY agent surface — the in-app agent and
+ * external agents alike.
+ *
+ * The runtime backstops (`executeAgentToolCall`, `searchToolRegistry`) use
+ * this rather than `agentTool === false`: each caller already passes a
+ * surface-scoped registry, so the backstop's job is to catch an entry that no
+ * surface should ever run, not to re-litigate which surface this is. Testing
+ * `agentTool` alone made those two refuse the MCP-only actions their own
+ * caller had deliberately handed them.
+ */
+export declare function isActionHiddenFromEveryAgentSurface(entry: {
+    agentTool?: boolean;
+    mcpTool?: boolean;
+}): boolean;
 export declare function stripUnsupportedSchemaKeywords<T>(node: T): T;
 /**
  * Compact signature of an action's parameters, e.g.

package/dist/action.js

@@ -144,6 +144,17 @@ export function defineAction(options) {
     // agentTool: default-allow opt-out. Only an explicit `false` hides the action
     // from the agent tool surfaces; undefined is preserved (treated as exposed).
     const agentTool = typeof options.agentTool === "boolean" ? options.agentTool : undefined;
+    // mcpTool / deferLoading: like `agentTool`, `undefined` is a distinct third
+    // state and must survive to the entry. Both flags mean something different
+    // when declared than when omitted — an explicit `mcpTool: true` puts the
+    // action on the curated external catalog, and an explicit
+    // `deferLoading: false` narrows the derived first-request set — so
+    // collapsing undefined to the default here would erase the declaration the
+    // surfaces read.
+    const mcpTool = typeof options.mcpTool === "boolean" ? options.mcpTool : undefined;
+    const deferLoading = typeof options.deferLoading === "boolean"
+        ? options.deferLoading
+        : undefined;
     const parallelSafe = typeof options.parallelSafe === "boolean"
         ? options.parallelSafe
         : undefined;
@@ -190,6 +201,8 @@ export function defineAction(options) {
             ? { maxBodyBytes: options.maxBodyBytes }
             : {}),
         ...(typeof agentTool === "boolean" ? { agentTool } : {}),
+        ...(typeof mcpTool === "boolean" ? { mcpTool } : {}),
+        ...(typeof deferLoading === "boolean" ? { deferLoading } : {}),
         ...(typeof readOnly === "boolean" ? { readOnly } : {}),
         ...(typeof options.grounding === "boolean"
             ? { grounding: options.grounding }
@@ -235,6 +248,43 @@ export function defineAction(options) {
         ...(auditConfig ? { audit: auditConfig } : {}),
     };
 }
+/**
+ * Whether an action is exposed to EXTERNAL agents — MCP and the direct A2A
+ * action surface. The one resolver every surface asks; nothing downstream
+ * re-derives this from the two raw fields.
+ *
+ * `mcpTool` DEFAULTS TO `agentTool` rather than to a flat `true`, so hiding an
+ * action from the agent hides it from outside agents too and one flag stays
+ * one decision. Declaring `mcpTool` overrides that inheritance in both
+ * directions:
+ *
+ *   agentTool: false                → hidden from every agent surface
+ *   agentTool: false, mcpTool: true → MCP-only: external agents get it, the
+ *                                     app's own agent does not
+ *   mcpTool: false                  → in-app only, whatever `agentTool` says
+ *
+ * The MCP-only combination needs the plugin to route those actions around the
+ * `filterAgentTools` gate — see `mcpOnlyActions` in `agent-chat-plugin.ts`.
+ */
+export function isActionExposedToExternalAgents(entry) {
+    return typeof entry.mcpTool === "boolean"
+        ? entry.mcpTool
+        : entry.agentTool !== false;
+}
+/**
+ * Whether an action is hidden from EVERY agent surface — the in-app agent and
+ * external agents alike.
+ *
+ * The runtime backstops (`executeAgentToolCall`, `searchToolRegistry`) use
+ * this rather than `agentTool === false`: each caller already passes a
+ * surface-scoped registry, so the backstop's job is to catch an entry that no
+ * surface should ever run, not to re-litigate which surface this is. Testing
+ * `agentTool` alone made those two refuse the MCP-only actions their own
+ * caller had deliberately handed them.
+ */
+export function isActionHiddenFromEveryAgentSurface(entry) {
+    return entry.agentTool === false && entry.mcpTool !== true;
+}
 /**
  * Wrap an action's run with its `authorize` gate.
  *

package/dist/agent/abort-reasons.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Abort-reason vocabulary, kept in a leaf module on purpose.
+ *
+ * The abort route needs only these two symbols, but they used to live in
+ * `run-loop-with-resume.ts` — the whole agent execution loop. Importing them
+ * from there pulled that graph into the server plugin's static imports, so
+ * every cold serverless start evaluated the entire run loop (measured at
+ * ~1.6s) before it could render a page it would never run an agent for.
+ * Nothing here may import from the run loop, or that cost comes straight back.
+ */
+/**
+ * Abort reasons the SERVER sets on a run's own controller. Everything else —
+ * including any reason a client passes to the abort route — is a user Stop.
+ *
+ * Kept deliberately short. Each entry is a bound this package owns and can name
+ * in a terminal outcome; if you are adding a fourth, check first whether the
+ * bound belongs in `run-manager.ts` at all.
+ *
+ * Exported so the abort route can refuse these words from a client. That check
+ * belongs at the boundary where untrusted input enters, not here: by the time a
+ * reason reaches an `AbortSignal` it is just a string, and nothing downstream
+ * can tell who wrote it.
+ */
+export declare const SERVER_OWNED_ABORT_REASONS: Set<string>;
+/**
+ * The abort reason to record for a client-initiated Stop.
+ *
+ * A caller reaching the abort route is a person pressing Stop, so it must not
+ * be able to name a bound only the server can reach: the terminal outcome keys
+ * off the abort reason, and a client sending `background_automation_hard_timeout`
+ * would file its own Stop as a server-side failure. Anything unrecognised,
+ * malformed, or reserved falls back to `"user"`.
+ *
+ * Normalised here rather than in the route because this is where the meaning of
+ * the string is decided — downstream it is just a string, and nothing can tell
+ * who wrote it.
+ */
+export declare function clientAbortReason(raw: unknown): string;

package/dist/agent/abort-reasons.js

@@ -0,0 +1,49 @@
+/**
+ * Abort-reason vocabulary, kept in a leaf module on purpose.
+ *
+ * The abort route needs only these two symbols, but they used to live in
+ * `run-loop-with-resume.ts` — the whole agent execution loop. Importing them
+ * from there pulled that graph into the server plugin's static imports, so
+ * every cold serverless start evaluated the entire run loop (measured at
+ * ~1.6s) before it could render a page it would never run an agent for.
+ * Nothing here may import from the run loop, or that cost comes straight back.
+ */
+/**
+ * Abort reasons the SERVER sets on a run's own controller. Everything else —
+ * including any reason a client passes to the abort route — is a user Stop.
+ *
+ * Kept deliberately short. Each entry is a bound this package owns and can name
+ * in a terminal outcome; if you are adding a fourth, check first whether the
+ * bound belongs in `run-manager.ts` at all.
+ *
+ * Exported so the abort route can refuse these words from a client. That check
+ * belongs at the boundary where untrusted input enters, not here: by the time a
+ * reason reaches an `AbortSignal` it is just a string, and nothing downstream
+ * can tell who wrote it.
+ */
+export const SERVER_OWNED_ABORT_REASONS = new Set([
+    "no_progress",
+    "run_timeout",
+    "background_automation_hard_timeout",
+]);
+/**
+ * The abort reason to record for a client-initiated Stop.
+ *
+ * A caller reaching the abort route is a person pressing Stop, so it must not
+ * be able to name a bound only the server can reach: the terminal outcome keys
+ * off the abort reason, and a client sending `background_automation_hard_timeout`
+ * would file its own Stop as a server-side failure. Anything unrecognised,
+ * malformed, or reserved falls back to `"user"`.
+ *
+ * Normalised here rather than in the route because this is where the meaning of
+ * the string is decided — downstream it is just a string, and nothing can tell
+ * who wrote it.
+ */
+export function clientAbortReason(raw) {
+    if (typeof raw !== "string")
+        return "user";
+    const reason = raw.trim();
+    if (!/^[a-z0-9_-]{1,64}$/i.test(reason))
+        return "user";
+    return SERVER_OWNED_ABORT_REASONS.has(reason.toLowerCase()) ? "user" : reason;
+}

package/dist/agent/engine/ai-sdk-engine.js

@@ -16,7 +16,7 @@ import { allowsSamplingParams, anthropicManualThinkingBudget, normalizeReasoning
 import { AI_SDK_MODEL_CONFIG } from "../model-config.js";
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./credential-errors.js";
 import { classifyProviderError, describeErrorWithCauses, } from "./error-detail.js";
-import { createFirstEventAbortController, FIRST_STREAM_EVENT_TIMEOUT_MS, } from "./first-event-timeout.js";
+import { createFirstEventAbortController } from "./first-event-timeout.js";
 import { clampThinkingBudgetTokens, resolveMaxOutputTokensForEngine, } from "./output-tokens.js";
 import { engineToolsToAISDK, engineMessagesToAISDK, aiSdkPartToEngineEvents, aiSdkStepToAssistantContent, } from "./translate-ai-sdk.js";
 import { createStreamedToolInputState, finalizeStreamedToolInputs, observeStreamedToolInput, } from "./translate-anthropic.js";
@@ -425,10 +425,13 @@ class AISDKEngine {
                 }
             }
             // AI SDK surfaces an aborted stream as a graceful `{type: "abort"}`
-            // part rather than a thrown error, so a first-event timeout would
-            // otherwise fall through to the normal end_turn completion below.
-            if (!sawFirstEvent && firstEventAbort.didTimeout()) {
-                throw new Error(`Model request produced no stream events within ${FIRST_STREAM_EVENT_TIMEOUT_MS / 1000}s; the connection appears wedged.`);
+            // part rather than a thrown error, so a deadline abort would otherwise
+            // fall through to the normal end_turn completion below. Not gated on
+            // `sawFirstEvent`: the total deadline fires mid-stream by definition, and
+            // reporting that half-delivered turn as a clean end_turn is exactly the
+            // truncated-run-reported-as-complete failure.
+            if (firstEventAbort.didTimeout()) {
+                throw new Error(`${firstEventAbort.timeoutMessage()}; the connection appears wedged.`);
             }
             // A step can finish having announced a tool call it never delivered.
             // Assemble it from its deltas, or report it in-band, rather than ending

package/dist/agent/engine/anthropic-engine.js

@@ -12,7 +12,7 @@ import { allowsSamplingParams, anthropicManualThinkingBudget, normalizeReasoning
 import { ANTHROPIC_MODEL_CONFIG } from "../model-config.js";
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "./credential-errors.js";
 import { describeErrorWithCauses } from "./error-detail.js";
-import { createFirstEventAbortController, FIRST_STREAM_EVENT_TIMEOUT_MS, } from "./first-event-timeout.js";
+import { createFirstEventAbortController } from "./first-event-timeout.js";
 import { clampThinkingBudgetTokens, resolveMaxOutputTokensForEngine, } from "./output-tokens.js";
 import { splitSystemPromptForCache, stablePrefixCacheControl, } from "./prompt-cache.js";
 import { engineToolsToAnthropic, engineMessagesToAnthropic, anthropicContentToEngine, anthropicChunkToEngineEvents, createAnthropicChunkStreamState, createStreamedToolInputState, finalizeStreamedToolInputs, observeStreamedToolInput, } from "./translate-anthropic.js";
@@ -233,12 +233,14 @@ class AnthropicEngine {
                 : typeof err?.statusCode === "number"
                     ? err.statusCode
                     : undefined;
-            // A first-event abort surfaces from the SDK as a generic
-            // APIUserAbortError ("Request was aborted.") — replace it with a
-            // message that actually explains what happened.
+            // A deadline abort surfaces from the SDK as a generic APIUserAbortError
+            // ("Request was aborted.") — replace it with a message that actually
+            // explains what happened. Which deadline fired comes from the
+            // controller: a total-deadline abort is a socket that wedged MID-stream,
+            // not a connection that never spoke.
             const rawMessage = err?.message ?? String(err);
             const errorMessage = timedOut
-                ? `Model request produced no stream events within ${FIRST_STREAM_EVENT_TIMEOUT_MS / 1000}s; the connection appears wedged.`
+                ? `${firstEventAbort.timeoutMessage()}; the connection appears wedged.`
                 : describeErrorWithCauses(err);
             // Anthropic SDK APIConnectionError defaults to "Connection error." with
             // no HTTP status. Tag it so in-run retries and run-level resume treat

package/dist/agent/engine/first-event-timeout.d.ts

@@ -1,32 +1,57 @@
 /**
- * Shared "first stream event" deadline for model-request engines.
+ * Shared stream deadlines for model-request engines.
  *
- * A request that connects successfully but then streams zero events means the
- * transport or gateway is wedged, not slow — real models (including deep
- * thinking ones) emit their first event within seconds. Bounding this window
- * separately from any total-request deadline turns a silent multi-minute hang
- * into a fast abort-and-retry.
+ * Two bounds, both keyed off facts the transport can actually establish:
  *
- * AUDIENCE: direct `engine.stream()` callers — `completeText`, voice
- * transcription, sentiment, evals, observational memory. It is EXPECTED to be
- * shadowed inside `runAgentLoop`, whose own `MODEL_STREAM_NO_PROGRESS_TIMEOUT_MS`
- * (90s) races the same first frame and always wins. That does not make it
- * redundant: `completeText` takes `timeoutMs` as optional, so a caller that
- * omits one has no other bound between it and an unbounded hang. Do not
- * "clean it up" as unreachable — check the non-loop callers first.
+ *  - FIRST: a request that connects and then streams zero events means the
+ *    transport or gateway is wedged, not slow — real models (including deep
+ *    thinking ones) emit their first event within seconds.
+ *  - TOTAL: the whole request, first event or not, cannot outlive the largest
+ *    budget any caller runs inside.
+ *
+ * AUDIENCE: every `engine.stream()` caller, `runAgentLoop` INCLUDED. The first
+ * bound used to be described as shadowed inside the loop by a 90s in-loop
+ * watchdog that "always wins"; that watchdog is gone (see
+ * run-lifecycle-invariants.ts), so these are now the PRIMARY bounds on a model
+ * call that wedges. They survive that deletion because neither infers death
+ * from the ABSENCE of a particular event mid-generation — the fact the removed
+ * watchdogs got wrong, since the Anthropic SDK drops the provider's `ping`
+ * keepalives before any consumer sees them. Do not "clean them up" as
+ * redundant, and do not add a no-progress bound back beside them.
  */
 export declare const FIRST_STREAM_EVENT_TIMEOUT_MS = 120000;
+/**
+ * Ceiling on one model call end to end, measured from request start.
+ *
+ * Sized so it can never preempt healthy work: the largest chunk any caller runs
+ * inside is the ~13-minute background soft timeout, and a hosted run is bounded
+ * by its own chunk long before this. It exists for the runtimes that have no
+ * outer budget at all — local dev and self-hosted resolve the soft timeout to
+ * `0`, so without this a socket that wedges AFTER the first frame leaves the
+ * run pending forever. Mirrors the ceiling builder-engine already applies to
+ * its own gateway requests, for the engines that talk to a provider directly.
+ */
+export declare const STREAM_TOTAL_TIMEOUT_MS: number;
 export interface FirstEventAbortController {
     readonly signal: AbortSignal;
     /** Idempotent. Call once the first real (non-keepalive) stream event arrives. */
     markFirstEvent: () => void;
     didTimeout: () => boolean;
+    /**
+     * Which deadline fired, phrased for the user, or `undefined` if none did.
+     * Callers must not assume a timeout is the first-event one — after
+     * `markFirstEvent()` a timeout means the total deadline, and reporting the
+     * wrong one describes a wedged mid-stream socket as a connection that never
+     * spoke.
+     */
+    timeoutMessage: () => string | undefined;
     cleanup: () => void;
 }
 /**
- * Layer a first-event deadline on top of a caller's AbortSignal. Aborts if
- * `markFirstEvent()` is not called within `FIRST_STREAM_EVENT_TIMEOUT_MS`.
- * Has no opinion on a total-request deadline — callers that need one (e.g.
- * builder-engine's flat gateway timeout) compose their own on top.
+ * Layer the two deadlines above on top of a caller's AbortSignal. Aborts if
+ * `markFirstEvent()` is not called within `FIRST_STREAM_EVENT_TIMEOUT_MS`, and
+ * again if the whole request outlives `STREAM_TOTAL_TIMEOUT_MS`. Callers that
+ * need a TIGHTER total deadline (e.g. builder-engine's flat gateway timeout)
+ * compose their own on top.
  */
 export declare function createFirstEventAbortController(parentSignal: AbortSignal): FirstEventAbortController;

package/dist/agent/engine/first-event-timeout.js

@@ -1,40 +1,74 @@
 /**
- * Shared "first stream event" deadline for model-request engines.
+ * Shared stream deadlines for model-request engines.
  *
- * A request that connects successfully but then streams zero events means the
- * transport or gateway is wedged, not slow — real models (including deep
- * thinking ones) emit their first event within seconds. Bounding this window
- * separately from any total-request deadline turns a silent multi-minute hang
- * into a fast abort-and-retry.
+ * Two bounds, both keyed off facts the transport can actually establish:
  *
- * AUDIENCE: direct `engine.stream()` callers — `completeText`, voice
- * transcription, sentiment, evals, observational memory. It is EXPECTED to be
- * shadowed inside `runAgentLoop`, whose own `MODEL_STREAM_NO_PROGRESS_TIMEOUT_MS`
- * (90s) races the same first frame and always wins. That does not make it
- * redundant: `completeText` takes `timeoutMs` as optional, so a caller that
- * omits one has no other bound between it and an unbounded hang. Do not
- * "clean it up" as unreachable — check the non-loop callers first.
+ *  - FIRST: a request that connects and then streams zero events means the
+ *    transport or gateway is wedged, not slow — real models (including deep
+ *    thinking ones) emit their first event within seconds.
+ *  - TOTAL: the whole request, first event or not, cannot outlive the largest
+ *    budget any caller runs inside.
+ *
+ * AUDIENCE: every `engine.stream()` caller, `runAgentLoop` INCLUDED. The first
+ * bound used to be described as shadowed inside the loop by a 90s in-loop
+ * watchdog that "always wins"; that watchdog is gone (see
+ * run-lifecycle-invariants.ts), so these are now the PRIMARY bounds on a model
+ * call that wedges. They survive that deletion because neither infers death
+ * from the ABSENCE of a particular event mid-generation — the fact the removed
+ * watchdogs got wrong, since the Anthropic SDK drops the provider's `ping`
+ * keepalives before any consumer sees them. Do not "clean them up" as
+ * redundant, and do not add a no-progress bound back beside them.
  */
 export const FIRST_STREAM_EVENT_TIMEOUT_MS = 120_000;
 /**
- * Layer a first-event deadline on top of a caller's AbortSignal. Aborts if
- * `markFirstEvent()` is not called within `FIRST_STREAM_EVENT_TIMEOUT_MS`.
- * Has no opinion on a total-request deadline — callers that need one (e.g.
- * builder-engine's flat gateway timeout) compose their own on top.
+ * Ceiling on one model call end to end, measured from request start.
+ *
+ * Sized so it can never preempt healthy work: the largest chunk any caller runs
+ * inside is the ~13-minute background soft timeout, and a hosted run is bounded
+ * by its own chunk long before this. It exists for the runtimes that have no
+ * outer budget at all — local dev and self-hosted resolve the soft timeout to
+ * `0`, so without this a socket that wedges AFTER the first frame leaves the
+ * run pending forever. Mirrors the ceiling builder-engine already applies to
+ * its own gateway requests, for the engines that talk to a provider directly.
+ */
+export const STREAM_TOTAL_TIMEOUT_MS = 14 * 60_000;
+/**
+ * Layer the two deadlines above on top of a caller's AbortSignal. Aborts if
+ * `markFirstEvent()` is not called within `FIRST_STREAM_EVENT_TIMEOUT_MS`, and
+ * again if the whole request outlives `STREAM_TOTAL_TIMEOUT_MS`. Callers that
+ * need a TIGHTER total deadline (e.g. builder-engine's flat gateway timeout)
+ * compose their own on top.
  */
 export function createFirstEventAbortController(parentSignal) {
     const controller = new AbortController();
-    let timedOut = false;
+    const startedAt = Date.now();
+    let timeoutMessage;
     let firstEventSeen = false;
     const abortFromParent = () => {
+        // Drop the outstanding deadline too. A parent abort ends this request, and
+        // the provider can take a moment to settle afterwards — a timer still
+        // armed through that window fires into an already-cancelled request and
+        // relabels a user Stop or a run-budget abort as a retryable provider
+        // failure. That window used to be small because the first frame cleared
+        // the timer outright; now that a deadline runs for the whole stream, it is
+        // the whole stream.
+        clearTimeout(timeout);
         if (!controller.signal.aborted)
             controller.abort(parentSignal.reason);
     };
-    const timeout = setTimeout(() => {
-        timedOut = true;
-        if (!controller.signal.aborted) {
-            controller.abort(new Error(`Model request produced no stream events within ${FIRST_STREAM_EVENT_TIMEOUT_MS / 1000}s`));
-        }
+    const fireTimeout = (message) => {
+        // Record a timeout ONLY when this controller wins the abort race. Setting
+        // the message first and checking `aborted` after made a deadline that
+        // merely fired into an already-aborted controller indistinguishable from
+        // one that caused the abort — and `didTimeout()` is what the engines read
+        // to decide a failure was the transport's fault and worth retrying.
+        if (controller.signal.aborted)
+            return;
+        timeoutMessage = message;
+        controller.abort(new Error(message));
+    };
+    let timeout = setTimeout(() => {
+        fireTimeout(`Model request produced no stream events within ${FIRST_STREAM_EVENT_TIMEOUT_MS / 1000}s`);
     }, FIRST_STREAM_EVENT_TIMEOUT_MS);
     if (parentSignal.aborted)
         abortFromParent();
@@ -42,12 +76,20 @@ export function createFirstEventAbortController(parentSignal) {
     return {
         signal: controller.signal,
         markFirstEvent: () => {
-            if (firstEventSeen)
+            // `aborted` subsumes the timeout check — `fireTimeout` only records a
+            // message when it aborts — and also covers the parent-abort case, so a
+            // frame processed after a Stop cannot re-arm a deadline on a dead
+            // request.
+            if (firstEventSeen || controller.signal.aborted)
                 return;
             firstEventSeen = true;
             clearTimeout(timeout);
+            timeout = setTimeout(() => {
+                fireTimeout(`Model request exceeded the ${STREAM_TOTAL_TIMEOUT_MS / 60_000}-minute total stream deadline`);
+            }, Math.max(0, STREAM_TOTAL_TIMEOUT_MS - (Date.now() - startedAt)));
         },
-        didTimeout: () => timedOut,
+        didTimeout: () => timeoutMessage !== undefined,
+        timeoutMessage: () => timeoutMessage,
         cleanup: () => {
             clearTimeout(timeout);
             parentSignal.removeEventListener("abort", abortFromParent);

package/dist/agent/production-agent.d.ts

@@ -178,6 +178,21 @@ export interface ActionEntry {
      *  MCP, A2A, job/trigger runners) while leaving it frontend/HTTP-callable.
      *  Set by `defineAction`'s `agentTool` option. */
     agentTool?: boolean;
+    /** Whether the action is exposed to EXTERNAL agents over MCP and the direct
+     *  A2A action surface. Defaults to `agentTool`. `false` is a hard veto on
+     *  every MCP tier (including the `--full-catalog` opt-in) while the in-app
+     *  agent keeps calling it; `true` declares curated connector-catalog
+     *  membership, and with `agentTool: false` makes the action MCP-only. Read
+     *  it through `isActionExposedToExternalAgents`, never as a raw field.
+     *  Set by `defineAction`'s `mcpTool` option. */
+    mcpTool?: boolean;
+    /** Whether the action's schema is held back from the agent's first-request
+     *  tool list — the action-owned form of the plugin's `initialToolNames`.
+     *  `false` always includes it (and narrows the derived default to the
+     *  actions that opted in); `true` keeps it out of the DERIVED set, reachable
+     *  through `tool-search`. Context cost, not access. Set by `defineAction`'s
+     *  `deferLoading` option. */
+    deferLoading?: boolean;
     /** Explicit opt-in metadata for public agent protocols. Public routes never
      *  imply public tool exposure; MCP/A2A/OpenAPI surfaces must filter for this. */
     publicAgent?: import("../action.js").PublicAgentActionConfig;
@@ -872,6 +887,14 @@ export declare function runAgentLoop(opts: {
      * App-level default limits applied to every tool call unless the individual
      * ActionEntry overrides them with its own timeoutMs / maxResultChars.
      */
+    /**
+     * The chunk's REAL soft-timeout budget, when the caller has one.
+     *
+     * Only `runToolTimeoutCeilingMs` reads it, and only so a per-tool timeout
+     * stays under the budget it actually runs inside. Absent, the generic hosted
+     * ceiling is used — right for callers that have no chunk of their own.
+     */
+    runSoftTimeoutMs?: number;
     toolLimits?: {
         timeoutMs?: number;
         maxResultChars?: number;