<!-- Source: https://console.uubright.com/docs/artifacts/ -->
# Artifacts

An agent can publish a file from its task workspace with the `ccr-artifacts` MCP
tool `publish_artifact`. Give it a workspace-relative path, a `./`-prefixed path,
or an absolute path inside that workspace, plus a `title`; `kind` and
`provenance` are optional. Kinds are video, image, pdf, slides, markdown and file.
The extension determines the kind when omitted. Each publication starts as
**ready**. Publishing the same title again creates the next version; old versions
remain available in the task and the workspace's **Deliverables** page (called
Outputs or the Library before). Deliverables shows the newest published version per
title; earlier versions are behind the item's **Versions** control. The owner can
approve each published version independently.

## Deliverable states

Each version has a state, derived from what happened to it. The API reports it as
`state`; nothing new is asked of the agent.

| State | `state` | How it gets there |
|---|---|---|
| Draft | `draft` | A file in `.ccr/artifacts/` that the task hasn't published (`status: "draft"`). |
| Needs review | `needs-review` | The task published it (`status: "ready"`). Every new version starts here. |
| Approved | `approved` | You approved it (`status: "approved"`, `approvedAt`). |
| Published | `published` | You marked an approved version as gone out: posted, merged or sent (`publishedAt`, and `publishedUrl` if you gave a link). |

Versions only move forward, and only through approval: a draft or a version that
needs review can't be marked published. On the Deliverables page, a row of
filters counts each deliverable once, by its newest version. **Approve** and
**Mark published…** are on the cards and in a version's preview. Marking
published asks for an optional link to where it went. This records that you
shared it elsewhere; it does not upload or post the file. In every task or chat,
deliverables start as a compact title and state on desktop and phone. Choose
**Show preview** to review the output. Expanded previews scroll within a bounded
area so the conversation and reply box remain usable. Approving a version folds
the preview automatically; **Show preview** opens it again whenever you need it.
Library previews remain available for a larger review.

Artifact versions point to files in the task workspace. The server records the
entry file's size, modification time and inode at publication. If any of these
change, an old version returns HTTP 410 and asks the agent to publish again;
use a new path for a revised output. Approval records the owner's decision about
that version; it does not copy the files into immutable storage. For an HTML
slides deck, this change check protects the entry file only. Its asset files are
checked for safe serving but can change, so keep the whole deck directory
unchanged after publication.

Files under `.ccr/artifacts/` are scanned at startup or after a turn. Eligible
unpublished files appear behind a collapsed **N unpublished files** control in
Deliverables and the artifact-first task view. Drafts have version 0, can be previewed
through a capability URL, and cannot be approved until published. A published
path disappears from drafts and invalidates its draft preview URL. Files inside
the directory of a published slides deck are treated as deck assets, including
audio, images and scripts, so they do not appear as separate drafts. Scanned
audio (`.wav`, `.mp3`, `.m4a`, `.aac`, `.flac`), frame and contact-sheet images,
and intermediate files such as `.json`, `.log`, `.txt`, `.vtt`, scripts and fonts
are also omitted from draft listings. Explicitly publishing any of these files
still makes it an output. The scan is limited to four directory levels and 200
files per task.

The artifact-first task view places the newest published video first, followed
by a published slides deck and then other published outputs. Drafts stay behind
the unpublished-files control below published outputs.

The owner or a paired device can list a task's outputs with
`GET /api/sessions/:id/artifacts`, or a workspace's outputs with
`GET /api/artifacts?workspace=<id>`; the latter accepts `kind` and `task` filters.
`GET /api/artifacts/:id` returns one record. `POST /api/artifacts/:id/approve`
approves a published version. `POST /api/artifacts/:id/published` with an
optional `{"url": "https://…"}` marks an approved version published; it returns
409 for a version that isn't approved. `POST /api/artifacts/:id/url` mints a one-hour URL
for viewing or downloading that version. These API routes require owner or paired
device authentication. Drafts can mint preview URLs, but approval returns 409.

The URL authorizes only that artifact id and expires after one hour. File serving
rechecks the path against the task workspace, follows symlinks to detect escapes,
requires a regular file and enforces the size limit (2 GiB by default; set
`CCR_CLOUD_ARTIFACT_MAX_BYTES` on the server to change it). HTML and SVG responses
have a sandbox Content Security Policy with an opaque origin. An HTML slides
entry in its own directory may load files from that directory and its children
under the same signed URL. The server checks every asset again, rejects directory
listings and paths that leave either the deck directory or the task workspace,
and gives the deck scripts no fetch/XHR access. Decks can load HTTPS scripts,
styles, fonts and images from a CDN. A slides entry at the task workspace root
can serve only its entry file; put the entry and assets in a dedicated directory.
Media requests
support a single byte range for seeking. Unknown files download as attachments.

