Optional artifacts

@agentplat/artifacts@1.4.0 provides tenant-scoped artifact metadata, immutable content revisions, explicit reads and writes, runtime tools, and reference-only events. The @agentplat/artifacts-postgres@1.4.0 adapter persists revisions with transactional compare-and-set (CAS) and an event outbox.

Supported inert UTF-8 formats are Markdown, plain text, source code, CSV, HTML and JSON. JSON is syntax-checked and retained as text; artifact content is never executed. These packages do not generate PDF, XLSX or PPTX files.

Opt-in activation

Installing packages alone does not expose artifact capabilities to agents. The host explicitly constructs a service and registers tools in the runtime tool registry. Tool calls must use a verified tenant context; the baseline restricts access to the creating owner in that tenant. A host can add broader authorization only through its own reviewed policy layer.

For local use, InMemoryArtifactStore is process-local and not durable. For PostgreSQL, follow the package migration entry point and migration documentation in the pinned @agentplat/artifacts-postgres release before constructing PostgresArtifactStore. Adapter construction does not apply schema migrations. Add the migration as an explicit deployment step, back up the selected schema, and verify status before starting consumers. The adapter's destructive rollback drops artifact data and requires explicit confirmation.

Updates require an expected revision. A stale head returns a conflict; successful writes create immutable revisions. The PostgreSQL adapter writes reference events to its outbox in the revision transaction. Delivery is at least once, so workers and downstream consumers must deduplicate by stable event ID and apply a retention policy to delivered rows.

HTML remains inert artifact content. If an application renders it, use an isolated origin or strict sandbox with restrictive CSP. The host remains responsible for identity, authorization, quotas, retention, API delivery, UI and any document generation.

Agent tools

Register artifact tools only when the application intends an agent to read or write artifacts. Bind tenant, owner, Room, message and run authority from verified server-side execution context; do not accept those fields from model arguments. See the package README (opens in a new tab) and catalog.