@bendyline/gezel-cli 1.2.4 → 1.2.6

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.
@@ -4,6 +4,7 @@
4
4
  import { basename as basename4, isAbsolute as isAbsolutePath, join as joinPath } from "path";
5
5
  import {
6
6
  GEZEL_VERSION,
7
+ evaluateApiCompat as evaluateApiCompat2,
7
8
  getLogLevel as getLogLevel2,
8
9
  getLogOutput as getLogOutput2,
9
10
  setLogLevel as setLogLevel2,
@@ -20,7 +21,7 @@ import {
20
21
  stopOwnedDaemon as stopOwnedDaemon2,
21
22
  stopProcessByPid
22
23
  } from "@bendyline/gezel-client/node";
23
- import { resolveOnDeviceProvider as resolveOnDeviceProvider2 } from "@bendyline/gezel/native";
24
+ import { resolveOnDeviceProvider as resolveOnDeviceProvider3 } from "@bendyline/gezel/native";
24
25
  import { Command, Option } from "commander";
25
26
 
26
27
  // src/cli-errors.ts
@@ -60,9 +61,11 @@ import { chmod, mkdir, readFile, realpath, rm, writeFile } from "fs/promises";
60
61
  import { homedir } from "os";
61
62
  import { basename, dirname, join, resolve } from "path";
62
63
  import {
64
+ evaluateApiCompat,
63
65
  getLogLevel,
64
66
  getLogOutput,
65
- pickRandomNameWithGender,
67
+ gezelNamesInUse,
68
+ pickUnusedGezelName,
66
69
  projectLeadGezelId,
67
70
  setLogLevel,
68
71
  setLogOutput
@@ -88,7 +91,7 @@ import {
88
91
  stopOwnedDaemon,
89
92
  systemSharedAssetsDir
90
93
  } from "@bendyline/gezel-client/node";
91
- import { gezelPaths } from "@bendyline/gezel/paths";
94
+ import { gezelHome, gezelPaths, nativePayloadVerificationPath } from "@bendyline/gezel/paths";
92
95
 
93
96
  // src/signal-cleanup.ts
94
97
  function installSignalCleanup(cleanup, options = {}) {
@@ -122,11 +125,19 @@ var CliError = class extends Error {
122
125
  };
123
126
  function applyHome(globals) {
124
127
  if (globals.home) process.env.GEZEL_HOME = resolve(globals.home);
125
- if (!process.env.GEZEL_SHARED_ASSETS_DIR) {
128
+ if (globals.home && process.env.GEZEL_DISABLE_MACHINE_SHARED === void 0 && !isAccountHome(resolve(globals.home))) {
129
+ process.env.GEZEL_DISABLE_MACHINE_SHARED = "1";
130
+ }
131
+ if (!process.env.GEZEL_SHARED_ASSETS_DIR && process.env.GEZEL_DISABLE_MACHINE_SHARED !== "1") {
126
132
  const sharedAssets = systemSharedAssetsDir();
127
133
  if (sharedAssets) process.env.GEZEL_SHARED_ASSETS_DIR = sharedAssets;
128
134
  }
129
135
  }
136
+ function isAccountHome(home) {
137
+ const normalize = (path) => process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
138
+ const wanted = normalize(home);
139
+ return [".gezel", ".gezel-dev"].some((name) => normalize(join(homedir(), name)) === wanted);
140
+ }
130
141
  function validateGlobals(globals) {
131
142
  if (globals.connect && globals.standalone) {
132
143
  throw new CliError("--connect and --standalone cannot be used together.");
@@ -177,6 +188,8 @@ async function connectOwned(globals, options = {}) {
177
188
  preferCanonicalPort: await shouldPreferCanonicalPort(),
178
189
  ...process.env.GEZEL_HOME ? { home: process.env.GEZEL_HOME } : {}
179
190
  }
191
+ }).catch((error) => {
192
+ throw isIncompatibleDaemonError(error) ? incompatibleDaemonCliError(error) : error;
180
193
  });
181
194
  if (authorized.daemon.mode === "spawned" && options.announceSpawn !== false) {
182
195
  process.stderr.write(spawnedDaemonNotice(authorized.daemon.pid));
@@ -207,7 +220,19 @@ async function connectForTui(globals) {
207
220
  });
208
221
  result.child?.stdout?.resume();
209
222
  result.child?.stderr?.resume();
210
- if (result.outcome !== "spawned") return { client: result.client };
223
+ if (result.outcome !== "spawned") {
224
+ const health = await result.client.health();
225
+ const verdict = evaluateApiCompat(health, { client: CLI_CLIENT_LABEL });
226
+ if (!verdict.compatible) {
227
+ throw incompatibleDaemonCliError({
228
+ code: verdict.code,
229
+ reason: verdict.reason,
230
+ version: health.version,
231
+ systemService: false
232
+ });
233
+ }
234
+ return { client: result.client };
235
+ }
211
236
  let stopPromise;
212
237
  return {
213
238
  client: result.client,
@@ -316,7 +341,7 @@ async function connectForRun(globals) {
316
341
  }
317
342
  function spawnedDaemonNotice(pid) {
318
343
  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\`.
344
+ return `Started the Gezel background service${which}; it keeps running after this command. Stop it with \`gezel stop\`.
320
345
  `;
321
346
  }
322
347
  async function withTransientConnection(globals, fn) {
@@ -375,7 +400,9 @@ async function findHealthySystemService(globals, deps = {}) {
375
400
  baseUrl: endpoint.baseUrl,
376
401
  fetch: fetchImpl,
377
402
  port: endpoint.port,
378
- home: endpoint.home
403
+ home: endpoint.home,
404
+ version: health.version,
405
+ compat: evaluateApiCompat(health, { client: CLI_CLIENT_LABEL })
379
406
  };
380
407
  } catch {
381
408
  return null;
@@ -430,6 +457,14 @@ async function connectPreferredService(globals) {
430
457
  }
431
458
  const system = await findHealthySystemService(globals);
432
459
  if (!system) return null;
460
+ if (!system.compat.compatible) {
461
+ throw incompatibleDaemonCliError({
462
+ code: system.compat.code,
463
+ reason: system.compat.reason,
464
+ version: system.version,
465
+ systemService: true
466
+ });
467
+ }
433
468
  return connectWithCliGrant({
434
469
  baseUrl: system.baseUrl,
435
470
  fetch: system.fetch,
@@ -441,7 +476,10 @@ async function prepareStandaloneAssets() {
441
476
  const candidates = electronNativeBinCandidates();
442
477
  if (candidates.length === 0) return;
443
478
  const { reuseVerifiedElectronNativeBinaries } = await import("@bendyline/gezel-service");
444
- await reuseVerifiedElectronNativeBinaries({ candidates });
479
+ await reuseVerifiedElectronNativeBinaries({
480
+ candidates,
481
+ cacheFile: nativePayloadVerificationPath(gezelHome())
482
+ });
445
483
  }
446
484
  async function connectWithCliGrant(input) {
447
485
  if (input.token) {
@@ -515,11 +553,34 @@ function cliGrantError(error, target) {
515
553
  "No local Gezel daemon is running. Start the Gezel app or run `gezel start`, then try again."
516
554
  );
517
555
  }
556
+ if (isIncompatibleDaemonError(error)) return incompatibleDaemonCliError(error);
518
557
  }
519
558
  return new CliError(
520
559
  `Could not authorize Gezel CLI against ${target}: ${error instanceof Error ? error.message : String(error)}`
521
560
  );
522
561
  }
562
+ var CLI_CLIENT_LABEL = "this gezel CLI";
563
+ function isIncompatibleDaemonError(error) {
564
+ return error instanceof GezelSdkError && error.code === "daemon_incompatible";
565
+ }
566
+ function incompatibleDaemonCliError(source) {
567
+ const verdict = source instanceof GezelSdkError ? { ...source.cause, systemService: false } : source;
568
+ const service = `the Gezel service${verdict.version ? ` (${verdict.version})` : ""}`;
569
+ if (verdict.code === "client-too-old") {
570
+ return new CliError(
571
+ `This gezel CLI is older than ${service} supports. Update it with \`npm install -g @bendyline/gezel-cli\`, then try again.`
572
+ );
573
+ }
574
+ if (verdict.code === "machine-engine-role") {
575
+ return new CliError(`Cannot use ${service}: ${verdict.reason}.`);
576
+ }
577
+ return new CliError(
578
+ verdict.systemService ? `${capitalize(service)} installed for this computer is older than this gezel CLI can use. Update the Gezel app, which replaces it, then try again.` : `${capitalize(service)} running for this user is older than this gezel CLI can use. Open the Gezel app, which replaces an outdated service when it starts, or stop it with \`gezel stop\` and run this command again.`
579
+ );
580
+ }
581
+ function capitalize(text) {
582
+ return `${text[0]?.toUpperCase() ?? ""}${text.slice(1)}`;
583
+ }
523
584
  async function resolveCliAppId() {
524
585
  const dir = join(gezelPaths().root, "cli");
525
586
  const file = join(dir, "client-id");
@@ -658,7 +719,7 @@ async function ensureCliProjectLead(client, projectId) {
658
719
  (gezel) => gezel.templateId === "builder" || gezel.role?.trim().toLowerCase() === "builder"
659
720
  );
660
721
  if (!builder) {
661
- const { name, gender } = pickRandomNameWithGender();
722
+ const { name, gender } = pickUnusedGezelName(gezelNamesInUse(gezels2));
662
723
  builder = await client.createGezelFromTemplate("builder", { name, gender });
663
724
  }
664
725
  const updated2 = await client.updateProject(projectId, { voormanGezelId: builder.id });
@@ -673,7 +734,7 @@ async function ensureCliProjectLead(client, projectId) {
673
734
  (gezel) => gezel.templateId === "voorman" || gezel.role?.trim().toLowerCase() === "voorman"
674
735
  );
675
736
  if (!voorman) {
676
- const { name, gender } = pickRandomNameWithGender();
737
+ const { name, gender } = pickUnusedGezelName(gezelNamesInUse(gezels));
677
738
  voorman = await client.createGezelFromTemplate("voorman", { name, gender });
678
739
  }
679
740
  const updated = await client.updateProject(projectId, { voormanGezelId: voorman.id });
@@ -825,12 +886,12 @@ function parseCraftbookArguments(book, tokens, named = []) {
825
886
  const request = requestWords.join(" ").trim();
826
887
  return request ? { params, request } : { params };
827
888
  }
828
- function craftbookDoLaunch(craftbook, { params, request }) {
889
+ function craftbookDoLaunch(craftbook2, { params, request }) {
829
890
  if (!request) return { craftbookParams: params };
830
891
  const launch = composeCraftbookLaunch({
831
892
  message: request,
832
- craftbookName: craftbook.name,
833
- paramSchema: craftbook.paramSchema,
893
+ craftbookName: craftbook2.name,
894
+ paramSchema: craftbook2.paramSchema,
834
895
  params
835
896
  });
836
897
  return { description: launch.description, craftbookParams: launch.params };
@@ -925,6 +986,33 @@ async function waitForTask(client, ref, options) {
925
986
  timeout.dispose();
926
987
  }
927
988
  }
989
+ function summarizeTaskNote(text, maxLength = 240) {
990
+ const lines = text.split(/\r?\n/).map((line) => line.trim());
991
+ const headingIndex = lines.findIndex((line) => line.startsWith("#"));
992
+ const heading = headingIndex >= 0 ? lines[headingIndex].replace(/^#+\s*/, "") : "";
993
+ const body = lines.slice(headingIndex + 1).find((line) => line.length > 0 && !line.startsWith("#"));
994
+ const sentence = body?.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? body ?? "";
995
+ const summary = heading && sentence ? `${heading}: ${sentence}` : heading || sentence;
996
+ return summary.length > maxLength ? `${summary.slice(0, maxLength - 1).trimEnd()}\u2026` : summary;
997
+ }
998
+ async function blockedTaskReason(client, result) {
999
+ if (result.outcome !== "blocked") return void 0;
1000
+ if (result.questionIds?.length) {
1001
+ return "A gezel is waiting for your answer to a question. Answer it in the Gezel app or the interactive `gezel` terminal.";
1002
+ }
1003
+ if (result.task.status === "draft") return "The task is still a draft and has not started.";
1004
+ const { notes } = await client.listTaskNotes(result.task.projectId, result.task.num).catch(() => ({ notes: [] }));
1005
+ const latest = [...notes].sort((a, b) => a.at.localeCompare(b.at)).at(-1);
1006
+ return latest ? summarizeTaskNote(latest.text) || void 0 : void 0;
1007
+ }
1008
+ function filterCraftbooks(books, words) {
1009
+ const needles = words.map((word) => word.trim().toLowerCase()).filter(Boolean);
1010
+ if (needles.length === 0) return [...books];
1011
+ return books.filter((book) => {
1012
+ const haystack = [book.command, book.name, book.category, ...book.tags].join(" ").toLowerCase();
1013
+ return needles.every((needle) => haystack.includes(needle));
1014
+ });
1015
+ }
928
1016
 
929
1017
  // src/craftbook-setup.ts
930
1018
  import { Writable } from "stream";
@@ -967,6 +1055,34 @@ async function pullChatModel(client, engine, id, writeProgress) {
967
1055
  else await client.installLlamaCppModel(id, onEvent);
968
1056
  if (pullError) throw new CliError(`download failed: ${pullError}`);
969
1057
  }
1058
+ async function waitForMlxRuntime(client, writeProgress, options = {}) {
1059
+ const pollMs = options.pollMs ?? 1e3;
1060
+ const now = options.now ?? Date.now;
1061
+ const started = now();
1062
+ let shown = false;
1063
+ for (; ; ) {
1064
+ const status = await client.getMlxRuntimeStatus();
1065
+ if (status.phase === "provisioning") {
1066
+ const elapsed = Math.round((now() - started) / 1e3);
1067
+ writeProgress(
1068
+ `\rpreparing the MLX Python runtime (one-time, a few minutes): ${Math.floor(elapsed / 60)}m ${String(elapsed % 60).padStart(2, "0")}s`
1069
+ );
1070
+ shown = true;
1071
+ await new Promise((resolve6) => setTimeout(resolve6, pollMs));
1072
+ continue;
1073
+ }
1074
+ if (status.phase === "error") {
1075
+ writeProgress(
1076
+ `${shown ? "\n" : ""}MLX runtime setup failed; the first chat will retry it: ${status.error ?? "unknown error"}
1077
+ `
1078
+ );
1079
+ return "error";
1080
+ }
1081
+ if (shown) writeProgress(`\rMLX runtime ready${" ".repeat(56)}
1082
+ `);
1083
+ return status.phase === "ready" ? "ready" : "idle";
1084
+ }
1085
+ }
970
1086
  function formatGb(bytes) {
971
1087
  return (bytes / 1e9).toFixed(2);
972
1088
  }
@@ -982,15 +1098,113 @@ import {
982
1098
  formatModelAttribution,
983
1099
  isMoEFromTags,
984
1100
  isRecommendedModel,
985
- mediaModelFits,
1101
+ lowBitScoreFactor,
986
1102
  pickRecommendedModel
987
1103
  } from "@bendyline/gezel";
1104
+ var CHAT_MEMORY_OVERHEAD = {
1105
+ "llama-cpp": 1.2,
1106
+ mlx: 1.3
1107
+ };
988
1108
  var NATIVE_TOOLKIT = [
989
1109
  "uv",
990
1110
  "sd-server",
991
1111
  "whisper-server",
992
1112
  "llama-server"
993
1113
  ];
1114
+ function recoDevice(memory) {
1115
+ return {
1116
+ platform: memory.platform,
1117
+ gpuVramBytes: memory.gpuVramBytes,
1118
+ ...memory.gpuMemoryKind ? { gpuMemoryKind: memory.gpuMemoryKind } : {},
1119
+ totalRamBytes: memory.totalRamBytes,
1120
+ usableBytes: memory.usableBytes,
1121
+ ...memory.budgetBytes !== void 0 ? { budgetBytes: memory.budgetBytes } : {}
1122
+ };
1123
+ }
1124
+ function chatModelCandidates(items, device, provider) {
1125
+ const candidates = [];
1126
+ for (const item of items) {
1127
+ if (item.manifest.kind !== "chat-model") continue;
1128
+ const manifest = item.manifest;
1129
+ if (manifest.licenseClass !== "open") continue;
1130
+ const source = provider === "mlx" ? manifest.mlx : manifest.llamaCpp;
1131
+ if (!source || provider === "mlx" && manifest.mlx?.disabledReason) continue;
1132
+ const residentBytes = source.residentBytes ?? Math.round(source.approxSizeBytes * CHAT_MEMORY_OVERHEAD[provider]);
1133
+ const fit = computeModelFit({
1134
+ residentBytes,
1135
+ isMoE: isMoEFromTags(manifest.tags),
1136
+ usableBytes: device.usableBytes,
1137
+ totalRamBytes: device.totalRamBytes,
1138
+ gpuVramBytes: device.gpuVramBytes,
1139
+ ...device.budgetBytes !== void 0 ? { admissibleBytes: device.budgetBytes } : {}
1140
+ }).tier;
1141
+ candidates.push({
1142
+ id: manifest.id,
1143
+ name: manifest.name,
1144
+ provider,
1145
+ approxSizeBytes: source.approxSizeBytes,
1146
+ residentBytes,
1147
+ // Effective score: a model the shared gate rejects (restricted license,
1148
+ // no tool support) sorts as unscored rather than leading the list.
1149
+ recoScore: isRecommendedModel(manifest) ? manifest.recoScore ?? 0 : 0,
1150
+ ...source.quantization ? { quantization: source.quantization } : {},
1151
+ fit,
1152
+ attribution: formatModelAttribution(manifest)
1153
+ });
1154
+ }
1155
+ return candidates;
1156
+ }
1157
+ function rankChatModels(items, device, provider) {
1158
+ const candidates = chatModelCandidates(items, device, provider);
1159
+ if (candidates.length === 0) return [];
1160
+ const picked = pickRecommendedModel(
1161
+ candidates.map((model2) => ({
1162
+ id: model2.id,
1163
+ ...model2.recoScore > 0 ? { recoScore: model2.recoScore } : {},
1164
+ licenseClass: "open",
1165
+ tags: items.find((item) => item.manifest.kind === "chat-model" && item.manifest.id === model2.id)?.manifest?.tags ?? [],
1166
+ residentBytes: model2.residentBytes,
1167
+ ...model2.quantization ? { quantization: model2.quantization } : {}
1168
+ })),
1169
+ device
1170
+ );
1171
+ const comfortable = candidates.filter(
1172
+ (model2) => model2.fit === "fits" || model2.fit === "fits-offload"
1173
+ );
1174
+ const pool = comfortable.length > 0 ? comfortable : candidates;
1175
+ const ranked = (model2) => model2.recoScore * lowBitScoreFactor(model2.quantization);
1176
+ pool.sort(
1177
+ (a, b) => ranked(b) - ranked(a) || fitOrder(a.fit) - fitOrder(b.fit) || b.residentBytes - a.residentBytes || a.name.localeCompare(b.name)
1178
+ );
1179
+ if (!picked) return pool;
1180
+ const bestIndex = pool.findIndex((model2) => model2.id === picked.id);
1181
+ if (bestIndex < 0) {
1182
+ const best = candidates.find((model2) => model2.id === picked.id);
1183
+ if (best) pool.unshift(best);
1184
+ return pool;
1185
+ }
1186
+ if (bestIndex > 0) {
1187
+ const [best] = pool.splice(bestIndex, 1);
1188
+ if (best) pool.unshift(best);
1189
+ }
1190
+ return pool;
1191
+ }
1192
+ function formatDownloadSize(bytes) {
1193
+ if (bytes >= 1e9) return `${(bytes / 1e9).toFixed(1)} GB`;
1194
+ return `${Math.max(1, Math.round(bytes / 1e6))} MB`;
1195
+ }
1196
+ function fitOrder(fit) {
1197
+ switch (fit) {
1198
+ case "fits":
1199
+ return 0;
1200
+ case "fits-offload":
1201
+ return 1;
1202
+ case "tight":
1203
+ return 2;
1204
+ case "too-big":
1205
+ return 3;
1206
+ }
1207
+ }
994
1208
 
995
1209
  // src/native-command.ts
996
1210
  var NATIVE_VARIANTS = ["cuda", "vulkan", "metal", "cpu"];
@@ -1242,8 +1456,12 @@ ${lines.join("\n")}
1242
1456
  `Web search needs a Brave Search API key. Get one at ${BRAVE_KEY_URL} \u2014 Gezel keeps it in this computer's secret store.
1243
1457
  `
1244
1458
  );
1245
- const key = (await prompter.secret("Paste the key (hidden), or press Enter to stop: ")).trim();
1459
+ const key = (await prompter.secret(
1460
+ "Paste the key, then press Enter (Enter on its own stops here): ",
1461
+ (length) => `Key received (${length} characters, hidden). Press Enter to continue with this key. `
1462
+ )).trim();
1246
1463
  if (!key) stop(gap);
1464
+ options.write("Checking the key with one Brave search\u2026\n");
1247
1465
  await saveBraveKey(client, config, key, options.projectId);
1248
1466
  options.write("Web search: Brave (test search passed)\n");
1249
1467
  } else {
@@ -1294,44 +1512,79 @@ ${lines.join("\n")}
1294
1512
  }
1295
1513
  options.write("\n");
1296
1514
  }
1297
- function terminalPrompter() {
1298
- if (!process.stdin.isTTY || !process.stderr.isTTY) return null;
1515
+ function terminalPrompter(terminal = { input: process.stdin, output: process.stderr }) {
1516
+ if (!terminal.input.isTTY || !terminal.output.isTTY) return null;
1299
1517
  return {
1300
- confirm: async (question) => /^(y|yes)$/i.test((await ask(question, false)).trim()),
1301
- secret: (question) => ask(question, true)
1518
+ confirm: async (question) => {
1519
+ for (; ; ) {
1520
+ const answer = (await ask(terminal, question)).trim().toLowerCase();
1521
+ if (answer === "y" || answer === "yes") return true;
1522
+ if (answer === "" || answer === "n" || answer === "no") return false;
1523
+ terminal.output.write("Please answer y or n.\n");
1524
+ }
1525
+ },
1526
+ secret: (question, filled) => ask(terminal, question, { filled })
1302
1527
  };
1303
1528
  }
1304
- function ask(question, hidden) {
1305
- let muted = false;
1306
- const output = new Writable({
1307
- write(chunk, encoding, callback) {
1308
- if (!muted) process.stderr.write(chunk, encoding);
1309
- callback();
1310
- }
1311
- });
1529
+ function ask(terminal, question, secret) {
1530
+ const { input, output } = terminal;
1312
1531
  return import("readline").then(
1313
- ({ createInterface }) => new Promise((resolve6, reject) => {
1314
- const rl = createInterface({ input: process.stdin, output, terminal: true });
1532
+ ({ clearScreenDown, createInterface, cursorTo, moveCursor }) => new Promise((resolve6, reject) => {
1533
+ const rl = createInterface({
1534
+ input,
1535
+ output: secret ? new Writable({ write: (_chunk, _encoding, done) => done() }) : output,
1536
+ terminal: true,
1537
+ ...secret ? { historySize: 0 } : {}
1538
+ });
1315
1539
  let settled = false;
1316
- rl.on("SIGINT", () => {
1540
+ const settle = () => {
1317
1541
  settled = true;
1542
+ input.removeListener("keypress", onKeypress);
1543
+ };
1544
+ let drawn = "";
1545
+ let shownLength = -1;
1546
+ let pending = false;
1547
+ const draw = () => {
1548
+ pending = false;
1549
+ if (settled || !secret) return;
1550
+ const length = rl.line.length;
1551
+ if (length === shownLength) return;
1552
+ shownLength = length;
1553
+ const text = length > 0 && secret.filled ? secret.filled(length) : question;
1554
+ if (drawn) {
1555
+ const rows = Math.floor((drawn.length - 1) / (output.columns || 80));
1556
+ if (rows > 0) moveCursor(output, 0, -rows);
1557
+ cursorTo(output, 0);
1558
+ clearScreenDown(output);
1559
+ }
1560
+ output.write(text);
1561
+ drawn = text;
1562
+ };
1563
+ function onKeypress() {
1564
+ if (pending) return;
1565
+ pending = true;
1566
+ queueMicrotask(draw);
1567
+ }
1568
+ if (secret) input.on("keypress", onKeypress);
1569
+ rl.on("SIGINT", () => {
1570
+ settle();
1318
1571
  rl.close();
1319
- process.stderr.write("\n");
1572
+ output.write("\n");
1320
1573
  reject(new CliError("Cancelled."));
1321
1574
  });
1322
1575
  rl.on("close", () => {
1323
1576
  if (settled) return;
1324
- settled = true;
1325
- process.stderr.write("\n");
1577
+ settle();
1578
+ output.write("\n");
1326
1579
  resolve6("");
1327
1580
  });
1328
1581
  rl.question(question, (answer) => {
1329
- settled = true;
1582
+ settle();
1330
1583
  rl.close();
1331
- if (hidden) process.stderr.write("\n");
1584
+ if (secret) output.write("\n");
1332
1585
  resolve6(answer);
1333
1586
  });
1334
- muted = hidden;
1587
+ draw();
1335
1588
  })
1336
1589
  );
1337
1590
  }
@@ -1635,6 +1888,99 @@ function assertCatalogOnlyOptions(opts, kind) {
1635
1888
  }
1636
1889
  }
1637
1890
 
1891
+ // src/model-choice.ts
1892
+ async function installedChatModels(client, engine) {
1893
+ const { models } = engine === "mlx" ? await client.listMlxModels() : engine === "ds4" ? await client.listDs4Models() : await client.listLlamaCppModels();
1894
+ return models.map((model2) => model2.id);
1895
+ }
1896
+ function providerFlag(engine, platformDefault) {
1897
+ return engine === platformDefault ? "" : ` --provider ${engine}`;
1898
+ }
1899
+ var FIT_LABEL = {
1900
+ fits: "fits",
1901
+ "fits-offload": "fits, partly offloaded",
1902
+ tight: "tight",
1903
+ "too-big": "too big"
1904
+ };
1905
+ async function availableChatModels(client, engine) {
1906
+ if (engine === "ds4") {
1907
+ throw new CliError("`--available` lists mlx and llama-cpp models; pass one with --provider.");
1908
+ }
1909
+ const [memory, catalog, installed, config] = await Promise.all([
1910
+ client.getMemoryProfile(),
1911
+ client.listCatalogItems("chat-model"),
1912
+ installedChatModels(client, engine),
1913
+ client.getConfig()
1914
+ ]);
1915
+ const pinned = config.defaultModel?.[engine];
1916
+ return {
1917
+ ranked: rankChatModels(catalog.items, recoDevice(memory), engine),
1918
+ installed: new Set(installed),
1919
+ ...pinned ? { pinned } : {}
1920
+ };
1921
+ }
1922
+ function formatAvailableChatModels(input) {
1923
+ const { engine, ranked, installed, pinned } = input;
1924
+ if (ranked.length === 0) return `(no ${engine} chat models in the catalog for this machine)`;
1925
+ const width = Math.max(...ranked.map((model2) => model2.id.length));
1926
+ const lines = [`${engine} chat models for this machine, best first:`];
1927
+ ranked.forEach((model2, index) => {
1928
+ const notes = [
1929
+ index === 0 ? "recommended" : "",
1930
+ installed.has(model2.id) ? "installed" : "",
1931
+ model2.id === pinned ? "in use" : ""
1932
+ ].filter(Boolean);
1933
+ lines.push(
1934
+ ` ${model2.id.padEnd(width)} ${formatDownloadSize(model2.approxSizeBytes).padStart(7)} ${FIT_LABEL[model2.fit].padEnd(22)} ${model2.name}${notes.length > 0 ? ` (${notes.join(", ")})` : ""}`
1935
+ );
1936
+ });
1937
+ const flag = providerFlag(engine, input.platformDefault);
1938
+ const smallest = [...ranked].sort((a, b) => a.approxSizeBytes - b.approxSizeBytes)[0];
1939
+ lines.push(
1940
+ "",
1941
+ `Download one with \`gezel model pull <id>${flag}\`. The smallest is ${smallest.id} (${formatDownloadSize(smallest.approxSizeBytes)}).`,
1942
+ `\`gezel model use <id>${flag}\` picks the installed model chats use.`
1943
+ );
1944
+ return lines.join("\n");
1945
+ }
1946
+ async function useChatModel(client, id, options) {
1947
+ const order = options.requested ? [options.requested] : [options.platformDefault, ...["mlx", "llama-cpp", "ds4"]].filter(
1948
+ (engine2, index, all) => all.indexOf(engine2) === index
1949
+ );
1950
+ let engine;
1951
+ for (const candidate of order) {
1952
+ const installed = await installedChatModels(client, candidate).catch(() => []);
1953
+ if (installed.includes(id)) {
1954
+ engine = candidate;
1955
+ break;
1956
+ }
1957
+ }
1958
+ if (!engine) {
1959
+ const target = options.requested ?? options.platformDefault;
1960
+ throw new CliError(
1961
+ `${id} isn't downloaded for ${target}. Download it with \`gezel model pull ${id}${providerFlag(target, options.platformDefault)}\`, or see \`gezel model list --available\`.`
1962
+ );
1963
+ }
1964
+ const config = await client.getConfig();
1965
+ await client.updateConfig({
1966
+ provider: engine,
1967
+ defaultModel: { ...config.defaultModel ?? {}, [engine]: id },
1968
+ firstRunCompleted: true
1969
+ });
1970
+ return engine;
1971
+ }
1972
+ async function pinPulledModel(client, engine, id) {
1973
+ const config = await client.getConfig();
1974
+ const current = config.defaultModel?.[engine];
1975
+ if (current === id) return "already";
1976
+ if (current && (await installedChatModels(client, engine)).includes(current)) return "kept";
1977
+ await client.updateConfig({
1978
+ defaultModel: { ...config.defaultModel ?? {}, [engine]: id },
1979
+ firstRunCompleted: true
1980
+ });
1981
+ return "pinned";
1982
+ }
1983
+
1638
1984
  // src/model-export.ts
1639
1985
  import { randomUUID as randomUUID2 } from "crypto";
1640
1986
  import { rename, rm as rm2, stat } from "fs/promises";
@@ -1749,6 +2095,143 @@ function progressText(bytesCompleted, bytesTotal) {
1749
2095
  return `${String(pct).padStart(3)}% ${formatGb(bytesCompleted)}/${formatGb(bytesTotal)} GB`;
1750
2096
  }
1751
2097
 
2098
+ // src/progress-output.ts
2099
+ function progressWriter(stream, options = {}) {
2100
+ if (stream.isTTY) {
2101
+ return (text) => {
2102
+ stream.write(text);
2103
+ };
2104
+ }
2105
+ const intervalMs = options.intervalMs ?? 15e3;
2106
+ const now = options.now ?? Date.now;
2107
+ let lastLine = "";
2108
+ let lastAt = Number.NEGATIVE_INFINITY;
2109
+ return (text) => {
2110
+ const finished = text.endsWith("\n");
2111
+ const line = text.replace(/\r/g, "").trim();
2112
+ if (!line || line === lastLine) return;
2113
+ if (!finished && now() - lastAt < intervalMs) return;
2114
+ stream.write(`${line}
2115
+ `);
2116
+ lastLine = line;
2117
+ lastAt = now();
2118
+ };
2119
+ }
2120
+ function stderrProgress() {
2121
+ return progressWriter(process.stderr);
2122
+ }
2123
+
2124
+ // src/tui/gezel-picker.ts
2125
+ import {
2126
+ getProjectType,
2127
+ resolveProjectTypeId
2128
+ } from "@bendyline/gezel";
2129
+ function roleIdentity(value) {
2130
+ return (value ?? "").trim().toLowerCase();
2131
+ }
2132
+ function resolveGezelArg(arg, inputs) {
2133
+ const query = arg.trim().toLowerCase();
2134
+ if (!query) return { kind: "unknown" };
2135
+ const { gezels, templates } = inputs;
2136
+ const gezelKeys = (g) => [g.id, g.name, g.roleBasedName, g.role].map(roleIdentity).filter(Boolean);
2137
+ const templateKeys = (t) => [t.id, t.role, t.name].map(roleIdentity).filter(Boolean);
2138
+ const exactGezel = gezels.find((g) => gezelKeys(g).includes(query));
2139
+ if (exactGezel) return { kind: "gezel", gezelId: exactGezel.id };
2140
+ const exactTemplate = templates.find((t) => templateKeys(t).includes(query));
2141
+ if (exactTemplate) return { kind: "template", templateId: exactTemplate.id };
2142
+ const prefixGezels = gezels.filter((g) => gezelKeys(g).some((k) => k.startsWith(query)));
2143
+ if (prefixGezels.length === 1) return { kind: "gezel", gezelId: prefixGezels[0].id };
2144
+ if (prefixGezels.length > 1) {
2145
+ return { kind: "ambiguous", labels: prefixGezels.map((g) => g.name) };
2146
+ }
2147
+ const prefixTemplates = templates.filter((t) => templateKeys(t).some((k) => k.startsWith(query)));
2148
+ if (prefixTemplates.length === 1) return { kind: "template", templateId: prefixTemplates[0].id };
2149
+ if (prefixTemplates.length > 1) {
2150
+ return { kind: "ambiguous", labels: prefixTemplates.map((t) => t.name) };
2151
+ }
2152
+ return { kind: "unknown" };
2153
+ }
2154
+
2155
+ // src/run-gezel.ts
2156
+ async function resolveRunGezel(client, ref) {
2157
+ const { gezels } = await client.listGezels();
2158
+ const byId = gezels.find((gezel) => gezel.id === ref.trim());
2159
+ if (byId) return byId.id;
2160
+ const query = ref.trim().toLowerCase();
2161
+ const sameName = gezels.filter((gezel) => gezel.name.trim().toLowerCase() === query);
2162
+ if (sameName.length > 1) throw ambiguous(ref, sameName);
2163
+ const match = resolveGezelArg(ref, { gezels, templates: [] });
2164
+ if (match.kind === "gezel") return match.gezelId;
2165
+ if (match.kind === "ambiguous") {
2166
+ const candidates = gezels.filter((gezel) => match.labels.includes(gezel.name));
2167
+ throw ambiguous(ref, candidates);
2168
+ }
2169
+ throw new CliError(`No gezel matches "${ref}". Run \`gezel agent list\` to see your gezels.`);
2170
+ }
2171
+ function ambiguous(ref, candidates) {
2172
+ const listed = candidates.map((gezel) => `${gezel.name} (${gezel.id})`).join(", ");
2173
+ return new CliError(`"${ref}" matches more than one gezel: ${listed}. Pass the id instead.`);
2174
+ }
2175
+
2176
+ // src/run-progress.ts
2177
+ var ENGINE_NAMES = {
2178
+ mlx: "MLX",
2179
+ "llama-cpp": "llama.cpp",
2180
+ ds4: "DS4"
2181
+ };
2182
+ var WAIT_RANK = { starting: 2, loading_model: 2, prefill: 1 };
2183
+ var DEFAULT_DETAIL = {
2184
+ starting: "starting the engine",
2185
+ loading_model: "loading the model",
2186
+ prefill: "reading the prompt"
2187
+ };
2188
+ function phaseLine(event) {
2189
+ if (WAIT_RANK[event.phase] === void 0) return void 0;
2190
+ const engine = ENGINE_NAMES[event.provider] ?? event.provider;
2191
+ const detail = event.detail ?? DEFAULT_DETAIL[event.phase];
2192
+ return detail.startsWith(engine) ? detail : `${engine}: ${detail}`;
2193
+ }
2194
+ var RunProgress = class {
2195
+ constructor(write, delayMs = 2e3) {
2196
+ this.write = write;
2197
+ this.delayMs = delayMs;
2198
+ }
2199
+ write;
2200
+ delayMs;
2201
+ pending;
2202
+ reported = /* @__PURE__ */ new Set();
2203
+ phase(event) {
2204
+ const line = phaseLine(event);
2205
+ if (!line) {
2206
+ this.settle();
2207
+ return;
2208
+ }
2209
+ if (this.reported.has(event.phase)) return;
2210
+ if (this.pending?.phase === event.phase) {
2211
+ this.pending.line = line;
2212
+ return;
2213
+ }
2214
+ if (this.pending && WAIT_RANK[this.pending.phase] > WAIT_RANK[event.phase]) return;
2215
+ this.settle();
2216
+ const pending = {
2217
+ phase: event.phase,
2218
+ line,
2219
+ timer: setTimeout(() => {
2220
+ this.pending = void 0;
2221
+ this.reported.add(pending.phase);
2222
+ this.write(`${pending.line}
2223
+ `);
2224
+ }, this.delayMs)
2225
+ };
2226
+ this.pending = pending;
2227
+ }
2228
+ /** The reply started or the turn ended: nothing still waiting is worth a line. */
2229
+ settle() {
2230
+ if (this.pending) clearTimeout(this.pending.timer);
2231
+ this.pending = void 0;
2232
+ }
2233
+ };
2234
+
1752
2235
  // src/run-prompt.ts
1753
2236
  async function resolveRunPrompt(parts, input = process.stdin) {
1754
2237
  if (parts?.length !== 1 || parts[0] !== "-") {
@@ -1776,6 +2259,7 @@ async function resolveRunPrompt(parts, input = process.stdin) {
1776
2259
  }
1777
2260
 
1778
2261
  // src/run-readiness.ts
2262
+ import { resolveOnDeviceProvider as resolveOnDeviceProvider2 } from "@bendyline/gezel/native";
1779
2263
  var READY = { ready: true };
1780
2264
  async function settledFirstRunConfig(client, options = {}) {
1781
2265
  const attempts = options.attempts ?? 12;
@@ -1824,12 +2308,22 @@ async function checkRunReadiness(client, gezelId, env2 = process.env) {
1824
2308
  }
1825
2309
  function formatRunSetupMessage(input) {
1826
2310
  const { provider, engineMissing, pinned, installedIds } = input;
2311
+ const flag = providerFlag(
2312
+ provider,
2313
+ input.platformDefault ?? resolveOnDeviceProvider2(process.platform, process.arch)
2314
+ );
1827
2315
  const steps = [];
1828
2316
  if (engineMissing) steps.push("gezel native install");
1829
2317
  if (pinned && !installedIds.includes(pinned)) {
1830
- steps.push(`gezel model pull ${pinned}${provider === "mlx" ? " --provider mlx" : ""}`);
2318
+ if (installedIds.length > 0) {
2319
+ steps.push(`gezel model use ${installedIds[0]}${flag} (already downloaded)`);
2320
+ }
2321
+ steps.push(`gezel model pull ${pinned}${flag}`);
2322
+ if (installedIds.length === 0) {
2323
+ steps.push(`gezel model list --available${flag} (to pick a smaller one)`);
2324
+ }
1831
2325
  } else if (!pinned && installedIds.length === 0) {
1832
- steps.push("gezel model list (then: gezel model pull <id>)");
2326
+ steps.push(`gezel model list --available${flag} (then: gezel model pull <id>${flag})`);
1833
2327
  }
1834
2328
  const lines = [];
1835
2329
  if (pinned && !installedIds.includes(pinned) && installedIds.length > 0) {
@@ -1853,6 +2347,99 @@ function formatRunSetupMessage(input) {
1853
2347
  return lines.join("\n");
1854
2348
  }
1855
2349
 
2350
+ // src/run-reply.ts
2351
+ var NAME = "[A-Za-z_][A-Za-z0-9_.-]*";
2352
+ var CLOSED_CALLS = [
2353
+ /<tool_call>[\s\S]*?<\/tool_call\s*>/gi,
2354
+ /<function_calls>[\s\S]*?<\/function_calls\s*>/gi,
2355
+ new RegExp(`<function=${NAME}\\s*>[\\s\\S]*?<\\/function\\s*>`, "gi"),
2356
+ new RegExp(`<invoke\\s+name="${NAME}"\\s*>[\\s\\S]*?<\\/invoke\\s*>`, "gi"),
2357
+ /<\|tool_call\|?>[\s\S]*?<\/?\|?tool_call\|?>/gi
2358
+ ];
2359
+ var OPEN_CALL = new RegExp(
2360
+ `<tool_call>|<function_calls>|<function=${NAME}\\s*>|<invoke\\s+name=|<\\|tool_call\\|?>`,
2361
+ "i"
2362
+ );
2363
+ function prefixOf(literal) {
2364
+ return [...literal].reduceRight(
2365
+ (rest, ch) => `(?:${ch.replace(/[|\\^$.*+?()[\]{}]/g, "\\$&")}${rest})?`,
2366
+ ""
2367
+ );
2368
+ }
2369
+ var PARTIAL_TAG = new RegExp(
2370
+ `^<(?:/?(?:${["tool_call", "function_calls", "invoke", "|tool_call|"].map(prefixOf).join("|")})|function=(?:${NAME}\\s*)?|invoke\\s+${prefixOf("name")})$`,
2371
+ "i"
2372
+ );
2373
+ var MAX_PARTIAL_TAG = 128;
2374
+ function withoutPartialTag(text) {
2375
+ const at = text.lastIndexOf("<");
2376
+ if (at < 0 || text.length - at > MAX_PARTIAL_TAG) return text;
2377
+ return PARTIAL_TAG.test(text.slice(at)) ? text.slice(0, at) : text;
2378
+ }
2379
+ var CUT = "\uE000";
2380
+ function visibleReply(raw, streaming) {
2381
+ let out = raw;
2382
+ for (const pattern of CLOSED_CALLS) out = out.replace(pattern, CUT);
2383
+ if (streaming) {
2384
+ const open = OPEN_CALL.exec(out);
2385
+ if (open) out = out.slice(0, open.index);
2386
+ out = withoutPartialTag(out);
2387
+ }
2388
+ out = out.replace(/^\s*(?:\uE000\s*)+/, "").replace(/\s*(?:\uE000\s*)+$/, "").replace(/\s*(?:\uE000\s*)+/g, "\n\n").replace(/^\s+/, "");
2389
+ return streaming ? out.replace(/\s+$/, "") : out;
2390
+ }
2391
+ function rejoinPoint(shown, visible) {
2392
+ let at = 0;
2393
+ while (at < shown.length && at < visible.length && shown[at] === visible[at]) at++;
2394
+ const isText = (ch) => ch !== void 0 && /\S/.test(ch);
2395
+ if (isText(visible[at - 1]) && (isText(visible[at]) || isText(shown[at]))) {
2396
+ while (at > 0 && isText(visible[at - 1])) at--;
2397
+ }
2398
+ return at;
2399
+ }
2400
+ var ReplyPrinter = class {
2401
+ constructor(write) {
2402
+ this.write = write;
2403
+ }
2404
+ write;
2405
+ raw = "";
2406
+ printed = "";
2407
+ push(chunk) {
2408
+ this.raw += chunk;
2409
+ this.extend(visibleReply(this.raw, true));
2410
+ }
2411
+ /**
2412
+ * End of the reply. `committed` is the saved message, printed when the
2413
+ * stream carried no visible text (providers that send it whole). Returns
2414
+ * whether anything was printed.
2415
+ */
2416
+ finish(committed) {
2417
+ let visible = visibleReply(this.raw, false);
2418
+ if (!visible && committed) visible = visibleReply(committed, false);
2419
+ if (!this.extend(visible) && !this.printed.startsWith(visible)) this.rejoin(visible);
2420
+ return this.printed.length > 0;
2421
+ }
2422
+ /** Prints what `visible` adds to the screen; false when it does not extend it. */
2423
+ extend(visible) {
2424
+ if (!visible.startsWith(this.printed)) return false;
2425
+ if (visible.length > this.printed.length) {
2426
+ this.write(visible.slice(this.printed.length));
2427
+ this.printed = visible;
2428
+ }
2429
+ return true;
2430
+ }
2431
+ /**
2432
+ * The screen holds text the reply no longer has: a tag printed before it
2433
+ * completed into a call. It cannot be taken back, so the rest of the reply
2434
+ * goes on a line of its own rather than being dropped.
2435
+ */
2436
+ rejoin(visible) {
2437
+ const rest = visible.slice(rejoinPoint(this.printed, visible)).replace(/^\s+/, "");
2438
+ if (rest) this.write(`${this.printed.endsWith("\n") ? "" : "\n"}${rest}`);
2439
+ this.printed = visible;
2440
+ }
2441
+ };
2442
+
1856
2443
  // src/secrets-command.ts
1857
2444
  import { GezelApiError as GezelApiError2 } from "@bendyline/gezel-client";
1858
2445
  var credentialFlags = {
@@ -2379,7 +2966,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
2379
2966
  "Run the daemon attached to this terminal \u2014 stdio streams to this shell, Ctrl+C stops it. Useful for development and CI."
2380
2967
  ).option(
2381
2968
  "--web",
2382
- "Serve the web UI over HTTP on loopback and print a one-time browser URL (reuses a daemon already serving it)."
2969
+ "Serve the web UI over HTTP on loopback and print a browser URL whose sign-in token lasts until the service restarts (reuses a daemon already serving it)."
2383
2970
  ).option("--open", "With --web, open the printed URL in your default browser.").option(
2384
2971
  "--restart",
2385
2972
  "With --web or --port, stop a running daemon started without them and start a new one."
@@ -2420,7 +3007,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
2420
3007
  if (opts.web) retry.push("--web");
2421
3008
  throw new CliError(
2422
3009
  `gezeld is already running for this home ${opts.web ? "without the web UI" : `on port ${running.port}`} (pid ${running.pid}).
2423
- Restart it ${wanted} with \`${[...retry, "--restart"].join(" ")}\`, or stop it first with \`gezel stop --daemon\`.`
3010
+ Restart it ${wanted} with \`${[...retry, "--restart"].join(" ")}\`, or stop it first with \`gezel stop\`.`
2424
3011
  );
2425
3012
  }
2426
3013
  console.error(`Restarting gezeld (pid ${running.pid}) ${wanted}\u2026`);
@@ -2546,6 +3133,7 @@ program.command("status").description("Show daemon status (exits 1 when gezeld i
2546
3133
  console.log(
2547
3134
  `gezeld system service port=${system.port} health=ok version=${health.version} startedAt=${health.startedAt}`
2548
3135
  );
3136
+ reportApiCompat(system.compat);
2549
3137
  return;
2550
3138
  }
2551
3139
  const broker = await describeMachineEngineBroker();
@@ -2584,18 +3172,41 @@ program.command("status").description("Show daemon status (exits 1 when gezeld i
2584
3172
  console.log(
2585
3173
  `health ok: version=${health.version} startedAt=${health.startedAt}${engineNote}`
2586
3174
  );
3175
+ reportApiCompat(evaluateApiCompat2(health, { client: CLI_CLIENT_LABEL }));
2587
3176
  } catch (err) {
2588
3177
  console.error(`health failed: ${err.message}`);
2589
3178
  process.exitCode = 1;
2590
3179
  }
2591
3180
  });
3181
+ function reportApiCompat(verdict) {
3182
+ if (verdict.compatible) {
3183
+ console.log("api: compatible with this gezel CLI");
3184
+ return;
3185
+ }
3186
+ console.log(`api: incompatible \u2014 ${verdict.reason}`);
3187
+ process.exitCode = 1;
3188
+ }
2592
3189
  program.command("stop").description(
2593
- "Hard stop all AI work and switch Gezel to Reactive mode; gezeld keeps running (use --daemon to shut it down)"
2594
- ).option("--daemon", "Shut down the user-owned daemon process itself").action(async (opts) => {
3190
+ "Stop all AI work and shut down your Gezel service (--keep-running only stops the AI work)"
3191
+ ).option(
3192
+ "--keep-running",
3193
+ "Emergency brake: cancel AI work, unload engines and switch to Reactive, but leave the service running"
3194
+ ).addOption(new Option("--daemon", "Shut down the service (the default)").hideHelp()).action(async (opts) => {
2595
3195
  const globals = cliGlobals();
2596
- if (opts.daemon) {
2597
- await stopUserDaemon(globals);
2598
- return;
3196
+ if (!opts.keepRunning) {
3197
+ if (globals.connect) {
3198
+ throw new CliError(
3199
+ "gezel stop cannot shut down a remote service. Use `gezel stop --keep-running` to stop its AI work."
3200
+ );
3201
+ }
3202
+ const system = await findHealthySystemService(globals);
3203
+ if (!system) {
3204
+ await stopUserDaemon(globals);
3205
+ return;
3206
+ }
3207
+ console.log(
3208
+ `The machine-wide Gezel service on port ${system.port} is managed by the operating system and keeps running; stopping its AI work instead.`
3209
+ );
2599
3210
  }
2600
3211
  let userRuntime = null;
2601
3212
  if (!globals.connect && !await findHealthySystemService(globals)) {
@@ -2617,7 +3228,7 @@ program.command("stop").description(
2617
3228
  );
2618
3229
  if (userRuntime) {
2619
3230
  console.log(
2620
- `gezeld is still running (pid ${userRuntime.pid}); run \`gezel stop --daemon\` to shut it down.`
3231
+ `gezeld is still running (pid ${userRuntime.pid}); run \`gezel stop\` to shut it down.`
2621
3232
  );
2622
3233
  }
2623
3234
  });
@@ -2648,7 +3259,7 @@ async function stopDaemonPid(pid) {
2648
3259
  }
2649
3260
  async function stopUserDaemon(globals) {
2650
3261
  if (globals.connect) {
2651
- throw new CliError("gezel stop --daemon cannot stop an explicit remote service.");
3262
+ throw new CliError("gezel stop cannot shut down an explicit remote service.");
2652
3263
  }
2653
3264
  const system = await findHealthySystemService(globals);
2654
3265
  if (system) {
@@ -2716,15 +3327,17 @@ Replies go to stdout; diagnostics go to stderr.`
2716
3327
  });
2717
3328
  const { client } = conn;
2718
3329
  const projectId = await resolveRunProject(client, cliGlobals());
2719
- const gezelId = opts.gezel ?? await ensureCliProjectLead(client, projectId);
3330
+ const gezelId = opts.gezel ? await resolveRunGezel(client, opts.gezel) : await ensureCliProjectLead(client, projectId);
2720
3331
  const readiness = await checkRunReadiness(client, gezelId);
2721
3332
  if (!readiness.ready) {
2722
3333
  console.error(readiness.message);
2723
3334
  process.exitCode = 1;
2724
3335
  return;
2725
3336
  }
2726
- const session = await client.createChatSession({ gezelId, projectId });
3337
+ const session = await client.createChatSession({ gezelId, projectId, oneShot: true });
2727
3338
  await client.sendToChatSession(session.id, prompt);
3339
+ const reply = new ReplyPrinter((text) => process.stdout.write(text));
3340
+ const progress = new RunProgress((text) => process.stderr.write(text));
2728
3341
  let printed = false;
2729
3342
  let errored = false;
2730
3343
  for await (const ev of streamChatEvents({
@@ -2732,20 +3345,23 @@ Replies go to stdout; diagnostics go to stderr.`
2732
3345
  headers: client.authHeader(),
2733
3346
  fetch: client.getFetch()
2734
3347
  })) {
2735
- if (ev.type === "delta") {
2736
- process.stdout.write(ev.content);
2737
- printed = true;
3348
+ if (ev.type === "engine_phase") {
3349
+ progress.phase(ev);
3350
+ } else if (ev.type === "delta") {
3351
+ progress.settle();
3352
+ reply.push(ev.content);
2738
3353
  } else if (ev.type === "complete") {
2739
- if (!printed && ev.message.content) {
2740
- process.stdout.write(ev.message.content);
2741
- printed = true;
2742
- }
3354
+ progress.settle();
3355
+ printed = reply.finish(ev.message.content);
2743
3356
  } else if (ev.type === "error") {
3357
+ progress.settle();
2744
3358
  console.error(`
2745
3359
  ${ev.error}`);
2746
3360
  errored = true;
2747
3361
  }
2748
3362
  }
3363
+ progress.settle();
3364
+ printed = reply.finish() || printed;
2749
3365
  if (printed) process.stdout.write("\n");
2750
3366
  if (errored) process.exitCode = 1;
2751
3367
  } finally {
@@ -2765,6 +3381,7 @@ program.command("do <craftbook...>").description(
2765
3381
  `
2766
3382
  Bare values fill the craftbook's required parameters in order; key=value sets any
2767
3383
  parameter; every other word is your request, which becomes the task description.
3384
+ \`gezel craftbook list\` shows the craftbooks you can start here.
2768
3385
 
2769
3386
  Examples:
2770
3387
  gezel do summarize-long "Summarize notes.txt for the board"
@@ -2795,35 +3412,35 @@ Examples:
2795
3412
  const shorthandBook = shorthand2 && craftbooks.find((candidate) => candidate.id === shorthand2.id);
2796
3413
  if (shorthand2 && !shorthandBook) throw new CliError(`craftbook not found: ${shorthand2.id}`);
2797
3414
  const { book, args } = shorthandBook ? { book: shorthandBook, args: craftbookParts.slice(1) } : resolveCraftbookInvocation(craftbooks, craftbookParts);
2798
- const { craftbook } = await client.getCraftbook(book.id, {
3415
+ const { craftbook: craftbook2 } = await client.getCraftbook(book.id, {
2799
3416
  projectId,
2800
3417
  source: book.source,
2801
3418
  version: book.version
2802
3419
  });
2803
3420
  if (shorthand2) {
2804
- if (craftbook.cliWorkflow)
3421
+ if (craftbook2.cliWorkflow)
2805
3422
  throw new CliError(
2806
3423
  `${book.id} runs a workflow module from this project's code, so it does not start by name alone. Run it with: gezel do ${book.id}`
2807
3424
  );
2808
3425
  process.stderr.write(`${shorthandEcho(book.id, shorthandTail)}
2809
3426
  `);
2810
3427
  }
2811
- const parsed = parseCraftbookArguments(craftbook, args, opts.param);
3428
+ const parsed = parseCraftbookArguments(craftbook2, args, opts.param);
2812
3429
  const setUp = () => ensureCraftbookSetup(client, {
2813
3430
  projectId,
2814
- label: craftbook.name,
2815
- needs: craftbook,
3431
+ label: craftbook2.name,
3432
+ needs: craftbook2,
2816
3433
  params: parsed.params,
2817
- ...craftbook.paramSchema ? { paramSchema: craftbook.paramSchema } : {},
3434
+ ...craftbook2.paramSchema ? { paramSchema: craftbook2.paramSchema } : {},
2818
3435
  prompter: terminalPrompter(),
2819
- write: (text) => process.stderr.write(text)
3436
+ write: stderrProgress()
2820
3437
  });
2821
- if (craftbook.cliWorkflow) {
3438
+ if (craftbook2.cliWorkflow) {
2822
3439
  if (book.source !== "project")
2823
3440
  throw new CliError("CLI workflow craftbooks must belong to this project.");
2824
3441
  if (parsed.request)
2825
3442
  throw new CliError(
2826
- `${craftbook.name} runs a workflow module and takes no request text; pass its parameters as key=value (unused: "${parsed.request}").`
3443
+ `${craftbook2.name} runs a workflow module and takes no request text; pass its parameters as key=value (unused: "${parsed.request}").`
2827
3444
  );
2828
3445
  if (opts.strictSandbox)
2829
3446
  throw new CliError(
@@ -2831,16 +3448,16 @@ Examples:
2831
3448
  );
2832
3449
  await setUp();
2833
3450
  const workspace = typeof cliGlobals().project === "string" ? cliGlobals().project : process.cwd();
2834
- console.error(`Running ${craftbook.name}: ${craftbook.cliWorkflow.module}`);
3451
+ console.error(`Running ${craftbook2.name}: ${craftbook2.cliWorkflow.module}`);
2835
3452
  const result2 = await runWorkflow(
2836
3453
  client,
2837
3454
  projectId,
2838
3455
  workspace,
2839
- craftbook.cliWorkflow.module,
3456
+ craftbook2.cliWorkflow.module,
2840
3457
  [],
2841
3458
  console.error,
2842
3459
  {
2843
- craftbook,
3460
+ craftbook: craftbook2,
2844
3461
  params: parsed.params,
2845
3462
  timeoutMs
2846
3463
  }
@@ -2851,7 +3468,7 @@ Examples:
2851
3468
  await setUp();
2852
3469
  const created = await client.createTask(projectId, {
2853
3470
  ...craftbookStartRequest(book),
2854
- ...craftbookDoLaunch(craftbook, parsed),
3471
+ ...craftbookDoLaunch(craftbook2, parsed),
2855
3472
  trustScripts: !opts.strictSandbox,
2856
3473
  roleBasedNameOnlyMode: true
2857
3474
  });
@@ -2894,9 +3511,56 @@ async function printTaskWait(client, ref, opts) {
2894
3511
  `${task2.ref}: ${task2.status}${task2.activeStepId ? ` (${task2.activeStepId})` : ""}`
2895
3512
  )
2896
3513
  });
2897
- console.log(opts.json ? JSON.stringify(result) : `${result.task.ref}: ${result.outcome}`);
3514
+ const reason = await blockedTaskReason(client, result);
3515
+ console.log(
3516
+ opts.json ? JSON.stringify({ ...result, ...reason ? { reason } : {} }) : `${result.task.ref}: ${result.outcome}`
3517
+ );
3518
+ if (!opts.json && result.outcome === "blocked") {
3519
+ if (reason) console.error(reason);
3520
+ console.error(`See its notes with \`gezel task notes ${result.task.ref}\`.`);
3521
+ }
2898
3522
  process.exitCode = result.exitCode;
2899
3523
  }
3524
+ var craftbook = program.command("craftbook").description("Browse the craftbooks `gezel do` can start");
3525
+ craftbook.command("list [words...]").description(
3526
+ "List the craftbooks `gezel do` can start in this folder's project; words filter by command, title and tags"
3527
+ ).option("--json", "emit the list as JSON").action(async (words, opts) => {
3528
+ const client = await connectOwned(cliGlobals());
3529
+ const preview = await previewRunProject(client, cliGlobals());
3530
+ const projectId = preview.projectId ?? "default";
3531
+ const [config, result] = await Promise.all([
3532
+ client.getConfig(),
3533
+ client.listProjectCraftbooks(projectId)
3534
+ ]);
3535
+ const books = filterCraftbooks(
3536
+ normalizeCraftbooks(result.items, config.showWorkInProgressFeatures === true),
3537
+ words
3538
+ );
3539
+ if (opts.json) {
3540
+ console.log(
3541
+ JSON.stringify(
3542
+ books.map((book) => ({
3543
+ command: book.command,
3544
+ name: book.name,
3545
+ category: book.category,
3546
+ source: book.source,
3547
+ ...book.description ? { description: book.description } : {}
3548
+ }))
3549
+ )
3550
+ );
3551
+ return;
3552
+ }
3553
+ if (books.length === 0) {
3554
+ console.log(
3555
+ words.length > 0 ? `No craftbook matches "${words.join(" ")}".` : "No craftbooks are available here."
3556
+ );
3557
+ return;
3558
+ }
3559
+ const width = Math.min(32, Math.max(...books.map((book) => book.command.length)) + 2);
3560
+ for (const book of books) console.log(`${book.command.padEnd(width)}${book.name}`);
3561
+ console.error(`
3562
+ Start one with \`gezel do <command> "<your request>"\`.`);
3563
+ });
2900
3564
  var agent = program.command("agent").description("Manage your gezels (your AI companions)");
2901
3565
  agent.command("output-limit <id> [tokens]").description(
2902
3566
  "Show or set one gezel's output-token limit, including reasoning; auto clears its override"
@@ -3523,7 +4187,7 @@ native.command("install").description(
3523
4187
  const installed = await installNativeToolkit(client, {
3524
4188
  ...variant ? { variant } : {},
3525
4189
  ...engine ? { engines: [engine] } : {},
3526
- output: { writeProgress: (text) => process.stderr.write(text) }
4190
+ output: { writeProgress: stderrProgress() }
3527
4191
  });
3528
4192
  console.log(
3529
4193
  `${engine ? `${engine} ready` : "native toolkit ready"}
@@ -3571,25 +4235,26 @@ image.command("pull <id>").description("Download an image model from the catalog
3571
4235
  const client = await connectOwned(cliGlobals());
3572
4236
  let lastPct = -1;
3573
4237
  let pullError;
4238
+ const progress = stderrProgress();
3574
4239
  await client.pullImageModel(id, (ev) => {
3575
4240
  if (ev.type === "progress") {
3576
4241
  const total = ev.totalBytes ?? 0;
3577
4242
  const pct = total > 0 ? Math.floor(ev.bytesWritten / total * 100) : 0;
3578
4243
  if (pct !== lastPct) {
3579
4244
  lastPct = pct;
3580
- process.stderr.write(
4245
+ progress(
3581
4246
  `\rpulling ${id}: ${String(pct).padStart(3)}% ${(ev.bytesWritten / 1e9).toFixed(2)}/${(total / 1e9).toFixed(2)} GB`
3582
4247
  );
3583
4248
  }
3584
4249
  } else if (ev.type === "retrying") {
3585
- process.stderr.write(`
4250
+ progress(`
3586
4251
  retry ${ev.attempt}/${ev.maxAttempts}: ${ev.reason}
3587
4252
  `);
3588
4253
  } else if (ev.type === "error") {
3589
4254
  pullError = ev.error;
3590
- process.stderr.write("\n");
4255
+ progress("\n");
3591
4256
  } else if (ev.type === "done" && !pullError) {
3592
- process.stderr.write(`\rpulled ${id}${" ".repeat(48)}
4257
+ progress(`\rpulled ${id}${" ".repeat(48)}
3593
4258
  `);
3594
4259
  }
3595
4260
  });
@@ -3608,7 +4273,7 @@ function resolveModelProvider(raw) {
3608
4273
  }
3609
4274
  return raw;
3610
4275
  }
3611
- return resolveOnDeviceProvider2(process.platform, process.arch);
4276
+ return resolveOnDeviceProvider3(process.platform, process.arch);
3612
4277
  }
3613
4278
  model.command("concurrency [slots]").description("Show or set local inference slots; use auto to restore automatic sizing").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").option("--json", "Output the slot override as JSON").action(async (slots, opts) => {
3614
4279
  const provider = resolveModelProvider(opts.provider);
@@ -3648,12 +4313,25 @@ model.command("context <id> [tokens]").description("Show or set a model context
3648
4313
  );
3649
4314
  }
3650
4315
  );
3651
- model.command("list").description("List local chat models for an engine").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").action(async (opts) => {
4316
+ model.command("list").description("List downloaded chat models, or with --available the catalog models that fit").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").option("-a, --available", "List catalog models for this machine, with download sizes").action(async (opts) => {
3652
4317
  const client = await connectOwned(cliGlobals());
3653
4318
  const provider = resolveModelProvider(opts.provider);
4319
+ if (opts.available) {
4320
+ const available = await availableChatModels(client, provider);
4321
+ console.log(
4322
+ formatAvailableChatModels({
4323
+ engine: provider,
4324
+ platformDefault: resolveOnDeviceProvider3(process.platform, process.arch),
4325
+ ...available
4326
+ })
4327
+ );
4328
+ return;
4329
+ }
3654
4330
  const { models } = provider === "mlx" ? await client.listMlxModels() : provider === "ds4" ? await client.listDs4Models() : await client.listLlamaCppModels();
3655
4331
  if (models.length === 0) {
3656
- console.log(`(no local ${provider} models \u2014 download one with \`gezel model pull <id>\`)`);
4332
+ console.log(
4333
+ `(no local ${provider} models \u2014 \`gezel model list --available\` shows ones to download)`
4334
+ );
3657
4335
  return;
3658
4336
  }
3659
4337
  for (const m of models) {
@@ -3662,10 +4340,26 @@ model.command("list").description("List local chat models for an engine").option
3662
4340
  );
3663
4341
  }
3664
4342
  });
3665
- model.command("pull <id>").description("Download a local chat model from the catalog (e.g. gemma4-31b-q4)").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").action(async (id, opts) => {
4343
+ model.command("pull <id>").description(
4344
+ "Download a local chat model from the catalog (e.g. qwen3.5-2b-q4, about 1.5 GB; `gezel model list --available` shows what fits)"
4345
+ ).option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").action(async (id, opts) => {
3666
4346
  const client = await connectOwned(cliGlobals());
3667
4347
  const provider = resolveModelProvider(opts.provider);
3668
- await pullChatModel(client, provider, id, (text) => process.stderr.write(text));
4348
+ const progress = stderrProgress();
4349
+ await pullChatModel(client, provider, id, progress);
4350
+ if (provider === "mlx") await waitForMlxRuntime(client, progress);
4351
+ if (await pinPulledModel(client, provider, id) === "pinned") {
4352
+ process.stderr.write(`${id} is now the default ${provider} model.
4353
+ `);
4354
+ }
4355
+ });
4356
+ model.command("use <id>").description("Make chats use a downloaded model").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: the engine that has it)").action(async (id, opts) => {
4357
+ const client = await connectOwned(cliGlobals());
4358
+ const engine = await useChatModel(client, id, {
4359
+ ...opts.provider ? { requested: resolveModelProvider(opts.provider) } : {},
4360
+ platformDefault: resolveOnDeviceProvider3(process.platform, process.arch)
4361
+ });
4362
+ console.log(`Chats now use ${id} (${engine}).`);
3669
4363
  });
3670
4364
  model.command("export <id> [file]").description("Export a catalog model to a portable .gezmodel (downloads it first if needed)").option("-p, --provider <engine>", "mlx | llama-cpp | ds4 (default: platform default)").option("-f, --force", "Overwrite an existing file").option("--no-pull", "Fail instead of downloading a model that is not installed yet").action(async (id, file, opts) => {
3671
4365
  const client = await connectOwned(cliGlobals());
@@ -3676,9 +4370,7 @@ model.command("export <id> [file]").description("Export a catalog model to a por
3676
4370
  ...opts.force ? { force: true } : {},
3677
4371
  ...opts.pull === false ? { skipPull: true } : {},
3678
4372
  output: {
3679
- writeProgress: (text) => {
3680
- process.stderr.write(text);
3681
- }
4373
+ writeProgress: stderrProgress()
3682
4374
  }
3683
4375
  });
3684
4376
  console.log(`exported ${id} to ${result.path} (${(result.bytesWritten / 1e9).toFixed(2)} GB)`);