Repository navigation
Open
Labels
enhancementNew feature or requestNew feature or request
Description
What problem are you trying to solve?
Agents regularly produce HTML pages (reports, dashboards, one-pagers) and Markdown documents. Today those files only live in the session sandbox. They can be previewed in the chat file preview panel, but they can't be shared, and they disappear with the sandbox.
Users need a way to turn a file from a session into a stable, shareable page that outlives the sandbox and can be updated over time.
Proposed solution
Artifacts: publish an HTML or Markdown file from the file preview panel as a versioned page at /artifacts/<slug>.
Product behavior (v1)
- Publishing starts only from a Publish button in the file preview panel. No agent tool and no chat command.
- Publishing copies the file plus everything it references (CSS, JS, images, data files) out of the sandbox. The server works out this bundle automatically; the dialog shows a read-only summary, not a file picker.
- Sign-in is required to view. Any signed-in user in the tenant can open an artifact; there is no per-artifact access control yet.
- The slug is unique per tenant, chosen by the user or generated from the title. It is immutable and freed when the artifact is deleted.
- Republishing creates version N+1 under the same link.
?version=<n>pins a version. Each version records the session and turn it came from. Publishing identical content is a no-op. - Only the creator or a tenant admin can publish new versions or delete. Delete is a hard delete.
- An Artifacts page lists artifacts and versions, opens the viewer, and links back to the source session (a separate "Open session" button on each row).
- Download gives the raw file for a single-file artifact and a zip for a bundle.
- Limits: 20 files per version, 10 MB per file, 50 MB per version.
Design
- Storage: pluggable blob storage with local disk and S3 (including S3-compatible stores) in v1. A version is a directory tree under
{tenant_id}/{artifact_id}/{artifact_version_id}/{path}, laid out like a static site. A new backend (GCS, Azure) is one adapter. Each version records its backend, so switching from local to S3 doesn't orphan old versions. - Metadata: three tables,
artifact,artifact_versionandartifact_file, on Postgres and SQLite. The file table records what each version contains (for listings, the file tree and change summaries); the blob store holds the bytes. - Bundle collection: the client sends only
session_id,turn_idandentry_path. The server lists sandbox files through a provider-agnostic helper intrueforge-core, then follows references transitively (HTMLsrc/href, CSSurl()/@import, Markdown images and links, and relative path strings in JS/JSON that match existing files). Because the server reads the files itself, provenance can't be forged by the client. - Why not render from
srcDoc: the preview panel usesiframe srcDoc, which has no base URL, so./styles.csscan't resolve. Bundles are instead served from real paths at/artifact-content/<token>/<path>. - Content tokens: the signed-in SPA requests a short-lived (1 hour) HMAC token bound to one version. Cookies don't work because the iframe is sandboxed without
allow-same-origin. Tokens never appear in shareable links; the link is always/artifacts/<slug>. - Security: AI-generated HTML never runs with the app's privileges. The viewer uses
iframe sandboxwithoutallow-same-origin, and every content response sendsContent-Security-Policy: sandbox …,X-Content-Type-Options: nosniffandReferrer-Policy: no-referrer. Paths are normalized and checked on publish and on serve. Content is served on the app's origin in v1. - Why not S3 static website hosting: it only serves public, unauthenticated objects and doesn't help local disk. Presigned URLs drop their signature on relative references. The server proxies files after verifying a token instead. The static-site key layout keeps a later CDN option open without a data migration.
- Versioning flow: compute hashes and skip if unchanged, upload files to the new version prefix, then allocate the version number and insert rows in one short transaction (no remote I/O inside the transaction). Failures clean up the prefix; orphan blobs from a crash are left for a future sweeper.
- Deployment: new
ARTIFACT_*settings, a Helm chart option for a PVC or S3, and a docker-compose volume. Distributed mode requires an explicit local directory or S3 so replicas don't disagree.
Delivery
- Backend: migrations and stores, blob storage, bundle collection, API, content route, config and deployment. See the backend PR below.
- UI: server port and adapter, publish dialog, Artifacts page, viewer, analytics. See the UI PR below.
Tracking:
- Backend: Store and serve versioned HTML and Markdown artifacts #1401
- UI (stacked on the backend PR): Add the artifact list, viewer, and publish dialog #1402
- Regenerate the SDKs after the API lands
Alternatives considered
- Agent-triggered publishing: left out of v1 so users stay in control of what becomes shareable.
- Blob URLs or a service worker for bundles: these break on CSS
url(), runtimefetchand dynamic imports. - Content-addressed blob storage: rejected in favor of real paths per version so a version is a self-contained static site.
- A separate content domain: stronger isolation, deferred; the sandbox iframe and CSP
sandboxheader are the v1 isolation.
Additional context
Future work, intentionally out of scope for v1:
- Per-artifact visibility and grants, and links that work without signing in.
- A separate content origin.
- Publishing from an agent tool or from assistant messages.
- A control to add files the automatic scan missed.
- Slug rename with redirects.
- GCS and Azure Blob adapters, storage migration, and an orphan-blob sweeper.
- Per-version deletion, retention, view counts and visual diffs.
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity