@bendyline/gezel-cli 1.2.5 → 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
  }
@@ -985,12 +1101,110 @@ import {
985
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"];
@@ -1674,6 +1888,99 @@ function assertCatalogOnlyOptions(opts, kind) {
1674
1888
  }
1675
1889
  }
1676
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
+
1677
1984
  // src/model-export.ts
1678
1985
  import { randomUUID as randomUUID2 } from "crypto";
1679
1986
  import { rename, rm as rm2, stat } from "fs/promises";
@@ -1788,6 +2095,143 @@ function progressText(bytesCompleted, bytesTotal) {
1788
2095
  return `${String(pct).padStart(3)}% ${formatGb(bytesCompleted)}/${formatGb(bytesTotal)} GB`;
1789
2096
  }
1790
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
+
1791
2235
  // src/run-prompt.ts
1792
2236
  async function resolveRunPrompt(parts, input = process.stdin) {
1793
2237
  if (parts?.length !== 1 || parts[0] !== "-") {
@@ -1815,6 +2259,7 @@ async function resolveRunPrompt(parts, input = process.stdin) {
1815
2259
  }
1816
2260
 
1817
2261
  // src/run-readiness.ts
2262
+ import { resolveOnDeviceProvider as resolveOnDeviceProvider2 } from "@bendyline/gezel/native";
1818
2263
  var READY = { ready: true };
1819
2264
  async function settledFirstRunConfig(client, options = {}) {
1820
2265
  const attempts = options.attempts ?? 12;
@@ -1863,12 +2308,22 @@ async function checkRunReadiness(client, gezelId, env2 = process.env) {
1863
2308
  }
1864
2309
  function formatRunSetupMessage(input) {
1865
2310
  const { provider, engineMissing, pinned, installedIds } = input;
2311
+ const flag = providerFlag(
2312
+ provider,
2313
+ input.platformDefault ?? resolveOnDeviceProvider2(process.platform, process.arch)
2314
+ );
1866
2315
  const steps = [];
1867
2316
  if (engineMissing) steps.push("gezel native install");
1868
2317
  if (pinned && !installedIds.includes(pinned)) {
1869
- 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
+ }
1870
2325
  } else if (!pinned && installedIds.length === 0) {
1871
- steps.push("gezel model list (then: gezel model pull <id>)");
2326
+ steps.push(`gezel model list --available${flag} (then: gezel model pull <id>${flag})`);
1872
2327
  }
1873
2328
  const lines = [];
1874
2329
  if (pinned && !installedIds.includes(pinned) && installedIds.length > 0) {
@@ -1892,6 +2347,99 @@ function formatRunSetupMessage(input) {
1892
2347
  return lines.join("\n");
1893
2348
  }
1894
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
+
1895
2443
  // src/secrets-command.ts
1896
2444
  import { GezelApiError as GezelApiError2 } from "@bendyline/gezel-client";
1897
2445
  var credentialFlags = {
@@ -2418,7 +2966,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
2418
2966
  "Run the daemon attached to this terminal \u2014 stdio streams to this shell, Ctrl+C stops it. Useful for development and CI."
2419
2967
  ).option(
2420
2968
  "--web",
2421
- "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)."
2422
2970
  ).option("--open", "With --web, open the printed URL in your default browser.").option(
2423
2971
  "--restart",
2424
2972
  "With --web or --port, stop a running daemon started without them and start a new one."
@@ -2459,7 +3007,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
2459
3007
  if (opts.web) retry.push("--web");
2460
3008
  throw new CliError(
2461
3009
  `gezeld is already running for this home ${opts.web ? "without the web UI" : `on port ${running.port}`} (pid ${running.pid}).
2462
- 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\`.`
2463
3011
  );
2464
3012
  }
2465
3013
  console.error(`Restarting gezeld (pid ${running.pid}) ${wanted}\u2026`);
@@ -2585,6 +3133,7 @@ program.command("status").description("Show daemon status (exits 1 when gezeld i
2585
3133
  console.log(
2586
3134
  `gezeld system service port=${system.port} health=ok version=${health.version} startedAt=${health.startedAt}`
2587
3135
  );
3136
+ reportApiCompat(system.compat);
2588
3137
  return;
2589
3138
  }
2590
3139
  const broker = await describeMachineEngineBroker();
@@ -2623,18 +3172,41 @@ program.command("status").description("Show daemon status (exits 1 when gezeld i
2623
3172
  console.log(
2624
3173
  `health ok: version=${health.version} startedAt=${health.startedAt}${engineNote}`
2625
3174
  );
3175
+ reportApiCompat(evaluateApiCompat2(health, { client: CLI_CLIENT_LABEL }));
2626
3176
  } catch (err) {
2627
3177
  console.error(`health failed: ${err.message}`);
2628
3178
  process.exitCode = 1;
2629
3179
  }
2630
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
+ }
2631
3189
  program.command("stop").description(
2632
- "Hard stop all AI work and switch Gezel to Reactive mode; gezeld keeps running (use --daemon to shut it down)"
2633
- ).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) => {
2634
3195
  const globals = cliGlobals();
2635
- if (opts.daemon) {
2636
- await stopUserDaemon(globals);
2637
- 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
+ );
2638
3210
  }
2639
3211
  let userRuntime = null;
2640
3212
  if (!globals.connect && !await findHealthySystemService(globals)) {
@@ -2656,7 +3228,7 @@ program.command("stop").description(
2656
3228
  );
2657
3229
  if (userRuntime) {
2658
3230
  console.log(
2659
- `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.`
2660
3232
  );
2661
3233
  }
2662
3234
  });
@@ -2687,7 +3259,7 @@ async function stopDaemonPid(pid) {
2687
3259
  }
2688
3260
  async function stopUserDaemon(globals) {
2689
3261
  if (globals.connect) {
2690
- 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.");
2691
3263
  }
2692
3264
  const system = await findHealthySystemService(globals);
2693
3265
  if (system) {
@@ -2755,15 +3327,17 @@ Replies go to stdout; diagnostics go to stderr.`
2755
3327
  });
2756
3328
  const { client } = conn;
2757
3329
  const projectId = await resolveRunProject(client, cliGlobals());
2758
- const gezelId = opts.gezel ?? await ensureCliProjectLead(client, projectId);
3330
+ const gezelId = opts.gezel ? await resolveRunGezel(client, opts.gezel) : await ensureCliProjectLead(client, projectId);
2759
3331
  const readiness = await checkRunReadiness(client, gezelId);
2760
3332
  if (!readiness.ready) {
2761
3333
  console.error(readiness.message);
2762
3334
  process.exitCode = 1;
2763
3335
  return;
2764
3336
  }
2765
- const session = await client.createChatSession({ gezelId, projectId });
3337
+ const session = await client.createChatSession({ gezelId, projectId, oneShot: true });
2766
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));
2767
3341
  let printed = false;
2768
3342
  let errored = false;
2769
3343
  for await (const ev of streamChatEvents({
@@ -2771,20 +3345,23 @@ Replies go to stdout; diagnostics go to stderr.`
2771
3345
  headers: client.authHeader(),
2772
3346
  fetch: client.getFetch()
2773
3347
  })) {
2774
- if (ev.type === "delta") {
2775
- process.stdout.write(ev.content);
2776
- 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);
2777
3353
  } else if (ev.type === "complete") {
2778
- if (!printed && ev.message.content) {
2779
- process.stdout.write(ev.message.content);
2780
- printed = true;
2781
- }
3354
+ progress.settle();
3355
+ printed = reply.finish(ev.message.content);
2782
3356
  } else if (ev.type === "error") {
3357
+ progress.settle();
2783
3358
  console.error(`
2784
3359
  ${ev.error}`);
2785
3360
  errored = true;
2786
3361
  }
