shadok-ai 0.3.80 → 0.3.82

package/context/scheduler-skill/SKILL.md

@@ -48,17 +48,17 @@ absent, and you find out at 6am rather than now. A name that isn't in the vault
 is skipped just as silently. Your own shell having the key proves nothing about
 the guard's.
 
-`schedule.py env` prints exactly what a guard gets here. Run it before writing a
+`schedule.mjs env` prints exactly what a guard gets here. Run it before writing a
 check that needs a secret.
 
 ## Commands
 
 ```
-python3 scripts/schedule.py add --schedule <spec> --prompt "<text>" [--check "<shell command>"] [--tz <zone>]
-python3 scripts/schedule.py list
-python3 scripts/schedule.py del <id>
-python3 scripts/schedule.py tz [<zone>|-]
-python3 scripts/schedule.py env
+node scripts/schedule.mjs add --schedule <spec> --prompt "<text>" [--check "<shell command>"] [--tz <zone>]
+node scripts/schedule.mjs list
+node scripts/schedule.mjs del <id>
+node scripts/schedule.mjs tz [<zone>|-]
+node scripts/schedule.mjs env
 ```
 
 `<spec>`: `every:30m` · `every:2h` · `daily:09:00`.
@@ -69,8 +69,8 @@ A `daily` runs at that wall-clock time **in a timezone**, and the default is
 whatever the SERVER's machine is set to. On a machine running in UTC,
 `daily:09:00` fires at 11:00 for someone in Paris — silently.
 
