@stigmer/cli 0.1.3 → 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.
Files changed (270) hide show
  1. package/auth/browser.d.ts +7 -0
  2. package/auth/browser.d.ts.map +1 -0
  3. package/auth/browser.js +49 -0
  4. package/auth/browser.js.map +1 -0
  5. package/auth/callback-server.d.ts +8 -3
  6. package/auth/callback-server.d.ts.map +1 -1
  7. package/auth/callback-server.js +53 -19
  8. package/auth/callback-server.js.map +1 -1
  9. package/auth/device.d.ts +23 -0
  10. package/auth/device.d.ts.map +1 -0
  11. package/auth/device.js +119 -0
  12. package/auth/device.js.map +1 -0
  13. package/auth/index.d.ts +4 -3
  14. package/auth/index.d.ts.map +1 -1
  15. package/auth/index.js +4 -3
  16. package/auth/index.js.map +1 -1
  17. package/auth/login.d.ts +49 -1
  18. package/auth/login.d.ts.map +1 -1
  19. package/auth/login.js +161 -51
  20. package/auth/login.js.map +1 -1
  21. package/auth/oidc.d.ts +67 -0
  22. package/auth/oidc.d.ts.map +1 -0
  23. package/auth/oidc.js +213 -0
  24. package/auth/oidc.js.map +1 -0
  25. package/auth/token.d.ts +17 -23
  26. package/auth/token.d.ts.map +1 -1
  27. package/auth/token.js +51 -60
  28. package/auth/token.js.map +1 -1
  29. package/client/client.d.ts.map +1 -1
  30. package/client/client.js +4 -1
  31. package/client/client.js.map +1 -1
  32. package/client/current-organization.d.ts +5 -0
  33. package/client/current-organization.d.ts.map +1 -0
  34. package/client/current-organization.js +15 -0
  35. package/client/current-organization.js.map +1 -0
  36. package/commands/apikey/index.d.ts +16 -1
  37. package/commands/apikey/index.d.ts.map +1 -1
  38. package/commands/apikey/index.js +81 -0
  39. package/commands/apikey/index.js.map +1 -1
  40. package/commands/app-handover.d.ts +17 -0
  41. package/commands/app-handover.d.ts.map +1 -0
  42. package/commands/app-handover.js +168 -0
  43. package/commands/app-handover.js.map +1 -0
  44. package/commands/auth/index.d.ts.map +1 -1
  45. package/commands/auth/index.js +15 -9
  46. package/commands/auth/index.js.map +1 -1
  47. package/commands/auth/login.d.ts +7 -2
  48. package/commands/auth/login.d.ts.map +1 -1
  49. package/commands/auth/login.js +26 -23
  50. package/commands/auth/login.js.map +1 -1
  51. package/commands/auth/whoami.d.ts +15 -0
  52. package/commands/auth/whoami.d.ts.map +1 -1
  53. package/commands/auth/whoami.js +72 -2
  54. package/commands/auth/whoami.js.map +1 -1
  55. package/commands/coding-agent.d.ts +5 -0
  56. package/commands/coding-agent.d.ts.map +1 -0
  57. package/commands/coding-agent.js +30 -0
  58. package/commands/coding-agent.js.map +1 -0
  59. package/commands/config/backend.js +20 -6
  60. package/commands/config/backend.js.map +1 -1
  61. package/commands/docs/index.d.ts +9 -0
  62. package/commands/docs/index.d.ts.map +1 -0
  63. package/commands/docs/index.js +64 -0
  64. package/commands/docs/index.js.map +1 -0
  65. package/commands/embedding.d.ts +28 -0
  66. package/commands/embedding.d.ts.map +1 -0
  67. package/commands/embedding.js +170 -0
  68. package/commands/embedding.js.map +1 -0
  69. package/commands/example.d.ts +20 -0
  70. package/commands/example.d.ts.map +1 -0
  71. package/commands/example.js +136 -0
  72. package/commands/example.js.map +1 -0
  73. package/commands/help.d.ts.map +1 -1
  74. package/commands/help.js +19 -3
  75. package/commands/help.js.map +1 -1
  76. package/commands/list.d.ts.map +1 -1
  77. package/commands/list.js +13 -1
  78. package/commands/list.js.map +1 -1
  79. package/commands/load-test/burst.d.ts +64 -0
  80. package/commands/load-test/burst.d.ts.map +1 -0
  81. package/commands/load-test/burst.js +202 -0
  82. package/commands/load-test/burst.js.map +1 -0
  83. package/commands/load-test/index.d.ts +37 -0
  84. package/commands/load-test/index.d.ts.map +1 -0
  85. package/commands/load-test/index.js +154 -0
  86. package/commands/load-test/index.js.map +1 -0
  87. package/commands/load-test/report.d.ts +98 -0
  88. package/commands/load-test/report.d.ts.map +1 -0
  89. package/commands/load-test/report.js +210 -0
  90. package/commands/load-test/report.js.map +1 -0
  91. package/commands/mcp-server.d.ts +3 -3
  92. package/commands/mcp-server.d.ts.map +1 -1
  93. package/commands/mcp-server.js +16 -7
  94. package/commands/mcp-server.js.map +1 -1
  95. package/commands/provider-key/index.d.ts.map +1 -1
  96. package/commands/provider-key/index.js +2 -2
  97. package/commands/provider-key/index.js.map +1 -1
  98. package/commands/setup.d.ts +17 -0
  99. package/commands/setup.d.ts.map +1 -1
  100. package/commands/setup.js +71 -1
  101. package/commands/setup.js.map +1 -1
  102. package/commands/status.d.ts.map +1 -1
  103. package/commands/status.js +4 -3
  104. package/commands/status.js.map +1 -1
  105. package/commands/up.d.ts.map +1 -1
  106. package/commands/up.js +67 -9
  107. package/commands/up.js.map +1 -1
  108. package/commands/usage.d.ts +15 -0
  109. package/commands/usage.d.ts.map +1 -1
  110. package/commands/usage.js +52 -2
  111. package/commands/usage.js.map +1 -1
  112. package/config/config.d.ts +14 -7
  113. package/config/config.d.ts.map +1 -1
  114. package/config/config.js +5 -1
  115. package/config/config.js.map +1 -1
  116. package/config/index.d.ts +2 -2
  117. package/config/index.d.ts.map +1 -1
  118. package/config/index.js +2 -2
  119. package/config/index.js.map +1 -1
  120. package/config/resolve.d.ts +14 -3
  121. package/config/resolve.d.ts.map +1 -1
  122. package/config/resolve.js +30 -6
  123. package/config/resolve.js.map +1 -1
  124. package/errors/classify.d.ts.map +1 -1
  125. package/errors/classify.js +10 -1
  126. package/errors/classify.js.map +1 -1
  127. package/errors/cli-exit-error.d.ts +3 -1
  128. package/errors/cli-exit-error.d.ts.map +1 -1
  129. package/errors/cli-exit-error.js +6 -2
  130. package/errors/cli-exit-error.js.map +1 -1
  131. package/errors/handle.d.ts +32 -5
  132. package/errors/handle.d.ts.map +1 -1
  133. package/errors/handle.js +67 -8
  134. package/errors/handle.js.map +1 -1
  135. package/local/daemon/components.d.ts +28 -1
  136. package/local/daemon/components.d.ts.map +1 -1
  137. package/local/daemon/components.js +64 -2
  138. package/local/daemon/components.js.map +1 -1
  139. package/local/daemon/host.d.ts.map +1 -1
  140. package/local/daemon/host.js +6 -2
  141. package/local/daemon/host.js.map +1 -1
  142. package/local/daemon/launch.d.ts +12 -4
  143. package/local/daemon/launch.d.ts.map +1 -1
  144. package/local/daemon/launch.js +49 -16
  145. package/local/daemon/launch.js.map +1 -1
  146. package/local/daemon/types.d.ts +9 -1
  147. package/local/daemon/types.d.ts.map +1 -1
  148. package/local/key-check.d.ts +20 -0
  149. package/local/key-check.d.ts.map +1 -0
  150. package/local/key-check.js +45 -0
  151. package/local/key-check.js.map +1 -0
  152. package/local/model-key-step.d.ts +63 -0
  153. package/local/model-key-step.d.ts.map +1 -0
  154. package/local/model-key-step.js +133 -0
  155. package/local/model-key-step.js.map +1 -0
  156. package/local/runtime/node.d.ts +12 -4
  157. package/local/runtime/node.d.ts.map +1 -1
  158. package/local/runtime/node.js +73 -27
  159. package/local/runtime/node.js.map +1 -1
  160. package/local/setup/prompt.d.ts.map +1 -1
  161. package/local/setup/prompt.js +22 -18
  162. package/local/setup/prompt.js.map +1 -1
  163. package/local/setup/wizard.d.ts +10 -0
  164. package/local/setup/wizard.d.ts.map +1 -1
  165. package/local/setup/wizard.js +40 -17
  166. package/local/setup/wizard.js.map +1 -1
  167. package/local/state/lock.d.ts.map +1 -1
  168. package/local/state/lock.js +123 -36
  169. package/local/state/lock.js.map +1 -1
  170. package/local/state/pidfile.d.ts +4 -0
  171. package/local/state/pidfile.d.ts.map +1 -1
  172. package/local/state/pidfile.js +12 -3
  173. package/local/state/pidfile.js.map +1 -1
  174. package/local/status.d.ts.map +1 -1
  175. package/local/status.js +62 -4
  176. package/local/status.js.map +1 -1
  177. package/package.json +13 -10
  178. package/program.d.ts.map +1 -1
  179. package/program.js +12 -0
  180. package/program.js.map +1 -1
  181. package/resources/get.js +1 -1
  182. package/resources/get.js.map +1 -1
  183. package/resources/provider-key.d.ts +7 -2
  184. package/resources/provider-key.d.ts.map +1 -1
  185. package/resources/provider-key.js +18 -3
  186. package/resources/provider-key.js.map +1 -1
  187. package/resources/run/stream.d.ts.map +1 -1
  188. package/resources/run/stream.js +2 -1
  189. package/resources/run/stream.js.map +1 -1
  190. package/resources/runs.d.ts +10 -3
  191. package/resources/runs.d.ts.map +1 -1
  192. package/resources/runs.js +22 -4
  193. package/resources/runs.js.map +1 -1
  194. package/resources/stream/render-plaintext.d.ts +3 -0
  195. package/resources/stream/render-plaintext.d.ts.map +1 -1
  196. package/resources/stream/render-plaintext.js +20 -2
  197. package/resources/stream/render-plaintext.js.map +1 -1
  198. package/resources/usage.d.ts +8 -0
  199. package/resources/usage.d.ts.map +1 -1
  200. package/resources/usage.js +37 -0
  201. package/resources/usage.js.map +1 -1
  202. package/resources/views/agent.d.ts.map +1 -1
  203. package/resources/views/agent.js +18 -2
  204. package/resources/views/agent.js.map +1 -1
  205. package/runtime.d.ts +9 -0
  206. package/runtime.d.ts.map +1 -1
  207. package/runtime.js +12 -1
  208. package/runtime.js.map +1 -1
  209. package/src/auth/browser.ts +57 -0
  210. package/src/auth/callback-server.ts +58 -22
  211. package/src/auth/device.ts +151 -0
  212. package/src/auth/index.ts +4 -3
  213. package/src/auth/login.ts +243 -67
  214. package/src/auth/oidc.ts +270 -0
  215. package/src/auth/token.ts +53 -90
  216. package/src/client/client.ts +4 -1
  217. package/src/client/current-organization.ts +27 -0
  218. package/src/commands/apikey/index.ts +85 -0
  219. package/src/commands/app-handover.ts +202 -0
  220. package/src/commands/auth/index.ts +16 -10
  221. package/src/commands/auth/login.ts +30 -23
  222. package/src/commands/auth/whoami.ts +80 -1
  223. package/src/commands/coding-agent.ts +33 -0
  224. package/src/commands/config/backend.ts +20 -6
  225. package/src/commands/docs/index.ts +65 -0
  226. package/src/commands/embedding.ts +209 -0
  227. package/src/commands/example.ts +157 -0
  228. package/src/commands/help.ts +19 -3
  229. package/src/commands/list.ts +14 -1
  230. package/src/commands/load-test/burst.ts +291 -0
  231. package/src/commands/load-test/index.ts +183 -0
  232. package/src/commands/load-test/report.ts +302 -0
  233. package/src/commands/mcp-server.ts +16 -8
  234. package/src/commands/provider-key/index.ts +7 -1
  235. package/src/commands/setup.ts +76 -2
  236. package/src/commands/status.ts +4 -3
  237. package/src/commands/up.ts +76 -10
  238. package/src/commands/usage.ts +55 -2
  239. package/src/config/config.ts +18 -8
  240. package/src/config/index.ts +2 -0
  241. package/src/config/resolve.ts +31 -6
  242. package/src/errors/classify.ts +10 -1
  243. package/src/errors/cli-exit-error.ts +6 -2
  244. package/src/errors/handle.ts +74 -8
  245. package/src/local/daemon/components.ts +66 -2
  246. package/src/local/daemon/host.ts +6 -2
  247. package/src/local/daemon/launch.ts +51 -16
  248. package/src/local/daemon/types.ts +9 -1
  249. package/src/local/key-check.ts +61 -0
  250. package/src/local/model-key-step.ts +164 -0
  251. package/src/local/runtime/node.ts +95 -30
  252. package/src/local/setup/prompt.ts +22 -18
  253. package/src/local/setup/wizard.ts +45 -18
  254. package/src/local/state/lock.ts +116 -35
  255. package/src/local/state/pidfile.ts +14 -3
  256. package/src/local/status.ts +69 -4
  257. package/src/program.ts +12 -0
  258. package/src/resources/get.ts +1 -1
  259. package/src/resources/provider-key.ts +24 -3
  260. package/src/resources/run/stream.ts +2 -1
  261. package/src/resources/runs.ts +36 -4
  262. package/src/resources/stream/render-plaintext.ts +20 -2
  263. package/src/resources/usage.ts +42 -0
  264. package/src/resources/views/agent.ts +19 -2
  265. package/src/runtime.ts +17 -1
  266. package/auth/auth0.d.ts +0 -19
  267. package/auth/auth0.d.ts.map +0 -1
  268. package/auth/auth0.js +0 -39
  269. package/auth/auth0.js.map +0 -1
  270. package/src/auth/auth0.ts +0 -43
