@usabledev/usable-chat 1.147.0 → 1.148.0

package/cli.js

@@ -23716,8 +23716,7 @@ var init_harness_prompt = __esm({
 </communication>
 
 <grounding>
-Usable is the user's long-term memory and your first source of truth \u2014 consult it before guessing.
-- Before non-trivial work, search it with \`agentic-search-fragments\`: natural-language intent (what you're trying to achieve, not keywords), scoped to the workspace; iterate until the result is sufficient. Prefer it over external search or memory.
+Usable is the user's long-term memory. When a task touches project domain, past decisions, or conventions you're unsure of, ground yourself ONCE with a single targeted \`agentic-search-fragments\` (natural-language intent \u2014 what you're trying to achieve, not keywords \u2014 scoped to the workspace), then proceed. One good search is enough: don't re-run the same search, and don't search at all for routine local work you can just do (reading/editing files, running tests, authoring an extension from the \`extension_authoring_guide\`).
 - Cite the fragments you relied on (title + id). When you point the user at a fragment, give the link: https://usable.dev/dashboard/workspaces/<workspaceId>/fragments/<fragmentId>.
 - IDs \u2014 fragment, workspace, collection \u2014 come ONLY from tool results. NEVER invent, guess, or shorten a UUID.
 - After work is complete AND verified, capture durable insights with create/update-memory-fragment (tag by repo; note residual risk). Don't document speculatively.
@@ -23725,7 +23724,6 @@ Usable is the user's long-term memory and your first source of truth \u2014 cons
 
 <tools>
 - Resolve prerequisites before acting; run independent calls in parallel.
-- Don't stop at the first plausible answer if another call would cut uncertainty. If a search comes back empty or suspiciously narrow, retry with a different strategy.
 - \`bash\` output is truncated to a preview; the full output spills to a temp file whose path is reported. Don't pipe through \`head\`/\`tail\` to work around the truncation.
 - Destructive or hard-to-reverse commands require approval \u2014 surface what you're about to do first.
 </tools>
@@ -23740,7 +23738,7 @@ Usable is the user's long-term memory and your first source of truth \u2014 cons
 </completeness>
 
 <workflow>
-1. Scope \u2014 for multi-file work, research the existing code and conventions (and search Usable) before writing. Reuse existing patterns; inventing a parallel convention is prohibited.
+1. Scope \u2014 for multi-file work, research the existing code and conventions before writing (ground once in Usable if the task touches project conventions or past decisions). Reuse existing patterns; inventing a parallel convention is prohibited. A local coding task needs no plan-mode, task-status updates, or other workflow ceremony unless the user asks for it \u2014 just do the work.
 2. Edit \u2014 read whole sections, not snippets. Re-read a file if it changed since you last read it. Fix problems at the source and remove obsolete code rather than leaving aliases or re-exports behind.
 3. Verify \u2014 for non-trivial changes, prove it with tests you can actually run (prefer real over mocks; test behavior, not plumbing). All tests green before you call it done \u2014 "it was already broken" is not a skip reason; fix it or flag it.
 4. Report \u2014 say what changed, the evidence (the commands you ran and their results), and anything left or risky. Be brief in prose, not in evidence.
@@ -27325,7 +27323,7 @@ var init_sql = __esm({
         return new SQL([new StringChunk(str)]);
       }
       sql2.raw = raw;
-      function join20(chunks, separator) {
+      function join21(chunks, separator) {
         const result = [];
         for (const [i18, chunk2] of chunks.entries()) {
           if (i18 > 0 && separator !== void 0) {
@@ -27335,7 +27333,7 @@ var init_sql = __esm({
         }
         return new SQL(result);
       }
-      sql2.join = join20;
+      sql2.join = join21;
       function identifier(value) {
         return new Name(value);
       }
@@ -31722,7 +31720,7 @@ var init_select2 = __esm({
           const baseTableName = this.tableName;
           const tableName = getTableLikeName(table);
           for (const item of extractUsedTable(table)) this.usedTables.add(item);
-          if (typeof tableName === "string" && this.config.joins?.some((join20) => join20.alias === tableName)) {
+          if (typeof tableName === "string" && this.config.joins?.some((join21) => join21.alias === tableName)) {
             throw new Error(`Alias "${tableName}" is already used in this query`);
           }
           if (!this.isPartialSelect) {
@@ -33257,7 +33255,7 @@ var init_update = __esm({
       createJoin(joinType) {
         return (table, on3) => {
           const tableName = getTableLikeName(table);
-          if (typeof tableName === "string" && this.config.joins.some((join20) => join20.alias === tableName)) {
+          if (typeof tableName === "string" && this.config.joins.some((join21) => join21.alias === tableName)) {
             throw new Error(`Alias "${tableName}" is already used in this query`);
           }
           if (typeof on3 === "function") {
@@ -33353,10 +33351,10 @@ var init_update = __esm({
               const fromFields = this.getTableLikeFields(this.config.from);
               fields[tableName] = fromFields;
             }
-            for (const join20 of this.config.joins) {
-              const tableName2 = getTableLikeName(join20.table);
-              if (typeof tableName2 === "string" && !is(join20.table, SQL)) {
-                const fromFields = this.getTableLikeFields(join20.table);
+            for (const join21 of this.config.joins) {
+              const tableName2 = getTableLikeName(join21.table);
+              if (typeof tableName2 === "string" && !is(join21.table, SQL)) {
+                const fromFields = this.getTableLikeFields(join21.table);
                 fields[tableName2] = fromFields;
               }
             }
@@ -84938,8 +84936,8 @@ var init_bedrock_sdk = __esm({
 });
 
 // src/lib/logger.ts
-import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync8 } from "fs";
-import { join as join10 } from "path";
+import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync9 } from "fs";
+import { join as join11 } from "path";
 var LOG_LEVEL_PRIORITY, Logger, logger2, orchestrationLogger, streamLogger;
 var init_logger2 = __esm({
   "src/lib/logger.ts"() {
@@ -84952,7 +84950,7 @@ var init_logger2 = __esm({
     };
     Logger = class {
       constructor() {
-        this.logDir = join10(process.cwd(), "logs");
+        this.logDir = join11(process.cwd(), "logs");
         this.enableFileLogging = process.env.ENABLE_FILE_LOGGING === "true";
         this.isDevelopment = process.env.NODE_ENV === "development";
         this.enableConsoleLogging = this.isDevelopment || process.env.ENABLE_CONSOLE_LOGGING === "true";
@@ -84960,7 +84958,7 @@ var init_logger2 = __esm({
         this.minLogLevel = ["debug", "info", "warn", "error"].includes(configuredLevel) ? configuredLevel : "info";
         if (this.enableFileLogging) {
           try {
-            mkdirSync8(this.logDir, { recursive: true });
+            mkdirSync9(this.logDir, { recursive: true });
           } catch (error41) {
             console.error("Failed to create logs directory:", error41);
             this.enableFileLogging = false;
@@ -85042,7 +85040,7 @@ var init_logger2 = __esm({
       logToFile(entry) {
         try {
           const logFileName = this.getLogFileName(entry.category);
-          const logPath = join10(this.logDir, logFileName);
+          const logPath = join11(this.logDir, logFileName);
           const logLine = JSON.stringify(entry) + "\n";
           appendFileSync3(logPath, logLine, "utf-8");
         } catch (error41) {
@@ -215465,14 +215463,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self2, node);
         }
-        return join20(output, replacement);
+        return join21(output, replacement);
       }, "");
     }
     function postProcess(output) {
       var self2 = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join20(output, rule.append(self2.options));
+          output = join21(output, rule.append(self2.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -215484,7 +215482,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join20(output, replacement) {
+    function join21(output, replacement) {
       var s17 = trimTrailingNewlines(output);
       var s22 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s17.length, replacement.length - s22.length);
@@ -244534,12 +244532,12 @@ var init_session_pathway = __esm({
 });
 
 // src/adapters/cli/prompt-files.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, realpathSync as realpathSync4 } from "node:fs";
-import { dirname as dirname14, join as join15 } from "node:path";
+import { existsSync as existsSync10, readFileSync as readFileSync7, realpathSync as realpathSync4 } from "node:fs";
+import { dirname as dirname14, join as join16 } from "node:path";
 function readFile(path11) {
   try {
-    if (!existsSync9(path11)) return void 0;
-    const content = readFileSync6(path11, "utf8").trim();
+    if (!existsSync10(path11)) return void 0;
+    const content = readFileSync7(path11, "utf8").trim();
     return content || void 0;
   } catch {
     return void 0;
@@ -244548,7 +244546,7 @@ function readFile(path11) {
 function gitRoot(start) {
   let dir = start;
   while (true) {
-    if (existsSync9(join15(dir, ".git"))) return dir;
+    if (existsSync10(join16(dir, ".git"))) return dir;
     const parent = dirname14(dir);
     if (parent === dir) return start;
     dir = parent;
@@ -244566,16 +244564,16 @@ function projectChain(cwd) {
   return chain;
 }
 function resolvePromptFiles(cwd, dataDir2) {
-  const override = readFile(join15(cwd, ".usable", "SYSTEM.md")) ?? readFile(join15(dataDir2, "SYSTEM.md"));
+  const override = readFile(join16(cwd, ".usable", "SYSTEM.md")) ?? readFile(join16(dataDir2, "SYSTEM.md"));
   const appends = [
-    readFile(join15(dataDir2, "SYSTEM.append.md")),
-    readFile(join15(cwd, ".usable", "SYSTEM.append.md"))
+    readFile(join16(dataDir2, "SYSTEM.append.md")),
+    readFile(join16(cwd, ".usable", "SYSTEM.append.md"))
   ].filter((s17) => Boolean(s17));
   const append = appends.length ? appends.join("\n\n") : void 0;
   const candidates = [];
-  for (const name14 of CONTEXT_FILE_NAMES) candidates.push(join15(dataDir2, name14));
+  for (const name14 of CONTEXT_FILE_NAMES) candidates.push(join16(dataDir2, name14));
   for (const dir of projectChain(cwd)) {
-    for (const name14 of CONTEXT_FILE_NAMES) candidates.push(join15(dir, name14));
+    for (const name14 of CONTEXT_FILE_NAMES) candidates.push(join16(dir, name14));
   }
   const seen = /* @__PURE__ */ new Set();
   const contextFiles = [];
@@ -245321,12 +245319,12 @@ var init_stdio2 = __esm({
 });
 
 // src/adapters/cli/mcp-servers.ts
-import { existsSync as existsSync10, readFileSync as readFileSync7 } from "node:fs";
-import { join as join16 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync8 } from "node:fs";
+import { join as join17 } from "node:path";
 function readConfig(path11) {
   try {
-    if (!existsSync10(path11)) return {};
-    const parsed = configSchema.safeParse(JSON.parse(readFileSync7(path11, "utf8")));
+    if (!existsSync11(path11)) return {};
+    const parsed = configSchema.safeParse(JSON.parse(readFileSync8(path11, "utf8")));
     if (!parsed.success || !parsed.data.mcpServers) return {};
     const out = {};
     for (const [name14, spec] of Object.entries(parsed.data.mcpServers)) out[name14] = { name: name14, ...spec };
@@ -245337,9 +245335,9 @@ function readConfig(path11) {
 }
 function loadMcpServerSpecs(cwd, dataDir2) {
   const merged = {
-    ...readConfig(join16(dataDir2, "mcp.json")),
-    ...readConfig(join16(cwd, ".mcp.json")),
-    ...readConfig(join16(cwd, ".usable", "mcp.json"))
+    ...readConfig(join17(dataDir2, "mcp.json")),
+    ...readConfig(join17(cwd, ".mcp.json")),
+    ...readConfig(join17(cwd, ".usable", "mcp.json"))
   };
   return Object.values(merged).filter((s17) => !s17.disabled && (s17.command || s17.url));
 }
@@ -245759,8 +245757,8 @@ var init_usable_api = __esm({
 });
 
 // src/adapters/cli/media-tools.ts
-import { writeFileSync as writeFileSync7 } from "node:fs";
-import { join as join17 } from "node:path";
+import { writeFileSync as writeFileSync8 } from "node:fs";
+import { join as join18 } from "node:path";
 function stamp() {
   return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 }
@@ -245800,8 +245798,8 @@ function buildMediaTools(opts) {
           const b64 = resp.data?.[0]?.b64_json;
           if (!b64) return { error: "no image returned" };
           const buf = Buffer.from(b64, "base64");
-          const file2 = join17(outDir ?? process.cwd(), `usable-image-${stamp()}.png`);
-          writeFileSync7(file2, buf);
+          const file2 = join18(outDir ?? process.cwd(), `usable-image-${stamp()}.png`);
+          writeFileSync8(file2, buf);
           return { path: file2, bytes: buf.length };
         } catch (err) {
           return { error: err.message || "image generation failed" };
@@ -245920,7 +245918,9 @@ Notes:
 
 ## Minimal example
 \`\`\`ts
-import { z } from 'zod'
+// Type-only import (erased at runtime) \u2014 keep the file dependency-free so it
+// loads anywhere. Use plain JSON-schema for \`parameters\`; a zod schema also
+// works, but only if your project actually has zod installed on disk.
 import type { ExtensionAPI } from '@/extensions/api'
 
 export default (pi: ExtensionAPI) => {
@@ -245928,7 +245928,7 @@ export default (pi: ExtensionAPI) => {
   pi.registerTool({
     name: 'word_count',
     description: 'Count the words in a string.',
-    parameters: z.object({ text: z.string() }),
+    parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
     async execute({ text }) {
       return { success: true, data: { words: String(text).trim().split(/\\s+/).filter(Boolean).length } }
     },
@@ -245953,20 +245953,113 @@ export default (pi: ExtensionAPI) => {
 }
 \`\`\`
 
-After creating it: \`/trust\` (project only) then \`/reload\` \u2014 or restart. Verify with \`/help\` (commands) and by asking the model to call your tool.`;
+## Verifying it loads
+- Run \`/verify-extension <name>\` \u2014 it transpiles + loads the file in isolation (via jiti) and reports syntax / load-time errors and what it registers. Do NOT run \`tsc\` on the file: path aliases (\`@/extensions/api\`) won't resolve standalone, and the \`@/extensions/api\` import is types-only (erased at runtime). \`/verify-extension\` is the supported check.
+- Then \`/trust\` (project only) + \`/reload\` \u2014 or restart. Confirm with \`/help\` (commands) and by asking the model to call your tool.`;
+  }
+});
+
+// src/adapters/cli/diff.ts
+function unifiedDiff(oldStr, newStr, opts = {}) {
+  if (oldStr === newStr) return "";
+  const context = opts.context ?? 3;
+  const maxLines = opts.maxLines ?? 80;
+  const a21 = oldStr === "" ? [] : oldStr.split("\n");
+  const b32 = newStr === "" ? [] : newStr.split("\n");
+  const n30 = a21.length;
+  const m33 = b32.length;
+  if (n30 * m33 > 4e6) return `(diff omitted \u2014 ${n30}\u2192${m33} lines too large to render)`;
+  const lcs = Array.from({ length: n30 + 1 }, () => new Array(m33 + 1).fill(0));
+  for (let i19 = n30 - 1; i19 >= 0; i19--) {
+    for (let j21 = m33 - 1; j21 >= 0; j21--) {
+      lcs[i19][j21] = a21[i19] === b32[j21] ? lcs[i19 + 1][j21 + 1] + 1 : Math.max(lcs[i19 + 1][j21], lcs[i19][j21 + 1]);
+    }
+  }
+  const ops = [];
+  let i18 = 0;
+  let j20 = 0;
+  while (i18 < n30 && j20 < m33) {
+    if (a21[i18] === b32[j20]) {
+      ops.push({ t: " ", line: a21[i18] });
+      i18++;
+      j20++;
+    } else if (lcs[i18 + 1][j20] >= lcs[i18][j20 + 1]) {
+      ops.push({ t: "-", line: a21[i18] });
+      i18++;
+    } else {
+      ops.push({ t: "+", line: b32[j20] });
+      j20++;
+    }
+  }
+  while (i18 < n30) ops.push({ t: "-", line: a21[i18++] });
+  while (j20 < m33) ops.push({ t: "+", line: b32[j20++] });
+  const keep = new Array(ops.length).fill(false);
+  ops.forEach((op2, idx) => {
+    if (op2.t === " ") return;
+    for (let k23 = Math.max(0, idx - context); k23 <= Math.min(ops.length - 1, idx + context); k23++) {
+      keep[k23] = true;
+    }
+  });
+  const out = [];
+  let oldNo = 1;
+  let newNo = 1;
+  let inHunk = false;
+  let hunk = [];
+  let hunkOldStart = 1;
+  let hunkNewStart = 1;
+  const flush = () => {
+    if (hunk.length) {
+      out.push(`@@ -${hunkOldStart} +${hunkNewStart} @@`);
+      out.push(...hunk);
+      hunk = [];
+    }
+    inHunk = false;
+  };
+  for (let idx = 0; idx < ops.length; idx++) {
+    const op2 = ops[idx];
+    if (keep[idx]) {
+      if (!inHunk) {
+        inHunk = true;
+        hunkOldStart = oldNo;
+        hunkNewStart = newNo;
+      }
+      hunk.push(`${op2.t}${op2.line}`);
+    } else if (inHunk) {
+      flush();
+    }
+    if (op2.t === " ") {
+      oldNo++;
+      newNo++;
+    } else if (op2.t === "-") {
+      oldNo++;
+    } else {
+      newNo++;
+    }
+  }
+  flush();
+  if (out.length > maxLines) {
+    const kept = out.slice(0, maxLines);
+    kept.push(`\u2026 (${out.length - maxLines} more diff lines)`);
+    return kept.join("\n");
+  }
+  return out.join("\n");
+}
+var init_diff = __esm({
+  "src/adapters/cli/diff.ts"() {
+    "use strict";
   }
 });
 
 // src/adapters/cli/tools.ts
 import { spawn as spawn6 } from "node:child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync10, readFileSync as readFileSync9, writeFileSync as writeFileSync9 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname as dirname15, isAbsolute as isAbsolute4, join as join18, relative as relative2, resolve as resolve6, sep as sep2 } from "node:path";
