agentradar-cli 0.2.6 → 0.2.8

package/dist/index.js

@@ -15,7 +15,7 @@ export const runArgs = (raw) => raw[0] !== "run" ? raw
 async function main() {
     const args = runArgs(process.argv.slice(2));
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
-        console.log("Usage: agentradar run <enrolment-url> [--name <n>] [--model <m>] | agentradar run <runner-id> <tool> [--<argument> <value> | --<argument>-file <path> ...] | agentradar setup [--trust] [--harness claude|codex] | agentradar join <enrolment-url> [--name <n>] [--model <m>] [--trust] | agentradar leave <runner-id> | agentradar channel <runner-id> | agentradar selftest <runner-id> [--status|--restart] | agentradar runner start <runner-id> | agentradar tool list <runner-id> | agentradar tool run <runner-id> <tool-key> [--args '<json>'] | agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>'] | agentradar task create|repeat <runner-id> --args '<json>' | agentradar skill install | agentradar sync [dir] | agentradar sync install [dir] [--interval <s>]");
+        console.log("Usage: agentradar run <join-link> [--name <n>] [--model <m>] | agentradar run <runner-id> <tool> [--<argument> <value> | --<argument>-file <path> ...] | agentradar setup [--trust] [--harness claude|codex] | agentradar join <join-link> [--name <n>] [--model <m>] [--trust] | agentradar leave <runner-id> | agentradar channel <runner-id> | agentradar selftest <runner-id> [--status|--restart] | agentradar runner start <runner-id> | agentradar tool list <runner-id> | agentradar tool run <runner-id> <tool-key> [--args '<json>'] | agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>'] | agentradar task create|repeat <runner-id> --args '<json>' | agentradar skill install | agentradar sync [dir] | agentradar sync install [dir] [--interval <s>]");
         return;
     }
     if (args[0] === "leave" && args.length === 2) {
@@ -65,7 +65,7 @@ async function main() {
                 urls.push(args[i]);
         }
         if (urls.length !== 1 || [urls[0], ...Object.values(named)].some((value) => value.startsWith("-"))) {
-            console.error("Usage: agentradar join <enrolment-url> [--name <your name>] [--model <your model id>] [--trust]");
+            console.error("Usage: agentradar join <join-link> [--name <your name>] [--model <your model id>] [--trust]");
             process.exitCode = 1;
             return;
         }
@@ -89,7 +89,7 @@ async function main() {
         const call = args[0] === "call";
         const parsed = parseCallArgs(args.slice(call ? 1 : 2));
         if (!parsed || (!call && parsed.flags.length)) {
-            console.error(call ? "Usage: agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>']" : "Usage: agentradar tool run <runner-id> <tool-key> [--args '<json>']");
+            console.error(call ? "Usage: agentradar run <runner-id> <tool> [--<argument> <value> ...] [--args '<json>'] | agentradar run <runner-id> [<tool>] --help" : "Usage: agentradar tool run <runner-id> <tool-key> [--args '<json>']");
             process.exitCode = 1;
             return;
         }
@@ -129,7 +129,7 @@ async function main() {
         return;
     }
     const help = args.length === 1 && (args[0] === "--help" || args[0] === "-h");
-    (help ? console.log : console.error)("Usage: agentradar run <enrolment-url> [--name <n>] [--model <m>] | agentradar run <runner-id> <tool> [--<argument> <value> | --<argument>-file <path> ...] | agentradar setup [--trust] | agentradar join <enrolment-url> [--name <n>] [--model <m>] [--trust] | agentradar leave <runner-id> | agentradar channel <runner-id> | agentradar selftest <runner-id> [--status|--restart] | agentradar runner start <runner-id> | agentradar tool list <runner-id> | agentradar tool run <runner-id> <tool-key> [--args '<json>'] | agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>'] | agentradar task create|repeat <runner-id> --args '<json>' | agentradar skill install | agentradar sync [dir] | agentradar sync install [dir] [--interval <s>]");
+    (help ? console.log : console.error)("Usage: agentradar run <join-link> [--name <n>] [--model <m>] | agentradar run <runner-id> <tool> [--<argument> <value> | --<argument>-file <path> ...] | agentradar setup [--trust] | agentradar join <join-link> [--name <n>] [--model <m>] [--trust] | agentradar leave <runner-id> | agentradar channel <runner-id> | agentradar selftest <runner-id> [--status|--restart] | agentradar runner start <runner-id> | agentradar tool list <runner-id> | agentradar tool run <runner-id> <tool-key> [--args '<json>'] | agentradar call <runner-id> <tool> [--<argument> <value> ...] [--args '<json>'] | agentradar task create|repeat <runner-id> --args '<json>' | agentradar skill install | agentradar sync [dir] | agentradar sync install [dir] [--interval <s>]");
     if (!help)
         process.exitCode = 1;
 }

package/dist/setup.js

@@ -7,7 +7,6 @@ import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import * as tls from "node:tls";
 import { promisify } from "node:util";
-import { syncJoinedSkills } from "./skill-install.js";
 const DEFAULT_API_URL = "https://vendor.agentradar.com/api";
 /** The service's CLI build (the CLI itself and the agent-guard plugin): `installCli` keeps it current, never the npx cache. */
 const cliDist = (home) => join(home, ".agentradar", "cli", "current", "dist");
@@ -556,7 +555,7 @@ async function installAgentService(runnerId, home, env) {
     });
 }
 /**
- * Mode A — the organisation's own agent, on its own compute, joining through an enrolment link.
+ * Mode A — the organisation's own agent, on its own compute, joining through a join link.
  *
  * accept → wait for a human to approve → claim the key once → install the runner and start it as a service
  * (LaunchAgent / systemd user unit) that owns the agent's persistent session. The one-time claim secret is
@@ -605,10 +604,6 @@ export async function joinOrganisation(enrolmentUrl, deps = {}) {
         const runnerEnv = await installRunner(home, projectPath, { status: "approved", agentId, runnerId, installation, harness }, { sessionId, env });
         await saved?.();
         log(`Runner installed → ${runnerEnv}`);
-        // Best effort: a failed first sync never stops the join; the service's feeder syncs them again.
-        await syncJoinedSkills(runnerId, { home, fetch: fetchImpl, log }).catch((error) => {
-            log(`Your AgentRadar skills are not installed yet (${String(error?.message ?? error).split("\n")[0]}); the runner installs them once it is running.`);
-        });
         try {
             await (deps.installService ?? ((id) => installAgentService(id, home, env)))(runnerId);
         }
@@ -625,11 +620,11 @@ export async function joinOrganisation(enrolmentUrl, deps = {}) {
         link = new URL(enrolmentUrl);
     }
     catch {
-        throw new Error("Pass the enrolment link your organisation gave you, e.g. https://…/invite/<token>");
+        throw new Error("Pass the join link your organisation gave you, e.g. https://…/invite/<token>");
     }
     const token = /^\/(?:api\/invites|invite)\/([^/]+?)(?:\.md)?(?:\/|$)/.exec(link.pathname)?.[1];
     if (!token || !trustedMcpEndpoint(link.origin)) {
-        throw new Error("That is not an AgentRadar enrolment link (expected https://…/invite/<token>)");
+        throw new Error("That is not an AgentRadar join link (expected https://…/invite/<token>)");
     }
     const api = (path) => new URL(`/api/${path}`, link.origin);
     const mcpEndpoint = env.AWP_MCP_URL || api("mcp").toString();
@@ -645,12 +640,12 @@ export async function joinOrganisation(enrolmentUrl, deps = {}) {
             throw error;
     }
     if (state?.agentId) {
-        log("This enrolment link is already joined on this machine.");
+        log("This machine already joined with this join link.");
         const saved = await readFile(join(home, ".agentradar", "agents", `join-${state.requestId}.env`), "utf8").catch(() => "");
         const { envValue } = await import("./tool-run.js");
         const bearer = envValue(saved, "AWP_BEARER");
         if (!bearer)
-            throw new Error("This machine left that organisation (agentradar leave). A key is issued once; ask your organisation for a new enrolment link.");
+            throw new Error("This machine left that organisation (agentradar leave). A key is issued once; ask your organisation for a new join link.");
         return startJoined(state.requestId, state.agentId, { mcpEndpoint: envValue(saved, "AWP_MCP_URL") ?? mcpEndpoint, bearer });
     }
     if (!state) {
@@ -712,10 +707,10 @@ export async function joinOrganisation(enrolmentUrl, deps = {}) {
             continue;
         }
         if (response.status === 409 && said.includes("rejected")) {
-            throw new Error("Your organisation declined this join request. Ask it for a new enrolment link.");
+            throw new Error("Your organisation declined this join request. Ask it for a new join link.");
         }
         if (response.status === 409 && /already (?:used|claimed)/.test(said)) {
-            throw new Error("This enrolment link's key was already claimed. A key is issued once and cannot be claimed again; ask your organisation for a new enrolment link.");
+            throw new Error("This join link's key was already claimed. A key is issued once and cannot be claimed again; ask your organisation for a new join link.");
         }
         throw new Error(said);
     }

package/dist/skill-install.js

@@ -1,9 +1,6 @@
-import { chmod, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, normalize, sep } from "node:path";
-import { awpRequest, envValue } from "./tool-run.js";
-const MANAGED_MARK = ".agentradar-managed";
-const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,99}$/;
+import { join } from "node:path";
 async function ensureDirectory(path) {
     try {
         const info = await lstat(path);
@@ -41,98 +38,7 @@ export async function installVendorSkill(deps = {}) {
         });
     }
     // The runner keeps this skill current from AgentRadar; the marker says the folder is AgentRadar's to replace.
-    await writeFile(join(skillDir, MANAGED_MARK), "Written by AgentRadar; replaced on every sync.\n");
+    await writeFile(join(skillDir, ".agentradar-managed"), "Written by AgentRadar; replaced on every sync.\n");
     (deps.log ?? console.log)("AgentRadar vendor skill installed for this project.");
 }
-const isManaged = async (dir) => (await lstat(dir).then((info) => info.isDirectory(), () => false)) && (await lstat(join(dir, MANAGED_MARK)).then(() => true, () => false));
-/**
- * The feeder's `writeManagedSkills` (templates/vendor-runner/feeder.mjs), for the CLI: the server's answer is
- * untrusted input to this box, so names and paths are checked, each skill is staged then renamed into place,
- * a folder without the marker (the vendor's own) is never touched, and a managed skill no longer listed goes.
- */
-const sameSkill = async (dir, files) => {
-    try {
-        const have = [];
-        for (const p of await readdir(dir, { recursive: true }))
-            if (p !== MANAGED_MARK && (await stat(join(dir, p))).isFile())
-                have.push(p);
-        for (const f of files)
-            if (await readFile(join(dir, f.path), "utf8") !== f.content)
-                return false;
-        return have.length === files.length;
-    }
-    catch {
-        return false;
-    }
-};
-export async function writeManagedSkills(skillsDir, skills) {
-    await mkdir(skillsDir, { recursive: true });
-    const written = new Set();
-    for (const skill of skills) {
-        const name = String(skill?.name ?? "");
-        const target = join(skillsDir, name);
-        if (!SKILL_NAME.test(name))
-            continue;
-        if (await lstat(target).then(() => true, () => false) && !(await isManaged(target)))
-            continue;
-        const files = (Array.isArray(skill.files) ? skill.files : []);
-        if (files.some((f) => typeof f?.path !== "string" || typeof f?.content !== "string" || isAbsolute(f.path)
-            || normalize(f.path).split(sep).includes("..") || [".", MANAGED_MARK].includes(normalize(f.path))))
-            continue;
-        // An unchanged skill is not rewritten: the agent's CLI may be reading it.
-        if (await sameSkill(target, files)) {
-            written.add(name);
-            continue;
-        }
-        const staging = join(skillsDir, `.${name}.sync-${process.pid}`);
-        const old = join(skillsDir, `.${name}.old-${process.pid}`);
-        try {
-            await rm(staging, { recursive: true, force: true });
-            for (const f of files) {
-                await mkdir(dirname(join(staging, f.path)), { recursive: true });
-                await writeFile(join(staging, f.path), f.content);
-            }
-            await writeFile(join(staging, MANAGED_MARK), "Written by the AgentRadar runner; replaced on every sync.\n");
-            // Rename aside, then into place: the skill is missing for two renames, not for a recursive delete.
-            await rm(old, { recursive: true, force: true });
-            await rename(target, old).catch((err) => { if (err?.code !== "ENOENT")
-                throw err; });
-            await rename(staging, target);
-            await rm(old, { recursive: true, force: true });
-            written.add(name);
-        }
-        catch {
-            await rm(staging, { recursive: true, force: true });
-            if (!(await lstat(target).then(() => true, () => false)))
-                await rename(old, target).catch(() => { });
-            if (await isManaged(target))
-                written.add(name);
-        }
-    }
-    for (const entry of await readdir(skillsDir)) {
-        if (!written.has(entry) && await isManaged(join(skillsDir, entry)))
-            await rm(join(skillsDir, entry), { recursive: true, force: true });
-    }
-    return [...written];
-}
-/**
- * R650 — a joined agent's AgentRadar skills (`my_skills`: the bundled set plus the ones linked to it), written
- * at join into the directory its CLI reads, the feeder's `skillsDirFor`: Claude `$AR_BASE/.claude/skills`,
- * Codex `$CODEX_HOME/skills`. Done here because a session that acts only through `agentradar run` has no
- * feeder; where the service runs, its feeder keeps them current.
- */
-export async function syncJoinedSkills(runnerId, deps) {
-    const env = await readFile(join(deps.home, ".agentradar", "agents", `${runnerId}.env`), "utf8");
-    const root = envValue(env, "AR_AGENT_HARNESS") === "codex" ? envValue(env, "CODEX_HOME") : envValue(env, "AR_BASE");
-    if (!root)
-        return;
-    const skillsDir = envValue(env, "AR_AGENT_HARNESS") === "codex" ? join(root, "skills") : join(root, ".claude", "skills");
-    const body = await awpRequest(runnerId, "tools/call", { name: "my_skills", arguments: {} }, { home: deps.home, fetch: deps.fetch, logError: deps.log });
-    const text = body?.result?.content?.find((c) => c.type === "text")?.text;
-    const answer = (text ? JSON.parse(text) : {});
-    if (!answer.ok || !Array.isArray(answer.skills))
-        throw new Error("AgentRadar did not return your skills");
-    const written = await writeManagedSkills(skillsDir, answer.skills);
-    deps.log(`Installed ${written.length} AgentRadar skill(s) in ${skillsDir}.`);
-}
 //# sourceMappingURL=skill-install.js.map

