zidane 7.0.14 → 7.0.16

package/docs/ARTIFACTS.md

@@ -0,0 +1,130 @@
+# Session artifacts
+
+An **artifact** is a durable, typed pointer to something a session produced outside its transcript: a pull request, a branch, a commit, a created file, a deployment, an issue. The session stores the locator and small metadata; the content stays where it lives.
+
+- **Model / store:** `src/session/artifacts.ts`, `SessionStore` artifact methods in `src/session/index.ts`
+- **Producers:** the `metadata.artifacts` tool-result namespace, lifted by `src/loop.ts`
+- **Kinds:** `src/extensions/builtin-artifact-kinds.ts` + `ctx.registerArtifactKind`
+- **Surfaces:** TUI `/artifacts` · GUI Artifacts modal · sessions-list badge · `#pr` completion
+- **IPC:** `sessions.artifacts`, `artifacts.list` / `delete` / `upsert`; signals `artifact:recorded`, `artifact:changed`
+
+Contents: [Model](#model) · [Producers](#producers) · [Storage](#storage) · [Extension API](#extension-api) · [Surfaces](#surfaces) · [IPC](#ipc) · [Lazy refresh](#lazy-refresh) · [Known gaps](#known-gaps)
+
+## Model
+
+```ts
+interface SessionArtifact {
+  id: string            // uuid, stable across upserts
+  sessionId: string
+  runId?: string        // producing run (a subagent's own run id)
+  turnId?: string       // producing loop turn — the transcript anchor
+  kind: string          // open string: 'pull_request' | 'branch' | 'commit' | 'file' | '<ext>.<kind>'
+  uri: string           // canonical locator: URL, file://<abs>, git:commit:<sha>, git:branch:<name>
+  label: string         // human line; the rendering fallback
+  projectRoot?: string  // where it landed (may differ from the session's root)
+  meta?: JsonValue      // kind-specific, ≤ 16 KB
+  createdAt: number
+  updatedAt: number
+}
+```
+
+| Rule | Value |
+|---|---|
+| Identity | `(sessionId, kind, uri)`. Re-emitting upserts: keeps `id` / `runId` / `turnId` / `createdAt`, refreshes `label` / `meta` / `projectRoot` / `updatedAt`. |
+| Cap | 200 per session. On overflow, `file` artifacts are evicted first, oldest first. |
+| Bounds | `kind` `[\w.:-]+` ≤ 64 chars · `uri` ≤ 2048 · `label` ≤ 512 (clipped) · `meta` ≤ 16 KB (dropped, artifact kept). |
+| `projectRoot` | Defaults to the session's root. `file` artifacts get the git root of the landed path when the execution runs on the host (`process` handle); docker/remote paths keep the session default. |
+| Subagents | Land on the shared parent session under the child's `runId`. |
+| Unknown kinds | Always render as `label` + `uri`. Rows are never dropped because a kind's extension is gone. |
+
+Artifacts are **not** part of `SessionData`: `load()` / `save()` / export / compaction / ACP never see them.
+
+## Producers
+
+All three paths converge on one channel — the reserved `artifacts` key of tool-result metadata — so bounds, normalization, and hooks are identical.
+
+| Path | How |
+|---|---|
+| **Tool-result metadata** | Any `tool:transform` hook appends `SessionArtifactInput[]` to `ctx.metadata.artifacts`. After the tool settles, the loop normalizes each entry (`normalizeArtifactInput`), canonicalizes `file:` URIs against the execution cwd, and calls `session.addArtifact`. ≤ 50 entries per tool result. |
+| **Built-in detectors** (`artifactsPreset`) | Keyed on the command or tool name, never on free text: `gh pr create` / `glab mr create` / `*create_pull_request` → `pull_request` · `git commit` → `commit` · `git switch -c` / `checkout -b` / `push -u` → `branch` · `write_file` that *creates* → `file`. Composed under every TUI / daemon / GUI profile; SDK users opt in with `composePresets(artifactsPreset, …)`. |
+| **`record_artifact` tool** | Explicit path for what detection can't see: a PR opened from a background shell task, a deployment URL, an issue. Input `{ kind, uri, label?, meta? }`; the preset's detector reads the input and emits it. |
+
+Emission is best-effort: a store failure never fails the tool call, and the persisted turn / wire payload are byte-identical with or without artifacts. Each stored artifact fires `artifact:recorded` (`child:artifact:recorded` when bubbled from a subagent).
+
+## Storage
+
+`SessionStore` gains three **optional** methods; stores that omit them (file-map, remote, third-party) keep working and `Session.addArtifact` no-ops.
+
+```ts
+upsertArtifact?(artifact: SessionArtifact): Promise<SessionArtifact | null>   // null: unknown session
+listArtifacts?(filter?: { sessionId?, projectRoot?: string | null, kind?, uri?, since?, limit? }): Promise<SessionArtifact[]>
+deleteArtifact?(sessionId: string, artifactId: string): Promise<void>
+```
+
+`Session` exposes `addArtifact(input, { runId?, turnId? })` and `listArtifacts(filter)`. `SessionMetaRow.artifactCount?` powers badges without a `load()`.
+
+**SQLite:** an additive `artifacts` table (FK → `sessions` with `ON DELETE CASCADE`, unique `(session_id, kind, uri)`, indexes on session / project+kind / kind+uri). Created after `migrate()` with `CREATE TABLE IF NOT EXISTS`; `user_version` is unchanged (4), so older builds sharing the DB keep working. `projectRoot: null` in a filter selects untagged sessions; omitting it ignores the axis.
+
+## Extension API
+
+```ts
+ctx.registerArtifactKind({
+  kind: 'coolify.deployment',
+  label: 'Deployment',
+  detect?: ({ tool, input, result, isError }) => ArtifactDetection | ArtifactDetection[] | undefined,
+  validateMeta?: (meta) => boolean,      // failing → meta dropped, artifact kept (own detections only)
+  render?: (artifact) => { title, subtitle?, href?, status? },
+  resolve?: async (artifact) => ({ label?, meta? }),   // lazy refresh, see below
+})
+ctx.tui.registerArtifactRenderer({ kind, renderDetail: artifact => <Pane /> })   // TUI detail pane
+ctx.artifacts.list({ scope: 'session' | 'project' | 'all', kind?, since?, limit? })
+ctx.artifacts.find(kind, uri)                                                    // reverse lookup across sessions
+ctx.registerHook('artifact:recorded', ({ artifact, runId, turnId }) => …)
+```
+
+- Kinds are a global namespace; first registration wins (logged). Built-ins use the same API and can be refined by an extension re-registering the kind.
+- `detect` rides `tool:transform` and `child:tool:transform` but can only append to `metadata.artifacts`; it never changes what the model sees. A throwing detector emits nothing.
+- `ctx.artifacts` is late-bound (like `ctx.sessions`): `[]` when detached or when the store lacks artifact support.
+- Row presentation goes through `renderArtifactRow(artifact, registry)`: registry kind → built-in kind → `label` + `uri` fallback. A throwing `render` falls back.
+
+Authoring example: [EXTENSIONS.md → Session artifacts](./EXTENSIONS.md#session-artifacts).
+
+## Surfaces
+
+| Surface | Behavior |
+|---|---|
+| `/artifacts [project]` | TUI opens the modal; daemon / GUI hosts without a modal emit a markdown list. Session scope by default. |
+| TUI modal (`ctrl+shift+a`) | Grouped by kind (built-ins first). `↵` open href (browser / editor) · `tab` session ↔ project · `c` copy locator · `d` remove. Re-queries on `artifact:recorded` / `artifact:changed`. Extension `renderDetail` mounts under the list in an error boundary. |
+| GUI modal (`⌃⇧A`) | Same scopes; rows pre-rendered main-side (`artifacts:list` IPC) so the renderer stays node-free. Hover → copy / remove. |
+| Sessions list | `N artifacts` badge from `artifactCount` (hidden at 0 or when the store doesn't report it). |
+| `#` completion | Shares the trigger with chats. `#pr` / `#br` / `#file` rank by kind alias; selecting inserts the locator as plain text (no reference grammar). |
+
+Reads are **daemon-authoritative** when a daemon is attached (`sessions.artifacts` / `artifacts.list`); the window's own store handle is used only in the local runtime or against a pre-artifact daemon.
+
+## IPC
+
+| Method / signal | Purpose |
+|---|---|
+| `sessions.artifacts { sessionId, kind?, limit? }` | One session's artifacts, newest first |
+| `artifacts.list { projectRoot?, kind?, uri?, since?, limit? }` | Cross-session query; `projectRoot: null` = untagged |
+| `artifacts.delete { sessionId, artifactId }` | Remove; fans out `artifact:changed` |
+| `artifacts.upsert { artifact }` | Lazy-refresh write-back; input re-normalized; fans out `artifact:changed` |
+| `artifact:recorded { sessionId, artifact }` | The loop stored an artifact |
+| `artifact:changed { sessionId, op: 'delete' \| 'upsert', artifactId, artifact? }` | Host-side mutation |
+
+All additive: a pre-artifact daemon rejects the methods and clients treat that as empty.
+
+## Lazy refresh
+
+`resolve()` is never polled. UIs call it once per focused row per open (`refreshArtifact(artifact, registry)`), persist the patched row through the store or `artifacts.upsert`, and the change signal re-converges other windows. The built-in `pull_request` resolver queries the GitHub API (bearer token from `GITHUB_TOKEN` / `GH_TOKEN` when set, 4 s timeout), writes `meta.state` (`open` / `draft` / `merged` / `closed`), `title`, `resolvedAt`, and skips terminal states and entries fresher than 5 minutes.
+
+## Known gaps
+
+- **PR / commit / branch attribution.** Detected from shell output, these carry no local path, so `projectRoot` is the session's root; `cd ../other && gh pr create` files under the current project. Fix needs the execution cwd on the detect outcome plus `cd` parsing, or an `owner/repo` → checkout map.
+- **Staleness.** `git commit --amend` records a second commit; deleted files/branches persist until removed (`d` / `×`).
+- **Remote / file-map stores** don't implement artifacts (by design); everything degrades to empty.
+- **Background shells.** Output that never reaches a tool result isn't detected; `record_artifact` is the model's escape hatch.
+
+## Tests
+
+`test/session-artifacts.test.ts` (stores) · `test/loop-artifacts.test.ts` (lift + canonicalization) · `test/extensions/artifacts.test.ts` (kinds, detectors, `record_artifact`, `resolve`) · `test/chat/artifacts-view.test.ts` · `test/chat/completion-artifacts.test.ts` · `test/tui/artifacts-modal.test.tsx` · `test/tui-daemon-runtime.test.ts` · `test/ipc-daemon.test.ts` · GUI: `engine.artifacts.test.ts`, `ArtifactsProvider.test.tsx`.