+import { dirname as dirname15, isAbsolute as isAbsolute4, join as join19, relative as relative2, resolve as resolve6, sep as sep2 } from "node:path";
 function truncate2(text2, label) {
   if (text2.length <= MAX_OUTPUT_CHARS) return text2;
-  const file2 = join18(tmpdir(), `usable-${label}-${Date.now()}.txt`);
+  const file2 = join19(tmpdir(), `usable-${label}-${Date.now()}.txt`);
   try {
-    writeFileSync8(file2, text2);
+    writeFileSync9(file2, text2);
   } catch {
   }
   return text2.slice(0, MAX_OUTPUT_CHARS) + `
@@ -246090,9 +246183,9 @@ function createLocalTools(opts = {}) {
       const guarded = guardPath(parsed.data.path);
       if (!guarded.ok) return { error: guarded.error };
       const path11 = guarded.path;
-      if (!existsSync11(path11)) return { error: `No such file: ${rel(path11)}` };
+      if (!existsSync12(path11)) return { error: `No such file: ${rel(path11)}` };
       try {
-        const lines = readFileSync8(path11, "utf8").split("\n");
+        const lines = readFileSync9(path11, "utf8").split("\n");
         const offset = Math.max(1, parsed.data.offset ?? 1);
         const limit = Math.max(1, parsed.data.limit ?? MAX_READ_LINES);
         const slice = lines.slice(offset - 1, offset - 1 + limit);
@@ -246124,10 +246217,14 @@ function createLocalTools(opts = {}) {
       const path11 = guarded.path;
       try {
         const dir = dirname15(path11);
-        if (!existsSync11(dir)) mkdirSync9(dir, { recursive: true });
-        writeFileSync8(path11, parsed.data.content);
+        const before = existsSync12(path11) ? readFileSync9(path11, "utf8") : "";
+        if (!existsSync12(dir)) mkdirSync10(dir, { recursive: true });
+        writeFileSync9(path11, parsed.data.content);
         readFiles.add(path11);
-        return `Wrote ${rel(path11)} (${parsed.data.content.length} bytes)`;
+        const verb = before ? "Overwrote" : "Wrote";
+        const diff = unifiedDiff(before, parsed.data.content, { maxLines: 60 });
+        return `${verb} ${rel(path11)} (${parsed.data.content.length} bytes)` + (diff ? `
+${diff}` : "");
       } catch (e14) {
         return { error: e14 instanceof Error ? e14.message : String(e14) };
       }
@@ -246157,11 +246254,12 @@ function createLocalTools(opts = {}) {
       const guarded = guardPath(parsed.data.path);
       if (!guarded.ok) return { error: guarded.error };
       const path11 = guarded.path;
-      if (!existsSync11(path11)) return { error: `No such file: ${rel(path11)}` };
+      if (!existsSync12(path11)) return { error: `No such file: ${rel(path11)}` };
       if (!readFiles.has(path11)) return { error: `Read ${rel(path11)} before editing it.` };
       const edits = parsed.data.edits;
       try {
-        let content = readFileSync8(path11, "utf8");
+        const original2 = readFileSync9(path11, "utf8");
+        let content = original2;
         for (const [i18, edit2] of edits.entries()) {
           const { oldText, newText } = edit2;
           let count2 = content.split(oldText).length - 1;
@@ -246179,8 +246277,10 @@ function createLocalTools(opts = {}) {
           if (count2 > 1) return { error: `edit ${i18 + 1}: oldText appears ${count2}\xD7 \u2014 add more context to make it unique` };
           content = content.replace(target, () => newText);
         }
-        writeFileSync8(path11, content);
-        return `Applied ${edits.length} edit(s) to ${rel(path11)}`;
+        writeFileSync9(path11, content);
+        const diff = unifiedDiff(original2, content, { maxLines: 60 });
+        return `Applied ${edits.length} edit(s) to ${rel(path11)}` + (diff ? `
+${diff}` : "");
       } catch (e14) {
         return { error: e14 instanceof Error ? e14.message : String(e14) };
       }
@@ -246331,6 +246431,7 @@ var init_tools = __esm({
     "use strict";
     init_zod();
     init_extension_authoring();
+    init_diff();
     MAX_READ_LINES = 2e3;
     MAX_OUTPUT_CHARS = 3e4;
     DEFAULT_BASH_TIMEOUT_S = 120;
@@ -261237,13 +261338,25 @@ async function launchTui(options2) {
         if (res.ok) {
           sys(
             `Scaffolded ${res.path}
-Edit it, then /trust (project extensions need it) and /reload to load it.`
+Edit it, then /verify-extension ${arg.trim()} to check it loads, /trust (project extensions need it) and /reload to load it.`
           );
         } else {
           sys(`Could not scaffold: ${res.error}`, "error");
         }
         return;
       }
