Skip to content

Publish HTML and Markdown from a session as versioned, shareable artifacts #1403

Open

Description

@innoavator

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_version and artifact_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_id and entry_path. The server lists sandbox files through a provider-agnostic helper in trueforge-core, then follows references transitively (HTML src/href, CSS url()/@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 uses iframe srcDoc, which has no base URL, so ./styles.css can'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 sandbox without allow-same-origin, and every content response sends Content-Security-Policy: sandbox …, X-Content-Type-Options: nosniff and Referrer-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

  1. Backend: migrations and stores, blob storage, bundle collection, API, content route, config and deployment. See the backend PR below.
  2. UI: server port and adapter, publish dialog, Artifacts page, viewer, analytics. See the UI PR below.

Tracking:

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(), runtime fetch and 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 sandbox header 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions