@bendyline/gezel-cli 1.1.2 → 1.2.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.
package/README.md CHANGED
@@ -45,7 +45,13 @@ With no connection flags, the CLI follows this order:
45
45
  2. Discover the logged-in user's product daemon through the same pinned
46
46
  runtime discovery used by the Gezel app SDK. Its actual dynamic port and
47
47
  pinned TLS certificate come from `~/.gezel/runtime`; management commands
48
- may start that user-role daemon when it is absent. The interactive TUI
48
+ may start that user-role daemon when it is absent, and say so on stderr
49
+ because it keeps running afterwards (`gezel stop --daemon` ends it). A
50
+ daemon the CLI starts keeps its own log in
51
+ `~/.gezel/logs/service-YYYY-MM-DD.log` (rolled at 10 MB, kept 7 days).
52
+ Read-only diagnostics such as `gezel native status` and `native list`
53
+ never leave one behind: with no daemon running they answer from a
54
+ service that stops with the command. The interactive TUI
49
55
  retains ownership when it starts a daemon itself, so exiting the TUI runs
50
56
  the daemon's complete shutdown path and cleans up its local engine children.
51
57
  3. On first use, the terminal waits while the Gezel app asks you to approve
@@ -101,7 +107,7 @@ gezel secret set openaiApiKey --stdin < /path/to/private-key-file
101
107
  gezel secret remove openaiApiKey
102
108
  ```
103
109
 
104
- `--use-for-search` also selects Brave (or Tavily for `tavilyApiKey`) as the
110
+ `--use-for-search` (with `braveSearchApiKey`) also selects Brave as the
105
111
  search provider while preserving its other settings. Without it, setting a
106
112
  credential leaves provider selection unchanged. `secret list` gives the supported
107
113
  names and whether each is configured; credentials are write-only and never
@@ -210,12 +216,29 @@ The CLI does not bundle model weights or native inference engines; those are
210
216
  downloaded only on demand when you opt into on-device models. Straight away
211
217
  you can use:
212
218
 
213
- - The interactive TUI (`gezel`) and one-shot prompts (`gezel run "…"`)
219
+ - The interactive TUI (`gezel`), which walks you through choosing a model on
220
+ first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
221
+ Until then `run` downloads nothing: it names the setup commands and exits.
214
222
  - Cloud providers — OpenAI, Anthropic, GitHub Copilot, and any
215
223
  OpenAI-compatible endpoint
216
- - Gezel and project management (`gezel agent`, `gezel env`, `gezel task`)
224
+ - Gezel and project management (`gezel agent`, `gezel project`, `gezel task`)
217
225
  - Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
218
226
  these need no running daemon at all
227
+ - Knowledge catalogs you already have: `gezel knowledge validate`, `inspect`
228
+ and full-text `search` work offline, with no daemon
229
+
230
+ Building a catalog (`gezel knowledge build`) and `gezel knowledge search
231
+ --semantic` also need the embedding runtime, which an npm install leaves out.
232
+ Add it where Gezel is installed (drop `-g` for a project install); the desktop
233
+ app already includes it:
234
+
235
+ ```bash
236
+ npm install -g @huggingface/transformers@^3.8.1
237
+ ```
238
+
239
+ In a project install, also add the `overrides` from the
240
+ [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service):
241
+ Transformers still asks for a `sharp` release that `npm audit` flags.
219
242
 
220
243
  ## Running models on your own machine
221
244
 
@@ -261,14 +284,14 @@ Run `gezel --help` for the full list. The most-used ones:
261
284
  | `gezel run [prompt…]` | One-shot prompt in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
262
285
  | `gezel do <craftbook…>` | Start a craftbook as an immediately dispatched task in the current directory's project; accepts its id or display name |
263
286
  | `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
264
- | `gezel secret list / set / remove` | Manage write-only provider credentials, including Brave and Tavily search keys |
287
+ | `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
265
288
  | `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
266
289
  | `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
267
290
  | `gezel start` / `stop` / `status` | Use or inspect the selected service. `stop` is the same hard stop as the desktop UX: cancel work, unload local engines, and switch to Reactive. `stop --daemon` shuts down a user-owned daemon process itself. `start --web` serves the browser UI. On hosts without a Gezel machine service, a started daemon prefers the canonical port 6228 (ephemeral fallback) so third-party OpenAI clients get a stable `https://127.0.0.1:6228/v1` base URL; with a machine service installed, the service owns 6228 and started daemons use an ephemeral port (`--port` pins one explicitly). |
268
291
  | `gezel doctor` | Report on the local install |