-- `schedule.py tz` prints the timezone `daily` schedules actually use.
-- `schedule.py tz Europe/Paris` pins it for every `daily` on this instance,
+- `schedule.mjs tz` prints the timezone `daily` schedules actually use.
+- `schedule.mjs tz Europe/Paris` pins it for every `daily` on this instance,
   including the ones already scheduled (they're realigned immediately).
 - `--tz Europe/Paris` on `add` pins one schedule only.
 
@@ -81,7 +81,7 @@ An interval (`every:30m`) is a duration, so it has no timezone.
 ### Example — guarded monitoring (near-zero tokens)
 
 ```
-python3 scripts/schedule.py add \
+node scripts/schedule.mjs add \
   --schedule daily:09:00 \
   --check "python3 $HOME/.claude/skills/google-ads/scripts/check_budget.py" \
   --prompt "Le monitoring a détecté une anomalie budget Google Ads. Rédige une alerte claire et actionnable pour l'équipe."
@@ -90,7 +90,7 @@ python3 scripts/schedule.py add \
 ### Example — plain recurring report (runs every time)
 
 ```
-python3 scripts/schedule.py add --schedule daily:18:00 \
+node scripts/schedule.mjs add --schedule daily:18:00 \
   --prompt "Fais le point de la journée sur le compte et poste un court résumé."
 ```
 

package/context/scheduler-skill/scripts/schedule.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// schedule — manage the CURRENT shadok-ai channel's scheduled prompts (crons)
+// through the local server API. Reads SHADOK_SESSION_ID / SHADOK_PORT /
+// SHADOK_AUTH from the env (injected by shadok-ai into every agent).
+//
+// Node, not Python: shadok-ai IS a Node program, so the runtime is guaranteed
+// present wherever a skill runs. The Dockerfile's python3 is there to build
+// native npm modules, not for skills — trimming it would have broken this
+// silently. See context/scheduler-skill/test/ for the tests that now guard it.
+
+import { pathToFileURL } from "node:url";
+
+const TIMEOUT_MS = 15_000;
+
+/** Exit the way the old `sys.exit("…")` did: message on stderr, code 1. */
+function die(msg) {
+  process.stderr.write(msg + "\n");
+  process.exit(1);
+}
+
+/** A misuse of the command line — argparse's own exit code, kept on purpose. */
+class UsageError extends Error {}
+
+function env() {
+  const port = process.env.SHADOK_PORT;
+  const sid = process.env.SHADOK_SESSION_ID;
+  if (!port || !sid) die("Not inside a shadok-ai channel (SHADOK_PORT / SHADOK_SESSION_ID unset).");
+  return { base: `http://127.0.0.1:${port}`, sid, auth: process.env.SHADOK_AUTH ?? "" };
+}
+
+async function api(ctx, method, path, body) {
+  let res;
+  try {
+    res = await fetch(ctx.base + path, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(ctx.auth ? { Cookie: ctx.auth } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    // The Python version had no branch for this and printed a traceback; a
+    // stopped cockpit is a normal thing to hit, so it gets a sentence.
+    die(`cannot reach the cockpit on ${ctx.base}: ${e.message}`);
+  }
+  const raw = await res.text();
+  if (!res.ok) die(`API error ${res.status}: ${raw.slice(0, 200)}`);
+  return raw ? JSON.parse(raw) : {};
+}
+
+/** `every:30m` · `every:2h` · `every:45` · `daily:09:00` → the API's schedule. */
+export function parseSchedule(spec) {
+  const s = String(spec).trim().toLowerCase();
+  const bad = () => {
+    throw new UsageError(`bad schedule '${spec}' (use every:30m, every:2h, or daily:09:00)`);
+  };
+  if (s.startsWith("every:")) {
+    const m = /^(\d+)([hm]?)$/.exec(s.slice(6));
+    // Python raised on a non-numeric value; JS would quietly make it NaN and
+    // ship `everyMin: null` to the server, so the digits are checked here.
+    if (!m) bad();
+    const n = Number(m[1]);
+    return { kind: "interval", everyMin: m[2] === "h" ? n * 60 : n };
+  }
+  if (s.startsWith("daily:")) {
+    const m = /^(\d{1,2}):(\d{1,2})$/.exec(s.slice(6));
+    if (!m) bad();
+    return { kind: "daily", hour: Number(m[1]), minute: Number(m[2]) };
+  }
+  return bad();
+}
+
+const pad = (n) => String(n).padStart(2, "0");
+
+export function label(s, tz) {
+  if (s.kind === "interval") return `every ${s.everyMin}m`;
+  // The timezone is always shown: a bare "daily 09:00" doesn't say 9am WHERE,
+  // and that is exactly what makes a UTC server look on time.
+  return `daily ${pad(s.hour)}:${pad(s.minute)}` + (tz ? ` (${tz})` : "");
+}
+
+/**
+ * The command line, kept byte-for-byte compatible with the argparse version:
+ * a renamed option would break every cron already registered by an agent.
+ */
+export function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  const known = {
+    add: { flags: ["--schedule", "--prompt", "--check", "--tz"], required: ["--schedule", "--prompt"], pos: 0 },
+    list: { flags: [], required: [], pos: 0 },
+    env: { flags: [], required: [], pos: 0 },
+    tz: { flags: [], required: [], pos: 1 },
+    del: { flags: [], required: [], pos: 1, posRequired: 1 },
+  };
+  if (!cmd || !(cmd in known)) {
+    throw new UsageError(`usage: schedule {add,list,del,tz,env} …\ninvalid choice: '${cmd ?? ""}'`);
+  }
+  const spec = known[cmd];
+  const opts = {};
+  const pos = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a.startsWith("--")) {
+      const [name, inline] = a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : [a, null];
+      if (!spec.flags.includes(name)) throw new UsageError(`schedule ${cmd}: unrecognized argument ${name}`);
+      const v = inline ?? rest[++i];
+      if (v === undefined) throw new UsageError(`schedule ${cmd}: ${name} expects a value`);
+      opts[name.slice(2)] = v;
+    } else pos.push(a);
+  }
+  for (const r of spec.required) {
+    if (opts[r.slice(2)] === undefined) throw new UsageError(`schedule ${cmd}: the following arguments are required: ${r}`);
+  }
+  if (pos.length > spec.pos) throw new UsageError(`schedule ${cmd}: unrecognized arguments: ${pos.slice(spec.pos).join(" ")}`);
+  if (pos.length < (spec.posRequired ?? 0)) throw new UsageError(`schedule ${cmd}: the following arguments are required: id`);
+  return { cmd, opts, pos };
+}
+
+async function cmdAdd(ctx, opts) {
+  const body = { sessionId: ctx.sid, prompt: opts.prompt, schedule: parseSchedule(opts.schedule), enabled: true };
+  if (opts.check) body.check = opts.check;
+  if (opts.tz) body.tz = opts.tz;
+  const r = await api(ctx, "POST", "/crons", body);
+  console.log(
+    `scheduled [${String(r.id).slice(0, 8)}] ${label(r.schedule, r.timezone)}` +
+      (opts.check ? " +guard (0 tokens on quiet runs)" : ""),
+  );
+}
+
+async function cmdList(ctx) {
+  const all = await api(ctx, "GET", "/crons");
+  const mine = all.filter((c) => c.sessionId === ctx.sid);
+  if (!mine.length) return console.log("(no schedule on this channel)");
+  const tzinfo = await api(ctx, "GET", "/timezone");
+  for (const c of mine) {
+    const flags = (c.enabled ? "" : " (paused)") + (c.check ? " +guard" : "");
+    const tz = c.tz || tzinfo.timezone || tzinfo.system;
+    console.log(`[${String(c.id).slice(0, 8)}] ${label(c.schedule, tz)}${flags}\n   ${String(c.prompt).slice(0, 100)}`);
+  }
+}
+
+async function cmdTz(ctx, zone) {
+  const r = zone
+    ? await api(ctx, "POST", "/timezone", { timezone: zone === "-" ? "" : zone })
+    : await api(ctx, "GET", "/timezone");
+  const cur = r.timezone;
+  console.log(
+    `daily schedules run in: ${cur || r.system}` + (cur ? "" : " (machine default — set one to pin it)"),
+  );
+}
+
+async function cmdEnv(ctx) {
+  // A guard runs server-side, not in this agent's process: it gets the secrets
+  // of the CHANNEL's profile, never whatever happens to sit in this shell.
+  // Agents that can't see that list assume the worst and hardcode the value
+  // into the check script — printing it is the fix.
+  const channels = await api(ctx, "GET", "/channels");
+  const ch = channels.find((c) => c.sessionId === ctx.sid);
+  if (!ch) {
+    console.log("this channel is not registered server-side: a guard would run from the");
+    console.log("server's own directory, with no profile secrets at all.");
+    return;
+  }
+  console.log(`guard cwd: ${ch.cwd || "(server default)"}`);
+  const pname = ch.profile;
+  if (!pname) {
+    console.log("guard secrets: NONE — this channel has no profile.");
+    console.log("  Secrets reach a guard only through the channel's profile; attach one");
+    console.log("  (web UI, the agent's profile picker) that lists the names you need.");
+    return;
+  }
+  const profiles = await api(ctx, "GET", "/profiles");
+  const prof = profiles.find((p) => p.name === pname);
+  if (!prof) {
+    // Same end result as "no secrets", but a very different cause: say which
+    // one, or the report reads as a working setup.
+    console.log(`guard secrets: NONE — the channel points at profile '${pname}', which no longer exists.`);
+    return;
+  }
+  const wanted = prof.secrets ?? [];
+  if (!wanted.length) return console.log(`guard secrets: NONE — profile '${pname}' lists no secret.`);
+  const vault = new Set((await api(ctx, "GET", "/secrets")).names ?? []);
+  const present = wanted.filter((n) => vault.has(n));
+  const missing = wanted.filter((n) => !vault.has(n));
+  console.log(`guard secrets (profile '${pname}'): ${present.length ? present.join(", ") : "NONE"}`);
+  // `secretsFor` skips an unknown name without a word, so a typo here looks
+  // exactly like a working guard until the day it runs.
+  if (missing.length) console.log(`  referenced but NOT in the vault, so absent at run time: ${missing.join(", ")}`);
+}
+
+async function cmdDel(ctx, id) {
+  // `list` only prints 8 characters of an id: the server accepts that prefix.
+  // Print WHAT IT deleted — an older version announced "deleted" without ever
+  // deleting anything.
+  const r = await api(ctx, "DELETE", `/crons?id=${encodeURIComponent(id)}`);
+  console.log(`deleted ${String(r.id ?? id).slice(0, 8)}`);
+}
+
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    if (!(e instanceof UsageError)) throw e;
+    process.stderr.write(e.message + "\n");
+    process.exit(2);
+  }
+  const ctx = env();
+  try {
+    if (parsed.cmd === "add") await cmdAdd(ctx, parsed.opts);
+    else if (parsed.cmd === "list") await cmdList(ctx);
+    else if (parsed.cmd === "tz") await cmdTz(ctx, parsed.pos[0]);
+    else if (parsed.cmd === "env") await cmdEnv(ctx);
+    else if (parsed.cmd === "del") await cmdDel(ctx, parsed.pos[0]);
+  } catch (e) {
+    // A bad --schedule is a command-line mistake, not a server error.
+    if (e instanceof UsageError) die(e.message);
+    throw e;
+  }
+}
+
+// Importable by the tests, executable by the agents: only run when invoked
+// directly, or importing this file would exit on a missing SHADOK_PORT.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main(process.argv.slice(2));
+}

