zidane 7.2.4 → 8.0.4

package/docs/EXTENSIONS.md

@@ -130,6 +130,9 @@ Three namespaces:
 | `registerPanel({ id, label, icon?, load, subscribe?, onAction? })` | A tab in the side panel (TUI rail / GUI side panel) fed by declarative, JSON-safe content | Renderer-agnostic: the same registration paints in both hosts. See [PANELS.md](./PANELS.md) |
 | `registerArtifactKind({ kind, label, detect?, validateMeta?, render?, resolve? })` | Give meaning to a session artifact kind | Global namespace, first registration wins. See [ARTIFACTS.md](./ARTIFACTS.md) |
 | `artifacts.list(query)` / `artifacts.find(kind, uri)` / `artifacts.record(input)` | Read the artifact store; record one from host-side code (a `/` command that ran `gh pr create`) | Late-bound like `sessions`: reads `[]`, `record` `undefined`, when detached. See [ARTIFACTS.md](./ARTIFACTS.md) |
+| `registerReferences({ id, patterns, surfaces?, resolve })` | Badges for things named in text without a trigger: ticket ids, issue URLs | Patterns are declarative (RegExp source + key template) so every host matches the same way; only a key `resolve` answers paints. See [Text references](#text-references) |
+| `registerBadgeActions({ id, match?, actions, run })` | Right-click items on badges (links, files, commits, PRs, references, session badges), after the built-in copy / add to prompt / open | `run` answers effects (`copy` / `insert` / `open` / `notice`) the host applies. See [Badge actions](#badge-actions) |
+| `mcp?.servers()` / `mcp?.callTool(server, tool, args)` | The user's enabled MCP servers, and calls into their tools outside agent runs (same stored OAuth logins) | Present only with the `'mcp:call'` permission on an enabled extension. See [MCP access](#mcp-access) |
 | `registerRunTransform(fn)` | Rewrite `agent.run()` options before precondition checks | Synchronous, applied in extension order; throws logged under `ZIDANE_DEBUG` and ignored |
 | `registerBehaviorTransform(fn)` | Rewrite resolved behavior (`maxTurns`, retry, budgets) | Run-level `behavior` options re-applied after, so explicit caller choices win |
 | `registerProviderMiddleware(fn)` | Wrap provider instances (tracing, fallback, metrics, policy) | Runs per provider-factory call; `undefined` return = pass-through |
@@ -143,6 +146,8 @@ Three namespaces:
 | `registerConfigCategory(category)` / `registerConfigItem(categoryId?, item)` | Typed settings in `Settings → Extensions` | See [Settings UI](#settings-ui) |
 | `bus?.emit(payload, opts)` / `bus?.onMessage(fn)` | Private cross-window message channel | Present only when the definition declares the `'ipc'` permission; payloads are JSON ≤ 64 KiB |
 
+Two permissions are enforced rather than descriptive: `'ipc'` (`ctx.bus`) and `'mcp:call'` (`ctx.mcp`). Without them the surface is `undefined`.
+
 ### TUI-specific
 
 ```ts
@@ -242,6 +247,8 @@ const size = await ctx.workspace.fileSize('big.log')   // probe before whole-rea
 if (await ctx.workspace.available()) { /* … */ }  // detached ⇒ calls above REJECT, not no-op
 ```
 
+Relative paths resolve against the session's workspace root; absolute paths are used as given. Containment is the execution context's own: a sandbox confines calls to its workspace, the local process context doesn't. With the TUI on the daemon runtime, window-side code (keybindings, palette actions, modals) reaches the same workspace through the host (`sessions.workspace*`), so the calls behave the same in both modes. One difference: an exec `signal` can't cross the socket, so aborting rejects the call at once while the command on the host runs until its own `timeout`.
+
 `/reload` (built-in command) hot-reloads the registry: re-discover, re-import each extension's module graph fresh, re-run `setup`, swap — outgoing teardowns run and the outgoing HUD paint is wiped. Toggling an extension off in Settings hides its paint and mutes notifications immediately; toggling back on restores them.
 
 `onTrigger` receives `{ extensionName, openModal(id), closeModal() }`. Heavy work should hop to its own microtask; the dispatcher is synchronous.
@@ -261,7 +268,7 @@ Extension bindings appear in `Settings → Keybindings` under a trailing **Exten
 
 ### GUI-specific
 
-There is no GUI-only registration surface. Panels are renderer-agnostic (`ctx.registerPanel`, see [PANELS.md](./PANELS.md)); `ctx.gui.registerPanel` is kept as a deprecated alias that forwards there. GUI parity wired today: extension discovery/settings, extension summaries, completion providers, completion submit hooks (`resolveReferences` / `onSubmit`), themes, and panels through IPC.
+There is no GUI-only registration surface. Panels are renderer-agnostic (`ctx.registerPanel`, see [PANELS.md](./PANELS.md)); `ctx.gui.registerPanel` is kept as a deprecated alias that forwards there. GUI parity wired today: extension discovery/settings, extension summaries, completion providers, completion submit hooks (`resolveReferences` / `onSubmit`), themes, panels, text references, and artifact kinds (rows, refresh and session badges render with the registry of the project the artifact landed in) through IPC.
 
 ## How it boots
 
@@ -272,7 +279,7 @@ flowchart TD
   state["loadState(state.json)<br/>→ Settings.enabledExtensions"]
   build["buildExtensionRegistry<br/>(runs setup with disabled filter)"]
   config["resolveConfig<br/>(folds into ResolvedConfig)"]
-  agent["buildAgent / createAgent<br/>(composePresets(extensionPreset, profile.preset))"]
+  agent["host buildActiveRun / createAgent<br/>(composePresets(extensionPreset, profile.preset))"]
 
   scan --> build
   inline --> build
@@ -345,6 +352,7 @@ owner/repo#main:packages/ext      # search a subdirectory (monorepos); pasted tr
 Tahul/zidane:extensions/git-flow    # /commit — agent-written commit messages + one-tap push
 Tahul/zidane:extensions/headroom    # compress large tool outputs via a local Headroom proxy
 Tahul/zidane:extensions/pxpipe      # image tool outputs in-process + optional pxpipe proxy routing
+Tahul/zidane:extensions/linear      # Linear tickets/projects as badges + chat artifacts, via your Linear MCP
 ```
 
 All mirror the packaging conventions to copy for your own extensions (`package.json` with `zidane-extension` keyword, entry `index.ts`, `zidane` as a peer).
@@ -477,6 +485,8 @@ ctx.registerCommand({
 
 `emit` output is display-only (persisted, never sent to the model). A command may also call `ctx.runAgent` for interactive sub-runs, `ctx.generateData` for silent schema-pinned JSON, `ctx.spawnAgents?` for parallel isolated child agents, and `ctx.appendContext?` to persist a model-visible note — the optional surfaces are host-dependent, so guard for bare hosts.
 
+Builtin commands (`/help`, `/reload`) are reserved. An extension command with the same name is dropped. Extension commands beat markdown file commands (see [CHAT.md, Markdown commands and subagents](./CHAT.md#markdown-commands-and-subagents)).
+
 ### A completion provider
 
 ```ts
@@ -562,6 +572,117 @@ export default defineExtension({
 })
 ```
 
+### Session badges
+
+A kind with `badge(artifacts)` gets a badge under the session's title: the GUI sidebar row (with a hover card) and the TUI sessions list. Commits and pull requests are built-in kinds on the same path.
+
+```ts
+ctx.registerArtifactKind({
+  kind: 'acme.ticket',
+  label: 'Ticket',
+  badge: tickets => ({                       // this session's artifacts of the kind, newest first
+    text: tickets[0]!.label,
+    ...(tickets.length > 1 ? { more: tickets.length - 1 } : { href: tickets[0]!.uri }), // ⌘ / ctrl-click opens it
+    icon: { gui: 'i-ph-ticket', tui: '◇' },
+    tone: 'warn',                             // muted | subtle | accent | success | warn | danger
+    order: 30,                                // pull requests 0, commits 10
+    panel: 'tickets',                         // what a click opens; default: the Artifacts panel
+    card: { title: 'Tickets', rows: tickets.map(t => ({ title: t.label, href: t.uri, uri: t.uri })) },
+  }),
+})
+
+ctx.registerPanel({
+  id: 'tickets',
+  label: 'Tickets',
+  load: async ({ focus }) => {                // { kind, uri? }: what the click pointed at
+    const rows = await ctx.artifacts.list({ kind: 'acme.ticket' })   // the session the panel is for
+    return { sections: [{ id: 'all', items: rows.map(r => ({ kind: 'row', title: r.label, href: r.uri, ...(r.uri === focus?.uri ? { status: 'selected' } : {}) })) }] }
+  },
+})
+```
+
+**Clicks.** A click on a badge selects that chat and opens its `panel` (GUI side panel, TUI rail) with `PanelLoadContext.focus = { kind }`; a click on a card row adds the row's `uri`. ⌘-click (GUI) / ctrl-click (TUI) opens the badge's or row's `href` instead. `panel` is a bare id of a panel the same extension registered, a full `<extension>/<id>`, or `'artifacts'`; an id no active extension registered falls back to Artifacts, which brings the badge's kind (or the row) into view. Panel `load` / `onAction` run scoped to the panel's session, so `ctx.artifacts.list()` answers that chat's artifacts in both hosts.
+
+JSON-safe and synchronous; a throw drops the badge, never the row. GUI icons are build-time UnoCSS classes: pick from `BADGE_ICONS` (`gui/src/renderer/src/components/ui/badge-tone.ts`), or the badge shows its text alone.
+
+### Text references
+
+```ts
+ctx.registerReferences({
+  id: 'acme.ticket',
+  patterns: [
+    { regex: 'https://acme\\.dev/t/(\\d+)', key: '$1' },   // URL first: longest match wins at a position
+    { regex: '(?<![\\w-])ACME-\\d+(?![\\w-])' },          // key defaults to the whole match
+  ],
+  surfaces: ['prompt', 'assistant', 'title'],               // default: all
+  resolve: async (key, { signal }) => {
+    const t = await fetchTicket(key, signal)
+    return t ? { label: t.id, status: t.state, title: t.title, href: t.url, tone: 'warn', icon: { gui: 'i-ph-ticket' } } : undefined
+  },
+})
+```
+
+Hosts match the patterns (the GUI renderer included, through `findReferences` in `zidane/chat/pure`), then ask `resolve` for each key; views are cached per `(provider, key)` (5 min, misses 1 min, throws not cached). A key that resolves to `undefined` stays plain text, so broad patterns are safe. GUI today: sent prompts, assistant markdown (prose and links whose whole URL matches; not code), sidebar titles. The TUI does not paint references yet.
+
+A view's `prompt` is what the badge menu's **Add to prompt** inserts (default: the matched text).
+
+### Badge actions
+
+Right-clicking a badge opens its actions: GUI chips in prompts and replies (links, files, branches, `#123` / SHA chips, extension references), sidebar badges and their card rows; TUI sessions-list badges and Artifacts rail rows (a small modal). Each badge describes what it stands for as a `BadgeTarget`:
+
+```ts
+interface BadgeTarget {
+  kind: 'link' | 'file' | 'commit' | 'pull_request' | 'branch' | 'reference' | 'artifact'
+  text: string                                    // what the badge shows
+  href?: string                                   // URL, or absolute path for files
+  prompt?: string                                 // what Add to prompt inserts
+  artifact?: { kind: string, uri: string }        // session badges, card rows, artifact rows
+  reference?: { providerId: string, key: string } // `registerReferences` badges
+  sessionId?: string
+}
+```
+
+Built-ins come first and derive from the target alone: **Copy URL** (web `href`; **Copy path** for files), **Copy SHA** / **Copy** (no web link), **Add to prompt** (`prompt`, else the URL for links, `@path` for files, else `text`; the GUI inserts a file inside the chat's folder as a real mention), **Open in browser** (web `href`; **Open** for files). Feed them through `prompt` on reference views, session badges and card rows rather than overriding them.
+
+Extensions add items after them:
+
+```ts
+ctx.registerBadgeActions({
+  id: 'acme.tickets',
+  match: { kinds: ['reference', 'artifact'], references: ['acme.ticket'] }, // omitted axes match all
+  actions: target => target.reference ? [
+    { id: 'copy-id', label: 'Copy ID', group: 'copy', shortcut: 'I' },     // groups: copy, prompt, open, more
+    { id: 'details', label: 'Add details to prompt', group: 'prompt' },
+  ] : undefined,
+  run: async (actionId, target, { sessionId, cwd, signal }) =>
+    actionId === 'copy-id'
+      ? { copy: target.reference!.key, notice: 'Copied' }
+      : { insert: `> ${await fetchTitle(target.reference!.key, signal)}\n` },
+})
+```
+
+`actions` is synchronous and cheap (it runs on every right-click; the GUI asks main for it while the menu is already showing the built-ins). Items are ordered by group, stable within one; at most eight per registration; a shortcut already taken is dropped. `run` executes where the extension lives (GUI main, TUI in-process), scoped to the badge's chat (`ctx.artifacts`), with an 8 s deadline; a throw comes back as a `notice`. Effects are data: `copy` (clipboard), `insert` (the composer), `open` (a web URL or an absolute path), `notice` (a brief message; the GUI shows it by the pointer, the TUI keeps it in the debug log).
+
+### MCP access
+
+```ts
+export default defineExtension({
+  name: 'tracker',
+  permissions: ['mcp:call'],
+  setup(ctx) {
+    ctx.registerReferences({ id: 'tracker.issue', patterns, resolve: async (key) => {
+      const server = (await ctx.mcp?.servers())?.find(s => s.url?.includes('mcp.linear.app'))
+      if (!server)
+        return undefined                      // not installed / not enabled: nothing paints
+      const { text, isError } = await ctx.mcp!.callTool(server.name, 'get_issue', { id: key })
+      return isError ? undefined : toView(JSON.parse(text))
+    } })
+  },
+})
+```
+
+`servers()` lists the `mcps.json` servers the user enabled for the extension's cwd (`{ name, transport, url?, command?, toolPrefix }`; match tool names in `detect` / hooks with `toolPrefix`). `callTool` uses the server's own tool name, connects on first use with the stored OAuth credentials (non-interactive: a server needing a login rejects), pools the connection per host and closes it after 60 s idle. It rejects when the server is missing, can't connect or lacks the tool, and resolves `{ isError: true }` when the call itself failed. `scope: 'context'` servers are not offered. Hosts pass `createExtensionMcpHost` (`zidane/chat`) as `mcp` to `discoverAndBuildExtensionRegistry`; the TUI, the daemon and the GUI main process do.
+
 ### A keybinding + modal
 
 ```tsx

package/docs/HEADLESS.md

@@ -104,6 +104,8 @@ stderr.**
 **Exit codes:** `0` ok · `1` run error · `2` usage error · `124` timeout ·
 `130` aborted.
 
+Subagents: the builtin `Explore` / `Plan` agents and markdown subagents from `~/.agents/agents` and `~/.zidane/agents` are available to `spawn`. Project agents (`<cwd>/.agents/agents`, `<cwd>/.zidane/agents`) are opt-in with `--project-agents`, because a headless run often targets a repo it did not write and an agent file sets a child's system prompt (its tools stay a subset of the parent's). Pass `--import-foreign-configs` to also load `.claude/agents`: the user-scope `~/.claude/agents` alone, plus the project `.claude/agents` when `--project-agents` is also set. Headless loads no settings, so the flags are the only opt-ins. Pass `--no-markdown-agents` to skip loading entirely: no builtin `Explore` / `Plan`, no file agents, and the `spawn` schema stays as it was before markdown agents existed. `print-tools` applies the same fold as a real run, so it honors all three flags. Load diagnostics print to stderr only when `ZIDANE_DEBUG` is set. Format and precedence: [CHAT.md, Markdown commands and subagents](./CHAT.md#markdown-commands-and-subagents).
+
 Run `bun run headless --help` for the full flag list.
 
 ## Reusable output helpers