> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts Runtime

> Create immutable versions and governed links for plugin-generated deliverables.

`ArtifactsRuntimeCapability` exposes `ArtifactsApi` under `platform.artifacts`. It manages durable deliverables generated by plugins and Agents, including HTML, Markdown, PDF, PowerPoint, images, files, Sites, and presentations.

Artifact content bytes live in [Workspace Files](./workspace-files). The Artifact service adds stable business identity, immutable version history, governed access links, lifecycle state, and access counters.

## Data model

An Artifact flow has three layers:

1. **Artifact container** — stable plugin-owned identity defined by `pluginName`, `resourceType`, and `resourceId`.
2. **Artifact version** — immutable content described by a `WorkspacePortableFileReference`, MIME type, checksums, and metadata.
3. **Artifact link** — an open/share/download entrypoint with a version policy, access mode, expiration, and presentation policy.

Supported Artifact kinds are `html`, `markdown`, `pdf`, `pptx`, `image`, `file`, `site`, and `presentation`.

## Container and version methods

| Method | Purpose |
| - | - |
| `createArtifact(input)` | Create or locate a container without uploading content bytes. |
| `findArtifactBySource(input)` | Find a container by the plugin-owned source triple. |
| `getArtifact(idOrSlug)` | Get a container by ID or slug. |
| `listArtifacts(input?)` | Page through visible containers. |
| `archiveArtifact(idOrSlug)` | Transition a container to `archived`. |
| `deleteArtifact(idOrSlug)` | Transition a container to `deleted`. |
| `createArtifactVersion(input)` | Create an immutable version. |
| `ensureArtifactVersion(input)` | Idempotently create or reuse a version. |
| `listArtifactVersions(input)` | List versions, optionally by idempotency key or status. |

Container status is `active`, `archived`, or `deleted`. Version status is `active` or `deleted`.

## Link and share methods

| Method | Purpose |
| - | - |
| `createArtifactLink(input)` | Create a new governed link. |
| `createSignedPreviewLink(input)` | Create a short-lived preview link; never use it as a durable share URL. |
| `updateArtifactLinkAccess(idOrSlug, patch)` | Change mutable access and presentation properties. |
| `revokeArtifactLink(idOrSlug)` | Revoke a specific link. |
| `getArtifactShare(input)` | Resolve the active durable share for an Artifact and `shareKey`. |
| `ensureArtifactShare(input)` | Create, reuse, or replace one stable share slot. |
| `revokeArtifactShare(input)` | Revoke a stable share slot. |

Link status is `active`, `revoked`, or `expired`. `versionMode: 'latest'` follows the current Artifact version; `versionMode: 'version'` pins an immutable version.

Access modes are:

* `owner_only`
* `workspace_all`
* `organization_all`
* `custom_principals`
* `public_link`
* `signed_preview`

Presentation can use `inline` or `attachment`, can allow or disallow download, and can apply the `strict` or `interactive` safe-HTML profile.

## Publish a generated file

Write bytes to Workspace Files first, then create or reuse the Artifact version and share:

```ts theme={null}
import {
  ArtifactsRuntimeCapability,
  WorkspaceFilesRuntimeCapability
} from '@xpert-ai/plugin-sdk'

const files = capabilities.require(WorkspaceFilesRuntimeCapability)
const artifacts = capabilities.require(ArtifactsRuntimeCapability)

const stored = await files.writeRuntimeBuffer({
  buffer: reportBuffer,
  originalName: 'inspection-report.pdf',
  mimeType: 'application/pdf',
  folder: 'reports'
})

const artifact = await artifacts.createArtifact({
  source: {
    pluginName: '@acme/plugin-inspection',
    resourceType: 'inspection-report',
    resourceId: inspectionId
  },
  kind: 'pdf',
  title: `Inspection report ${inspectionCode}`,
  scope: {
    workspaceId,
    projectId,
    userId
  }
})

const { version } = await artifacts.ensureArtifactVersion({
  artifactId: artifact.id,
  idempotencyKey: `inspection:${inspectionId}:${reportRevision}`,
  workspaceFileRef: stored.reference,
  mimeType: 'application/pdf',
  fileName: stored.name,
  size: stored.size,
  sha256: reportSha256,
  sourceVersionId: reportRevision,
  setCurrent: true
})

const { link } = await artifacts.ensureArtifactShare({
  artifactId: artifact.id,
  artifactVersionId: version.id,
  versionMode: 'version',
  shareKey: 'reviewers',
  access: {
    mode: 'workspace_all'
  },
  presentation: {
    disposition: 'inline',
    allowDownload: true
  }
})

return link.publicUrl
```

Use a deterministic version `idempotencyKey` that represents the same immutable content. `ensureArtifactVersion()` reports `created` or `reused`; `ensureArtifactShare()` reports `created`, `reused`, or `replaced`.

## Security and lifecycle rules

* Do not store content bytes in Artifact metadata. Store them in Workspace Files and pass the portable reference.
* Require explicit user confirmation before requesting `public_link`; set `userConfirmedPublicLink` in the access input.
* Use `createSignedPreviewLink()` only for short-lived previews. Store a `shareKey` and use `ensureArtifactShare()` for a durable share policy.
* Pin a version for review, approval, audit, and reproducible delivery. Use `latest` only when readers should always see the current version.
* Choose `strict` HTML unless the deliverable needs the platform's interactive HTML allowance.
* Revoke links or share slots when access should end. Archiving the business object should also drive the plugin's Artifact lifecycle policy.