Over the [uuBright relay](https://console.uubright.com/docs/relay-managed/#files-over-the-relay), a phone opens
files up to 2 MiB (including a deck's folder) through the encrypted channel, even
without relay file storage. Larger files use encrypted relay storage when available.
The same checks apply: a changed entry returns 410, and decks run in a sandbox.
Files above 256 MiB, or above 2 MiB when storage is unavailable, open over direct access.

## Office files

A published `.pptx`, `.docx` or `.xlsx` opens as a file card with its name, size and
slide, sheet or page count (read from the file's own package, nothing is run) and a
**Download** link. When previews are turned on, the card also shows the file's pages:
a large view of the selected slide or page and a strip of every page below it; tap one
to see it large. **Open as PDF** opens the whole converted file. Otherwise the card says
how to turn previews on.

Previews are **off by default**. Making one means running LibreOffice on a file an
agent wrote, so you turn it on per computer: install LibreOffice and start the console
with `CCR_CLOUD_OFFICE_PREVIEW=1`. The console looks for `soffice` (or `libreoffice`)
on its `PATH`, or uses `CCR_CLOUD_SOFFICE_BIN` if you set it to the full path of
`soffice`. Page images also need `pdftoppm` (poppler-utils; `CCR_CLOUD_PDFTOPPM_BIN`
to point at it); without it the preview is the PDF. Install them with
`apt install libreoffice poppler-utils` or
`brew install --cask libreoffice && brew install poppler`.

Each published version is converted once, in the background, when it is published
(or first opened), and the result is kept under the server's data directory by the
file's content hash, so republishing the same bytes converts nothing. The first 100
pages get images. A conversion that fails or takes longer than 90 seconds
(`CCR_CLOUD_SOFFICE_TIMEOUT_MS`) is stopped, its whole process group killed, and the
card says why; files over 100 MiB are not converted. Deleting the last task that
published those bytes deletes the preview.

The conversion treats the file as hostile:

- Only a plain OOXML package of the claimed type is converted: it must have
  `[Content_Types].xml` and the type's main part (`ppt/presentation.xml`,
  `word/document.xml` or `xl/workbook.xml`), and nothing from an OpenDocument package
  (`mimetype`, `content.xml`, `META-INF/manifest.xml`, …). LibreOffice is also told
  which import filter to use, so it never sniffs the content and opens, say, an
  OpenDocument file renamed `.pptx`.
- The package check runs in a worker thread with a heap limit and a 20 second limit.
  It refuses zips whose entries overlap, more than 5,000 parts, more than 1 GiB declared
  or 200 MB actually unpacked.
- LibreOffice opens a sanitized copy in a fresh temporary directory, never the
  workspace file. The copy has no macro project (`vbaProject.bin`) or ActiveX parts,
  and every external relationship (linked images and objects, remote templates,
  hyperlinks) is removed, so loading it fetches nothing.
- Each conversion gets a fresh LibreOffice profile that disables macros, blocks
  untrusted links and sets Writer's and Calc's link updates to never (Impress has no
  such setting; the stripped links cover it), and runs with `--headless --norestore`, an
  environment holding only `PATH`, `HOME` and `TMPDIR` (no console secrets), a
  fixed file name and, on Linux, a 2 GiB address-space limit
  (`CCR_CLOUD_SOFFICE_MEMORY_MB`).
- Where the OS allows it, the conversion has no network at all: a new network
  namespace on Linux when unprivileged user namespaces are enabled (Ubuntu 24.04
  restricts them by default, in which case the sanitized copy is the protection), or
  a sandbox profile on macOS.
- The output is untrusted: only files that start with a PDF or PNG signature and stay
  under the size caps are kept, page images are served with a sandbox Content Security
  Policy and `nosniff`, and the app shows them only as images.

Page images are files of the version: over direct access they are served under the
version's signed URL (`…/.preview/page-1.png`), and over the relay they travel sealed
with the file, so a phone shows the same strip. `GET /api/artifacts/:id/preview`
returns the card's facts and the preview's state (`converting`, `ready`, `failed` or
`unavailable` with a hint).

In Docker mode, task files live in Docker volumes that the control plane cannot
read through a host path. Publication records and draft metadata work, but URL
serving returns HTTP 501. Host mode serves files directly. Artifact files remain
in their task workspace; deleting the task removes its records and workspace.

See [Security](https://console.uubright.com/docs/security/) and [Workspaces](https://console.uubright.com/docs/workspaces/).
