@nylorun/runtime 0.19.1-beta → 0.21.0-beta

package/dist/gates/mcp-handler.js

@@ -1,4 +1,4 @@
-import { openMcpServer, } from "../mcp/connect.js";
+import { McpCallFailed, McpConnectionStale, openMcpServer, unreachable, } from "../mcp/connect.js";
 import { findServer } from "../mcp/pool.js";
 import { GateRefusal } from "./tenant-vaults.js";
 /** A connection unused this long is closed; the next request opens it again. */
@@ -65,29 +65,79 @@ export function createMcpHandler(options) {
                 ...fields(server),
                 ...extra,
                 ms: now() - started,
-                outcome: failed.code === undefined ? "failed" : String(failed.code),
+                outcome: failed.failure?.code ?? (failed.code === undefined ? "failed" : String(failed.code)),
             });
             return { ok: false, error: failed };
         }
     }
-    async function use(tenantId, server, run) {
-        const entry = await connection(tenantId, server);
+    /** The server's connection; for a tool call, one that cannot be opened is `mcp.unreachable`. */
+    async function opened(tenantId, server, call) {
+        try {
+            return await connection(tenantId, server);
+        }
+        catch (error) {
+            // The call was never sent, so the model may try again (R2b C7). A gate that cannot serve
+            // the session is not the server's failure, and stays as it was.
+            if (!call || error instanceof GateRefusal || error instanceof NotDeclared)
+                throw error;
+            throw unreachable(server.serverName, error);
+        }
+    }
+    async function use(tenantId, server, run, call = false) {
+        const entry = await opened(tenantId, server, call);
         entry.active += 1;
         try {
             return await run(entry);
         }
+        catch (error) {
+            // The connection can no longer make requests: the next one opens a new connection, and
+            // the calls still running on this one finish first (the last closes it).
+            if (error instanceof McpConnectionStale) {
+                const key = keyOf(server);
+                if (live.get(key) === entry)
+                    live.delete(key);
+                entry.evicted = true;
+            }
+            throw error;
+        }
         finally {
             entry.active -= 1;
             entry.lastUsedAt = now();
+            if (entry.evicted && entry.active === 0)
+                void entry.connection.close().catch(() => { });
+        }
+    }
+    /**
+     * One `tools/call`. A connection found stale before the tool saw the call is opened again, and
+     * the call sent once more (R2b C7).
+     */
+    async function callOnce(tenantId, request, signal) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal }), true);
+            }
+            catch (error) {
+                if (!(error instanceof McpConnectionStale) || attempt > 0)
+                    throw error;
+            }
         }
     }
     return {
         connect: (tenantId, server) => answer("connect", server, async () => {
-            await connection(tenantId, server);
-            return null;
+            const { instructions } = (await connection(tenantId, server)).connection;
+            // The server's instructions, for the note on its deferred tools (R2b C10).
+            return instructions === undefined ? null : { instructions };
         }),
         list: (tenantId, server, cursor, signal) => answer("list", server, () => use(tenantId, server, (entry) => entry.connection.client.listTools(cursor ? { cursor } : undefined, { signal }))),
-        call: (tenantId, request, signal) => answer("call", request.server, () => use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal })), { effect: request.effectId }),
+        async call(tenantId, request, signal) {
+            const answered = await answer("call", request.server, () => callOnce(tenantId, request, signal), {
+                effect: request.effectId,
+            });
+            if (!answered.ok)
+                return answered;
+            const { result, redacted } = answered.result;
+            return { ok: true, result, ...(redacted ? { redacted } : {}) };
+        },
         async close(server) {
             const key = keyOf(server);
             const entry = live.get(key);
@@ -125,10 +175,16 @@ function fields(server) {
         ...(server.agentId === undefined ? {} : { agent: server.agentId }),
     };
 }
