@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,183 @@
1
+ // `stigmer load-test --agents <n>`: start n agents at the same moment on the
2
+ // connected server and report how many started, how long each waited for a
3
+ // sandbox, and which were refused and why. A top-level verb in "Run agents".
4
+ //
5
+ // Thin handler: check the flags, resolve the server and the organization,
6
+ // say the budget before spending it, run the burst (burst.ts), print the
7
+ // report (report.ts). The CLI's laws hold: the report is data on stdout
8
+ // (`-o table|json|yaml`), the budget, the progress and the cleanup are on
9
+ // stderr, and there is no prompt (it destroys nothing of the person's;
10
+ // `stigmer run` spends without one).
11
+ //
12
+ // The budget is the whole burst's (`--max-usd`, $1 by default), split evenly
13
+ // into each run's `max_cost_usd`; a run stops once its estimate reaches its
14
+ // share, and one model call can go past it. There is no cap on n: the budget
15
+ // is the guard, and a number the tool refused would be a fleet size of its
16
+ // own.
17
+ //
18
+ // Exit codes are the CLI's table: 0 when the burst ran and was reported,
19
+ // whatever it found (the report is the verdict); a refusal before the burst
20
+ // (the key, the organization, the agent's create) exits with its own code;
21
+ // 1 when the cleanup left something, listed on stderr; 130 after Ctrl-C,
22
+ // once the cleanup ran.
23
+
24
+ import type { Command } from "commander";
25
+ import { ensureAuthenticated, resolveOrganization } from "../../config/index.js";
26
+ import { CliExitError, ExitCode, UsageError } from "../../errors/index.js";
27
+ import type { OutputFlags } from "../../output/index.js";
28
+ import { dialedServerAddress } from "../../runtime.js";
29
+ import { globalOrg, readFormat } from "../shared.js";
30
+ import type { BurstProgress } from "./burst.js";
31
+
32
+ interface LoadTestFlags extends OutputFlags {
33
+ agents?: string;
34
+ model?: string;
35
+ message?: string;
36
+ maxUsd?: string;
37
+ waitMinutes?: string;
38
+ }
39
+
40
+ /** What each agent is asked when `--message` is not given. */
41
+ export const DEFAULT_MESSAGE = "Say hello in one word.";
42
+
43
+ const DEFAULT_MAX_USD = 1;
44
+ const DEFAULT_WAIT_MINUTES = 20;
45
+
46
+ export function registerLoadTest(program: Command): void {
47
+ program
48
+ .command("load-test")
49
+ .description("start many agents at once and report how many started, how long each waited, and which were refused")
50
+ .option("--agents <n>", "how many agents to start at the same moment (required)")
51
+ .option("--model <id>", "the model each run uses; the agent's default when unset")
52
+ .option("--message <text>", `what each agent is asked (default "${DEFAULT_MESSAGE}")`)
53
+ .option("--max-usd <total>", `the whole burst's budget in US dollars, split evenly across the runs (default ${DEFAULT_MAX_USD})`)
54
+ .option("--wait-minutes <m>", `how long to watch for runs to start before calling them still waiting (default ${DEFAULT_WAIT_MINUTES})`)
55
+ .option("-o, --output <format>", "output format: table, json, or yaml")
56
+ .action((options: LoadTestFlags, command: Command) => runLoadTest(options, command));
57
+ }
58
+
59
+ /** The flags, checked: a count of at least one, a positive budget and watch. */
60
+ export function parseFlags(options: LoadTestFlags): { agents: number; maxUsd: number; waitMinutes: number } {
61
+ const agents = Number(options.agents ?? "");
62
+ if (!Number.isInteger(agents) || agents < 1) {
63
+ throw new UsageError("--agents takes a whole number of at least 1");
64
+ }
65
+ const maxUsd = options.maxUsd === undefined ? DEFAULT_MAX_USD : Number(options.maxUsd);
66
+ if (!Number.isFinite(maxUsd) || maxUsd <= 0) {
67
+ throw new UsageError("--max-usd takes an amount above 0, in US dollars");
68
+ }
69
+ const waitMinutes = options.waitMinutes === undefined ? DEFAULT_WAIT_MINUTES : Number(options.waitMinutes);
70
+ if (!Number.isFinite(waitMinutes) || waitMinutes <= 0) {
71
+ throw new UsageError("--wait-minutes takes a number of minutes above 0");
72
+ }
73
+ return { agents, maxUsd, waitMinutes };
74
+ }
75
+
76
+ async function runLoadTest(options: LoadTestFlags, command: Command): Promise<void> {
77
+ const { agents, maxUsd, waitMinutes } = parseFlags(options);
78
+ const format = readFormat(options);
79
+ const [{ connectBackend }, { runBurst }, report, { formatElapsed }] = await Promise.all([
80
+ import("../../backend.js"),
81
+ import("./burst.js"),
82
+ import("./report.js"),
83
+ import("@stigmer/client"),
84
+ ]);
85
+ const client = connectBackend();
86
+ ensureAuthenticated(client.config);
87
+ const org = resolveOrganization(client.config, globalOrg(command));
88
+ const server = dialedServerAddress()?.address ?? "";
89
+ const shareUsd = maxUsd / agents;
90
+
91
+ const where = [org === "" ? "" : ` in ${org}`, server === "" ? "" : ` on ${server}`].join("");
92
+ process.stderr.write(
93
+ `Starting ${agents} agent${agents === 1 ? "" : "s"} at once${where}.\n` +
94
+ `Budget ${report.usd(maxUsd)}, split across the runs: each stops once it has spent ${report.usd(shareUsd)}. One model call can go past a run's share.\n`,
95
+ );
96
+
97
+ const controller = new AbortController();
98
+ const onSignal = (): void => controller.abort();
99
+ process.once("SIGINT", onSignal);
100
+ process.once("SIGTERM", onSignal);
101
+ const progress = progressPrinter(process.stderr, formatElapsed);
102
+ try {
103
+ const result = await runBurst(client.stigmer, {
104
+ org,
105
+ agents,
106
+ model: options.model ?? "",
107
+ message: options.message ?? DEFAULT_MESSAGE,
108
+ shareUsd,
109
+ waitMs: waitMinutes * 60_000,
110
+ signal: controller.signal,
111
+ onProgress: progress.update,
112
+ });
113
+ progress.stop();
114
+ process.stderr.write(cleanupLine(result.sightings.filter((s) => s.sessionId !== "").length, result.leftBehind));
115
+ const built = report.buildReport(
116
+ { server, org, agent: result.agent, requested: agents, budgetUsd: maxUsd, shareUsd },
117
+ result.sightings,
118
+ result.leftBehind,
119
+ );
120
+ process.stdout.write(report.renderReport(built, format));
121
+ if (result.interrupted) throw new CliExitError("", ExitCode.Interrupted);
122
+ if (result.leftBehind.length > 0) throw new CliExitError("", ExitCode.General);
123
+ } finally {
124
+ progress.stop();
125
+ process.removeListener("SIGINT", onSignal);
126
+ process.removeListener("SIGTERM", onSignal);
127
+ }
128
+ }
129
+
130
+ /** The cleanup's line: what was deleted, or what is left to remove by hand. */
131
+ export function cleanupLine(conversations: number, leftBehind: readonly string[]): string {
132
+ if (leftBehind.length > 0) return `Could not delete, remove by hand: ${leftBehind.join(", ")}\n`;
133
+ const deleted = conversations === 0 ? "the agent" : `${conversations} conversation${conversations === 1 ? "" : "s"} and the agent`;
134
+ return `Cleaned up: deleted ${deleted}.\n`;
135
+ }
136
+
137
+ /** The stream the progress line is written to. */
138
+ export interface ProgressStream {
139
+ readonly isTTY?: boolean;
140
+ write(text: string): boolean;
141
+ }
142
+
143
+ /**
144
+ * The progress line, "6 sent · 3 started · 2 waiting · 1 refused · 42s": on
145
+ * a terminal one line rewritten in place, its time ticking each second; off
146
+ * one, a line per change. `stop` ends the line; calling it again does nothing.
147
+ */
148
+ export function progressPrinter(
149
+ stream: ProgressStream,
150
+ elapsed: (ms: number) => string,
151
+ now: () => number = Date.now,
152
+ ): { update: (progress: BurstProgress) => void; stop: () => void } {
153
+ const begin = now();
154
+ let last: BurstProgress | undefined;
155
+ let ticker: ReturnType<typeof setInterval> | undefined;
156
+ const text = (p: BurstProgress): string => {
157
+ const parts = [`${p.sent} sent`, `${p.started} started`, `${p.waiting} waiting`];
158
+ if (p.refused > 0) parts.push(`${p.refused} refused`);
159
+ parts.push(elapsed(now() - begin));
160
+ return parts.join(" · ");
161
+ };
162
+ const draw = (): void => {
163
+ if (last !== undefined) stream.write(`\r\u001b[2K${text(last)}`);
164
+ };
165
+ return {
166
+ update(progress) {
167
+ last = progress;
168
+ if (stream.isTTY !== true) {
169
+ stream.write(`${text(progress)}\n`);
170
+ return;
171
+ }
172
+ draw();
173
+ ticker ??= setInterval(draw, 1000);
174
+ ticker.unref();
175
+ },
176
+ stop() {
177
+ if (ticker === undefined) return;
178
+ clearInterval(ticker);
179
+ ticker = undefined;
180
+ stream.write("\n");
181
+ },
182
+ };
183
+ }
@@ -0,0 +1,302 @@
1
+ // What `stigmer load-test` reports: each run's start and ending, read apart,
2
+ // and the burst's summary, as a table with sentences or as one JSON (or
3
+ // YAML) document. Pure: the engine (burst.ts) hands in what it saw, and this
4
+ // module decides the words.
5
+ //
6
+ // A run's start is one of five words. `started` once the runner stamped
7
+ // `status.started_at`; `refused` when the create itself was answered with an
8
+ // error (its code and the server's own sentence, verbatim, so a plan's limit
9
+ // reads in the server's words without this tool knowing them); `wait ran out`
10
+ // when the run ended `no_sandbox_room`; `never started` for any other ending
11
+ // before a start; `still waiting` when the watch ended first.
12
+ //
13
+ // Two times per run, both from the server's side, never this machine's clock:
14
+ // - to start: `status.started_at` (the runner) minus
15
+ // `status.audit.spec_audit.created_at` (the server, when it accepted the
16
+ // message). A `started_at` written without milliseconds (it is a
17
+ // string; the create's stamp is a Timestamp), or a negative difference,
18
+ // is "unclear" and left out of the figures.
19
+ // - waited for a sandbox: the longest `awaiting_sandbox_for` the run's
20
+ // liveness carried. The server's own number counts from its first "no
21
+ // room" to the answer that found room, and liveness is sent on each "no
22
+ // room" answer, at most one backoff (15 s) apart, so the server's figure
23
+ // is at least this one and at most "to start": the report writes "≥".
24
+ // Liveness is the serving process's memory, so the report says a run
25
+ // "reported" a wait, and when none did it says so in its own line: a
26
+ // fleet that cannot run out of room never reads as one that held.
27
+ //
28
+ // Spend is the sum of the runs' own estimates
29
+ // (`status.streaming_usage.estimated_cost_usd`), the number each run's
30
+ // budget share is enforced against.
31
+
32
+ import { timestampMs } from "@bufbuild/protobuf/wkt";
33
+ import type { Run } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
34
+ import { formatElapsed, turnPhaseOf } from "@stigmer/client";
35
+ import { stringify } from "yaml";
36
+ import type { OutputFormat } from "../../output/index.js";
37
+ import { renderTable } from "../../output/index.js";
38
+
39
+ /** How a run's start went. */
40
+ export type StartOutcome = "started" | "refused" | "wait ran out" | "never started" | "still waiting";
41
+
42
+ /** The server's answer to a create it refused: its code word and its own sentence. */
43
+ export interface Refusal {
44
+ readonly code: string;
45
+ readonly message: string;
46
+ }
47
+
48
+ /** What the engine saw of one run. */
49
+ export interface RunSighting {
50
+ /** 1-based, in the order the creates were sent. */
51
+ readonly index: number;
52
+ /** The create's refusal; the run was never made. */
53
+ readonly refusal?: Refusal;
54
+ /** The run as read after the watch; absent when it was refused, or could not be read. */
55
+ readonly run?: Run;
56
+ readonly runId: string;
57
+ readonly sessionId: string;
58
+ /** The longest wait for a sandbox any liveness frame carried, in ms; undefined when none was reported. */
59
+ readonly waitedMs?: number;
60
+ }
61
+
62
+ /** One run's row of the report. */
63
+ export interface RunOutcome {
64
+ readonly index: number;
65
+ readonly runId: string;
66
+ readonly sessionId: string;
67
+ readonly start: StartOutcome;
68
+ /** Ms from the message accepted to the agent starting; null when not started or unclear. */
69
+ readonly toStartMs: number | null;
70
+ /** Whether a started run's stamps were too coarse, or out of order, to time it. */
71
+ readonly toStartUnclear: boolean;
72
+ /** The longest wait for a sandbox the run reported, in ms (at least); null when it reported none. */
73
+ readonly waitedForRoomMs: number | null;
74
+ /** How a started run ended, or what ended one that never started; "" while it works or when refused. */
75
+ readonly ending: string;
76
+ readonly stopCause: string;
77
+ readonly stopKind: string;
78
+ /** The run's own spend estimate in USD; null when it has none. */
79
+ readonly costUsd: number | null;
80
+ readonly refusal: Refusal | null;
81
+ }
82
+
83
+ /** Median, 90th percentile (nearest rank) and longest of a set of times, in ms. */
84
+ export interface Figures {
85
+ readonly median: number | null;
86
+ readonly p90: number | null;
87
+ readonly longest: number | null;
88
+ }
89
+
90
+ /** The whole report, as `-o json` prints it. */
91
+ export interface LoadTestReport {
92
+ readonly server: string;
93
+ readonly org: string;
94
+ readonly agent: string;
95
+ readonly requested: number;
96
+ readonly budgetUsd: number;
97
+ readonly shareUsd: number;
98
+ readonly counts: {
99
+ readonly started: number;
100
+ readonly refused: number;
101
+ readonly waitRanOut: number;
102
+ readonly neverStarted: number;
103
+ readonly stillWaiting: number;
104
+ };
105
+ readonly toStartMs: Figures & { readonly unclear: number };
106
+ readonly waitedForRoomMs: Figures & { readonly runs: number };
107
+ readonly anyWaitReported: boolean;
108
+ readonly refusals: ReadonlyArray<Refusal & { readonly count: number }>;
109
+ readonly spentUsd: number;
110
+ readonly runs: readonly RunOutcome[];
111
+ /** What cleanup could not delete, as "<kind> <id>". */
112
+ readonly leftBehind: readonly string[];
113
+ }
114
+
115
+ /** The burst's frame: where it ran and what it was allowed to spend. */
116
+ export interface BurstFrame {
117
+ readonly server: string;
118
+ readonly org: string;
119
+ readonly agent: string;
120
+ readonly requested: number;
121
+ readonly budgetUsd: number;
122
+ readonly shareUsd: number;
123
+ }
124
+
125
+ const NO_SANDBOX_ROOM = "no_sandbox_room";
126
+ const COST_CAP = "cost_cap";
127
+
128
+ // A stamp's fraction of a second: three digits or more is millisecond-precise.
129
+ const FRACTION = /\.(\d+)/;
130
+
131
+ /** One run's row, from what the engine saw. */
132
+ export function outcomeOf(sighting: RunSighting): RunOutcome {
133
+ const base = {
134
+ index: sighting.index,
135
+ runId: sighting.runId,
136
+ sessionId: sighting.sessionId,
137
+ waitedForRoomMs: sighting.waitedMs ?? null,
138
+ };
139
+ if (sighting.refusal !== undefined) {
140
+ return { ...base, start: "refused", toStartMs: null, toStartUnclear: false, ending: "", stopCause: "", stopKind: "", costUsd: null, refusal: sighting.refusal };
141
+ }
142
+ const status = sighting.run?.status;
143
+ const stopCause = status?.stopCause ?? "";
144
+ const stopKind = status?.stopDetail?.kind ?? "";
145
+ const phase = turnPhaseOf(status?.phase ?? 0);
146
+ const ended = phase === "completed" || phase === "failed" || phase === "cancelled" || phase === "terminated";
147
+ const cost = status?.streamingUsage?.estimatedCostUsd;
148
+ const common = { ...base, stopCause, stopKind, costUsd: cost === undefined ? null : cost, refusal: null };
149
+ const startedAt = status?.startedAt ?? "";
150
+ if (startedAt !== "") {
151
+ const toStart = toStartOf(sighting.run, startedAt);
152
+ return {
153
+ ...common,
154
+ start: "started",
155
+ toStartMs: toStart,
156
+ toStartUnclear: toStart === null,
157
+ ending: ended ? endingOf(phase, stopCause, stopKind) : "",
158
+ };
159
+ }
160
+ const notStarted = { ...common, toStartMs: null, toStartUnclear: false };
161
+ if (stopKind === NO_SANDBOX_ROOM) return { ...notStarted, start: "wait ran out", ending: "" };
162
+ if (ended) return { ...notStarted, start: "never started", ending: endingOf(phase, stopCause, stopKind) };
163
+ return { ...notStarted, start: "still waiting", ending: "" };
164
+ }
165
+
166
+ /** The report of a burst: every run's row, the counts, the figures and the spend. */
167
+ export function buildReport(frame: BurstFrame, sightings: readonly RunSighting[], leftBehind: readonly string[]): LoadTestReport {
168
+ const runs = sightings.map(outcomeOf);
169
+ const count = (start: StartOutcome): number => runs.filter((run) => run.start === start).length;
170
+ const started = runs.filter((run) => run.start === "started");
171
+ const waits = runs.flatMap((run) => (run.waitedForRoomMs === null ? [] : [run.waitedForRoomMs]));
172
+ return {
173
+ ...frame,
174
+ counts: {
175
+ started: started.length,
176
+ refused: count("refused"),
177
+ waitRanOut: count("wait ran out"),
178
+ neverStarted: count("never started"),
179
+ stillWaiting: count("still waiting"),
180
+ },
181
+ toStartMs: {
182
+ ...figuresOf(started.flatMap((run) => (run.toStartMs === null ? [] : [run.toStartMs]))),
183
+ unclear: started.filter((run) => run.toStartUnclear).length,
184
+ },
185
+ waitedForRoomMs: { ...figuresOf(waits), runs: waits.length },
186
+ anyWaitReported: waits.length > 0,
187
+ refusals: groupRefusals(runs),
188
+ spentUsd: runs.reduce((sum, run) => sum + (run.costUsd ?? 0), 0),
189
+ runs,
190
+ leftBehind,
191
+ };
192
+ }
193
+
194
+ /** The report in the asked format: table and summary, or the JSON or YAML document. */
195
+ export function renderReport(report: LoadTestReport, format: OutputFormat): string {
196
+ if (format === "json") return `${JSON.stringify(report, null, 2)}\n`;
197
+ if (format === "yaml") return stringify(report);
198
+ return `${renderRuns(report.runs)}\n${summaryLines(report).join("\n")}\n`;
199
+ }
200
+
201
+ /** The burst's summary sentences, in the order the report prints them. */
202
+ export function summaryLines(report: LoadTestReport): string[] {
203
+ const lines = [countsLine(report)];
204
+ const toStart = report.toStartMs;
205
+ if (toStart.median !== null) {
206
+ lines.push(`To start: ${figuresText(toStart)}.`);
207
+ }
208
+ if (toStart.unclear > 0) {
209
+ lines.push(`To start was unclear for ${plural(toStart.unclear, "run")}: a stamp was too coarse to time it.`);
210
+ }
211
+ if (report.anyWaitReported) {
212
+ const waited = report.waitedForRoomMs;
213
+ lines.push(`Waited for a sandbox, ${plural(waited.runs, "run")}: ${figuresText(waited)} (at least).`);
214
+ } else {
215
+ lines.push("No run reported waiting for a sandbox during the burst.");
216
+ }
217
+ for (const refusal of report.refusals) {
218
+ lines.push(`Refused ${refusal.count}: ${refusal.code}, "${refusal.message}"`);
219
+ }
220
+ lines.push(`Spent about ${usd(report.spentUsd)}, by the runs' own estimates.`);
221
+ return lines;
222
+ }
223
+
224
+ /** A dollar amount: cents, or four places below a cent so a tiny spend is not "$0.00". */
225
+ export function usd(amount: number): string {
226
+ return amount > 0 && amount < 0.01 ? `$${amount.toFixed(4)}` : `$${amount.toFixed(2)}`;
227
+ }
228
+
229
+ function renderRuns(runs: readonly RunOutcome[]): string {
230
+ const rows = runs.map((run) => [
231
+ String(run.index),
232
+ run.start,
233
+ run.toStartUnclear ? "unclear" : duration(run.toStartMs),
234
+ run.waitedForRoomMs === null ? "-" : `≥ ${formatElapsed(run.waitedForRoomMs)}`,
235
+ run.ending === "" ? "-" : run.ending,
236
+ run.costUsd === null ? "-" : usd(run.costUsd),
237
+ ]);
238
+ return renderTable(["#", "START", "TO START", "WAITED FOR A SANDBOX", "ENDING", "COST"], rows);
239
+ }
240
+
241
+ function countsLine(report: LoadTestReport): string {
242
+ const { counts } = report;
243
+ const parts = [
244
+ `${counts.started} started`,
245
+ counts.refused > 0 ? `${counts.refused} refused` : "",
246
+ counts.waitRanOut > 0 ? `${counts.waitRanOut} wait ran out` : "",
247
+ counts.neverStarted > 0 ? `${counts.neverStarted} never started` : "",
248
+ counts.stillWaiting > 0 ? `${counts.stillWaiting} still waiting` : "",
249
+ ].filter((part) => part !== "");
250
+ return `${plural(report.requested, "agent")}: ${parts.join(", ")}.`;
251
+ }
252
+
253
+ function figuresText(figures: Figures): string {
254
+ return `median ${duration(figures.median)}, 90th percentile ${duration(figures.p90)}, longest ${duration(figures.longest)}`;
255
+ }
256
+
257
+ function duration(ms: number | null): string {
258
+ return ms === null ? "-" : formatElapsed(ms);
259
+ }
260
+
261
+ function plural(count: number, noun: string): string {
262
+ return `${count} ${noun}${count === 1 ? "" : "s"}`;
263
+ }
264
+
265
+ // How an ended run ended, in the report's words: a completion, its budget,
266
+ // or the stop's cause and kind as the run names them.
267
+ function endingOf(phase: string | undefined, stopCause: string, stopKind: string): string {
268
+ if (stopKind === COST_CAP) return "stopped at its budget";
269
+ if (stopCause === "" && phase === "completed") return "completed";
270
+ const cause = stopCause === "" ? (phase ?? "ended") : stopCause;
271
+ return stopKind === "" ? cause : `${cause} (${stopKind})`;
272
+ }
273
+
274
+ // `started_at` minus the create's stamp, when `started_at` is
275
+ // millisecond-precise and the pair is in order; null otherwise.
276
+ function toStartOf(run: Run | undefined, startedAt: string): number | null {
277
+ const created = run?.status?.audit?.specAudit?.createdAt;
278
+ const fraction = FRACTION.exec(startedAt);
279
+ if (created === undefined || fraction === null || fraction[1].length < 3) return null;
280
+ const started = Date.parse(startedAt);
281
+ const ms = started - timestampMs(created);
282
+ return Number.isNaN(started) || ms < 0 ? null : ms;
283
+ }
284
+
285
+ function figuresOf(values: readonly number[]): Figures {
286
+ if (values.length === 0) return { median: null, p90: null, longest: null };
287
+ const sorted = [...values].sort((a, b) => a - b);
288
+ const rank = (p: number): number => sorted[Math.max(0, Math.ceil(p * sorted.length) - 1)];
289
+ return { median: rank(0.5), p90: rank(0.9), longest: sorted[sorted.length - 1] };
290
+ }
291
+
292
+ function groupRefusals(runs: readonly RunOutcome[]): Array<Refusal & { count: number }> {
293
+ const groups = new Map<string, Refusal & { count: number }>();
294
+ for (const run of runs) {
295
+ if (run.refusal === null) continue;
296
+ const key = `${run.refusal.code}\u0000${run.refusal.message}`;
297
+ const group = groups.get(key);
298
+ if (group === undefined) groups.set(key, { ...run.refusal, count: 1 });
299
+ else group.count += 1;
300
+ }
301
+ return [...groups.values()];
302
+ }
@@ -22,12 +22,18 @@
22
22
  // backend instead (auth/token.ts, createBackendTokenSource), which refreshes the