2787
3362
  }
3363
+ progress.settle();
3364
+ printed = reply.finish() || printed;
2788
3365
  if (printed) process.stdout.write("\n");
2789
3366
  if (errored) process.exitCode = 1;
2790
3367
  } finally {
@@ -2804,6 +3381,7 @@ program.command("do <craftbook...>").description(
2804
3381
  `
2805
3382
  Bare values fill the craftbook's required parameters in order; key=value sets any
2806
3383
  parameter; every other word is your request, which becomes the task description.
3384
+ \`gezel craftbook list\` shows the craftbooks you can start here.
2807
3385
 
2808
3386
  Examples:
2809
3387
  gezel do summarize-long "Summarize notes.txt for the board"
@@ -2834,35 +3412,35 @@ Examples:
2834
3412
  const shorthandBook = shorthand2 && craftbooks.find((candidate) => candidate.id === shorthand2.id);
2835
3413
  if (shorthand2 && !shorthandBook) throw new CliError(`craftbook not found: ${shorthand2.id}`);
2836
3414
  const { book, args } = shorthandBook ? { book: shorthandBook, args: craftbookParts.slice(1) } : resolveCraftbookInvocation(craftbooks, craftbookParts);
2837
- const { craftbook } = await client.getCraftbook(book.id, {
3415
+ const { craftbook: craftbook2 } = await client.getCraftbook(book.id, {
2838
3416
  projectId,
2839
3417
  source: book.source,
2840
3418
  version: book.version
2841
3419
  });
2842
3420
  if (shorthand2) {
2843
- if (craftbook.cliWorkflow)
3421
+ if (craftbook2.cliWorkflow)
2844
3422
  throw new CliError(
2845
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}`
2846
3424
  );
2847
3425
  process.stderr.write(`${shorthandEcho(book.id, shorthandTail)}
2848
3426
  `);
2849
3427
  }