package/dist/tool-run.js

@@ -21,6 +21,8 @@ export async function runServiceToolOverCli(runnerId, toolKey, argumentsJson, de
 }
 /** `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 = []) {
+    if (flags.some(([flag]) => flag === "help"))
+        return await describeTools(runnerId, tool, deps);
     const parameters = argumentsJson === undefined ? {} : parseArgumentsObject(argumentsJson, deps.logError ?? console.error);
     if (!parameters)
         return 1;
@@ -65,6 +67,10 @@ export function parseCallArgs(rest) {
             positional.push(arg);
             continue;
         }
+        if (arg === "--help") {
+            flags.push(["help", ""]);
+            continue;
+        }
         const value = rest[++i];
         if (value === undefined)
             return null;
@@ -73,7 +79,37 @@ export function parseCallArgs(rest) {
         else
             flags.push([arg.slice(2), value]);
     }
-    return positional.length === 2 ? { runnerId: positional[0], tool: positional[1], json, flags } : null;
+    const help = flags.some(([flag]) => flag === "help");
+    return positional.length === 2 || (help && positional.length === 1)
+        ? { runnerId: positional[0], tool: positional[1] ?? "", json, flags } : null;
+}
+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;
+    }
+    const entry = tools.find((candidate) => candidate.name === tool);
+    if (!entry) {
+        (deps.logError ?? console.error)(unknownTool(runnerId, tool, tools));
+        return 1;
+    }
+    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;
 }
 /**
  * `--text "hi" --conversation-id X` as the tool's own arguments, typed by the inputSchema the server
@@ -81,10 +117,15 @@ export function parseCallArgs(rest) {
  */
 async function flagArguments(runnerId, tool, flags, deps) {
     const logError = deps.logError ?? console.error;
-    const listed = await awpRequest(runnerId, "tools/list", {}, deps);
-    if (!listed)
+    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 = listed.result?.tools?.find((entry) => entry.name === tool)?.inputSchema?.properties ?? {};
+    }
+    const schema = entry.inputSchema?.properties ?? {};
     const out = {};
     const camel = (flag) => flag.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
     for (let [flag, value] of flags) {
@@ -203,7 +244,7 @@ export async function callAwpTool(runnerId, name, toolArguments, deps) {
 }
 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) {
+async function awpRequest(runnerId, method, params, deps) {
     const logError = deps.logError ?? console.error;
     if (!RUNNER_ID.test(runnerId)) {
         logError("Invalid runner ID");

package/dist/vendor-runner/feeder.mjs

@@ -663,14 +663,6 @@ const isManaged = (dir) => {
   const st = fs.lstatSync(dir, { throwIfNoEntry: false });
   return Boolean(st?.isDirectory() && fs.existsSync(join(dir, MANAGED_MARK)));
 };
-const sameSkill = (dir, files) => {
-  try {
-    const have = fs.readdirSync(dir, { recursive: true }).filter((p) => p !== MANAGED_MARK && fs.statSync(join(dir, p)).isFile());
-    return have.length === files.length && files.every((f) => fs.readFileSync(join(dir, f.path), "utf8") === f.content);
-  } catch {
-    return false;
-  }
-};
 
 export function writeManagedSkills(skillsDir, skills) {
   fs.mkdirSync(skillsDir, { recursive: true });
@@ -687,11 +679,7 @@ export function writeManagedSkills(skillsDir, skills) {
     const bad = files.find((f) => typeof f?.path !== "string" || typeof f?.content !== "string" || isAbsolute(f.path)
       || normalize(f.path).split(sep).includes("..") || [".", MANAGED_MARK].includes(normalize(f.path)));
     if (bad) { console.warn(`[feeder] skill sync: ${name} has an unsafe file path, skipped`); continue; }
-    // An unchanged skill is not rewritten: the agent's CLI may be reading it (Codex skipped a SKILL.md that a
-    // periodic resync had just removed).
-    if (sameSkill(target, files)) { written.add(name); continue; }
     const staging = join(skillsDir, `.${name}.sync-${process.pid}`);
-    const old = join(skillsDir, `.${name}.old-${process.pid}`);
     try {
       fs.rmSync(staging, { recursive: true, force: true });
       for (const f of files) {
@@ -699,16 +687,12 @@ export function writeManagedSkills(skillsDir, skills) {
         fs.writeFileSync(join(staging, f.path), f.content);
       }
       fs.writeFileSync(join(staging, MANAGED_MARK), "Written by the AgentRadar runner; replaced on every sync.\n");
-      // Rename aside, then into place: the skill is missing for two renames, not for a recursive delete.
-      fs.rmSync(old, { recursive: true, force: true });
-      if (fs.existsSync(target)) fs.renameSync(target, old);
+      fs.rmSync(target, { recursive: true, force: true });
       fs.renameSync(staging, target);
-      fs.rmSync(old, { recursive: true, force: true });
       written.add(name);
     } catch (err) {
       // One skill that cannot be written keeps its previous copy and does not stop the rest of the sync.
       fs.rmSync(staging, { recursive: true, force: true });
-      if (!fs.existsSync(target) && fs.existsSync(old)) fs.renameSync(old, target);
       if (isManaged(target)) written.add(name);
       console.warn(`[feeder] skill sync: ${name} not written: ${err instanceof Error ? err.message : String(err)}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentradar-cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "engines": {
     "node": ">=20"
   },