@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
@@ -11,6 +11,17 @@
11
11
  // (Anthropic + skip: the key setup saves; the runner reaches other providers
12
12
  // by keys exported in the shell, local/provider-reach.ts).
13
13
  //
14
+ // `--api-key-stdin` reads the key from stdin instead of the command line,
15
+ // where a shell's history and a coding agent's transcript would keep it
16
+ // (`printenv ANTHROPIC_API_KEY | stigmer setup --provider anthropic
17
+ // --api-key-stdin`); it implies `--provider anthropic` and refuses a terminal,
18
+ // where the interactive `stigmer setup` asks at a hidden prompt instead.
19
+ //
20
+ // A key given to setup is checked with Anthropic before it is saved, on both
21
+ // paths (local/model-key-step.ts): the flag path refuses a key Anthropic
22
+ // rejects with exit code 1 and saves nothing, and saves a key Anthropic did not
23
+ // answer for with a line saying so; the interactive path asks again.
24
+ //
14
25
  // Setup deliberately has NO model concept: the platform model registry owns
15
26
  // the execution default, and per-run overrides belong to `stigmer run
16
27
  // --model`. A setup-level pin would look authoritative and reach no
@@ -21,9 +32,10 @@ import { homedir } from "node:os";
21
32
  import { type OutputFlags, CommandResult, renderResult } from "../output/index.js";
22
33
  import { addResultFlags, resultFormat } from "./shared.js";
23
34
 