@@ -0,0 +1,157 @@
1
+ // `stigmer example list|get` — Stigmer's example agents, as files in your repository.
2
+ //
3
+ // example list every example: the job, what goes in, what comes back;
4
+ // then the ready-made skills
5
+ // example get <id> [dir] write an example's manifest and samples into dir
6
+ // (default stigmer/<id>), or a skill's SKILL.md
7
+ // (default stigmer/skills/<id>)
8
+ //
9
+ // The list is `@stigmer/examples`, the one the console's first question and
10
+ // its Make it yours tab read, so every door offers the same agents with the
11
+ // same words. `get` writes the manifest people would download and the sample
12
+ // files a first run attaches, then says the two commands that make the agent
13
+ // and run it once on the samples (`stigmer apply -f`, `stigmer run --attach`).
14
+ // An agent made from an example keeps the example's slug, which is how the
15
+ // console's journey knows it.
16
+ //
17
+ // It never overwrites: a file already there is refused unless `--force`, so a
18
+ // manifest a person (or their coding agent) has edited is not lost.
19
+
20
+ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
21
+ import { join, relative, resolve } from "node:path";
22
+ import type { Command } from "commander";
23
+ import type { Example, ExampleSkill } from "@stigmer/examples";
24
+ import { CliExitError, ExitCode } from "../errors/index.js";
25
+ import { type OutputFlags, CommandResult, renderResult } from "../output/index.js";
26
+ import { addResultFlags, resultFormat } from "./shared.js";
27
+
28
+ interface GetFlags extends OutputFlags {
29
+ force?: boolean;
30
+ }
31
+
32
+ /** Where the output of a first run goes, as the guide's step 4 names it. */
33
+ export const RUN_OUTPUT_DIR = "stigmer-output";
34
+
35
+ export function registerExample(program: Command): void {
36
+ const group = program
37
+ .command("example")
38
+ .description("the example agents and skills, written into your repository as files");
39
+
40
+ const list = group
41
+ .command("list")
42
+ .description("list the example agents (the job, what goes in, what comes back) and the ready-made skills")
43
+ .action(async (options: OutputFlags) => {
44
+ const { EXAMPLES, SKILLS } = await import("@stigmer/examples");
45
+ renderResult(exampleListResult(EXAMPLES, SKILLS), resultFormat(options));
46
+ });
47
+ addResultFlags(list);
48
+
49
+ const get = group
50
+ .command("get <id> [dir]")
51
+ .description("write an example's manifest and sample files (or a skill's SKILL.md) into dir")
52
+ .option("-f, --force", "overwrite files that are already there")
53
+ .action(async (id: string, dir: string | undefined, options: GetFlags) => {
54
+ const { exampleById, skillById, EXAMPLES, SKILLS } = await import("@stigmer/examples");
55
+ const example = exampleById(id);
56
+ const skill = example === undefined ? skillById(id) : undefined;
57
+ if (example === undefined && skill === undefined) {
58
+ throw new CliExitError(`no example or skill named "${id}"`, ExitCode.Usage, [
59
+ `Examples: ${EXAMPLES.map((e) => e.id).join(", ")}`,
60
+ `Skills: ${SKILLS.map((s) => s.id).join(", ")}`,
61
+ "See them with: stigmer example list",
62
+ ]);
63
+ }
64
+ const result =
65
+ example !== undefined
66
+ ? writeExample(example, dir ?? join("stigmer", example.id), options.force === true)
67
+ : writeSkill(skill as ExampleSkill, dir ?? join("stigmer", "skills", (skill as ExampleSkill).id), options.force === true);
68
+ renderResult(result, resultFormat(options));
69
+ });
70
+ addResultFlags(get);
71
+ }
72
+
73
+ /** The list a person reads: each example's job, then the skills. Pure. */
74
+ export function exampleListResult(examples: readonly Example[], skills: readonly ExampleSkill[]): CommandResult {
75
+ const result = CommandResult.success(`${examples.length} example agents`).withData({
76
+ examples: examples.map((e) => ({
77
+ id: e.id,
78
+ name: e.name,
79
+ for: e.for,
80
+ gives: e.gives,
81
+ gets: e.gets,
82
+ agent: e.agent.slug,
83
+ })),
84
+ skills: skills.map((s) => ({ id: s.id, name: s.name, description: s.description })),
85
+ });
86
+ for (const example of examples) {
87
+ result
88
+ .addSection(`${example.id} — ${example.name}`)
89
+ .field("For", example.for.replace(/^For /, ""))
90
+ .field("Gives", example.gives)
91
+ .field("Gets", example.gets)
92
+ .field("Agent", example.agent.slug);
93
+ }
94
+ if (skills.length > 0) {
95
+ const section = result.addSection("Skills");
96
+ for (const skill of skills) section.field(skill.id, skill.name);
97
+ }
98
+ return result
99
+ .hint("Write one into this repository: stigmer example get <id>")
100
+ .hint("Or describe your own agent in a manifest and: stigmer apply -f <file>");
101
+ }
102
+
103
+ /** Write an example's manifest and samples into `dir`, refusing to overwrite unless `force`. */
104
+ export function writeExample(example: Example, dir: string, force: boolean): CommandResult {
105
+ const files = [example.manifest, ...example.samples.map((s) => ({ name: s.name, text: s.text }))];
106
+ const written = writeFiles(dir, files, force);
107
+ const shown = displayPath(dir);
108
+ const attach = example.samples.map((s) => `--attach ${join(shown, s.name)}`).join(" ");
109
+ return CommandResult.success(`Wrote ${example.name} into ${shown}`)
110
+ .withData({ dir: shown, files: written, agent: example.agent.slug })
111
+ .hint(`Make the agent: stigmer apply -f ${join(shown, example.manifest.name)}`)
112
+ .hint(
113
+ `Run it once on the ${example.sampleName}: stigmer run ${example.agent.slug} -m ${JSON.stringify(example.message)} ${attach} --download ${RUN_OUTPUT_DIR}/`,
114
+ );
115
+ }
116
+
117
+ /** Write a skill's SKILL.md into `dir`, refusing to overwrite unless `force`. */
118
+ export function writeSkill(skill: ExampleSkill, dir: string, force: boolean): CommandResult {
119
+ const written = writeFiles(dir, [{ name: "SKILL.md", text: skill.text }], force);
120
+ const shown = displayPath(dir);
121
+ return CommandResult.success(`Wrote the ${skill.name} skill into ${shown}`)
122
+ .withData({ dir: shown, files: written, skill: skill.id })
123
+ .hint(`Push it to your organization: stigmer push skill ${shown}`)
124
+ .hint(`Then add these lines under the agent's spec: and apply it again:`)
125
+ .hint(skillRefsLines(skill.id));
126
+ }
127
+
128
+ /**
129
+ * The exact `skill_refs` lines that turn a pushed skill on for an agent, as
130
+ * its manifest carries them under `spec:` (a relative reference, so the
131
+ * manifest works in any organization). Spelled out because a bare
132
+ * "add it to skill_refs" left coding agents guessing the shape (stigmer#3233).
133
+ */
134
+ export function skillRefsLines(slug: string): string {
135
+ return `skill_refs:\n - kind: skill\n slug: ${slug}`;
136
+ }
137
+
138
+ function writeFiles(dir: string, files: readonly { name: string; text: string }[], force: boolean): string[] {
139
+ const target = resolve(dir);
140
+ const existing = files.map((f) => join(target, f.name)).filter((path) => existsSync(path));
141
+ if (existing.length > 0 && !force) {
142
+ throw new CliExitError(
143
+ `${existing.map(displayPath).join(", ")} ${existing.length === 1 ? "is" : "are"} already there`,
144
+ ExitCode.Usage,
145
+ ["Keep your copy, write somewhere else (stigmer example get <id> <dir>), or overwrite with --force."],
146
+ );
147
+ }
148
+ mkdirSync(target, { recursive: true });
149
+ for (const file of files) writeFileSync(join(target, file.name), file.text);
150
+ return files.map((f) => displayPath(join(target, f.name)));
151
+ }
152
+
153
+ /** A path as the person typed it: relative to where they stand when it is inside. */
154
+ function displayPath(path: string): string {
155
+ const rel = relative(process.cwd(), resolve(path));
156
+ return rel === "" ? "." : rel.startsWith("..") ? resolve(path) : rel;
157
+ }
@@ -29,6 +29,9 @@ export const COMMAND_GROUPS: Readonly<Record<string, HelpGroup>> = {
29
29
  run: "Run agents",
30
30
  resume: "Run agents",
31
31
  runs: "Run agents",
32
+ "app-handover": "Run agents",
33
+ "coding-agent": "Run agents",
34
+ "load-test": "Run agents",
32
35
  get: "Your library",
33
36
  list: "Your library",
34
37
  search: "Your library",
@@ -42,6 +45,7 @@ export const COMMAND_GROUPS: Readonly<Record<string, HelpGroup>> = {
42
45
  vault: "Your library",
43
46
  file: "Your library",
44
47
  connect: "Your library",
48
+ example: "Your library",
45
49
  push: "Packages",
46
50
  install: "Packages",
47
51
  marketplace: "Packages",
@@ -58,12 +62,14 @@ export const COMMAND_GROUPS: Readonly<Record<string, HelpGroup>> = {
58
62
  auth: "Account and access",
59
63
  apikey: "Account and access",
60
64
  "service-account": "Account and access",
65
+ embedding: "Account and access",
61
66
  "provider-key": "Account and access",
62
67
  "access-history": "Account and access",
63
68
  usage: "Account and access",
64
69
  config: "Configuration",
65
70
  completion: "Configuration",
66
71
  version: "Configuration",
72
+ docs: "Configuration",
67
73
  };
68
74
 
69
75
  /** Each runnable command's examples, by path. */
@@ -71,15 +77,17 @@ export const HELP_EXAMPLES: ReadonlyMap<string, readonly HelpExample[]> = new Ma
71
77
  ["stigmer access-history export", [{ say: "everything, oldest first, one JSON object per line", run: "stigmer access-history export > access-history.jsonl" }, { say: "only what came after the last entry you hold", run: "stigmer access-history export --after 42 >> access-history.jsonl" }]],
72
78
  ["stigmer access-history list", [{ say: "the newest 50 changes", run: "stigmer access-history list" }, { say: "the newest 200, as JSON", run: "stigmer access-history list --limit 200 -o json" }]],
73
79
  ["stigmer agent quality", [{ say: "how the agent's runs were graded over the last 30 days, per version", run: "stigmer agent quality variance-reporter" }, { say: "the last week's failed grades, newest first", run: "stigmer agent quality variance-reporter --days 7 --flagged --limit 50" }]],
74
- ["stigmer apikey create", [{ say: "create a new API key", run: "stigmer apikey create --name \"ci-pipeline\"" }, { say: "create a key that never expires", run: "stigmer apikey create --name \"automation\" --never-expires" }]],
80
+ ["stigmer apikey create", [{ say: "create a new API key", run: "stigmer apikey create --name \"ci-pipeline\"" }, { say: "create a key that never expires", run: "stigmer apikey create --name \"automation\" --never-expires" }, { say: "a key for your app's backend, saved to its env file and never printed", run: "stigmer apikey create --service-account app-backend --name my-app --save-to-env .env.local" }]],
81
+ ["stigmer app-handover", [{ say: "print the token route and chat for a Next.js app", run: "stigmer app-handover --stack nextjs --agent invoice-matcher" }, { say: "write them into the app you are in", run: "stigmer app-handover --stack node --agent invoice-matcher --write ." }]],
75
82
  ["stigmer apikey fingerprint", [{ say: "look up which key matches a raw token", run: "stigmer apikey fingerprint stk_abc123..." }]],
76
83
  ["stigmer apply", [{ say: "apply a single resource file", run: "stigmer apply -f agent.yaml" }, { say: "apply all resources in a directory", run: "stigmer apply -f ./manifests/" }]],
77
- ["stigmer auth login", [{ say: "log in to Stigmer Cloud", run: "stigmer auth login" }]],
84
+ ["stigmer auth login", [{ say: "sign in to the active backend's server in your browser", run: "stigmer auth login" }, { say: "where no browser opens here, sign in with a code on any device", run: "stigmer auth login --device" }]],
78
85
  ["stigmer auth logout", [{ say: "log out", run: "stigmer auth logout" }]],
79
86
  ["stigmer auth whoami", [{ say: "check who you're logged in as", run: "stigmer auth whoami" }]],
80
87
  ["stigmer channel disable", [{ say: "pause any channel (web, Slack or WhatsApp), keeping its configuration", run: "stigmer channel disable acme-corp/variance-reporter-slack" }]],
81
88
  ["stigmer channel enable", [{ say: "turn it back on", run: "stigmer channel enable acme-corp/variance-reporter-slack" }]],
82
89
  ["stigmer channel link", [{ say: "turn on an Agent's chat link for your Organization's members", run: "stigmer channel link variance-reporter" }, { say: "make the link public and print the embed snippet", run: "stigmer channel link variance-reporter --audience public" }]],
90
+ ["stigmer coding-agent", [{ say: "print the guide your coding agent follows", run: "stigmer coding-agent" }]],
83
91
  ["stigmer completion", [{ say: "install permanently", run: "stigmer completion bash > /etc/bash_completion.d/stigmer" }]],
84
92
  ["stigmer config backend add", [{ say: "register a self-hosted server (mint the key with `stigmer apikey create`)", run: "stigmer config backend add staging --endpoint stigmer.example.com:7234 --api-key stk_..." }]],
85
93
  ["stigmer config backend list", [{ say: "see what is configured", run: "stigmer config backend list" }]],
@@ -95,15 +103,22 @@ export const HELP_EXAMPLES: ReadonlyMap<string, readonly HelpExample[]> = new Ma
95
103
  ["stigmer config set", [{ say: "make acme the active organization", run: "stigmer config set context.org acme" }]],
96
104
  ["stigmer connect plugin", [{ say: "list the tools the linear plugin's MCP server offers", run: "stigmer connect plugin linear" }]],
97
105
  ["stigmer delete", [{ say: "delete an agent by slug", run: "stigmer delete agent my-agent" }, { say: "delete an agent by ID", run: "stigmer delete agent agt_abc123" }]],
106
+ ["stigmer docs read", [{ say: "print a page whole, opening with its Source URL", run: "stigmer docs read concepts/runners" }]],
107
+ ["stigmer docs search", [{ say: "find the pages about moving the local server's port", run: "stigmer docs search port stigmer up" }]],
98
108
  ["stigmer down", [{ say: "stop the local stack", run: "stigmer down" }]],
99
109
  ["stigmer down server", [{ say: "stop the whole stack, as stigmer down does", run: "stigmer down server" }]],
100
110
  ["stigmer download", [{ say: "download all outputs from a run", run: "stigmer download run run_01abc123" }, { say: "download to a specific directory", run: "stigmer download run run_01abc123 --output-dir ./results/" }]],
111
+ ["stigmer embedding", [{ say: "how people sign in to your organization from your app", run: "stigmer embedding" }]],
112
+ ["stigmer embedding set", [{ say: "make an app user's account on their first sign-in, as a Member", run: "stigmer embedding set --create-accounts-on-sign-in on --sign-in-role member" }]],
101
113
  ["stigmer eval cancel", [{ say: "cancel a running eval run", run: "stigmer eval cancel evr_01abc123" }]],
102
114
  ["stigmer eval run", [{ say: "a plugin's own cases on the built-in assistant, with and without it", run: "stigmer eval run --plugin thermos" }, { say: "the cases of every plugin the agent attaches, on the agent", run: "stigmer eval run --agent variance-reporter" }, { say: "the cases of an Eval pushed with stigmer push eval, at its stable version", run: "stigmer eval run --agent variance-reporter --eval variance-reporter-evals@stable" }, { say: "the plugin's cases on the agent, with and without the plugin", run: "stigmer eval run --agent variance-reporter --plugin payroll" }]],
115
+ ["stigmer example get", [{ say: "write an example's manifest and samples into stigmer/invoice-match", run: "stigmer example get invoice-match" }, { say: "write a ready-made skill to push", run: "stigmer example get spreadsheet-export" }]],
116
+ ["stigmer example list", [{ say: "see the example agents and skills", run: "stigmer example list" }]],
103
117
  ["stigmer file upload", [{ say: "upload a spreadsheet to reuse, and see the id it is named by", run: "stigmer file upload q3-ledger.xlsx" }, { say: "upload into a conversation you already have", run: "stigmer file upload notes.md --session ses_01abc123" }]],
104
118
  ["stigmer get", [{ say: "get an agent by slug", run: "stigmer get agent my-agent" }, { say: "get by org-qualified slug", run: "stigmer get agent acme-corp/variance-reporter" }]],
105
119
  ["stigmer install", [{ say: "install from the official catalogue by name", run: "stigmer install linear" }, { say: "install from a source you added, naming it", run: "stigmer install acme-plugins/thermos" }]],
106
120
  ["stigmer list", [{ say: "list all agents", run: "stigmer list agents" }, { say: "list available resource types", run: "stigmer list types" }]],
121
+ ["stigmer load-test", [{ say: "start 25 agents at once on the active server", run: "stigmer load-test --agents 25" }, { say: "a bigger burst on a cheaper model, as JSON for a script", run: "stigmer load-test --agents 100 --model claude-haiku-4-5 --max-usd 2 -o json > burst.json" }]],
107
122
  ["stigmer logs", [{ say: "follow all components live (tail snapshot first)", run: "stigmer logs" }, { say: "show the last 100 lines and exit", run: "stigmer logs --no-follow --tail 100" }]],
108
123
  ["stigmer marketplace add", [{ say: "add your company's catalogue (a public GitHub repository with a marketplace file)", run: "stigmer marketplace add acme/agent-plugins" }, { say: "add a repository at a branch or tag, or from its URL", run: "stigmer marketplace add acme/agent-plugins@main" }]],
109
124
  ["stigmer marketplace list", [{ say: "see what is configured, and what one offers", run: "stigmer marketplace list" }]],
@@ -135,7 +150,7 @@ export const HELP_EXAMPLES: ReadonlyMap<string, readonly HelpExample[]> = new Ma
135
150
  ["stigmer service-account delete", [{ say: "delete one; every key it has stops working at once", run: "stigmer service-account delete ci-deploy" }]],
136
151
  ["stigmer service-account keys", [{ say: "list one's API keys; revoke one with: stigmer delete apikey <id>", run: "stigmer service-account keys ci-deploy" }]],
137
152
  ["stigmer service-account list", [{ say: "list the Organization's service accounts, newest first", run: "stigmer service-account list" }]],
138
- ["stigmer setup", [{ say: "interactive setup", run: "stigmer setup" }, { say: "non-interactive: configure Anthropic", run: "stigmer setup --provider anthropic --api-key sk-ant-xxx" }]],
153
+ ["stigmer setup", [{ say: "interactive setup", run: "stigmer setup" }, { say: "non-interactive: configure Anthropic", run: "stigmer setup --provider anthropic --api-key sk-ant-xxx" }, { say: "the key through stdin, kept out of history and transcripts", run: "stigmer setup --api-key-stdin < anthropic.key" }]],
139
154
  ["stigmer status", [{ say: "show component health and LLM configuration", run: "stigmer status" }, { say: "machine-readable status for scripts", run: "stigmer status --json" }]],
140
155
  ["stigmer tag", [{ say: "tag an agent version as stable, by the short hash the history prints", run: "stigmer tag agent acme-corp/variance-reporter 3f8a1c0e9b7d stable" }, { say: "the same, by its full 64-character hash", run: "stigmer tag agent acme-corp/variance-reporter 3f8a1c0e9b7d2a4c6e5f1b3d9a7c0e2f4b6d8a1c3e5f7b9d0a2c4e6f8b1d3a5c stable" }]],
141
156
  ["stigmer up", [{ say: "start the full local stack (server, runner, Temporal)", run: "stigmer up" }]],
@@ -143,6 +158,7 @@ export const HELP_EXAMPLES: ReadonlyMap<string, readonly HelpExample[]> = new Ma
143
158
  ["stigmer usage agent", [{ say: "view agent usage for a date range", run: "stigmer usage agent agt-01abc123 --from 2026-03-01 --to 2026-03-31" }]],
144
159
  ["stigmer usage hours", [{ say: "view the organization's agent hours (Stigmer Cloud)", run: "stigmer usage hours" }]],
145
160
  ["stigmer usage org", [{ say: "view organization-wide usage", run: "stigmer usage org --from 2026-03-01 --to 2026-03-31" }]],
161
+ ["stigmer usage onboarding", [{ say: "see where last week's new organizations stopped (platform operators)", run: "stigmer usage onboarding" }]],
146
162
  ["stigmer usage session", [{ say: "view usage for a specific session", run: "stigmer usage session ses_01j9z3k8m2q4r6t8v0w2y4a6c8" }]],
147
163
  ["stigmer validate", [{ say: "validate a single file", run: "stigmer validate -f agent.yaml" }, { say: "validate all YAML files in a directory", run: "stigmer validate -f ./manifests/" }]],
148
164
  ["stigmer vault connect-link", [{ say: "make a one-time sign-in page whose login lands in a shared vault", run: "stigmer vault connect-link ledger-keys --address https://mcp.linear.app/mcp --return-url https://app.example.com/settings" }]],
@@ -18,6 +18,7 @@ interface ListFlags extends OutputFlags {
18
18
  verb?: string;
19
19
  label?: string[];
20
20
  session?: string;
21
+ agent?: string;
21
22
  }
22
23
 
23
24
  export function registerList(program: Command): void {
@@ -33,6 +34,7 @@ export function registerList(program: Command): void {
33
34
  [],
34
35
  )
35
36
  .option("--session <id>", "files: list one conversation's Files, what was given to it and what its turns saved (only for 'list files')")
37
+ .option("--agent <agent>", "runs: list one agent's runs, newest first across its conversations (only for 'list runs')")
36
38
  .action((type: string, options: ListFlags, command: Command) => runList(type, options, command));
37
39
  addReadFlags(list);
38
40
  }
@@ -45,6 +47,7 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
45
47
  if (options.session !== undefined) {
46
48
  throw new UsageError("--session names a conversation whose Files to list; 'list types' has none");
47
49
  }
50
+ if (options.agent !== undefined) throw agentFilterRefusal(type);
48
51
  process.stdout.write(renderTypes(options.verb, readFormat(options)));
49
52
  return;
50
53
  }
@@ -69,6 +72,7 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
69
72
  if (info === undefined) {
70
73
  throw new UsageError(`unknown resource type: ${type}`);
71
74
  }
75
+ if (options.agent !== undefined) throw agentFilterRefusal(type);
72
76
  if (!info.supportedVerbs.has(Verb.List)) {
73
77
  throw new UsageError(`${info.displayName} does not support 'list'`);
74
78
  }
@@ -101,6 +105,10 @@ async function runList(type: string, options: ListFlags, command: Command): Prom
101
105
  process.stdout.write(rendered);
102
106
  }