2850
- const parsed = parseCraftbookArguments(craftbook, args, opts.param);
3428
+ const parsed = parseCraftbookArguments(craftbook2, args, opts.param);
2851
3429
  const setUp = () => ensureCraftbookSetup(client, {
2852
3430
  projectId,
2853
- label: craftbook.name,
2854
- needs: craftbook,
3431
+ label: craftbook2.name,
3432
+ needs: craftbook2,
2855
3433
  params: parsed.params,
2856
- ...craftbook.paramSchema ? { paramSchema: craftbook.paramSchema } : {},
3434
+ ...craftbook2.paramSchema ? { paramSchema: craftbook2.paramSchema } : {},
2857
3435
  prompter: terminalPrompter(),
2858
- write: (text) => process.stderr.write(text)
3436
+ write: stderrProgress()
2859
3437
  });
2860
- if (craftbook.cliWorkflow) {
3438
+ if (craftbook2.cliWorkflow) {
2861
3439
  if (book.source !== "project")
2862
3440
  throw new CliError("CLI workflow craftbooks must belong to this project.");
2863
3441
  if (parsed.request)
2864
3442
  throw new CliError(
2865
- `${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}").`
2866
3444
  );
2867
3445
  if (opts.strictSandbox)
2868
3446
  throw new CliError(
@@ -2870,16 +3448,16 @@ Examples:
2870
3448
  );
2871
3449
  await setUp();
2872
3450
  const workspace = typeof cliGlobals().project === "string" ? cliGlobals().project : process.cwd();
2873
- console.error(`Running ${craftbook.name}: ${craftbook.cliWorkflow.module}`);
3451
+ console.error(`Running ${craftbook2.name}: ${craftbook2.cliWorkflow.module}`);
2874
3452
  const result2 = await runWorkflow(
2875
3453
  client,
2876
3454
  projectId,
2877
3455
  workspace,
2878
- craftbook.cliWorkflow.module,
3456
+ craftbook2.cliWorkflow.module,
2879
3457
  [],
2880
3458
  console.error,
2881
3459
  {
2882
- craftbook,
3460
+ craftbook: craftbook2,
2883
3461
  params: parsed.params,
2884
3462
  timeoutMs
2885
3463
  }
@@ -2890,7 +3468,7 @@ Examples:
2890
3468
  await setUp();
2891
3469
  const created = await client.createTask(projectId, {
2892
3470
  ...craftbookStartRequest(book),
2893
- ...craftbookDoLaunch(craftbook, parsed),
3471
+ ...craftbookDoLaunch(craftbook2, parsed),
2894
3472
  trustScripts: !opts.strictSandbox,
2895
3473
  roleBasedNameOnlyMode: true
2896
3474
  });
@@ -2933,9 +3511,56 @@ async function printTaskWait(client, ref, opts) {
2933
3511
  `${task2.ref}: ${task2.status}${task2.activeStepId ? ` (${task2.activeStepId})` : ""}`
2934
3512
  )
2935
3513
  });
2936
- 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
+ }
2937
3522
  process.exitCode = result.exitCode;
2938
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
+ });
2939
3564
  var agent = program.command("agent").description("Manage your gezels (your AI companions)");
