agentradar-cli 0.3.5 → 0.3.7

package/dist/tool-run.js

@@ -1,8 +1,8 @@
-import { readFile, realpath, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { commandFor, DEPRECATED_TOOLS, toolFor } from "./commands.js";
-import { cliHeader, newer, runningVersion } from "./update.js";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { cliHeader, noteCliUpdate, withCliUpdate } from "./update.js";
+const UNAUTHORIZED = "AgentRadar refused the tool call (401): this agent's key is no longer valid on this server (it was revoked, or the hire it was issued for has ended). Nothing was done. Stop calling tools with this key and tell the person who runs you.";
 /**
  * One `KEY='value'` line as `setup.ts` wrote it, single-quoted with `'` escaped as `'\''`.
  * Nothing here is printed: the file holds the runner's bearer.
@@ -15,39 +15,59 @@ export function envValue(contents, key) {
     const quoted = raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2;
     return (quoted ? raw.slice(1, -1).replaceAll("'\\''", "'") : raw) || null;
 }
-export async function runServiceToolOverCli(runnerId, toolKey, argumentsJson, deps = {}) {
-    const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
-    if (!parameters)
-        return 1;
-    return await callAwpTool(runnerId, "run_service_tool", { toolKey, arguments: parameters, entryPoint: "cli" }, deps);
-}
-/** `agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>']`: any AWP tool from a shell, so a just-joined agent works before its harness reloads MCP tools. */
-export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {}, flags = []) {
+/**
+ * #1871 slice 1: `agentradar <noun> [<sub-noun>] <verb> [--<argument> <value> ...]`, every path read from the server's
+ * tools/list (`_meta.cli.path`), so a new tool or a renamed path needs no CLI release. `command` is that path, or a
+ * tool name (`call <runner-id> <tool>` and `run <runner-id> <tool>` stay until slices 4-5). A group prints its
+ * children, a leaf with --help its generated flags.
+ */
+export async function callToolOverCli(runnerId, command, argumentsJson, deps = {}, flags = []) {
     const switches = new Set(flags.filter(([flag]) => ["help", "dry-run", "json"].includes(flag)).map(([flag]) => flag));
     flags = flags.filter(([flag]) => !switches.has(flag));
-    // A noun has no underscore; a tool name has one unless it is a single word (reply, recall), which the resolver returns as is.
-    if (tool.includes(" ") || (switches.has("help") && tool !== "" && !tool.includes("_"))) {
-        const resolved = await resolveCommand(runnerId, tool, switches.has("help"), deps);
-        if (typeof resolved === "number")
-            return resolved;
-        tool = resolved;
-    }
-    if (switches.has("help"))
-        return await describeTools(runnerId, tool, deps);
+    let tool = command;
     const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
     if (!parameters)
         return EXIT.usage;
-    if (flags.length) {
-        const typed = await flagArguments(runnerId, tool, flags, deps);
-        if (!typed)
-            return EXIT.usage;
-        Object.assign(parameters, typed);
+    // A bare tool name with nothing to type goes straight to the server: the hot `inbox next` poll and the get_self probe
+    // cost no tools/list round trip.
+    if (switches.has("help") || flags.length || argumentsJson !== undefined || !command.includes("_")) {
+        const tools = await listedTools(runnerId, deps);
+        if (!tools)
+            return EXIT.refused;
+        const entry = tools.find((candidate) => pathOf(candidate) === command) ?? tools.find((candidate) => candidate.name === command);
+        if (!entry?.name)
+            return groupHelp(runnerId, command, tools, switches.has("help"), deps);
+        if (switches.has("help")) {
+            (deps.log ?? console.log)(leafHelp(entry));
+            return EXIT.ok;
+        }
+        tool = entry.name;
+        const schema = entry.inputSchema?.properties ?? {};
+        // PER-TOOL-MODES (Vadym 12919): `--tool X=ask` builds `tools`, on any tool that takes `tools` and no `tool`.
+        if ("tools" in schema && !("tool" in schema) && flags.some(([flag]) => flag === "tool")) {
+            const named = namedToolFlags(flags);
+            parameters.tools = named.tools;
+            flags = named.flags;
+        }
+        if (flags.length) {
+            const typed = await flagArguments(entry, flags, deps);
+            if (!typed)
+                return EXIT.usage;
+            Object.assign(parameters, typed);
+        }
+        // Provenance for the execution ledger (R572), not permission: the server treats it as the self-report it is.
+        if ("entryPoint" in schema && parameters.entryPoint === undefined)
+            parameters.entryPoint = "cli";
     }
     // --dry-run: say exactly what would be sent, and send nothing.
     if (switches.has("dry-run")) {
         (deps.log ?? console.log)(JSON.stringify({ dryRun: true, tool, arguments: parameters }));
         return EXIT.ok;
     }
+    if (tool === "inbox_search" && !switches.has("json")) {
+        const log = deps.log ?? console.log;
+        deps = { ...deps, log: (text) => log(inboxLines(text)) };
+    }
     if (tool !== "next_event" || !RUNNER_ID.test(runnerId))
         return await callAwpTool(runnerId, tool, parameters, deps);
     // A bare poll acknowledges the batch the previous poll printed, so the command stays byte-identical and
@@ -59,6 +79,8 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
         if (Array.isArray(ids) && ids.length)
             parameters.ackEventIds = ids;
     }
+    // The agent's own poll answers at once: the channel process holds the long poll, and a held agent call stalls its whole turn.
+    parameters.waitMs ??= 0;
     let said = "";
     const code = await callAwpTool(runnerId, tool, parameters, { ...deps, log: (text) => { said = text; (deps.log ?? console.log)(text); } });
     if (code !== 0)
@@ -69,7 +91,8 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
     }
     catch { /* not a batch: nothing to acknowledge */ }
     const ids = Array.isArray(events) ? events.map((event) => event?.eventId).filter((id) => typeof id === "string") : [];
-    await writeFile(delivered, JSON.stringify(ids), { mode: 0o600 }).catch(() => undefined);
+    // A hosted home has no runner file, so the folder may not exist yet; without it the ack and the channel's proof of a poll were lost.
+    await mkdir(dirname(delivered), { recursive: true }).then(() => writeFile(delivered, JSON.stringify(ids), { mode: 0o600 })).catch(() => undefined);
     return 0;
 }
 /**
@@ -77,39 +100,16 @@ export async function callToolOverCli(runnerId, tool, argumentsJson, deps = {},
  * (its sentence is on stderr); 2 the command itself was wrong (unknown command, missing or mistyped argument).
  */
 export const EXIT = { ok: 0, refused: 1, usage: 2 };