103
107
 
108
+ function agentFilterRefusal(type: string): UsageError {
109
+ return new UsageError(`--agent lists one agent's runs; 'list ${type}' takes no agent (use 'list runs --agent <agent>')`);
110
+ }
111
+
104
112
  function sessionFilterRefusal(type: string): UsageError {
105
113
  return new UsageError(`--session lists one conversation's Files; 'list ${type}' takes no conversation (use 'list files --session <id>')`);
106
114
  }
@@ -108,6 +116,8 @@ function sessionFilterRefusal(type: string): UsageError {
108
116
  // Runs bypass the registry: they're listed by their own controller. Results are
109
117
  // scoped to the resolved org context (--org flag, env, or configured context);
110
118
  // an unset cloud context resolves to "" = permission-bounded across orgs.
119
+ // `--agent` lists one agent's runs instead, newest first across its
120
+ // conversations, the agent named as `agent quality` names it.
111
121
  async function runListRuns(options: ListFlags, command: Command, labels: Record<string, string>): Promise<void> {
112
122
  const [{ connectBackend }, runs] = await Promise.all([
113
123
  import("../backend.js"),
@@ -120,7 +130,10 @@ async function runListRuns(options: ListFlags, command: Command, labels: Record<
120
130
  const limit = parseLimit(options.limit);
121
131
  const format = readFormat(options);
122
132
 
123
- const result = await runs.listAgentRuns(client.stigmer, limit, org, labels);
133
+ const result =
134
+ options.agent === undefined
135
+ ? await runs.listOrgRuns(client.stigmer, limit, org, labels)
136
+ : await runs.listRunsOfAgent(client.stigmer, limit, options.agent, org, labels);
124
137
  process.stdout.write(runs.renderRunList(result, format));
125
138
  }
126
139
 
@@ -0,0 +1,291 @@
1
+ // The engine of `stigmer load-test`: make one agent of its own, start N
2
+ // turns on it at the same moment, watch each until it ends or the watch's
3
+ // time is up, read each run once, then delete everything it made.
4
+ //
5
+ // - Every turn is a new conversation (`startTurn` with a `sessionSpec`), so
6
+ // each asks the fleet for a sandbox of its own. The creates are fired
7
+ // together (one `Promise.allSettled`, no stagger); a create the server
8
+ // refuses is kept as its code and the server's own sentence.
9
+ // - Each admitted turn is followed the way `stigmer run` follows one
10
+ // (`followSession` with the `stigmer.run.liveness` preview), never with
11
+ // `waitForTurn`, which asks for no previews and so never sees a wait. The
12
+ // largest `awaiting_sandbox_for` any frame carried is kept: a later
13
+ // liveness replaces the fold's, so the fold forgets the wait once the turn
14
+ // starts.
15
+ // - A started turn's conversation is left as a person leaves one until the
16
+ // cleanup at the end: its sandbox holds its place until the fleet's own
17
+ // idle sweep, which is how room frees for the turns still waiting.
18
+ // - The cleanup runs on every way out, Ctrl-C included: every follow is
19
+ // aborted, every run still open is terminated, every conversation it made
20
+ // is deleted (with its sandbox), then the agent. What could not be deleted
21
+ // is returned by id. This command cannot read a server's database, so it
22
+ // never claims the fleet is empty.
23
+ //
24
+ // The client is the narrow slice of `Stigmer` the engine calls, so tests
25
+ // drive it with a fake.
26
+
27
+ import type { Agent } from "@stigmer/apis/ai/stigmer/agentic/agent/v1/api_pb";
28
+ import type { Run } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
29
+ import { RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
30
+ import type { Duration } from "@bufbuild/protobuf/wkt";
31
+ import {
32
+ type AgentInput,
33
+ followSession,
34
+ isTerminalPhase,
35
+ type RunInput,
36
+ type SessionEventsClient,
37
+ SessionLog,
38
+ startTurn,
39
+ StigmerError,
40
+ turnOf,
41
+ type TurnPhase,
42
+ } from "@stigmer/client";
43
+ import type { Refusal, RunSighting } from "./report.js";
44
+
45
+ /** The slice of the client the engine calls. */
46
+ export interface LoadTestClient extends SessionEventsClient {
47
+ readonly agent: {
48
+ create(input: AgentInput): Promise<Agent>;
49
+ delete(id: string): Promise<unknown>;
50
+ };
51
+ readonly run: {
52
+ create(input: RunInput): Promise<Run>;
53
+ get(id: string): Promise<Run>;
54
+ terminate(input: { id: string; reason: string }): Promise<unknown>;
55
+ };
56
+ readonly session: SessionEventsClient["session"] & {
57
+ delete(id: string): Promise<unknown>;
58
+ };
59
+ }
60
+
61
+ /** How the burst stands, each time it changes. */
62
+ export interface BurstProgress {
63
+ readonly sent: number;
64
+ readonly started: number;
65
+ /** Admitted and not yet started: waiting for a sandbox, or still setting up. */
66
+ readonly waiting: number;
67
+ readonly refused: number;
68
+ }
69
+
70
+ export interface BurstOptions {
71
+ /** The organization the agent and the turns are made in ("" lets a single-organization server fill it). */
72
+ readonly org: string;
73
+ readonly agents: number;
74
+ /** The model every turn asks for; "" leaves the agent's default. */
75
+ readonly model: string;
76
+ readonly message: string;
77
+ /** Each turn's budget, `RunConfig.max_cost_usd`. */
78
+ readonly shareUsd: number;
79
+ /** How long to watch, from the burst, before calling a run still waiting. */
80
+ readonly waitMs: number;
81
+ /** Ctrl-C: stops every watch; the cleanup still runs. */
82
+ readonly signal: AbortSignal;
83
+ readonly onProgress?: (progress: BurstProgress) => void;
84
+ /** The agent's name suffix; random when absent (tests pin it). */
85
+ readonly nonce?: string;
86
+ }
87
+
88
+ /** What the burst saw, and what its cleanup could not delete. */
89
+ export interface BurstResult {
90
+ /** The agent's slug. */
91
+ readonly agent: string;
92
+ readonly sightings: readonly RunSighting[];
93
+ /** "<kind> <id>" for each thing the cleanup could not delete. */
94
+ readonly leftBehind: readonly string[];
95
+ /** Whether Ctrl-C ended the watch. */
96
+ readonly interrupted: boolean;
97
+ }
98
+
99
+ /** The one-line instructions the burst's agent runs: each turn stays tiny. */
100
+ export const AGENT_INSTRUCTIONS = "Reply with one word.";
101
+
102
+ const TERMINATE_REASON = "stigmer load-test cleanup";
103
+
104
+ // The fold's phases a turn has only once its runner started it.
105
+ const STARTED_PHASES: ReadonlySet<TurnPhase> = new Set<TurnPhase>(["running", "waiting", "paused", "completed"]);
106
+
107
+ interface Admitted {
108
+ readonly index: number;
109
+ readonly runId: string;
110
+ readonly sessionId: string;
111
+ }
112
+
113
+ /** Run the burst (module header). The agent's create throws through; everything after it is cleaned up. */
114
+ export async function runBurst(client: LoadTestClient, options: BurstOptions): Promise<BurstResult> {
115
+ const nonce = options.nonce ?? Math.random().toString(36).slice(2, 8);
116
+ const agent = await client.agent.create({
117
+ name: `load-test-${nonce}`,
118
+ org: options.org,
119
+ description: "Made by stigmer load-test and deleted when it ends.",
120
+ instructions: AGENT_INSTRUCTIONS,
121
+ });
122
+ const agentId = agent.metadata?.id ?? "";
123
+ const agentRef = { org: agent.metadata?.org ?? options.org, slug: agent.metadata?.slug ?? "" };
124
+
125
+ const deadline = new AbortController();
126
+ const timer = setTimeout(() => deadline.abort(), options.waitMs);
127
+ const signal = AbortSignal.any([options.signal, deadline.signal]);
128
+ const tracker = new Tracker(options.agents, options.onProgress);
129
+ const slots: Array<Admitted | Refusal> = [];
130
+ const admitted: Admitted[] = [];
131
+ const waits = new Map<string, number>();
132
+ const runs = new Map<string, Run>();
133
+ try {
134
+ const sends = await Promise.allSettled(
135
+ Array.from({ length: options.agents }, () =>
136
+ startTurn(client, {
137
+ org: agentRef.org,
138
+ message: options.message,
139
+ sessionSpec: { agentRef, includeMyVault: true },
140
+ runConfig: { maxCostUsd: options.shareUsd, ...(options.model === "" ? {} : { modelName: options.model }) },
141
+ }),
142
+ ),
143
+ );
144
+ for (const [i, send] of sends.entries()) {
145
+ if (send.status === "fulfilled") {
146
+ const a = { index: i + 1, runId: send.value.runId, sessionId: send.value.sessionId };
147
+ admitted.push(a);
148
+ slots.push(a);
149
+ } else {
150
+ slots.push(refusalOf(send.reason));
151
+ }
152
+ }
153
+ tracker.sent(admitted.map((a) => a.runId), slots.length - admitted.length);
154
+
155
+ await Promise.all(
156
+ admitted.map(async (a) => {
157
+ const waited = await watch(client, a, signal, tracker);
158
+ if (waited !== undefined) waits.set(a.runId, waited);
159
+ }),
160
+ );
161
+ await Promise.all(
162
+ admitted.map(async (a) => {
163
+ const run = await client.run.get(a.runId).catch(() => undefined);
164
+ if (run !== undefined) runs.set(a.runId, run);
165
+ }),
166
+ );
167
+ } finally {
168
+ clearTimeout(timer);
169
+ }
170
+
171
+ const leftBehind = await cleanUp(client, admitted, runs, agentId);
172
+ const sightings = slots.map((slot, i): RunSighting =>
173
+ "runId" in slot
174
+ ? { index: slot.index, runId: slot.runId, sessionId: slot.sessionId, run: runs.get(slot.runId), waitedMs: waits.get(slot.runId) }
175
+ : { index: i + 1, runId: "", sessionId: "", refusal: slot },
176
+ );
177
+ return { agent: agentRef.slug, sightings, leftBehind, interrupted: options.signal.aborted };
178
+ }
179
+
180
+ /** A refused create as its code word and the server's own sentence. */
181
+ export function refusalOf(err: unknown): Refusal {
182
+ if (err instanceof StigmerError) return { code: err.code, message: err.message };
183
+ return { code: "unknown", message: err instanceof Error ? err.message : String(err) };
184
+ }
185
+
186
+ // Follow one turn until it ends or the watch stops; the largest wait for a
187
+ // sandbox its liveness carried, or undefined when it reported none. A follow
188
+ // the server refuses ends the watch; the run is read afterwards either way.
189
+ async function watch(client: LoadTestClient, a: Admitted, signal: AbortSignal, tracker: Tracker): Promise<number | undefined> {
190
+ const own = new AbortController();
191
+ const log = new SessionLog();
192
+ let waited: number | undefined;
193
+ try {
194
+ for await (const frame of followSession(client, a.sessionId, {
195
+ signal: AbortSignal.any([signal, own.signal]),
196
+ previews: ["stigmer.run.liveness"],
197
+ })) {
198
+ if (frame.frame.case === "stigmerRunLiveness" && frame.frame.value.runId === a.runId) {
199
+ const awaiting = frame.frame.value.awaitingSandboxFor;
200
+ if (awaiting !== undefined) waited = Math.max(waited ?? 0, durationMs(awaiting));
201
+ }
202
+ if (!log.applyFrame(frame)) continue;
203
+ const turn = turnOf(log.snapshot(), a.runId);
204
+ if (turn?.status === undefined) continue;
205
+ if (STARTED_PHASES.has(turn.status.phase)) tracker.started(a.runId);
206
+ if (turn.ended) {
207
+ tracker.ended(a.runId);
208
+ break;
209
+ }
210
+ }
211
+ } catch {
212
+ // A refused follow: the run's own read says how it stands.
213
+ } finally {
214
+ own.abort();
215
+ }
216
+ return waited;
217
+ }
218
+
219
+ // Terminate what is still open, delete each conversation, then the agent;
220
+ // return what could not be deleted.
221
+ async function cleanUp(client: LoadTestClient, admitted: readonly Admitted[], runs: ReadonlyMap<string, Run>, agentId: string): Promise<string[]> {
222
+ const left: string[] = [];
223
+ await Promise.all(
224
+ admitted
225
+ .filter((a) => !isTerminalPhase(runs.get(a.runId)?.status?.phase ?? RunPhase.RUN_PHASE_UNSPECIFIED))
226
+ .map((a) => client.run.terminate({ id: a.runId, reason: TERMINATE_REASON }).catch(() => undefined)),
227
+ );
228
+ await Promise.all(
229
+ admitted.map(async (a) => {
230
+ try {
231
+ await client.session.delete(a.sessionId);
232
+ } catch {
233
+ left.push(`conversation ${a.sessionId}`);
234
+ }
235
+ }),
236
+ );
237
+ if (agentId !== "") {
238
+ try {
239
+ await client.agent.delete(agentId);
240
+ } catch {
241
+ left.push(`agent ${agentId}`);
242
+ }
243
+ }
244
+ return left;
245
+ }
246
+
247
+ function durationMs(duration: Duration): number {
248
+ return Number(duration.seconds) * 1000 + Math.floor(duration.nanos / 1_000_000);
249
+ }
250
+
251
+ // The burst's counts, told to the caller each time one changes.
252
+ class Tracker {
253
+ private readonly startedRuns = new Set<string>();
254
+ private readonly endedRuns = new Set<string>();
255
+ private admitted: readonly string[] = [];
256
+ private refused = 0;
257
+ private lastTold = "";
258
+
259
+ constructor(
260
+ private readonly total: number,
261
+ private readonly onProgress: ((progress: BurstProgress) => void) | undefined,
262
+ ) {}
263
+
264
+ sent(admitted: readonly string[], refused: number): void {
265
+ this.admitted = admitted;
266
+ this.refused = refused;
267
+ this.tell();
268
+ }
269
+
270
+ started(runId: string): void {
271
+ if (this.startedRuns.has(runId)) return;
272
+ this.startedRuns.add(runId);
273
+ this.tell();
274
+ }
275
+
276
+ // Once per run: its watch stops at its end.
277
+ ended(runId: string): void {
278
+ this.endedRuns.add(runId);
279
+ this.tell();
280
+ }
281
+
282
+ // Told only when a count moved: a run that ends after it started changes none.
283
+ private tell(): void {
284
+ const waiting = this.admitted.filter((id) => !this.startedRuns.has(id) && !this.endedRuns.has(id)).length;
285
+ const progress = { sent: this.total, started: this.startedRuns.size, waiting, refused: this.refused };
286
+ const key = JSON.stringify(progress);
287
+ if (key === this.lastTold) return;
288
+ this.lastTold = key;
289
+ this.onProgress?.(progress);
290
+ }
291
+ }