23
23
  // sign-in and saves it as every other command does. A given key (flag or
24
24
  // environment) still wins and is never refreshed.
25
+ //
26
+ // This server runs on the person's machine, as their coding agent's child,
27
+ // so it tells the server it shares their disk (`localFiles`): run_agent may
28
+ // then hand a run the project files a call names, inside the folders the
29
+ // coding agent lists as its workspace. The server applies it to the stdio
30
+ // roster alone; its HTTP rosters never read a path.
25
31
 
26
32
  import type { Command } from "commander";
27
- import { type Config, activeBackend } from "../config/config.js";
33
+ import { type Config, activeBackend, hasSignIn } from "../config/config.js";
28
34
  import { DEFAULT_CLOUD_ENDPOINT } from "../config/resolve.js";
29
35
 
30
- /** The cloud backend whose sign-in the server's credential comes from. */
36
+ /** The signed-in backend the server's credential comes from. */
31
37
  export interface CloudSignIn {
32
38
  readonly name: string;
33
39
  /** The address the server dials, the entry's own or Stigmer Cloud's. */
@@ -81,10 +87,12 @@ async function runMcpServer(flags: McpServerFlags): Promise<void> {
81
87
  // Imported lazily so `stigmer --help`/`version` never pull in the MCP stack.
82
88
  const { run, defaultConfig } = await import("@stigmer/mcp-server");
83
89
  const { createBackendTokenSource } = await import("../auth/token.js");
84
- const options =
85
- signIn === undefined
90
+ const options = {
91
+ localFiles: true,
92
+ ...(signIn === undefined
86
93
  ? {}
87
- : { getAccessToken: createBackendTokenSource(signIn.name, signIn.endpoint).getAccessToken };
94
+ : { getAccessToken: createBackendTokenSource(signIn.name, signIn.endpoint).getAccessToken }),
95
+ };
88
96
 
89
97
  const controller = new AbortController();
90
98
  const onSignal = (): void => controller.abort();
@@ -102,8 +110,8 @@ async function runMcpServer(flags: McpServerFlags): Promise<void> {
102
110
  * Bridge the active backend into the server's environment, but only where
103
111
  * unset, so a pre-existing environment variable (or a flag bridged before this)
104
112
  * wins. The local daemon is reached without auth; a named backend contributes
105
- * its endpoint, and a self-hosted entry its API key. A cloud entry's sign-in is
106
- * returned instead of bridged, for the caller to hand the server as a token
113
+ * its endpoint, and a self-hosted entry with no sign-in its API key. A sign-in
114
+ * (any cloud entry, or a selfhost one signed in to) is returned instead of bridged, for the caller to hand the server as a token
107
115
  * provider. The credential goes only to its own backend: when the environment
108
116
  * already names another address (a runner spawning this command for its
109
117
  * server), none applies, and none does when a key was already given.
@@ -122,7 +130,7 @@ export function applyConfigEnv(config: Config, env: NodeJS.ProcessEnv): CloudSig
122
130
  if (endpoint === undefined) return undefined;
123
131
  setIfEmpty(env, "STIGMER_SERVER_ADDRESS", endpoint);
124
132
  if (env.STIGMER_SERVER_ADDRESS !== endpoint || isSet(env.STIGMER_API_KEY)) return undefined;
125
- if (entry.type === "cloud") return { name, endpoint };
133
+ if (entry.type === "cloud" || hasSignIn(entry)) return { name, endpoint };
126
134
  setIfEmpty(env, "STIGMER_API_KEY", entry.api_key);
127
135
  return undefined;
128
136
  }
@@ -35,6 +35,7 @@ import { type Command, Option } from "commander";
35
35
  import {
36
36
  contextOrganizationLabel,
37
37
  ensureAuthenticated,
38
+ knownConsoleURL,
38
39
  resolveContextOrganization,
39
40
  resolveOrganization,
40
41
  } from "../../config/index.js";
@@ -114,7 +115,12 @@ export function registerProviderKey(program: Command): void {
114
115
  openSession(command, "writes keys"),
115
116
  import("../../output/command-result.js"),
116
117
  ]);
117
- const apiKey = await resources.readProviderKey(provider, options.keyStdin === true, await keyIo());
118
+ const apiKey = await resources.readProviderKey(
119
+ provider,
120
+ options.keyStdin === true,
121
+ await keyIo(),
122
+ knownConsoleURL(session.client.config),
123
+ );
118
124
  renderResult(
119
125
  await resources.setProviderKey(session.client.stigmer, session.org, provider, apiKey, baseUrl),
120
126
  format,