@corbits/artifacts

Versioned documents and files for Interchange agents and their users: a Corbits hub module that mounts grant-gated Hono routes on @intx/hub-api, keeps versions in Postgres and bytes in a pluggable ContentStore, and ships agent tools for the sidecar.

Why @corbits/artifacts?

1. Every version is kept. Each revision of a document or uploaded file is a new version with its own content, bytes and SHA-256 digest. expectedVersion turns a revise into a compare-and-set.
2. Mounts like any hub route. createArtifactRoutes returns a Hono<TenantEnv> sub-app. Reads are confined to the caller's tenant, and writes run through the hub's requireGrant.
3. Agents write through the same store. A run-scoped route set and a sidecar tool pack let a workflow run create, read and revise the artifacts its users see.
4. Migrations that replay safely. Every SQL file is idempotent and runs on every boot under an advisory lock, so several replicas can start at once.

It ships no UI and no object store: the host renders artifacts and brings its own ContentStore for large files.

Install

bun add @corbits/artifacts \
  @intx/agent @intx/authz @intx/db @intx/hub-api @intx/types \
  drizzle-orm hono hono-openapi postgres

Add @intx/agent only if an agent uses the sidecar tools. Runs on Node >= 24.

Quickstart

With DATABASE_URL pointing at a hub database that has run runArtifactMigrations (see Using with Interchange):

import {
  createArtifact,
  createArtifactDb,
  getArtifact,
} from "@corbits/artifacts";

const { db, close } = createArtifactDb(process.env.DATABASE_URL!);

const created = await db.transaction((tx) =>
  createArtifact(tx, {
    scope: { tenantId: "acme", principalId: "alice" },
    ownerPrincipalId: "alice",
    kind: "document",
    title: "Notes",
    content: "Hello",
    source: { origin: "manual" },
  }),
);
console.log(await getArtifact(db, created.id));
await close();

acme and alice must be a tenant and principal in the hub. It prints the artifact at version 1.

Where it fits

Interchange runs AI agents as principals: accounts with their own identity, permissions and credentials. Its hub is the multi-tenant control plane that holds tenants, principals and grants (permissions a principal holds on a resource); its sidecar is the agent runtime.

• Runs in: the hub, as routes on its Hono app and tables in its Postgres (artifacts schema).
• Plugs into: @intx/hub-api routes and grants, @intx/db (its DBConfig, and its tenant and principal tables as FK targets), and @intx/agent tools on the sidecar.
• Pairs with: @corbits/mailbox and @corbits/memory, the other Corbits hub modules, and @corbits/agent-token for agent bearer tokens.

Reference

createArtifactRoutes(deps)

With no principal, every route except the list and counts answers 403. Another tenant's artifact, or an unknown id, answers 404. Set a request-body limit on the host for the upload and file-revise routes; they buffer the body before checking MAX_UPLOAD_BYTES.

Every write reports contentSha256, the hex sha256 stored with the new version: over the UTF-8 text, or over the file's bytes for an upload. POST /artifacts and POST /artifacts/upload carry it on each artifact, and POST /artifacts/:id/versions returns it beside artifactId and version. It is null only for a version written before digests existed.

createWorkflowArtifactRoutes(deps)

Run-scoped routes for a workflow run, which authenticates with a bearer token and an x-workflow-run-address header instead of a session.

beforeWrite({ scope, kind, write, content }) gets the run scope, the artifact kind, write as { op: "create" } or { op: "revise", artifactId }, and the content the version will hold after any edits. It returns one of:

• { action: "allow" } writes as usual.
• { action: "refuse", code, message } answers 422 with { code, message }, and the agent's tool error is message. code must match /^[a-z0-9_]+$/; message must be 1 to 1,000 characters.
• { action: "redirect", artifactId, expectedVersion? } turns a create into a revision of that artifact, which must be of the same kind and in the run's tenant, answering 200 with its { id, version }. The revision takes the create's title. A missing, archived or other-tenant artifact answers 404, and a stale expectedVersion answers 409 telling the agent to read the existing artifact and revise it.

Any other decision, a redirect returned for a revision, or a redirect to an artifact of another kind answers 500 and writes nothing. Binary uploads and linked files are not checked.

A create's check is not serialized: two concurrent creates can both be allowed, so a policy like "one plan per tenant" can still end with two plans when runs race. A revision's check runs inside the transaction holding the artifact's row lock, so it should be fast and must not write that artifact.

Every write (POST /artifacts, POST /artifacts/binary, POST /artifacts/link-file, PATCH /artifacts/:id) answers { data: { id, version, contentSha256 } }, with the same digest the tenant routes report. For link-file the digest covers the stored preview text (empty when none is given), not the workspace file at path.

runArtifactMigrations(config, { schema })

Takes the same DBConfig and schema as Interchange's runMigrations. schema holds the host's tenant and principal tables; this package's tables always go in artifacts.

@corbits/artifacts/sidecar-bundle