2940
3565
  agent.command("output-limit <id> [tokens]").description(
2941
3566
  "Show or set one gezel's output-token limit, including reasoning; auto clears its override"
@@ -3562,7 +4187,7 @@ native.command("install").description(
3562
4187
  const installed = await installNativeToolkit(client, {
3563
4188
  ...variant ? { variant } : {},
3564
4189
  ...engine ? { engines: [engine] } : {},
3565
- output: { writeProgress: (text) => process.stderr.write(text) }
4190
+ output: { writeProgress: stderrProgress() }
3566
4191
  });
3567
4192
  console.log(
3568
4193
  `${engine ? `${engine} ready` : "native toolkit ready"}
@@ -3610,25 +4235,26 @@ image.command("pull <id>").description("Download an image model from the catalog
3610
4235
  const client = await connectOwned(cliGlobals());
3611
4236
  let lastPct = -1;
3612
4237
  let pullError;
4238
+ const progress = stderrProgress();
3613
4239
  await client.pullImageModel(id, (ev) => {
3614
4240
  if (ev.type === "progress") {
3615
4241
  const total = ev.totalBytes ?? 0;
3616
4242
  const pct = total > 0 ? Math.floor(ev.bytesWritten / total * 100) : 0;
3617
4243
  if (pct !== lastPct) {
3618
4244
  lastPct = pct;
3619
- process.stderr.write(
4245
+ progress(
3620
4246
  `\rpulling ${id}: ${String(pct).padStart(3)}% ${(ev.bytesWritten / 1e9).toFixed(2)}/${(total / 1e9).toFixed(2)} GB`
3621
4247
  );
3622
4248
  }
3623
4249
  } else if (ev.type === "retrying") {
3624
- process.stderr.write(`
4250
+ progress(`
3625
4251
  retry ${ev.attempt}/${ev.maxAttempts}: ${ev.reason}
3626
4252
  `);
3627
4253
  } else if (ev.type === "error") {
3628
4254
  pullError = ev.error;
3629
- process.stderr.write("\n");
4255
+ progress("\n");
3630
4256
  } else if (ev.type === "done" && !pullError) {
3631
- process.stderr.write(`\rpulled ${id}${" ".repeat(48)}
4257
+ progress(`\rpulled ${id}${" ".repeat(48)}
3632
4258
  `);
3633
4259
  }
3634
4260
  });
@@ -3647,7 +4273,7 @@ function resolveModelProvider(raw) {
3647
4273
  }
3648
4274
  return raw;
3649
4275
  }
3650
- return resolveOnDeviceProvider2(process.platform, process.arch);
4276
+ return resolveOnDeviceProvider3(process.platform, process.arch);
3651
4277
  }
3652
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) => {
3653
4279
  const provider = resolveModelProvider(opts.provider);
@@ -3687,12 +4313,25 @@ model.command("context <id> [tokens]").description("Show or set a model context
3687
4313
  );
3688
4314
  }
3689
4315
  );
3690
- 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) => {
3691
4317
  const client = await connectOwned(cliGlobals());
3692
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
+ }
3693
4330
  const { models } = provider === "mlx" ? await client.listMlxModels() : provider === "ds4" ? await client.listDs4Models() : await client.listLlamaCppModels();
3694
4331
  if (models.length === 0) {
3695
- 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
+ );
3696
4335
  return;
3697
4336
  }
3698
4337
  for (const m of models) {
@@ -3701,10 +4340,26 @@ model.command("list").description("List local chat models for an engine").option
3701
4340
  );
3702
4341
  }
3703
4342
  });
3704
- 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) => {
3705
4346
  const client = await connectOwned(cliGlobals());
3706
4347
  const provider = resolveModelProvider(opts.provider);
3707
- 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}).`);
3708
4363
  });
3709
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) => {
3710
4365
  const client = await connectOwned(cliGlobals());
@@ -3715,9 +4370,7 @@ model.command("export <id> [file]").description("Export a catalog model to a por
3715
4370
  ...opts.force ? { force: true } : {},
3716
4371
  ...opts.pull === false ? { skipPull: true } : {},
3717
4372
  output: {
3718
- writeProgress: (text) => {
3719
- process.stderr.write(text);
3720
- }
4373
+ writeProgress: stderrProgress()
3721
4374
  }
3722
4375
  });
3723
4376
  console.log(`exported ${id} to ${result.path} (${(result.bytesWritten / 1e9).toFixed(2)} GB)`);