@stigmer/cli 0.2.0 → 0.3.1

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 (77) hide show
  1. package/commands/app-handover.d.ts.map +1 -1
  2. package/commands/app-handover.js +23 -10
  3. package/commands/app-handover.js.map +1 -1
  4. package/commands/auth/whoami.d.ts +10 -0
  5. package/commands/auth/whoami.d.ts.map +1 -1
  6. package/commands/auth/whoami.js +63 -5
  7. package/commands/auth/whoami.js.map +1 -1
  8. package/commands/docs/index.d.ts +9 -0
  9. package/commands/docs/index.d.ts.map +1 -0
  10. package/commands/docs/index.js +64 -0
  11. package/commands/docs/index.js.map +1 -0
  12. package/commands/example.d.ts +7 -0
  13. package/commands/example.d.ts.map +1 -1
  14. package/commands/example.js +11 -1
  15. package/commands/example.js.map +1 -1
  16. package/commands/help.d.ts.map +1 -1
  17. package/commands/help.js +3 -0
  18. package/commands/help.js.map +1 -1
  19. package/commands/list.d.ts.map +1 -1
  20. package/commands/list.js +13 -1
  21. package/commands/list.js.map +1 -1
  22. package/commands/mcp-server.d.ts.map +1 -1
  23. package/commands/mcp-server.js +12 -3
  24. package/commands/mcp-server.js.map +1 -1
  25. package/commands/provider-key/index.d.ts.map +1 -1
  26. package/commands/provider-key/index.js +2 -2
  27. package/commands/provider-key/index.js.map +1 -1
  28. package/commands/status.d.ts.map +1 -1
  29. package/commands/status.js +4 -3
  30. package/commands/status.js.map +1 -1
  31. package/config/index.d.ts +1 -1
  32. package/config/index.d.ts.map +1 -1
  33. package/config/index.js +1 -1
  34. package/config/index.js.map +1 -1
  35. package/config/resolve.d.ts +13 -2
  36. package/config/resolve.d.ts.map +1 -1
  37. package/config/resolve.js +24 -3
  38. package/config/resolve.js.map +1 -1
  39. package/local/runtime/node.d.ts +12 -4
  40. package/local/runtime/node.d.ts.map +1 -1
  41. package/local/runtime/node.js +73 -27
  42. package/local/runtime/node.js.map +1 -1
  43. package/local/status.d.ts.map +1 -1
  44. package/local/status.js +62 -4
  45. package/local/status.js.map +1 -1
  46. package/package.json +12 -12
  47. package/program.d.ts.map +1 -1
  48. package/program.js +2 -0
  49. package/program.js.map +1 -1
  50. package/resources/provider-key.d.ts +7 -2
  51. package/resources/provider-key.d.ts.map +1 -1
  52. package/resources/provider-key.js +18 -3
  53. package/resources/provider-key.js.map +1 -1
  54. package/resources/runs.d.ts +10 -3
  55. package/resources/runs.d.ts.map +1 -1
  56. package/resources/runs.js +22 -4
  57. package/resources/runs.js.map +1 -1
  58. package/resources/views/agent.d.ts.map +1 -1
  59. package/resources/views/agent.js +18 -2
  60. package/resources/views/agent.js.map +1 -1
  61. package/src/commands/app-handover.ts +26 -12
  62. package/src/commands/auth/whoami.ts +68 -4
  63. package/src/commands/docs/index.ts +65 -0
  64. package/src/commands/example.ts +12 -1
  65. package/src/commands/help.ts +3 -0
  66. package/src/commands/list.ts +14 -1
  67. package/src/commands/mcp-server.ts +11 -3
  68. package/src/commands/provider-key/index.ts +7 -1
  69. package/src/commands/status.ts +4 -3
  70. package/src/config/index.ts +1 -0
  71. package/src/config/resolve.ts +26 -3
  72. package/src/local/runtime/node.ts +95 -30
  73. package/src/local/status.ts +69 -4
  74. package/src/program.ts +2 -0
  75. package/src/resources/provider-key.ts +24 -3
  76. package/src/resources/runs.ts +36 -4
  77. package/src/resources/views/agent.ts +19 -2