24
- interface SetupFlags extends OutputFlags {
35
+ export interface SetupFlags extends OutputFlags {
25
36
  provider?: string;
26
37
  apiKey?: string;
38
+ apiKeyStdin?: boolean;
27
39
  operatorEmail?: string;
28
40
  operatorName?: string;
29
41
  }
@@ -34,13 +46,15 @@ export function registerSetup(program: Command): void {
34
46
  .description("configure the LLM provider and operator identity for local execution")
35
47
  .option("--provider <name>", "provider: anthropic, or skip to clear (non-interactive)")
36
48
  .option("--api-key <key>", "Anthropic API key")
49
+ .option("--api-key-stdin", "read the Anthropic API key from stdin (keeps it out of history and transcripts)")
37
50
  .option("--operator-email <email>", "operator identity for local caller attribution (non-interactive)")
38
51
  .option("--operator-name <name>", "operator display name (requires --operator-email)")
39
52
  .action((options: SetupFlags) => runSetup(options));
40
53
  addResultFlags(setup);
41
54
  }
42
55
 
43
- async function runSetup(options: SetupFlags): Promise<void> {
56
+ async function runSetup(flags: SetupFlags): Promise<void> {
57
+ const options = await withStdinKey(flags);
44
58
  const { load, save } = await import("../config/config.js");
45
59
  const { PROVIDER_CHOICES, applyChoice, applyOperatorIdentity, runInteractiveWizard } =
46
60
  await import("../local/setup/wizard.js");
@@ -55,6 +69,7 @@ async function runSetup(options: SetupFlags): Promise<void> {
55
69
  options.operatorName !== undefined;
56
70
 
57
71
  let updated: typeof config;
72
+ let unchecked = false;
58
73
  if (nonInteractive) {
59
74
  updated = config;
60
75
  if (options.provider !== undefined) {
@@ -64,6 +79,9 @@ async function runSetup(options: SetupFlags): Promise<void> {
64
79
  `Valid providers: ${PROVIDER_CHOICES.join(", ")}`,
65
80
  ]);
66
81
  }
82
+ if (provider === "anthropic" && (options.apiKey ?? "").trim() !== "") {
83
+ unchecked = await refuseRejectedKey(options.apiKey!.trim());
84
+ }
67
85
  updated = applyChoice(updated, provider as (typeof PROVIDER_CHOICES)[number], {
68
86
  apiKey: options.apiKey,
69
87
  });
@@ -90,8 +108,64 @@ async function runSetup(options: SetupFlags): Promise<void> {
90
108
  save(updated);
91
109
 
92
110
  const result = CommandResult.success("Configuration saved");
111
+ if (unchecked) {
112
+ const { KEY_UNCHECKED } = await import("../local/model-key-step.js");
113
+ result.hint(KEY_UNCHECKED);
114
+ }
93
115
  if (await isRunning(homedir())) {
94
116
  result.hint("Restart to apply: stigmer down && stigmer up");
95
117
  }
96
118
  renderResult(result, resultFormat(options));
97
119
  }
120
+
121
+ /**
122
+ * The flags with `--api-key-stdin` read into `apiKey`: refused beside
123
+ * `--api-key`, on a terminal, and when stdin is empty; the provider is
124
+ * Anthropic unless the flags said it.
125
+ */
126
+ export async function withStdinKey(
127
+ flags: SetupFlags,
128
+ io: { readonly stdinIsTty: boolean; readonly readStdin: () => Promise<string> } = {
129
+ stdinIsTty: process.stdin.isTTY === true,
130
+ readStdin: async () => {
131
+ const chunks: Buffer[] = [];
132
+ for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
133
+ return Buffer.concat(chunks).toString("utf8");
134
+ },
135
+ },
136
+ ): Promise<SetupFlags> {
137
+ if (flags.apiKeyStdin !== true) return flags;
138
+ const { UsageError } = await import("../errors/usage-error.js");
139
+ if (flags.apiKey !== undefined) {
140
+ throw new UsageError("--api-key and --api-key-stdin both give the key\n\nUse one.");
141
+ }
142
+ if (io.stdinIsTty) {
143
+ throw new UsageError(
144
+ "--api-key-stdin reads a key piped in, and stdin is a terminal\n\n" +
145
+ "Pipe it: printenv ANTHROPIC_API_KEY | stigmer setup --api-key-stdin\nor type it at a hidden prompt: stigmer setup",
146
+ );
147
+ }
148
+ const key = (await io.readStdin()).trim();
149
+ if (key === "") throw new UsageError("--api-key-stdin read nothing from stdin");
150
+ return { ...flags, provider: flags.provider ?? "anthropic", apiKey: key };
151
+ }
152
+
153
+ /**
154
+ * Check a key given by flag with Anthropic, where the runner would send it:
155
+ * a refused key ends the command with exit code 1 before anything is saved.
156
+ * Returns whether Anthropic did not answer (the key is saved, and the card
157
+ * says so).
158
+ */
159
+ async function refuseRejectedKey(key: string): Promise<boolean> {
160
+ const { ANTHROPIC_KEYS_URL, anthropicKeyTarget, KEY_REJECTED } = await import("../local/model-key-step.js");
161
+ const { checkAnthropicKey } = await import("../local/key-check.js");
162
+ const { CliExitError } = await import("../errors/cli-exit-error.js");
163
+ const { ExitCode } = await import("@stigmer/client/exit-codes");
164
+ const target = anthropicKeyTarget({ ...process.env, ANTHROPIC_API_KEY: key });
165
+ if (target === null) return false;
166
+ const check = await checkAnthropicKey(key, target.baseUrl);
167
+ if (check === "rejected") {
168
+ throw new CliExitError(`${KEY_REJECTED}.`, ExitCode.General, [`Nothing was saved. Get a key at ${ANTHROPIC_KEYS_URL}`]);
169
+ }
170
+ return check === "unchecked";
171
+ }
@@ -1,5 +1,6 @@
1
- // `stigmer status` — show the local stack's health (daemon, Temporal, server,
2
- // runner, web console) plus the effective LLM configuration.
1
+ // `stigmer status` — say which server the CLI uses (backend and address),
2
+ // then show the local stack's health (daemon, Temporal, server, runner, web
3
+ // console) plus the effective LLM configuration.
3
4
  //
4
5
  // Thin handler: build the structured result in the local subsystem and render
5
6
  // it. The local module loads lazily so `--help` stays fast.
@@ -11,7 +12,7 @@ import { addResultFlags, resultFormat } from "./shared.js";
11
12
  export function registerStatus(program: Command): void {
12
13
  const status = program
13
14
  .command("status")
14
- .description("show the status of the local Stigmer stack")
15
+ .description("show which server the CLI uses and the local stack's health")
15
16
  .action(async (options: OutputFlags) => {
16
17
  const { buildStatusResult } = await import("../local/status.js");
17
18
  renderResult(await buildStatusResult(), resultFormat(options));
@@ -13,6 +13,12 @@
13
13
  // started runner reaches, the same answer the server was handed (stigmer#1084).
14
14
  // A stack that does not start ends with why, in either shape: the failed
15
15
  // component, how it ended and its last stderr lines (stigmer#1845).
16
+ //
17
+ // The agents line also says what Anthropic made of the runner's key
18
+ // (stigmer#3036): the key is checked before the card calls it ready, and on a
19
+ // terminal a missing or refused key is asked for before the daemon starts, so
20
+ // the key entered reaches the runner in this start (local/model-key-step.ts).
21
+ // Off a terminal nothing is asked, and the check runs beside the start.
16
22
 
17
23
  import { homedir } from "node:os";
18
24
  import type { Command } from "commander";
@@ -21,7 +27,8 @@ import { ExitCode } from "@stigmer/client/exit-codes";
21
27
  import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
22
28
  import { SERVER_PORT } from "../local/constants.js";
23
29
  import type { UpReport } from "../local/daemon/launch.js";
24
- import { describeReach } from "../local/provider-reach.js";
30
+ import type { KeyStepOutcome } from "../local/model-key-step.js";
31
+ import { describeReach, type ProviderReach } from "../local/provider-reach.js";
25
32
  import { addResultFlags, resultFormat } from "./shared.js";
26
33
 
27
34
  interface UpFlags extends OutputFlags {
@@ -73,12 +80,26 @@ export function registerUp(program: Command): void {
73
80
  }
74
81
 
75
82
  async function runUp(run: UpRun, flags: OutputFlags): Promise<void> {
76
- process.stderr.write("Starting Stigmer local stack… (first run may take a moment)\n");
77
83
  const launch = await import("../local/daemon/launch.js");
84
+ const interactive =
85
+ process.stdin.isTTY === true && process.stderr.isTTY === true && resultFormat(flags) === "human";
86
+ let keyStep: Promise<KeyStepOutcome | undefined> = Promise.resolve(undefined);
87
+ if (!run.serverOnly) {
88
+ if (interactive) {
89
+ // Never ask for a key and then refuse to start.
90
+ const { dataDir } = await import("../local/paths.js");
91
+ launch.refuseRunningStack(dataDir(homedir()));
92
+ keyStep = Promise.resolve(await runKeyStep(true));
93
+ } else {
94
+ // A fault here (an unreadable config) is the launch's to report.
95
+ keyStep = runKeyStep(false).catch(() => undefined);
96
+ }
97
+ }
98
+ process.stderr.write("Starting Stigmer local stack… (first run may take a moment)\n");
78
99
 
79
100
  if (!run.foreground) {
80
101
  const report = await launch.up(run);
81
- await renderUpCard(run, flags, report);
102
+ await renderUpCard(run, flags, report, await keyStep);
82
103
  return;
83
104
  }
84
105
 
@@ -86,7 +107,7 @@ async function runUp(run: UpRun, flags: OutputFlags): Promise<void> {
86
107
  // detached shape would have returned — and the process then stays up,
87
108
  // mirroring the server's and runner's output, until a shutdown signal.
88
109
  const code = await launch.upForeground(run, homedir(), {
89
- onReady: (report) => renderUpCard(run, flags, report),
110
+ onReady: async (report) => renderUpCard(run, flags, report, await keyStep),
90
111
  });
91
112
  if (code !== 0) {
92
113
  // The daemon body ran as this process, so its record carries our PID; the
@@ -101,7 +122,31 @@ async function runUp(run: UpRun, flags: OutputFlags): Promise<void> {
101
122
  }
102
123
  }
103
124
 
104
- async function renderUpCard(run: UpRun, flags: OutputFlags, report: UpReport): Promise<void> {
125
+ /** The model key step over the real terminal, config file and Anthropic. */
126
+ async function runKeyStep(interactive: boolean): Promise<KeyStepOutcome | undefined> {
127
+ const [{ modelKeyStep }, { checkAnthropicKey }, { load, save }, { promptSecret }] = await Promise.all([
128
+ import("../local/model-key-step.js"),
129
+ import("../local/key-check.js"),
130
+ import("../config/config.js"),
131
+ import("../local/setup/prompt.js"),
132
+ ]);
133
+ return modelKeyStep({
134
+ env: process.env,
135
+ interactive,
136
+ loadConfig: () => load(),
137
+ saveConfig: (config) => save(config),
138
+ promptSecret,
139
+ write: (text) => process.stderr.write(text),
140
+ check: (key, baseUrl) => checkAnthropicKey(key, baseUrl),
141
+ });
142
+ }
143
+
144
+ async function renderUpCard(
145
+ run: UpRun,
146
+ flags: OutputFlags,
147
+ report: UpReport,
148
+ key: KeyStepOutcome | undefined,
149
+ ): Promise<void> {
105
150
  const result = CommandResult.success(run.serverOnly ? "Stigmer control plane is up" : "Stigmer local stack is up");
106
151
  const section = result.addSection("Endpoints");
107
152
  section.field("server", `http://localhost:${SERVER_PORT}`);
@@ -111,7 +156,7 @@ async function renderUpCard(run: UpRun, flags: OutputFlags, report: UpReport): P
111
156
  // server without a bundled export must not advertise a dead URL.
112
157
  section.field("console", `http://localhost:${SERVER_PORT}`);
113
158
  }
114
- addAgentsSection(result, report);
159
+ addAgentsSection(result, report, key);
115
160
  result.hint("Check status with: stigmer status");
116
161
  result.hint(run.foreground ? "Stop it with: Ctrl-C (or stigmer down from another shell)" : "Stop it with: stigmer down");
117
162
  renderResult(result, resultFormat(flags));
@@ -129,19 +174,40 @@ async function consoleServed(): Promise<boolean> {
129
174
  return isWebConsoleAvailable();
130
175
  }
131
176
 
132
- /** Whether agents can run on this stack, and through which providers. */
133
- function addAgentsSection(result: CommandResult, report: UpReport): void {
177
+ /**
178
+ * Whether agents can run on this stack, through which providers, and what
179
+ * Anthropic said of the runner's key: checked, not answered, or refused (a
180
+ * refused key is not ready, whatever the runner reaches).
181
+ */
182
+ function addAgentsSection(result: CommandResult, report: UpReport, key: KeyStepOutcome | undefined): void {
134
183
  const section = result.addSection("Agents");
135
184
  if (report.runnerReach === undefined) {
136
185
  section.field("not ready", "no local runner (control plane only)");
137
186
  return;
138
187
  }
188
+ const rejected = key?.check === "rejected";
189
+ const ready = report.runnerReach.filter((entry) => !(rejected && entry.provider === "anthropic"));
190
+ if (ready.length > 0) section.field("ready", ready.map((entry) => describeEntry(entry, key)).join(", "));
191
+ if (rejected) {
192
+ section.field("not ready", "anthropic key rejected");
193
+ result.hint(
194
+ key.fromEnvironment
195
+ ? "Export a working ANTHROPIC_API_KEY, or unset it and run stigmer setup, then stigmer down && stigmer up"
196
+ : "Add a working key: stigmer setup, then stigmer down && stigmer up",
197
+ );
198
+ return;
199
+ }
139
200
  if (report.runnerReach.length === 0) {
140
201
  section.field("not ready", "no model provider");
141
202
  // The daemon hands its runner the key only at start, so a key saved
142
203
  // while the stack runs needs a restart to reach it.
143
204
  result.hint("Add a model provider: stigmer setup, then stigmer down && stigmer up");
144
- return;
145
205
  }
146
- section.field("ready", describeReach(report.runnerReach));
206
+ }
207
+
208
+ /** One provider for the card: `anthropic (key checked just now)`, `openai (key)`, `anthropic (vertex)`. */
209
+ function describeEntry(entry: ProviderReach, key: KeyStepOutcome | undefined): string {
210
+ if (entry.provider !== "anthropic" || key === undefined) return describeReach([entry]);
211
+ const said = key.check === "accepted" ? "key checked just now" : "key not checked: Anthropic didn't answer";
212
+ return entry.via === "gateway" ? `anthropic (gateway, ${said})` : `anthropic (${said})`;
147
213
  }
@@ -1,6 +1,8 @@
1
1
  // `stigmer usage {session,agent,org}` — token, model and working-time reports
2
- // at three granularities — and `stigmer usage hours`, the organization's
3
- // agent hours against its plan. Thin handlers: validate flags, fetch the
2
+ // at three granularities — `stigmer usage hours`, the organization's agent
3
+ // hours against its plan, and `stigmer usage onboarding`, a platform
4
+ // operator's count of how far new organizations got on the journey from a
5
+ // first agent to their users. Thin handlers: validate flags, fetch the
4
6
  // report, render. The dates pass through as typed: the server reads a UTC
5
7
  // calendar day (the whole day, both bounds inclusive) or an RFC 3339
6
8
  // instant. Heavy modules are lazy-imported inside actions so `--help` stays
@@ -16,6 +18,7 @@ import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
16
18
  import { UsageError } from "../errors/index.js";
17
19
  import type { OutputFlags } from "../output/index.js";
18
20
  import { globalOrg, readFormat } from "./shared.js";
21
+ import { CliExitError } from "../errors/cli-exit-error.js";
19
22
 
20
23
  interface UsageFlags extends OutputFlags {
21
24
  from?: string;
@@ -29,6 +32,16 @@ const TO_HELP = "end: a UTC day, inclusive (e.g. 2026-03-13), or an RFC 3339 ins
29
32
  export const AGENT_HOURS_NOT_SERVED =
30
33
  "This server does not count agent hours: they are a Stigmer Cloud plan's. `stigmer usage org` shows working time.";
31
34
 
35
+ /** What `usage onboarding` says to a caller who is no platform operator. */
36
+ export const ONBOARDING_NOT_PERMITTED = "Only a platform operator can read onboarding counts.";
37
+
38
+ /** What `usage onboarding` says on a server older than the count. */
39
+ export const ONBOARDING_NOT_SERVED =
40
+ "This server does not count onboarding yet: it is older than this command. Upgrade the server to read where newcomers stop.";
41
+
42
+ /** How many days `usage onboarding` counts when no --from is given: the last week, today included. */
43
+ const ONBOARDING_DEFAULT_DAYS = 7;
44
+
32
45
  export function registerUsage(program: Command): void {
33
46
  const usage = program.command("usage").description("view token and working-time usage reports");
34
47
 
@@ -54,6 +67,14 @@ export function registerUsage(program: Command): void {
54
67
  .option("-o, --output <format>", "output format: table, json, or yaml")
55
68
  .action((options: UsageFlags, command: Command) => runOrgUsage(options, command));
56
69
 
70
+ usage
71
+ .command("onboarding")
72
+ .description("view how far new organizations got, from a first agent to their users (platform operators)")
73
+ .option("--from <date>", `${FROM_HELP}; default: ${ONBOARDING_DEFAULT_DAYS - 1} days before --to`)
74
+ .option("--to <date>", `${TO_HELP}; default: today`)
75
+ .option("-o, --output <format>", "output format: table, json, or yaml")
76
+ .action((options: UsageFlags) => runOnboardingFunnel(options));
77
+
57
78
  usage
58
79
  .command("hours")
59
80
  .description("view the organization's agent hours against its plan (Stigmer Cloud)")
@@ -114,3 +135,35 @@ async function runAgentHours(options: UsageFlags, command: Command): Promise<voi
114
135
  const hours = await usage.getAgentHours(client.stigmer, org);
115
136
  process.stdout.write(usage.renderAgentHours(hours, readFormat(options)));
116
137
  }
138
+
139
+ async function runOnboardingFunnel(options: UsageFlags): Promise<void> {
140
+ const range = onboardingRange(options, new Date());
141
+ const [{ connectBackend }, usage, { isPermissionDenied, isUnimplemented }, { ExitCode }] = await Promise.all([
142
+ import("../backend.js"),
143
+ import("../resources/usage.js"),
144
+ import("@stigmer/client"),
145
+ import("@stigmer/client/exit-codes"),
146
+ ]);
147
+ const client = connectBackend();
148
+ ensureAuthenticated(client.config);
149
+
150
+ let funnel: Awaited<ReturnType<typeof usage.getOnboardingFunnel>>;
151
+ try {
152
+ funnel = await usage.getOnboardingFunnel(client.stigmer, range);
153
+ } catch (err) {
154
+ if (isPermissionDenied(err)) throw new CliExitError(ONBOARDING_NOT_PERMITTED, ExitCode.Auth, undefined, { cause: err });
155
+ if (isUnimplemented(err)) throw new CliExitError(ONBOARDING_NOT_SERVED, ExitCode.Usage, undefined, { cause: err });
156
+ throw err;
157
+ }
158
+ process.stdout.write(usage.renderOnboardingFunnel(funnel, range, readFormat(options)));
159
+ }
160
+
161
+ /** The window `usage onboarding` counts: as typed, else the last week to today (UTC days). */
162
+ export function onboardingRange(options: UsageFlags, now: Date): { readonly from: string; readonly to: string } {
163
+ const to = options.to ?? now.toISOString().slice(0, 10);
164
+ if (options.from !== undefined) return { from: options.from, to };
165
+ const end = /^\d{4}-\d{2}-\d{2}$/.test(to) ? Date.parse(`${to}T00:00:00Z`) : Date.parse(to);
166
+ if (Number.isNaN(end)) throw new UsageError(`--to "${to}" is not a UTC day (2026-11-07) or an RFC 3339 instant`);
167
+ const from = new Date(end - (ONBOARDING_DEFAULT_DAYS - 1) * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
168
+ return { from, to };
169
+ }
@@ -7,7 +7,7 @@
7
7
  // never clobbers either side's login state. Two names are reserved:
8
8
  // "local" (the managed daemon, never stored in the map — its endpoint and
9
9
  // no-auth posture are fixed) and "cloud" (where `stigmer auth login` lands
10
- // by default).
10
+ // when run from the local daemon, which has nothing to sign in to).
11
11
  //
12
12
  // The `backend.local` section (daemon/LLM/Temporal settings owned by the
13
13
  // local-mode modules) is carried through verbatim, so a save never drops a key
@@ -48,13 +48,14 @@ export const CLOUD_BACKEND_NAME = "cloud";
48
48
  * One named backend: endpoint + its own credentials. Property names are
49
49
  * snake_case to keep the YAML in the file's established dialect.
50
50
  *
51
- * Credential lanes by type:
52
- * - cloud: the OAuth token set (token / refresh_token / token_expiry),
53
- * written by `stigmer auth login` and rotated by the token provider.
54
- * - selfhost: `api_key` — a server-minted `stk_` token
55
- * (`stigmer apikey create`). Browser login against self-hosted
56
- * issuers is deliberately not modeled here; the API token is the
57
- * self-host credential story.
51
+ * Credentials, on any backend:
52
+ * - a sign-in: the OAuth token set (token / refresh_token / token_expiry)
53
+ * beside the issuer and the native client it came from (oidc_issuer /
54
+ * oidc_client_id), written by `stigmer auth login` from what the server
55
+ * announces and refreshed at that issuer by the token provider;
56
+ * - `api_key`: a server-minted `stk_` token (`stigmer apikey create`), set
57
+ * with `config backend add --api-key`. On a selfhost entry holding both,
58
+ * the sign-in is sent; a cloud entry sends only its sign-in.
58
59
  */
59
60
  export interface NamedBackendConfig {
60
61
  type: NamedBackendType;
@@ -64,6 +65,10 @@ export interface NamedBackendConfig {
64
65
  env_id?: string;
65
66
  refresh_token?: string;
66
67
  token_expiry?: string;
68
+ /** The issuer the sign-in came from, exactly as the server announced it. */
69
+ oidc_issuer?: string;
70
+ /** The public native client the sign-in used at that issuer. */
71
+ oidc_client_id?: string;
67
72
  api_key?: string;
68
73
  }
69
74
 
@@ -211,6 +216,11 @@ export function activeBackend(config: Config): {
211
216
  return { name, entry };
212
217
  }
213
218
 
219
+ /** Whether an entry holds a sign-in's token set (as opposed to an API key or nothing). */
220
+ export function hasSignIn(entry: NamedBackendConfig): boolean {
221
+ return (entry.token !== undefined && entry.token !== "") || (entry.refresh_token !== undefined && entry.refresh_token !== "");
222
+ }
223
+
214
224
  /** True when the active backend is Stigmer Cloud. */
215
225
  export function isCloudMode(config: Config): boolean {
216
226
  return activeBackend(config).entry?.type === "cloud";
@@ -12,6 +12,7 @@ export {
12
12
  activeBackend,
13
13
  activeBackendName,
14
14
  getDefault,
15
+ hasSignIn,
15
16
  isCloudMode,
16
17
  load,
17
18
  save,
@@ -19,6 +20,7 @@ export {
19
20
  export {
20
21
  DEFAULT_CLOUD_CONSOLE_URL,
21
22
  ensureAuthenticated,
23
+ knownConsoleURL,
22
24
  resolveConsoleURL,
23
25
  contextOrganizationId,
24
26
  contextOrganizationLabel,
@@ -4,7 +4,8 @@
4
4
  //
5
5
  // All resolvers read the ACTIVE named backend (config.ts): local is the
6
6
  // managed daemon (fixed endpoint, never requires auth), cloud entries carry
7
- // the OAuth token set, selfhost entries carry an endpoint + api_key.
7
+ // a sign-in's token set, selfhost entries an endpoint and a sign-in or an
8
+ // api_key.
8
9
 
9
10
  import { CliExitError, ExitCode } from "../errors/index.js";
10
11
  import { SERVER_PORT } from "../local/constants.js";
@@ -36,10 +37,11 @@ export function resolveEndpoint(config: Config): string {
36
37
  * The endpoint {@link resolveEndpoint} names, with where it came from: the
37
38
  * override's name, or the active backend's kind. The backend client records
38
39
  * it when made, so a failure names the address tried and the fix that fits
39
- * its source.
40
+ * its source. `env` is the environment the override is read from; `stigmer
41
+ * status` passes the one it was given, so its tests need no process state.
40
42
  */
41
- export function resolveServerAddress(config: Config): ServerAddress {
42
- const override = process.env.STIGMER_SERVER_ADDRESS;
43
+ export function resolveServerAddress(config: Config, env: NodeJS.ProcessEnv = process.env): ServerAddress {
44
+ const override = env.STIGMER_SERVER_ADDRESS;
43
45
  if (override !== undefined && override !== "") {
44
46
  return { address: override, source: "environment" };
45
47
  }
@@ -66,7 +68,7 @@ export function resolveServerAddress(config: Config): ServerAddress {
66
68
  /**
67
69
  * Resolve the auth token.
68
70
  * STIGMER_API_KEY (env, also where the --api-key global is bridged)
69
- * > the active entry's credential (cloud: login token; selfhost: api_key)
71
+ * > the active entry's credential (its sign-in's token; else a selfhost api_key)
70
72
  * > "" (unauthenticated)
71
73
  */
72
74
  export function resolveToken(config: Config): string {
@@ -78,7 +80,8 @@ export function resolveToken(config: Config): string {
78
80
  if (entry === undefined) {
79
81
  return "";
80
82
  }
81
- return (entry.type === "cloud" ? entry.token : entry.api_key) ?? "";
83
+ if (entry.token !== undefined && entry.token !== "") return entry.token;
84
+ return (entry.type === "selfhost" ? entry.api_key : undefined) ?? "";
82
85
  }
83
86
 
84
87
  /**
@@ -136,6 +139,28 @@ export function resolveConsoleURL(
136
139
  return DEFAULT_CLOUD_CONSOLE_URL;
137
140
  }
138
141
 
142
+ /**
143
+ * The console's address when the CLI knows it for certain, or `undefined`:
144
+ * the `STIGMER_CONSOLE_URL` override, or Stigmer Cloud's own console for a
145
+ * `cloud` entry that talks to Stigmer Cloud's own API. Where a person is sent
146
+ * to a page, a guess must not stand in for it: a hosted deployment registered
147
+ * by its API address (an address entry, or a `cloud` entry given another
148
+ * endpoint) can serve its console from another origin, so the rule
149
+ * {@link resolveConsoleURL} applies there would name the wrong host.
150
+ */
151
+ export function knownConsoleURL(
152
+ config: Config,
153
+ env: NodeJS.ProcessEnv = process.env,
154
+ ): string | undefined {
155
+ const override = env.STIGMER_CONSOLE_URL;
156
+ if (override !== undefined && override !== "") return override;
157
+ const { entry } = activeBackend(config);
158
+ if (entry?.type !== "cloud") return undefined;
159
+ const serverOverride = env.STIGMER_SERVER_ADDRESS ?? "";
160
+ const endpoint = serverOverride !== "" ? serverOverride : (entry.endpoint ?? "");
161
+ return endpoint === "" || endpoint === DEFAULT_CLOUD_ENDPOINT ? DEFAULT_CLOUD_CONSOLE_URL : undefined;
162
+ }
163
+
139
164
  /**
140
165
  * The configured organization, with the active entry's org_id fallback.
141
166
  * Reports only what is explicitly set (no implicit local default) so
@@ -76,8 +76,17 @@ export function classify(err: unknown): CliError | null {
76
76
 
77
77
  // Local errors that carry their own exit code (UsageError, auth-required,
78
78
  // etc.) are passed through verbatim, including any remediation hints.
79
+ // One that says a server's refusal in the command's own words keeps the
80
+ // refusal's status, so it still reads as the server's answer.
79
81
  if (err instanceof CliExitError) {
80
- return { exitCode: err.exitCode, message: err.message, hints: err.hints, cause: err };
82
+ const answered = err.cause === undefined ? undefined : extractCoded(err.cause);
83
+ return {
84
+ exitCode: err.exitCode,
85
+ message: err.message,
86
+ hints: err.hints,
87
+ cause: err,
88
+ ...(answered === undefined ? {} : { code: answered.code }),
89
+ };
81
90
  }
82
91
 
83
92
  const coded = extractCoded(err);
@@ -2,13 +2,17 @@
2
2
  // classify() passes these through verbatim, so command code can fail fast with
3
3
  // a precise exit code (e.g. "auth required" -> 4) without round-tripping to the
4
4
  // server. UsageError is the common specialization (exit 2).
5
+ //
6
+ // A command that says a server's refusal in its own words passes the refusal
7
+ // as `cause`: classify() then keeps its RPC status, so the failure still
8
+ // reads as the server's answer (its help line, its debug code).
5
9
 
6
10
  export class CliExitError extends Error {
7
11
  readonly exitCode: number;
8
12
  readonly hints?: readonly string[];
9
13
 
10
- constructor(message: string, exitCode: number, hints?: readonly string[]) {
11
- super(message);
14
+ constructor(message: string, exitCode: number, hints?: readonly string[], options?: { readonly cause?: unknown }) {
15
+ super(message, options);
12
16
  this.name = "CliExitError";
13
17
  this.exitCode = exitCode;
14
18
  this.hints = hints;