Module Session

An artifact is generated content that outlives the message that produced it. A tool returns _control.artifacts, this module persists it, writes the messages that reference it, and serves it over HTTP.

An artifact carries two independent settings.

Render mode determines how a client draws the artifact. It is returned as type by GET /artifact/{id}.

Values are stored verbatim and are not validated. A value outside this set matches no renderer branch, and the artifact renders as nothing.

Placement determines which messages this module writes, and therefore how the artifact reaches the thread.

The reference tools derive placement from instructions: true → inline, otherwise standalone. The standalone artifact message is written only when instructions is exactly false; nil does not qualify.

The two settings are independent — any combination is valid. A standalone placement with an inline render mode puts the content in its own message; a standalone render mode with an inline placement gives a chip embedded in the agent's reply.

Placement must not be mapped onto type. Returning meta.display_type as type for every kind was tried and reverted: it collapses the two settings into one, so a standalone placement can no longer carry inline content — the combination the reference tools produce by default. An author who wants a chip asks for the render mode directly (type = "standalone") rather than getting it as a side effect of where the artifact is delivered.

Exactly one applies. title is always required.

A page reference also requires type: "view_ref". Its content endpoint renders the page server-side rather than returning stored bytes.

return {
  success = true,
  _control = {
    artifacts = {
      {
        title        = "Q3 summary",   -- required
        content      = "# Q3 …",       -- one content mode
        content_type = "text/markdown",
        type         = "standalone",   -- render mode; omitted ⇒ "inline"
        display_type = "standalone",   -- placement
        instructions = false,
        preview      = "",             -- shown before the artifact loads
        description  = nil,
        icon         = nil,
        status       = nil,            -- omitted ⇒ "idle"
      },
    },
  },
}

_control.artifacts is a list; one tool call may produce several artifacts. A failing tool returns no _control.

GET /artifact/{id} returns metadata for one artifact.

GET /artifact/{id}/content returns raw bytes with Content-Type from meta.content_type, or text/plain when absent. A view_ref is rendered server-side.

GET /artifacts?session_id=&limit=&cursor= returns an actor-scoped catalog, metadata only. Pagination is keyset over (created_at DESC, artifact_id DESC). Cursors are opaque (v1:<uuid>) and resolved within the caller's own scope, so a cursor naming an inaccessible row is rejected. Rows carry kind and display_type; they do not carry type, so that one field name does not mean different things on two endpoints.

Only session:-prefixed topics are relayed to clients.

• kind is stored verbatim from type with no enum check.
• Updating an artifact replaces meta wholesale. The update path supplies only content_type, description, icon and status, so display_type, page_id and preview do not survive an update.
• Supplying both title and content matches the create path first, so an update shaped that way produces a second artifact with a new id.
• content_version is constant, so a client caching on it will not refetch updated content. Use updated_at.
• A delegated tool call produces no artifact; the control payload is ignored.
• SQLite does not cascade artifact deletion with its session. Orphaned rows remain listable, and fetching one returns HTTP 500.