269
292
  | `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
270
293
  | `gezel agent list\|create\|show` | Manage your gezels |
271
- | `gezel env list\|create\|install` | Manage projects and their packages |
294
+ | `gezel project list\|create\|install` | Manage projects and their packages (`gezel env` is the same command) |
272
295
  | `gezel task list\|create\|show` | Manage tasks |
273
296
  | `gezel model list\|pull\|export` | Manage on-device chat models. `export <id> [file]` downloads the catalog model if needed, then writes a portable, checksum-verified `.gezmodel` you can move to another machine |
274
297
  | `gezel native install\|list\|status` | Manage native engine binaries |
@@ -273,7 +273,13 @@ import { createHash, randomUUID } from "crypto";
273
273
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
274
274
  import { homedir } from "os";
275
275
  import { basename, dirname, join, resolve } from "path";
276
- import { pickRandomNameWithGender } from "@bendyline/gezel";
276
+ import {
277
+ getLogLevel,
278
+ getLogOutput,
279
+ pickRandomNameWithGender,
280
+ setLogLevel,
281
+ setLogOutput
282
+ } from "@bendyline/gezel";
277
283
  import {
278
284
  GezelSdkError,
279
285
  authorizeLocal,
@@ -286,6 +292,7 @@ import {
286
292
  createTrustingFetch,
287
293
  discoverOrSpawn,
288
294
  electronNativeBinCandidates,
295
+ ensureProjectForFolder as ensureClientProjectForFolder,
289
296
  isProcessAlive,
290
297
  readRuntime,
291
298
  readSystemServiceEndpoint,
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/app-command.ts
4
- import { readFile as readFile2 } from "fs/promises";
4
+ import { readFile as readFile2, realpath } from "fs/promises";
5
5
  import { isAbsolute, join as join2, resolve as resolve2 } from "path";
6
6
  import { compareSemver } from "@bendyline/gezel";
7
7
 
@@ -10,7 +10,13 @@ import { createHash, randomUUID } from "crypto";
10
10
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
11
11
  import { homedir } from "os";
12
12
  import { basename, dirname, join, resolve } from "path";
13
- import { pickRandomNameWithGender } from "@bendyline/gezel";
13
+ import {
14
+ getLogLevel,
15
+ getLogOutput,
16
+ pickRandomNameWithGender,
17
+ setLogLevel,
18
+ setLogOutput
19
+ } from "@bendyline/gezel";
14
20
  import {
15
21
  GezelSdkError,
16
22
  authorizeLocal,
@@ -23,6 +29,7 @@ import {
23
29
  createTrustingFetch,
24
30
  discoverOrSpawn,
25
31
  electronNativeBinCandidates,
32
+ ensureProjectForFolder as ensureClientProjectForFolder,
26
33
  isProcessAlive,
27
34
  readRuntime,
28
35
  readSystemServiceEndpoint,
@@ -39,25 +46,15 @@ var CliError = class extends Error {
39
46
  };
40
47
  async function ensureProjectForFolder(client, folderPath) {
41
48
  const wd = resolve(folderPath);
42
- const eq = (a, b) => !!a && (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
43
- const { projects } = await client.listProjects();
44
- const exact = projects.find((p) => eq(p.workingDir, wd));
45
- if (exact) return exact.id;
46
49
  const name = basename(wd) || "workspace";
47
- const orphan = projects.find((p) => !p.workingDir && p.name === name);
48
- if (orphan) {
49
- await client.setProjectWorkingDir(orphan.id, wd);
50
- return orphan.id;
51
- }
52
- const created = await client.createProject({
53
- name,
50
+ const result = await ensureClientProjectForFolder(client, wd, {
51
+ mode: "solo",
52
+ source: "cli",
54
53
  description: `CLI workspace at ${wd}`,
55
54
  about: `${name} \u2014 working directory ${wd}. Fill in who this project is for, what's in scope, and what's explicitly out of scope.`,
56
- missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`,
57
- mode: "solo",
58
- workingDir: wd
55
+ missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`
59
56
  });
60
- return created.id;
57
+ return result.projectId;
61
58
  }
62
59
 
63
60
  // src/app-command.ts
@@ -306,11 +303,12 @@ async function runAppSetEnabled(client, appId, enabled) {
306
303
  throw new CliError(apiMessage(err));
307
304
  }
308
305
  }
309
- function findProjectForFolder(projects, folder) {
310
- const wd = resolve2(folder);
311
- return projects.find(
312
- (project) => !!project.workingDir && (process.platform === "win32" ? project.workingDir.toLowerCase() === wd.toLowerCase() : project.workingDir === wd)
313
- );
306
+ async function findProjectForFolder(projects, folder) {
307
+ const requested = resolve2(folder);
308
+ const real = await realpath(requested).catch(() => requested);
309
+ const fold = (p) => process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p;
310
+ const wanted = /* @__PURE__ */ new Set([fold(requested), fold(real)]);
311
+ return projects.find((project) => !!project.workingDir && wanted.has(fold(project.workingDir)));
314
312
  }
315
313
  function parseParamFlags(flags) {
316
314
  const params = {};
@@ -398,7 +396,7 @@ async function runAppApply(client, appId, folder, opts) {
398
396
  }
399
397
  const params = parseParamFlags(opts.param ?? []);
400
398
  const { projects } = await client.listProjects();
401
- const existing = findProjectForFolder(projects, folder);
399
+ const existing = await findProjectForFolder(projects, folder);
402
400
  const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
403
401
  const project = await client.getProject(projectId);
404
402
  if (!opts.json) {
@@ -453,7 +451,7 @@ async function runAppApply(client, appId, folder, opts) {
453
451
  }
454
452
  async function runAppStatus(client, folder, opts) {
455
453
  const { projects } = await client.listProjects();
456
- const project = findProjectForFolder(projects, folder);
454
+ const project = await findProjectForFolder(projects, folder);
457
455
  if (!project) {
458
456
  console.log(`No gezel project is linked to ${resolve2(folder)}.`);
459
457
  console.log("Apply an app here with: gezel app apply <appId>");
@@ -509,7 +507,7 @@ async function openUrlInBrowser(url) {
509
507
  async function resolveServeProject(client, appId, folder) {
510
508
  const { projects } = await client.listProjects();
511
509
  if (!appId) {
512
- const existing = findProjectForFolder(projects, folder);
510
+ const existing = await findProjectForFolder(projects, folder);
513
511
  const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
514
512
  const project = await client.getProject(projectId);
515
513
  if (!project.projectType) {
@@ -2,9 +2,14 @@
2
2
 
3
3
  // src/bin/gezel.ts
4
4
  import { basename as basename4, isAbsolute as isAbsolutePath, join as joinPath } from "path";
5
- import { GEZEL_VERSION, getLogOutput, setLogOutput } from "@bendyline/gezel";
6
5
  import {
7
- GezelApiError as GezelApiError3,
6
+ GEZEL_VERSION,
7
+ getLogLevel as getLogLevel2,
8
+ getLogOutput as getLogOutput2,
9
+ setLogLevel as setLogLevel2,
10
+ setLogOutput as setLogOutput2
11
+ } from "@bendyline/gezel";
12
+ import {
8
13
  streamChatEvents
9
14
  } from "@bendyline/gezel-client";
10
15
  import {
@@ -20,12 +25,49 @@ import {
20
25
  import { resolveOnDeviceProvider } from "@bendyline/gezel/native";
21
26
  import { Command } from "commander";
22
27
 
28
+ // src/cli-errors.ts
29
+ function formatCliFailure(err, env2 = process.env) {
30
+ if (!(err instanceof Error)) return null;
31
+ if (err.name === "CliError") return err.message;
32
+ if (err.name !== "GezelApiError" || env2.GEZEL_DEBUG === "1") return null;
33
+ const { status, details } = err;
34
+ const request = /\bon ([A-Z]+ \S+)/.exec(err.message)?.[1];
35
+ const serviceText = detailText(details);
36
+ if (status === 404) {
37
+ const what = serviceText && serviceText.toLowerCase() !== "not found" ? serviceText : void 0;
38
+ return `error: not found${what ? `: ${what}` : request ? ` (${request})` : ""}`;
39
+ }
40
+ const lines = [`error: ${serviceText ?? err.message}`];
41
+ if (serviceText && request) lines.push(`(Gezel service answered ${status ?? "?"} to ${request})`);
42
+ lines.push("Set GEZEL_DEBUG=1 to see the full error.");
43
+ return lines.join("\n");
44
+ }
45
+ function isNotFound(err) {
46
+ return err instanceof Error && err.name === "GezelApiError" && err.status === 404;
47
+ }
48
+ function detailText(details) {
49
+ if (typeof details === "string" && details.trim()) return details.trim();
50
+ if (details && typeof details === "object") {
51
+ for (const key of ["message", "error"]) {
52
+ const value = details[key];
53
+ if (typeof value === "string" && value.trim()) return value.trim();
54
+ }
55
+ }
56
+ return void 0;
57
+ }
58
+
23
59
  // src/connection.ts
24
60
  import { createHash, randomUUID } from "crypto";
25
61
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
26
62
  import { homedir } from "os";
27
63
  import { basename, dirname, join, resolve } from "path";
28
- import { pickRandomNameWithGender } from "@bendyline/gezel";
64
+ import {
65
+ getLogLevel,
66
+ getLogOutput,
67
+ pickRandomNameWithGender,
68
+ setLogLevel,
69
+ setLogOutput
70
+ } from "@bendyline/gezel";
29
71
  import {
30
72
  GezelSdkError,
31
73
  authorizeLocal,
@@ -38,6 +80,7 @@ import {
38
80
  createTrustingFetch,
39
81
  discoverOrSpawn,
40
82
  electronNativeBinCandidates,
83
+ ensureProjectForFolder as ensureClientProjectForFolder,
41
84
  isProcessAlive,
42
85
  readRuntime,
43
86
  readSystemServiceEndpoint,
@@ -46,6 +89,31 @@ import {
46
89
  systemSharedAssetsDir
47
90
  } from "@bendyline/gezel-client/node";
48
91
  import { gezelPaths } from "@bendyline/gezel/paths";
92
+
93
+ // src/signal-cleanup.ts
94
+ function installSignalCleanup(cleanup, options = {}) {
95
+ if (!cleanup) return () => {
96
+ };
97
+ const host = options.host ?? process;
98
+ let cleanupPromise;
99
+ const onSignal = (signal) => {
100
+ host.exitCode = signal === "SIGINT" ? 130 : 143;
101
+ cleanupPromise ??= cleanup().catch((error) => {
102
+ options.onError?.(error);
103
+ host.exitCode = 1;
104
+ });
105
+ };
106
+ const onSigint = () => onSignal("SIGINT");
107
+ const onSigterm = () => onSignal("SIGTERM");
108
+ host.on("SIGINT", onSigint);
109
+ host.on("SIGTERM", onSigterm);
110
+ return () => {
111
+ host.off("SIGINT", onSigint);
112
+ host.off("SIGTERM", onSigterm);
113
+ };
114
+ }
115
+
116
+ // src/connection.ts
49
117
  var CliError = class extends Error {
50
118
  constructor(message) {
51
119
  super(message);
@@ -93,7 +161,7 @@ function resolveDevHome(globals) {
93
161
  process.env.GEZEL_HOME = join(homedir(), ".gezel-dev");
94
162
  }
95
163
  }
96
- async function connectOwned(globals) {
164
+ async function connectOwned(globals, options = {}) {
97
165
  applyHome(globals);
98
166
  const preferred = await connectPreferredService(globals);
99
167
  if (preferred) return preferred.client;
@@ -110,6 +178,9 @@ async function connectOwned(globals) {
110
178
  ...process.env.GEZEL_HOME ? { home: process.env.GEZEL_HOME } : {}
111
179
  }
112
180
  });
181
+ if (authorized.daemon.mode === "spawned" && options.announceSpawn !== false) {
182
+ process.stderr.write(spawnedDaemonNotice(authorized.daemon.pid));
183
+ }
113
184
  const connected = await connectionFromAuthorization(
114
185
  authorized,
115
186
  "The local Gezel owner authorization"
@@ -128,6 +199,8 @@ async function connectForTui(globals) {
128
199
  daemonEntry: resolveDaemonEntry(import.meta.url),
129
200
  detached: false,
130
201
  stdio: "pipe",
202
+ // The pipes below are drained and discarded, so the daemon keeps its own log.
203
+ writeLogFile: true,
131
204
  env: cliUserDaemonEnv(process.env.GEZEL_HOME, await shouldPreferCanonicalPort()),
132
205
  ...process.env.GEZEL_HOME ? { home: process.env.GEZEL_HOME } : {},
133
206
  timeoutMs: 2e4
@@ -241,6 +314,39 @@ async function connectForRun(globals) {
241
314
  };
242
315
  return { kind: "owned", client, baseUrl, stop };
243
316
  }
317
+ function spawnedDaemonNotice(pid) {
318
+ const which = pid === void 0 ? "" : ` (pid ${pid})`;
319
+ return `Started the Gezel background service${which}; it keeps running after this command. Stop it with \`gezel stop --daemon\`.
320
+ `;
321
+ }
322
+ async function withTransientConnection(globals, fn) {
323
+ const previousLogOutput = getLogOutput();
324
+ setLogOutput("stderr");
325
+ const previousLogLevel = getLogLevel();
326
+ if (!process.env.GEZEL_LOG_LEVEL && previousLogLevel === "info") setLogLevel("warn");
327
+ let conn;
328
+ let removeSignalCleanup;
329
+ try {
330
+ conn = await connectForRun(globals);
331
+ removeSignalCleanup = installSignalCleanup(conn.stop, {
332
+ onError: (error) => {
333
+ process.stderr.write(
334
+ `shutdown failed: ${error instanceof Error ? error.message : String(error)}
335
+ `
336
+ );
337
+ }
338
+ });
339
+ return await fn(conn.client);
340
+ } finally {
341
+ removeSignalCleanup?.();
342
+ try {
343
+ if (conn?.stop) await conn.stop();
344
+ } finally {
345
+ setLogOutput(previousLogOutput);
346
+ setLogLevel(previousLogLevel);
347
+ }
348
+ }
349
+ }
244
350
  var CLI_APP_ID_PREFIX = "gezel-cli";
