@arbidocs/tui 0.3.66 → 0.3.68

package/dist/index.js

@@ -8,6 +8,10 @@ var chalk = require('chalk');
 require('fake-indexeddb/auto');
 var client = require('@arbidocs/client');
 var prompts = require('@inquirer/prompts');
+var child_process = require('child_process');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -213,18 +217,39 @@ var RightAlignedText = class {
     return [" ".repeat(padding) + styled];
   }
 };
+var GLYPH_LIFECYCLE = ">";
+var GLYPH_TOOL = "\u25B8";
+var GLYPH_RESULT = "\u2192";
 var AgentStep = class extends piTui.Text {
   completed = false;
-  constructor(focus) {
-    const styled = `${colors.stepPending(">")} ${colors.muted(focus)}`;
-    super(styled, 2, 0);
+  constructor(label, details) {
+    super(buildText(label, details), 2, 0);
   }
-  /** Mark this step as completed. */
+  /** Mark this step as completed. Renderer is unchanged for now —
+   *  see the file-header comment for the planned focusable-collapse
+   *  upgrade path. */
   complete() {
     if (this.completed) return;
     this.completed = true;
   }
 };
+function buildText(label, details) {
+  const hasDetails = !!(details?.tool || details?.args || details?.result);
+  const glyph = hasDetails ? GLYPH_TOOL : GLYPH_LIFECYCLE;
+  const header = `${colors.stepPending(glyph)} ${hasDetails ? colors.accent(label) : colors.muted(label)}`;
+  if (!hasDetails) return header;
+  const lines = [header];
+  if (details?.tool && details.tool !== label) {
+    lines.push(`  ${colors.muted("tool:")} ${details.tool}`);
+  }
+  if (details?.args) {
+    lines.push(`  ${colors.muted("args:")} ${details.args}`);
+  }
+  if (details?.result) {
+    lines.push(`  ${colors.muted(GLYPH_RESULT)} ${details.result}`);
+  }
+  return lines.join("\n");
+}
 
 // src/components/chat-log.ts
 var ChatLog = class extends piTui.Container {
@@ -282,10 +307,14 @@ var ChatLog = class extends piTui.Container {
   updateAssistant(text) {
     this.activeAssistant?.setText(text);
   }
-  /** Add an agent step to the current streaming run. */
-  addAgentStep(focus) {
+  /** Add an agent step to the current streaming run. Optional
+   *  ``details`` enriches the rendered block with ``tool`` / ``args``
+   *  / ``result`` lines beneath the header — claude-code-style
+   *  tool-use expansion. Callers that don't have structured detail
+   *  can omit the second arg and get the original flat behaviour. */
+  addAgentStep(label, details) {
     if (!this.activeAssistant) return;
-    const step = new AgentStep(focus);
+    const step = new AgentStep(label, details);
     this.activeSteps.push(step);
     this.addChild(step);
   }
@@ -303,6 +332,107 @@ var ChatLog = class extends piTui.Container {
     this.addChild(new piTui.Spacer(1));
   }
 };
+
+// src/event-log.ts
+var WsEventLog = class {
+  entries = [];
+  capacity;
+  /** ``capacity`` defaults to 200, the same order-of-magnitude as
+   *  a typical long chat session. Old entries roll off when the
+   *  buffer fills — same shape as openclaw's session log. */
+  constructor(capacity = 200) {
+    this.capacity = capacity;
+  }
+  /** Append a new entry. Drops the oldest if at capacity. */
+  add(entry) {
+    this.entries.push({
+      at: entry.at ?? /* @__PURE__ */ new Date(),
+      text: entry.text,
+      level: entry.level,
+      msgType: entry.msgType
+    });
+    while (this.entries.length > this.capacity) this.entries.shift();
+  }
+  /** Read the last ``limit`` entries (most recent last). Optionally
+   *  filter by level — useful for ``/events --errors``. */
+  getAll(options) {
+    let view = this.entries;
+    if (options?.level) view = view.filter((e) => e.level === options.level);
+    if (options?.limit != null) view = view.slice(-options.limit);
+    return view;
+  }
+  /** Number of entries currently retained (after eviction). */
+  get size() {
+    return this.entries.length;
+  }
+};
+function formatEventLine(entry) {
+  const h = String(entry.at.getHours()).padStart(2, "0");
+  const m = String(entry.at.getMinutes()).padStart(2, "0");
+  const s = String(entry.at.getSeconds()).padStart(2, "0");
+  const tag = entry.level.padEnd(7);
+  return `[${h}:${m}:${s}] ${tag} ${entry.text}`;
+}
+var SourcesIndex = class {
+  // Keyed by docId so successive turns add to the same entry rather
+  // than duplicating it.
+  entries = /* @__PURE__ */ new Map();
+  /** Fold every citation in ``metadata`` into the index. Idempotent
+   *  on the same payload — adding the same metadata twice doesn't
+   *  inflate counts. */
+  recordCitations(metadata) {
+    if (!metadata) return;
+    this.recordResolved(sdk.resolveCitations(metadata));
+  }
+  /** The underlying fold step, separated so tests can drive it with
+   *  hand-rolled ``ResolvedCitation`` fixtures rather than mocking
+   *  the full ``MessageMetadataPayload.tools.*`` graph that
+   *  ``resolveCitations`` traverses. */
+  recordResolved(resolved) {
+    for (const c of resolved) {
+      for (const chunk of c.chunks) {
+        const docId = chunk.metadata?.doc_ext_id;
+        if (!docId) continue;
+        const title = chunk.metadata?.doc_title ?? docId;
+        const page = chunk.metadata?.page_number;
+        const existing = this.entries.get(docId);
+        if (existing) {
+          if (typeof page === "number" && !existing.pages.includes(page)) {
+            existing.pages.push(page);
+            existing.pages.sort((a, b) => a - b);
+          }
+          if (!existing.citationNums.includes(c.citationNum)) {
+            existing.citationNums.push(c.citationNum);
+            existing.citationNums.sort();
+          }
+          if (existing.title === docId && title !== docId) existing.title = title;
+        } else {
+          this.entries.set(docId, {
+            docId,
+            title,
+            pages: typeof page === "number" ? [page] : [],
+            citationNums: [c.citationNum]
+          });
+        }
+      }
+    }
+  }
+  /** All entries in registration order — first-cited first. The
+   *  iterator order of ``Map`` is insertion order, which is what
+   *  we want for ``/sources`` (oldest at top, newest at bottom). */
+  list() {
+    return Array.from(this.entries.values());
+  }
+  /** Clear the index. Wired to ``/new`` so a fresh conversation
+   *  starts with no inherited sources. */
+  clear() {
+    this.entries.clear();
+  }
+  /** Number of unique documents tracked. */
+  get size() {
+    return this.entries.size;
+  }
+};
 var ArbiEditor = class extends piTui.Editor {
   /** Callback when Escape is pressed (abort streaming). */
   onEscape;
@@ -314,8 +444,31 @@ var ArbiEditor = class extends piTui.Editor {
   onCtrlW;
   /** Callback when Ctrl+N is pressed (new conversation). */
   onCtrlN;
+  /** Callback when Alt+1..9 is pressed (jump to citation N from
+   *  the last response). The handler gets the integer ``1`` through
+   *  ``9``; it is responsible for checking whether that citation
+   *  exists and surfacing a useful message if not. */
+  onCitationKey;
+  /**
+   * Callback fired after every keystroke that mutates the buffer.
+   *
+   * The TUI uses this to power the **pre-flight skill hint**: when
+   * the user types ``/<slug>`` we surface the skill's description in
+   * the chat log so they see what they're about to invoke before
+   * pressing Enter. The handler is responsible for its own
+   * deduplication (e.g. only show the hint when the parsed slug
+   * changes), since this callback fires on *every* mutating key.
+   *
+   * Receives the buffer text *after* the base ``handleInput`` has
+   * applied the change. Read-only — handlers must not mutate the
+   * editor synchronously or it'll loop.
+   */
+  onBufferChange;
   /** Track Ctrl+C presses for double-tap exit. */
   lastCtrlCTime = 0;
+  /** Snapshot of the last text we emitted, so we don't fire on
+   *  non-mutating keys (cursor moves, redraws). */
+  lastEmittedText = "";
   constructor(tui) {
     super(tui, editorTheme, { paddingX: 1 });
   }
@@ -349,7 +502,25 @@ var ArbiEditor = class extends piTui.Editor {
       this.onCtrlN?.();
       return;
     }
+    if (this.onCitationKey) {
+      for (let n = 1; n <= 9; n++) {
+        if (piTui.matchesKey(data, piTui.Key.alt(String(n)))) {
+          this.onCitationKey(n);
+          return;
+        }
+      }
+    }
     super.handleInput(data);
+    if (this.onBufferChange) {
+      const current = this.getText();
+      if (current !== this.lastEmittedText) {
+        this.lastEmittedText = current;
+        try {
+          this.onBufferChange(current);
+        } catch {
+        }
+      }
+    }
   }
 };
 var LEVEL_STYLE = {
@@ -407,6 +578,7 @@ var ToastContainer = class extends piTui.Container {
 // src/command-registry.ts
 init_tui_helpers();
 var registry = /* @__PURE__ */ new Map();
+var KNOWN_SERVER_COMMANDS = /* @__PURE__ */ new Set(["pa", "setup", "cold-start"]);
 function registerCommand(def) {
   registry.set(def.name, def);
 }
@@ -423,6 +595,15 @@ function toSlashCommands() {
   }
   return cmds;
 }
+function toSlashCommandsWithSkills(skills) {
+  const out = toSlashCommands();
+  const taken = new Set(out.map((c) => c.name));
+  for (const s of skills) {
+    if (taken.has(s.slug)) continue;
+    out.push({ name: s.slug, description: s.description });
+  }
+  return out;
+}
 function formatHelpText() {
   const lines = [];
   for (const def of registry.values()) {
@@ -440,21 +621,36 @@ function formatHelpText() {
     "  @arbi  \u2014 Switch back to AI chat",
     "",
     "Keyboard shortcuts:",
-    "  Ctrl+N \u2014 New conversation",
-    "  Ctrl+W \u2014 Switch workspace",
-    "  Ctrl+D \u2014 Exit",
-    "  Escape \u2014 Abort streaming"
+    "  Ctrl+N    \u2014 New conversation",
+    "  Ctrl+W    \u2014 Switch workspace",
+    "  Ctrl+D    \u2014 Exit",
+    "  Escape    \u2014 Abort streaming",
+    "  Alt+1..9  \u2014 Jump to citation N from the last response",
+    "",
+    "Skills: any workspace SKILL.md with `user-invocable: true` becomes a",
+    "  ``/<slug>`` command \u2014 type it like a regular slash command and the",
+    "  agent handles it. ``/skills`` lists what is available."
   ].join("\n");
 }
 async function dispatchCommand(tui, input2) {
+  const parsed = sdk.parseSlashCommand(input2);
+  if (!parsed) return false;
+  const cmdName = parsed.slug;
+  const args = parsed.args.length > 0 ? parsed.args.split(/\s+/) : [];
   const trimmed = input2.trim();
-  if (!trimmed.startsWith("/")) return false;
-  const parts = trimmed.slice(1).split(/\s+/);
-  const cmdName = parts[0]?.toLowerCase();
-  const args = parts.slice(1);
-  if (!cmdName) return false;
   const def = registry.get(cmdName);
   if (!def) {
+    const skill = tui.skillsCache?.find(
+      (s) => s.slug === cmdName || s.name.toLowerCase() === cmdName
+    );
+    if (skill) {
+      const meta = skill.arg_hint ? `Skill: ${skill.name} ${skill.arg_hint} \u2014 ${skill.description}` : `Skill: ${skill.name} \u2014 ${skill.description}`;
+      showMessage(tui, meta, "info");
+      return false;
+    }
+    if (KNOWN_SERVER_COMMANDS.has(cmdName)) {
+      return false;
+    }
     showMessage(tui, `Unknown command: /${cmdName}. Type /help for available commands.`, "warning");
     return true;
   }
@@ -548,6 +744,7 @@ var generalCommands = [
       const { tui } = ctx;
       tui.state.conversationMessageId = null;
       tui.lastMetadata = null;
+      tui.sourcesIndex.clear();
       tui.store.clearChatSession();
       return "Started new conversation.";
     }
@@ -1336,6 +1533,387 @@ var citationCommands = [
   }
 ];
 
+// src/commands/events.ts
+var DEFAULT_LIMIT = 20;
+function parseEventsArg(arg) {
+  if (!arg) return { limit: DEFAULT_LIMIT };
+  const lower = arg.trim().toLowerCase();
+  if (lower === "all") return {};
+  if (lower === "errors" || lower === "error") {
+    return { limit: DEFAULT_LIMIT, level: "error" };
+  }
+  if (lower === "warnings" || lower === "warning") {
+    return { limit: DEFAULT_LIMIT, level: "warning" };
+  }
+  const n = Number.parseInt(lower, 10);
+  if (Number.isFinite(n) && n > 0) return { limit: n };
+  return { limit: DEFAULT_LIMIT };
+}
+var eventCommands = [
+  {
+    name: "events",
+    description: "Show recent WebSocket events (replaces toasts that scroll off)",
+    argHint: "count|all|errors",
+    requires: "none",
+    run: (ctx) => {
+      const { tui, args } = ctx;
+      const query = parseEventsArg(args[0]);
+      const entries = tui.eventLog.getAll(query);
+      if (entries.length === 0) {
+        if (query.level) {
+          return `No ${query.level} events recorded yet.`;
+        }
+        return "No WebSocket events recorded yet.";
+      }
+      const lines = entries.map((e) => {
+        const line = formatEventLine(e);
+        switch (e.level) {
+          case "error":
+            return colors.error(line);
+          case "warning":
+            return colors.warning(line);
+          case "success":
+            return colors.success(line);
+          default:
+            return colors.muted(line);
+        }
+      });
+      const header = query.level != null ? `Events (${entries.length}, level=${query.level}):` : `Events (${entries.length} of ${tui.eventLog.size} retained):`;
+      return [header, "", ...lines];
+    }
+  }
+];
+var MAX_CHARS_PER_PAGE = 2e3;
+function splitIntoPages(content) {
+  if (!content) return [];
+  const trimmed = content.trim();
+  if (!trimmed) return [];
+  if (trimmed.includes("\n---\n")) {
+    return trimmed.split(/\n---\n/).map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  if (trimmed.includes("\f")) {
+    return trimmed.split("\f").map((p) => p.trim()).filter((p) => p.length > 0);
+  }
+  return [trimmed];
+}
+function indexCitationsByPage(docId, citations) {
+  const byPage = /* @__PURE__ */ new Map();
+  for (const c of citations) {
+    for (const chunk of c.chunks) {
+      if (chunk.metadata?.doc_ext_id !== docId) continue;
+      const page = chunk.metadata?.page_number ?? 1;
+      const list = byPage.get(page) ?? [];
+      if (!list.includes(c.citationNum)) list.push(c.citationNum);
+      byPage.set(page, list);
+    }
+  }
+  return byPage;
+}
+function renderDocView(opts) {
+  const { docId, title, fileName, pages, citationsByPage } = opts;
+  const totalCitations = Array.from(citationsByPage.values()).reduce((n, ids) => n + ids.length, 0);
+  const lines = [];
+  lines.push(colors.textBold(title));
+  if (fileName && fileName !== title) lines.push(colors.muted(fileName));
+  lines.push(colors.muted(`${docId} \u2014 ${pages.length} page${pages.length === 1 ? "" : "s"}`));
+  if (totalCitations > 0) {
+    lines.push(
+      colors.muted(
+        `${totalCitations} citation${totalCitations === 1 ? "" : "s"} from the current conversation`
+      )
+    );
+  }
+  lines.push("");
+  for (let i = 0; i < pages.length; i++) {
+    const pageNum = i + 1;
+    const cites = citationsByPage.get(pageNum);
+    const citeBadge = cites && cites.length > 0 ? colors.accent(` [${cites.map((n) => `[${n}]`).join(" ")}]`) : "";
+    lines.push(colors.accentBold(`\u2500\u2500 page ${pageNum} \u2500\u2500`) + citeBadge);
+    const body = pages[i];
+    if (body.length > MAX_CHARS_PER_PAGE) {
+      lines.push(body.slice(0, MAX_CHARS_PER_PAGE));
+      lines.push(
+        colors.muted(
+          `\u2026 (${body.length - MAX_CHARS_PER_PAGE} more chars \u2014 use /parsed ${docId} for the raw stream)`
+        )
+      );
+    } else {
+      lines.push(body);
+    }
+    lines.push("");
+  }
+  return lines;
+}
+var viewCommands = [
+  {
+    name: "view",
+    description: "Read a document in the chat log, with citation hints per page",
+    argHint: "doc-id",
+    minArgs: 1,
+    requires: "workspace",
+    run: async (ctx) => {
+      const { args, arbi, authHeaders, tui } = ctx;
+      const docId = args[0].trim();
+      const [docs, parsed] = await Promise.all([
+        sdk.documents.getDocuments(arbi, [docId]),
+        sdk.documents.getParsedContent(authHeaders, docId, "content")
+      ]);
+      const doc = docs[0];
+      if (!doc) return `Document ${docId} not found.`;
+      const meta = doc.doc_metadata;
+      const title = meta?.title ?? doc.file_name ?? docId;
+      const content = parsed.content ?? "";
+      if (!content) return `No parsed content available for ${docId}.`;
+      const pages = splitIntoPages(content);
+      const citationsByPage = tui.lastMetadata ? indexCitationsByPage(docId, sdk.resolveCitations(tui.lastMetadata)) : /* @__PURE__ */ new Map();
+      return renderDocView({
+        docId,
+        title,
+        fileName: doc.file_name ?? null,
+        pages,
+        citationsByPage
+      });
+    }
+  }
+];
+
+// src/commands/sources.ts
+function renderSourcesList(entries) {
+  if (entries.length === 0) {
+    return "No sources cited yet in this conversation. Ask a question first.";
+  }
+  const lines = [`Sources in this conversation (${entries.length}):`, ""];
+  for (const e of entries) {
+    const cites = e.citationNums.map((n) => `[${n}]`).join(" ");
+    const pages = e.pages.length > 0 ? ` p.${e.pages.join(", p.")}` : "";
+    lines.push(`  ${colors.accent(cites)} ${colors.textBold(e.title)}${pages}`);
+    lines.push(`      ${colors.muted(e.docId)}`);
+  }
+  lines.push("");
+  lines.push(
+    colors.muted("Use /view <doc-id> to read a source, or /cite N for a specific passage.")
+  );
+  return lines;
+}
+var sourcesCommands = [
+  {
+    name: "sources",
+    description: "List documents cited in this conversation",
+    requires: "none",
+    run: (ctx) => {
+      const { tui } = ctx;
+      return renderSourcesList(tui.sourcesIndex.list());
+    }
+  }
+];
+var DEFAULT_LIMIT2 = 10;
+function formatHistoryLine(row) {
+  const title = row.title?.trim() || colors.muted("(untitled)");
+  const count = typeof row.message_count === "number" ? ` \xB7 ${row.message_count} msg` : "";
+  const when = row.updated_at ? ` \xB7 ${formatRelativeTime(row.updated_at)}` : "";
+  return `  ${colors.accent(row.external_id)}  ${title}${colors.muted(count + when)}`;
+}
+function formatRelativeTime(iso, now = /* @__PURE__ */ new Date()) {
+  const t = new Date(iso);
+  if (Number.isNaN(t.getTime())) return iso;
+  const seconds = Math.floor((now.getTime() - t.getTime()) / 1e3);
+  if (seconds < 60) return "just now";
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ago`;
+  if (seconds < 86400 * 2) return "yesterday";
+  if (seconds < 86400 * 7) return `${Math.floor(seconds / 86400)}d ago`;
+  return t.toLocaleDateString(void 0, { month: "short", day: "numeric" });
+}
+var historyCommands = [
+  {
+    name: "history",
+    description: "Browse past conversations",
+    argHint: "count|all",
+    requires: "workspace",
+    run: async (ctx) => {
+      const { arbi, args } = ctx;
+      const arg = args[0]?.trim().toLowerCase();
+      const convs = await sdk.conversations.listConversations(arbi);
+      if (convs.length === 0) {
+        return "No conversations yet in this workspace. Ask a question to start one.";
+      }
+      const slice = arg === "all" ? convs : convs.slice(0, parseLimit(arg) ?? DEFAULT_LIMIT2);
+      const lines = [
+        `Conversations (${slice.length}${slice.length < convs.length ? ` of ${convs.length}` : ""}):`,
+        ""
+      ];
+      for (const row of slice) lines.push(formatHistoryLine(row));
+      lines.push("");
+      lines.push(colors.muted("Use /resume <conv-id> to switch to one of these."));
+      return lines;
+    }
+  },
+  {
+    name: "resume",
+    description: "Switch to a past conversation by ID",
+    argHint: "conv-id",
+    minArgs: 1,
+    requires: "workspace",
+    run: async (ctx) => {
+      const { args, arbi, tui } = ctx;
+      const convId = args[0].trim();
+      const data = await sdk.conversations.getConversationThreads(arbi, convId);
+      const threadList = data.threads ?? [];
+      const primary = threadList[0];
+      if (!primary?.leaf_message_ext_id) {
+        return `Conversation ${convId} not found or has no messages.`;
+      }
+      tui.chatLog.clearMessages();
+      for (const msg of primary.history ?? []) {
+        if (msg.role === "user") tui.chatLog.addUser(msg.content);
+        else if (msg.role === "assistant") tui.chatLog.addAssistant(msg.content);
+      }
+      tui.chatLog.addSystem(`--- resumed conversation ${convId} ---`, "info");
+      tui.state.conversationMessageId = primary.leaf_message_ext_id;
+      tui.store.updateChatSession({
+        lastMessageExtId: primary.leaf_message_ext_id,
+        conversationExtId: convId
+      });
+      tui.sourcesIndex.clear();
+      tui.lastMetadata = null;
+      tui.requestRender();
+      return `Resumed conversation ${convId}.`;
+    }
+  }
+];
+function parseLimit(arg) {
+  if (!arg) return void 0;
+  const n = Number.parseInt(arg, 10);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+init_tui_helpers();
+var skillCommands = [
+  {
+    name: "skills",
+    description: "List user-invocable skills in the active workspace",
+    requires: "workspace",
+    run: async (ctx) => {
+      const { arbi, tui } = ctx;
+      const list = await sdk.assistant.listSkills(arbi);
+      tui.skillsCache = list;
+      if (list.length === 0) {
+        return [
+          "No skills in this workspace yet.",
+          colors.muted(
+            "Skills are documents with wp_type=skill. Upload a SKILL.md with frontmatter (name, description, user-invocable: true) to add one."
+          )
+        ];
+      }
+      const lines = [`Skills (${list.length}):`, ""];
+      for (const s of list) {
+        const argHint = s.arg_hint ? colors.muted(` ${s.arg_hint}`) : "";
+        const typeBadge = s.skill_type && s.skill_type !== "markdown" ? colors.muted(` [${s.skill_type}]`) : "";
+        lines.push(`  ${colors.accent("/" + s.slug)}${argHint}${typeBadge}`);
+        if (s.description) {
+          lines.push(`      ${colors.muted(s.description)}`);
+        }
+      }
+      lines.push("");
+      lines.push(
+        colors.muted("Use /skill view <slug> to read a skill, /skill source <slug> for its doc-id.")
+      );
+      return lines;
+    }
+  },
+  {
+    name: "skill",
+    description: "Inspect or edit a skill (view | source | edit) <slug>",
+    argHint: "subcommand slug",
+    minArgs: 2,
+    requires: "workspace",
+    run: async (ctx) => {
+      const { args, arbi, tui } = ctx;
+      const [sub, slug, ...rest] = args;
+      if (sub !== "view" && sub !== "source" && sub !== "edit") {
+        return `Unknown /skill subcommand "${sub}". Use /skill view <slug>, /skill source <slug>, or /skill edit <slug>.`;
+      }
+      const list = tui.skillsCache?.length ? tui.skillsCache : await sdk.assistant.listSkills(arbi, { includeHidden: true });
+      const skill = list.find((s) => s.slug === slug || s.name === slug);
+      if (!skill) {
+        return `No skill matching "${slug}" in this workspace. Use /skills to list available skills.`;
+      }
+      if (sub === "source") {
+        return [
+          colors.textBold(`${skill.name} (${skill.slug})`),
+          colors.muted(`doc-id: ${skill.doc_ext_id}`),
+          colors.muted(`workspace: ${skill.workspace_ext_id}`),
+          colors.muted(
+            "Use `arbi upload --folder skills/<slug>` to replace the SKILL.md, or edit it via the web app."
+          )
+        ];
+      }
+      const { authHeaders } = ctx;
+      if (sub === "edit") {
+        return await editSkill(tui, authHeaders, skill);
+      }
+      const dlRes = await sdk.documents.downloadDocument(authHeaders, skill.doc_ext_id);
+      const body = dlRes.ok ? await dlRes.text() : "";
+      const lines = [colors.textBold(`${skill.name} (${skill.slug})`)];
+      if (skill.description) lines.push(colors.muted(skill.description));
+      if (skill.arg_hint) lines.push(colors.muted(`args: ${skill.arg_hint}`));
+      lines.push(colors.muted(`type: ${skill.skill_type}  doc: ${skill.doc_ext_id}`));
+      lines.push("");
+      lines.push(body);
+      return lines;
+    }
+  }
+];
+async function editSkill(tui, authHeaders, skill) {
+  const dlRes = await sdk.documents.downloadDocument(authHeaders, skill.doc_ext_id);
+  if (!dlRes.ok) {
+    return `Failed to fetch skill body (HTTP ${dlRes.status}). Edit aborted.`;
+  }
+  const original = await dlRes.text();
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `arbi-skill-${skill.slug}-`));
+  const path$1 = path.join(dir, "SKILL.md");
+  fs.writeFileSync(path$1, original, "utf8");
+  const mtimeBefore = fs.statSync(path$1).mtimeMs;
+  const editor = process.env.VISUAL || process.env.EDITOR || "vi";
+  const result = await runInteractiveFlow(
+    tui,
+    colors.muted(`Opening ${skill.slug}/SKILL.md in ${editor}\u2026`),
+    async () => {
+      const child = child_process.spawnSync(editor, [path$1], { stdio: "inherit" });
+      if (child.error) throw child.error;
+      if (child.status !== 0 && child.status !== null) {
+        throw new Error(`${editor} exited with status ${child.status}`);
+      }
+      return fs.readFileSync(path$1, "utf8");
+    },
+    `Skill edit (${skill.slug}) failed`
+  );
+  const mtimeAfter = (() => {
+    try {
+      return fs.statSync(path$1).mtimeMs;
+    } catch {
+      return mtimeBefore;
+    }
+  })();
+  const updated = result ?? original;
+  fs.rmSync(dir, { recursive: true, force: true });
+  if (result === null) {
+    return [];
+  }
+  if (mtimeAfter === mtimeBefore || updated === original) {
+    return colors.muted(`No changes to ${skill.slug}/SKILL.md \u2014 skill unchanged.`);
+  }
+  const blob = new Blob([updated], { type: "text/markdown" });
+  await sdk.documents.uploadFile(authHeaders, blob, "SKILL.md", {
+    folder: `skills/${skill.slug}`,
+    wpType: "skill"
+  });
+  await tui.refreshSkillsCache();
+  return [
+    colors.textBold(`Updated ${skill.name} (${skill.slug})`),
+    colors.muted("Skill cache refreshed \u2014 new description and args take effect immediately.")
+  ];
+}
+
 // src/commands/index.ts
 function registerAllCommands() {
   registerCommands(generalCommands);
@@ -1346,6 +1924,21 @@ function registerAllCommands() {
   registerCommands(tagCommands);
   registerCommands(miscCommands);
   registerCommands(citationCommands);
+  registerCommands(eventCommands);
+  registerCommands(viewCommands);
+  registerCommands(sourcesCommands);
+  registerCommands(historyCommands);
+  registerCommands(skillCommands);
+}
+function extractStepDetails(data) {
+  const detail = data.detail;
+  if (!detail || detail.length === 0) return void 0;
+  const d = detail[0];
+  if (!d) return void 0;
+  const result = {};
+  if (d.tool) result.tool = d.tool;
+  if (d.message) result.args = d.message;
+  return result.tool || result.args || result.result ? result : void 0;
 }
 async function streamResponse(tui, response) {
   tui.chatLog.startAssistant();
@@ -1372,7 +1965,7 @@ async function streamResponse(tui, response) {
     onAgentStep: (data) => {
       const label = sdk.formatAgentStepLabel(data);
       if (label) {
-        tui.chatLog.addAgentStep(label);
+        tui.chatLog.addAgentStep(label, extractStepDetails(data));
         tui.requestRender();
       }
     },
@@ -1388,6 +1981,7 @@ async function streamResponse(tui, response) {
     const result = await sdk.streamSSE(response, callbacks);
     tui.chatLog.finalizeAssistant();
     tui.lastMetadata = result.metadata ?? null;
+    tui.sourcesIndex.recordCitations(result.metadata);
     const summary = sdk.formatStreamSummary(result, elapsedTime);
     if (summary) {
       const refs = sdk.countCitations(result.metadata ?? null);
@@ -1596,43 +2190,50 @@ var DURATION_BY_LEVEL = {
 function isNotification(msg) {
   return "sender" in msg && "recipient" in msg;
 }
-async function handleMessage(msg, toasts, tui) {
+function shouldToast(level, msgType) {
+  if (level === "error" || level === "warning" || level === "success") return true;
+  if (msgType === "response_complete" || msgType === "batch_complete") return true;
+  return false;
+}
+async function handleMessage(msg, toasts, eventLog, tui) {
   if (isNotification(msg) && msg.type === "user_message" && tui) {
     const handled = await handleIncomingDm(tui, msg);
     if (handled) return;
   }
   const { text, level } = sdk.formatWsMessage(msg);
-  const duration = DURATION_BY_LEVEL[level] ?? DURATION_DEFAULT;
-  toasts.show(text, level, duration);
+  const msgType = msg.type;
+  eventLog.add({ text, level, msgType });
+  if (shouldToast(level, msgType)) {
+    const duration = DURATION_BY_LEVEL[level] ?? DURATION_DEFAULT;
+    toasts.show(text, level, duration);
+  }
 }
 async function connectTuiWebSocket(options) {
-  const { baseUrl, accessToken, toasts, tui } = options;
+  const { baseUrl, accessToken, toasts, eventLog, tui } = options;
+  const recordTransport = (text, level) => {
+    eventLog.add({ text, level });
+    const duration = DURATION_BY_LEVEL[level] ?? DURATION_DEFAULT;
+    toasts.show(text, level, duration);
+  };
   try {
     const connection = await sdk.connectWithReconnect({
       baseUrl,
       accessToken,
-      onMessage: (msg) => handleMessage(msg, toasts, tui ?? null),
-      onClose: () => {
-        toasts.show("WebSocket disconnected", "warning", DURATION_DEFAULT);
-      },
-      onReconnecting: (attempt, maxRetries) => {
-        toasts.show(`Reconnecting... (${attempt}/${maxRetries})`, "warning", DURATION_DEFAULT);
-      },
-      onReconnected: () => {
-        toasts.show("WebSocket reconnected", "success", DURATION_DEFAULT);
-      },
-      onReconnectFailed: () => {
-        toasts.show("WebSocket reconnection failed", "error", DURATION_LONG);
-      }
+      onMessage: (msg) => handleMessage(msg, toasts, eventLog, tui ?? null),
+      onClose: () => recordTransport("WebSocket disconnected", "warning"),
+      onReconnecting: (attempt, maxRetries) => recordTransport(`Reconnecting... (${attempt}/${maxRetries})`, "warning"),
+      onReconnected: () => recordTransport("WebSocket reconnected", "success"),
+      onReconnectFailed: () => recordTransport("WebSocket reconnection failed", "error")
     });
     return connection;
   } catch {
-    toasts.show("WebSocket connection failed", "warning", DURATION_DEFAULT);
+    recordTransport("WebSocket connection failed", "warning");
     return null;
   }
 }
 
 // src/tui.ts
+init_tui_helpers();
 var ArbiTui = class {
   tui;
   header;
@@ -1658,6 +2259,23 @@ var ArbiTui = class {
   dmChannel = null;
   /** Last response metadata — used by /cite for citation browsing. */
   lastMetadata = null;
+  /** Persistent log of WebSocket events for this session. Toasts are
+   *  ephemeral; this is the "what happened?" scrollback that
+   *  ``/events`` reads from. Public so ws-handler can append and the
+   *  events command can read. */
+  eventLog = new WsEventLog();
+  /** Running tally of documents cited in the current conversation.
+   *  Cleared on ``/new``; appended to after every assistant response
+   *  that carries citation metadata. Drives ``/sources`` and (later)
+   *  the persistent right-side sources panel. */
+  sourcesIndex = new SourcesIndex();
+  /** Cached list of user-invocable skills in the active workspace.
+   *  Refreshed on workspace switch (``setWorkspaceContext``) and
+   *  invalidated to ``[]`` when leaving a workspace. Drives the
+   *  autocomplete provider and the ``/skills`` / ``/skill view``
+   *  commands. ``null`` means "haven't fetched yet"; ``[]`` means
+   *  "fetched, no skills exist". */
+  skillsCache = [];
   /** Active citation overlay handle (null when not showing). */
   citationOverlay = null;
   /** Input listener ID for overlay dismiss (null when no overlay). */
@@ -1728,15 +2346,60 @@ var ArbiTui = class {
   /** Create and wire a new editor instance. */
   createEditor() {
     const editor = new ArbiEditor(this.tui);
-    editor.setAutocompleteProvider(new piTui.CombinedAutocompleteProvider(toSlashCommands()));
+    editor.setAutocompleteProvider(
+      new piTui.CombinedAutocompleteProvider(toSlashCommands(), process.cwd())
+    );
     editor.onSubmit = (text) => this.handleSubmit(text);
     editor.onEscape = () => this.handleAbort();
     editor.onCtrlC = () => this.shutdown();
     editor.onCtrlD = () => this.shutdown();
     editor.onCtrlW = () => this.handleSubmit("/workspaces");
     editor.onCtrlN = () => this.handleSubmit("/new");
+    editor.onCitationKey = (n) => this.handleSubmit(`/cite ${n}`);
+    editor.onBufferChange = (text) => this.handleBufferChange(text);
     return editor;
   }
+  /** The slug we last surfaced as a pre-flight hint. ``null`` once
+   *  the user has navigated away from the skill prefix (e.g. typed a
+   *  non-slash char first, or deleted past the slash). Tracking this
+   *  here — not in the editor — keeps the editor pure: it just emits
+   *  text, the TUI decides what's interesting. */
+  lastHintedSlug = null;
+  /**
+   * Pre-flight skill hint dispatcher.
+   *
+   * Watches the editor buffer; when it starts with ``/<token>`` where
+   * ``<token>`` is a slug in ``skillsCache`` *and* not also a static
+   * command (those have their own ``--help`` style help), we drop a
+   * one-line description into the chat log so the user sees what
+   * they're about to invoke before pressing Enter. Equivalent of
+   * claude-code's slash-command palette preview, minus the modal.
+   *
+   * Dedup rule: only emit when the matched slug *changes*. Typing
+   * "/foo" → "/foob" → "/foo" emits once for ``foo``, never for the
+   * intermediate ``foob`` (no match), and not again when the user
+   * lands back on ``foo``. The state resets whenever the buffer no
+   * longer matches anything, so a fresh ``/foo`` after a clear emits
+   * the hint again.
+   */
+  handleBufferChange(text) {
+    const parsed = sdk.parseSlashCommand(text);
+    if (!parsed) {
+      this.lastHintedSlug = null;
+      return;
+    }
+    const slug = parsed.slug;
+    if (this.skillsCache.length === 0) return;
+    const skill = this.skillsCache.find((s) => s.slug === slug);
+    if (!skill) {
+      this.lastHintedSlug = null;
+      return;
+    }
+    if (this.lastHintedSlug === slug) return;
+    this.lastHintedSlug = slug;
+    const argHint = skill.arg_hint ? ` ${skill.arg_hint}` : "";
+    showMessage(this, `Skill: /${skill.slug}${argHint} \u2014 ${skill.description}`, "info");
+  }
   /** Request a render update. */
   requestRender() {
     this.tui.requestRender();
@@ -1757,6 +2420,34 @@ var ArbiTui = class {
     this.state.workspaceId = ctx.workspaceId;
     this.updateHeader();
     this.connectWebSocket();
+    void this.refreshSkillsCache();
+  }
+  /** Refresh the cached skills list for the current workspace. Called
+   *  on workspace switch and from ``/skills`` itself so a freshly
+   *  uploaded skill becomes invocable without a TUI restart. */
+  async refreshSkillsCache() {
+    if (!this.workspaceContext) {
+      this.skillsCache = [];
+      this.rebuildAutocomplete();
+      return;
+    }
+    try {
+      this.skillsCache = await sdk.assistant.listSkills(this.workspaceContext.arbi);
+    } catch {
+      this.skillsCache = [];
+    }
+    this.rebuildAutocomplete();
+  }
+  /** Re-feed the editor's autocomplete provider with the merged
+   *  static-commands + skills list. Called on workspace switch and
+   *  after every ``refreshSkillsCache`` so a newly uploaded skill
+   *  appears in tab-complete without a TUI restart. */
+  rebuildAutocomplete() {
+    if (!this.editor) return;
+    const merged = toSlashCommandsWithSkills(
+      this.skillsCache.map((s) => ({ slug: s.slug, description: s.description }))
+    );
+    this.editor.setAutocompleteProvider(new piTui.CombinedAutocompleteProvider(merged, process.cwd()));
   }
   /** Refresh workspace context (after switching workspaces). */
   async refreshWorkspaceContext() {
@@ -1784,6 +2475,7 @@ var ArbiTui = class {
       baseUrl: config.baseUrl,
       accessToken,
       toasts: this.toastContainer,
+      eventLog: this.eventLog,
       tui: this
     }).then((conn) => {
       this.wsConnection = conn;
@@ -1841,6 +2533,14 @@ var ArbiTui = class {
         previousResponseId
       });
       const result = await streamResponse(this, response);
+      if (this.lastMetadata) {
+        const n = sdk.countCitations(this.lastMetadata);
+        if (n > 0) {
+          const cap = Math.min(n, 9);
+          const label = n <= 9 ? `${n} citation${n === 1 ? "" : "s"} available` : `${n} citations \u2014 Alt+1..9 jumps to the first 9; /cite N for the rest`;
+          this.chatLog.addSystem(`${label} \u2014 press Alt+1..${cap} to view`, "info");
+        }
+      }
       if (result.assistantMessageExtId) {
         this.state.conversationMessageId = result.assistantMessageExtId;
         const sessionUpdate = {