-/**
- * `<noun> <verb>` → the tool it names on this server; or an exit code once `<noun> --help` has listed its
- * verbs, or after saying what is wrong.
- */
-async function resolveCommand(runnerId, command, help, deps) {
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return EXIT.refused;
-    const names = tools.map((entry) => entry.name ?? "").filter((name) => name && !DEPRECATED_TOOLS.has(name));
-    const [noun, verb] = command.split(" ");
-    if (!verb && names.includes(noun))
-        return noun;
-    if (verb) {
-        const tool = toolFor(noun, verb, names);
-        if (tool)
-            return tool;
-    }
-    const verbs = names.filter((name) => commandFor(name)[0] === noun).map((name) => commandFor(name)[1]).sort();
-    const log = help && !verb ? deps.log ?? console.log : deps.logError ?? console.error;
-    log(verbs.length
-        ? `${verb ? `${noun} ${verb} is not a command. ` : ""}agentradar run ${runnerId} ${noun} <verb>: ${verbs.join(" ")}. Add --help to a command for its arguments.`
-        : `${noun} is not a command group. Groups: ${[...new Set(names.map((name) => commandFor(name)[0]))].sort().join(" ")}.`);
-    return help && !verb && verbs.length ? EXIT.ok : EXIT.usage;
-}
-/** Split `<runner-id> <tool> [--args '<json>'] [--<argument> <value> ...]`; null when it is not that shape. */
+const EXIT_CODES = "EXIT CODES\n  0 done   1 refused or unreachable (the reason is on stderr)   2 fix the command";
+/** Split `<word> ... [--args '<json>'] [--<argument> <value> ...]`; null when a flag has no value. */
 export function parseCallArgs(rest) {
-    const positional = [];
+    const words = [];
     const flags = [];
     let json;
     for (let i = 0; i < rest.length; i++) {
         const arg = rest[i];
         if (!arg.startsWith("--")) {
-            positional.push(arg);
+            words.push(arg);
             continue;
         }
         if (arg === "--help" || arg === "--dry-run" || arg === "--json") {
@@ -124,55 +124,70 @@ export function parseCallArgs(rest) {
         else
             flags.push([arg.slice(2), value]);
     }
-    const help = flags.some(([flag]) => flag === "help");
-    // `<runner-id> <noun> <verb>` (Vadym 9970) names the same tool as `<runner-id> <tool>`; resolved against the server's list.
-    if (positional.length === 3)
-        return { runnerId: positional[0], tool: `${positional[1]} ${positional[2]}`, json, flags };
-    return positional.length === 2 || (help && positional.length === 1)
-        ? { runnerId: positional[0], tool: positional[1] ?? "", json, flags } : null;
+    return { words, json, flags };
 }
+const pathOf = (tool) => typeof tool._meta?.cli?.path === "string" ? tool._meta.cli.path : undefined;
+const kebab = (name) => name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+const firstSentence = (text = "") => text.split(/(?<=[.!?])\s/)[0].trim();
 async function listedTools(runnerId, deps) {
     const listed = await awpRequest(runnerId, "tools/list", {}, deps);
     return listed ? listed.result?.tools ?? [] : null;
 }
-// An agent that guessed a tool name from memory needs the real list, or it goes looking with commands
-// its harness has not allowed and the session stalls on a permission prompt.
-const unknownTool = (runnerId, tool, tools) => `${tool} is not a tool on this server. Its tools: ${tools.map((entry) => entry.name).join(" ")}. `
-    + `\`agentradar run ${runnerId} <tool> --help\` shows a tool's arguments.`;
-/** `agentradar run <runner-id> [<tool>] --help`: the server's own tool list or one tool's arguments. */
-async function describeTools(runnerId, tool, deps) {
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return 1;
-    const log = deps.log ?? console.log;
-    if (!tool) {
-        log(`Tools: ${tools.map((entry) => entry.name).join(" ")}. \`agentradar run ${runnerId} <tool> --help\` shows a tool's arguments.`);
-        return 0;
+// A connected service's tool (ask_question on a company's MCP) is never in the tool list, so an agent told to use one by
+// name said "not available" instead of running it (behaviour evals tool-mode, approval-third-person; #2010).
+const serviceTools = (runnerId, tools) => {
+    const command = (name) => { const tool = tools.find((entry) => entry.name === name); return tool && (pathOf(tool) ?? `run ${runnerId} ${name}`); };
+    return command("run_service_tool")
+        ? ` A tool of a service your company connected is not in this list: \`agentradar ${command("list_service_tools")}\` shows them,`
+            + ` and \`agentradar ${command("run_service_tool")} --tool-key <tool> --arguments '<its arguments as JSON>'\` runs one.`
+        : "";
+};
+/** `agentradar <group> --help`: one line per child; anything else that names no command is a usage error that lists the groups. */
+function groupHelp(runnerId, command, tools, help, deps) {
+    const prefix = command ? `${command} ` : "";
+    const children = new Map();
+    for (const tool of tools) {
+        const path = pathOf(tool);
+        if (!path?.startsWith(prefix))
+            continue;
+        const word = path.slice(prefix.length).split(" ")[0];
+        children.set(word, [...children.get(word) ?? [], tool]);
     }
-    const entry = tools.find((candidate) => candidate.name === tool);
-    if (!entry) {
-        (deps.logError ?? console.error)(unknownTool(runnerId, tool, tools));
-        return 1;
+    if (!children.size) {
+        const groups = [...new Set(tools.map(pathOf).filter((path) => path).map((path) => path.split(" ")[0]))].sort();
+        (deps.logError ?? console.error)(`${command} is not a command. Groups: ${groups.join(" ")}. \`agentradar <group> --help\` lists its commands.${serviceTools(runnerId, tools)}`);
+        return EXIT.usage;
     }
-    const required = entry.inputSchema?.required ?? [];
-    const names = Object.keys(entry.inputSchema?.properties ?? {}).map((name) => `--${name}${required.includes(name) ? " (required)" : ""}`);
-    log(`${tool}: ${entry.description ?? ""}\nArguments: ${names.join(" ") || "none"}`);
-    return 0;
+    const lines = [...children].sort(([a], [b]) => a.localeCompare(b)).map(([word, leaves]) => `  ${word.padEnd(16)} ${leaves.length === 1 && pathOf(leaves[0]) === `${prefix}${word}` ? firstSentence(leaves[0].description) : `(${leaves.length} commands)`}`);
+    (help ? deps.log ?? console.log : deps.logError ?? console.error)([
+        `agentradar ${prefix}<${command ? "command" : "group"}>`, ...lines,
+        `Add --help to any of them for its flags.${command ? "" : serviceTools(runnerId, tools)}`,
+    ].join("\n"));
+    return help ? EXIT.ok : EXIT.usage;
+}
+/** `agentradar <path> --help`: the description, usage, required and optional flags, all generated from the inputSchema. */
+function leafHelp(tool) {
+    const properties = tool.inputSchema?.properties ?? {};
+    const required = tool.inputSchema?.required ?? [];
+    const typeOf = (schema) => schema.enum ? schema.enum.join("|")
+        : [schema.type].flat()[0] === "array" ? `${typeOf(schema.items ?? {})} (a list: repeat the flag, or pass one JSON array)` : `<${[schema.type].flat()[0] ?? "value"}>`;
+    const flag = (name) => `  --${kebab(name)} ${typeOf(properties[name])}${properties[name].description ? `  ${firstSentence(properties[name].description)}` : ""}`;
+    const optional = Object.keys(properties).filter((name) => !required.includes(name));
+    const path = pathOf(tool) ?? `call <runner-id> ${tool.name}`;
+    return [
+        tool.description ?? "", "",
+        "USAGE", `  agentradar ${path}${required.map((name) => ` --${kebab(name)} ${typeOf(properties[name] ?? {})}`).join("")}${optional.length ? " [flags]" : ""}`,
+        ...(required.length ? ["REQUIRED", ...required.filter((name) => name in properties).map(flag)] : []),
+        "FLAGS", ...optional.map(flag), "  --dry-run  print the exact call and send nothing   --json  raw JSON   --runner <id>  the runner (default $AR_CLI_RUNNER_ID)",
+        EXIT_CODES,
+    ].join("\n");
 }
 /**
  * `--text "hi" --thread-id X` as the tool's own arguments, typed by the inputSchema the server
  * advertises, so an agent never types JSON (braces and quotes) into a shell command.
  */
-async function flagArguments(runnerId, tool, flags, deps) {
+async function flagArguments(entry, flags, deps) {
     const logError = deps.logError ?? console.error;
-    const tools = await listedTools(runnerId, deps);
-    if (!tools)
-        return null;
-    const entry = tools.find((candidate) => candidate.name === tool);
-    if (!entry) {
-        logError(unknownTool(runnerId, tool, tools));
-        return null;
-    }
     const schema = entry.inputSchema?.properties ?? {};
     const out = {};
     const camel = (flag) => flag.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
@@ -190,20 +205,54 @@ async function flagArguments(runnerId, tool, flags, deps) {
         // --text is what agents reach for on append_task_log, whose argument is --entry.
         const key = flag in schema ? flag : flag === "text" && "entry" in schema ? "entry" : camel(flag);
         if (!(key in schema)) {
-            logError(`${tool} has no argument --${flag}. Its arguments: ${Object.keys(schema).map((name) => `--${name}`).join(" ") || "none"}`);
+            logError(`${pathOf(entry) ?? entry.name} has no flag --${flag}. Its flags: ${Object.keys(schema).map((name) => `--${kebab(name)}`).join(" ") || "none"}`);
             return null;
         }
         const type = [schema[key].type].flat()[0];
-        const typed = coerce(type === "array" ? [schema[key].items?.type].flat()[0] : type, value);
+        if (type === "array") {
+            // A list is one JSON array or a repeated flag (#1752): --message-ids a --message-ids b, or --tools '[{...},{...}]'.
+            const itemType = [schema[key].items?.type].flat()[0];
+            const items = parseList(value, itemType);
+            if (!items) {
+                logError(listFlagError(flag, itemType, schema[key]));
+                return null;
+            }
+            out[key] = [...(out[key] ?? []), ...items];
+            continue;
+        }
+        const typed = coerce(type, value);
         if (typed === undefined) {
-            logError(`--${flag} must be ${type === "array" ? "a list of " + schema[key].items?.type : "a " + type}`);
+            logError(`--${flag} must be a ${type}`);
             return null;
         }
-        // A repeated flag builds a list: --message-ids a --message-ids b.
-        out[key] = type === "array" ? [...(out[key] ?? []), typed] : typed;
+        out[key] = typed;
     }
     return out;
 }
+/** One flag's items: a JSON array spreads (a nested-list schema keeps it whole), anything else is a single item; null when an item does not fit the type. */
+function parseList(value, itemType) {
+    let parsed;
+    if (itemType !== "array" && value.trimStart().startsWith("["))
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch { /* a single item that starts with "[" */ }
+    const items = Array.isArray(parsed) ? parsed : [coerce(itemType, value)];
+    const fits = (item) => itemType === "object" ? !!item && typeof item === "object" && !Array.isArray(item)
+        : itemType === "array" ? Array.isArray(item)
+            : itemType === "integer" ? Number.isInteger(item)
+                : itemType === "number" || itemType === "string" || itemType === "boolean" ? typeof item === itemType
+                    : item !== undefined;
+    return items.every(fits) ? items : null;
+}
+/** What an agent reads when a list argument is mistyped: both accepted forms, with an example built from the tool's own item fields. */
+function listFlagError(flag, itemType, schema) {
+    const fields = Object.keys(schema.items?.properties ?? {});
+    const object = `{${(fields.length ? fields : ["key"]).map((name) => `"${name}":"..."`).join(",")}}`;
+    const [one, two] = itemType === "object" ? [object, object] : itemType === "number" || itemType === "integer" ? ["1", "2"] : itemType === "boolean" ? ["true", "false"] : ['"a"', '"b"'];
+    const bare = (item) => (itemType === "object" ? `'${item}'` : item.replaceAll('"', ""));
+    return `--${flag} takes a list of ${itemType ?? "values"}: either one JSON array, --${flag} '[${one},${two}]', or the flag repeated, --${flag} ${bare(one)} --${flag} ${bare(two)}.`;
+}
 /**
  * `agentradar run` is always-allowed, so a file flag must not read and upload any file the agent names:
  * only a regular file inside the working folder (after symlinks), and at most 256 KB — and never one in
@@ -238,22 +287,7 @@ function coerce(type, value) {
         return type === undefined ? value : undefined;
     }
 }
-// The parity test (server human-metrics-ext-realpg) fails when report_metric gains an argument this line does not name.
-export const METRIC_REPORT_USAGE = "Usage: agentradar metric report <runner-id> --metric-id <id> --value <n> --period-start <iso> --period-end <iso> [--evidence <text>] [--from-event-id <id>] [--comment <text>]";
-// The parity test (server r013-propose-human-realpg) fails when propose_human gains an argument this line does not name.
-export const PROPOSE_HUMAN_USAGE = "Usage: agentradar propose-human <runner-id> --name <name> --email <email> --role-id <id>";
-// The parity test (server listing-description-realpg) fails when set_listing_description gains an argument this line does not name.
-export const LISTING_DESCRIBE_USAGE = "Usage: agentradar listing describe <runner-id> --capabilities <text>";
-// The parity test (server inbox-search-realpg) fails when inbox_search gains an argument this line does not name.
-export const INBOX_SEARCH_USAGE = "Usage: agentradar inbox search <runner-id> [--query <text>] [--channel <c>] [--thread-id <id>] [--sender <s>] [--from <iso>] [--to <iso>] [--has-attachment true] [--unread true] [--unacked true] [--limit <n>] [--before <cursor>] [--after <cursor>] [--around <message-id>] [--json]";
-/**
- * INBOX-SEARCH (Vadym 9974) — `agentradar inbox search <runner-id> [--query <text>] [--<filter> <value> ...] [--json]`:
- * the MCP `inbox_search` on the same endpoint with the same key. One block per message, or the tool's JSON with --json.
- */
-export async function inboxSearchOverCli(runnerId, flags, json, deps = {}) {
-    const log = deps.log ?? console.log;
-    return await callToolOverCli(runnerId, "inbox_search", undefined, json ? deps : { ...deps, log: (text) => log(inboxLines(text)) }, flags);
-}
+/** INBOX-SEARCH (Vadym 9974): one block per message; `--json` keeps the tool's own JSON. */
 function inboxLines(text) {
     let body;
     try {
@@ -270,32 +304,13 @@ function inboxLines(text) {
     const pages = [body.older && `Older: --before ${body.older}`, body.newer && `Newer: --after ${body.newer}`].filter(Boolean);
     return [...results.map((r) => `${r.at}  ${r.channel}  ${r.sender?.name ?? r.from ?? ""}\n  thread ${r.threadId}  message ${r.messageId}\n  ${r.snippet}`), ...pages].join("\n");
 }
-/**
- * Vadym 10719 — `agentradar permissions mine|roles|set|request|grant-tool <runner-id> [--<argument> <value> ...]`: the MCP permission
- * tools on the same endpoint with the same key. The parity test (server permission-tools-realpg) fails when one drifts.
- */
-export const PERMISSION_VERB_TOOLS = {
-    mine: "my_permissions",
-    roles: "read_role_permissions",
-    set: "set_role_permission",
-    request: "request_permission",
-    "grant-tool": "propose_tool_assignment",
-};
-/**
- * Ruling 49 — `agentradar task create|repeat|make-recurring <runner-id> --args '<json>'`: the agent's own
- * `create_task`, `create_recurring_task` or `make_task_recurring` (Vadym 10317), on the same AWP endpoint
- * with the same key, so who it may assign to is the server's decision exactly as it is over MCP.
- */
-export const TASK_VERB_TOOLS = {
-    create: "create_task",
-    repeat: "create_recurring_task",
-    "make-recurring": "make_task_recurring",
-};
-export async function createTaskOverCli(runnerId, verb, argumentsJson, deps = {}) {
-    const parameters = parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
-    if (!parameters)
-        return 1;
-    return await callAwpTool(runnerId, TASK_VERB_TOOLS[verb], parameters, deps);
+/** PER-TOOL-MODES (Vadym 12919): `--tool X=ask --tool Y=blocked` is `tools: [{toolKey: X, mode: ask}, ...]`; a bare `--tool X` takes `--mode`. */
+export function namedToolFlags(flags) {
+    const tools = flags.filter(([flag]) => flag === "tool").map(([, value]) => {
+        const at = value.lastIndexOf("=");
+        return at < 0 ? { toolKey: value } : { toolKey: value.slice(0, at), mode: value.slice(at + 1) };
+    });
+    return { tools, flags: flags.filter(([flag]) => flag !== "tool") };
 }
 function parseArgumentsObject(argumentsJson, logError) {
     let parsed;
@@ -312,14 +327,6 @@ function parseArgumentsObject(argumentsJson, logError) {
     }
     return parsed;
 }
-/**
- * R251 — `agentradar tool list <runner-id>`: the server's own `list_service_tools`, printed as it
- * answered. The listing is the policy's preview for this agent, so the CLI computes nothing — a second
- * copy of the decision here could only drift from the one the MCP tool and every real call make.
- */
-export async function listServiceToolsOverCli(runnerId, deps = {}) {
-    return await callAwpTool(runnerId, "list_service_tools", {}, deps);
-}
 /** One `tools/call` on the runner's AWP MCP endpoint with the runner's own key; the answer is printed verbatim. */
 export async function callAwpTool(runnerId, name, toolArguments, deps) {
     const log = deps.log ?? console.log;
@@ -335,38 +342,24 @@ export async function callAwpTool(runnerId, name, toolArguments, deps) {
         logError(said);
         return 1;
     }
-    log(said);
-    await cliVersionNotice(said, logError);
+    log(withCliUpdate(said));
     return 0;
 }
-/**
- * Vadym 9970: the server names the CLI it expects (`cli: { latest, min }`, on a successful get_my_context).
- * When this one is behind, the agent reads it in its own output (stderr, so --json stdout stays parseable).
- */
-async function cliVersionNotice(said, logError) {
-    let cli;
-    try {
-        cli = JSON.parse(said).cli;
-    }
-    catch {
-        return;
-    }
-    if (!cli || typeof cli.latest !== "string")
-        return;
-    const mine = await runningVersion().catch(() => null);
-    if (!mine || !newer(cli.latest, mine))
-        return;
-    logError(typeof cli.min === "string" && newer(cli.min, mine)
-        ? `agentradar ${mine} is below the minimum ${cli.min}: upgrade required. Run \`agentradar upgrade\`.`
-        : `agentradar ${cli.latest} is available (you run ${mine}). Run \`agentradar upgrade\`.`);
-}
 const RUNNER_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 /** One JSON-RPC request on the runner's AWP MCP endpoint with the runner's own key; null after logging why it failed. */
 export async function awpRequest(runnerId, method, params, deps) {
     const target = await awpEndpoint(runnerId, deps);
     if (!target)
         return null;
-    return postAwp(target.url, target.bearer, method, params, deps);
+    const result = await postAwp(target.url, target.bearer, method, params, deps);
+    // A hosted workspace stops after 15 idle minutes; the bridge reads this file's mtime, so a background job that
+    // keeps calling AgentRadar keeps it awake. Only a call that succeeded counts: a loop of failing calls must not hold
+    // the box up. Platform hooks (AR_HOOK) and skill sync are not the agent's work.
+    if (result !== null && target.hosted && (deps.env ?? process.env).AR_HOOK !== "1" && deps.surface !== "skill-sync") {
+        const run = join(deps.home ?? homedir(), ".agentradar", "run");
+        await mkdir(run, { recursive: true }).then(() => writeFile(join(run, "activity"), "")).catch(() => { });
+    }
+    return result;
 }
 /** The runner's MCP endpoint and bearer: its runner file, else a hosted run's own environment. */
 export async function awpEndpoint(runnerId, deps) {
@@ -400,14 +393,14 @@ export async function awpEndpoint(runnerId, deps) {
         }
         url = `${origin}/api/mcp`;
     }
-    return { url, bearer };
+    return { url, bearer, hosted: contents === null };
 }
 async function postAwp(url, bearer, method, params, deps) {
     const logError = deps.logError ?? console.error;
     const response = await (deps.fetch ?? fetch)(url, {
         method: "POST",
         headers: {
-            ...(await cliHeader()),
+            ...(await cliHeader(deps.surface)),
             authorization: `Bearer ${bearer}`,
             "content-type": "application/json",
             // Both, because the endpoint answers JSON only when the client says it takes JSON.
@@ -420,10 +413,12 @@ async function postAwp(url, bearer, method, params, deps) {
             params,
         }),
     });
+    await noteCliUpdate(response.headers, logError);
     if (!response.ok) {
         // 426: this CLI is below the server's minimum; its sentence says how to upgrade.
         const said = response.status === 426 ? await response.json().then((body) => body.error?.message).catch(() => null) : null;
-        logError(said ?? `AgentRadar refused the tool call (${response.status}).`);
+        // 401: the server says only "unauthorized" for every cause, so a revoked key and an ended hire read the same here.
+        logError(said ?? (response.status === 401 ? UNAUTHORIZED : `AgentRadar refused the tool call (${response.status}).`));
         return null;
     }
     const body = await response.json();

package/dist/update.js

@@ -16,8 +16,33 @@ export const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const serviceCopy = (root) => basename(dirname(root)) === "cli" && basename(dirname(dirname(root))) === ".agentradar";
 /** The version this process runs, whatever `current` points at now. */
 export const runningVersion = async () => JSON.parse(await readFile(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
-/** Sent as `x-agentradar-cli` on every MCP call, so the server can refuse a CLI below its minimum (self-release card 2). */
-export const cliHeader = async () => ({ "x-agentradar-cli": await runningVersion().catch(() => "") });
+/**
+ * Sent as `x-agentradar-cli` on every MCP call, so the server can refuse a CLI below its minimum (self-release card 2),
+ * and as `x-agentradar-surface` so it can count which client a call came from (MCPR-1).
+ */
+export const cliHeader = async (surface = "cli") => ({ "x-agentradar-cli": await runningVersion().catch(() => ""), "x-agentradar-surface": surface });
+let behind = null;
+export const forgetCliUpdate = () => { behind = null; };
+export async function noteCliUpdate(headers, logError = console.error) {
+    const latest = headers?.get("x-agentradar-cli-latest");
+    const current = latest && !behind ? await runningVersion().catch(() => "") : "";
+    if (!latest || !current || !newer(latest, current) || behind)
+        return;
+    behind = { current, latest, command: "agentradar upgrade" };
+    logError(`agentradar ${latest} is available (you run ${current}). Run \`agentradar upgrade\`.`);
+}
+/** A JSON-object output with `cliUpdate` added when this CLI is behind; anything else, or a current CLI, unchanged. */
+export function withCliUpdate(text) {
+    if (!behind)
+        return text;
+    try {
+        const body = JSON.parse(text);
+        return body && typeof body === "object" && !Array.isArray(body) ? JSON.stringify({ ...body, cliUpdate: behind }, null, text.includes("\n") ? 2 : 0) : text;
+    }
+    catch {
+        return text;
+    }
+}
 /** The version on disk: for a service's copy, the one `current` points at, which another runner may have moved. */
 export const installedVersion = async (root = PACKAGE_ROOT) => JSON.parse(await readFile(join(serviceCopy(root) ? join(dirname(root), "current") : root, "package.json"), "utf8")).version;
 export const newer = (a, b) => {