@wirecat/cli-core 0.466.0 → 0.468.0

package/dist/entities/recorded-run.js

@@ -28,7 +28,20 @@ export const recordedRun = v.strictObject({
     cli_command: v.optional(text),
     argv: v.optional(v.array(text)),
     unknown_command: v.optional(text),
-    agent: v.optional(v.strictObject({ kind: text, session_id: v.nullable(text), from_chat: v.optional(v.literal(true)) })),
+    agent: v.optional(v.strictObject({
+        kind: text,
+        session_id: v.nullable(text),
+        from_chat: v.optional(v.literal(true)),
+        client: v.optional(v.strictObject({ name: text, version: v.optional(text), id: v.optional(text) })),
+    })),
+    via: v.optional(v.picklist(["cli", "mcp-stdio", "mcp-http", "desktop"])),
+    mcp: v.optional(v.strictObject({
+        tool: text,
+        request_id: v.optional(text),
+        connection_id: v.optional(text),
+        proxied: v.optional(v.literal(true)),
+    })),
+    events_dropped: v.optional(count),
     error: v.optional(v.strictObject({
         class: text,
         code: v.optional(text),

package/dist/mcp/agent.d.ts

@@ -7,6 +7,7 @@ export type { CommandAvailability } from "../cli/command-availability.js";
 import type { RunOptions } from "../cli/program.js";
 import type { StdinField } from "../cli/stdin-field.js";
 import type { MessengerAdapter } from "../ports/messenger.js";
+import type { RunCaller } from "../runs/run-context.js";
 import { type Level, type PermissionKey } from "../sends/permissions.js";
 /** The CLI's own `run` — a fresh program on every call — and its command tree as `commands --json` describes it. */
 export interface AgentProgram {
@@ -32,6 +33,8 @@ export interface AgentContext {
     stdin?: (path: readonly string[]) => StdinField | undefined;
     /** More of the run's environment, read by the commands that look for it: the server's `spawnJob`, `embedders`. */
     environment?: Readonly<Record<string, unknown>>;
+    /** Who made the call (`callerOf`); the run records it rather than this server's environment. */
+    caller?: RunCaller;
 }
 export type AgentAnswer = {
     result: unknown;
@@ -67,6 +70,8 @@ export interface CatalogueOptions {
     permissions?: CommandPermissions | undefined;
     /** Whether a command changes what a later run may do (`grantsAuthority`): execution requires `mcp.authority`. */
     authority?: (path: readonly string[]) => boolean;
+    /** Whether a command only fetches into this machine (`fetchesOnlyAt`): offered as a read. Unset, every write stays one. */
+    fetchOnly?: (path: readonly string[]) => boolean;
     /** Arguments left out of every tool, by name. */
     omit?: readonly string[];
     /** Offer `offline` on commands that read the messenger: answer from the copy on this machine. */

package/dist/mcp/agent.js

@@ -8,6 +8,7 @@ import { commandAvailability } from "../cli/command-availability.js";
 import { changesMessenger } from "../cli/effects.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
 import { authorityAllowed, botApiAllowed } from "../sends/permissions.js";
+import { currentCaller } from "./caller.js";
 const TYPES = new Map(VOCABULARY.flags.map((flag) => [flag.name, flag.type]));
 // `<name|id>` is one argument: its field is `name_or_id`.
 const snake = (name) => name.replaceAll("|", "_or_").replace(/[^a-z0-9]+/gi, "_");
@@ -153,7 +154,7 @@ export const toolsFromCommands = (commands, options = {}) => {
         path: info.path,
         title: info.summary ?? info.description,
         description: info.description,
-        writes: writes(info.effects),
+        writes: writes(info.effects) && options.fetchOnly?.(info.path) !== true,
         input: schemaOf(fieldsOf(info, options)),
         ...(info.output ? { output: info.output } : {}),
     }));
@@ -231,6 +232,7 @@ export const runCommandForAgent = async (program, path, input, ctx) => {
                 ...(ctx.overrides?.length ? { overrides: ctx.overrides } : {}),
                 authority: levels !== undefined && authorityAllowed(levels),
                 botApi: levels !== undefined && botApiAllowed(levels),
+                ...((ctx.caller ?? currentCaller()) ? { caller: ctx.caller ?? currentCaller() } : {}),
             },
             // Opened only when the command asks: a read the store answers never connects.
             ...(lend

package/dist/mcp/all-profiles.d.ts

@@ -25,6 +25,8 @@ export interface AllProfilesOptions {
     idleMs?: number;
     /** A child's stderr, line by line; never this process's stdout, which carries the protocol. */
     note?: (line: string) => void;
+    /** This server's environment, which names the agent that started it on stdio; `process.env` when left out. */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * The child's tool with the one field that picks the profile, required and without a default. Each profile carries

package/dist/mcp/all-profiles.js

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
+import { CALLER_META_KEY, callerOf, PROXY_CLIENT_NAME } from "./caller.js";
 import { answeredWire } from "./stdio-wire.js";
 const PROTOCOL = "2025-06-18";
 const START_MS = 30_000;
@@ -82,7 +84,7 @@ const startChild = (spec, note, onExit) => {
     return request("initialize", {
         protocolVersion: PROTOCOL,
         capabilities: {},
-        clientInfo: { name: "all-profiles", version: "1" },
+        clientInfo: { name: PROXY_CLIENT_NAME, version: "1" },
     })
         .then(() => {
         send({ method: "notifications/initialized" });
@@ -202,7 +204,12 @@ export const allProfilesServer = (options) => {
                 ? []
                 : (await tools(profiles)).map((one) => withProfile(one, profiles, options.name, signedIn)),
         }));
-        server.server.setRequestHandler("tools/call", async (request) => {
+        const callers = {
+            env: options.env ?? process.env,
+            client: () => server.server.getClientVersion(),
+            connectionId: randomUUID(),
+        };
+        server.server.setRequestHandler("tools/call", async (request, ctx) => {
             const { name, arguments: given = {}, _meta } = request.params;
             const { profile, ...rest } = given;
             if (typeof profile !== "string" || !profiles.includes(profile))
@@ -210,7 +217,13 @@ export const allProfilesServer = (options) => {
             if (!signedIn(profile))
                 return refusal(options.signIn?.(profile) ?? `profile ${profile} is not signed in.`);
             try {
-                return (await children.use(profile, (child) => child.request("tools/call", { name, arguments: rest, ...(_meta ? { _meta } : {}) })));
+                return (await children.use(profile, (child) => 
+                // Children are shared by every session, so each call names its own caller.
+                child.request("tools/call", {
+                    name,
+                    arguments: rest,
+                    _meta: { ..._meta, [CALLER_META_KEY]: callerOf(ctx, name, callers) },
+                })));
             }
             catch (error) {
                 return refusal(`profile ${profile}: ${error instanceof Error ? error.message : String(error)}`);

package/dist/mcp/bot/server.d.ts

@@ -16,6 +16,8 @@ export interface BotServerOptions {
     keyOf?: (path: readonly string[]) => PermissionKey | null | undefined;
     /** Whether a command changes what a later run may do; such a command requires `mcp.authority` to execute. */
     authority?: (path: readonly string[]) => boolean;
+    /** Whether a command only fetches into this machine (`fetchesOnlyAt`): offered through the read tool. */
+    fetchOnly?: (path: readonly string[]) => boolean;
     env: NodeJS.ProcessEnv;
     skill?: URL;
 }

package/dist/mcp/bot/server.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { mcpErrorResult } from "@wirecat/cli-base";
@@ -9,6 +10,7 @@ import { itemOf } from "../../cli/envelope.js";
 import { wholeList } from "../../cli/messenger/chat-answers.js";
 import { MESSENGER_CHANGE_REFUSAL, readOnlyLockOf, readOnlyRefusal } from "../../ports/app.js";
 import { runCommandForAgent, toolsFromCommands } from "../agent.js";
+import { callerOf } from "../caller.js";
 import { normal, registerCommands } from "../surface.js";
 import { agentJson } from "../text.js";
 import { answered } from "../tool.js";
@@ -31,6 +33,7 @@ export const createBotServer = (options) => {
         readOnly: readOnlyLockOf(bot.app, env) !== undefined,
         ...(options.keyOf ? { keyOf: options.keyOf } : {}),
         authority,
+        ...(options.fetchOnly ? { fetchOnly: options.fetchOnly } : {}),
         offline: true,
         // Another bot's copy is this bot's to read only where `read_other_bots` says so.
         ...(settings.readOtherBots ? {} : { omit: ["all_bots", "bots"] }),
@@ -48,7 +51,7 @@ export const createBotServer = (options) => {
     const skill = options.skill ? skillResource(bot.app, options.skill) : undefined;
     // One at a time: the commands share the journal, the registry and the local copy.
     let queue = Promise.resolve();
-    const invoke = (path, input) => {
+    const invoke = (path, input, caller) => {
         const next = queue.then(() => runCommandForAgent(program, path, path[0] === "config" ? { ...input, bot: true } : input, {
             profile: settings.profile,
             readOnly: readOnlyLockOf(bot.app, env) !== undefined,
@@ -56,11 +59,13 @@ export const createBotServer = (options) => {
             levels,
             ...(options.keyOf ? { keyOf: options.keyOf } : {}),
             authority,
+            ...(caller ? { caller } : {}),
         }));
         queue = next.catch(() => undefined);
         return next;
     };
     const build = () => {
+        const callers = { env, client: () => server.server.getClientVersion(), connectionId: randomUUID() };
         const server = new McpServer({ name: `${command}-bot-${settings.profile}`, version: bot.app.version }, {
             instructions: botInstructions({
                 command,
@@ -82,8 +87,9 @@ export const createBotServer = (options) => {
                 writes: tool.writes,
                 availability: tool.availability,
                 input: tool.input,
-                run: async (args) => {
-                    const answer = await invoke(tool.path, args);
+                run: async (args, ctx) => {
+                    const caller = callerOf(ctx, `${command}_${tool.command.replaceAll(" ", "_")}`, callers);
+                    const answer = await invoke(tool.path, args, caller);
                     return "error" in answer
                         ? mcpErrorResult(JSON.parse(agentJson(answer.error)))
                         : answered(body(tool.command, answer.result));

package/dist/mcp/caller.d.ts

@@ -0,0 +1,38 @@
+import { type RunCaller } from "../runs/run-context.js";
+export { currentCaller, withCaller } from "../runs/run-context.js";
+/** The `_meta` key the every-profile server names the real caller under, for the profile server it passes a call to. */
+export declare const CALLER_META_KEY = "wirecat.dev/caller";
+/** The name the every-profile server gives itself in `initialize`; only a connection from it may name a caller. */
+export declare const PROXY_CLIENT_NAME = "all-profiles";
+/** What a tool call's handler is given, reduced to what identifies the caller. */
+export interface CallContext {
+    sessionId?: string | undefined;
+    mcpReq?: {
+        id?: string | number;
+        _meta?: Record<string, unknown> | undefined;
+    } | undefined;
+    http?: {
+        authInfo?: {
+            clientId: string;
+            extra?: Record<string, unknown> | undefined;
+        } | undefined;
+    } | undefined;
+}
+export interface CallerSource {
+    /** This server's environment: the coding agent that started a stdio server. Never read for an HTTP call. */
+    env: NodeJS.ProcessEnv;
+    /** The client's `initialize`, when this connection had one. */
+    client?: () => {
+        name: string;
+        version?: string;
+    } | undefined;
+    /** One id per stdio connection, made when the server starts. */
+    connectionId?: string;
+}
+/**
+ * Who made one MCP call. Over HTTP the server's own environment is somebody else's — whoever started `mcp --http` —
+ * so the caller is the OAuth client (its registered name and a hash of its id) and the HTTP session, if any. Over
+ * stdio the agent that started the server is the caller, and `initialize` names its client. A call the every-profile
+ * server passed on carries the caller it worked out, trusted only on a connection that server opened.
+ */
+export declare const callerOf: (ctx: CallContext | undefined, tool: string, source: CallerSource) => RunCaller;

package/dist/mcp/caller.js

@@ -0,0 +1,95 @@
+import { CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
+import { agentOf, clientHash } from "../runs/run-context.js";
+export { currentCaller, withCaller } from "../runs/run-context.js";
+/** The `_meta` key the every-profile server names the real caller under, for the profile server it passes a call to. */
+export const CALLER_META_KEY = "wirecat.dev/caller";
+/** The name the every-profile server gives itself in `initialize`; only a connection from it may name a caller. */
+export const PROXY_CLIENT_NAME = "all-profiles";
+const NAME = /^[\w .@()/+-]{1,64}$/;
+const plain = (value) => typeof value === "string" && NAME.test(value.trim()) ? value.trim() : undefined;
+const clientFrom = (value) => {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const { name, version } = value;
+    const named = plain(name);
+    if (!named)
+        return undefined;
+    const versioned = plain(version);
+    return { name: named, ...(versioned ? { version: versioned } : {}) };
+};
+/**
+ * Who made one MCP call. Over HTTP the server's own environment is somebody else's — whoever started `mcp --http` —
+ * so the caller is the OAuth client (its registered name and a hash of its id) and the HTTP session, if any. Over
+ * stdio the agent that started the server is the caller, and `initialize` names its client. A call the every-profile
+ * server passed on carries the caller it worked out, trusted only on a connection that server opened.
+ */
+export const callerOf = (ctx, tool, source) => {
+    const meta = ctx?.mcpReq?._meta;
+    const requestId = ctx?.mcpReq?.id;
+    const initialized = source.client?.();
+    const proxied = initialized?.name === PROXY_CLIENT_NAME ? passedOn(meta?.[CALLER_META_KEY], tool) : undefined;
+    if (proxied)
+        return proxied;
+    const client = clientFrom(meta?.[CLIENT_INFO_META_KEY]) ?? clientFrom(initialized);
+    const mcp = (connection) => ({
+        tool,
+        ...(requestId === undefined ? {} : { request_id: String(requestId) }),
+        ...(connection ? { connection_id: connection } : {}),
+    });
+    const auth = ctx?.http?.authInfo;
+    if (auth) {
+        const registered = plain(auth.extra?.clientName);
+        return {
+            via: "mcp-http",
+            agent: {
+                kind: "mcp-client",
+                session_id: ctx?.sessionId ?? null,
+                client: {
+                    name: registered ?? client?.name ?? "unknown",
+                    ...(client?.version ? { version: client.version } : {}),
+                    id: clientHash(auth.clientId),
+                },
+            },
+            mcp: mcp(ctx?.sessionId),
+        };
+    }
+    const agent = agentOf(source.env) ?? { kind: "mcp-client", session_id: null };
+    return { via: "mcp-stdio", agent: { ...agent, ...(client ? { client } : {}) }, mcp: mcp(source.connectionId) };
+};
+/** The caller the every-profile server named, field by field: nothing else it sent reaches a run. */
+const passedOn = (value, tool) => {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const { via, agent, mcp } = value;
+    if (via !== "mcp-stdio" && via !== "mcp-http")
+        return undefined;
+    const a = agent && typeof agent === "object" ? agent : undefined;
+    const kind = plain(a?.kind);
+    const session = typeof a?.session_id === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(a.session_id) ? a.session_id : null;
+    const client = clientFrom(a?.client);
+    const id = a?.client && typeof a.client === "object" ? a.client.id : undefined;
+    const m = mcp && typeof mcp === "object" ? mcp : {};
+    const request = plain(m.request_id);
+    const connection = typeof m.connection_id === "string" && /^[\w-]{1,128}$/.test(m.connection_id) ? m.connection_id : undefined;
+    return {
+        via,
+        ...(kind
+            ? {
+                agent: {
+                    kind,
+                    session_id: session,
+                    ...(a?.from_chat === true ? { from_chat: true } : {}),
+                    ...(client
+                        ? { client: { ...client, ...(typeof id === "string" && /^[0-9a-f]{8}$/.test(id) ? { id } : {}) } }
+                        : {}),
+                },
+            }
+            : {}),
+        mcp: {
+            tool,
+            ...(request ? { request_id: request } : {}),
+            ...(connection ? { connection_id: connection } : {}),
+            proxied: true,
+        },
+    };
+};

package/dist/mcp/http/oauth.js

@@ -258,15 +258,19 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
     const verifier = {
         verifyAccessToken: async (presented) => {
             const seconds = Math.floor(now() / 1000);
-            const found = store.read().tokens.find((one) => one.kind === "access" && one.hash === hash(presented));
+            const stored = store.read();
+            const found = stored.tokens.find((one) => one.kind === "access" && one.hash === hash(presented));
             if (!found || found.expiresAt <= seconds)
                 throw new OAuthError(OAuthErrorCode.InvalidToken, "the token is unknown or expired");
+            // The name the app registered with, so a run can say which app called; the id itself never leaves here unhashed.
+            const clientName = stored.clients.find((one) => one.id === found.clientId)?.name;
             return {
                 token: presented,
                 clientId: found.clientId,
                 scopes: [],
                 expiresAt: found.expiresAt,
                 resource,
+                ...(clientName ? { extra: { clientName } } : {}),
             };
         },
     };

package/dist/mcp/server.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport, serveStdio } from "@modelcontextprotocol/server/stdio";
 import { CliError, mcpErrorResult } from "@wirecat/cli-base";
@@ -7,7 +8,7 @@ import * as v from "valibot";
 import { findCommand } from "../cli/command-contract.js";
 import { environmentOf } from "../cli/context.js";
 import { refuseWriteBeforeConnecting } from "../cli/early-refusal.js";
-import { changesAuthorityAt, judgedTargets } from "../cli/effects.js";
+import { changesAuthorityAt, fetchesOnlyAt, judgedTargets } from "../cli/effects.js";
 import { itemOf } from "../cli/envelope.js";
 import { DEFAULT_OUTPUT_BYTES } from "../cli/execution.js";
 import { recalledAccount } from "../cli/messenger/accounts.js";
@@ -25,6 +26,7 @@ import { levelFor, readKeysForCommand } from "../sends/permissions.js";
 import { openStore } from "../store/store.js";
 import { runCommandForAgent, toolsFromCommands } from "./agent.js";
 import { agentLog } from "./agent-log.js";
+import { callerOf, withCaller } from "./caller.js";
 import { mcpHttpMarker } from "./http/state.js";
 import { instructions } from "./instructions.js";
 import { registerPrompts } from "./prompts.js";
@@ -125,6 +127,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         readOnly: readOnlyLockOf(app, context.env) !== undefined,
         keyOf,
         authority,
+        fetchOnly: fetchesOnlyAt(root),
         offline: true,
         stdin,
     }).map((one) => "sync_first" in one.input.entries && !syncAllowed(one.path)
@@ -195,7 +198,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
      * One command at a time, on the session's connection, opened only if the command asks for it. A failure that may
      * have been the connection's drops it, as the session does for its own calls.
      */
-    const invoke = (one, input, env) => new Promise((resolve) => {
+    const invoke = (one, input, env, caller) => new Promise((resolve) => {
         let finish;
         let held;
         const connection = () => new Promise((lend, refuse) => {
@@ -219,6 +222,7 @@ export const createServer = (command, context, messenger, sessionOptions) => {
             stdin,
             connection,
             environment: agentEnvironment,
+            caller,
         }).then(async (answer) => {
             finish?.("error" in answer && !harmless(answer.error.error.code));
             await held?.catch(() => undefined);
@@ -226,12 +230,12 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         });
     });
     let queue = Promise.resolve();
-    const queued = (one, input, env) => {
-        const next = queue.then(() => invoke(one, input, env));
+    const queued = (one, input, env, caller) => {
+        const next = queue.then(() => invoke(one, input, env, caller));
         queue = next.catch(() => undefined);
         return next;
     };
-    const asCommand = (one) => ({
+    const asCommand = (one, source) => ({
         title: one.title,
         description: one.description,
         writes: one.writes,
@@ -243,7 +247,9 @@ export const createServer = (command, context, messenger, sessionOptions) => {
             // The caller's trace reaches the run, its send journal lines and its record, as `TRACEPARENT` does.
             const traceparent = ctx?.mcpReq?._meta?.traceparent;
             const env = typeof traceparent === "string" ? { ...context.env, TRACEPARENT: traceparent } : context.env;
-            const answer = await queued(one, args, env);
+            const caller = callerOf(ctx, keyOfCommand(one.command), source);
+            // The connection the session opens for this call is recorded under the same caller.
+            const answer = await withCaller(caller, () => queued(one, args, env, caller));
             const result = "error" in answer
                 ? mcpErrorResult(JSON.parse(agentJson(answer.error)))
                 : (() => {
@@ -266,6 +272,12 @@ export const createServer = (command, context, messenger, sessionOptions) => {
         },
     });
     const build = () => {
+        // Built once for a stdio connection; over HTTP the session or the OAuth client identifies the caller instead.
+        const callers = {
+            env: context.env,
+            client: () => server.server.getClientVersion(),
+            connectionId: randomUUID(),
+        };
         const server = new McpServer({ name: app.command, version: app.version }, {
             instructions: instructions({
                 command: app.command,
@@ -305,11 +317,12 @@ export const createServer = (command, context, messenger, sessionOptions) => {
                 env: context.env,
                 ...(context.keyring ? { keyring: context.keyring } : {}),
                 embedders,
-                history: settings.keepFailedRuns,
+                history: settings.record,
             },
+            callers,
         };
         registerCommands(server, app.command, {
-            ...Object.fromEntries(commands.map((one) => [one.command, asCommand(one)])),
+            ...Object.fromEntries(commands.map((one) => [one.command, asCommand(one, callers)])),
             ...Object.fromEntries(Object.entries(surfaceCommands({ ...pictures, status }, registration)).map(([name, one]) => [
                 name,
                 {

package/dist/mcp/surface.js

@@ -1,8 +1,10 @@
+import { randomUUID } from "node:crypto";
 import { toJsonSchema, toStandardJsonSchema } from "@valibot/to-json-schema";
 import { CliError } from "@wirecat/cli-base";
 import * as v from "valibot";
 import { answerSchema, listOf } from "../cli/envelope.js";
 import { ENTITIES } from "../entities/index.js";
+import { callerOf, currentCaller, withCaller } from "./caller.js";
 import { agentArguments } from "./text.js";
 import { answered, commandOf, entryRunner, failed, inputOf, outputSchemaOf, READ, syncAllowedFor, UNTRUSTED, UNTRUSTED_NEUTRAL, WRITE, } from "./tool.js";
 const MATCHES = 8;
@@ -113,6 +115,12 @@ isMessenger) => {
         });
         return answered(list);
     });
+    // A CLI's own server runs in its own process: its environment names the agent that started it on stdio.
+    const callers = {
+        env: process.env,
+        client: () => server.server.getClientVersion(),
+        connectionId: randomUUID(),
+    };
     const runner = (writing) => async ({ command: asked, arguments: given }, ctx) => {
         try {
             const command = byNormal.get(normal(asked));
@@ -125,14 +133,15 @@ isMessenger) => {
             if (one.writes !== writing)
                 throw new CliError("validation_error", `"${command}" ${writing ? "only reads" : "writes"}: call it with ${prefix}_${writing ? "read" : "write"}`);
             const args = writing ? agentArguments(given ?? {}) : (given ?? {});
+            const caller = currentCaller() ?? callerOf(ctx, command.replace(/[ -]/g, "_"), callers);
             if (one.checked)
-                return runnableOnly(await one.run(args, ctx), (named) => byNormal.has(normal(named)));
+                return runnableOnly(await withCaller(caller, () => one.run(args, ctx)), (named) => byNormal.has(normal(named)));
             const parsed = v.safeParse(v.strictObject(one.input.entries), args);
             if (!parsed.success)
                 throw new CliError("validation_error", `${command}: ${v.summarize(parsed.issues)}`, {
                     arguments: toJsonSchema(one.input),
                 });
-            return runnableOnly(await one.run(parsed.output, ctx), (named) => byNormal.has(normal(named)));
+            return runnableOnly(await withCaller(caller, () => one.run(parsed.output, ctx)), (named) => byNormal.has(normal(named)));
         }
         catch (error) {
             return failed(error, errors);

package/dist/mcp/tool.d.ts

@@ -13,6 +13,7 @@ import type { SendGuard } from "../sends/guard.js";
 import { type PermissionKey } from "../sends/permissions.js";
 import { type Services } from "../services/index.js";
 import type { AccountKey, MessageStore } from "../store/store.js";
+import { type CallerSource } from "./caller.js";
 import type { MessengerSession } from "./session.js";
 export declare const limit: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 100, undefined>, v.DescriptionAction<number, "how many">]>, undefined>;
 export declare const page: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.DescriptionAction<number, "which page, from 1">]>, undefined>;
@@ -34,7 +35,7 @@ export interface Defaults {
     limit: number;
     guard: SendGuard;
     /** The profile's own entries, for a tool reading a setting of its own — `transcribeWith`. */
-    settings: Pick<Settings, "configured" | "shared" | "profile"> & Partial<Pick<Settings, "permissions" | "searchCatchUp" | "pictureSearch" | "searchReranker" | "offline">> & AISettings;
+    settings: Pick<Settings, "configured" | "shared" | "profile"> & Partial<Pick<Settings, "permissions" | "searchCatchUp" | "pictureSearch" | "searchReranker" | "offline" | "record" | "keepFailedRuns" | "keepRunsForDays" | "keepSuccessfulRunsForDays" | "runsSizeLimitMb">> & AISettings;
     env: NodeJS.ProcessEnv;
     keyring?: KeyringStore;
     /** The server's open models, kept between `search_conversations` calls. */
@@ -123,6 +124,8 @@ export interface Registration {
     log?: (call: ToolCall) => Promise<void>;
     /** The CLI's commands, by which an answer's next steps are judged safe to run unasked. */
     targets?: NonNullable<StepInput["targets"]>;
+    /** How a call's caller is worked out on this connection (`callerOf`); without it the environment's agent is kept. */
+    callers?: CallerSource;
 }
 export type ToolTier = "read" | "draft" | "write-private" | "write-public" | "destructive" | "admin";
 export interface ToolCall {

package/dist/mcp/tool.js

@@ -9,13 +9,14 @@ import { MAX_BUFFERED_INPUT } from "../cli/input-policy.js";
 import { refuseLacking } from "../cli/messenger/lacks.js";
 import { ENTITIES } from "../entities/index.js";
 import { failureContext } from "../errors/reasons.js";
-import { partialOutcome, startRecording } from "../runs/recording.js";
+import { startRecording } from "../runs/recording.js";
 import { newRunId } from "../runs/run.js";
-import { runContextOf } from "../runs/run-context.js";
+import { keepsSuccess, runContextOf } from "../runs/run-context.js";
 import { inRun } from "../runs/scope.js";
 import { keyForCommand, levelFor, readKeysForCommand } from "../sends/permissions.js";
 import { onlineDeps, storeModeDeps } from "../services/deps.js";
 import { servicesFor } from "../services/index.js";
+import { callerOf, currentCaller, withCaller } from "./caller.js";
 import { agentJson } from "./text.js";
 export const limit = v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100), v.description("how many")));
 export const page = v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.description("which page, from 1")));
@@ -104,19 +105,25 @@ export const entryRunner = (registration) => {
         const command = `mcp ${commandOf(key, definition)}`;
         const traceId = traceIdOf(ctx?.mcpReq?._meta?.traceparent);
         const app = registration.messenger?.app;
-        const recording = key !== "runs_search" && registration.defaults.history !== false && app?.appName
+        const caller = registration.callers ? callerOf(ctx, key, registration.callers) : currentCaller();
+        const env = registration.defaults.env ?? process.env;
+        const settings = registration.defaults.settings;
+        const recording = key !== "runs_search" && settings.keepFailedRuns !== false && app?.appName
             ? startRecording({
                 app,
                 command,
-                ...(registration.defaults.settings.profile === undefined
-                    ? {}
-                    : { profile: registration.defaults.settings.profile }),
-                env: registration.defaults.env,
-                record: false,
+                ...(settings.profile === undefined ? {} : { profile: settings.profile }),
+                env,
+                record: keepsSuccess({ record: settings.record ?? true, fromFlag: false, env, caller }),
                 keepFailed: true,
                 trace: false,
                 format: "json",
-                context: runContextOf({ bin: app.command, command, env: registration.defaults.env ?? process.env }),
+                context: runContextOf({ bin: app.command, command, env, caller }),
+                ...(settings.keepRunsForDays === undefined ? {} : { keepDays: settings.keepRunsForDays }),
+                ...(settings.keepSuccessfulRunsForDays === undefined
+                    ? {}
+                    : { keepSuccessDays: settings.keepSuccessfulRunsForDays }),
+                ...(settings.runsSizeLimitMb === undefined ? {} : { maxBytes: settings.runsSizeLimitMb * 1024 * 1024 }),
                 ...(traceId === undefined ? {} : { traceId }),
             })
             : undefined;
@@ -127,8 +134,9 @@ export const entryRunner = (registration) => {
             startedAt,
             ...(profile === undefined ? {} : { profile }),
             ...(traceId === undefined ? {} : { traceId }),
+            ...(recording ? { events: recording.events } : {}),
         };
-        const result = await inRun(scope, () => {
+        const work = () => inRun(scope, () => {
             const input = inputOf(definition, syncAllowedFor(key, registration.defaults));
             const parsed = v.safeParse(input, args);
             return parsed.success
@@ -137,7 +145,9 @@ export const entryRunner = (registration) => {
                     arguments: toJsonSchema(input),
                 }), app?.errors);
         });
-        if (recording && (result.isError || partialOutcome(result.structuredContent))) {
+        // The connection a session opens for this call is recorded under the same caller.
+        const result = await (caller ? withCaller(caller, work) : work());
+        if (recording) {
             if (result.isError) {
                 const error = result.structuredContent?.error;
                 const code = error?.code && errorCodes.includes(error.code)

package/dist/runs/events.d.ts

@@ -2,10 +2,12 @@
  * One operation against the messenger, as both sinks see it: `--trace` renders it, a recorded run
  * writes it as a line of JSON.
  *
- * ⚠ **Nothing here may carry content.** An operation name, an id, a count, a duration and an error
- * code are safe. A chat title, a name, a message body, a phone number or a token are not — not
- * truncated and not hashed. The adapter builds `ids` and `counts` from fields it names, never by
- * copying a request, and never from what the person typed: a typed chat is often a title.
+ * ⚠ **Nothing here may carry content.** An operation name, an id, a file or folder path, a count, a duration and an
+ * error code are safe: a run record stays on the owner's machine, and keeping the ids that tell runs apart was the
+ * owner's choice (NEED-110, 2026-10-27). A chat title, a name, a message body, a phone number, a token, a URL as sent
+ * or a query string are not — not truncated and not hashed. The adapter builds `ids` and `counts` from fields it names,
+ * never by copying a request, and never from what the person typed: a typed chat is often a title. Anything that
+ * leaves the machine (a bug report) strips the ids too.
  */
 export interface RequestEvent {
     event: "request" | "response";
@@ -30,6 +32,16 @@ export interface RequestEvent {
     errorCode?: string;
     /** The messenger's own name for a refusal, when it is shaped like one (`providerErrorKey`). */
     providerError?: string;
+    /**
+     * `operation` for one adapter call (`observed`), `wire` for one call on the network under it. A run counts wire
+     * requests when it has any, so one operation over three frames is three requests, never four.
+     */
+    level?: "operation" | "wire";
+    transport?: "http" | "mtproto" | "max-ws" | "wa-engine";
+    /** 1 for the first try, 2 and up for a retry of the same call. */
+    attempt?: number;
+    /** How long the client waited before this attempt: a flood wait or a `Retry-After`. */
+    waitMs?: number;
 }
 /** Something the client noticed and went on without. A code, never the sentence. */
 export interface WarningEvent {

package/dist/runs/events.js

@@ -28,6 +28,10 @@ export const renderEvent = (event) => {
             parts.push([event.method, event.endpointTemplate].filter(Boolean).join(" "));
         if (event.status !== undefined)
             parts.push(`${event.status}`);
+        if (event.attempt !== undefined && event.attempt > 1)
+            parts.push(`attempt ${event.attempt}`);
+        if (event.waitMs !== undefined)
+            parts.push(`waited ${age(event.waitMs)}`);
     }
     if (event.ids)
         for (const [name, value] of Object.entries(event.ids))