-/** An error as the loop's `diagnosticFromError` reads it. */
+/** An error as the loop's `diagnosticFromError` reads it, with a coded failure's code (R2b C7). */
 function errorOf(error) {
     if (error instanceof GateRefusal)
         return { message: error.outcome.message };
+    if (error instanceof McpCallFailed)
+        return {
+            message: error.message,
+            ...(error.code === "credential_rejected" ? { code: 401 } : {}),
+            failure: error.failure,
+        };
     const message = error instanceof Error ? error.message.slice(0, 2000) : String(error);
     const code = error && typeof error === "object" && "code" in error && typeof error.code === "number"
         ? error.code

package/dist/gates/tenant-vaults.d.ts

@@ -9,12 +9,12 @@
 import type { Credential } from "@earendil-works/pi-ai";
 import type { ModelFailureOutcome } from "@nylorun/core/define";
 import type { PostgresClient } from "../store/postgres/connect.js";
-import { type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
-import { CredentialSources, type McpCredentialRequest, type ResolverConfig } from "../vault/sources.js";
+import { VaultService, type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
+import { type McpCredentialRequest } from "../vault/sources.js";
 import type { SessionStore } from "../store/types.js";
+import type { OutboundPolicy } from "../tenant/outbound.js";
 import type { Session } from "../tenant/context.js";
 import { type Keys } from "../keys/keys.js";
-import { type OutboundPolicy } from "../tenant/outbound.js";
 /** The Tenant, as a model call needs it. */
 export interface TenantVault {
     readonly tenantId: string;
@@ -29,8 +29,7 @@ export interface TenantVault {
     session(sessionId: string): Promise<Session | undefined>;
     /**
      * The authorization of one request to a session's remote MCP server or HTTP tool: its
-     * credential from the session's attached vaults, refreshed when due (F4.1), else from the
-     * operator's credential resolver (F9 C1).
+     * credential from the session's attached vaults.
      */
     authorizeMcp(sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;
     /** Vault writes and token signing with the Tenant's vault key (the keys service, F4.2). */
@@ -52,18 +51,13 @@ export interface TenantVaultsOptions {
     readonly sql: PostgresClient;
     /** The Host root; the gate reads `keys/vault-kek` and `tenant/home` under it. */
     readonly hostRoot: string;
-    /** The operator's credential resolver (`NYLORUN_RESOLVER_*`, F9 C1). */
-    readonly resolver?: ResolverConfig;
-    /**
-     * The Host's address policy (`NYLORUN_ENDPOINT_*`): OAuth refresh and MCP OAuth connect call
-     * authorization servers through `guardedFetch` under it (F9 C2).
-     */
+    /** How the keys service's tool preview reaches a server (`NYLORUN_ENDPOINT_*`, R2b C12). */
     readonly delivery?: OutboundPolicy;
 }
 export declare function createTenantVaults(options: TenantVaultsOptions): TenantVaults;
 /**
- * A request to a session's remote MCP server, authorized from the session's attached vaults,
- * else the operator's credential resolver: what the loop does in its own process
- * (`tenant/effects.ts` `authorize`). The owner and turn come from the session row.
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop does in its own process (`tenant/effects.ts` `authorize`). The vaults come from
+ * the session row.
  */
-export declare function authorizeSessionMcp(sources: CredentialSources, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;
+export declare function authorizeSessionMcp(vault: Pick<VaultService, "authorize">, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;

package/dist/gates/tenant-vaults.js

@@ -8,10 +8,9 @@ import { tenantPaths } from "../tenant/paths.js";
 import { readVaultKek } from "../vault/kek.js";
 import { HostModelVault } from "../vault/host-model.js";
 import { VaultService } from "../vault/service.js";
-import { CredentialSources } from "../vault/sources.js";
+import { sessionCredentials } from "../vault/sources.js";
 import { inProcessKeys } from "../keys/keys.js";
 import { SigningKeys } from "../tenant/signing-keys.js";
-import { guardedFetch } from "../tenant/outbound.js";
 /** A call the gate refuses before the provider is called; it answers with `outcome`. */
 export class GateRefusal extends Error {
     outcome;
@@ -35,20 +34,13 @@ export function createTenantVaults(options) {
             return kek;
         };
         const vault = new HostModelVault({ store, kek: readKek });
-        const credentials = new VaultService({
-            store,
-            kek: readKek,
-            fetch: guardedFetch(options.delivery ?? {}),
-        });
-        const sources = new CredentialSources({
-            vault: credentials,
-            ...(options.resolver ? { resolver: options.resolver } : {}),
-        });
+        const credentials = new VaultService({ store, kek: readKek });
         const keys = inProcessKeys({
             store,
             vault: credentials,
             signingKeys: new SigningKeys({ tenantId, kek: readKek }),
             kek: readKek,
+            ...(options.delivery ? { policy: options.delivery } : {}),
         });
         const session = (sessionId) => store.tx((t) => t.get("sessions", sessionId));
         return {
@@ -58,7 +50,7 @@ export function createTenantVaults(options) {
             readHostModel: () => vault.readHostModel(),
             writeHostCredential: (credential) => vault.updateHostCredential(credential),
             session,
-            authorizeMcp: (sessionId, request) => authorizeSessionMcp(sources, session, sessionId, request),
+            authorizeMcp: (sessionId, request) => authorizeSessionMcp(credentials, session, sessionId, request),
             keys: () => keys,
         };
     }
@@ -87,13 +79,13 @@ export function createTenantVaults(options) {
     };
 }
 /**
- * A request to a session's remote MCP server, authorized from the session's attached vaults,
- * else the operator's credential resolver: what the loop does in its own process
- * (`tenant/effects.ts` `authorize`). The owner and turn come from the session row.
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop does in its own process (`tenant/effects.ts` `authorize`). The vaults come from
+ * the session row.
  */
-export async function authorizeSessionMcp(sources, session, sessionId, request) {
+export async function authorizeSessionMcp(vault, session, sessionId, request) {
     const found = await session(sessionId);
     if (!found)
         throw new Error(`Session ${sessionId} not found`);
-    return sources.authorize({ ...found, id: sessionId }, request);
+    return sessionCredentials(vault, { ...found, id: sessionId }, request);
 }

package/dist/gates/tool-client.js

@@ -6,9 +6,12 @@
  * has finished.
  *
  * Failures keep the meaning they had in the loop's own process:
- * - An MCP request that fails, at the server or on the hop, throws, so the pool reports a
- *   diagnostic and `resolveEffect` marks a call `uncertain`, as before. An HTTP tool call
- *   throws only for the hop, or a call lost with the gateway: its own failures are outcomes.
+ * - An MCP request that fails throws, so the pool reports a diagnostic. A tool call's coded
+ *   failure (R2b C7) throws the `McpCallFailed` the loop's own call would have, which becomes a
+ *   failed outcome the model sees. Only the hop's failures and a call lost with the gateway leave
+ *   it `uncertain`.
+ * - An HTTP tool call throws only for the hop, or a call lost with the gateway: its own failures
+ *   are outcomes.
  *
  * Credentials (F5): a session's MCP requests and keyed cancels carry its run token, read per
  * request from the advance's grant, and leave the session out of the body: the gate takes it
@@ -19,6 +22,7 @@
 import { randomUUID } from "node:crypto";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
+import { McpCallFailed, } from "../mcp/connect.js";
 import { TENANT_HEADER } from "./contract.js";
 import { GATE_CLIENT_TIMEOUT_MS } from "./http-client.js";
 import { HTTP_CALLS_PATH, MCP_CLOSE_PATH, MCP_CONNECT_PATH, MCP_LIST_PATH, TOOL_CALLS_PATH, } from "./tool-contract.js";
@@ -106,10 +110,11 @@ export function httpToolGate(options) {
         return { body: body(unnamed), bearer: token };
     }
     /**
-     * The result of an MCP or HTTP tool request, or a throw the pool and `resolveEffect` read as
-     * before: the call's fate is unknown, and the effect becomes `uncertain`.
+     * The answer of an MCP or HTTP tool request, or a throw: a coded MCP failure (`McpCallFailed`),
+     * or one the pool and `resolveEffect` read as before, the call's fate unknown and the effect
+     * `uncertain`.
      */
-    async function answered(path, scope, request) {
+    async function answer(path, scope, request) {
         const result = await exchange(path, scope.body, {
             ...request,
             timeoutMs,
@@ -123,9 +128,12 @@ export function httpToolGate(options) {
         if (result.status !== 200 || !parsed || !("ok" in parsed))
             throw new Error(gateRefusal(result.status, parsed));
         if (parsed.ok)
-            return parsed.result;
+            return parsed;
         throw mcpError(parsed.error);
     }
+    async function answered(path, scope, request) {
+        return (await answer(path, scope, request)).result;
+    }
     async function fireAndForget(path, scope) {
         await exchange(path, scope.body, {
             timeoutMs: SHORT_TIMEOUT_MS,
@@ -136,24 +144,32 @@ export function httpToolGate(options) {
         recovers: true,
         async openMcp(server) {
             // The credential is read per request: the connection outlives the advance that opened it.
-            await answered(MCP_CONNECT_PATH, scoped(server, (named) => ({ server: named })), {});
+            // A gate answers the server's instructions (R2b C10); an older one answers null.
+            const connected = await answered(MCP_CONNECT_PATH, scoped(server, (named) => ({ server: named })), {});
+            const instructions = typeof connected?.instructions === "string" && connected.instructions.length > 0
+                ? connected.instructions
+                : undefined;
             const client = {
                 listTools: (params, request) => answered(MCP_LIST_PATH, scoped(server, (named) => ({
                     server: named,
                     ...(params?.cursor ? { cursor: params.cursor } : {}),
                 })), request?.signal ? { signal: request.signal } : {}),
-                callTool: (params, request) => answered(TOOL_CALLS_PATH, scoped(server, (named) => ({
-                    server: named,
-                    effectId: request?.key ?? randomUUID(),
-                    name: params.name,
-                    arguments: params.arguments,
-                })), {
-                    ...(request?.signal ? { signal: request.signal } : {}),
-                    ...(request?.key ? { idempotencyKey: request.key } : {}),
-                }),
+                async callTool(params, request) {
+                    const called = await answer(TOOL_CALLS_PATH, scoped(server, (named) => ({
+                        server: named,
+                        effectId: request?.key ?? randomUUID(),
+                        name: params.name,
+                        arguments: params.arguments,
+                    })), {
+                        ...(request?.signal ? { signal: request.signal } : {}),
+                        ...(request?.key ? { idempotencyKey: request.key } : {}),
+                    });
+                    return { result: called.result, ...(called.redacted ? { redacted: called.redacted } : {}) };
+                },
             };
             return {
                 client,
+                ...(instructions === undefined ? {} : { instructions }),
                 close: () => fireAndForget(MCP_CLOSE_PATH, scoped(server, (named) => ({ server: named }))),
             };
         },
@@ -174,6 +190,9 @@ export function httpToolGate(options) {
 }
 /** An MCP failure the gate reported, as the loop's own MCP code would have thrown it. */
 function mcpError(error) {
+    // Coded (R2b C7): the model sees it. A call lost with the gateway never is.
+    if (error.failure && !error.uncertain)
+        return McpCallFailed.from(error.failure);
     const thrown = new Error(error.uncertain ? `${error.message} (the call may have run; it is not sent again)` : error.message);
     if (error.code !== undefined)
         thrown.code = error.code;

package/dist/gates/tool-contract.d.ts

@@ -11,7 +11,9 @@
  * Remote MCP. The gate holds the connection and the vault credential; the loop names the
  * server, never a URL or a credential, and the gate finds it in the session's pinned manifest.
  * - `POST /nylorun/v1/mcp/connect` `{server}`: opens the server's connection (vault
- *   authorization included), or keeps the open one.
+ *   authorization included), or keeps the open one. Its result is `{instructions}` when the
+ *   server gave instructions at `initialize` (R2b C10, for the note on its deferred tools), else
+ *   `null`.
  * - `POST /nylorun/v1/mcp/list` `{server, cursor?}`: one page of `tools/list`.
  * - `POST /nylorun/v1/tool-calls` `{server, effectId, name, arguments}`: one
  *   `tools/call`. With an `Idempotency-Key` (the effect id) the call outlives its client and runs
@@ -20,8 +22,12 @@
  *   gate_forbidden` for another session's call under a run token.
  * - `POST /nylorun/v1/mcp/close` `{server}`: closes the server's connection; `204`.
  * Each answers `200 {ok: true, result}` or `200 {ok: false, error}`: an MCP failure is an
- * answer, not a gate error. A keyed call whose earlier attempt was lost with the gateway answers
- * `{ok: false, error: {uncertain: true}}` and is never run again.
+ * answer, not a gate error. A tool call's failure is coded (`error.failure`, R2b C7), and neither
+ * a result nor a failure carries a credential value the gate sent (C8). An answer past 8 MiB is
+ * `mcp.too-large` (C11), as an HTTP tool's is `http.too-large`; core shapes what fits into a
+ * result the model can take (`tenant/tool-results.ts`). A keyed call whose
+ * earlier attempt was lost with the gateway answers `{ok: false, error: {uncertain: true}}` and
+ * is never run again.
  *
  * HTTP tools (R2 M3). `POST /nylorun/v1/http-calls` `{tool, effectId, turnId, input}`: one call
  * of an HTTP tool. The loop names the tool (`{sessionId?, agentId?, capabilityId, toolName}`), or a
@@ -33,6 +39,7 @@
  * model sees), or `{ok: false, error: {uncertain: true}}` for a call lost with the gateway.
  */
 import { z } from "zod";
+import type { McpCallFailure } from "../mcp/connect.js";
 export declare const MCP_CONNECT_PATH = "/nylorun/v1/mcp/connect";
 export declare const MCP_LIST_PATH = "/nylorun/v1/mcp/list";
 export declare const MCP_CLOSE_PATH = "/nylorun/v1/mcp/close";
@@ -99,10 +106,19 @@ export interface McpGateError {
     readonly credentialIds?: readonly string[];
     /** The call may have run: its earlier attempt was lost with the gateway. Never re-run. */
     readonly uncertain?: boolean;
+    /**
+     * How the request failed, coded (R2b C1, C7): the loop's `McpCallFailed`, which a tool call
+     * turns into a failed outcome the model sees (`mcp.lost` only for a read-only or idempotent
+     * tool). `credential_rejected` for a `401`, with the server and the scope of the vault whose
+     * credential was sent. Its message has no credential value in it (C8).
+     */
+    readonly failure?: McpCallFailure;
 }
 export type McpAnswer<T> = {
     readonly ok: true;
     readonly result: T;
+    /** A `tools/call`'s: how many credential values its result echoed, replaced (R2b C8). */
+    readonly redacted?: number;
 } | {
     readonly ok: false;
     readonly error: McpGateError;

package/dist/gates/tool-contract.js

@@ -11,7 +11,9 @@
  * Remote MCP. The gate holds the connection and the vault credential; the loop names the
  * server, never a URL or a credential, and the gate finds it in the session's pinned manifest.
  * - `POST /nylorun/v1/mcp/connect` `{server}`: opens the server's connection (vault
- *   authorization included), or keeps the open one.
+ *   authorization included), or keeps the open one. Its result is `{instructions}` when the
+ *   server gave instructions at `initialize` (R2b C10, for the note on its deferred tools), else
+ *   `null`.
  * - `POST /nylorun/v1/mcp/list` `{server, cursor?}`: one page of `tools/list`.
  * - `POST /nylorun/v1/tool-calls` `{server, effectId, name, arguments}`: one
  *   `tools/call`. With an `Idempotency-Key` (the effect id) the call outlives its client and runs
@@ -20,8 +22,12 @@
  *   gate_forbidden` for another session's call under a run token.
  * - `POST /nylorun/v1/mcp/close` `{server}`: closes the server's connection; `204`.
  * Each answers `200 {ok: true, result}` or `200 {ok: false, error}`: an MCP failure is an
- * answer, not a gate error. A keyed call whose earlier attempt was lost with the gateway answers
- * `{ok: false, error: {uncertain: true}}` and is never run again.
+ * answer, not a gate error. A tool call's failure is coded (`error.failure`, R2b C7), and neither
+ * a result nor a failure carries a credential value the gate sent (C8). An answer past 8 MiB is
+ * `mcp.too-large` (C11), as an HTTP tool's is `http.too-large`; core shapes what fits into a
+ * result the model can take (`tenant/tool-results.ts`). A keyed call whose
+ * earlier attempt was lost with the gateway answers `{ok: false, error: {uncertain: true}}` and
+ * is never run again.
  *
  * HTTP tools (R2 M3). `POST /nylorun/v1/http-calls` `{tool, effectId, turnId, input}`: one call
  * of an HTTP tool. The loop names the tool (`{sessionId?, agentId?, capabilityId, toolName}`), or a

package/dist/gates/tool-gate.d.ts

@@ -1,8 +1,8 @@
 /**
  * The Tool Gate seam (blueprint §12, F4.1). Every tool call that leaves the loop crosses one
  * `ToolGate`: a remote MCP server's connection and calls, and an HTTP tool's request (R2 M3).
- * The gate owns what those need that the loop must not hold: the MCP and HTTP tool credentials
- * and their OAuth refresh, and the outbound route.
+ * The gate owns what those need that the loop must not hold: the MCP and HTTP tool credentials,
+ * and the outbound route.
  *
  * Two implementations: `inProcessToolGate` (embedding, the ephemeral Runtime, tests), which
  * opens remote servers and calls HTTP tools in this process, and the HTTP client of the gates

package/dist/harness/calls.d.ts

@@ -46,6 +46,8 @@ export declare function invokeModel(route: ModelRoute, request: HostEffect, sign
 export declare function abortOn(signal: AbortSignal, kinds: readonly AbortReason[]): AbortSignal;
 /** True when `request` calls `save_artifact` of the `nylorun.artifacts` capability `manifest` has. */
 export declare function isSaveArtifactCall(manifest: AgentManifest | undefined, request: HostEffect): boolean;
+/** True when `request` calls `read_artifact` (R2b C11) of the `nylorun.artifacts` capability. */
+export declare function isReadArtifactCall(manifest: AgentManifest | undefined, request: HostEffect): boolean;
 /** True when `request` calls a tool of a declared MCP server (every one is remote). */
 export declare function isRemoteMcpCall(routing: Pick<ToolRouting, "rootManifest" | "mcpSnapshot">, request: HostEffect): boolean;
 export declare function callMcpTool(mcp: McpPool, routing: ToolRouting, request: HostEffect, signal: AbortSignal): Promise<unknown>;

package/dist/harness/calls.js

@@ -3,7 +3,7 @@
  * Tenant's provider), the Tool Gate, the MCP pool, the SandboxManager. No store, no record: the
  * session's routing comes with the run (`TurnStart.routing`).
  */
-import { ARTIFACTS_CAPABILITY_ID, SAVE_ARTIFACT_TOOL } from "@nylorun/core/define";
+import { ARTIFACTS_CAPABILITY_ID, READ_ARTIFACT_TOOL, SAVE_ARTIFACT_TOOL, } from "@nylorun/core/define";
 import { runAbortKind } from "@nylorun/harness/api";
 import { httpToolRefOf } from "../gates/http-tool.js";
 import { classifyThrown } from "../model/classify.js";
@@ -67,10 +67,18 @@ export function abortOn(signal, kinds) {
 }
 /** True when `request` calls `save_artifact` of the `nylorun.artifacts` capability `manifest` has. */
 export function isSaveArtifactCall(manifest, request) {
+    return isArtifactsToolCall(manifest, request, SAVE_ARTIFACT_TOOL);
+}
+/** True when `request` calls `read_artifact` (R2b C11) of the `nylorun.artifacts` capability. */
+export function isReadArtifactCall(manifest, request) {
+    return isArtifactsToolCall(manifest, request, READ_ARTIFACT_TOOL);
+}
+function isArtifactsToolCall(manifest, request, toolName) {
     return (request.kind === "tool" &&
         request.capabilityId === ARTIFACTS_CAPABILITY_ID &&
-        request.toolName === SAVE_ARTIFACT_TOOL &&
-        manifest?.capabilities.some((capability) => capability.id === ARTIFACTS_CAPABILITY_ID) === true);
+        request.toolName === toolName &&
+        manifest?.capabilities.some((capability) => capability.id === ARTIFACTS_CAPABILITY_ID &&
+            capability.tools?.some((tool) => tool.name === toolName) === true) === true);
 }
 /** True when `request` calls a tool of a declared MCP server (every one is remote). */
 export function isRemoteMcpCall(routing, request) {
@@ -94,6 +102,8 @@ export async function callMcpTool(mcp, routing, request, signal) {
         args: request.input,
         manifest: routing.rootManifest,
         effectId: request.effectId,
+        // A read-only or idempotent tool's lost answer is the model's to retry (R2b C7, Q15).
+        retrySafe: tool.annotations?.readOnlyHint === true || tool.annotations?.idempotentHint === true,
         signal,
     });
 }

package/dist/harness-api/record.d.ts

@@ -1,12 +1,13 @@
 /**
  * The Record seam of the Harness API: core's journal for the effects of a run. `recordIntent`
  * journals an effect before anything runs it, and either answers it from the journal, hands it
- * to core's own executors (flow work, delegation, `save_artifact` and the skill tools), tells
- * the harness to `execute` it (model calls; MCP, HTTP and sandbox tools; a flow's HTTP stages
- * and HTTP verifiers), or fails a tool the Runtime cannot run (one that would run the
- * developer's code, R2 M6). `recordOutcome`
- * records what the harness's call returned. Both run under the advance's lease: every write is
- * epoch-checked (`ownedSession`), and a lost epoch writes nothing.
+ * to core's own executors (flow work, delegation, `save_artifact`, `read_artifact`,
+ * `tool_search` and the skill tools), tells the harness to `execute` it (model calls; MCP, HTTP
+ * and sandbox tools, a deferred MCP tool's `tool_call` among them, whose effect names the tool;
+ * a flow's HTTP stages and HTTP verifiers), or fails a tool the Runtime cannot run (one that
+ * would run the developer's code, R2 M6). `recordOutcome` records what the harness's call returned, an
+ * agent's MCP or HTTP tool result first shaped to fit (R2b C11). Both run under the advance's
+ * lease: every write is epoch-checked (`ownedSession`), and a lost epoch writes nothing.
  *
  * Rows store the request's hash (`requestHash`) and, for a model call, the request without its
  * prompt: drift is a hash compare. Rows written before carry their full request, hashed on read.