@corenel/term 0.1.0 → 0.2.0

package/dist/chunk-F4ENQXQQ.js

@@ -0,0 +1,909 @@
+import {
+  emptyState,
+  parseTodos
+} from "./chunk-OSJFMQCW.js";
+import {
+  parseCommand
+} from "./chunk-VTJEWHM3.js";
+import {
+  WRITE_TOOL_NAMES,
+  buildWritePreview
+} from "./chunk-M44CET5L.js";
+import {
+  committedFromMessages,
+  titleFrom
+} from "./chunk-IK4ZANNW.js";
+import {
+  capPreview,
+  describeToolCall,
+  formatPolicy,
+  formatTools
+} from "./chunk-2D7G4YW2.js";
+
+// src/session.ts
+import { runAgent } from "@corenel/harness/core/loop";
+
+// src/markdown.ts
+var FENCE = /^```(\w*)\s*$/;
+var HEADING = /^(#{1,6})\s+(.*)$/;
+var BULLET = /^\s*[-*]\s+(.*)$/;
+var NUMBERED = /^\s*\d+[.)]\s+(.*)$/;
+function parseMarkdown(text) {
+  return parseMarkdownSpans(text).map((s) => s.block);
+}
+function parseMarkdownSpans(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  let fence = null;
+  for (const line of lines) {
+    const f = FENCE.exec(line);
+    if (fence) {
+      if (f) {
+        fence.raw.push(line);
+        out.push({ block: { kind: "code", lang: fence.lang, text: fence.body.join("\n") }, raw: fence.raw.join("\n") });
+        fence = null;
+      } else {
+        fence.body.push(line);
+        fence.raw.push(line);
+      }
+      continue;
+    }
+    if (f) {
+      fence = { lang: f[1] ?? "", body: [], raw: [line] };
+      continue;
+    }
+    if (!line.trim()) {
+      const prev = out[out.length - 1];
+      if (prev && prev.block.kind === "blank") {
+        prev.raw += `
+${line}`;
+        continue;
+      }
+      out.push({ block: { kind: "blank", text: "" }, raw: line });
+      continue;
+    }
+    const h = HEADING.exec(line);
+    if (h) {
+      out.push({ block: { kind: "h", level: h[1].length, text: stripInline(h[2]) }, raw: line });
+      continue;
+    }
+    const li = BULLET.exec(line) ?? NUMBERED.exec(line);
+    if (li) {
+      out.push({ block: { kind: "li", text: stripInline(li[1]) }, raw: line });
+      continue;
+    }
+    out.push({ block: { kind: "p", text: stripInline(line) }, raw: line });
+  }
+  if (fence) out.push({ block: { kind: "code", lang: fence.lang, text: fence.body.join("\n") }, raw: fence.raw.join("\n") });
+  return out;
+}
+function stripInline(s) {
+  return s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)").replace(/\*\*(\S(?:[^*]*\S)?)\*\*/g, "$1").replace(/(?<!\*)\*(\S(?:[^*]*\S)?)\*(?!\*)/g, "$1").replace(/`([^`]+)`/g, "$1");
+}
+
+// src/session.ts
+var HELP_TEXT = [
+  "Type a request and press enter.",
+  "",
+  "  /tools          what the agent can do, and what it can change",
+  "  /policy         how this session is governed -- levels, caps, and what actually confines it",
+  "  /expand #3      re-print a tool result in full (#3 is the id on its row)",
+  "  /resume [id]    reopen an earlier conversation",
+  "  /clear          forget the conversation",
+  "  /exit           leave",
+  "",
+  "  /mode [id]      switch the agent mode, or list what is configured",
+  "  /persona [id]   switch persona, or list what is configured",
+  "  /skill [name]   apply a skill to your NEXT message only, or list what is installed",
+  "  /strategy [name] run a saved strategy from .prompd/strategies, or list what is saved",
+  "",
+  /* Deliberately not 'esc stops a turn': this text is shared, and Escape is
+   * an Ink-only key -- the readline fallback has no key handler at all, so
+   * there Ctrl-C is the only way to stop a turn. Name the one that is true
+   * on both faces, and mark the other as what it is. */
+  "Ctrl-C stops a turn; twice leaves. Ctrl-D leaves. In the full terminal face, esc also stops a turn."
+].join("\n");
+var DELTA_FLUSH_MS = 50;
+var TOOL_DELTA_CAP = 4e3;
+var TermSession = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  state = emptyState();
+  listeners = /* @__PURE__ */ new Set();
+  nextOrd = 1;
+  idSeq = 0;
+  pendingDelta = "";
+  flushTimer = null;
+  /* The full text streamed so far THIS ROUND (reset at beginTurn and again at
+   * every 'assistant' event, since a round of tool calls can be followed by
+   * another round of assistant text). Re-parsed into markdown blocks on every
+   * flush so all-but-the-last block can be committed as soon as it can no
+   * longer change -- see the module comment and flushDeltas(). */
+  streamFull = "";
+  /** How many leading blocks of `streamFull` have already been committed.
+   * Only the block at this index (the last one seen so far) is still live. */
+  streamCommittedBlocks = 0;
+  /** Whether this TURN has committed an assistant block yet. Reset only in
+   * `beginTurn` (never per round-trip within a turn, even though a turn with
+   * tool calls emits several 'assistant' events) so a whole turn's streamed
+   * reply -- however many rounds of tool use it took -- reads as ONE reply
+   * with ONE leading blank line, not one per round. See `commitAssistantBlock`. */
+  replyHasBlock = false;
+  /** Set when a `blank` markdown span was seen but not committed as its own
+   * item (see `commitCompletedBlocks`), and consumed by the next block that
+   * DOES commit -- see `commitAssistantBlock`. Reset in `beginTurn` too: a
+   * blank line at the very end of one round of streamed text must never leak
+   * a gap onto the first block of a LATER round (e.g. after a tool call). */
+  pendingGap = false;
+  /* An offload is emitted just BEFORE the tool-result it belongs to (see
+   * @corenel/harness core/loop.ts: recall.record() then emit('offload'), then
+   * emit('tool-result')), and it carries the BLOB id, not the call id. So it is
+   * held here and claimed by the next result rather than looked up by id. */
+  pendingOffload = null;
+  /** The model's truth, as opposed to `committed`, which is display. */
+  history = [];
+  turnAc = null;
+  /** Monotonic turn id. Events stamped with an older one are dropped: a late
+   * delta from an aborted turn must never paint into the next one. */
+  turnId = 0;
+  activeTurn = 0;
+  pending = null;
+  draining = false;
+  /* Bumped whenever the conversation is REPLACED out from under a turn --
+   * `/clear` and `resume()`. A turn captures it when it starts and only adopts
+   * the messages it accumulated if the stamp still matches, because runAgent
+   * copies `messages` at turn start: without this, a `/clear` typed mid-turn
+   * was undone the moment the turn landed (and then written to disk), so the
+   * screen said forgotten while the next request still carried everything. */
+  historyGen = 0;
+  /* True from the moment a turn starts until the queue behind it has been
+   * drained. `status` flips to 'idle' inside runAgent's 'done' event, but
+   * runTurn then awaits persist() -- a DISK WRITE -- before it reaches drain().
+   * A line submitted in that window used to find an idle controller with a
+   * non-empty queue and start a turn immediately: the queue lost its order,
+   * and two turns could overlap, leaving a user message with no reply. */
+  settling = false;
+  /** The approval gate. Supplied by whichever face can show a prompt (readline's
+   * `ask`, the Ink modal, ...) — the controller has no rendering of its own, so
+   * it cannot build one itself. Unattached, `runTurn` simply omits `permission`
+   * from the runner args, and the loop runs every tool ungated. */
+  permission;
+  /** Armed by `/skill <name>` (see runCommand); consumed and cleared by the
+   * NEXT runTurn, never a later one. `state.pendingSkill` mirrors just the
+   * label, for a face's indicator -- the instructions text never needs to
+   * reach a renderer. */
+  pendingSkill = null;
+  wantsExit = false;
+  attachPermission(p) {
+    this.permission = p;
+  }
+  historyForTest() {
+    return this.history;
+  }
+  getSnapshot() {
+    return this.state;
+  }
+  subscribe(fn) {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+  /** Replace state and notify. Every mutation goes through here so `seq` and the
+   * snapshot identity can never drift from the data. */
+  set(patch) {
+    this.state = { ...this.state, ...patch, seq: this.state.seq + 1 };
+    for (const fn of this.listeners) fn();
+  }
+  id(prefix) {
+    return `${prefix}${++this.idSeq}`;
+  }
+  commit(item) {
+    this.set({ committed: [...this.state.committed, item] });
+  }
+  /** Commit one assistant block, marking it `leadingBlank` iff no block has
+   * been committed yet this turn OR a `blank` span was seen (and swallowed --
+   * see `commitCompletedBlocks`) since the last one that was. This is the
+   * ONLY place that commits an 'assistant' item -- commitCompletedBlocks, the
+   * manual commits in the 'assistant' event case, and endTurn's
+   * trailing-block commit all route through here, so there is one rule for
+   * which block gets the leading margin rather than four call sites that
+   * merely happen to agree today. */
+  commitAssistantBlock(text) {
+    const leadingBlank = !this.replyHasBlock || this.pendingGap;
+    this.replyHasBlock = true;
+    this.pendingGap = false;
+    this.commit({ kind: "assistant", id: this.id("a"), text, ...leadingBlank ? { leadingBlank: true } : {} });
+  }
+  /** The system prompt for the turn about to run -- called fresh every time
+   * (see `runTurn`), never cached, so a mode/persona switch (which mutates
+   * state the HOST owns, then calls `deps.system` again on the next turn)
+   * actually changes what the model sees instead of only looking like it did.
+   * A plain string `deps.system` degrades to exactly today's behaviour. */
+  async resolveSystem() {
+    const s = this.deps.system;
+    if (s === void 0) return void 0;
+    return typeof s === "function" ? await s() : s;
+  }
+  note(level, text, detail) {
+    this.commit({ kind: "note", id: this.id("n"), level, text, ...detail ? { detail } : {} });
+  }
+  /** Open a live turn. Public-for-test until Task 4 gives it a real caller. */
+  beginTurnForTest() {
+    this.beginTurn();
+  }
+  flushDeltasForTest() {
+    this.flushDeltas();
+  }
+  beginTurn() {
+    this.streamFull = "";
+    this.streamCommittedBlocks = 0;
+    this.replyHasBlock = false;
+    this.pendingGap = false;
+    this.set({
+      live: { streaming: "", tools: [], turn: (this.state.live?.turn ?? 0) + 1 },
+      status: "running",
+      error: null,
+      turnUsage: { promptTokens: 0, completionTokens: 0 }
+    });
+  }
+  /** Commit every markdown block in `streamFull` that can no longer change --
+   * i.e. every block except the last, which more text can still extend --
+   * and return the still-live trailing block's raw text. This is what keeps
+   * the live region Ink redraws every frame bounded by one block instead of
+   * the whole reply: see the module comment for why an unbounded live region
+   * corrupts the frame once it scrolls out of the viewport.
+   *
+   * KNOWN LIMIT: any single block taller than the terminal -- not just a
+   * fenced code block, but equally one long unbroken paragraph, or any other
+   * span with no internal blank-line break -- stays "the trailing block", and
+   * so stays live and unbounded, until it closes (or the blank line that ends
+   * it arrives). That bounds the live region by one block rather than by the
+   * viewport, which the headless controller has no way to know. It is still
+   * a large improvement over the whole reply staying live, and a single block
+   * taller than the terminal is rare. */
+  commitCompletedBlocks() {
+    const spans = parseMarkdownSpans(this.streamFull);
+    if (spans.length === 0) return "";
+    while (this.streamCommittedBlocks < spans.length - 1) {
+      const span = spans[this.streamCommittedBlocks];
+      if (span.block.kind === "blank") this.pendingGap = true;
+      else this.commitAssistantBlock(span.raw);
+      this.streamCommittedBlocks++;
+    }
+    return spans[spans.length - 1].raw;
+  }
+  flushDeltas() {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (!this.pendingDelta) return;
+    const chunk = this.pendingDelta;
+    this.pendingDelta = "";
+    const live = this.state.live;
+    if (!live) return;
+    this.streamFull += chunk;
+    const trailing = this.commitCompletedBlocks();
+    this.set({ live: { ...this.state.live, streaming: trailing } });
+  }
+  scheduleFlush() {
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      this.flushDeltas();
+    }, DELTA_FLUSH_MS);
+    this.flushTimer.unref?.();
+  }
+  /** Commit whatever the live region still holds -- the trailing block that
+   * flushDeltas kept live, since every block before it is already committed
+   * -- and close the turn. */
+  endTurn() {
+    this.flushDeltas();
+    const live = this.state.live;
+    if (live?.streaming.trim()) {
+      this.commitAssistantBlock(live.streaming);
+    }
+    const stopped = this.state.status === "aborting";
+    this.set({ live: null, status: "idle" });
+    this.streamFull = "";
+    this.streamCommittedBlocks = 0;
+    if (stopped) this.note("info", "(stopped)");
+  }
+  /** The ordinal a 'tool-result' with this callId will commit with: the id
+   * already recorded against it in `live.tools` if a 'tool-call' announced
+   * it, or the next fresh one otherwise -- the second path is how a bare
+   * result with no matching call (loop.ts emits one straight away when the
+   * model's JSON arguments don't parse) still gets a real ordinal.
+   *
+   * PEEKS `nextOrd`, never advances it. This is shared, read-only, by BOTH
+   * `ordFor` (the tap's preview) and the 'tool-result' reducer case below
+   * (which alone decides whether to advance `nextOrd`, immediately after
+   * calling this) precisely so there is one rule for "what ordinal does this
+   * result get", expressed once, rather than two conditions that merely
+   * happen to agree today. A same-shaped bare-result WITHOUT this shared
+   * helper is exactly the case that let the tap and the reducer drift before
+   * -- ordFor returned undefined while the reducer minted a real ordinal. */
+  resultOrd(callId) {
+    return this.state.live?.tools.find((t) => t.callId === callId)?.ord ?? this.nextOrd;
+  }
+  /** The ordinal a face's raw event tap should show for `e`, read from the
+   * SAME state the reducer below is about to use -- never a second counter.
+   * 'tool-call' previews the id the reducer is about to hand out (`nextOrd`
+   * itself, not a copy of it); 'tool-result' previews `resultOrd` above,
+   * covering the announced AND the bare-result case alike. Anything else has
+   * no ordinal to show. */
+  ordFor(e) {
+    if (e.type === "tool-call") return this.nextOrd;
+    if (e.type === "tool-result") return this.resultOrd(e.id);
+    return void 0;
+  }
+  handleEvent(e) {
+    this.deps.onEvent?.(e, this.ordFor(e));
+    switch (e.type) {
+      case "turn": {
+        const live = this.state.live;
+        if (live) this.set({ live: { ...live, turn: e.turn } });
+        break;
+      }
+      case "assistant-delta":
+        this.pendingDelta += e.delta;
+        this.scheduleFlush();
+        break;
+      case "assistant": {
+        this.flushDeltas();
+        const live = this.state.live;
+        const trailing = live?.streaming ?? "";
+        if (trailing.trim()) {
+          this.commitAssistantBlock(trailing);
+        } else if (this.streamCommittedBlocks === 0 && e.content.trim()) {
+          this.commitAssistantBlock(e.content);
+        }
+        if (live) this.set({ live: { ...this.state.live, streaming: "" } });
+        this.streamFull = "";
+        this.streamCommittedBlocks = 0;
+        this.pendingGap = false;
+        break;
+      }
+      case "tool-call": {
+        this.flushDeltas();
+        if (e.name === "todo_write") {
+          this.set({ todos: parseTodos(e.args) });
+        }
+        const live = this.state.live;
+        if (!live) break;
+        const tool = {
+          callId: e.id,
+          ord: this.nextOrd++,
+          name: e.name,
+          subject: describeToolCall(e.name, e.args)
+        };
+        this.set({ live: { ...live, tools: [...live.tools, tool] } });
+        break;
+      }
+      case "tool-delta": {
+        const live = this.state.live;
+        if (!live) break;
+        const idx = live.tools.findIndex((t) => t.callId === e.id);
+        if (idx < 0) break;
+        const prior = live.tools[idx];
+        const combined = (prior.delta ?? "") + e.delta;
+        const capped = combined.length > TOOL_DELTA_CAP ? combined.slice(-TOOL_DELTA_CAP) : combined;
+        const tools = [...live.tools];
+        tools[idx] = { ...prior, delta: capped };
+        this.set({ live: { ...live, tools } });
+        break;
+      }
+      case "tool-result": {
+        this.flushDeltas();
+        const live = this.state.live;
+        const pending = live?.tools.find((t) => t.callId === e.id);
+        const ord = this.resultOrd(e.id);
+        if (!pending) this.nextOrd++;
+        const isError = e.isError === true;
+        const offload = this.pendingOffload;
+        this.pendingOffload = null;
+        const item = {
+          kind: "tool",
+          id: this.id("t"),
+          callId: e.id,
+          ord,
+          name: e.name,
+          subject: pending?.subject ?? "",
+          preview: capPreview(e.result, isError),
+          isError,
+          ...e.durationMs !== void 0 ? { durationMs: e.durationMs } : {},
+          ...offload ? { offloadedBytes: offload.bytes, offloadRefId: offload.refId } : {}
+        };
+        if (live) {
+          this.state = {
+            ...this.state,
+            live: { ...live, tools: live.tools.filter((t) => t.callId !== e.id) }
+          };
+        }
+        this.commit(item);
+        break;
+      }
+      case "offload":
+        this.pendingOffload = { refId: e.id, bytes: e.bytes };
+        break;
+      case "permission":
+      case "permission-audit":
+        break;
+      case "policy-violation":
+        this.note(
+          e.action === "stop" ? "error" : "warn",
+          e.action === "stop" ? `blocked  ${e.message}` : `warning  ${e.message}`,
+          e.tool
+        );
+        break;
+      case "heal":
+        if (e.record.outcome === "abandoned" || e.record.outcome === "exhausted") {
+          this.note("warn", `recovery gave up  ${e.record.error ?? e.record.strategy}`);
+        }
+        break;
+      case "usage":
+        this.set({
+          usage: {
+            promptTokens: this.state.usage.promptTokens + e.usage.promptTokens,
+            completionTokens: this.state.usage.completionTokens + e.usage.completionTokens
+          },
+          turnUsage: {
+            promptTokens: this.state.turnUsage.promptTokens + e.usage.promptTokens,
+            completionTokens: this.state.turnUsage.completionTokens + e.usage.completionTokens
+          }
+        });
+        break;
+      case "artifact":
+        this.note("info", `artifact  ${e.kind}${e.title ? `  ${e.title}` : ""}`);
+        break;
+      case "budget-stop":
+      case "budget-warn":
+        this.note("warn", `budget  ${e.type === "budget-stop" ? "stopped" : "over"}`);
+        break;
+      case "error":
+        this.flushDeltas();
+        this.note("error", e.message);
+        this.set({ error: e.message });
+        break;
+      case "done":
+        this.endTurn();
+        break;
+      default:
+        break;
+    }
+  }
+  /** Route one line: a command runs here; anything else is a turn. */
+  async submit(text) {
+    const line = text.trim();
+    if (!line) return;
+    const cmd = parseCommand(line);
+    if (cmd) {
+      await this.runCommand(cmd);
+      return;
+    }
+    await this.queueOrRun(line);
+  }
+  /** Run `line` as a turn now, or queue it, exactly like `submit` does for
+   * ordinary text -- factored out so `/strategy` (runCommand) can send its
+   * resolved prompt through the SAME busy/queue check a typed line gets,
+   * rather than calling `runTurn` directly and risking two turns in flight. */
+  async queueOrRun(line) {
+    if (this.state.status !== "idle" || this.settling) {
+      this.set({ queued: [...this.state.queued, line] });
+      return;
+    }
+    await this.runTurn(line);
+  }
+  async runCommand(cmd) {
+    switch (cmd.cmd) {
+      case "exit":
+        this.wantsExit = true;
+        return;
+      case "clear": {
+        const droppedSkill = this.pendingSkill;
+        this.pendingSkill = null;
+        this.history = [];
+        this.historyGen++;
+        this.set({
+          committed: [],
+          usage: { promptTokens: 0, completionTokens: 0 },
+          turnUsage: { promptTokens: 0, completionTokens: 0 },
+          todos: [],
+          pendingSkill: null
+        });
+        if (droppedSkill) this.note("info", `cleared -- the armed skill "${droppedSkill.label}" was dropped too`);
+        return;
+      }
+      case "tools":
+        this.note("info", formatTools(this.deps.tools));
+        return;
+      case "policy":
+        if (!this.deps.policy || !this.deps.policySource) {
+          this.note("warn", "/policy is not available in this session");
+          return;
+        }
+        this.note("info", formatPolicy(this.deps.policy, this.deps.policySource, this.deps.tools));
+        return;
+      case "help":
+        this.note("info", HELP_TEXT);
+        return;
+      case "expand": {
+        if (cmd.ord === void 0) {
+          this.note("warn", "usage: /expand #3");
+          return;
+        }
+        await this.expand(cmd.ord);
+        return;
+      }
+      case "resume":
+        await this.resume(cmd.id);
+        return;
+      case "mode":
+        await this.switchIdentity({
+          kind: "mode",
+          id: cmd.id,
+          list: this.deps.listModes,
+          apply: this.deps.setMode
+        });
+        return;
+      case "persona":
+        await this.switchIdentity({
+          kind: "persona",
+          id: cmd.id,
+          list: this.deps.listPersonas,
+          apply: this.deps.setPersona
+        });
+        return;
+      case "skill":
+        await this.armSkillCommand(cmd.id);
+        return;
+      case "strategy":
+        await this.runStrategyCommand(cmd.id);
+        return;
+    }
+  }
+  /** Runs a host-supplied config-workspace call (`listModes`, `listSkills`,
+   * `armSkill`, ...) and turns a THROW into a `warn` note instead of letting
+   * it escape the command handler and take the turn down with it.
+   *
+   * `listSkills()` (packages/harness/skills.ts) already wraps its own
+   * `seedConfig()`/read calls this way and never throws; `loadModes`/
+   * `loadPersonas` (packages/harness/prompts/config.ts) call `seedConfig()`
+   * UNGUARDED, so a genuine config-workspace failure (permissions, a
+   * read-only home, disk full -- masked on a normal install because
+   * `NodeFileService.write()` mkdirs recursively, but real on a broken one)
+   * threw straight out of `/mode`/`/persona` and crashed the turn instead of
+   * reporting "not available" the way `/skill` already does. Wrapping every
+   * host call here, not just the two that are known to need it, means the
+   * NEXT one added can't reintroduce the same gap by omission. */
+  async safeCall(kind, fn) {
+    try {
+      return { ok: true, value: await fn() };
+    } catch (e) {
+      this.note("warn", `/${kind} is not available -- could not read the config workspace (${e instanceof Error ? e.message : String(e)})`);
+      return { ok: false };
+    }
+  }
+  /** Shared `/mode` and `/persona` shape: no id lists what's configured, an
+   * unknown id reports the valid options (never silently no-ops, never sends
+   * a typo through to the model), a real id applies immediately -- "applies"
+   * meaning `deps.system` will pick it up on the NEXT `resolveSystem()` call,
+   * not this instant (see the field docs on TermSessionDeps.system). */
+  async switchIdentity(opts) {
+    if (!opts.list || !opts.apply) {
+      this.note("warn", `/${opts.kind} is not available in this session`);
+      return;
+    }
+    const listed = await this.safeCall(opts.kind, opts.list);
+    if (!listed.ok) return;
+    const entries = listed.value;
+    const names = entries.map((e) => e.id).join(", ") || "none configured";
+    if (!opts.id) {
+      this.note("info", `${opts.kind}s: ${names}`);
+      return;
+    }
+    const found = entries.find((e) => e.id === opts.id);
+    if (!found) {
+      this.note("warn", `no ${opts.kind} "${opts.id}". available: ${names}`);
+      return;
+    }
+    opts.apply(found.id);
+    this.note("info", `${opts.kind} set to ${found.label} -- takes effect on your next message`);
+  }
+  async armSkillCommand(id) {
+    if (!this.deps.listSkills || !this.deps.armSkill) {
+      this.note("warn", "/skill is not available in this session");
+      return;
+    }
+    const listed = await this.safeCall("skill", this.deps.listSkills);
+    if (!listed.ok) return;
+    const entries = listed.value;
+    const names = entries.map((e) => e.id).join(", ") || "none installed";
+    if (!id) {
+      this.note("info", `skills: ${names}`);
+      return;
+    }
+    const found = entries.find((e) => e.id === id);
+    if (!found) {
+      this.note("warn", `no skill "${id}". available: ${names}`);
+      return;
+    }
+    const armSkill = this.deps.armSkill;
+    const loaded = await this.safeCall("skill", () => armSkill(found.id));
+    if (!loaded.ok) return;
+    const armed = loaded.value;
+    if (!armed) {
+      this.note("warn", `could not load skill "${found.id}"`);
+      return;
+    }
+    this.pendingSkill = armed;
+    this.set({ pendingSkill: armed.label });
+    this.note("info", `skill "${armed.label}" armed -- applies to your next message, then clears`);
+  }
+  async runStrategyCommand(id) {
+    if (!this.deps.listStrategies || !this.deps.resolveStrategy) {
+      this.note("warn", "/strategy is not available in this session");
+      return;
+    }
+    const listed = await this.safeCall("strategy", this.deps.listStrategies);
+    if (!listed.ok) return;
+    const entries = listed.value;
+    const names = entries.map((e) => e.id).join(", ");
+    if (!id) {
+      this.note("info", entries.length ? `strategies: ${names}` : "no saved strategies in this workspace");
+      return;
+    }
+    const found = entries.find((e) => e.id === id);
+    if (!found) {
+      this.note("warn", entries.length ? `no strategy "${id}". available: ${names}` : `no strategy "${id}" -- no saved strategies in this workspace`);
+      return;
+    }
+    const resolveStrategy = this.deps.resolveStrategy;
+    const resolved = await this.safeCall("strategy", () => resolveStrategy(found.id));
+    if (!resolved.ok) return;
+    if (!resolved.value) {
+      this.note("warn", `could not load strategy "${found.id}"`);
+      return;
+    }
+    this.note("info", `running strategy "${resolved.value.name}"`);
+    await this.queueOrRun(resolved.value.prompt);
+  }
+  /** Save after the turn, never during: a half-written turn is a lie on disk. */
+  async persist() {
+    const p = this.deps.persistence;
+    if (!p) return;
+    try {
+      const title = this.state.session?.title ?? titleFrom(this.history);
+      const { id } = await p.save({ id: this.state.session?.id ?? null, title, messages: this.history });
+      this.set({ session: { id, title } });
+      this.deps.onSessionId?.(id);
+    } catch (e) {
+      this.note("warn", `could not save this conversation: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  /** Reopen a conversation: `id` if given, otherwise the most recent. */
+  async resume(id) {
+    const p = this.deps.persistence;
+    if (!p) {
+      this.note("warn", "this session is not being saved, so there is nothing to resume");
+      return;
+    }
+    const loaded = await p.load(id);
+    if (!loaded) {
+      this.note("warn", id ? `no conversation ${id}` : "no earlier conversation to resume");
+      return;
+    }
+    const droppedSkill = this.pendingSkill;
+    this.pendingSkill = null;
+    this.history = loaded.messages;
+    this.historyGen++;
+    this.nextOrd = 1;
+    const committed = committedFromMessages(loaded.messages).map(
+      (item) => item.kind === "tool" ? { ...item, ord: this.nextOrd++ } : item
+    );
+    this.set({
+      committed,
+      // Defensive, not reachable today (a command can't run while `live` is
+      // set -- see `submit`'s `status !== 'idle'` guard): `nextOrd` is reset
+      // above on the assumption no turn is mid-flight handing out ordinals
+      // of its own right now. If that assumption is ever wrong, a live tool
+      // row from BEFORE the resume would still be pointing at an ordinal
+      // this reset just reused for a restored row -- the very drift this
+      // whole ordinal design exists to rule out. Clearing it here keeps the
+      // assumption true by construction instead of by the caller's care.
+      live: null,
+      transcriptGen: this.state.transcriptGen + 1,
+      session: { id: loaded.id, title: loaded.title },
+      pendingSkill: null
+    });
+    this.deps.onSessionId?.(loaded.id);
+    if (droppedSkill) this.note("info", `resumed -- the armed skill "${droppedSkill.label}" was dropped too`);
+  }
+  /** Re-print a committed tool row in full, as a NEW block at the bottom.
+   * Inline rendering owns this trade: the original row's bytes belong to the
+   * terminal's scrollback and cannot be rewritten in place. */
+  async expand(ord) {
+    const row = this.state.committed.find((i) => i.kind === "tool" && i.ord === ord);
+    if (!row || row.kind !== "tool") {
+      this.note("warn", `no tool result #${ord} in this conversation`);
+      return;
+    }
+    const full = await this.fullResult(row.id, row);
+    this.note("info", `#${row.ord}  ${row.name}  ${row.subject}`, full);
+  }
+  /** The full body of a committed row. `committed` only ever keeps the capped
+   * `preview`, and a second copy would be redundant AND wrong: `history`
+   * already carries the exact string the model saw for this call (the full
+   * body when it wasn't offloaded, the short offload ref when it was — see
+   * @corenel/harness core/loop.ts's `messages.push({ role: 'tool', ... })`),
+   * and `history` is cleared by `/clear`, so a stale row can't outlive the
+   * conversation it belongs to the way a side map would. Branch (a) below reads
+   * an offloaded body back out of the blob store by `row.offloadRefId` — live
+   * now that the CLI passes `deps.recall` and `deps.compression` (see
+   * packages/cli/src/cli.ts). */
+  async fullResult(_id, row) {
+    if (row.offloadedBytes !== void 0 && this.deps.recall) {
+      const full = await this.deps.recall(row.offloadRefId ?? row.id);
+      if (full) return full;
+    }
+    const msg = this.history.find(
+      (m) => m.role === "tool" && m.tool_call_id === row.callId
+    );
+    if (msg && typeof msg.content === "string") return msg.content;
+    return row.preview.join("\n");
+  }
+  async runTurn(line) {
+    this.settling = true;
+    this.commit({ kind: "user", id: this.id("u"), text: line });
+    const skill = this.pendingSkill;
+    this.pendingSkill = null;
+    this.set({ pendingSkill: null });
+    const content = skill ? `[Skill: ${skill.label}]
+${skill.instructions}
+
+---
+
+${line}` : line;
+    this.history.push({ role: "user", content });
+    const gen = this.historyGen;
+    const ac = new AbortController();
+    this.turnAc = ac;
+    const mine = ++this.turnId;
+    this.activeTurn = mine;
+    this.beginTurn();
+    const system = await this.resolveSystem();
+    const run = this.deps.runner ?? runAgent;
+    try {
+      const result = await run({
+        client: this.deps.client,
+        model: this.deps.model,
+        ...system ? { system } : {},
+        messages: this.history,
+        tools: this.deps.tools,
+        toolCtx: this.deps.toolCtx(ac.signal, (q) => this.askUser(q), this.permission),
+        signal: ac.signal,
+        ...this.permission ? { permission: this.permission } : {},
+        ...this.deps.compression ? { compression: this.deps.compression } : {},
+        onEvent: (e) => {
+          if (this.activeTurn === mine) this.handleEvent(e);
+        }
+      });
+      if (this.activeTurn !== mine) return;
+      if (ac.signal.aborted || result.stopReason === "aborted") {
+        await this.finishAbandoned(gen);
+        return;
+      }
+      if (this.historyGen === gen) this.history = result.messages;
+      this.endTurn();
+      await this.persist();
+      if (this.activeTurn === mine) this.activeTurn = 0;
+    } catch (e) {
+      if (this.activeTurn === mine) {
+        if (!ac.signal.aborted) this.note("error", e instanceof Error ? e.message : String(e));
+        await this.finishAbandoned(gen);
+      }
+    } finally {
+      if (this.turnAc === ac) this.turnAc = null;
+      this.forceClosePending();
+      await this.drain();
+      if (!this.draining) this.settling = false;
+    }
+  }
+  /** Close out a turn that produced nothing usable -- aborted, or failed.
+   * Drops the abandoned user message: a user message with no reply, or a tool
+   * call with no result, poisons the next request. Exactly once, and never when
+   * the conversation was replaced under it (`/clear`, `/resume`), where the
+   * message it would drop belongs to someone else's history. */
+  async finishAbandoned(gen) {
+    if (this.historyGen === gen) this.history = this.history.slice(0, -1);
+    this.endTurn();
+    await this.persist();
+    this.activeTurn = 0;
+  }
+  async drain() {
+    if (this.draining) return;
+    this.draining = true;
+    try {
+      for (; ; ) {
+        const [next, ...rest] = this.state.queued;
+        if (next === void 0) break;
+        this.set({ queued: rest });
+        await this.runTurn(next);
+      }
+    } finally {
+      this.draining = false;
+    }
+  }
+  /** Stop the TURN, never the process. A long tool call you regret is the common
+   * case, and killing the shell to escape it loses the conversation. */
+  abort() {
+    if (this.state.status === "idle" && !this.pending) return;
+    this.set({ status: "aborting" });
+    this.forceClosePending();
+    this.turnAc?.abort();
+  }
+  /** DO NOT mark this method `async` -- that is a deliberate, load-bearing
+   * choice, not an oversight to "clean up" later. An `async` function turns a
+   * synchronous `throw` into a REJECTED PROMISE rather than an exception the
+   * caller's own `try`/`catch` sees, which would silently break the "a
+   * question is already open" guard immediately below (session.turn.test.ts's
+   * "refuses a second concurrent ask rather than queueing it quietly" pins
+   * this: it calls `askPermission` twice back-to-back and asserts the SECOND
+   * call throws synchronously). The diff read only ever happens for a write
+   * tool with a `path` AND a host that wired `previewWrite` -- reached via the
+   * `.then(openModal)` chain below, not `await` -- so every other call stays
+   * fully synchronous, exactly as before this method could show a diff at
+   * all. */
+  askPermission(req) {
+    if (this.deps.approveAll) return Promise.resolve("allow");
+    if (this.pending) throw new Error("a question is already open");
+    const detail = req.input;
+    const shown = typeof detail?.command === "string" ? detail.command : typeof detail?.path === "string" ? detail.path : "";
+    const openModal = (diff) => {
+      if (this.state.status === "aborting") return "deny";
+      this.set({ modal: { kind: "permission", tool: req.tool, detail: shown, ...diff ? { diff } : {} } });
+      return new Promise((resolve) => {
+        this.pending = { resolve: (v) => resolve(v ?? "deny") };
+      });
+    };
+    if (!this.deps.previewWrite || !WRITE_TOOL_NAMES.has(req.tool)) return Promise.resolve(openModal(null));
+    return buildWritePreview(req.tool, req.input, this.deps.previewWrite).then(openModal);
+  }
+  askUser(questions) {
+    if (this.pending) throw new Error("a question is already open");
+    this.set({ modal: { kind: "user", questions } });
+    return new Promise((resolve) => {
+      this.pending = { resolve: (v) => resolve(v ?? null) };
+    });
+  }
+  /** The view's answer to whichever modal is open. */
+  answer(value) {
+    this.resolvePending(value);
+  }
+  /** Force-close whatever modal is open, on turn teardown or `abort()`. The
+   * sentinel must match the modal's OWN contract, not a shared default:
+   * `askPermission` promises `PermissionDecision`, where `'deny'` is a real
+   * value; `askUser` promises `AskAnswers | null`, and `'deny'` there would be
+   * a bogus truthy string standing in for the documented "dismissed" (`null`)
+   * outcome that `askUserTool` (packages/harness/tools/builtins.ts) checks for. */
+  forceClosePending() {
+    if (!this.pending) return;
+    this.resolvePending(this.state.modal?.kind === "user" ? null : "deny");
+  }
+  resolvePending(value) {
+    const p = this.pending;
+    if (!p) return;
+    this.pending = null;
+    this.set({ modal: null });
+    p.resolve(value);
+  }
+};
+
+export {
+  parseMarkdown,
+  DELTA_FLUSH_MS,
+  TOOL_DELTA_CAP,
+  TermSession
+};