245
351
  var CLI_APPROVAL_TIMEOUT_SEC = 300;
246
352
  var PENDING_GRANT_MINUTES = 10;
@@ -503,25 +609,15 @@ function fileTokenStorage(storageKey) {
503
609
  }
504
610
  async function ensureProjectForFolder(client, folderPath) {
505
611
  const wd = resolve(folderPath);
506
- const eq = (a, b) => !!a && (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
507
- const { projects } = await client.listProjects();
508
- const exact = projects.find((p) => eq(p.workingDir, wd));
509
- if (exact) return exact.id;
510
612
  const name = basename(wd) || "workspace";
511
- const orphan = projects.find((p) => !p.workingDir && p.name === name);
512
- if (orphan) {
513
- await client.setProjectWorkingDir(orphan.id, wd);
514
- return orphan.id;
515
- }
516
- const created = await client.createProject({
517
- name,
613
+ const result = await ensureClientProjectForFolder(client, wd, {
614
+ mode: "solo",
615
+ source: "cli",
518
616
  description: `CLI workspace at ${wd}`,
519
617
  about: `${name} \u2014 working directory ${wd}. Fill in who this project is for, what's in scope, and what's explicitly out of scope.`,
520
- missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`,
521
- mode: "solo",
522
- workingDir: wd
618
+ missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`
523
619
  });
524
- return created.id;
620
+ return result.projectId;
525
621
  }
526
622
  async function ensureCliProjectLead(client, projectId) {
527
623
  const project = await client.getProject(projectId);
@@ -570,7 +666,8 @@ async function resolveTuiProject(client, globals) {
570
666
  }
571
667
 
572
668
  // src/craftbook-command.ts
573
- import { AwakeBudget } from "@bendyline/gezel";
669
+ import { setTimeout as delay } from "timers/promises";
670
+ import { createAwakeTimeout } from "@bendyline/gezel";
574
671
 
575
672
  // src/tui/craftbook-start.ts
576
673
  import {
@@ -666,37 +763,94 @@ function parseCraftbookParams(book, tokens) {
666
763
  }
667
764
  return params;
668
765
  }
766
+ var READ_RETRY_DELAYS = [250, 750, 1500];
767
+ function transientTaskReadError(error) {
768
+ const codes = /ECONNRESET|ECONNREFUSED|ECONNABORTED|EPIPE|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|EAI_AGAIN|UND_ERR_(?:SOCKET|CONNECT_TIMEOUT)|NGHTTP2_ENHANCE_YOUR_CALM|Connect Timeout Error|socket hang up|other side closed/;
769
+ if (error instanceof Error && error.name === "GezelApiError") {
770
+ const apiError = error;
771
+ return apiError.status === 0 && apiError.details?.kind === "transport" && apiError.details.readRetryExhausted !== true && typeof apiError.details.cause === "string" && codes.test(apiError.details.cause);
772
+ }
773
+ return error instanceof TypeError && error.cause instanceof Error && codes.test(`${error.cause.code ?? ""} ${error.cause.message}`);
774
+ }
775
+ async function readTaskObservation(read, budget, signal) {
776
+ for (let retries = 0; ; retries++) {
777
+ signal.throwIfAborted();
778
+ if (retries > 0 && budget.expired()) throw new CliError("Task observation timed out.");
779
+ try {
780
+ return await read();
781
+ } catch (error) {
782
+ signal.throwIfAborted();
783
+ if (!transientTaskReadError(error) || retries >= READ_RETRY_DELAYS.length || budget.expired())
784
+ throw error;
785
+ await sleepWithinBudget(READ_RETRY_DELAYS[retries], budget, signal);
786
+ }
787
+ }
788
+ }
789
+ async function sleepWithinBudget(backoffMs, budget, signal) {
790
+ if (budget.remainingMs() > backoffMs) {
791
+ await delay(backoffMs, void 0, { signal });
792
+ return;
793
+ }
794
+ while (!budget.expired()) {
795
+ await delay(Math.max(1, budget.remainingMs()), void 0, { signal });
796
+ }
797
+ }
669
798
  async function waitForTask(client, ref, options) {
670
- const budget = new AwakeBudget(options.timeoutMs);
799
+ const timeout = createAwakeTimeout(options.timeoutMs, { pollMs: 100 });
800
+ const budget = timeout.budget;
801
+ const signal = options.signal ? AbortSignal.any([options.signal, timeout.signal]) : timeout.signal;
671
802
  let previous = "";
672
- for (; ; ) {
673
- const task2 = await client.getTaskByRef(ref);
674
- const progress = `${task2.status}:${task2.activeStepId}`;
675
- if (progress !== previous) {
676
- options.onProgress?.(task2);
677
- previous = progress;
678
- }
679
- if (task2.status === "complete") return { task: task2, outcome: "complete", exitCode: 0 };
680
- if (task2.status === "canceled") return { task: task2, outcome: "canceled", exitCode: 1 };
681
- if (task2.status === "paused" || task2.status === "draft")
682
- return { task: task2, outcome: "blocked", exitCode: 2 };
683
- const refs = /* @__PURE__ */ new Set([task2.ref]);
684
- if (task2.fanout || task2.craftbook.spawn || task2.craftbook.cliWorkflow) {
685
- const { tasks } = await client.listTaskChildren(task2.projectId, task2.num);
686
- if (!task2.craftbook.cliWorkflow && !tasks.some((child) => child.status === "active") && tasks.some((child) => child.status === "paused" || child.status === "canceled"))
803
+ let lastTask;
804
+ const read = (operation) => readTaskObservation(operation, budget, signal);
805
+ try {
806
+ for (; ; ) {
807
+ const task2 = await read(() => client.getTaskByRef(ref, signal));
808
+ lastTask = task2;
809
+ const progress = `${task2.status}:${task2.activeStepId}`;
810
+ if (progress !== previous) {
811
+ options.onProgress?.(task2);
812
+ previous = progress;
813
+ }
814
+ if (task2.status === "complete") return { task: task2, outcome: "complete", exitCode: 0 };
815
+ if (task2.status === "canceled") return { task: task2, outcome: "canceled", exitCode: 1 };
816
+ if (task2.status === "paused" || task2.status === "draft")
687
817
  return { task: task2, outcome: "blocked", exitCode: 2 };
688
- if (!task2.craftbook.cliWorkflow) for (const child of tasks) refs.add(child.ref);
689
- }
690
- if (client.listQuestions) {
691
- const { questions } = await client.listQuestions({
692
- projectId: task2.projectId,
693
- pending: true
694
- });
695
- const questionIds = questions.filter((q) => q.taskRef && refs.has(q.taskRef)).map((q) => q.id);
696
- if (questionIds.length) return { task: task2, outcome: "blocked", exitCode: 2, questionIds };
818
+ const refs = /* @__PURE__ */ new Set([task2.ref]);
819
+ if (task2.fanout || task2.craftbook.spawn || task2.craftbook.cliWorkflow) {
820
+ const { tasks } = await read(
821
+ () => client.listTaskChildren(task2.projectId, task2.num, void 0, signal)
822
+ );
823
+ if (!task2.craftbook.cliWorkflow && !tasks.some((child) => child.status === "active") && tasks.some((child) => child.status === "paused" || child.status === "canceled"))
824
+ return { task: task2, outcome: "blocked", exitCode: 2 };
825
+ if (!task2.craftbook.cliWorkflow) for (const child of tasks) refs.add(child.ref);
826
+ }
827
+ if (client.listQuestions) {
828
+ const { questions } = await read(
829
+ () => client.listQuestions(
830
+ {
831
+ projectId: task2.projectId,
832
+ pending: true
833
+ },
834
+ signal
835
+ )
836
+ );
837
+ const questionIds = questions.filter(
838
+ (q) => q.taskRef && refs.has(q.taskRef) && // A service pause card is a historical notification. Actual task
839
+ // status above decides whether it is still paused; real session
840
+ // questions and permissions must continue to block observation.
841
+ !(q.sessionId === "" && q.intent?.kind === "task-paused")
842
+ ).map((q) => q.id);
843
+ if (questionIds.length) return { task: task2, outcome: "blocked", exitCode: 2, questionIds };
844
+ }
845
+ if (budget.expired()) return { task: task2, outcome: "timeout", exitCode: 3 };
846
+ await delay(Math.min(options.pollMs ?? 1e3, budget.remainingMs()), void 0, { signal });
697
847
  }
698
- if (budget.expired()) return { task: task2, outcome: "timeout", exitCode: 3 };
699
- await new Promise((resolve6) => setTimeout(resolve6, options.pollMs ?? 1e3));
848
+ } catch (error) {
849
+ options.signal?.throwIfAborted();
850
+ if (budget.expired() && lastTask) return { task: lastTask, outcome: "timeout", exitCode: 3 };
851
+ throw error;
852
+ } finally {
853
+ timeout.dispose();
700
854
  }
701
855
  }
702
856
 
@@ -981,6 +1135,11 @@ function formatGb(bytes) {
981
1135
  return (bytes / 1e9).toFixed(2);
982
1136
  }
983
1137
 
1138
+ // src/native-command.ts
1139
+ import {
1140
+ NativeEngineNameSchema
1141
+ } from "@bendyline/gezel";
1142
+
984
1143
  // src/tui/bootstrap.ts
985
1144
  import {
986
1145
  computeModelFit,
@@ -1004,6 +1163,14 @@ function parseNativeVariant(value) {
1004
1163
  if (NATIVE_VARIANTS.includes(value)) return value;
1005
1164
  throw new CliError(`--variant must be one of ${NATIVE_VARIANTS.join(", ")} (got "${value}")`);
1006
1165
  }
1166
+ function parseNativeEngine(value) {
1167
+ if (value === void 0) return void 0;
1168
+ const parsed = NativeEngineNameSchema.safeParse(value);
1169
+ if (parsed.success) return parsed.data;
1170
+ throw new CliError(
1171
+ `--engine must be one of ${NativeEngineNameSchema.options.join(", ")} (got "${value}")`
1172
+ );
1173
+ }
1007
1174
  function formatNativeStatus(status) {
1008
1175
  const installed = new Set(
1009
1176
  status.engines.filter((engine) => engine.installed).map((engine) => engine.name)
@@ -1013,7 +1180,9 @@ function formatNativeStatus(status) {
1013
1180
  `release: native-v${status.release} (${status.pinned ? "verified pin" : "unpinned \u2014 downloads disabled"})`,
1014
1181
  `platform: ${status.platformKey ?? "unsupported \u2014 downloads unavailable"}`,
1015
1182
  `llama backend: ${status.llamaBackend ?? "automatic"}`,
1016
- `toolkit: ${toolkitInstalled}/${NATIVE_TOOLKIT.length} installed`
1183
+ // Name the members: `native list` shows every engine the release carries
1184
+ // (ds4, duckdb too), so a bare "0/4" read as a miscount beside it.
1185
+ `toolkit: ${toolkitInstalled}/${NATIVE_TOOLKIT.length} installed (${NATIVE_TOOLKIT.join(", ")}; see \`gezel native list\` for every engine)`
1017
1186
  ].join("\n");
1018
1187
  }
1019
1188
  function formatNativeList(status) {
@@ -1040,7 +1209,7 @@ async function installNativeToolkit(client, options) {
1040
1209
  );
1041
1210
  }
1042
1211
  const llamaVariant = options.variant ?? status.llamaBackend;
1043
- for (const engine of NATIVE_TOOLKIT) {
1212
+ for (const engine of options.engines ?? NATIVE_TOOLKIT) {
1044
1213
  await ensureOneEngine(client, engine, llamaVariant, options.output);
1045
1214
  }
1046
1215
  return client.getNativeEngineStatus();
@@ -1114,6 +1283,84 @@ function errorMessage(error) {
1114
1283
  return error instanceof Error ? error.message : String(error);
1115
1284
  }
1116
1285
 
1286
+ // src/run-readiness.ts
1287
+ var READY = { ready: true };
1288
+ async function settledFirstRunConfig(client, options = {}) {
1289
+ const attempts = options.attempts ?? 12;
1290
+ const delayMs = options.delayMs ?? 250;
1291
+ let config = await client.getConfig();
1292
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
1293
+ if (config.firstRunCompleted || config.provider !== "copilot") return config;
1294
+ await new Promise((resolve6) => setTimeout(resolve6, delayMs));
1295
+ config = await client.getConfig();
1296
+ }
1297
+ return config;
1298
+ }
1299
+ async function checkRunReadiness(client, gezelId, env2 = process.env) {
1300
+ if (env2.GEZEL_MOCK_PROVIDER === "1") return READY;
1301
+ const config = await settledFirstRunConfig(client);
1302
+ let provider = config.provider;
1303
+ if (gezelId) {
1304
+ try {
1305
+ const { parsed } = await client.getGezel(gezelId);
1306
+ if (parsed.frontmatter.provider) provider = parsed.frontmatter.provider;
1307
+ } catch {
1308
+ }
1309
+ }
1310
+ if (provider !== "llama-cpp" && provider !== "mlx") return READY;
1311
+ if (provider === "llama-cpp" && (config.llamaCppBaseUrl || config.llamaCppModelPath)) {
1312
+ return READY;
1313
+ }
1314
+ if (provider === "mlx" && (config.mlxBaseUrl || config.mlxModelPath)) return READY;
1315
+ const native2 = await client.getNativeEngineStatus();
1316
+ if (!native2.platformKey) return READY;
1317
+ const installed = provider === "mlx" ? await client.listMlxModels() : await client.listLlamaCppModels();
1318
+ const installedIds = installed.models.map((model2) => model2.id);
1319
+ const pinned = config.defaultModel?.[provider];
1320
+ const engineMissing = provider === "llama-cpp" && !native2.engines.some((engine) => engine.name === "llama-server" && engine.installed);
1321
+ const modelReady = pinned ? installedIds.includes(pinned) : installedIds.length > 0;
1322
+ if (!engineMissing && modelReady) return READY;
1323
+ return {
1324
+ ready: false,
1325
+ message: formatRunSetupMessage({
1326
+ provider,
1327
+ engineMissing,
1328
+ pinned,
1329
+ installedIds
1330
+ })
1331
+ };
1332
+ }
1333
+ function formatRunSetupMessage(input) {
1334
+ const { provider, engineMissing, pinned, installedIds } = input;
1335
+ const steps = [];
1336
+ if (engineMissing) steps.push("gezel native install");
1337
+ if (pinned && !installedIds.includes(pinned)) {
1338
+ steps.push(`gezel model pull ${pinned}${provider === "mlx" ? " --provider mlx" : ""}`);
1339
+ } else if (!pinned && installedIds.length === 0) {
1340
+ steps.push("gezel model list (then: gezel model pull <id>)");
1341
+ }
1342
+ const lines = [];
1343
+ if (pinned && !installedIds.includes(pinned) && installedIds.length > 0) {
1344
+ lines.push(`Your selected on-device model, ${pinned}, isn't downloaded yet.`);
1345
+ } else if (engineMissing && installedIds.length > 0 && (!pinned || installedIds.includes(pinned))) {
1346
+ lines.push("Gezel's on-device engine isn't installed yet.");
1347
+ } else {
1348
+ lines.push("Gezel isn't set up to chat yet: this device doesn't have an on-device model.");
1349
+ }
1350
+ lines.push("", "Run `gezel` to choose a model and download it, step by step.");
1351
+ if (steps.length > 0) {
1352
+ lines.push("", "Or set it up directly:", ...steps.map((step) => ` ${step}`));
1353
+ }
1354
+ lines.push(
1355
+ "",
1356
+ "To use a cloud model instead, save a key (for example",
1357
+ "`gezel secret set openaiApiKey --stdin`), then run `gezel` and pick it with /model.",
1358
+ "",
1359
+ "Nothing was downloaded."
1360
+ );
1361
+ return lines.join("\n");
1362
+ }
1363
+
1117
1364
  // src/secrets-command.ts
1118
1365
  import { GezelApiError as GezelApiError2 } from "@bendyline/gezel-client";
1119
1366
  var credentialFlags = {
@@ -1187,14 +1434,15 @@ function registerSecretCommands(program2, connect, output = console.log) {
1187
1434
  options.json ? JSON.stringify({ credentials }) : credentials.map((c) => `${c.name} ${c.configured ? "configured" : "not configured"}`).join("\n")
1188
1435
  );
1189
1436
  });
1190
- secret.command("set <name>").description("Save a provider credential in the service credential store").option("--env <VARIABLE>", "Read the value from this environment variable").option("--stdin", "Read the value from piped stdin").option(
1191
- "--use-for-search",
1192
- "Also select this Brave or Tavily credential as the web search provider"
1193
- ).option("--json", "Output status as JSON without the value").action(async (name, options) => {
1437
+ secret.command("set <name>").description("Save a provider credential in the service credential store").option("--env <VARIABLE>", "Read the value from this environment variable").option("--stdin", "Read the value from piped stdin").option("--use-for-search", "Also select this Brave credential as the web search provider").option("--json", "Output status as JSON without the value").action(async (name, options) => {
1194
1438
  const key = credentialName(name);
1195
- const provider = key === "braveSearchApiKey" ? "brave" : key === "tavilyApiKey" ? "tavily" : void 0;
1439
+ if (options.useForSearch && key === "tavilyApiKey")
1440
+ throw new CliError(
1441
+ "Tavily search is not available yet. Save the key without --use-for-search, and use braveSearchApiKey (or the built-in Wikipedia search) for now."
1442
+ );
1443
+ const provider = key === "braveSearchApiKey" ? "brave" : void 0;
1196
1444
  if (options.useForSearch && !provider)
1197
- throw new CliError("--use-for-search requires braveSearchApiKey or tavilyApiKey.");
1445
+ throw new CliError("--use-for-search requires braveSearchApiKey.");
1198
1446
  const value = await readSecretInput(options);
1199
1447
  const client = await connect();
1200
1448
  const patch = { [key]: value };
@@ -1255,29 +1503,6 @@ function registerProjectSettingsCommands(env2, connect, projectFor) {
1255
1503
  });
1256
1504
  }
1257
1505
 
1258
- // src/signal-cleanup.ts
1259
- function installSignalCleanup(cleanup, options = {}) {
1260
- if (!cleanup) return () => {
1261
- };
1262
- const host = options.host ?? process;
1263
- let cleanupPromise;
1264
- const onSignal = (signal) => {
1265
- host.exitCode = signal === "SIGINT" ? 130 : 143;
1266
- cleanupPromise ??= cleanup().catch((error) => {
1267
- options.onError?.(error);
1268
- host.exitCode = 1;
1269
- });
1270
- };
1271
- const onSigint = () => onSignal("SIGINT");
1272
- const onSigterm = () => onSignal("SIGTERM");
1273
- host.on("SIGINT", onSigint);
1274
- host.on("SIGTERM", onSigterm);
1275
- return () => {
1276
- host.off("SIGINT", onSigint);
1277
- host.off("SIGTERM", onSigterm);
1278
- };
1279
- }
1280
-
1281
1506
  // src/storage-format.ts
1282
1507
  function formatBytes2(bytes) {
1283
1508
  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
@@ -1459,6 +1684,51 @@ function resolveRestoreSelection(review, opts) {
1459
1684
  return { items, skipped };
1460
1685
  }
1461
1686
 
1687
+ // src/unknown-command.ts
1688
+ function unknownCommandMessage(operands, known) {
1689
+ const word = operands[0] ?? "";
1690
+ const lines = [`error: unknown command '${word}'`];
1691
+ const looksLikePrompt = operands.length > 1 || /\s/.test(word) || word.length > 24;
1692
+ const suggestion = looksLikePrompt ? void 0 : closestCommand(word, known);
1693
+ if (suggestion) lines.push(`(Did you mean ${suggestion}?)`);
1694
+ if (looksLikePrompt) {
1695
+ lines.push('To send a prompt, use: gezel run "<prompt>"');
1696
+ }
1697
+ lines.push("Run `gezel --help` to see every command.");
1698
+ return lines.join("\n");
1699
+ }
1700
+ function closestCommand(word, known) {
1701
+ const target = word.toLowerCase();
1702
+ if (!target) return void 0;
1703
+ const limit = Math.max(1, Math.floor(target.length * 0.4));
1704
+ let best;
1705
+ for (const name of known) {
1706
+ const distance = editDistance(target, name.toLowerCase());
1707
+ if (distance > limit) continue;
1708
+ if (!best || distance < best.distance) best = { name, distance };
1709
+ }
1710
+ return best?.name;
1711
+ }
1712
+ function editDistance(a, b) {
1713
+ const rows = a.length + 1;
1714
+ const cols = b.length + 1;
1715
+ const d = Array.from(
1716
+ { length: rows },
1717
+ (_, i) => Array.from({ length: cols }, (_2, j) => i === 0 ? j : j === 0 ? i : 0)
1718
+ );
1719
+ for (let i = 1; i < rows; i += 1) {
1720
+ for (let j = 1; j < cols; j += 1) {
1721
+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;
1722
+ let value = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
1723
+ if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
1724
+ value = Math.min(value, d[i - 2][j - 2] + 1);
1725
+ }
1726
+ d[i][j] = value;
1727
+ }
1728
+ }
1729
+ return d[a.length][b.length];
1730
+ }
1731
+
1462
1732
  // src/workflow-command.ts
1463
1733
  import { realpath } from "fs/promises";
1464
1734
  import { isAbsolute as isAbsolute2, relative, resolve as resolve5 } from "path";
@@ -1530,12 +1800,12 @@ async function runWorkflow(client, projectId, workspace, file, args, log = conso
1530
1800
 
1531
1801
  // src/bin/gezel.ts
1532
1802
  var program = new Command();
1533
- program.name("gezel").description("Gezel \u2014 build a community of agents that do things.").version(GEZEL_VERSION).option(
1803
+ program.name("gezel").description("Gezel \u2014 assemble a team of AI companions (gezels) and put them to work.").version(GEZEL_VERSION).option(
1534
1804
  "--connect <url>",
1535
1805
  "Connect to this Gezel service (first use asks for approval in the Gezel app)."
1536
- ).option("--token <token>", "Bearer token for --connect (must have CLI access).").option(
1806
+ ).option("--token <token>", "Bearer token for --connect (must have CLI access).").option("--http1", "Use HTTP/1.1 for daemon requests, keeping TLS certificate validation.").option(
1537
1807
  "--standalone",
1538
- "Skip legacy full-product machine-service compatibility and use the per-user daemon."
1808
+ "Always use your own per-user Gezel service, even if an older machine-wide install is present."
1539
1809
  ).option("--home <dir>", "Use this user-owned Gezel home (default: $GEZEL_HOME or ~/.gezel).").option(
1540
1810
  "--project [folder]",
1541
1811
  "Use this folder as the active project (default and bare flag: cwd)."
@@ -1546,9 +1816,23 @@ registerSecurityCommands(program, () => connectOwned(cliGlobals()));
1546
1816
  program.hook("preAction", () => {
1547
1817
  const globals = cliGlobals();
1548
1818
  validateGlobals(globals);
1819
+ if (globals.http1) process.env.GEZEL_HTTP_VERSION = "1.1";
1549
1820
  applyHome(globals);
1550
1821
  });
1551
1822
  program.action(async () => {
1823
+ if (program.args.length > 0) {
1824
+ const known = program.commands.flatMap((command) => [command.name(), ...command.aliases()]);
1825
+ throw new CliError(unknownCommandMessage(program.args, known));
1826
+ }
1827
+ if (!process.stdin.isTTY || !process.stdout.isTTY) {
1828
+ throw new CliError(
1829
+ [
1830
+ "The interactive Gezel terminal needs a terminal window, and this one is not interactive.",
1831
+ 'For a one-shot reply, use: gezel run "<prompt>"',
1832
+ "Run `gezel --help` to see every command."
1833
+ ].join("\n")
1834
+ );
1835
+ }
1552
1836
  const globals = cliGlobals();
1553
1837
  resolveDevHome(globals);
1554
1838
  const connection = await connectForTui(globals);
@@ -1627,7 +1911,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
1627
1911
  if (opts.web) await printWebUrl(result.baseUrl, opts.open === true);
1628
1912
  return;
1629
1913
  }
1630
- const client = await connectOwned(cliGlobals());
1914
+ const client = await connectOwned(cliGlobals(), { announceSpawn: false });
1631
1915
  const health = await client.health();
1632
1916
  console.log(`gezeld running (version ${health.version})`);
1633
1917
  });
@@ -1696,7 +1980,7 @@ async function startForeground(env2) {
1696
1980
  process.off("SIGTERM", requestStop);
1697
1981
  }
1698
1982
  }
1699
- program.command("status").description("Show daemon status").action(async () => {
1983
+ program.command("status").description("Show daemon status (exits 1 when gezeld is not running or not healthy)").action(async () => {
1700
1984
  const globals = cliGlobals();
1701
1985
  if (globals.connect) {
1702
1986
  const client2 = await connectOwned(globals);
@@ -1732,11 +2016,16 @@ program.command("status").description("Show daemon status").action(async () => {
1732
2016
  const runtime = await readRuntime2();
1733
2017
  if (!runtime) {
1734
2018
  console.log("gezeld is not running");
2019
+ process.exitCode = 1;
1735
2020
  return;
1736
2021
  }
1737
2022
  const alive = isProcessAlive2(runtime.pid);
2023
+ if (!alive) {
2024
+ console.log(`gezeld is not running (stale runtime record for pid ${runtime.pid})`);
2025
+ process.exitCode = 1;
2026
+ return;
2027
+ }
1738
2028
  console.log(`gezeld pid=${runtime.pid} port=${runtime.port} alive=${alive}`);
1739
- if (!alive) return;
1740
2029
  const client = new GezelClient2({
1741
2030
  baseUrl: runtime.baseUrl,
1742
2031
  // Health is intentionally unauthenticated; diagnostics do not need to
@@ -1752,17 +2041,21 @@ program.command("status").description("Show daemon status").action(async () => {
1752
2041
  );
1753
2042
  } catch (err) {
1754
2043
  console.error(`health failed: ${err.message}`);
2044
+ process.exitCode = 1;
1755
2045
  }
1756
2046
  });
1757
- program.command("stop").description("Hard stop all AI work and switch Gezel to Reactive mode").option("--daemon", "Shut down the user-owned daemon process itself").action(async (opts) => {
2047
+ program.command("stop").description(
2048
+ "Hard stop all AI work and switch Gezel to Reactive mode; gezeld keeps running (use --daemon to shut it down)"
2049
+ ).option("--daemon", "Shut down the user-owned daemon process itself").action(async (opts) => {
1758
2050
  const globals = cliGlobals();
1759
2051
  if (opts.daemon) {
1760
2052
  await stopUserDaemon(globals);
1761
2053
  return;
1762
2054
  }
2055
+ let userRuntime = null;
1763
2056
  if (!globals.connect && !await findHealthySystemService(globals)) {
1764
- const runtime = await readRuntime2();
1765
- if (!runtime || !isProcessAlive2(runtime.pid)) {
2057
+ userRuntime = await readRuntime2();
2058
+ if (!userRuntime || !isProcessAlive2(userRuntime.pid)) {
1766
2059
  console.log("Gezel has no running AI work to stop.");
1767
2060
  return;
1768
2061
  }
@@ -1777,7 +2070,32 @@ program.command("stop").description("Hard stop all AI work and switch Gezel to R
1777
2070
  console.log(
1778
2071
  `Hard stop complete: ${details.join(", ")}. Local engines unloaded; Gezel is Reactive.`
1779
2072
  );
2073
+ if (userRuntime) {
2074
+ console.log(
2075
+ `gezeld is still running (pid ${userRuntime.pid}); run \`gezel stop --daemon\` to shut it down.`
2076
+ );
2077
+ }
1780
2078
  });
2079
+ async function clearStaleRuntime(stoppedPid) {
2080
+ const { readFile: readFile3, rm: rm3 } = await import("fs/promises");
2081
+ const { gezelPaths: gezelPaths2 } = await import("@bendyline/gezel/paths");
2082
+ const runtime = gezelPaths2().runtime;
2083
+ const recorded = Number.parseInt(
2084
+ (await readFile3(runtime.pid, "utf8").catch(() => "")).trim(),
2085
+ 10
2086
+ );
2087
+ if (recorded !== stoppedPid || isProcessAlive2(stoppedPid)) return;
2088
+ await Promise.all(
2089
+ [
2090
+ runtime.pid,
2091
+ runtime.port,
2092
+ runtime.token,
2093
+ runtime.cert,
2094
+ runtime.fingerprint,
2095
+ runtime.webUiToken
2096
+ ].map((path) => rm3(path, { force: true }))
2097
+ );
2098
+ }
1781
2099
  async function stopUserDaemon(globals) {
1782
2100
  if (globals.connect) {
1783
2101
  throw new CliError("gezel stop --daemon cannot stop an explicit remote service.");
@@ -1796,6 +2114,7 @@ async function stopUserDaemon(globals) {
1796
2114
  }
1797
2115
  const stopped = await stopProcessByPid(runtime.pid);
1798
2116
  if (stopped) {
2117
+ await clearStaleRuntime(runtime.pid);
1799
2118
  console.log(`stopped gezeld pid=${runtime.pid}`);
1800
2119
  } else {
1801
2120
  console.error(`failed to confirm gezeld pid=${runtime.pid} stopped`);
@@ -1827,8 +2146,10 @@ program.command("run [prompt...]").description("Run a prompt through a gezel and
1827
2146
  process.exitCode = 1;
1828
2147
  return;
1829
2148
  }
1830
- const previousLogOutput = getLogOutput();
1831
- setLogOutput("stderr");
2149
+ const previousLogOutput = getLogOutput2();
2150
+ setLogOutput2("stderr");
2151
+ const previousLogLevel = getLogLevel2();
2152
+ if (!process.env.GEZEL_LOG_LEVEL && previousLogLevel === "info") setLogLevel2("warn");
1832
2153
  let conn;
1833
2154
  let removeSignalCleanup;
1834
2155
  try {
@@ -1843,6 +2164,12 @@ program.command("run [prompt...]").description("Run a prompt through a gezel and
1843
2164
  const { client } = conn;
1844
2165
  const projectId = await resolveRunProject(client, cliGlobals());
1845
2166
  const gezelId = opts.gezel ?? await ensureCliProjectLead(client, projectId);
2167
+ const readiness = await checkRunReadiness(client, gezelId);
2168
+ if (!readiness.ready) {
2169
+ console.error(readiness.message);
2170
+ process.exitCode = 1;
2171
+ return;
2172
+ }
1846
2173
  const session = await client.createChatSession({ gezelId, projectId });
1847
2174
  await client.sendToChatSession(session.id, prompt);
1848
2175
  let printed = false;
@@ -1873,7 +2200,8 @@ ${ev.error}`);
1873
2200
  try {
1874
2201
  if (conn?.stop) await conn.stop();
1875
2202
  } finally {
1876
- setLogOutput(previousLogOutput);
2203
+ setLogOutput2(previousLogOutput);
2204
+ setLogLevel2(previousLogLevel);
1877
2205
  }
1878
2206
  }
1879
2207
  });
@@ -1978,7 +2306,7 @@ async function printTaskWait(client, ref, opts) {
1978
2306
  console.log(opts.json ? JSON.stringify(result) : `${result.task.ref}: ${result.outcome}`);
1979
2307
  process.exitCode = result.exitCode;
1980
2308
  }
1981
- var agent = program.command("agent").description("Manage agents");
2309
+ var agent = program.command("agent").description("Manage your gezels (your AI companions)");
1982
2310
  agent.command("output-limit <id> [tokens]").description(
1983
2311
  "Show or set one gezel's output-token limit, including reasoning; auto clears its override"
1984
2312
  ).option("--json", "Output the per-gezel override as JSON").action(async (id, tokens, opts) => {
@@ -2001,24 +2329,26 @@ agent.command("output-limit <id> [tokens]").description(
2001
2329
  opts.json ? JSON.stringify(result) : `${id}: ${result.outputTokens === null ? "auto (inherits model/profile defaults)" : `${result.outputTokens} output tokens, including reasoning`}`
2002
2330
  );
2003
2331
  });
2004
- agent.command("list").description("List agents").action(async () => {
2332
+ agent.command("list").description("List your gezels").action(async () => {
2005
2333
  const client = await connectOwned(cliGlobals());
2006
2334
  const res = await client.listGezels();
2007
2335
  for (const a of res.gezels) {
2008
2336
  console.log(`${a.id.padEnd(20)} ${a.name}`);
2009
2337
  }
2010
2338
  });
2011
- agent.command("create <name>").description("Create a new agent").option("-d, --description <text>", "description").option("-m, --model <model>", "model identifier").action(async (name, opts) => {
2339
+ agent.command("create <name>").description("Create a new gezel").option("-d, --description <text>", "description").option("-m, --model <model>", "model identifier").action(async (name, opts) => {
2012
2340
  const client = await connectOwned(cliGlobals());
2013
2341
  const created = await client.createGezel({ name, ...opts });
2014
- console.log(`created agent ${created.id}`);
2342
+ console.log(`created gezel ${created.id}`);
2015
2343
  });
2016
- agent.command("show <id>").description("Show an agent").action(async (id) => {
2344
+ agent.command("show <id>").description("Show one gezel").action(async (id) => {
2017
2345
  const client = await connectOwned(cliGlobals());
2018
- const a = await client.getGezel(id);
2346
+ const a = await client.getGezel(id).catch((err) => {
2347
+ throw isNotFound(err) ? new CliError(`No gezel with id "${id}". Run \`gezel agent list\` to see your gezels.`) : err;
2348
+ });
2019
2349
  console.log(a.parsed.source);
2020
2350
  });
2021
- var env = program.command("env").description("Manage projects");
2351
+ var env = program.command("env").alias("project").description("Manage projects (also available as `gezel project`)");
2022
2352
  registerProjectSettingsCommands(
2023
2353
  env,
2024
2354
  () => connectOwned(cliGlobals()),
@@ -2226,17 +2556,7 @@ knowledge.command("install <source>").description("Install a .gezk catalog into
2226
2556
  ...opts.private ? { privatePlacement: true } : {}
2227
2557
  });
2228
2558
  const client = await connectOwned(cliGlobals());
2229
- let started;
2230
- try {
2231
- started = await client.installKnowledgeCatalog({ source: installSource });
2232
- } catch (err) {
2233
- if (err instanceof GezelApiError3 && err.status === 403) {
2234
- throw new CliError(
2235
- "Downloading knowledge catalogs needs app network access, which the security policy turns off (Settings \u2192 Security)."
2236
- );
2237
- }
2238
- throw err;
2239
- }
2559
+ const started = await client.installKnowledgeCatalog({ source: installSource });
2240
2560
  if (started.alreadyRunning)
2241
2561
  console.error("Attaching to the install that is already running.");
2242
2562
  let done;
@@ -2457,7 +2777,9 @@ task.command("create <projectId> <title>").description("Create a task with a sin
2457
2777
  );
2458
2778
  task.command("show <ref>").description("Show one task (format: projectId/num)").action(async (ref) => {
2459
2779
  const client = await connectOwned(cliGlobals());
2460
- const t = await client.getTaskByRef(ref);
2780
+ const t = await client.getTaskByRef(ref).catch((err) => {
2781
+ throw isNotFound(err) ? new CliError(`No task "${ref}". Run \`gezel task list\` to see task references.`) : err;
2782
+ });
2461
2783
  console.log(JSON.stringify(t, null, 2));
2462
2784
  });
2463
2785
  task.command("notes <ref>").description("Read task notes, including pause reasons and failed checks").option("--warnings", "Also include model/runtime warnings from the latest 20 task sessions").option("--json", "Output the notes as JSON").action(async (ref, opts) => {
@@ -2582,6 +2904,7 @@ program.command("create-audio [text...]").description("Synthesize speech from te
2582
2904
  `speech synthesis failed: ${err instanceof Error ? err.message : String(err)}`
2583
2905
  );
2584
2906
  }
2907
+ if (!res.artifactPath) throw new CliError("speech synthesis returned no saved audio");
2585
2908
  const dest = await saveArtifact(client, projectId, res.artifactPath, opts.output);
2586
2909
  const m = res.meta;
2587
2910
  console.log(dest);
@@ -2590,23 +2913,35 @@ program.command("create-audio [text...]").description("Synthesize speech from te
2590
2913
  );
2591
2914
  });
2592
2915
  var native = program.command("native").description("Manage native engine binaries");
2593
- native.command("install").description("Download, verify, and activate the native inference toolkit").option("--variant <backend>", "llama.cpp backend: cuda | vulkan | metal | cpu").action(async (opts) => {
2916
+ native.command("install").description(
2917
+ "Download, verify, and activate the native inference toolkit (or one engine with --engine)"
2918
+ ).option("--variant <backend>", "llama.cpp backend: cuda | vulkan | metal | cpu").option("--engine <name>", "install only this engine, e.g. duckdb or llama-server").action(async (opts) => {
2594
2919
  const variant = parseNativeVariant(opts.variant);
2920
+ const engine = parseNativeEngine(opts.engine);
2595
2921
  const client = await connectOwned(cliGlobals());
2596
2922
  const installed = await installNativeToolkit(client, {
2597
2923
  ...variant ? { variant } : {},
2924
+ ...engine ? { engines: [engine] } : {},
2598
2925
  output: { writeProgress: (text) => process.stderr.write(text) }
2599
2926
  });
2600
- console.log(`native toolkit ready
2601
- ${formatNativeStatus(installed)}`);
2927
+ console.log(
2928
+ `${engine ? `${engine} ready` : "native toolkit ready"}
2929
+ ${formatNativeStatus(installed)}`
2930
+ );
2602
2931
  });
2603
2932
  native.command("list").description("List native executables and their install state").action(async () => {
2604
- const client = await connectOwned(cliGlobals());
2605
- console.log(formatNativeList(await client.getNativeEngineStatus()));
2933
+ const status = await withTransientConnection(
2934
+ cliGlobals(),
2935
+ (client) => client.getNativeEngineStatus()
2936
+ );
2937
+ console.log(formatNativeList(status));
2606
2938
  });
2607
2939
  native.command("status").description("Show native release, platform, backend, and toolkit status").action(async () => {
2608
- const client = await connectOwned(cliGlobals());
2609
- console.log(formatNativeStatus(await client.getNativeEngineStatus()));
2940
+ const status = await withTransientConnection(
2941
+ cliGlobals(),
2942
+ (client) => client.getNativeEngineStatus()
2943
+ );
2944
+ console.log(formatNativeStatus(status));
2610
2945
  });
2611
2946
  var image = program.command("image").description("Manage image-generation models");
2612
2947
  image.command("status").description("Show the image engine status and local model count").action(async () => {
@@ -2889,7 +3224,10 @@ Wrote ${outPath}`);
2889
3224
  program.command("restore <file>").description("Restore gezels, projects, and documents from a backup file").option("--list", "Show what the backup holds without restoring anything").option(
2890
3225
  "--only <item...>",
2891
3226
  "Restore just these items, by id (repeatable, e.g. --only tamsin roof-survey)"
2892
- ).option("--replace", "Overwrite items that already exist here").option("--settings", "Also restore preferences from the backup").action(
3227
+ ).option("--replace", "Overwrite items that already exist here").option(
3228
+ "--settings",
3229
+ "Also restore which gezels hold roles such as the meester (never providers, folders or security)"
3230
+ ).action(
2893
3231
  async (file, opts) => {
2894
3232
  const client = await connectOwned(cliGlobals());
2895
3233
  const review = await client.scanRestore({ path: resolvePath(file) });
@@ -2949,9 +3287,11 @@ async function pollStorageJob(client, jobId) {
2949
3287
  await new Promise((r) => setTimeout(r, 250));
2950
3288
  }
2951
3289
  }
3290
+ program.allowExcessArguments();
2952
3291
  program.parseAsync(process.argv).catch((err) => {
2953
- if (err instanceof CliError || err instanceof Error && err.name === "CliError") {
2954
- console.error(err.message);
3292
+ const friendly = formatCliFailure(err);
3293
+ if (friendly !== null) {
3294
+ console.error(friendly);
2955
3295
  } else {
2956
3296
  console.error(err);
2957
3297
  }
package/dist/bin/gezel.js CHANGED
@@ -1,6 +1,22 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ // src/bin/node-version.ts
4
+ var MINIMUM_NODE_MAJOR = 24;
5
+ function unsupportedNodeMessage(version) {
6
+ const major = Number.parseInt(version, 10);
7
+ if (!Number.isFinite(major) || major >= MINIMUM_NODE_MAJOR) return void 0;
8
+ return `Gezel needs Node.js ${MINIMUM_NODE_MAJOR} or newer (found v${version}).
9
+ Install Node.js ${MINIMUM_NODE_MAJOR} or later from https://nodejs.org, then run the command again.
10
+ `;
11
+ }
12
+
3
13
  // src/bin/gezel-launcher.ts
4
14
  if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
5
15
  var mainModule = "./gezel-main.js";
6
- await import(mainModule);
16
+ var unsupported = unsupportedNodeMessage(process.versions.node);
17
+ if (unsupported) {
18
+ process.stderr.write(unsupported);
19
+ process.exitCode = 1;
20
+ } else {
21
+ await import(mainModule);
22
+ }
@@ -442,6 +442,7 @@ body.hb {
442
442
  .hb-article .hb-scorecard-suite-title { font-size: 0.95rem; margin: 1.25rem 0 0.5rem; }
443
443
  .hb-scorecard-stamp { font-size: 0.85rem; margin: 0 0 0.75rem; }
444
444
  .hb-article .hb-scorecard-withheld,
445
+ .hb-article .hb-scorecard-memory-note,
445
446
  .hb-article .hb-scorecard-taskcount {
446
447
  font-size: 0.82rem;
447
448
  color: var(--hb-ink-muted);
@@ -12,6 +12,7 @@ import {
12
12
  EmbedderUnavailableError,
13
13
  KNOWLEDGE_EMBEDDING_PROFILES,
14
14
  MARKDOWN_CHUNKS_2,
15
+ TRANSFORMERS_PEER_RANGE,
15
16
  compileKnowledgeCatalog,
16
17
  createProfileEmbedder,
17
18
  detectTableOfContents,
@@ -29,7 +30,13 @@ import { createHash, randomUUID } from "crypto";
29
30
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
30
31
  import { homedir } from "os";
31
32
  import { basename, dirname, join, resolve } from "path";
32
- import { pickRandomNameWithGender } from "@bendyline/gezel";
33
+ import {
34
+ getLogLevel,
35
+ getLogOutput,
36
+ pickRandomNameWithGender,
37
+ setLogLevel,
38
+ setLogOutput
39
+ } from "@bendyline/gezel";
33
40
  import {
34
41
  GezelSdkError,
35
42
  authorizeLocal,
@@ -42,6 +49,7 @@ import {
42
49
  createTrustingFetch,
43
50
  discoverOrSpawn,
44
51
  electronNativeBinCandidates,
52
+ ensureProjectForFolder as ensureClientProjectForFolder,
45
53
  isProcessAlive,
46
54
  readRuntime,
47
55
  readSystemServiceEndpoint,
@@ -75,10 +83,22 @@ async function defaultCreateEmbedder(profileId) {
75
83
  try {
76
84
  return await createProfileEmbedder(profile, { cacheDir: hfCacheDir() });
77
85
  } catch (err) {
78
- if (err instanceof EmbedderUnavailableError) throw new CliError(err.message);
86
+ if (err instanceof EmbedderUnavailableError) {
87
+ throw new CliError(err.runtimeMissing ? embeddingRuntimeMissingMessage() : err.message);
88
+ }
79
89
  throw err;
80
90
  }
81
91
  }
92
+ function embeddingRuntimeMissingMessage() {
93
+ const spec = `@huggingface/transformers@${TRANSFORMERS_PEER_RANGE}`;
94
+ return [
95
+ "Building a catalog and --semantic search need the embedding runtime, which an npm install of Gezel leaves out.",
96
+ "Add it where Gezel is installed:",
97
+ ` npm install -g ${spec} if you installed gezel with npm install -g`,
98
+ ` npm install ${spec} in the project where you installed gezel`,
99
+ "The Gezel desktop app already includes it, and full-text search works without it."
100
+ ].join("\n");
101
+ }
82
102
  async function runKnowledgeInit(dir) {
83
103
  const root = resolve2(dir);
84
104
  const configPath = join2(root, CATALOG_JSON);
@@ -426,6 +446,7 @@ async function runKnowledgeExportParquet(path, opts) {
426
446
  }
427
447
  export {
428
448
  contentSha256,
449
+ embeddingRuntimeMissingMessage,
429
450
  runKnowledgeBuild,
430
451
  runKnowledgeExportParquet,
431
452
  runKnowledgeInit,
package/dist/tui/index.js CHANGED
@@ -15,7 +15,13 @@ import { createHash, randomUUID } from "crypto";
15
15
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
16
16
  import { homedir } from "os";
17
17
  import { basename, dirname, join, resolve } from "path";
18
- import { pickRandomNameWithGender } from "@bendyline/gezel";
18
+ import {
19
+ getLogLevel,
20
+ getLogOutput,
21
+ pickRandomNameWithGender,
22
+ setLogLevel,
23
+ setLogOutput
24
+ } from "@bendyline/gezel";
19
25
  import {
20
26
  GezelSdkError,
21
27
  authorizeLocal,
@@ -28,6 +34,7 @@ import {
28
34
  createTrustingFetch,
29
35
  discoverOrSpawn,
30
36
  electronNativeBinCandidates,
37
+ ensureProjectForFolder as ensureClientProjectForFolder,
31
38
  isProcessAlive,
32
39
  readRuntime,
33
40
  readSystemServiceEndpoint,
@@ -2649,6 +2656,7 @@ var PROVIDER_ORDER = [
2649
2656
  "mlx",
2650
2657
  "llama-cpp",
2651
2658
  "ds4",
2659
+ "apple-foundation-models",
2652
2660
  "ollama",
2653
2661
  "copilot",
2654
2662
  "openai",
@@ -2672,6 +2680,10 @@ function modelProviderLabel(provider) {
2672
2680
  return "Ollama";
2673
2681
  case "llama-cpp":
2674
2682
  return "llama.cpp";
2683
+ case "apple-foundation-models":
2684
+ return "Apple Intelligence";
2685
+ case "android-mlkit":
2686
+ return "Android system AI";
2675
2687
  case "mlx":
2676
2688
  return "MLX";
2677
2689
  case "ds4":
@@ -2687,6 +2699,7 @@ function configuredModelProviders(config, opts) {
2687
2699
  const ds4PlatformAvailable = Boolean(config.ds4BaseUrl) || opts.platform === "linux" || opts.platform === "darwin" && opts.arch === "arm64";
2688
2700
  const ds4MemoryAvailable = Boolean(config.ds4BaseUrl) || opts.totalRamBytes === null || opts.totalRamBytes >= 45 * 1024 ** 3;
2689
2701
  if (ds4PlatformAvailable && ds4MemoryAvailable) providers.push("ds4");
2702
+ if (config.appleFoundationModelsStatus?.installed) providers.push("apple-foundation-models");
2690
2703
  providers.push("ollama");
2691
2704
  if (opts.copilotAvailable !== false) providers.push("copilot");
2692
2705
  if (config.hasOpenaiApiKey) providers.push("openai");
@@ -4657,6 +4670,21 @@ function formatTaskDetails(task, gezels, boring) {
4657
4670
  import { formatModelAttribution as formatModelAttribution3 } from "@bendyline/gezel";
4658
4671
  import { Box as Box7, Text as Text7, useApp as useApp2, useInput as useInput5 } from "ink";
4659
4672
  import { useCallback as useCallback3, useEffect as useEffect5, useState as useState6 } from "react";
4673
+
4674
+ // src/run-readiness.ts
4675
+ async function settledFirstRunConfig(client, options = {}) {
4676
+ const attempts = options.attempts ?? 12;
4677
+ const delayMs = options.delayMs ?? 250;
4678
+ let config = await client.getConfig();
4679
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
4680
+ if (config.firstRunCompleted || config.provider !== "copilot") return config;
4681
+ await new Promise((resolve2) => setTimeout(resolve2, delayMs));
4682
+ config = await client.getConfig();
4683
+ }
4684
+ return config;
4685
+ }
4686
+
4687
+ // src/tui/components/BootstrapGate.tsx
4660
4688
  import { Fragment as Fragment4, jsx as jsx6, jsxs as jsxs7 } from "react/jsx-runtime";
4661
4689
  var MAX_ALTERNATIVE_MODELS = 6;
4662
4690
  function BootstrapGate(props) {
@@ -5129,15 +5157,6 @@ function ProgressBar({ pct }) {
5129
5157
  "]"
5130
5158
  ] });
5131
5159
  }
5132
- async function settledFirstRunConfig(client) {
5133
- let config = await client.getConfig();
5134
- for (let attempt = 0; attempt < 12; attempt += 1) {
5135
- if (config.firstRunCompleted || config.provider !== "copilot") return config;
5136
- await delay(250);
5137
- config = await client.getConfig();
5138
- }
5139
- return config;
5140
- }
5141
5160
  async function installNativeToolkit(client, status, missing, setScreen) {
5142
5161
  for (let index = 0; index < missing.length; index += 1) {
5143
5162
  const engine = missing[index];
@@ -5286,9 +5305,6 @@ function fitLabel(fit) {
5286
5305
  function errorMessage(error) {
5287
5306
  return error instanceof Error ? error.message : String(error);
5288
5307
  }
5289
- function delay(ms) {
5290
- return new Promise((resolve2) => setTimeout(resolve2, ms));
5291
- }
5292
5308
 
5293
5309
  // src/tui/memory-diagnostics.ts
5294
5310
  import { appendFile, mkdir as mkdir2 } from "fs/promises";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-cli",
3
- "version": "1.1.2",
3
+ "version": "1.2.1",
4
4
  "description": "The `gezel` command-line tool.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -44,15 +44,15 @@
44
44
  "!dist/**/*.map"
45
45
  ],
46
46
  "dependencies": {
47
- "@bendyline/gezel": "1.1.2",
48
- "@bendyline/gezel-app-sdk": "1.0.10",
49
- "@bendyline/gezel-catalog": "1.1.2",
50
- "@bendyline/gezel-client": "1.1.2",
51
- "@bendyline/gezel-knowledge": "1.1.2",
52
- "@bendyline/gezel-service": "1.1.2",
53
- "@bendyline/squisq": "2.11.5",
54
- "@bendyline/squisq-formats": "2.6.5",
55
- "@bendyline/squisq-react": "2.11.5",
47
+ "@bendyline/gezel": "1.2.1",
48
+ "@bendyline/gezel-app-sdk": "1.1.1",
49
+ "@bendyline/gezel-catalog": "1.2.1",
50
+ "@bendyline/gezel-client": "1.2.1",
51
+ "@bendyline/gezel-knowledge": "1.2.1",
52
+ "@bendyline/gezel-service": "1.2.1",
53
+ "@bendyline/squisq": "2.11.11",
54
+ "@bendyline/squisq-formats": "2.6.11",
55
+ "@bendyline/squisq-react": "2.11.13",
56
56
  "commander": "^15.0.0",
57
57
  "ink": "^7.1.1",
58
58
  "ink-text-input": "^6.0.0",