@@ -1,4 +1,16 @@
1
- // `stigmer status` — render the local stack's health as a structured result.
1
+ // `stigmer status` — say which server the CLI uses, then render the local
2
+ // stack's health as a structured result.
3
+ //
4
+ // It names the backend the CLI uses and its address first, read from the
5
+ // same resolver the backend client dials by (config/resolve.ts). When that is
6
+ // not the local stack (a self-hosted server, Stigmer Cloud, or an address in
7
+ // STIGMER_SERVER_ADDRESS), a missing local stack is nothing wrong: it says so
8
+ // and returns success, with no hint to start one, since a person signed in to
9
+ // their own server who follows `stigmer up` starts a second server
10
+ // (stigmer#3369). It never asks the remote server anything; reaching it is
11
+ // `stigmer auth whoami`'s. A backend config that cannot be read is shown on
12
+ // the Backend line with its own error, and the local stack is still reported:
13
+ // a diagnostic command never fails on what it diagnoses.
2
14
  //
3
15
  // Source of truth is `health-state.json`, written by the daemon's health
4
16
  // monitor. If it is missing but the server port answers (the daemon wrote a PID
@@ -10,8 +22,9 @@
10
22
  import { formatElapsed } from "@stigmer/client";
11
23
  import { homedir } from "node:os";
12
24
  import { join } from "node:path";
13
- import { load as loadConfig } from "../config/config.js";
25
+ import { activeBackend, load as loadConfig } from "../config/config.js";
14
26
  import { configPath } from "../config/paths.js";
27
+ import { resolveServerAddress } from "../config/resolve.js";
15
28
  import { CommandResult } from "../output/command-result.js";
16
29
  import { SERVER_PORT, TEMPORAL_UI_PORT } from "./constants.js";
17
30
  import { resolveApiKey } from "./llm-config.js";