package/context/scheduler-skill/test/fake-cockpit.mjs

@@ -0,0 +1,24 @@
+import http from "node:http";
+
+// A stand-in for the shadok-ai server, HTTP only: it records every request and
+// answers from a route table. The shadok-ai-agents skill has its own
+// `mock-server.mjs`, but that one is built around the WebSocket protocol and
+// hardcodes pilotctl's two endpoints — these scripts speak plain HTTP to a
+// different set of routes, so they get a helper of their own rather than a
+// shared one bent to cover both.
+export async function fakeCockpit(routes) {
+  const seen = [];
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => {
+      const [path, query = ""] = req.url.split("?");
+      seen.push({ method: req.method, path, query, body: raw ? JSON.parse(raw) : null, cookie: req.headers.cookie });
+      const route = routes[`${req.method} ${path}`] ?? routes[path];
+      res.writeHead(route?.status ?? 200, { "content-type": "application/json" });
+      res.end(JSON.stringify(route?.body ?? route ?? {}));
+    });
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  return { port: server.address().port, seen, close: () => new Promise((r) => server.close(r)) };
+}

package/context/scheduler-skill/test/schedule.test.mjs

@@ -0,0 +1,152 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { fakeCockpit } from "./fake-cockpit.mjs";
+import { parseSchedule, label, parseArgs } from "../scripts/schedule.mjs";
+
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "schedule.mjs");
+
+/** Runs the script with a controlled env, like an agent would. */
+function run(args, env = {}) {
+  return new Promise((resolve) => {
+    execFile(
+      process.execPath,
+      [SCRIPT, ...args],
+      { env: { ...process.env, SHADOK_PORT: "", SHADOK_SESSION_ID: "", SHADOK_AUTH: "", ...env } },
+      (e, out, err) => resolve({ code: e ? (e.code ?? 1) : 0, out, err }),
+    );
+  });
+}
+
+const AGENT = (port) => ({ SHADOK_PORT: String(port), SHADOK_SESSION_ID: "sess-1", SHADOK_AUTH: "sk_auth=tok" });
+
+test("parseSchedule understands minutes, hours and a bare number", () => {
+  assert.deepEqual(parseSchedule("every:30m"), { kind: "interval", everyMin: 30 });
+  assert.deepEqual(parseSchedule("every:2h"), { kind: "interval", everyMin: 120 });
+  assert.deepEqual(parseSchedule("every:45"), { kind: "interval", everyMin: 45 });
+  assert.deepEqual(parseSchedule("EVERY:15M"), { kind: "interval", everyMin: 15 });
+});
+
+test("parseSchedule reads a daily wall-clock time", () => {
+  assert.deepEqual(parseSchedule("daily:09:00"), { kind: "daily", hour: 9, minute: 0 });
+  assert.deepEqual(parseSchedule(" daily:18:30 "), { kind: "daily", hour: 18, minute: 30 });
+});
+
+test("parseSchedule refuses garbage instead of sending NaN to the server", () => {
+  for (const bad of ["every:soon", "daily:nine", "daily:09", "hourly", "", "every:"]) {
+    assert.throws(() => parseSchedule(bad), /bad schedule/, `accepted '${bad}'`);
+  }
+});
+
+test("label always names the timezone of a daily schedule", () => {
+  assert.equal(label({ kind: "daily", hour: 9, minute: 0 }, "Europe/Paris"), "daily 09:00 (Europe/Paris)");
+  assert.equal(label({ kind: "daily", hour: 9, minute: 5 }), "daily 09:05");
+  // An interval is a duration, so it has no timezone to show.
+  assert.equal(label({ kind: "interval", everyMin: 30 }, "Europe/Paris"), "every 30m");
+});
+
+test("parseArgs keeps the documented flags and their requirements", () => {
+  const r = parseArgs(["add", "--schedule", "daily:09:00", "--prompt", "hi", "--check", "sh x.sh", "--tz", "Europe/Paris"]);
+  assert.deepEqual(r.opts, { schedule: "daily:09:00", prompt: "hi", check: "sh x.sh", tz: "Europe/Paris" });
+  assert.throws(() => parseArgs(["add", "--prompt", "hi"]), /--schedule/);
+  assert.throws(() => parseArgs(["add", "--schedule", "every:5m"]), /--prompt/);
+  assert.throws(() => parseArgs(["del"]), /required/);
+  assert.equal(parseArgs(["del", "abc12345"]).pos[0], "abc12345");
+  assert.equal(parseArgs(["tz"]).pos.length, 0);
+  assert.equal(parseArgs(["tz", "Europe/Paris"]).pos[0], "Europe/Paris");
+  assert.throws(() => parseArgs(["nope"]), /invalid choice/);
+});
+
+test("refuses to run outside a shadok-ai channel", async () => {
+  const noPort = await run(["list"], { SHADOK_SESSION_ID: "sess-1" });
+  assert.notEqual(noPort.code, 0);
+  assert.match(noPort.err, /SHADOK_PORT/);
+  const noSid = await run(["list"], { SHADOK_PORT: "1" });
+  assert.notEqual(noSid.code, 0);
+  assert.match(noSid.err, /SHADOK_SESSION_ID/);
+});
+
+test("add posts the channel's own sessionId, the guard and the timezone", async () => {
+  const srv = await fakeCockpit({
+    "POST /crons": { body: { id: "abcdef0123456789", schedule: { kind: "daily", hour: 9, minute: 0 }, timezone: "Europe/Paris" } },
+  });
+  const res = await run(
+    ["add", "--schedule", "daily:09:00", "--prompt", "report", "--check", "sh guard.sh", "--tz", "Europe/Paris"],
+    AGENT(srv.port),
+  );
+  await srv.close();
+  assert.equal(res.code, 0, res.err);
+  assert.deepEqual(srv.seen[0].body, {
+    sessionId: "sess-1",
+    prompt: "report",
+    schedule: { kind: "daily", hour: 9, minute: 0 },
+    enabled: true,
+    check: "sh guard.sh",
+    tz: "Europe/Paris",
+  });
+  assert.equal(srv.seen[0].cookie, "sk_auth=tok");
+  assert.match(res.out, /scheduled \[abcdef01\] daily 09:00 \(Europe\/Paris\) \+guard/);
+});
+
+test("a bad schedule fails before anything is sent", async () => {
+  const srv = await fakeCockpit({});
+  const res = await run(["add", "--schedule", "every:soon", "--prompt", "x"], AGENT(srv.port));
+  await srv.close();
+  assert.notEqual(res.code, 0);
+  assert.match(res.err, /bad schedule/);
+  assert.equal(srv.seen.length, 0);
+});
+
+test("list only shows this channel's schedules, with their timezone", async () => {
+  const srv = await fakeCockpit({
+    "GET /crons": {
+      body: [
+        { id: "aaaaaaaa1111", sessionId: "sess-1", enabled: true, check: "sh x", schedule: { kind: "daily", hour: 9, minute: 0 }, prompt: "mine" },
+        { id: "bbbbbbbb2222", sessionId: "other", enabled: true, schedule: { kind: "interval", everyMin: 5 }, prompt: "someone else's" },
+      ],
+    },
+    "GET /timezone": { body: { timezone: "Europe/Paris", system: "UTC" } },
+  });
+  const res = await run(["list"], AGENT(srv.port));
+  await srv.close();
+  assert.match(res.out, /\[aaaaaaaa\] daily 09:00 \(Europe\/Paris\) \+guard/);
+  assert.doesNotMatch(res.out, /someone else's/);
+});
+
+test("del sends the 8-char prefix the listing prints, url-encoded", async () => {
+  const srv = await fakeCockpit({ "DELETE /crons": { body: { id: "abcdef0123456789" } } });
+  const res = await run(["del", "abcdef01"], AGENT(srv.port));
+  await srv.close();
+  assert.equal(srv.seen[0].query, "id=abcdef01");
+  assert.match(res.out, /deleted abcdef01/);
+});
+
+test("env names the secrets a guard really gets, and the ones it won't", async () => {
+  const srv = await fakeCockpit({
+    "GET /channels": { body: [{ sessionId: "sess-1", cwd: "/w/t", profile: "P" }] },
+    "GET /profiles": { body: [{ name: "P", secrets: ["HAVE", "MISSING"] }] },
+    "GET /secrets": { body: { names: ["HAVE"] } },
+  });
+  const res = await run(["env"], AGENT(srv.port));
+  await srv.close();
+  assert.match(res.out, /guard cwd: \/w\/t/);
+  assert.match(res.out, /guard secrets \(profile 'P'\): HAVE/);
+  assert.match(res.out, /NOT in the vault[^\n]*MISSING/);
+});
+
+test("env says which cause when a channel has no profile", async () => {
+  const srv = await fakeCockpit({ "GET /channels": { body: [{ sessionId: "sess-1", cwd: "/w/t" }] } });
+  const res = await run(["env"], AGENT(srv.port));
+  await srv.close();
+  assert.match(res.out, /guard secrets: NONE — this channel has no profile/);
+});
+
+test("an API error is reported, not swallowed", async () => {
+  const srv = await fakeCockpit({ "POST /crons": { status: 500, body: { error: "boom" } } });
+  const res = await run(["add", "--schedule", "every:5m", "--prompt", "x"], AGENT(srv.port));
+  await srv.close();
+  assert.notEqual(res.code, 0);
+  assert.match(res.err, /API error 500/);
+});

package/context/secrets-skill/SKILL.md

@@ -18,8 +18,8 @@ automatically). If it is missing, say so rather than improvising.
 ## Store it
 
 ```bash
-gh auth token | ~/.claude/skills/shadok-secrets/scripts/secret.py set GITHUB_TOKEN --stdin
-~/.claude/skills/shadok-secrets/scripts/secret.py list
+gh auth token | node ~/.claude/skills/shadok-secrets/scripts/secret.mjs set GITHUB_TOKEN --stdin
+node ~/.claude/skills/shadok-secrets/scripts/secret.mjs list
 ```
 
 ## The rules — these are the point