artifacts is an @intx/agent tool pack of three tools. They call the run-scoped routes through the agent's hub credential.

• artifact_write creates an artifact when no id is given, from content or a workspace file path. With an id it revises, either with the full text or with edits: exact passages, each of which must appear once, or nothing is written. expectedVersion refuses the write if a newer version exists. It returns { id, version, contentSha256 }.
• artifact_read returns the content, a past version with version, or a range with offset and limit.
• artifact_search lists the newest artifacts, filtered by kind and by a query matched against title and content.

Using with Interchange

Run the migrations after Interchange's, mount both route sets, grant create on artifact:* to principals that create artifacts, and give agents the tool pack.

import { timeWindowEvaluator } from "@intx/authz";
import { createDB, createGrantStore, runMigrations } from "@intx/db";
import { createRequireGrant } from "@intx/hub-api";
import {
  createArtifactRoutes,
  InlineContentStore,
  runArtifactMigrations,
} from "@corbits/artifacts";

const dbConfig = {
  host: "localhost",
  port: 5432,
  user: "postgres",
  password: "postgres",
  database: "interchange",
};

await runMigrations(dbConfig, { schema: "public" });
await runArtifactMigrations(dbConfig, { schema: "public" });

const { db } = createDB(dbConfig);
const requireGrant = createRequireGrant({
  grantStore: createGrantStore(db),
  conditionRegistry: { time_window: timeWindowEvaluator },
});

export const artifactRoutes = createArtifactRoutes({
  db,
  contentStore: InlineContentStore,
  requireGrant,
});

Mount artifactRoutes on the hub app at /api, behind the hub's auth and tenant middleware.

For agents, mount createWorkflowArtifactRoutes({ db, contentStore: InlineContentStore, resolveRunScope }) at /api/workflow-artifacts. resolveRunScope is the host's (bearerToken, runAddress) lookup that returns the run's tenant and principal from the hub's workflow runs, or null. The sidecar tools call /api/workflow-artifacts. Add them to an agent and bind its hub credential to the agent's hub token when you deploy it:

import { defineAgent, type InferencePreference } from "@intx/agent";
import { artifacts } from "@corbits/artifacts/sidecar-bundle";

export function buildAssistant(sources: readonly InferencePreference[]) {
  return defineAgent({
    id: "assistant",
    systemPrompt: "You help the team read and write shared artifacts.",
    capabilities: [],
    inference: { sources },
    tools: [artifacts],
  });
}

Upgrading from 0.1

• mountArtifacts(app, opts) is now createArtifactRoutes(deps), and mountWorkflowArtifacts(app, opts) is now createWorkflowArtifactRoutes(deps). Mount both with app.route.
• POST /artifacts and POST /artifacts/upload need create on artifact:*. The upgrade grants it to every principal that has already created an artifact in its tenant; grant it to new principals yourself.
• runArtifactMigrations(db) is now runArtifactMigrations(dbConfig, { schema }). Existing 0.1.0 data upgrades in place on the first boot.
• That boot drops the 0.1.0 migration ledger. You cannot roll back to 0.1.0, and 0.1.0 and 0.2.0 replicas must not share a database.
• The drizzle tables, the web_site helpers, SKILL_DRAFT_KIND, windowContent and the mail-attachment routes and helpers are removed. The mail_attachment_ref table is dropped.
• Node 24 or newer is required.

Upgrading from 0.2

Separated by surface: what changed for AGENTS (the sidecar tool pack) and what changed for HOSTS (the routes and exports).

Agent tools

The sidecar tool pack collapsed its five finer-grained tools into three. artifact_write now covers both create and link (revise via edits/content is unchanged), and its { artifactId, version } result is the same.

artifact_find_by_title is not a drop-in. In 0.2 it matched the title exactly, matched the title only, and returned at most one { artifactId, version } (or null). In 0.3 artifact_search does a case-insensitive substring (ILIKE) match on both the title and the content, and returns a list of matches. A caller that needs the old exact-title, single-result semantics must post-filter the results (compare title case-insensitively and take the first exact match).

Search results are capped at 50 artifacts per call. artifact_search accepts a cursor property (plus limit, capped at 50) to page through all matches; pass back the previous call's nextCursor (keeping the same query and kind) until none is returned.

Hosts

The roles are unchanged, but two routes and one export were removed:

• GET /artifacts/find → GET /artifacts?query=…, where query is the same case-insensitive substring (ILIKE) match on title and content.
• GET /artifacts/:id/chunk → GET /artifacts/:id/read?offset&limit.
• readArtifactChunk is removed. findArtifactByTitle and linkFileArtifact remain exported. README.md's Reference section describes the current routes and tools.

Two error classes are now exported from the package entry: VersionConflictError answers 409 when an expectedVersion is stale, and ArtifactEditError answers 400 when a revise is refused. Catch them to surface precise failures to your users.

License

LGPL-2.1-only