@@ -48,14 +61,25 @@ export async function buildStatusResult(
48
61
  const pid = recordedLiveProcess(join(data, DAEMON_PID_FILE));
49
62
  const daemonAlive = pid !== null;
50
63
  const portOpen = await probe(SERVER_PORT);
64
+ const backend = backendInUse(home, env);
65
+ const elsewhere = backend.kind === "remote";
51
66
 
52
67
  if (!daemonAlive && !portOpen) {
53
- return CommandResult.warning("Stigmer server is not running").hint("To start: stigmer up");
68
+ if (elsewhere) {
69
+ const result = CommandResult.success(usesMessage(backend));
70
+ addBackendSection(result, backend);
71
+ result.addSection("Local Stack").field("Status", "Not running ○");
72
+ return result;
73
+ }
74
+ const result = CommandResult.warning("Stigmer server is not running");
75
+ addBackendSection(result, backend);
76
+ return result.hint("To start: stigmer up");
54
77
  }
55
78
 
56
79
  const health = loadHealthState(join(data, "health-state.json")) ?? synthesizeHealth(pid, portOpen);
57
80
 
58
- const result = CommandResult.success("Stigmer server is running");
81
+ const result = CommandResult.success(elsewhere ? usesMessage(backend) : "Stigmer server is running");
82
+ addBackendSection(result, backend);
59
83
 
60
84
  const daemon = result.addSection("Daemon");
61
85
  daemon.field("PID", String(health.daemon_pid));
@@ -80,6 +104,47 @@ export async function buildStatusResult(
80
104
  return result;
81
105
  }
82
106
 
107
+ /** The server the CLI uses: the local stack, another server, or a config that names none it can read. */
108
+ type BackendInUse =
109
+ | { readonly kind: "local"; readonly name: string; readonly address: string }
110
+ | { readonly kind: "remote"; readonly name: string; readonly address: string; readonly fromEnvironment: boolean }
111
+ | { readonly kind: "broken"; readonly error: string };
112
+
113
+ // The local stack's own address, as the resolver names it or as an
114
+ // override may spell it; an override naming it is still the local stack.
115
+ const LOCAL_ADDRESSES = new Set([`localhost:${SERVER_PORT}`, `127.0.0.1:${SERVER_PORT}`]);
116
+
117
+ function backendInUse(home: string, env: NodeJS.ProcessEnv): BackendInUse {
118
+ try {
119
+ const config = loadConfig(configPath(home));
120
+ const { name } = activeBackend(config);
121
+ const { address, source } = resolveServerAddress(config, env);
122
+ if (source === "local" || LOCAL_ADDRESSES.has(address)) return { kind: "local", name, address };
123
+ return { kind: "remote", name, address, fromEnvironment: source === "environment" };
124
+ } catch (err) {
125
+ return { kind: "broken", error: err instanceof Error ? err.message : String(err) };
126
+ }
127
+ }
128
+
129
+ function usesMessage(backend: Extract<BackendInUse, { kind: "remote" }>): string {
130
+ return backend.fromEnvironment
131
+ ? `The CLI uses ${backend.address} (STIGMER_SERVER_ADDRESS), not a local stack`
132
+ : `The CLI uses backend "${backend.name}" at ${backend.address}, not a local stack`;
133
+ }
134
+
135
+ // The same words `stigmer config backend status` uses for the same facts.
136
+ function addBackendSection(result: CommandResult, backend: BackendInUse): void {
137
+ const section = result.addSection("");
138
+ if (backend.kind === "broken") {
139
+ section.field("Backend", `unreadable: ${backend.error}`);
140
+ result.hint("See the configured backends: stigmer config backend list");
141
+ return;
142
+ }
143
+ section.field("Backend", backend.name);
144
+ section.field("Endpoint", backend.address);
145
+ if (backend.kind === "remote" && backend.fromEnvironment) section.field("Set by", "STIGMER_SERVER_ADDRESS");
146
+ }
147
+
83
148
  function synthesizeHealth(pid: number | null, portOpen: boolean): HealthState {
84
149
  // No snapshot on disk: report only what a TCP probe can prove. If the port
85
150
  // answers the server is running; otherwise leave components empty so the
package/src/program.ts CHANGED
@@ -53,6 +53,7 @@ import { registerUsage } from "./commands/usage.js";
53
53
  import { registerValidate } from "./commands/validate.js";
54
54
  import { registerVault } from "./commands/vault.js";
55
55
  import { registerVersion } from "./commands/version.js";
56
+ import { registerDocs } from "./commands/docs/index.js";
56
57
  import { registerAppHandover } from "./commands/app-handover.js";
57
58
  import { registerCodingAgent } from "./commands/coding-agent.js";
58
59
  import { registerEmbedding } from "./commands/embedding.js";
@@ -138,6 +139,7 @@ export function buildProgram(): Command {
138
139
  registerConfig(program);
139
140
  registerCompletion(program);
140
141
  registerVersion(program);
142
+ registerDocs(program);
141
143
  registerInternalDaemon(program);
142
144
 
143
145
  // After registration, so every command is reached.
@@ -231,9 +231,19 @@ export function refuseKeyOnCommandLine(provider: Provider): never {
231
231
  /**
232
232
  * The key, read from stdin under `--key-stdin`, otherwise from a hidden
233
233
  * prompt on a terminal. Off a terminal without `--key-stdin` there is no
234
- * one to type it, so the command says how to pipe it in.
234
+ * one to type it: a coding agent runs commands with no terminal, and a key
235
+ * typed into its chat would land in its transcript (stigmer#3229). So the
236
+ * refusal sends the person to the console's key page first, where the key
237
+ * goes from their browser to the server and is checked live, then says how
238
+ * to pipe it in. `consoleUrl` is the console's address when the CLI knows it
239
+ * for certain (`knownConsoleURL`); otherwise the page is named.
235
240
  */
236
- export async function readProviderKey(provider: Provider, keyStdin: boolean, io: KeyIo): Promise<string> {
241
+ export async function readProviderKey(
242
+ provider: Provider,
243
+ keyStdin: boolean,
244
+ io: KeyIo,
245
+ consoleUrl: string | undefined,
246
+ ): Promise<string> {
237
247
  const name = providerDisplayName(provider);
238
248
  let raw: string;
239
249
  if (keyStdin) {
@@ -241,8 +251,12 @@ export async function readProviderKey(provider: Provider, keyStdin: boolean, io:
241
251
  } else if (io.stdinIsTty) {
242
252
  raw = await io.promptHidden(`${name} key`);
243
253
  } else {
254
+ const consoleLine =
255
+ consoleUrl === undefined
256
+ ? "Add it on the console's Models & providers page."
257
+ : `Add it in the console: ${withoutTrailingSlashes(consoleUrl)}/models`;
244
258
  throw new UsageError(
245
- `no terminal to type the ${name} key at\n\nPipe it in: stigmer provider-key set ${provider} --key-stdin`,
259
+ `no terminal to type the ${name} key at\n\n${consoleLine}\nOr pipe it in: stigmer provider-key set ${provider} --key-stdin`,
246
260
  );
247
261
  }
248
262
  const key = raw.trim();
@@ -250,6 +264,13 @@ export async function readProviderKey(provider: Provider, keyStdin: boolean, io:
250
264
  return key;
251
265
  }
252
266
 
267
+ /** `url` without trailing slashes, so a path joins it with one. */
268
+ function withoutTrailingSlashes(url: string): string {
269
+ let end = url.length;
270
+ while (end > 0 && url[end - 1] === "/") end--;
271
+ return url.slice(0, end);
272
+ }
273
+
253
274
  /** Save the organization's key for `provider`, and say whether the provider confirmed it. */
254
275
  export async function setProviderKey(
255
276
  client: ProviderKeyClient,
@@ -12,12 +12,17 @@
12
12
  import { create } from "@bufbuild/protobuf";
13
13
  import { RunSchema, type Run } from "@stigmer/apis/ai/stigmer/agentic/run/v1/api_pb";
14
14
  import { RunPhase } from "@stigmer/apis/ai/stigmer/agentic/run/v1/enum_pb";
15
- import { RunListSchema, ListRunsRequestSchema } from "@stigmer/apis/ai/stigmer/agentic/run/v1/io_pb";
15
+ import {
16
+ ListRunsByAgentRequestSchema,
17
+ ListRunsRequestSchema,
18
+ RunListSchema,
19
+ } from "@stigmer/apis/ai/stigmer/agentic/run/v1/io_pb";
16
20
  import { InterruptSessionInputSchema } from "@stigmer/apis/ai/stigmer/agentic/session/v1/io_pb";
17
21
  import { ApiResourceKind } from "@stigmer/apis/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
18
22
  import type { Stigmer } from "@stigmer/client";
19
23
  import type { OutputFormat } from "../output/index.js";
20
24
  import { buildTypeInfo } from "../registry/index.js";
25
+ import { resolveAgent } from "./agent/resolve.js";
21
26
  import { readCursorPages } from "./cursor-pages.js";
22
27
  import type { ResourceResult } from "./get-bindings.js";
23
28
  import { obj, renderListMessage, str, type TableShape } from "./render.js";
@@ -84,14 +89,14 @@ export async function getRun(client: Stigmer, id: string): Promise<ResourceResul
84
89
  }
85
90
 
86
91
  /**
87
- * List the newest `limit` runs for the current context, reading
88
- * as many pages as that takes.
92
+ * List the newest `limit` runs of the organization, reading as many pages as
93
+ * that takes.
89
94
  *
90
95
  * `org` scopes results to that organization; empty means permission-bounded
91
96
  * (all orgs the caller can view — the OSS single-tenant behavior). `labels`
92
97
  * keeps only the runs carrying every pair given.
93
98
  */
94
- export async function listAgentRuns(
99
+ export async function listOrgRuns(
95
100
  client: Stigmer,
96
101
  limit: number,
97
102
  org = "",
@@ -103,6 +108,33 @@ export async function listAgentRuns(
103
108
  return { schema: RunListSchema, message: create(RunListSchema, { entries }) };
104
109
  }
105
110
 
111
+ /** How `list runs --agent` says to set the organization a bare slug needs. */
112
+ const SET_ORG_WITH = [
113
+ "stigmer config context set --org <org>",
114
+ "stigmer --org <org> list runs --agent <agent>",
115
+ ] as const;
116
+
117
+ /**
118
+ * List the newest `limit` runs of one agent, across its conversations: the
119
+ * agent's last run is the first entry, whichever conversation took it.
120
+ * `agentRef` names the agent as `agent quality` does (an id, `org/slug`, or a
121
+ * slug in `org`); `labels` keeps only the runs carrying every pair given.
122
+ */
123
+ export async function listRunsOfAgent(
124
+ client: Stigmer,
125
+ limit: number,
126
+ agentRef: string,
127
+ org: string,
128
+ labels: Record<string, string> = {},
129
+ ): Promise<ResourceResult> {
130
+ const agent = await resolveAgent(client, agentRef, org, SET_ORG_WITH);
131
+ const agentId = agent.metadata?.id ?? "";
132
+ const entries = await readCursorPages(limit, (pageSize, pageToken) =>
133
+ client.run.listByAgent(create(ListRunsByAgentRequestSchema, { agentId, pageSize, pageToken, labels })),
134
+ );
135
+ return { schema: RunListSchema, message: create(RunListSchema, { entries }) };
136
+ }
137
+
106
138
  const RUN_TABLE: TableShape = {
107
139
  resourceName: "runs",
108
140
  headers: ["ID", "AGENT", "STATUS", "STARTED"],
@@ -1,7 +1,8 @@
1
1
  // `get agent`: what an agent is made of, as a person reads it. Its
2
2
  // description and when it last changed; the start of its instructions; the
3
- // skills, MCP servers, tools, subagents and plugins it works with; the
4
- // Environment its conversations run in and the values it declares; the
3
+ // skills, MCP servers, tools, subagents and plugins it works with; whether
4
+ // its conversations have a computer, the Environment they run in and the
5
+ // values it declares; the
5
6
  // settings a run starts from. Everything comes from the agent itself
6
7
  // (apis/ai/stigmer/agentic/agent/v1/spec.proto); `-o yaml` prints it whole.
7
8
 
@@ -33,6 +34,7 @@ export const agentView: KindView = {
33
34
  {
34
35
  title: "Environment",
35
36
  fields: [
37
+ ["Computer", computerWord(spec.computer)],
36
38
  ["Sandbox", refLabel(obj(spec, "environment_ref"), metadata, ctx)],
37
39
  ["Values", declaredValues(spec.env)],
38
40
  ],
@@ -42,6 +44,21 @@ export const agentView: KindView = {
42
44
  },
43
45
  };
44
46
 
47
+ // Whether the agent's conversations have a computer, as the agent records
48
+ // it. Only COMPUTER_NONE means none (session/v1/enum.proto, Computer); an
49
+ // agent saved before the setting records nothing, and the row is left out
50
+ // as every view leaves out what a resource does not carry.
51
+ function computerWord(computer: JsonValue | undefined): string | undefined {
52
+ switch (computer) {
53
+ case "COMPUTER_NONE":
54
+ return "no";
55
+ case "COMPUTER_REQUIRED":
56
+ return "yes";
57
+ default:
58
+ return undefined;
59
+ }
60
+ }
61
+
45
62
  // The values an agent declares, by name, each marked secret or optional
46
63
  // where it is ("GITHUB_TOKEN (secret), REGION (optional)"). A plain value's
47
64
  // content is the agent's own setting, and `-o yaml` shows it.