@instruction.md/agents 0.1.0 → 0.3.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/README.md +12 -11
- package/dist/accounts.js +16 -16
- package/dist/apply.js +1 -1
- package/dist/connect.js +5 -5
- package/dist/converse.js +31 -4
- package/dist/fleet.js +8 -6
- package/dist/hook.js +3 -3
- package/dist/main.js +60 -47
- package/dist/oauth.js +5 -5
- package/dist/setup.js +13 -13
- package/dist/sync.js +15 -5
- package/dist/turns.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# @instruction.md/agents
|
|
2
2
|
|
|
3
|
-
Run agents with [instruction.md](https://instruction.md): the `instruction-agents` CLI, for Node 18+.
|
|
3
|
+
Run agents with [instruction.md](https://instruction.md): the `instruction-agents` CLI, for Node 18+. Installed next to the
|
|
4
|
+
`instruction` command, every command here also runs as `instruction agents <command>`.
|
|
4
5
|
|
|
5
6
|
- **Following an instruction**: the hooks that give Claude Code, Codex and a dozen other coding agents the instruction a
|
|
6
7
|
project follows at a session's start, and each new version at the next prompt; the ACP proxy, pi's extension, Amp's
|
|
@@ -16,8 +17,8 @@ Writing, checking and releasing instructions is the `instruction` command, in th
|
|
|
16
17
|
```sh
|
|
17
18
|
npm install -g @instruction.md/agents
|
|
18
19
|
instruction-agents login # the same sign-in as `instruction login`
|
|
19
|
-
instruction-agents
|
|
20
|
-
instruction-agents
|
|
20
|
+
instruction-agents follow acme/support@stable --host claude-code --write
|
|
21
|
+
instruction-agents run --platform laptop --org acme -- claude -p "Work through today's queue."
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
or, without installing, `npx -y @instruction.md/agents <command>`. `instruction-agents --help` lists every command.
|
|
@@ -66,7 +67,7 @@ in every repository; `--block` keeps only its own region of the file:
|
|
|
66
67
|
npx -y instruction.md watch acme/me@latest --out ~/.codex/AGENTS.md --block
|
|
67
68
|
```
|
|
68
69
|
|
|
69
|
-
For an organization, `instruction-agents
|
|
70
|
+
For an organization, `instruction-agents follow <uri> --host claude-code|codex --managed` prints the settings an
|
|
70
71
|
administrator deploys (Claude Code's `managed-settings.json`, Codex's `requirements.toml`): every session on the
|
|
71
72
|
machine follows `<uri>` (`instruction-agents hook <host> --follow <uri>`).
|
|
72
73
|
|
|
@@ -109,19 +110,19 @@ chat applies, kept current:
|
|
|
109
110
|
npx -y instruction.md watch acme/support@stable --out .cursor/rules/instruction-md.mdc --rule
|
|
110
111
|
```
|
|
111
112
|
|
|
112
|
-
## As a subagent or a skill: `instruction-agents
|
|
113
|
+
## As a subagent or a skill: `instruction-agents install`
|
|
113
114
|
|
|
114
115
|
```sh
|
|
115
|
-
npx @instruction.md/agents
|
|
116
|
-
npx @instruction.md/agents
|
|
117
|
-
npx @instruction.md/agents
|
|
116
|
+
npx @instruction.md/agents install acme/reviewer@stable --host claude-code --as agent # .claude/agents/reviewer.md
|
|
117
|
+
npx @instruction.md/agents install acme/release@stable --host claude-code --as skill # .claude/skills/release/SKILL.md
|
|
118
|
+
npx @instruction.md/agents install acme/release@stable --host codex --as skill # .agents/skills/release/SKILL.md
|
|
118
119
|
```
|
|
119
120
|
|
|
120
121
|
The file takes the host's front matter (`name`, `description`, from the instruction's name and description), a line
|
|
121
122
|
saying where it came from (address, version, digest) and the delivered text. Run it again to take a new version: it is
|
|
122
123
|
written whole, or left as it is when nothing changed; both hosts notice a changed subagent or skill within the session.
|
|
123
124
|
A file sync didn't write, or one from another instruction, is left alone unless `--force`. In a project that follows
|
|
124
|
-
an instruction, `instruction-agents
|
|
125
|
+
an instruction, `instruction-agents install --host … --as …` with no uri installs that one, from the cache when you aren't signed in.
|
|
125
126
|
|
|
126
127
|
## In pi, Amp and any ACP agent
|
|
127
128
|
|
|
@@ -143,10 +144,10 @@ code of ours rather than a hook command:
|
|
|
143
144
|
|
|
144
145
|
Each reports the version a session applied with its host (`pi`, `amp`, `acp`).
|
|
145
146
|
|
|
146
|
-
## An agent per instruction: `instruction-agents
|
|
147
|
+
## An agent per instruction: `instruction-agents run`
|
|
147
148
|
|
|
148
149
|
A deployment rule (Settings ▸ Deployments in the editor; Team and above) picks a set of instructions: a project, a
|
|
149
|
-
folder, tags, a list. Each instruction in it becomes a deployment, and `instruction-agents
|
|
150
|
+
folder, tags, a list. Each instruction in it becomes a deployment, and `instruction-agents run` runs one agent per active
|
|
150
151
|
deployment on a machine:
|
|
151
152
|
|
|
152
153
|
```
|
package/dist/accounts.js
CHANGED
|
@@ -32,7 +32,7 @@ function entryFor(a, id, account) {
|
|
|
32
32
|
function describeEntry(e) {
|
|
33
33
|
if (e.env) return `the variable ${e.env}`;
|
|
34
34
|
if (e.command) return `the command ${e.command.split(/\s+/)[0]}…`;
|
|
35
|
-
if (e.oauth) return "a sign-in (instruction
|
|
35
|
+
if (e.oauth) return "a sign-in (instruction agents signin)";
|
|
36
36
|
if (e.xaa) return `the identity provider ${safeHost(e.xaa.idp)}`;
|
|
37
37
|
return "nothing";
|
|
38
38
|
}
|
|
@@ -81,14 +81,14 @@ async function headersFor(key, entry, o = {}) {
|
|
|
81
81
|
store.tokens[key] = t;
|
|
82
82
|
saveTokens(store, file);
|
|
83
83
|
} catch (e) {
|
|
84
|
-
if (!entry.xaa) throw new SecretError(`the sign-in to ${key} lapsed and couldn't be renewed (${e.message})`, `instruction
|
|
84
|
+
if (!entry.xaa) throw new SecretError(`the sign-in to ${key} lapsed and couldn't be renewed (${e.message})`, `instruction agents signin ${key.split("@")[0]}${key.includes("@") ? ` --account ${key.split("@")[1]}` : ""}${o.url ? ` --url ${o.url}` : ""}`);
|
|
85
85
|
t = void 0;
|
|
86
86
|
}
|
|
87
87
|
} else t = void 0;
|
|
88
88
|
}
|
|
89
89
|
if (!t && entry.xaa) {
|
|
90
90
|
const x = entry.xaa, url = o.url ?? store.tokens[key]?.resource;
|
|
91
|
-
if (!url) throw new SecretError(`the address of ${key} isn't known here`, `instruction
|
|
91
|
+
if (!url) throw new SecretError(`the address of ${key} isn't known here`, `instruction agents credential ${key} --url <its address>`);
|
|
92
92
|
const client = (id, s) => ({ client_id: id, ...s ? { client_secret: secretOf(s, env) } : {} });
|
|
93
93
|
try {
|
|
94
94
|
t = await xaaToken({ idp: x.idp, idpClient: client(x.clientId, x.clientSecret), subjectToken: secretOf(x.subjectToken, env), ...x.subjectTokenType ? { subjectTokenType: x.subjectTokenType } : {}, resource: url, ...x.scope ? { scope: x.scope } : {}, serverClient: client(x.serverClientId, x.serverClientSecret), ...x.audience ? { audience: x.audience } : {}, ...x.tokenEndpoint ? { tokenEndpoint: x.tokenEndpoint } : {} }, o.f, now);
|
|
@@ -98,10 +98,10 @@ async function headersFor(key, entry, o = {}) {
|
|
|
98
98
|
store.tokens[key] = t;
|
|
99
99
|
saveTokens(store, file);
|
|
100
100
|
}
|
|
101
|
-
if (!t) throw new SecretError(`${key} isn't signed in on this machine`, `instruction
|
|
101
|
+
if (!t) throw new SecretError(`${key} isn't signed in on this machine`, `instruction agents signin ${key.split("@")[0]}${key.includes("@") ? ` --account ${key.split("@")[1]}` : ""}${o.url ? ` --url ${o.url}` : ""}`);
|
|
102
102
|
return { [header]: `${scheme || "Bearer"} ${t.access_token}` };
|
|
103
103
|
}
|
|
104
|
-
throw new SecretError(`the entry for ${key} says nowhere to find its credential`, `instruction
|
|
104
|
+
throw new SecretError(`the entry for ${key} says nowhere to find its credential`, `instruction agents accounts set ${key} --env VAR`);
|
|
105
105
|
}
|
|
106
106
|
function hostEnv(a, host, env = process.env) {
|
|
107
107
|
const h = a.hosts[host];
|
|
@@ -124,13 +124,13 @@ function has(args, flag) {
|
|
|
124
124
|
}
|
|
125
125
|
var KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*(@[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
|
|
126
126
|
var ACCOUNTS_USAGE = `usage:
|
|
127
|
-
instruction
|
|
128
|
-
instruction
|
|
127
|
+
instruction agents accounts what each server and host uses on this machine
|
|
128
|
+
instruction agents accounts set <server[@account]> (--env VAR | --command CMD | --oauth | --xaa-idp URL --xaa-client-id ID
|
|
129
129
|
--xaa-subject-env V|--xaa-subject-command C --xaa-server-client-id ID [--xaa-client-secret-env V|--xaa-client-secret-command C]
|
|
130
130
|
[--xaa-server-client-secret-env V|--xaa-server-client-secret-command C] [--xaa-scope S] [--xaa-audience ISS])
|
|
131
131
|
[--header NAME] [--scheme WORD]
|
|
132
|
-
instruction
|
|
133
|
-
instruction
|
|
132
|
+
instruction agents accounts host <claude-code|codex> --env VAR (--from-env V | --from-command C)
|
|
133
|
+
instruction agents accounts remove <server[@account]> | instruction agents accounts remove-host <name>`;
|
|
134
134
|
var src = (args, envFlag, cmdFlag) => {
|
|
135
135
|
const e = take(args, envFlag), c = take(args, cmdFlag);
|
|
136
136
|
if (e && c) throw new OAuthError(`${envFlag} or ${cmdFlag}, not both`, 2);
|
|
@@ -200,7 +200,7 @@ ${ACCOUNTS_USAGE}`);
|
|
|
200
200
|
a.servers[key] = entry;
|
|
201
201
|
saveAccounts(a, file);
|
|
202
202
|
console.log(`${key}: ${describeEntry(entry)} (${file})${oauth ? `
|
|
203
|
-
Now sign in: instruction
|
|
203
|
+
Now sign in: instruction agents signin ${key.split("@")[0]}${key.includes("@") ? ` --account ${key.split("@")[1]}` : ""} --url <its address>` : ""}`);
|
|
204
204
|
return 0;
|
|
205
205
|
}
|
|
206
206
|
if (sub === "host") {
|
|
@@ -212,7 +212,7 @@ Now sign in: instruction-agents signin ${key.split("@")[0]}${key.includes("@") ?
|
|
|
212
212
|
}
|
|
213
213
|
a.hosts[name] = { env, from };
|
|
214
214
|
saveAccounts(a, file);
|
|
215
|
-
console.log(`host ${name}: ${env} from ${"env" in from ? `the variable ${from.env}` : "a command"} (${file}); \`instruction
|
|
215
|
+
console.log(`host ${name}: ${env} from ${"env" in from ? `the variable ${from.env}` : "a command"} (${file}); \`instruction agents run\` sets it for each agent it starts`);
|
|
216
216
|
return 0;
|
|
217
217
|
}
|
|
218
218
|
if (sub === "remove" || sub === "remove-host") {
|
|
@@ -243,17 +243,17 @@ async function cmdCredential(argv) {
|
|
|
243
243
|
const file = take(args, "--accounts");
|
|
244
244
|
const id = args.shift() ?? process.env.CLAUDE_CODE_MCP_SERVER_NAME;
|
|
245
245
|
if (!id || args.length) {
|
|
246
|
-
console.error("usage: instruction
|
|
246
|
+
console.error("usage: instruction agents credential <server> [--account A] [--url U]");
|
|
247
247
|
return 2;
|
|
248
248
|
}
|
|
249
249
|
if (process.stdout.isTTY && !show) {
|
|
250
|
-
console.error("instruction
|
|
250
|
+
console.error("instruction agents credential prints a secret for an agent's app to read; it doesn't print to a terminal (run `instruction agents check` to check it works)");
|
|
251
251
|
return 2;
|
|
252
252
|
}
|
|
253
253
|
const a = loadAccounts(file ?? accountsPath());
|
|
254
254
|
const found = entryFor(a, id, account);
|
|
255
255
|
if (!found) {
|
|
256
|
-
console.error(`instruction.md: no account for ${account ? `${id}@${account}` : id} on this machine: instruction
|
|
256
|
+
console.error(`instruction.md: no account for ${account ? `${id}@${account}` : id} on this machine: instruction agents accounts set ${account ? `${id}@${account}` : id} …`);
|
|
257
257
|
return 4;
|
|
258
258
|
}
|
|
259
259
|
try {
|
|
@@ -274,14 +274,14 @@ async function cmdSignin(argv) {
|
|
|
274
274
|
let url = take(args, "--url");
|
|
275
275
|
const id = args.shift();
|
|
276
276
|
if (!id || args.length || !KEY.test(account ? `${id}@${account}` : id)) {
|
|
277
|
-
console.error("usage: instruction
|
|
277
|
+
console.error("usage: instruction agents signin <server> --url U [--account A] [--device] [--no-browser] [--scope S] [--client-id ID [--client-secret-env V]]");
|
|
278
278
|
return 2;
|
|
279
279
|
}
|
|
280
280
|
const key = account ? `${id}@${account}` : id;
|
|
281
281
|
const store = loadTokens();
|
|
282
282
|
url ??= store.tokens[key]?.resource ?? appliedUrl(id);
|
|
283
283
|
if (!url) {
|
|
284
|
-
console.error(`name the server's address: instruction
|
|
284
|
+
console.error(`name the server's address: instruction agents signin ${id}${account ? ` --account ${account}` : ""} --url https://…`);
|
|
285
285
|
return 2;
|
|
286
286
|
}
|
|
287
287
|
try {
|
package/dist/apply.js
CHANGED
|
@@ -324,7 +324,7 @@ async function applyMachinery(src, o) {
|
|
|
324
324
|
if (changed || !before) atomicWrite(join(o.dir, APPLIED_FILE), `${JSON.stringify({ ...applied, at: changed || !before ? applied.at : before.at }, null, 2)}
|
|
325
325
|
`);
|
|
326
326
|
}
|
|
327
|
-
if (hosts.has("claude-code") && !o.fleet && !o.approve && nextOwned[mcpFile]?.length) result.notes.push("Claude Code asks once before it uses a project's servers (or run `instruction
|
|
327
|
+
if (hosts.has("claude-code") && !o.fleet && !o.approve && nextOwned[mcpFile]?.length) result.notes.push("Claude Code asks once before it uses a project's servers (or run `instruction agents apply --approve` to approve them for yourself).");
|
|
328
328
|
if (hosts.has("codex") && !o.fleet && nextOwned[tomlFile]?.length) result.notes.push("Codex reads a project's .codex/config.toml once you trust the folder (it asks when you start it here).");
|
|
329
329
|
return { ...result, changed, applied };
|
|
330
330
|
}
|
package/dist/connect.js
CHANGED
|
@@ -31,7 +31,7 @@ function connectWithHooks(ctx, host, target, full, o) {
|
|
|
31
31
|
return void 0;
|
|
32
32
|
}
|
|
33
33
|
};
|
|
34
|
-
const already = (setup.alsoReads ?? []).find((f) => /instruction(\.md)? hook|instruction\.js hook|instruction
|
|
34
|
+
const already = (setup.alsoReads ?? []).find((f) => /instruction(\.md)? hook|instruction\.js hook|instruction agents hook|@instruction\.md\/agents hook/.test(read(join(o.dir, f)) ?? ""));
|
|
35
35
|
const files = already ? [] : setup.files;
|
|
36
36
|
const said = [
|
|
37
37
|
...already ? [`# ${host} also runs the hooks in ${already}, which already give this project's instruction: nothing more to add`] : [],
|
|
@@ -52,7 +52,7 @@ function connectWithHooks(ctx, host, target, full, o) {
|
|
|
52
52
|
...files.flatMap((f) => [`# ${f.path} — ${f.merge === "script" ? "an executable" : "merged into what is there"}`, typeof f.value === "string" ? f.value.replace(/\n$/, "") : JSON.stringify(f.value, null, 2), ``]),
|
|
53
53
|
...said.map((l) => `# ${l.replace(/\n/g, "\n# ")}`),
|
|
54
54
|
...setup.note ? [`# ${setup.note}`] : [],
|
|
55
|
-
...files.length ? [`# or let this write them: instruction
|
|
55
|
+
...files.length ? [`# or let this write them: instruction agents follow ${target} --host ${host} --write`] : []
|
|
56
56
|
].join("\n");
|
|
57
57
|
cliOut(ctx, text2, { host, uri: target, follow, setup: { files: files.map((f) => ({ path: f.path, merge: f.merge, value: f.value })), manual: setup.manual ?? null, note: setup.note }, files: { follow: followFile, hooks: files.map((f) => join(o.dir, f.path)) }, snippet });
|
|
58
58
|
return 0;
|
|
@@ -105,10 +105,10 @@ async function cmdConnect(args) {
|
|
|
105
105
|
const dir = resolve(take(args, "--dir") ?? process.cwd());
|
|
106
106
|
if (managed && !host && MANAGED_HOSTS.includes(args[0] ?? "")) host = args.shift();
|
|
107
107
|
const uri = args.shift();
|
|
108
|
-
if (!withHooks && !write && !managed) throw new CliError("instruction
|
|
108
|
+
if (!withHooks && !write && !managed) throw new CliError("instruction agents follow sets a project's hooks up (--write) or prints an organization's managed settings (--managed); for an MCP host's snippet: instruction connect --host HOST", 2);
|
|
109
109
|
if ((withHooks || write) && !HOOKED_HOSTS.includes(host)) throw new CliError(`--with-hooks and --write are for --host ${HOOKED_HOSTS.join(", ")}; another host follows a file instruction.md keeps (instruction connect --host ${host || "HOST"} says how)`, 2);
|
|
110
110
|
if (managed && !MANAGED_HOSTS.includes(host)) throw new CliError(`--managed is for --host ${MANAGED_HOSTS.join(" or ")}`, 2);
|
|
111
|
-
if (!uri) throw new CliError(`name the instruction to follow: instruction
|
|
111
|
+
if (!uri) throw new CliError(`name the instruction to follow: instruction agents follow <uri> --host ${host}${managed ? " --managed" : ""}`, 2);
|
|
112
112
|
if (managed && (write || withHooks)) throw new CliError("--managed prints an organization's settings, for an administrator to deploy; it writes nothing", 2);
|
|
113
113
|
const target = asUri(uri);
|
|
114
114
|
if (managed) {
|
|
@@ -120,7 +120,7 @@ async function cmdConnect(args) {
|
|
|
120
120
|
const code = connectWithHooks(ctx, host, target, s, { write, dir, cli, requireSignature, apply: !noApply });
|
|
121
121
|
if (code === 0 && write && !noApply && (host === "claude-code" || host === "codex") && await ctx.token()) {
|
|
122
122
|
const { cmdApply } = await import("./setup.js");
|
|
123
|
-
await cmdApply([target, "--host", host, "--dir", dir, "--cli", cli, "--url", ctx.url, ...ctx.given ? ["--token", ctx.given] : [], ...ctx.json ? ["--quiet"] : []]).catch((e) => console.error(`the instruction's servers and skills weren't written (${e instanceof Error ? e.message : String(e)}); run \`instruction
|
|
123
|
+
await cmdApply([target, "--host", host, "--dir", dir, "--cli", cli, "--url", ctx.url, ...ctx.given ? ["--token", ctx.given] : [], ...ctx.json ? ["--quiet"] : []]).catch((e) => console.error(`the instruction's servers and skills weren't written (${e instanceof Error ? e.message : String(e)}); run \`instruction agents apply\``));
|
|
124
124
|
}
|
|
125
125
|
return code;
|
|
126
126
|
}
|
package/dist/converse.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
// src/converse.ts
|
|
2
2
|
import { basename } from "node:path";
|
|
3
|
+
var SUBAGENT_TOOLS = /* @__PURE__ */ new Set(["Task", "Agent"]);
|
|
3
4
|
var VALUE_FLAGS = /* @__PURE__ */ new Set([
|
|
4
5
|
"--model",
|
|
5
6
|
"--fallback-model",
|
|
@@ -140,6 +141,8 @@ var ClaudeSession = class {
|
|
|
140
141
|
pending = /* @__PURE__ */ new Map();
|
|
141
142
|
ended = false;
|
|
142
143
|
lastSaid = "";
|
|
144
|
+
/** The subagents of its current task, the newest last (at most 20). */
|
|
145
|
+
subagents = [];
|
|
143
146
|
write(o) {
|
|
144
147
|
if (this.ended || !this.child.stdin || this.child.stdin.destroyed) return false;
|
|
145
148
|
try {
|
|
@@ -158,6 +161,10 @@ var ClaudeSession = class {
|
|
|
158
161
|
/** A user message: the task, or a person's words. */
|
|
159
162
|
say(text) {
|
|
160
163
|
this.busy = true;
|
|
164
|
+
if (this.subagents.some((x) => !x.running)) {
|
|
165
|
+
this.subagents = this.subagents.filter((x) => x.running);
|
|
166
|
+
this.hooks.subagents?.(this.subagents);
|
|
167
|
+
}
|
|
161
168
|
return this.write({ type: "user", message: { role: "user", content: text }, parent_tool_use_id: null, session_id: this.sessionId });
|
|
162
169
|
}
|
|
163
170
|
interrupt() {
|
|
@@ -170,6 +177,19 @@ var ClaudeSession = class {
|
|
|
170
177
|
} catch {
|
|
171
178
|
}
|
|
172
179
|
}
|
|
180
|
+
started(id, input) {
|
|
181
|
+
const i = input && typeof input === "object" ? input : {};
|
|
182
|
+
const said = (k) => typeof i[k] === "string" && i[k].trim() ? cut(maskText(i[k].trim().replace(/\s+/g, " ")), 110) : void 0;
|
|
183
|
+
const type = said("subagent_type");
|
|
184
|
+
this.subagents = [...this.subagents.filter((x) => x.id !== id), { id, name: said("description") ?? type ?? "A subagent", ...type ? { type } : {}, running: true }].slice(-20);
|
|
185
|
+
this.hooks.subagents?.(this.subagents);
|
|
186
|
+
}
|
|
187
|
+
finished(id) {
|
|
188
|
+
const x = this.subagents.find((y) => y.id === id);
|
|
189
|
+
if (!x || !x.running) return;
|
|
190
|
+
this.subagents = this.subagents.map((y) => y.id === id ? { ...y, running: false } : y);
|
|
191
|
+
this.hooks.subagents?.(this.subagents);
|
|
192
|
+
}
|
|
173
193
|
feed(s) {
|
|
174
194
|
this.buf += s;
|
|
175
195
|
let i;
|
|
@@ -190,15 +210,22 @@ var ClaudeSession = class {
|
|
|
190
210
|
on(m) {
|
|
191
211
|
if (m.type === "system" && m.subtype === "init" && typeof m.session_id === "string") this.sessionId = m.session_id;
|
|
192
212
|
else if (m.type === "assistant" && Array.isArray(m.message?.content)) {
|
|
193
|
-
|
|
213
|
+
const sub = typeof m.parent_tool_use_id === "string" && m.parent_tool_use_id ? m.parent_tool_use_id : void 0;
|
|
214
|
+
const of = sub ? { agent: sub } : {};
|
|
194
215
|
for (const b of m.message.content) {
|
|
195
216
|
if (b?.type === "text" && typeof b.text === "string" && b.text.trim()) {
|
|
196
|
-
this.lastSaid = b.text.trim();
|
|
197
|
-
this.hooks.line({ type: "said", text: cut(maskText(b.text.trim().replace(/\s+/g, " ")), 480) });
|
|
198
|
-
} else if (b?.type === "tool_use" && b.name !== "AskUserQuestion")
|
|
217
|
+
if (!sub) this.lastSaid = b.text.trim();
|
|
218
|
+
this.hooks.line({ type: "said", text: cut(maskText(b.text.trim().replace(/\s+/g, " ")), 480), ...of });
|
|
219
|
+
} else if (b?.type === "tool_use" && b.name !== "AskUserQuestion") {
|
|
220
|
+
this.hooks.line({ type: "ran", text: toolLine(String(b.name), b.input), ...of });
|
|
221
|
+
if (SUBAGENT_TOOLS.has(String(b.name)) && typeof b.id === "string") this.started(b.id, b.input);
|
|
222
|
+
}
|
|
199
223
|
}
|
|
224
|
+
} else if (m.type === "user" && Array.isArray(m.message?.content)) {
|
|
225
|
+
for (const b of m.message.content) if (b?.type === "tool_result" && typeof b.tool_use_id === "string") this.finished(b.tool_use_id);
|
|
200
226
|
} else if (m.type === "result") {
|
|
201
227
|
this.busy = false;
|
|
228
|
+
for (const x of this.subagents) if (x.running) this.finished(x.id);
|
|
202
229
|
const err = m.is_error === true || typeof m.subtype === "string" && m.subtype !== "success";
|
|
203
230
|
const said = !err && typeof m.result === "string" && m.result.trim() === this.lastSaid;
|
|
204
231
|
this.lastSaid = "";
|
package/dist/fleet.js
CHANGED
|
@@ -174,7 +174,7 @@ function claudeArgv(argv, folder) {
|
|
|
174
174
|
return out;
|
|
175
175
|
}
|
|
176
176
|
var STATE_FILE = ".instruction-fleet.json";
|
|
177
|
-
var HOST_FIX = { "claude-code": "claude setup-token, then: instruction
|
|
177
|
+
var HOST_FIX = { "claude-code": "claude setup-token, then: instruction agents accounts host claude-code --env CLAUDE_CODE_OAUTH_TOKEN --from-command '<your secret store>'", codex: "codex login --device-auth (or: instruction agents accounts host codex --env CODEX_API_KEY --from-command '<your secret store>')" };
|
|
178
178
|
var STDERR_LINES = 20;
|
|
179
179
|
var Fleet = class {
|
|
180
180
|
constructor(client, o) {
|
|
@@ -347,7 +347,8 @@ var Fleet = class {
|
|
|
347
347
|
idle: () => {
|
|
348
348
|
if (this.onceMode) a.session?.end();
|
|
349
349
|
},
|
|
350
|
-
decide: (req, signal) => this.decide(a, req, signal)
|
|
350
|
+
decide: (req, signal) => this.decide(a, req, signal),
|
|
351
|
+
subagents: () => void this.reportOne(a.d.id, this.reportFor(a))
|
|
351
352
|
});
|
|
352
353
|
a.session.begin(conv.prompt);
|
|
353
354
|
} else child.stdout?.on("data", (c) => keep(c, false));
|
|
@@ -503,7 +504,8 @@ var Fleet = class {
|
|
|
503
504
|
...v ? { versionId: v } : {},
|
|
504
505
|
health: signIn ? "needs_sign_in" : failed ? "failed" : "ok",
|
|
505
506
|
...failed ? { error: (a.stderr.slice(-5).join("\n") || `exited (${a.exitSignal ?? `code ${a.exitCode}`})`).slice(0, 2e3) } : {},
|
|
506
|
-
...signIn && app ? { needs: [{ kind: "host", name: app, what: signIn.slice(0, 300), fix: HOST_FIX[app] }] } : {}
|
|
507
|
+
...signIn && app ? { needs: [{ kind: "host", name: app, what: signIn.slice(0, 300), fix: HOST_FIX[app] }] } : {},
|
|
508
|
+
...a.session ? { subagents: alive ? a.session.subagents : [] } : {}
|
|
507
509
|
};
|
|
508
510
|
}
|
|
509
511
|
async reportAll() {
|
|
@@ -856,7 +858,7 @@ function registryFleetClient(c, q, log = (l) => process.stderr.write(`${l}
|
|
|
856
858
|
}
|
|
857
859
|
},
|
|
858
860
|
async report(r) {
|
|
859
|
-
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 } : {} });
|
|
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 } : {} });
|
|
860
862
|
},
|
|
861
863
|
converse: {
|
|
862
864
|
async ask(card) {
|
|
@@ -891,7 +893,7 @@ function registryFleetClient(c, q, log = (l) => process.stderr.write(`${l}
|
|
|
891
893
|
}
|
|
892
894
|
};
|
|
893
895
|
}
|
|
894
|
-
var FLEET_USAGE = "usage: instruction
|
|
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…>";
|
|
895
897
|
function take(args, flag) {
|
|
896
898
|
const i = args.indexOf(flag);
|
|
897
899
|
if (i < 0) return void 0;
|
|
@@ -931,7 +933,7 @@ async function cmdFleet(argv) {
|
|
|
931
933
|
process.env.INSTRUCTION_MD_CLIENT_NAME ??= `instruction-md-cli fleet@${hostname()}`;
|
|
932
934
|
const conn = await registryConnection([...url ? ["--url", url] : [], ...token ? ["--token", token] : []]);
|
|
933
935
|
if (!conn) {
|
|
934
|
-
console.error("instruction
|
|
936
|
+
console.error("instruction agents run reads your organization's deployments: sign in first (`instruction agents login`, or --token)");
|
|
935
937
|
return 3;
|
|
936
938
|
}
|
|
937
939
|
let orgId;
|
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.
|
|
8
|
+
var version = "0.3.0";
|
|
9
9
|
|
|
10
10
|
// src/hook.ts
|
|
11
11
|
import {
|
|
@@ -288,7 +288,7 @@ function has(args, flag) {
|
|
|
288
288
|
args.splice(i, 1);
|
|
289
289
|
return true;
|
|
290
290
|
}
|
|
291
|
-
var HOOK_USAGE = `usage: instruction
|
|
291
|
+
var HOOK_USAGE = `usage: instruction agents hook ${HOOK_HOST_IDS.join("|")}|auto [--event NAME] [--fail-closed] [--dir D] [--follow URI [--require-signature]] [--url U]`;
|
|
292
292
|
function hostOf(event, env) {
|
|
293
293
|
return appOf(event, env) === "codex" ? "codex" : "claude-code";
|
|
294
294
|
}
|
|
@@ -387,7 +387,7 @@ async function cmdHook(args) {
|
|
|
387
387
|
else if (out) process.stdout.write(`${JSON.stringify(out)}
|
|
388
388
|
`);
|
|
389
389
|
} catch (e) {
|
|
390
|
-
console.error(`instruction
|
|
390
|
+
console.error(`instruction agents hook: ${e instanceof Error ? e.message : String(e)}`);
|
|
391
391
|
}
|
|
392
392
|
return 0;
|
|
393
393
|
}
|
package/dist/main.js
CHANGED
|
@@ -1,42 +1,31 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// package.json
|
|
3
3
|
var name = "@instruction.md/agents";
|
|
4
|
-
var version = "0.
|
|
4
|
+
var version = "0.3.0";
|
|
5
5
|
|
|
6
6
|
// src/main.ts
|
|
7
7
|
import { cmdHook } from "./hook.js";
|
|
8
|
-
var USAGE = `instruction
|
|
8
|
+
var USAGE = `instruction agents — run agents with instruction.md (${name} ${version})
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
instruction
|
|
15
|
-
a project follows <uri>: .instruction/follow.json and
|
|
16
|
-
|
|
17
|
-
into the project, merged into what is there. HOST:
|
|
18
|
-
codex, qwen-code, droid, devin, gemini-cli,
|
|
19
|
-
copilot, cursor, cline, crush (kiro, junie: said
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
instruction
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
--event: the event, for a host that doesn't name it on stdin;
|
|
30
|
-
auto: the host told from the event and its environment
|
|
31
|
-
instruction-agents acp [--follow URI [--require-signature]] [--url U] [--no-bridge] -- <agent command…>
|
|
32
|
-
an ACP proxy (Zed, JetBrains): runs the agent; a session's
|
|
33
|
-
system prompt carries the instruction where the agent takes
|
|
34
|
-
one (else its first prompt), a new version at the next prompt,
|
|
35
|
-
and the instruction mcp bridge among its MCP servers
|
|
36
|
-
instruction-agents turn <app> --session ID [--start [--source S]] [--cwd D] [--follow URI]
|
|
37
|
-
one turn for a plugin that runs a command (Amp's): JSON
|
|
38
|
-
{context, notice} on stdout, or nothing; exit 0 even offline
|
|
39
|
-
instruction-agents fleet (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run]
|
|
10
|
+
The same commands run as \`instruction agents <command>\` (the instruction.md package), \`instruction-agents <command>\` or
|
|
11
|
+
\`npx @instruction.md/agents <command>\`. --host is always the agent's app (claude-code, codex, …); --as what it becomes.
|
|
12
|
+
|
|
13
|
+
People run
|
|
14
|
+
instruction agents follow <uri> --host HOST [--write] [--require-signature] [--dir D] [--cli CMD] [--no-apply]
|
|
15
|
+
a project's agent follows <uri>: .instruction/follow.json and
|
|
16
|
+
the app's hooks (instruction agents hook), printed, or --write:
|
|
17
|
+
written into the project, merged into what is there. HOST:
|
|
18
|
+
claude-code, codex, qwen-code, droid, devin, gemini-cli,
|
|
19
|
+
antigravity, copilot, cursor, cline, crush (kiro, junie: said
|
|
20
|
+
how, by hand)
|
|
21
|
+
instruction agents follow <uri> --host claude-code|codex --managed
|
|
22
|
+
the organization-wide settings for an administrator (Claude
|
|
23
|
+
Code managed-settings.json, Codex requirements.toml)
|
|
24
|
+
instruction agents install [<uri>] --host claude-code|codex --as agent|skill [--name N] [--dir D] [--force]
|
|
25
|
+
an instruction as the app's own file: a Claude Code agent
|
|
26
|
+
(.claude/agents/) or skill (.claude/skills/), a Codex skill
|
|
27
|
+
(.agents/skills/); again to take a new version
|
|
28
|
+
instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run]
|
|
40
29
|
[--restart-on-exit] [--clean] [--host APP] -- <command…>
|
|
41
30
|
an agent per instruction (RFC-0042 §10): runs the command once
|
|
42
31
|
per active deployment of a rule or a platform, each in a folder
|
|
@@ -46,33 +35,51 @@ var USAGE = `instruction-agents — run agents with instruction.md (${name} ${ve
|
|
|
46
35
|
maxAgents; reports each. {instruction} {name} {dir} in the
|
|
47
36
|
command are replaced. --once: one pass, waiting for each
|
|
48
37
|
command to end (a cron job); --dry-run: what it would do
|
|
49
|
-
instruction
|
|
50
|
-
write the instruction's MCP servers and skills into the
|
|
38
|
+
instruction agents apply [<uri>] [--host claude-code|codex|both] [--approve] [--dry-run] [--remove] [--dir D] [--cli CMD]
|
|
39
|
+
write the instruction's MCP servers and skills into the app's
|
|
51
40
|
own files (.mcp.json, .claude/skills/, .codex/config.toml,
|
|
52
|
-
.agents/skills/), its allowed and denied tools as the
|
|
41
|
+
.agents/skills/), its allowed and denied tools as the app's
|
|
53
42
|
rules; only its own entries are changed or removed
|
|
54
43
|
(.instruction/applied.json); --approve: Claude Code uses the
|
|
55
44
|
servers without asking you
|
|
56
|
-
instruction
|
|
45
|
+
instruction agents check [--host claude-code|codex|both] [--fleet] [--no-probe] [--json]
|
|
57
46
|
what stops the agent, each with its fix: instruction.md's
|
|
58
|
-
sign-in, the
|
|
47
|
+
sign-in, the app's own (Claude Code, Codex), each server's
|
|
59
48
|
account on this machine; exit 1 when something does
|
|
60
|
-
instruction
|
|
49
|
+
instruction agents accounts [list | set <server[@account]> --env VAR | --command CMD | --oauth | --xaa-idp URL … | host <app> --env VAR
|
|
61
50
|
(--from-env V | --from-command C) | remove <server[@account]>]
|
|
62
|
-
what an instruction's
|
|
51
|
+
what an instruction's \`account\` means on this machine
|
|
63
52
|
(~/.config/instruction-md/accounts.json): a variable, a command
|
|
64
53
|
(your organization's secret store), a sign-in, or your identity
|
|
65
54
|
provider (XAA); never a value printed
|
|
66
|
-
instruction
|
|
55
|
+
instruction agents signin <server> --url U [--account A] [--device] [--no-browser]
|
|
67
56
|
sign this machine in to an MCP server (OAuth): a browser here,
|
|
68
57
|
a code on any device (--device), or the address pasted back
|
|
69
|
-
instruction
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
instruction
|
|
74
|
-
|
|
75
|
-
|
|
58
|
+
instruction agents login [--device] [--no-browser] [--url U] sign in to instruction.md (the same sign-in as \`instruction login\`)
|
|
59
|
+
instruction agents whoami who the server says you are
|
|
60
|
+
|
|
61
|
+
The agent's app runs
|
|
62
|
+
instruction agents hook HOST|auto [--event NAME] [--fail-closed] [--follow URI [--require-signature]] [--dir D]
|
|
63
|
+
the app's hooks: the event on stdin; the project's instruction
|
|
64
|
+
at a session's start, a new version at the next prompt, nothing
|
|
65
|
+
when nothing changed; exit 0 even offline. HOST: claude-code,
|
|
66
|
+
codex, qwen-code, droid, devin, gemini-cli, antigravity, copilot,
|
|
67
|
+
cursor, kiro, cline, junie, crush, goose; --event: the event, for
|
|
68
|
+
an app that doesn't name it on stdin; auto: told from the event
|
|
69
|
+
instruction agents acp [--follow URI [--require-signature]] [--url U] [--no-bridge] -- <agent command…>
|
|
70
|
+
an ACP proxy (Zed, JetBrains): runs the agent; a session's
|
|
71
|
+
system prompt carries the instruction where the agent takes
|
|
72
|
+
one (else its first prompt), a new version at the next prompt,
|
|
73
|
+
and the instruction mcp bridge among its MCP servers
|
|
74
|
+
instruction agents turn <app> --session ID [--start [--source S]] [--cwd D] [--follow URI]
|
|
75
|
+
one turn for a plugin that runs a command (Amp's): JSON
|
|
76
|
+
{context, notice} on stdout, or nothing; exit 0 even offline
|
|
77
|
+
instruction agents credential <server> [--account A] [--url U] the headers for a server, as JSON (Claude Code's
|
|
78
|
+
headersHelper, Codex's http_headers_helper)
|
|
79
|
+
instruction agents mcp … instruction.md's stdio MCP server (instruction mcp)
|
|
80
|
+
|
|
81
|
+
Earlier names still work: connect --with-hooks (follow), sync --as claude-agent|claude-skill|codex-skill (install),
|
|
82
|
+
fleet (run), doctor (check).
|
|
76
83
|
|
|
77
84
|
Writing, checking and releasing instructions: the \`instruction\` command (npm i -g instruction.md).`;
|
|
78
85
|
var commands = {
|
|
@@ -82,6 +89,12 @@ var commands = {
|
|
|
82
89
|
sync: async (a) => (await import("./connect.js")).cmdSync(a),
|
|
83
90
|
connect: async (a) => (await import("./connect.js")).cmdConnect(a),
|
|
84
91
|
fleet: async (a) => (await import("./fleet.js")).cmdFleet(a),
|
|
92
|
+
// (the names people type, the owner 2026-11-21: "aligned with agents word so command becomes more obvious";
|
|
93
|
+
// connect, sync, fleet and doctor stay, for hook settings, scripts and docs written before)
|
|
94
|
+
follow: async (a) => (await import("./connect.js")).cmdConnect(a.includes("--managed") || a.includes("--with-hooks") ? a : [...a, "--with-hooks"]),
|
|
95
|
+
install: async (a) => (await import("./connect.js")).cmdSync(a),
|
|
96
|
+
run: async (a) => (await import("./fleet.js")).cmdFleet(a),
|
|
97
|
+
check: async (a) => (await import("./setup.js")).cmdDoctor(a),
|
|
85
98
|
apply: async (a) => (await import("./setup.js")).cmdApply(a),
|
|
86
99
|
doctor: async (a) => (await import("./setup.js")).cmdDoctor(a),
|
|
87
100
|
accounts: async (a) => (await import("./accounts.js")).cmdAccounts(a),
|
package/dist/oauth.js
CHANGED
|
@@ -106,7 +106,7 @@ async function asksForSignIn(url, f = fetch, headers = {}) {
|
|
|
106
106
|
async function clientFor(m, redirectUri, o = {}) {
|
|
107
107
|
if (o.clientId) return { client_id: o.clientId, ...o.clientSecret ? { client_secret: o.clientSecret } : {} };
|
|
108
108
|
if (m.client_id_metadata_document_supported) return { client_id: CIMD_URL };
|
|
109
|
-
if (!m.registration_endpoint) throw new OAuthError(`${clean(m.issuer)} offers no way for the CLI to register (no client metadata documents, no dynamic registration): ask its administrator for a client id, then run \`instruction
|
|
109
|
+
if (!m.registration_endpoint) throw new OAuthError(`${clean(m.issuer)} offers no way for the CLI to register (no client metadata documents, no dynamic registration): ask its administrator for a client id, then run \`instruction agents signin … --client-id ID\`.`, 2);
|
|
110
110
|
const grants = ["authorization_code", "refresh_token", ...m.device_authorization_endpoint ? ["urn:ietf:params:oauth:grant-type:device_code"] : []];
|
|
111
111
|
const r = await (o.f ?? fetch)(m.registration_endpoint, {
|
|
112
112
|
method: "POST",
|
|
@@ -122,7 +122,7 @@ var clientAuth = (c) => c.client_secret ? { body: {}, headers: { authorization:
|
|
|
122
122
|
async function signIn(o) {
|
|
123
123
|
const f = o.f ?? fetch;
|
|
124
124
|
const found = await signInServiceOf(o.url, f);
|
|
125
|
-
if (!found) throw new OAuthError(`${clean(o.url)} describes no sign-in (no protected-resource metadata): it may take a key instead — \`instruction
|
|
125
|
+
if (!found) throw new OAuthError(`${clean(o.url)} describes no sign-in (no protected-resource metadata): it may take a key instead — \`instruction agents accounts set <server> --env VAR\`.`, 2);
|
|
126
126
|
const { resource, server } = found;
|
|
127
127
|
const scope = o.scope ?? resource.scopes_supported?.join(" ") ?? "";
|
|
128
128
|
if (o.device) return deviceGrant(o, server, resource.resource, scope);
|
|
@@ -131,7 +131,7 @@ async function signIn(o) {
|
|
|
131
131
|
async function deviceGrant(o, m, resource, scope) {
|
|
132
132
|
const f = o.f ?? fetch, log = o.log ?? ((l) => console.error(l));
|
|
133
133
|
const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))), now = o.now ?? Date.now;
|
|
134
|
-
if (!m.device_authorization_endpoint) throw new OAuthError(`${clean(m.issuer)} doesn't offer signing in with a code. Run \`instruction
|
|
134
|
+
if (!m.device_authorization_endpoint) throw new OAuthError(`${clean(m.issuer)} doesn't offer signing in with a code. Run \`instruction agents signin\` without --device: open the link on any device and paste back the address you end on.`, 2);
|
|
135
135
|
const c = await clientFor(m, null, { ...o, f });
|
|
136
136
|
const auth = clientAuth(c);
|
|
137
137
|
const { verifier, challenge } = pkce();
|
|
@@ -165,7 +165,7 @@ async function deviceGrant(o, m, resource, scope) {
|
|
|
165
165
|
}
|
|
166
166
|
throw new OAuthError(`The sign-in didn't finish (${why(tj, t.status)}).`, tj.error === "access_denied" ? 7 : 1);
|
|
167
167
|
}
|
|
168
|
-
throw new OAuthError("The code expired before it was approved. Run `instruction
|
|
168
|
+
throw new OAuthError("The code expired before it was approved. Run `instruction agents signin` again.", 3);
|
|
169
169
|
}
|
|
170
170
|
function send(res, status, html) {
|
|
171
171
|
res.writeHead(status, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff", connection: "close" });
|
|
@@ -215,7 +215,7 @@ async function codeGrant(o, m, resource, scope) {
|
|
|
215
215
|
if (e) reject(e);
|
|
216
216
|
else resolve(t);
|
|
217
217
|
};
|
|
218
|
-
const timer = setTimeout(() => finish(new OAuthError(`Nothing came back in ${Math.round(timeoutMs / 6e4)} minutes. Run \`instruction
|
|
218
|
+
const timer = setTimeout(() => finish(new OAuthError(`Nothing came back in ${Math.round(timeoutMs / 6e4)} minutes. Run \`instruction agents signin\` again.`, 3)), timeoutMs);
|
|
219
219
|
timer.unref?.();
|
|
220
220
|
const take = async (u, res) => {
|
|
221
221
|
if (!sameState(u.searchParams.get("state"))) {
|
package/dist/setup.js
CHANGED
|
@@ -66,7 +66,7 @@ function hostsOf(v, fallback) {
|
|
|
66
66
|
for (const h of list) if (!APPLY_HOSTS.includes(h)) throw new Error(`--host is ${APPLY_HOSTS.join(", ")} or both, not ${h}`);
|
|
67
67
|
return [...new Set(list)];
|
|
68
68
|
}
|
|
69
|
-
var APPLY_USAGE = "usage: instruction
|
|
69
|
+
var APPLY_USAGE = "usage: instruction agents apply [<uri>] [--host claude-code|codex|both] [--dir D] [--approve] [--dry-run] [--remove] [--cli CMD] [--if-changed] [--quiet] [--note] [--json]";
|
|
70
70
|
async function cmdApply(argv) {
|
|
71
71
|
const args = [...argv];
|
|
72
72
|
const json = has(args, "--json"), approve = has(args, "--approve"), dryRun = has(args, "--dry-run"), remove = has(args, "--remove"), ifChanged = has(args, "--if-changed"), quiet = has(args, "--quiet"), note = has(args, "--note");
|
|
@@ -105,14 +105,14 @@ not understood: ${args.join(" ")}`);
|
|
|
105
105
|
}
|
|
106
106
|
const follow = uri ?? found?.config.follow;
|
|
107
107
|
if (!follow) {
|
|
108
|
-
console.error(`name the instruction (instruction
|
|
108
|
+
console.error(`name the instruction (instruction agents apply owner/name), or run it in a project that follows one (.instruction/follow.json)
|
|
109
109
|
${APPLY_USAGE}`);
|
|
110
110
|
return 2;
|
|
111
111
|
}
|
|
112
112
|
const { registryConnection } = await import("instruction.md/cli/registry");
|
|
113
113
|
const c = await registryConnection([...conn[0] ? ["--url", conn[0]] : found?.config.url ? ["--url", found.config.url] : [], ...conn[1] ? ["--token", conn[1]] : []]);
|
|
114
114
|
if (!c) {
|
|
115
|
-
console.error("instruction
|
|
115
|
+
console.error("instruction agents apply reads the instruction from instruction.md: sign in first (`instruction agents login`, or --token)");
|
|
116
116
|
return 3;
|
|
117
117
|
}
|
|
118
118
|
try {
|
|
@@ -141,7 +141,7 @@ ${APPLY_USAGE}`);
|
|
|
141
141
|
if (!r.wrote.length && !r.removed.length) say("nothing to change");
|
|
142
142
|
for (const n of r.notes) say(n);
|
|
143
143
|
const unbound = src.machinery.servers.filter((s) => s.account && !entryFor(loadAccounts(), s.id, s.account));
|
|
144
|
-
if (unbound.length) say(`On this machine, say what ${unbound.map((s) => `${s.id}'s account "${s.account}"`).join(", ")} means: instruction
|
|
144
|
+
if (unbound.length) say(`On this machine, say what ${unbound.map((s) => `${s.id}'s account "${s.account}"`).join(", ")} means: instruction agents accounts set ${unbound[0].id}@${unbound[0].account} --env VAR (or --command, or instruction agents signin ${unbound[0].id} --account ${unbound[0].account})`);
|
|
145
145
|
return 0;
|
|
146
146
|
} finally {
|
|
147
147
|
await c.client.close().catch(() => {
|
|
@@ -155,7 +155,7 @@ var runCmd = (cmd, args, env) => {
|
|
|
155
155
|
var HOST_BIN = { "claude-code": "claude", codex: "codex" };
|
|
156
156
|
var HOST_VARS = { "claude-code": ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"], codex: ["CODEX_API_KEY", "OPENAI_API_KEY", "CODEX_ACCESS_TOKEN"] };
|
|
157
157
|
var HOST_LABEL = { "claude-code": "Claude Code", codex: "Codex" };
|
|
158
|
-
var HOST_SIGNIN = { "claude-code": "claude auth login (or, for a machine with no browser, claude setup-token, then instruction
|
|
158
|
+
var HOST_SIGNIN = { "claude-code": "claude auth login (or, for a machine with no browser, claude setup-token, then instruction agents accounts host claude-code --env CLAUDE_CODE_OAUTH_TOKEN --from-command …)", codex: "codex login --device-auth (or printenv OPENAI_API_KEY | codex login --with-api-key)" };
|
|
159
159
|
async function checkSetup(o) {
|
|
160
160
|
const env = o.env ?? process.env, run = o.run ?? runCmd, accounts = o.accounts ?? loadAccounts();
|
|
161
161
|
const out = [];
|
|
@@ -227,13 +227,13 @@ async function checkSetup(o) {
|
|
|
227
227
|
return s.url;
|
|
228
228
|
}
|
|
229
229
|
})();
|
|
230
|
-
const signinFix = `instruction
|
|
230
|
+
const signinFix = `instruction agents signin ${s.id}${s.account ? ` --account ${s.account}` : ""} --url ${s.url}`;
|
|
231
231
|
if (p.status === 0) {
|
|
232
232
|
out.push({ kind: "server", name: s.id, ...s.account ? { account: s.account } : {}, level: "warn", what: `${key}: ${host} didn't answer (${p.error ?? "no answer"})` });
|
|
233
233
|
continue;
|
|
234
234
|
}
|
|
235
235
|
if (found) {
|
|
236
|
-
if (p.asks) out.push({ kind: "server", name: s.id, ...s.account ? { account: s.account } : {}, level: "block", what: `${key}: ${host} refused this machine's credential (HTTP ${p.status})`, fix: found.entry.oauth ? signinFix : `check what instruction
|
|
236
|
+
if (p.asks) out.push({ kind: "server", name: s.id, ...s.account ? { account: s.account } : {}, level: "block", what: `${key}: ${host} refused this machine's credential (HTTP ${p.status})`, fix: found.entry.oauth ? signinFix : `check what instruction agents accounts says for ${found.key}` });
|
|
237
237
|
else out.push({ kind: "server", name: s.id, ...s.account ? { account: s.account } : {}, level: "ok", what: `${key}: ${host} takes this machine's credential` });
|
|
238
238
|
continue;
|
|
239
239
|
}
|
|
@@ -247,14 +247,14 @@ async function checkSetup(o) {
|
|
|
247
247
|
...s.account ? { account: s.account } : {},
|
|
248
248
|
level: o.unattended ? "block" : "warn",
|
|
249
249
|
what: o.unattended ? `${key}: ${host} needs a sign-in, and nobody is here to give it` : `${key}: ${host} needs a sign-in — the agent's app will ask you${s.account ? ` (the instruction asks for the account "${s.account}")` : ""}`,
|
|
250
|
-
fix: s.account ? `${signinFix} (or: instruction
|
|
250
|
+
fix: s.account ? `${signinFix} (or: instruction agents accounts set ${key} --env VAR | --command CMD)` : signinFix
|
|
251
251
|
});
|
|
252
252
|
}
|
|
253
253
|
return out;
|
|
254
254
|
}
|
|
255
255
|
var needsOf = (f) => f.filter((x) => x.level === "block").map((x) => ({ kind: x.kind, name: x.name, ...x.account ? { account: x.account } : {}, what: x.what.slice(0, 300), ...x.fix ? { fix: x.fix.slice(0, 300) } : {} }));
|
|
256
256
|
var MARK = { ok: "✓", warn: "!", block: "✗" };
|
|
257
|
-
var DOCTOR_USAGE = "usage: instruction
|
|
257
|
+
var DOCTOR_USAGE = "usage: instruction agents check [--host claude-code|codex|both] [--dir D] [--fleet] [--no-probe] [--json]";
|
|
258
258
|
async function cmdDoctor(argv) {
|
|
259
259
|
const args = [...argv];
|
|
260
260
|
const json = has(args, "--json"), unattended = has(args, "--fleet"), noProbe = has(args, "--no-probe");
|
|
@@ -278,15 +278,15 @@ async function cmdDoctor(argv) {
|
|
|
278
278
|
let servers = applied?.servers ?? [];
|
|
279
279
|
const { registryConnection } = await import("instruction.md/cli/registry");
|
|
280
280
|
const c = await registryConnection([...conn[0] ? ["--url", conn[0]] : found?.config.url ? ["--url", found.config.url] : [], ...conn[1] ? ["--token", conn[1]] : []]).catch(() => null);
|
|
281
|
-
if (!c) findings.push({ kind: "instruction-md", name: "instruction.md", level: found ? "block" : "warn", what: "not signed in to instruction.md", fix: "instruction
|
|
281
|
+
if (!c) findings.push({ kind: "instruction-md", name: "instruction.md", level: found ? "block" : "warn", what: "not signed in to instruction.md", fix: "instruction agents login (instruction agents login --device on a machine with no browser), or INSTRUCTION_MD_TOKEN" });
|
|
282
282
|
else {
|
|
283
283
|
try {
|
|
284
284
|
if (found) {
|
|
285
285
|
const src = await machinerySource(c, found.config.follow);
|
|
286
286
|
findings.push({ kind: "instruction-md", name: "instruction.md", level: "ok", what: `signed in; this project follows ${src.label}${src.version ? ` (v${src.version})` : ""}` });
|
|
287
287
|
if (!applied) servers = src.machinery.servers.map((s) => ({ id: s.id, url: s.url, ...s.account ? { account: s.account } : {} }));
|
|
288
|
-
if (applied && applied.digest !== src.machinery.digest) findings.push({ kind: "instruction-md", name: "instruction.md", level: "warn", what: `the servers and skills written here are an earlier version's`, fix: "instruction
|
|
289
|
-
if (!applied && (src.machinery.servers.length || src.machinery.skills.length)) findings.push({ kind: "instruction-md", name: "instruction.md", level: "warn", what: `the instruction's ${src.machinery.servers.length} server(s) and ${src.machinery.skills.length} skill(s) aren't written here yet`, fix: `instruction
|
|
288
|
+
if (applied && applied.digest !== src.machinery.digest) findings.push({ kind: "instruction-md", name: "instruction.md", level: "warn", what: `the servers and skills written here are an earlier version's`, fix: "instruction agents apply" });
|
|
289
|
+
if (!applied && (src.machinery.servers.length || src.machinery.skills.length)) findings.push({ kind: "instruction-md", name: "instruction.md", level: "warn", what: `the instruction's ${src.machinery.servers.length} server(s) and ${src.machinery.skills.length} skill(s) aren't written here yet`, fix: `instruction agents apply --host ${hosts.join(",")}` });
|
|
290
290
|
} else findings.push({ kind: "instruction-md", name: "instruction.md", level: "ok", what: "signed in (no project here follows an instruction)" });
|
|
291
291
|
} catch (e) {
|
|
292
292
|
findings.push({ kind: "instruction-md", name: "instruction.md", level: "block", what: `the followed instruction can't be read: ${e.message}` });
|
|
@@ -303,7 +303,7 @@ async function cmdDoctor(argv) {
|
|
|
303
303
|
}
|
|
304
304
|
for (const f of findings) console.log(`${MARK[f.level]} ${f.what}${f.fix ? `
|
|
305
305
|
fix: ${f.fix}` : ""}`);
|
|
306
|
-
console.log(blocked ? "\nSomething above stops the agent: fix it, then run `instruction
|
|
306
|
+
console.log(blocked ? "\nSomething above stops the agent: fix it, then run `instruction agents check` again." : "\nNothing stops the agent.");
|
|
307
307
|
return blocked ? 1 : 0;
|
|
308
308
|
}
|
|
309
309
|
function signInFailure(lines) {
|
package/dist/sync.js
CHANGED
|
@@ -21,7 +21,7 @@ name: ${name}
|
|
|
21
21
|
description: ${JSON.stringify(syncDescription(c))}
|
|
22
22
|
---
|
|
23
23
|
`;
|
|
24
|
-
const mark = `${SYNC_MARK} ${c.uri} v${c.version} ${c.digest} — written by \`instruction
|
|
24
|
+
const mark = `${SYNC_MARK} ${c.uri} v${c.version} ${c.digest} — written by \`instruction agents install --host ${target.startsWith("codex") ? "codex" : "claude-code"} --as ${target.endsWith("agent") ? "agent" : "skill"}\`; changed here, it is replaced on the next sync -->
|
|
25
25
|
`;
|
|
26
26
|
return `${front}${mark}
|
|
27
27
|
${c.text.replace(/\s+$/, "")}
|
|
@@ -50,7 +50,14 @@ var SyncError = class extends Error {
|
|
|
50
50
|
this.code = code;
|
|
51
51
|
}
|
|
52
52
|
};
|
|
53
|
-
var USAGE = "usage: instruction
|
|
53
|
+
var USAGE = "usage: instruction agents install [<uri>] --host claude-code|codex --as agent|skill [--name N] [--dir D] [--force]\n (Claude Code: an agent, .claude/agents/, or a skill, .claude/skills/; Codex: a skill, .agents/skills/)";
|
|
54
|
+
function syncTargetOf(host, as) {
|
|
55
|
+
if (as && SYNC_TARGETS.includes(as)) return as;
|
|
56
|
+
if (host === "claude-code" && as === "agent") return "claude-agent";
|
|
57
|
+
if (host === "claude-code" && as === "skill") return "claude-skill";
|
|
58
|
+
if (host === "codex" && as === "skill") return "codex-skill";
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
54
61
|
var take = (args, flag) => {
|
|
55
62
|
const i = args.indexOf(flag);
|
|
56
63
|
if (i < 0) return void 0;
|
|
@@ -65,11 +72,13 @@ var has = (args, flag) => {
|
|
|
65
72
|
return true;
|
|
66
73
|
};
|
|
67
74
|
async function cmdSync(args, connect) {
|
|
68
|
-
const
|
|
75
|
+
const host = take(args, "--host"), kind = take(args, "--as");
|
|
69
76
|
const nameArg = take(args, "--name");
|
|
70
77
|
const dirArg = take(args, "--dir");
|
|
71
78
|
const force = has(args, "--force");
|
|
72
|
-
|
|
79
|
+
const as = syncTargetOf(host, kind);
|
|
80
|
+
if (!as) throw new SyncError(host === "codex" && kind === "agent" ? `Codex has no subagent files: --host codex --as skill
|
|
81
|
+
${USAGE}` : USAGE, 2);
|
|
73
82
|
const project = findFollow(dirArg ? resolve(dirArg) : process.cwd());
|
|
74
83
|
const json = args.includes("--json");
|
|
75
84
|
let remote = null, unreachable = null;
|
|
@@ -90,7 +99,7 @@ async function cmdSync(args, connect) {
|
|
|
90
99
|
c = await readOnce(uri, { reader: followerReader(remote.client, policy), deadlineMs: 15e3 });
|
|
91
100
|
} else if (same) c = readCurrent(project.dir);
|
|
92
101
|
if (!c && unreachable) throw unreachable;
|
|
93
|
-
if (!c) throw new SyncError(`${uri}: not signed in, and nothing of it is cached here — run \`instruction
|
|
102
|
+
if (!c) throw new SyncError(`${uri}: not signed in, and nothing of it is cached here — run \`instruction agents login\` (or pass --token)`, 3);
|
|
94
103
|
const dir = dirArg ? resolve(dirArg) : project?.root ?? process.cwd();
|
|
95
104
|
const name = syncName(nameArg ?? namePartsOf(c).name ?? uri.replace(/^instruction:\/\//, "").split("@")[0].split("/").pop() ?? "instruction");
|
|
96
105
|
const r = writeSync(dir, as, c, name, force);
|
|
@@ -109,6 +118,7 @@ export {
|
|
|
109
118
|
syncFile,
|
|
110
119
|
syncName,
|
|
111
120
|
syncPath,
|
|
121
|
+
syncTargetOf,
|
|
112
122
|
syncedFrom,
|
|
113
123
|
writeSync
|
|
114
124
|
};
|
package/dist/turns.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@instruction.md/agents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.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",
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
},
|
|
56
56
|
"dependencies": {
|
|
57
57
|
"jose": "^5.9.6",
|
|
58
|
-
"instruction.md": "^0.10.
|
|
58
|
+
"instruction.md": "^0.10.2"
|
|
59
59
|
},
|
|
60
60
|
"devDependencies": {
|
|
61
61
|
"@modelcontextprotocol/sdk": "^1.32.0",
|