|
| 1 | +# Artifacts over ACP |
| 2 | + |
| 3 | +CrewCoder stores model-generated source documents and exposes them to embedding apps over |
| 4 | +ACP. Your app owns its artifact browser, preview sandbox, source editor, and download UI. |
| 5 | +CrewCoder never renders or executes artifact content and does not start a preview server. |
| 6 | + |
| 7 | +This is a CrewCoder ACP extension, not a standard ACP capability or a provider-native |
| 8 | +artifact format. It is implemented by CrewCoder as the ACP **agent** (`crewcoder acp`). |
| 9 | +HTTP model providers, Claude's CrewCoder MCP tools, and Codex's dynamic tools use the same |
| 10 | +artifact tools when running through this adapter. Nested external ACP providers such as |
| 11 | +Grok CLI own their tools and do not receive CrewCoder's artifact tools. |
| 12 | + |
| 13 | +## Discover support |
| 14 | + |
| 15 | +Read `initialize.result._meta["crewcoder/artifacts"]`: |
| 16 | + |
| 17 | +```json |
| 18 | +{ |
| 19 | + "version": 1, |
| 20 | + "listMethod": "session/artifacts/list", |
| 21 | + "readMethod": "session/artifacts/read", |
| 22 | + "writeMethod": "session/artifacts/write", |
| 23 | + "notification": "_crewcoder/artifact_updated", |
| 24 | + "formats": ["html", "svg", "mermaid", "markdown"], |
| 25 | + "maxContentBytes": 524288, |
| 26 | + "maxArtifacts": 100, |
| 27 | + "maxSessionBytes": 16777216 |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +Use the advertised method names. Every request requires `sessionId` and `version: 1`. |
| 32 | +The session must have been opened through `session/new` or `session/load` on the current |
| 33 | +connection. Knowing another session's artifact ID does not grant access to its content. |
| 34 | + |
| 35 | +## App integration |
| 36 | + |
| 37 | +1. Initialize ACP and check the advertised artifact version. |
| 38 | +2. Open or load a session, then call `session/artifacts/list` to populate your browser. |
| 39 | +3. Listen for `_crewcoder/artifact_updated` JSON-RPC notifications; upsert the metadata by |
| 40 | + session and artifact ID. Fetch the latest source when opening or refreshing a preview. |
| 41 | +4. Use `session/artifacts/read` to retrieve the complete document. Route its `format` |
| 42 | + to your renderer; HTML includes self-contained interactive charts and apps. |
| 43 | +5. Save source edits with `session/artifacts/write`, supplying the revision you read. |
| 44 | + On a conflict, fetch the latest source and let the user reconcile it. |
| 45 | +6. For downloads, encode the returned `content` as UTF-8 with the returned `mimeType` |
| 46 | + and an app-chosen safe filename. There is no public file URL or HTTP download endpoint. |
| 47 | + |
| 48 | +Example requests (JSON-RPC envelope omitted): |
| 49 | + |
| 50 | +```json |
| 51 | +{ "method": "session/artifacts/list", "params": { "sessionId": "SESSION", "version": 1 } } |
| 52 | +``` |
| 53 | + |
| 54 | +Returns `{ artifacts: ArtifactMetadata[] }`, without source content. |
| 55 | + |
| 56 | +```json |
| 57 | +{ |
| 58 | + "method": "session/artifacts/write", |
| 59 | + "params": { |
| 60 | + "sessionId": "SESSION", |
| 61 | + "version": 1, |
| 62 | + "title": "Counter", |
| 63 | + "format": "html", |
| 64 | + "content": "<!doctype html><button onclick=\"this.textContent=Number(this.textContent)+1\">0</button>" |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +Omit `id` and `expectedRevision` to create. The result is `{ artifact: Artifact }`. |
| 70 | + |
| 71 | +```json |
| 72 | +{ |
| 73 | + "method": "session/artifacts/read", |
| 74 | + "params": { "sessionId": "SESSION", "version": 1, "id": "ARTIFACT_ID" } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +Returns `{ artifact: Artifact }`, including the complete `content`. |
| 79 | + |
| 80 | +```json |
| 81 | +{ |
| 82 | + "method": "session/artifacts/write", |
| 83 | + "params": { |
| 84 | + "sessionId": "SESSION", |
| 85 | + "version": 1, |
| 86 | + "id": "ARTIFACT_ID", |
| 87 | + "expectedRevision": 1, |
| 88 | + "title": "Counter", |
| 89 | + "format": "html", |
| 90 | + "content": "<!doctype html><button onclick=\"this.textContent=Number(this.textContent)+2\">0</button>" |
| 91 | + } |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +Updates replace the entire source, title, and format. They retain the ID and creation time |
| 96 | +and increment `revision`. Only the latest source is retained; revision numbers provide |
| 97 | +conflict detection, not historical source retrieval. |
| 98 | + |
| 99 | +### Artifact shape |
| 100 | + |
| 101 | +```ts |
| 102 | +type ArtifactFormat = "html" | "svg" | "mermaid" | "markdown"; |
| 103 | + |
| 104 | +type ArtifactMetadata = { |
| 105 | + id: string; // CrewCoder-generated opaque ID |
| 106 | + title: string; // 1–200 characters, no control characters |
| 107 | + format: ArtifactFormat; |
| 108 | + mimeType: string; |
| 109 | + revision: number; // starts at 1 |
| 110 | + byteSize: number; // UTF-8 content bytes |
| 111 | + createdAt: string; // ISO timestamp |
| 112 | + updatedAt: string; // ISO timestamp |
| 113 | +}; |
| 114 | + |
| 115 | +type Artifact = ArtifactMetadata & { content: string }; |
| 116 | +``` |
| 117 | + |
| 118 | +| Format | MIME type | Suggested download extension | |
| 119 | +| --- | --- | --- | |
| 120 | +| html | text/html | .html | |
| 121 | +| svg | image/svg+xml | .svg | |
| 122 | +| mermaid | text/vnd.mermaid | .mmd | |
| 123 | +| markdown | text/markdown | .md | |
| 124 | + |
| 125 | +### Notifications and recovery |
| 126 | + |
| 127 | +A successful write stores the source before sending this notification: |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + "jsonrpc": "2.0", |
| 132 | + "method": "_crewcoder/artifact_updated", |
| 133 | + "params": { |
| 134 | + "sessionId": "SESSION", |
| 135 | + "version": 1, |
| 136 | + "action": "created", |
| 137 | + "artifact": { |
| 138 | + "id": "ARTIFACT_ID", |
| 139 | + "title": "Counter", |
| 140 | + "format": "html", |
| 141 | + "mimeType": "text/html", |
| 142 | + "revision": 1, |
| 143 | + "byteSize": 95, |
| 144 | + "createdAt": "2026-10-27T12:00:00.000Z", |
| 145 | + "updatedAt": "2026-10-27T12:00:00.000Z" |
| 146 | + } |
| 147 | + } |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +`action` is `created` or `updated`. Notifications contain metadata only. They are live |
| 152 | +hints, not a replay log: re-list after reconnect or load. A disconnected client can miss |
| 153 | +a notification even though the write committed. After an uncertain update outcome, read |
| 154 | +the artifact before retrying; after an uncertain create outcome, list before creating again. |
| 155 | + |
| 156 | +Artifact validation errors use JSON-RPC code `-32602` with `error.data.artifactCode`: |
| 157 | +`invalid`, `not_found`, `conflict`, `limit`, or `busy`. Storage/transport failures retain |
| 158 | +the normal ACP internal error path. A conflicting write leaves the stored source unchanged. |
| 159 | +A concurrent writer receives `busy` and may retry after re-reading. |
| 160 | + |
| 161 | +## Model behavior and permissions |
| 162 | + |
| 163 | +Normal ACP sessions expose `artifact_write`, `artifact_read`, and `artifact_list` in |
| 164 | +the model's tool catalog. Ask the model to create an artifact rather than merely write |
| 165 | +HTML into a chat code fence. The write tool accepts the same document fields as the app |
| 166 | +endpoint and requires the latest `expectedRevision` on updates. |
| 167 | + |
| 168 | +Model writes use the existing approval, cancellation, workflow, and tool-event paths. |
| 169 | +They are mutations, so review mode requests permission and deliberate CrewCoder mode |
| 170 | +requires its normal plan approval. App-initiated writes are explicit host operations |
| 171 | +and do not prompt the model's approval channel. |
| 172 | + |
| 173 | +The `hosted-text-only` policy excludes these model tools and refuses artifact write RPCs. |
| 174 | +Hosts using that policy can supply their own artifact tools with distinct names through |
| 175 | +[client-hosted tools](CLIENT_TOOLS.md); the existing host authority stays intact. |
| 176 | +The three CrewCoder artifact tool names are reserved and cannot be shadowed by host tools. |
| 177 | + |
| 178 | +Virtual workspace sessions may use artifact storage: these are explicitly owned CrewCoder |
| 179 | +state documents, never reads/writes of the host's workspace. Source documents contain no |
| 180 | +workspace paths and cannot cause CrewCoder to fetch files or run commands. |
| 181 | + |
| 182 | +## Storage and limitations |
| 183 | + |
| 184 | +Artifacts live at `<CREWCODER_HOME>/artifacts/<sessionId>/<artifactId>.json`, outside |
| 185 | +workspace directories and session-prune's disposable files. New artifact directories use |
| 186 | +mode `0700`; source records use `0600`. Writes use an atomic rename under a per-session |
| 187 | +writer lock. Source is limited to 512 KiB per artifact, 100 artifacts and 16 MiB of current |
| 188 | +source per session. UTF-8 bytes determine these limits. |
| 189 | + |
| 190 | +A crash can leave a `.write-lock` directory. Writes fail closed with `busy`; an operator |
| 191 | +must confirm no writer is active and clear the stale lock before retrying. Limits and |
| 192 | +symlink checks also apply when reading persisted records. |
| 193 | + |
| 194 | +The ordinary ACP session lifecycle still applies: `session/new` allocates an ID, and |
| 195 | +the first prompt saves the durable transcript. To reconnect with `session/load`, that |
| 196 | +transcript must already exist. Artifacts survive normal process restarts and compaction |
| 197 | +under the same session ID. They are not copied by session branching, export, or bundles, |
| 198 | +and session deletion/pruning does not automatically remove this separate artifact store. |
| 199 | +There is currently no artifact delete RPC or revision-history API. |
| 200 | + |
| 201 | +Only single text documents are supported. Multi-file bundles, binary images, React/TSX |
| 202 | +compilation, package installation, external asset resolution, and rendering are not provided. |
| 203 | +For charts or apps, models should produce self-contained HTML with inline CSS/JavaScript. |
| 204 | + |
| 205 | +## Preview trust boundary |
| 206 | + |
| 207 | +Treat all source and metadata as untrusted. Your app must render HTML/SVG in an isolated |
| 208 | +preview that has no Node/Electron integration, app privileges, filesystem access, credentials, |
| 209 | +or privileged IPC bridge. Keep script execution out of the app's origin, deny navigation and |
| 210 | +network access by default, and expose only narrowly defined preview capabilities. Sanitize |
| 211 | +Markdown and configure diagram rendering safely. Display titles as text. |
| 212 | + |
| 213 | +CrewCoder stores source exactly as supplied; it does not sanitize it or certify that it is |
| 214 | +safe to execute. The preview renderer and its security tests belong to the embedding app. |
0 commit comments