@instruction.md/agents 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/converse.js CHANGED
@@ -30,9 +30,17 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
30
30
  ]);
31
31
  var MANY_FLAGS = /* @__PURE__ */ new Set(["--mcp-config", "--allowedTools", "--allowed-tools", "--disallowedTools", "--disallowed-tools", "--add-dir", "--plugin-dir", "--tools"]);
32
32
  function converseArgv(argv) {
33
+ const t = taskOf(argv);
34
+ if (!t || argv.includes("--input-format") || argv.includes("--output-format")) return null;
35
+ const out = t.rest;
36
+ out.push("--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--permission-prompt-tool", "stdio");
37
+ if (!argv.includes("--permission-mode") && !argv.includes("--dangerously-skip-permissions")) out.push("--permission-mode", "default");
38
+ return { argv: out, prompt: t.prompt };
39
+ }
40
+ function taskOf(argv) {
33
41
  if (basename(argv[0] ?? "").replace(/\.(exe|cmd)$/i, "") !== "claude") return null;
34
42
  const p = argv.findIndex((a) => a === "-p" || a === "--print");
35
- if (p < 0 || argv.includes("--input-format") || argv.includes("--output-format")) return null;
43
+ if (p < 0) return null;
36
44
  let at = -1;
37
45
  if (argv[p + 1] !== void 0 && !argv[p + 1].startsWith("-")) at = p + 1;
38
46
  else {
@@ -44,10 +52,7 @@ function converseArgv(argv) {
44
52
  if (last > p && !argv[last].startsWith("-") && !VALUE_FLAGS.has(before) && !inMany) at = last;
45
53
  }
46
54
  if (at < 0 || !argv[at].trim()) return null;
47
- const out = argv.filter((_, i) => i !== at);
48
- out.push("--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--permission-prompt-tool", "stdio");
49
- if (!argv.includes("--permission-mode") && !argv.includes("--dangerously-skip-permissions")) out.push("--permission-mode", "default");
50
- return { argv: out, prompt: argv[at] };
55
+ return { prompt: argv[at], rest: argv.filter((_, i) => i !== at) };
51
56
  }
52
57
  var SECRETS = [
53
58
  /\b(?:sk|rk|pk)-(?:ant-|proj-|live-|test-)?[A-Za-z0-9_-]{16,}/g,
@@ -252,5 +257,6 @@ export {
252
257
  maskText,
253
258
  masked,
254
259
  responseOf,
260
+ taskOf,
255
261
  toolLine
256
262
  };
package/dist/fleet.js CHANGED
@@ -4,6 +4,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "nod
4
4
  import { hostname } from "node:os";
5
5
  import { basename, join, resolve } from "node:path";
6
6
  import { atomicWrite, DEFAULT_URL, ensureGitignore, readState } from "instruction.md/cli";
7
+ import { asksTrust, inTerminal, inheritedEnv, remoteAppOf, remoteArgv, remoteName, remoteRefusal, remoteUrlOf } from "./remote.js";
7
8
  import { ClaudeSession, cardOf, converseArgv, responseOf } from "./converse.js";
8
9
  var str = (v) => typeof v === "string" && v ? v : void 0;
9
10
  var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
@@ -234,7 +235,7 @@ var Fleet = class {
234
235
  const follow = followUri(d);
235
236
  const dir = join(folder, ".instruction");
236
237
  mkdirSync(dir, { recursive: true });
237
- const hosted = appOf(this.o.command, this.o.host) === "claude-code" && this.o.converse !== false && !!this.client.converse && !!converseArgv(this.o.command);
238
+ const hosted = appOf(this.o.command, this.o.host) === "claude-code" && this.o.converse !== false && !this.o.remoteControl && !!this.client.converse && !!converseArgv(this.o.command);
238
239
  const config = { follow, ...d.requireSignature ? { requireSignature: true } : {}, ...this.o.url ? { url: this.o.url } : {}, deploymentId: d.id, ...hosted ? { converse: true } : {} };
239
240
  atomicWrite(join(dir, "follow.json"), `${JSON.stringify(config, null, 2)}
240
241
  `);
@@ -302,15 +303,26 @@ var Fleet = class {
302
303
  if (this.blocked.delete(d.id)) this.log(`${labelOfDeployment(d)}: what it needed is here now`);
303
304
  }
304
305
  let argv = commandFor(this.o.command, d, folder);
305
- const conv = app === "claude-code" && this.o.converse !== false && this.client.converse && !this.o.dryRun ? converseArgv(argv) : null;
306
- if (app === "claude-code" && this.o.converse !== false && this.client.converse && !conv && !this.saidNoConverse) {
306
+ let terminal = null;
307
+ if (this.o.remoteControl && !this.o.dryRun) {
308
+ const r = remoteAppOf(argv) ? remoteArgv(argv, remoteName(labelOfDeployment(d))) : null;
309
+ const withSetup = r ? [r[0], ...claudeArgv([r[0]], folder).slice(1), ...r.slice(1)] : null;
310
+ terminal = withSetup ? inTerminal(withSetup) : null;
311
+ if (!terminal && !this.saidNoRemote) {
312
+ this.saidNoRemote = true;
313
+ this.log(!r ? 'fleet: --remote-control runs Claude Code: give it its task as `claude -p "…"`; its agents run without remote control' : "fleet: --remote-control needs a terminal (`script`, on Linux and macOS); its agents run without remote control");
314
+ }
315
+ }
316
+ const conv = !terminal && app === "claude-code" && this.o.converse !== false && this.client.converse && !this.o.dryRun ? converseArgv(argv) : null;
317
+ if (!terminal && app === "claude-code" && this.o.converse !== false && this.client.converse && !conv && !this.saidNoConverse) {
307
318
  this.saidNoConverse = true;
308
319
  this.log(`fleet: its agents' questions can't reach instruction.md: give Claude Code its prompt as \`claude -p "…"\` (without --input-format or --output-format)`);
309
320
  }
310
321
  if (conv) argv = conv.argv;
311
- if (app === "claude-code") argv = claudeArgv(argv, folder);
312
- const env = { ...process.env, ...hostVars, INSTRUCTION_MD_FOLLOW: follow, INSTRUCTION_MD_DEPLOYMENT: d.id, ...this.o.url ? { INSTRUCTION_MD_URL: this.o.url } : {}, ...this.o.accountsFile ? { INSTRUCTION_MD_ACCOUNTS: this.o.accountsFile } : {} };
313
- const child = (this.o.spawnImpl ?? spawn)(argv[0], argv.slice(1), { cwd: folder, env, stdio: [conv ? "pipe" : "ignore", "pipe", "pipe"] });
322
+ if (terminal) argv = [terminal.command, ...terminal.args];
323
+ else if (app === "claude-code") argv = claudeArgv(argv, folder);
324
+ const env = { ...inheritedEnv(process.env, !!terminal), ...terminal ? { TERM: process.env.TERM && process.env.TERM !== "dumb" ? process.env.TERM : "xterm-256color", COLUMNS: "120", LINES: "40" } : {}, ...hostVars, INSTRUCTION_MD_FOLLOW: follow, INSTRUCTION_MD_DEPLOYMENT: d.id, ...this.o.url ? { INSTRUCTION_MD_URL: this.o.url } : {}, ...this.o.accountsFile ? { INSTRUCTION_MD_ACCOUNTS: this.o.accountsFile } : {} };
325
+ const child = (this.o.spawnImpl ?? spawn)(argv[0], argv.slice(1), { cwd: folder, env, stdio: [conv || terminal ? "pipe" : "ignore", "pipe", "pipe"] });
314
326
  const a = {
315
327
  d,
316
328
  folder,
@@ -351,6 +363,30 @@ var Fleet = class {
351
363
  subagents: () => void this.reportOne(a.d.id, this.reportFor(a))
352
364
  });
353
365
  a.session.begin(conv.prompt);
366
+ } else if (terminal) {
367
+ let screen = "", trusted = false;
368
+ child.stdout?.on("data", (c) => {
369
+ keep(c, false);
370
+ screen = (screen + c.toString("utf8")).slice(-2e4);
371
+ if (!trusted && asksTrust(screen)) {
372
+ trusted = true;
373
+ child.stdin?.write("\r");
374
+ }
375
+ if (!a.remote) {
376
+ const url = remoteUrlOf(screen);
377
+ if (url) {
378
+ a.remote = { app: "claude-code", url };
379
+ this.log(`${labelOfDeployment(d)}: in the Claude app — ${url}`);
380
+ void this.reportOne(a.d.id, this.reportFor(a));
381
+ } else {
382
+ const no = remoteRefusal(screen);
383
+ if (no && !a.stderr.includes(no)) {
384
+ a.stderr.push(no);
385
+ this.log(`${labelOfDeployment(d)}: ${no}`);
386
+ }
387
+ }
388
+ }
389
+ });
354
390
  } else child.stdout?.on("data", (c) => keep(c, false));
355
391
  child.stderr?.on("data", (c) => keep(c, true));
356
392
  child.on("error", (e) => {
@@ -505,7 +541,8 @@ var Fleet = class {
505
541
  health: signIn ? "needs_sign_in" : failed ? "failed" : "ok",
506
542
  ...failed ? { error: (a.stderr.slice(-5).join("\n") || `exited (${a.exitSignal ?? `code ${a.exitCode}`})`).slice(0, 2e3) } : {},
507
543
  ...signIn && app ? { needs: [{ kind: "host", name: app, what: signIn.slice(0, 300), fix: HOST_FIX[app] }] } : {},
508
- ...a.session ? { subagents: alive ? a.session.subagents : [] } : {}
544
+ ...a.session ? { subagents: alive ? a.session.subagents : [] } : {},
545
+ ...a.remote && alive ? { remote: a.remote } : {}
509
546
  };
510
547
  }
511
548
  async reportAll() {
@@ -514,6 +551,7 @@ var Fleet = class {
514
551
  }
515
552
  // ───────────── conversations (RFC-0059) ─────────────
516
553
  saidNoConverse = false;
554
+ saidNoRemote = false;
517
555
  onceMode = false;
518
556
  converseTimer = null;
519
557
  /** The cards waiting for a person, each with what checks it again. */
@@ -858,7 +896,7 @@ function registryFleetClient(c, q, log = (l) => process.stderr.write(`${l}
858
896
  }
859
897
  },
860
898
  async report(r) {
861
- await call("deployments_report", { deploymentId: r.deploymentId, running: r.running, ...r.versionId ? { versionId: r.versionId } : {}, ...r.health ? { health: r.health } : {}, ...r.error ? { error: r.error } : {}, ...r.host ? { host: r.host } : {}, ...r.needs?.length ? { needs: r.needs } : {}, ...r.activity?.length ? { activity: r.activity } : {}, ...r.subagents ? { subagents: r.subagents } : {} });
899
+ await call("deployments_report", { deploymentId: r.deploymentId, running: r.running, ...r.versionId ? { versionId: r.versionId } : {}, ...r.health ? { health: r.health } : {}, ...r.error ? { error: r.error } : {}, ...r.host ? { host: r.host } : {}, ...r.needs?.length ? { needs: r.needs } : {}, ...r.activity?.length ? { activity: r.activity } : {}, ...r.subagents ? { subagents: r.subagents } : {}, ...r.remote ? { remote: r.remote } : {} });
862
900
  },
863
901
  converse: {
864
902
  async ask(card) {
@@ -893,7 +931,7 @@ function registryFleetClient(c, q, log = (l) => process.stderr.write(`${l}
893
931
  }
894
932
  };
895
933
  }
896
- var FLEET_USAGE = "usage: instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run] [--restart-on-exit] [--clean] [--host APP] [--accounts FILE] [--no-apply] [--no-converse] [--cli CMD] [--url U] [--token T] -- <command…>";
934
+ var FLEET_USAGE = "usage: instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run] [--restart-on-exit] [--clean] [--host APP] [--accounts FILE] [--no-apply] [--no-converse] [--remote-control] [--cli CMD] [--url U] [--token T] -- <command…>";
897
935
  function take(args, flag) {
898
936
  const i = args.indexOf(flag);
899
937
  if (i < 0) return void 0;
@@ -916,7 +954,7 @@ async function cmdFleet(argv) {
916
954
  const max = take(args, "--max"), interval = take(args, "--interval");
917
955
  const once = has(args, "--once"), dryRun = has(args, "--dry-run"), restartOnExit = has(args, "--restart-on-exit"), clean = has(args, "--clean");
918
956
  const url = take(args, "--url"), token = take(args, "--token"), host = take(args, "--host");
919
- const accountsFlag = take(args, "--accounts"), noApply = has(args, "--no-apply"), cli = take(args, "--cli"), noConverse = has(args, "--no-converse");
957
+ const accountsFlag = take(args, "--accounts"), noApply = has(args, "--no-apply"), cli = take(args, "--cli"), noConverse = has(args, "--no-converse"), remoteControl = has(args, "--remote-control");
920
958
  if (!rule && !platform || rule && platform || org && !platform || !command.length || args.length) {
921
959
  console.error(FLEET_USAGE);
922
960
  return 2;
@@ -925,6 +963,10 @@ async function cmdFleet(argv) {
925
963
  console.error("--max is a whole number above 0");
926
964
  return 2;
927
965
  }
966
+ if (remoteControl && once) {
967
+ console.error("--remote-control runs agents you control in their app, which don't end on their own: not with --once");
968
+ return 2;
969
+ }
928
970
  if (interval !== void 0 && !(Number(interval) >= 1)) {
929
971
  console.error("--interval is a number of seconds, at least 1");
930
972
  return 2;
@@ -962,6 +1004,7 @@ async function cmdFleet(argv) {
962
1004
  accounts: loadAccounts(accountsFile),
963
1005
  ...cli ? { cli } : {},
964
1006
  ...noConverse ? { converse: false } : {},
1007
+ ...remoteControl ? { remoteControl: true } : {},
965
1008
  // (follow.json names the registry only when it isn't the default one)
966
1009
  ...conn.url !== DEFAULT_URL ? { url: conn.url } : {}
967
1010
  });
package/dist/hook.js CHANGED
@@ -5,7 +5,7 @@ import { hostname } from "node:os";
5
5
  import { isAbsolute, join, relative } from "node:path";
6
6
 
7
7
  // package.json
8
- var version = "0.3.0";
8
+ var version = "0.4.0";
9
9
 
10
10
  // src/hook.ts
11
11
  import {
package/dist/main.js CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // package.json
3
3
  var name = "@instruction.md/agents";
4
- var version = "0.3.0";
4
+ var version = "0.4.0";
5
5
 
6
6
  // src/main.ts
7
7
  import { cmdHook } from "./hook.js";
@@ -26,7 +26,7 @@ People run
26
26
  (.claude/agents/) or skill (.claude/skills/), a Codex skill
27
27
  (.agents/skills/); again to take a new version
28
28
  instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run]
29
- [--restart-on-exit] [--clean] [--host APP] -- <command…>
29
+ [--restart-on-exit] [--clean] [--host APP] [--remote-control] -- <command…>
30
30
  an agent per instruction (RFC-0042 §10): runs the command once
31
31
  per active deployment of a rule or a platform, each in a folder
32
32
  of its own with its .instruction/follow.json; starts new ones,
@@ -35,6 +35,11 @@ People run
35
35
  maxAgents; reports each. {instruction} {name} {dir} in the
36
36
  command are replaced. --once: one pass, waiting for each
37
37
  command to end (a cron job); --dry-run: what it would do
38
+ --remote-control (claude -p "<task>"): each agent a Claude
39
+ Code session you control in the Claude app (claude.ai/code,
40
+ the phone app), named after its instruction; /agents links
41
+ to it. Needs a claude.ai sign-in (Pro, Max, Team,
42
+ Enterprise; not an API key), Linux or macOS
38
43
  instruction agents apply [<uri>] [--host claude-code|codex|both] [--approve] [--dry-run] [--remove] [--dir D] [--cli CMD]
39
44
  write the instruction's MCP servers and skills into the app's
40
45
  own files (.mcp.json, .claude/skills/, .codex/config.toml,
package/dist/remote.js ADDED
@@ -0,0 +1,74 @@
1
+ // src/remote.ts
2
+ import { existsSync } from "node:fs";
3
+ import { basename } from "node:path";
4
+ import { taskOf } from "./converse.js";
5
+ var REMOTE_APPS = ["claude-code"];
6
+ function remoteArgv(argv, name) {
7
+ const t = taskOf(argv);
8
+ if (!t) return null;
9
+ const rest = [];
10
+ for (let i = 1; i < t.rest.length; i++) {
11
+ const a = t.rest[i];
12
+ if (a === "--" || a === "-p" || a === "--print" || a === "--verbose" || a === "--include-partial-messages" || a === "--replay-user-messages") continue;
13
+ if (a === "--output-format" || a === "--input-format" || a === "--permission-prompt-tool") {
14
+ i++;
15
+ continue;
16
+ }
17
+ rest.push(a);
18
+ }
19
+ return [t.rest[0], "--remote-control", name, ...rest, "--", t.prompt];
20
+ }
21
+ var remoteName = (label) => `instruction.md: ${label}`.slice(0, 80);
22
+ function inTerminal(argv, platform = process.platform, has = existsSync) {
23
+ const script = ["/usr/bin/script", "/bin/script"].find((p) => has(p));
24
+ if (!script) return null;
25
+ if (platform === "linux") return { command: script, args: ["-qfec", argv.map(shq).join(" "), "/dev/null"] };
26
+ if (platform === "darwin") return { command: script, args: ["-qF", "/dev/null", ...argv] };
27
+ return null;
28
+ }
29
+ var shq = (s) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
30
+ var ESCAPES = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
31
+ var plainOf = (s) => s.replace(ESCAPES, "");
32
+ function remoteUrlOf(screen) {
33
+ const m = /https:\/\/claude\.ai\/code\/(session_[A-Za-z0-9]{16,40})/.exec(screen) ?? /https:\/\/claude\.ai\/code\/(session_[A-Za-z0-9]{16,40})/.exec(plainOf(screen));
34
+ return m ? `https://claude.ai/code/${m[1]}` : null;
35
+ }
36
+ var asksTrust = (screen) => /trust (?:the files in )?this folder|do you trust|folder you trust/i.test(plainOf(screen));
37
+ function remoteRefusal(screen) {
38
+ const s = plainOf(screen);
39
+ const m = /(Remote Control (?:is )?(?:not available|unavailable|disabled|requires)[^\n]{0,160})/i.exec(s);
40
+ return m ? m[1].trim() : null;
41
+ }
42
+ function inheritedEnv(env, remote) {
43
+ const out = {};
44
+ for (const [k, v] of Object.entries(env)) {
45
+ if (k === "CLAUDECODE" || k === "CLAUDE_PID" || k === "CLAUDE_EFFORT" || k.startsWith("CLAUDE_CODE_") && SESSION_VARS.has(k)) continue;
46
+ if (remote && (k === "ANTHROPIC_API_KEY" || k === "ANTHROPIC_AUTH_TOKEN" || k === "ANTHROPIC_BASE_URL")) continue;
47
+ out[k] = v;
48
+ }
49
+ return out;
50
+ }
51
+ var SESSION_VARS = /* @__PURE__ */ new Set([
52
+ "CLAUDE_CODE_SESSION_ID",
53
+ "CLAUDE_CODE_BRIDGE_SESSION_ID",
54
+ "CLAUDE_CODE_CHILD_SESSION",
55
+ "CLAUDE_CODE_CHILD_NOTES_DIR",
56
+ "CLAUDE_CODE_MESSAGING_SOCKET",
57
+ "CLAUDE_CODE_MESSAGING_TOKEN",
58
+ "CLAUDE_CODE_SESSION_ATTENDED",
59
+ "CLAUDE_CODE_ENTRYPOINT",
60
+ "CLAUDE_CODE_EXECPATH"
61
+ ]);
62
+ var remoteAppOf = (argv) => basename(argv[0] ?? "").replace(/\.(exe|cmd)$/i, "") === "claude" ? "claude-code" : null;
63
+ export {
64
+ REMOTE_APPS,
65
+ asksTrust,
66
+ inTerminal,
67
+ inheritedEnv,
68
+ plainOf,
69
+ remoteAppOf,
70
+ remoteArgv,
71
+ remoteName,
72
+ remoteRefusal,
73
+ remoteUrlOf
74
+ };
package/dist/turns.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { hostname } from "node:os";
3
3
 
4
4
  // package.json
5
- var version = "0.3.0";
5
+ var version = "0.4.0";
6
6
 
7
7
  // src/turns.ts
8
8
  import { runHook } from "./hook.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@instruction.md/agents",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Run agents with instruction.md: the `instruction-agents` CLI. Hooks that give Claude Code, Codex and other agents the instruction a project follows, and each new version as it is released; the ACP proxy, pi's extension and the SDK helper; `fleet`, an agent for every deployment, whose questions and permission requests reach you on instruction.md/agents; and an agent's MCP servers, skills and sign-ins (apply, doctor, accounts, signin, credential). Built on the instruction.md package.",
5
5
  "keywords": [
6
6
  "instruction.md",