@aiwayds/dsh-tui-pi 0.1.1 → 0.4.0

package/README.md

@@ -38,8 +38,11 @@ dsh ▸ ☁ opencode-go ▸ 🤖 deepseek-v4-flash ▸ ● high ▸ 🧠 11.6k/1
   `cmux-theme.sh` GitHub terminal themes). Hot-switchable at runtime: pick one
   with `/theme` (applies immediately), edit the `dsh-tui.theme` setting
   (external edits hot-apply too), or pin with `DSH_TUI_THEME=light|dark` — the
-  env var wins over every preference. Without a preference, terminal-background
-  detection (COLORFGBG).
+  env var wins over every preference. The app paints its own canvas, so a
+  switch recolors the whole screen (background included) even inside
+  multiplexers; without a preference, `auto` detects the terminal background
+  (COLORFGBG + a live OSC 11 / CSI 996n query) and follows the terminal's
+  light/dark switches in real time.
 - **Footer**: powerline segments ported from
   [pi-powerline-footer](https://github.com/fan56/pi-powerline-footer) —
   provider / model+thinking / context / cache-hit / msgs / tools with U+E0B0
@@ -77,7 +80,10 @@ dsh ▸ ☁ opencode-go ▸ 🤖 deepseek-v4-flash ▸ ● high ▸ 🧠 11.6k/1
 | `/export` | write the current session log as JSONL — default `~/Downloads/dsh-session-<id>.jsonl`, or a path argument. |
 | `/permission` | permission-preset picker (whatever the deployment table advertises — read-only / workspace-write / danger-full-access). Select a preset to apply it through dsh's canonical `/permission <name>` command, or Esc to keep the current one. The editor's top border shows the live preset badge (danger-full-access → "Full access"). |
 | `/theme` | color-scheme picker (auto / light / dark). The choice applies immediately and is persisted to `dsh-tui.theme`. |
+| `/agents` | manage agent definition markdown files (name/model/thinking/deep per agent) **and the subagent limits** — `l` from the table opens the limits panel: `maxAgents` (concurrent live children, default 4) and `maxRounds` (completed turns before the TUI queues a wrap-up request, default 50; both `0 = unlimited`). Limits are read live at every spawn/turn decision; writes go to the `dsh-tui` settings namespace and hot-apply. Also the initial view when no agent files exist yet. |
+| `/subagents` | the command twin of `Ctrl+G`: pick a running (or recently settled) subagent and watch its live transcript in the 80% viewer — status, rounds against the cap, tokens, tool calls. |
 | `/reload` | hot-reload the plugin from the current source (after `pnpm build`) without restarting dsh — the TUI and the live agent are torn down; the session log persists and can be rejoined with `/resume`. |
+| `/hotkeys` | keybinding browser: the effective app-key table (custom overrides starred) plus the keybindings file path — see [Custom keybindings](#custom-keybindings). |
 
 Anything that is not a resolvable command falls through to the model as an
 ordinary prompt, so dsh packages' commands (and future registrations) appear
@@ -115,13 +121,26 @@ Themes change live, no restart:
   `applies: 'live'`. The namespace's watch hook pushes the commit to the
   running TUI, which repaints everything on the next frame: transcript
   (replayed from its operation buffer), editor border, footer hint, spinner.
+- **The whole screen changes, background included.** The TUI paints its own
+  canvas (a patched pi-tui paints every rendered row with the palette's
+  canvas color), so a light→dark switch recolors the entire surface — the
+  terminal's own background never shows through, which is what makes the
+  switch look broken inside multiplexers like cmux/gostty where the pane
+  background belongs to the terminal, not the app. Set
+  `DSH_TUI_TRANSPARENT=1` to go back to the see-through canvas and keep your
+  terminal theme visible.
 - An **external edit** of `~/.dsh/settings.yaml` (`dsh-tui.theme: dark`)
   hot-applies through the same watch path.
 - `DSH_TUI_THEME=light|dark` **pins** the display regardless of preference —
   it wins at startup and keeps winning; `/theme` still persists the
   preference and honestly reports `Theme preference saved — display is pinned
   by DSH_TUI_THEME=…` instead of claiming it applied.
-- The choice survives restarts (`auto` falls back to terminal detection).
+- The choice survives restarts. `auto` detects the terminal: the synchronous
+  startup guess reads `COLORFGBG`; a background refinement then asks the
+  terminal itself (CSI `?996n` color-scheme query, falling back to an OSC 11
+  background-color query — both answered by Ghostty/cmux, kitty and iTerm),
+  and while `auto` stays selected the TUI follows live light/dark switches of
+  the terminal (CSI 997 push notifications) and repaints on the next frame.
 
 ## APPEND_SYSTEM.md
 
@@ -148,18 +167,25 @@ no reload, no watcher.
 ## Install (local)
 
 ```sh
-# build once
-cd dsh-tui-pi && pnpm install && pnpm build
+# build + pack + install into the profile in one step (the recommended dev loop)
+node scripts/dev-install.mjs        # = pnpm build → pnpm pack → refresh the profile's copies
 
-# live development link (recommended; edits to src/ + pnpm build apply on next launch)
-dsh plugin --profile tui add link:/path/to/dsh-tui-pi
-
-# or an npm tarball
-npm pack                                   # → aiwayds-dsh-tui-pi-0.1.0.tgz
-dsh plugin --profile tui add /path/to/aiwayds-dsh-tui-pi-0.1.0.tgz
+# or, manually, like a real user would:
+pnpm pack                            # → aiwayds-dsh-tui-pi-0.2.0.tgz
+dsh plugin --profile tui add /path/to/aiwayds-dsh-tui-pi-0.2.0.tgz
 ```
 
-Both paths auto-add `dsh-tui-pi` to the profile's `dsh.profile.bundles`.
+The profile's `package.json` carries **both** keys pointing at the tarball —
+`dsh-tui-pi` (dsh resolves the bundle by this name) and
+`@aiwayds/dsh-tui-pi` (the loader entry in `cordis.patch.yml` imports this
+name) — and its `pnpm-workspace.yaml` declares the pi-tui
+`patchedDependencies` (see `~/.dsh/profiles/tui/`). At runtime
+`@deepseek-ai/*` resolve through dsh's shared
+`~/.dsh/profiles/node_modules` fallback to the installed closure, so the
+profile never needs the repo's `node_modules`. Known quirk: pnpm does not
+re-read a changed `file:` tarball while its `node_modules` entry exists —
+`scripts/dev-install.mjs` removes the two installed copies before installing,
+which forces the refresh.
 
 ## Use
 
@@ -178,8 +204,103 @@ dsh --profile tui        # or: dsh-tui-pi (bin shim)
   finished child drops off; when nothing is left the panel and the activity
   lines collapse away.
 - `/` opens slash-command autocomplete (Tab/arrows/Enter).
-- Ctrl+C quits — while the agent is mid-turn the first press cancels the turn
-  (`⏹ canceling current turn…`), any further press quits.
+
+## Keyboard shortcuts
+
+App-level keys (key mappings mirror [pi](https://github.com/badlogic/pi-mono)):
+
+| Key | Action |
+| --- | --- |
+| `Enter` | send the prompt |
+| `Esc` | **stop the current task — as a deliberate double-press** — priority chain: a popup that is open closes itself first (Esc inside a popup *never* stops the running task); the editor's autocomplete closes; a mid-turn agent waits for a second `Esc` within 500ms to cancel the whole task (parent + subagents, `⏹ canceling current turn…`; the first press only arms the window and shows a hint); a non-empty editor does **nothing** (anti-misfire); on an **empty** editor a second `Esc` within 500ms opens `/session` |
+| `Ctrl+C` | mid-turn: first press cancels the running turn, second press (within 500ms) quits; idle: first press clears the editor, second press quits. With a popup open it cancels the popup instead. **Held-key auto-repeat never quits** — repeats under 80ms apart are swallowed, and the double-press quit is confirmed for 200ms (a follow-up repeat aborts it, a human-speed re-press fires it immediately) |
+| `Ctrl+D` | quit — only when the editor is **empty**, like pi's `app.exit`; with text it is the regular delete-character-forward |
+| `Ctrl+L` | open the model/think picker (pi's `app.model.select`) |
+| `Ctrl+G` | open the subagent picker while subagents run (see `/subagents`); idle the key falls through untouched. dsh's own mapping — pi spends this key on an external editor we don't have, remap in `keybindings.json` if you miss it |
+| `Tab` | autocomplete |
+
+Editor keys (movement/deletion/undo) come from the pi-tui `Editor` default
+bindings — no dsh code involved: `←→` / `Ctrl+B`/`Ctrl+F` move, `Alt+←→` /
+`Ctrl+←→` / `Alt+B`/`Alt+F` word-move, `Home`/`End` / `Ctrl+A`/`Ctrl+E` line
+edges, `PageUp`/`PageDown` scroll, `Backspace` / `Delete`/`Ctrl+D` delete,
+`Ctrl+W`/`Alt+Backspace` delete word back, `Alt+D` delete word forward,
+`Ctrl+U`/`Ctrl+K` delete to line start/end, `Ctrl+-` undo, `Ctrl+Y`/`Alt+Y`
+yank, `Shift+Enter`/`Ctrl+J` newline. `↑` / `↓` follow this interplay: on the
+first line `↑` moves the cursor to the line start, whereas on an **empty**
+editor (or with the cursor at the line start) it browses history instead (next
+paragraph).
+
+`↑` / `↓` browse the submitted-message history shell-style. `↑` recalls the
+most recent prompt and walks further back; `↓` moves forward again, and past
+the newest entry it restores your in-progress draft. Browsing starts when the
+cursor is at the start of the first line — including on an empty editor — and
+the text you were leaving is preserved as the draft, so `↓` all the way back
+hands you the draft again. The history holds up to **500 entries**, dropping
+the oldest ones beyond that; it survives a theme hot-swap (the editor is
+rebuilt on switch). The history is in-memory for the current TUI run — it does
+**not** survive `/reload` or a restart. Submitted slash commands (`/theme`,
+`/hotkeys`, …) are recorded too. Recalling a multi-line entry places the
+cursor at its start; `↓` then walks the entry's lines before advancing the
+history — but a single-line entry round-trips identically (do not fight the
+pi-tui behavior).
+
+Not supported yet (documented status): `Ctrl+O` collapse tool output, `Ctrl+X`
+copy the last assistant message, `Alt+Enter` follow-up queue, `Ctrl+V` paste
+image, `Ctrl+Z` suspend, `Ctrl+P`/`Ctrl+Shift+P` model cycle, `Shift+Tab` think
+cycle, `Ctrl+T` collapse thinking.
+
+### Subagent viewer & fine-grained control
+
+`Ctrl+G` (or `/subagents`) opens an 80% picker over the tracked children —
+running ones first (spinner, mode, rounds against `maxRounds`, tokens,
+elapsed), then the five most recently settled. Enter opens the transcript
+viewer: one readable line per buffered child event (user/assistant messages,
+tool calls paired with truncated results, turns, todos), refreshing ~3x/s
+with tail-follow (scroll up to detach, reach the bottom to re-attach), and a
+truncation note when the per-child 2000-event ring buffer dropped its head.
+`Esc` closes; a deliberate double-`x` within 500ms closes too.
+
+Two caps steer delegation (configure in `/agents` → `l`, both live-read at
+every decision):
+
+- **`maxAgents`** (default 4, `0` = unlimited) — a `tools.guard` denies
+  model-facing spawn tools (`subagent`, `subagent_fork`, `workflow`, `ralph`,
+  `use_agent`) once that many children run, with the running labels in the
+  deny reason so the model can wait or `list_agents`. The cap is approximate
+  under a burst of parallel spawns; workflow fan-out (which bypasses the tool
+  pipeline) is pruned after the fact on `subagent/start`.
+- **`maxRounds`** (default 50, `0` = unlimited) — when a child's completed
+  turns reach the cap, the TUI queues one wrap-up request
+  ("总结和结束这个任务，汇报情况。") as its next turn — it never interrupts
+  work underway, never repeats per child, and never re-awakens a child that
+  already settled. There is deliberately **no force stop**.
+
+### Custom keybindings
+
+The five app-level keys are remappable through `$DSH_HOME/keybindings.json`
+(`~/.dsh/keybindings.json` by default) — pi's
+`~/.pi/agent/keybindings.json` convention. The file is a **partial** map of
+the app keys to pi-tui key ids; anything missing keeps its default. Key id
+format: `modifier+key`, modifiers `ctrl`/`shift`/`alt`/`super` (combined with
+`+`), key a letter/digit/symbol or a named key (`escape`, `enter`, `tab`,
+`space`, `backspace`, `delete`, `home`, `end`, `pageUp`, `pageDown`, arrows,
+`f1`–`f24` …).
+
+```json
+{
+  "escape": "ctrl+x",
+  "ctrlC": "alt+c",
+  "ctrlD": "ctrl+w",
+  "modelPicker": "ctrl+m"
+}
+```
+
+The file is read when the TUI starts. You can edit it by hand (then
+`/reload`) — or use `/hotkeys`, which shows the effective table in the same
+select-panel style as `/agents`: each app key is a row (custom overrides
+starred), `Enter` prompts for a new key id (empty input resets the key to its
+default), and a commit **writes the file and applies the change live** — no
+`/reload` needed. Invalid entries never block: they warn and keep the default.
 
 ## Performance rules (from the pi-turbo findings)
 
@@ -217,7 +338,7 @@ dsh-tui-pi avoids both by construction:
 ```sh
 pnpm check    # tsc --noEmit
 pnpm build    # emit lib/
-pnpm test     # unit tests, node --test against lib/ (185 tests, pretest builds)
+pnpm test     # unit tests, node --test against lib/ (296 tests, pretest builds)
 ```
 
 Local type-checking symlinks `node_modules/@deepseek-ai/*` to the installed
@@ -225,23 +346,13 @@ dsh closure (`/opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules`);
 at runtime those imports resolve to the same module instances the running dsh
 uses. Those symlinks stay out of any tarball (`files` ships lib/bin/patch only).
 
-⚠️ `pnpm install` regenerates the three type-check symlinks declared in
-`package.json` (`dsh-settings`, `dsh-client-schema-form`, `schemastery`)
-into local `.pnpm` copies, splitting the cordis module identity and breaking
-`pnpm check` — after any install, re-link them:
-
-```sh
-ln -sfn /opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/{dsh-settings,dsh-client-schema-form,schemastery} node_modules/@deepseek-ai/
-```
-
-`dsh-permission-presets` is a fourth, undeclared type-check link — the same
-extraneous-closure pattern as `cordis`/`dsh-agent` above: `pnpm install`
-never regenerates it (it is not in the dependency tree), but a wiped
-`node_modules` needs it re-created by hand:
-
-```sh
-ln -sfn /opt/homebrew/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-permission-presets node_modules/@deepseek-ai/
-```
+`scripts/link-dsh-closure.mjs` (the package's `postinstall`) re-creates every
+`node_modules/@deepseek-ai/*` link to the global dsh closure after **each**
+`pnpm install`/`patch-commit`, and is a no-op without a global dsh install.
+That keeps a single `@deepseek-ai/cordis` module identity in the type graph
+(declaring any of them in `package.json` would make pnpm install a second
+local copy and break the cordis `settings` augmentation). A wiped
+`node_modules` self-heals on the next `pnpm install`.
 
 **pi-tui patch**: this plugin applies a small patch to the pinned
 `@earendil-works/pi-tui` 0.84.2 (`pnpm.patchedDependencies` in
@@ -262,7 +373,8 @@ src/
   index.ts          cordis plugin entry + wiring: command registration, footer,
                     git watcher, clock, bridge, theme hot-swap sink, shutdown
   tui.ts            TUI bootstrap: alt-screen tree, transcript ScrollView,
-                    dock (status/editor/last-request/footer), editor rebuild
+                    dock (status/editor/last-request/footer), editor rebuild,
+                    app-owned canvas background (patched pi-tui)
   session.ts        DshSessionBridge: lazy agent create, followup, resume,
                     replay, cancel, O(1) incremental stats, persistDefaultModel,
                     subagent tracker (tool-workflow + child events → live rows)
@@ -280,6 +392,16 @@ src/
   editor.ts         CwdBorderEditor (top border: 📁 cwd │ ⎇ branch)
   git.ts            GitBranchWatcher (polled, cached)
   frame.ts          FramedOverlay: shared top/bottom ─ border for every popup
+  panels.ts         select-panel framework: TablePanel/FieldPanel/ViewerPanel/
+                    PanelHost + padCell/columnWidths/ListController
+  keymap.ts         pure key-action decision (resolveKeyAction) — Esc/Ctrl+C/
+                    Ctrl+D/Ctrl+L/Ctrl+G chains with double-press guards
+  hotkeys.ts        keybindings.json contract + validation + /hotkeys manager
+  agent-manager.ts  agent markdown files: parse/validate/write-back engine +
+                    ~/.zcode/agents seeding, `deep` policy
+  agents.ts         /agents table + fields window + subagent limits panel
+  subagent-policy.ts  maxAgents guard + maxRounds wrap-up injection (read live)
+  subagent-viewer.ts  Ctrl+G picker + live transcript panel (300 ms tick)
   provider-catalog.ts  built-in provider directory (36 llm-pi-ai catalog
                     routes, mirrors the web Models page) + deriveKeyRef + row
                     views (pure data/functions for the Models add-provider flow)
@@ -294,22 +416,34 @@ src/
   sessions.ts       /session info panel + /resume persisted-session picker
   settings.ts       /settings browser: categories, schema walk, inline editors,
                     serialized mutate write chain, add-provider flow
+  welcome.ts        startup whale banner (WHALE_ART + PIXEL_FONT glyphs)
+  quotes.ts         startup quote pool
+  append-system.ts  APPEND_SYSTEM.md support + todo-lifecycle section
+                    maintenance (idempotent, atomic)
   theme/
     palette.ts      GitHub light/dark palettes + terminal-background detection
+                    (rgbIsLight luminance)
     index.ts        buildTheme: Editor/Markdown/SelectList/chat roles, POWERLINE
                     segment palette, resolveTheme (env > preference > detect)
-test/*.test.mjs     unit tests, node --test against lib/ (185 across 15 files)
+test/*.test.mjs     unit tests, node --test against lib/ (296 across 24 files)
 ```
 
-## Status (2026-08-15)
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the release history.
+
+## Status (0.2.0)
 
 All surface commands shipped and tmux-e2e verified: `/model /think /session
-/resume /new /settings /export /theme /reload`; provider-first Models with the
-add-provider flow; overlay chrome (backgrounds + borders); theme hot-switch
-(immediate apply, external-change watch, env pinning); graded Ctrl+C; live
-todos + subagent progress blocks; clean Ctrl+C exit. `pnpm check` clean,
-185 unit tests green, e2e run confirmed the settings/credentials files are
-restored byte-for-byte.
+/resume /new /settings /export /theme /reload /agents /subagents /hotkeys`;
+provider-first Models with the add-provider flow; overlay chrome
+(backgrounds + borders); theme hot-switch (immediate apply, external-change
+watch, env pinning) with an app-owned canvas background that recolors the
+whole screen; terminal-following `auto` theme; subagent viewer with live
+rounds/tokens/elapsed; subagent `maxAgents`/`maxRounds` limits; pi-aligned
+keybindings with double-press guards; live todos + subagent progress blocks;
+clean Ctrl+C exit. `pnpm check` clean, 296 unit tests green, e2e run
+confirmed the settings/credentials files are restored byte-for-byte.
 
 Known limitations (accepted, pi-tui 0.84.2 constraints):
 

package/lib/agent-manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Agent definitions as markdown files — the dsh terminal counterpart of the
+ * pi fun-agent / zcode "one file per agent" convention.
+ *
+ * An agent is a `<agents-dir>/<name>.md` file with a `---` frontmatter block
+ * and a markdown body that doubles as the agent's system prompt:
+ *
+ *   ---
+ *   name: oldfox
+ *   display_name: 老法师
+ *   description: "顾问角色：review、挑刺、保证健壮性。"
+ *   color: red
+ *   model: volc-ark-plan/glm-5.3
+ *   thinking: high
+ *   deep: 1
+ *   ---
+ *   You are 老法师 — 顾问…
+ *
+ * Frontmatter keys are parsed loosely (`key: value`, optional surrounding
+ * quotes); `name` is required, `description` feeds the picker subtitle,
+ * `model` is a dsh `provider/model` route (the picker rewrites it), and
+ * `deep` caps how many levels of subagents this agent may spawn (default 1,
+ * 0 = never, no unlimited — there is no spelling for unbounded depth).
+ * The body is kept verbatim.
+ */
+/** One agent's frontmatter-derived metadata (the editable surface). */
+export interface AgentMeta {
+    /** File basename without `.md` — required, the stable agent id. */
+    name: string;
+    /** Optional display name, shown before `name` in the picker. */
+    displayName?: string;
+    /** Optional one-line summary shown as the picker subtitle. */
+    description?: string;
+    /** Optional 8-color label (red/blue/green/yellow/purple/orange/pink/cyan). */
+    color?: string;
+    /** dsh model route (`provider/model`); absent = inherit the default. */
+    model?: string;
+    /** Reasoning effort id (off/low/medium/high/max); absent = inherit. */
+    thinking?: string;
+    /** Max subagent spawn depth: default 1, 0 = never spawn children. */
+    deep: number;
+}
+/** A parsed agent file: metadata + the raw system-prompt body. */
+export interface AgentFile {
+    path: string;
+    meta: AgentMeta;
+    body: string;
+}
+/** One parse outcome: a usable agent, or a broken file with a reason. */
+export type AgentParseResult = {
+    ok: true;
+    agent: AgentFile;
+} | {
+    ok: false;
+    error: string;
+};
+/** The dsh agents directory (`~/.dsh/agents`, under the dsh home). */
+export declare function agentsDir(): string;
+/**
+ * The legacy agents directory from the first shipped layout (`~/dsh/agents`,
+ * no dot). Kept only for one-time migration — see `migrateLegacyAgentsDir`.
+ */
+export declare function legacyAgentsDir(): string;
+/**
+ * One-time migration from the legacy `~/dsh/agents` layout into
+ * `~/.dsh/agents`: when the target directory holds no agents but the legacy
+ * one does, every legacy file is copied over. Idempotent.
+ */
+export declare function migrateLegacyAgentsDir(targetDir?: string, legacyDir?: string): number;
+/** zcode agent files are the one-time seeding source (model converted). */
+export declare function zcodeAgentsDir(): string;
+/**
+ * Parse one agent markdown file. Tolerates CRLF, quotes, and non-key lines
+ * inside the frontmatter; `name` is required, `deep` must be a non-negative
+ * integer when present (absent defaults to 1).
+ */
+export declare function parseAgentMarkdown(text: string, path: string): AgentParseResult;
+/** Render an agent back to markdown (frontmatter + blank line + body). */
+export declare function renderAgentMarkdown(meta: AgentMeta, body: string): string;
+/** List agents under `dir` (top level only), broken files reported aside. */
+export declare function listAgentFiles(dir: string): {
+    agents: AgentFile[];
+    broken: Array<{
+        path: string;
+        error: string;
+    }>;
+};
+/**
+ * Frontmatter field updates for one agent file. `undefined` leaves the key
+ * untouched; `null` removes the line (the "inherit" spelling — the agent
+ * falls back to its default); a concrete value writes/replaces the line.
+ */
+export interface FrontmatterUpdates {
+    model?: string | null;
+    thinking?: string | null;
+    deep?: number | null;
+}
+/**
+ * Apply frontmatter updates in place: existing lines are rewritten in place,
+ * missing keys are inserted before the closing fence, `null` removes the
+ * line. CRLF is preserved; a no-op returns without touching the file.
+ * Resolves with an error message, or `undefined` on success.
+ */
+export declare function updateAgentFrontmatter(path: string, updates: FrontmatterUpdates): string | undefined;
+/**
+ * Convert a zcode `custom:<uri-encoded providerId>:<modelName>` model value
+ * to a dsh `provider/model` route for providers we know. Unknown providers
+ * return `undefined` (caller keeps the original line); a value without the
+ * `custom:` prefix is assumed to be dsh format already.
+ */
+export declare function convertZcodeModel(model: string): string | undefined;
+/**
+ * One-time seeding: when `targetDir` holds no agents yet, copy every
+ * parseable zcode agent into it with the model converted to a dsh route.
+ * Idempotent — once any agent exists, nothing is written.
+ */
+export declare function seedFromZcode(targetDir: string, sourceDir?: string): {
+    seeded: number;
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+};
+/** Short file label for diagnostics (kept importable for callers). */
+export declare function agentFileLabel(path: string): string;