+      case "verify-extension": {
+        if (!extensions) {
+          sys("No extension system available.", "error");
+          return;
+        }
+        if (!arg.trim()) {
+          sys("Usage: /verify-extension <name>", "error");
+          return;
+        }
+        sys(await extensions.verify(arg.trim()));
+        return;
+      }
       case "login":
         try {
           const res = await actions.login((m33) => sys(m33));
@@ -261387,6 +261500,7 @@ Edit it, then /trust (project extensions need it) and /reload to load it.`
     { name: "sessions", description: "list sessions for this project" },
     { name: "provider", description: "switch model provider" },
     { name: "new-extension", description: "scaffold a starter extension", argumentHint: "<name>" },
+    { name: "verify-extension", description: "check an extension loads", argumentHint: "<name>" },
     { name: "new", description: "start a fresh session" },
     { name: "clear", description: "clear the screen" },
     { name: "exit", description: "quit" },
@@ -261506,6 +261620,9 @@ Edit it, then /trust (project extensions need it) and /reload to load it.`
       tone: "info"
     });
   }
+  if (options2.updateNotice) {
+    push({ kind: "system", text: options2.updateNotice, tone: "info" });
+  }
   ui2.addChild(root);
   ui2.setFocus(root);
   ui2.start();
@@ -261539,6 +261656,7 @@ var init_tui2 = __esm({
       "/reasoning [lvl]   set reasoning effort (low|medium|high)",
       "/sessions          list sessions for this project",
       "/new-extension <n> scaffold a starter extension in .usable/extensions/",
+      "/verify-extension <n>  check an extension loads (no tsc needed)",
       "/new               start a fresh session",
       "/clear             clear the screen",
       "/exit, /quit       quit (or Ctrl-C twice)",
@@ -261573,8 +261691,8 @@ process.emitWarning = function patchedEmitWarning(warning, ...rest) {
 
 // src/cli/index.ts
 import { parseArgs } from "node:util";
-import { appendFileSync as appendFileSync4, existsSync as existsSync12 } from "node:fs";
-import { basename as basename10, dirname as dirname16, join as join19 } from "node:path";
+import { appendFileSync as appendFileSync4, existsSync as existsSync13 } from "node:fs";
+import { basename as basename10, dirname as dirname16, join as join20 } from "node:path";
 
 // src/lib/config.cli.ts
 init_zod();
@@ -262149,7 +262267,7 @@ init_tui_select();
 init_model_registry();
 
 // package.json
-var version = "1.147.0";
+var version = "1.148.0";
 
 // src/adapters/cli/model-catalog.ts
 init_codex_auth();
@@ -262356,17 +262474,16 @@ function normalizeExtensionName(name14) {
 }
 function template(id) {
   const cmd = id.replace(/-/g, "");
-  return `import { z } from 'zod'
-import type { ExtensionAPI } from '@/extensions/api'
+  return `import type { ExtensionAPI } from '@/extensions/api'
 
 // ${id} \u2014 a usable-chat harness extension.
-// Edit, then run /trust (project) + /reload to load it. /help lists commands.
+// Verify it loads with /verify-extension ${id}, then /trust (project) + /reload. /help lists commands.
 export default (pi: ExtensionAPI) => {
-  // A model-callable tool.
+  // A model-callable tool (plain JSON-schema params \u2014 no external deps).
   pi.registerTool({
     name: '${cmd}_echo',
     description: 'Echo back the given text (example tool from the ${id} extension).',
-    parameters: z.object({ text: z.string() }),
+    parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
     async execute({ text }) {
       return { success: true, data: { echo: String(text) } }
     },
@@ -262378,8 +262495,9 @@ export default (pi: ExtensionAPI) => {
     run: (arg, ctx) => ctx.ui.notify(\`${id}: \${arg || '(no arg)'}\`),
   })
 
-  // Lifecycle/model hooks + UI contributions (uncomment to use):
-  // pi.on('token_usage', (e, ctx) => ctx.ui.setStatus('tok', \`\${e.totalTokens ?? 0} tok\`))
+  // Live status-bar metrics (uncomment): token count + context % for this session.
+  // pi.on('token_usage', (e, ctx) => ctx.ui.setStatus('${cmd}-tok', \`\${e.totalTokens ?? 0} tok\`))
+  // pi.on('context', (e, ctx) => ctx.ui.setStatus('${cmd}-ctx', e.pct != null ? \`ctx \${Math.round(e.pct)}%\` : ''))
   // pi.on('error', (e, ctx) => ctx.ui.notify(\`error: \${e.message}\`, 'error'))
   // pi.setBanner(['  ${id}  ']) // replace the startup ASCII banner
 }
@@ -262589,6 +262707,45 @@ async function loadExtensions(opts) {
   }
   return { registry: registry2, untrustedProjectDir };
 }
+async function verifyExtension(cwd, name14) {
+  const id = name14.replace(/^\//, "").trim();
+  if (!id) return { ok: false, message: "usage: /verify-extension <name>" };
+  const candidates = [];
+  for (const base of [projectExtensionsDir(cwd), homeExtensionsDir()]) {
+    for (const e14 of ["ts", "js", "mjs"]) candidates.push(join9(base, `${id}.${e14}`));
+    for (const idx of ["index.ts", "index.js", "index.mjs"]) candidates.push(join9(base, id, idx));
+  }
+  const file2 = candidates.find((p28) => existsSync7(p28));
+  if (!file2) {
+    return {
+      ok: false,
+      message: `extension "${id}" not found in ./.usable/extensions or ~/.usable/extensions`
+    };
+  }
+  const jiti = createJiti(import.meta.url, { moduleCache: false, fsCache: false });
+  try {
+    const mod = await jiti.import(file2);
+    const fn4 = typeof mod === "function" ? mod : mod.default;
+    if (typeof fn4 !== "function") {
+      return {
+        ok: false,
+        message: `${basename2(file2)}: no default export \u2014 expected \`export default (pi) => { \u2026 }\``
+      };
+    }
+    const registry2 = createRegistry();
+    await fn4(recordingApi(registry2, id));
+    const hooks = registry2.toolCall.length + registry2.toolResult.length + registry2.text.length + registry2.turnStart.length + registry2.turnEnd.length + registry2.reasoning.length + registry2.stepStart.length + registry2.stepEnd.length + registry2.tokenUsage.length + registry2.context.length + registry2.error.length + registry2.autoCompaction.length + registry2.sessionStart.length + registry2.sessionNew.length + registry2.sessionSwitch.length;
+    return {
+      ok: true,
+      message: `\u2713 ${basename2(file2)} loads cleanly \u2014 ${registry2.tools.length} tool(s), ${registry2.commands.size} command(s), ${hooks} hook(s). Run /reload to activate.`
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      message: `\u2717 ${basename2(file2)} failed to load: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+}
 
 // src/extensions/runtime.ts
 init_esm();
@@ -262698,6 +262855,153 @@ function buildExtensions(registry2, opts) {
   };
 }
 
+// src/adapters/cli/update-check.ts
+import { spawn as nodeSpawn } from "node:child_process";
+import { existsSync as existsSync8, mkdirSync as mkdirSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join10 } from "node:path";
+var PKG_NAME = "@usabledev/usable-chat";
+var REGISTRY_URL = `https://registry.npmjs.org/${PKG_NAME}/latest`;
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var FETCH_TIMEOUT_MS = 3e3;
+function parseVersion(version4) {
+  const m33 = version4.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+  if (!m33) return void 0;
+  return { major: +m33[1], minor: +m33[2], patch: +m33[3], prerelease: m33[4] };
+}
+function compareVersions(a21, b32) {
+  const l13 = parseVersion(a21);
+  const r17 = parseVersion(b32);
+  if (!l13 || !r17) return void 0;
+  if (l13.major !== r17.major) return l13.major - r17.major;
+  if (l13.minor !== r17.minor) return l13.minor - r17.minor;
+  if (l13.patch !== r17.patch) return l13.patch - r17.patch;
+  if (l13.prerelease === r17.prerelease) return 0;
+  if (!l13.prerelease) return 1;
+  if (!r17.prerelease) return -1;
+  return l13.prerelease.localeCompare(r17.prerelease);
+}
+function isNewerVersion(candidate, current) {
+  const c21 = compareVersions(candidate, current);
+  return c21 !== void 0 ? c21 > 0 : candidate.trim() !== current.trim();
+}
+function updateCheckEnabled() {
+  if (process.env.USABLE_SKIP_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER) return false;
+  if (process.env.CI) return false;
+  if (process.env.E2E_ALLOW_TEST_SEAMS === "true") return false;
+  return true;
+}
+function statePath(dataDir2) {
+  return join10(dataDir2, "update-check.json");
+}
+function readState(dataDir2) {
+  const p28 = statePath(dataDir2);
+  if (!existsSync8(p28)) return null;
+  try {
+    const s17 = JSON.parse(readFileSync6(p28, "utf8"));
+    if (typeof s17.lastCheckAt === "number" && typeof s17.latestVersion === "string") {
+      return { lastCheckAt: s17.lastCheckAt, latestVersion: s17.latestVersion };
+    }
+  } catch {
+  }
+  return null;
+}
+function writeState(dataDir2, state2) {
+  try {
+    if (!existsSync8(dataDir2)) mkdirSync8(dataDir2, { recursive: true });
+    writeFileSync7(statePath(dataDir2), JSON.stringify(state2, null, 2), { mode: 384 });
+  } catch {
+  }
+}
+async function fetchLatestVersion(timeoutMs = FETCH_TIMEOUT_MS) {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) return null;
+    const json3 = await res.json();
+    return typeof json3.version === "string" ? json3.version : null;
+  } catch {
+    return null;
+  }
+}
+function formatUpdateNotice(current, latest) {
+  return `\u24D8 update available ${current} \u2192 ${latest} \xB7 run \`usable-chat update\``;
+}
+function getUpdateNotice(opts) {
+  if (!updateCheckEnabled()) return null;
+  const state2 = readState(opts.dataDir);
+  if (state2 && isNewerVersion(state2.latestVersion, opts.currentVersion)) {
+    return formatUpdateNotice(opts.currentVersion, state2.latestVersion);
+  }
+  return null;
+}
+async function maybeRefreshUpdateState(opts) {
+  if (!updateCheckEnabled()) return;
+  const now2 = opts.now ?? Date.now();
+  const state2 = readState(opts.dataDir);
+  if (state2 && now2 - state2.lastCheckAt < CHECK_INTERVAL_MS) return;
+  const latest = await fetchLatestVersion();
+  writeState(opts.dataDir, {
+    lastCheckAt: now2,
+    latestVersion: latest ?? state2?.latestVersion ?? "0.0.0"
+  });
+}
+function refreshUpdateStateInBackground(opts) {
+  void maybeRefreshUpdateState(opts).catch(() => {
+  });
+}
+function detectInstall(entry = process.argv[1] ?? "") {
+  const p28 = entry.replace(/\\/g, "/");
+  if (p28.includes("/_npx/")) return "npx";
+  if (process.env.npm_config_global === "true") return "global";
+  if (p28.includes("/lib/node_modules/") || p28.includes("/pnpm/global/") || p28.includes("/pnpm-global/"))
+    return "global";
+  if (p28.includes("/node_modules/")) return "local";
+  return "unknown";
+}
+async function runUpdateCommand(opts) {
+  const kind = opts?.kind ?? detectInstall(opts?.entry);
+  const out = (s17) => process.stdout.write(s17 + "\n");
+  const err = (s17) => process.stderr.write(s17 + "\n");
+  if (kind === "npx") {
+    out("You're running via npx, which already fetches the latest on each run.");
+    out(`To force the newest explicitly:  npx ${PKG_NAME}@latest`);
+    return 0;
+  }
+  const usePnpm = (opts?.entry ?? process.argv[1] ?? "").replace(/\\/g, "/").includes("/pnpm");
+  const cmd = usePnpm ? "pnpm" : "npm";
+  const args = usePnpm ? ["add", "-g", `${PKG_NAME}@latest`] : ["install", "-g", `${PKG_NAME}@latest`];
+  out(`\u21BB installing ${PKG_NAME}@latest  (${cmd} ${args.join(" ")}) \u2026`);
+  const spawn7 = opts?.spawnFn ?? nodeSpawn;
+  return await new Promise((resolve7) => {
+    let settled = false;
+    const done = (code) => {
+      if (!settled) {
+        settled = true;
+        resolve7(code);
+      }
+    };
+    const child = spawn7(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    child.on("error", (e14) => {
+      if (e14.code === "EACCES" || e14.code === "EPERM") {
+        err(`\u2717 permission denied. Try:  sudo ${cmd} ${args.join(" ")}`);
+      } else if (e14.code === "ENOENT") {
+        err(`\u2717 \`${cmd}\` not found. Install it, or run:  npm install -g ${PKG_NAME}@latest`);
+      } else {
+        err(`\u2717 update failed: ${e14.message}
+  Run manually:  ${cmd} ${args.join(" ")}`);
+      }
+      done(1);
+    });
+    child.on("exit", (code) => {
+      if (code === 0) out(`\u2713 updated \u2014 restart usable-chat to use the new version.`);
+      else err(`\u2717 ${cmd} exited with code ${code ?? 1}`);
+      done(code ?? 1);
+    });
+  });
+}
+
 // src/cli/index.ts
 function usableCompletionsUrl(cfg) {
   const host = (cfg.ai.usableApiHost || "https://chat.usable.dev").replace(/\/+$/, "").replace(/\/api\/v1$/, "");
@@ -262756,7 +263060,7 @@ function userIdFromToken(token) {
 function resolveGitRoot(start) {
   let dir = start;
   while (true) {
-    if (existsSync12(join19(dir, ".git"))) return dir;
+    if (existsSync13(join20(dir, ".git"))) return dir;
     const parent = dirname16(dir);
     if (parent === dir) return start;
     dir = parent;
@@ -262775,6 +263079,7 @@ function printUsage() {
       '  usable-chat -c -p "<prompt>"         Continue the latest session for this project',
       '  usable-chat --resume <id> -p "..."   Resume a specific session',
       "  usable-chat sessions                 List sessions for this project",
+      "  usable-chat update                   Update to the latest version (npm i -g)",
       "",
       "Auth & keys:",
       "  usable-chat login                            Usable/MCP token (Keycloak)",
@@ -262893,7 +263198,7 @@ function readScriptedLlm() {
 }
 async function runTui(cfg, store, projectId, values2) {
   applyEnv(cfg);
-  silenceConsole(join19(cfg.paths.dataDir, "usable.log"));
+  silenceConsole(join20(cfg.paths.dataDir, "usable.log"));
   let session = await loadSession(cfg);
   let model = values2.model ?? cfg.ai.defaultModel;
   let reasoning = cfg.ai.reasoningEffort;
@@ -262922,7 +263227,7 @@ async function runTui(cfg, store, projectId, values2) {
   const scriptedLlm = readScriptedLlm();
   const { runCliTurn: runCliTurn2 } = await Promise.resolve().then(() => (init_run(), run_exports));
   const { launchTui: launchTui2 } = await Promise.resolve().then(() => (init_tui2(), tui_exports));
-  const extLogFile = join19(cfg.paths.dataDir, "usable.log");
+  const extLogFile = join20(cfg.paths.dataDir, "usable.log");
   const extLog = (m33) => {
     try {
       appendFileSync4(extLogFile, `[ext] ${m33}
@@ -263025,6 +263330,11 @@ async function runTui(cfg, store, projectId, values2) {
     kind: m33.role === "assistant" ? "assistant" : "user",
     text: typeof m33.content === "string" ? m33.content : JSON.stringify(m33.content)
   }));
+  const updateNotice = getUpdateNotice({
+    currentVersion: version,
+    dataDir: cfg.paths.dataDir
+  });
+  refreshUpdateStateInBackground({ dataDir: cfg.paths.dataDir });
   await launchTui2({
     runTurn,
     actions,
@@ -263032,6 +263342,7 @@ async function runTui(cfg, store, projectId, values2) {
     loggedIn: Boolean(session.user?.accessToken),
     user: session.user?.id,
     version,
+    updateNotice: updateNotice ?? void 0,
     extensions: {
       hasCommand: (n30) => ext2.current.hasCommand(n30),
       runCommand: (n30, a21) => ext2.current.runCommand(n30, a21),
@@ -263044,6 +263355,7 @@ async function runTui(cfg, store, projectId, values2) {
         clearSkillCache2();
         await ext2.reload();
       },
+      verify: (name14) => verifyExtension(process.cwd(), name14).then((r17) => r17.message),
       trust: () => ext2.trust(),
       bindNotify: (fn4) => {
         extUi.notify = fn4;
@@ -263085,6 +263397,9 @@ async function main() {
   if (positionals[0] === "config") {
     return runConfigCommand(cfg.paths.configFile, positionals.slice(1));
   }
+  if (positionals[0] === "update") {
+    return runUpdateCommand();
+  }
   const store = new CliStore(cfg.paths.dbFile);
   const gitRoot2 = resolveGitRoot(process.cwd());
   const projectId = store.resolveProject(gitRoot2, basename10(gitRoot2));
@@ -263196,6 +263511,14 @@ async function main() {
       message: { role: "assistant", content: result.text }
     });
   }
+  await maybeRefreshUpdateState({ dataDir: cfg.paths.dataDir });
+  const updateNotice = getUpdateNotice({
+    currentVersion: version,
+    dataDir: cfg.paths.dataDir
+  });
+  if (updateNotice) process.stderr.write(`
+${updateNotice}
+`);
   store.close();
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usabledev/usable-chat",
-  "version": "1.147.0",
+  "version": "1.148.0",
   "description": "usable-chat — terminal harness for usable-chat (headless + TUI)",
   "type": "module",
   "bin": {