package/context/secrets-skill/scripts/secret.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// secret — put a credential the agent OBTAINED into shadok-ai's vault, through
+// the local API.
+//
+// The value is read from STDIN, never from argv: `ps` exposes a process's
+// arguments to every user on the machine, so a token passed as a parameter
+// leaks. There is deliberately no way to read a value back out — `list` prints
+// names only, and there is no `get`.
+//
+// Reads SHADOK_PORT / SHADOK_AUTH from the env (injected into every agent).
+//
+// Node, not Python: shadok-ai IS a Node program, so the runtime is guaranteed
+// present wherever a skill runs — the image's python3 exists to build native
+// npm modules, and dropping it would have broken this in silence.
+
+import { pathToFileURL } from "node:url";
+
+const TIMEOUT_MS = 15_000;
+
+/** Exit the way the old `sys.exit("…")` did: message on stderr, code 1. */
+function die(msg) {
+  process.stderr.write(msg + "\n");
+  process.exit(1);
+}
+
+/** A misuse of the command line — argparse's own exit code, kept on purpose. */
+class UsageError extends Error {}
+
+function env() {
+  const port = process.env.SHADOK_PORT;
+  if (!port) die("Not inside a shadok-ai agent (SHADOK_PORT unset).");
+  return { base: `http://127.0.0.1:${port}`, auth: process.env.SHADOK_AUTH ?? "" };
+}
+
+async function api(ctx, method, path, body) {
+  let res;
+  try {
+    res = await fetch(ctx.base + path, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(ctx.auth ? { Cookie: ctx.auth } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch (e) {
+    die(`cannot reach the cockpit on ${ctx.base}: ${e.message}`);
+  }
+  const raw = await res.text();
+  if (res.status === 409) {
+    die(
+      "refused: a secret by that name already exists. Do NOT overwrite it " +
+        "yourself — tell the user and let them decide.",
+    );
+  }
+  if (!res.ok) die(`API error ${res.status}: ${raw.slice(0, 200)}`);
+  return raw ? JSON.parse(raw) : {};
+}
+
+/**
+ * The command line, kept identical to the argparse version. `--stdin` is
+ * REQUIRED rather than optional: that is what removes any way of passing a
+ * value in argv, so it is a security property, not ergonomics.
+ */
+export function parseArgs(argv) {
+  const [cmd, ...rest] = argv;
+  if (cmd === "list") {
+    if (rest.length) throw new UsageError(`secret list: unrecognized arguments: ${rest.join(" ")}`);
+    return { cmd };
+  }
+  if (cmd !== "set") {
+    throw new UsageError(`usage: secret {list,set} …\ninvalid choice: '${cmd ?? ""}'`);
+  }
+  let name;
+  let stdin = false;
+  for (const a of rest) {
+    if (a === "--stdin") stdin = true;
+    else if (a.startsWith("-")) throw new UsageError(`secret set: unrecognized argument ${a}`);
+    else if (name === undefined) name = a;
+    else throw new UsageError(`secret set: unrecognized arguments: ${a}`);
+  }
+  if (name === undefined) throw new UsageError("secret set: the following arguments are required: name");
+  if (!stdin) {
+    throw new UsageError(
+      "secret set: the following arguments are required: --stdin (the value is read from stdin, never from argv)",
+    );
+  }
+  return { cmd, name };
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let buf = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (buf += c));
+    process.stdin.on("end", () => resolve(buf));
+    process.stdin.on("error", () => resolve(buf));
+  });
+}
+
+export async function main(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    if (!(e instanceof UsageError)) throw e;
+    process.stderr.write(e.message + "\n");
+    process.exit(2);
+  }
+  const ctx = env();
+
+  if (parsed.cmd === "list") {
+    const names = (await api(ctx, "GET", "/secrets")).names ?? [];
+    console.log(names.length ? names.join("\n") : "(vault empty)");
+    return;
+  }
+
+  const value = (await readStdin()).trim();
+  if (!value) die("nothing on stdin — pipe the value in, e.g. `gh auth token | ... --stdin`");
+  await api(ctx, "PUT", "/secrets", { name: parsed.name, value });
+  // Never echo the value back: this output lands in the transcript, and may be
+  // mirrored to Telegram.
+  console.log(`stored ${parsed.name} in the vault`);
+  console.log("It reaches an agent only once attached to a profile (web Profiles panel).");
+}
+
+// Importable by the tests, executable by the agents: only run when invoked
+// directly, or importing this file would exit on a missing SHADOK_PORT.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main(process.argv.slice(2));
+}

package/context/secrets-skill/test/fake-cockpit.mjs

@@ -0,0 +1,21 @@
+import http from "node:http";
+
+// A stand-in for the cockpit: records what the script sent, answers `status`.
+// Deliberately not shared with the shadok-ai-agents skill's `mock-server.mjs`,
+// which is built around the WebSocket protocol and pilotctl's own routes.
+export async function fakeCockpit(status, body) {
+  const seen = { body: undefined, cookie: undefined, method: undefined };
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => {
+      seen.method = req.method;
+      seen.body = raw ? JSON.parse(raw) : null;
+      seen.cookie = req.headers.cookie;
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    });
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  return { port: server.address().port, seen, close: () => new Promise((r) => server.close(r)) };
+}