@fevex/core 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -28,18 +28,26 @@ adapters, validation and tests without adopting a heavy runtime.
 npm install @fevex/core
 ```
 
-For official model adapters:
+The npm release pipeline publishes exactly three official packages:
 
 ```bash
 npm install @fevex/core @fevex/openai
 npm install @fevex/core @fevex/deepseek
-npm install @fevex/core @fevex/mcp
-npm install @fevex/core @fevex/openapi
-npm install @fevex/core @fevex/sqlite
-npm install @fevex/core @fevex/postgres
-npm install @fevex/core @fevex/opentelemetry @opentelemetry/api
 ```
 
+CI builds, typechecks, tests and tarball-smokes all nine packages. The
+repository-only integrations below are **not published to npm** by the release
+pipeline; use them from this repository until they are published:
+
+| Package | Purpose |
+| --- | --- |
+| `@fevex/mcp` | Model Context Protocol tools and connections |
+| `@fevex/openapi` | Tools generated from an OpenAPI document |
+| `@fevex/sqlite` | SQLite run and session store |
+| `@fevex/postgres` | PostgreSQL run and session store |
+| `@fevex/opentelemetry` | OpenTelemetry trace and metric export |
+| `@fevex/browser` | Browser automation tools |
+
 Schemas are optional. The examples use Zod 4, but any Standard
 Schema-compatible validator can be used:
 
@@ -47,6 +55,20 @@ Schema-compatible validator can be used:
 npm install zod
 ```
 
+## Compatibility & releases
+
+FEVEX is pre-1.0. Documented imports from official packages are the public API;
+`src/internal`, undocumented paths and checkpoint shapes are not. While in alpha,
+`minor` releases may contain breaking changes with migration notes; `patch`
+releases stay compatible. Store migrations are forward-only, checkpoints are
+versioned and private, and downgrades are not supported.
+
+Only the latest alpha is supported; pin exact versions in production. Releases
+come from reviewed changesets, publish only the three official packages, and
+place alpha versions on the npm `latest` tag. Read the full
+[compatibility and release policy](https://fevex.dev/docs/compatibility/) before
+upgrading a durable deployment.
+
 ## Quickstart
 
 This example executes a complete model-tool-model cycle without network access:
@@ -568,6 +590,31 @@ Hosts pass authenticated `ExecutionContext` separately to `handler(request,
 SSE response never cancels its run. Cancellation is explicit through
 `client.cancelRun(run.id)`.
 
+Artifacts use the same handler:
+
+```ts
+const handler = createFevexHttpHandler({
+  fevex: app,
+  artifacts: artifactStore,       // FileSystemArtifactStore or S3ArtifactStore
+  artifactCatalog: artifactCatalog, // optional; enables listing by run
+  authorizeArtifact(access) {
+    return access.context?.actor?.id === 'alice';
+  },
+});
+```
+
+Routes:
+
+- `GET /v1/artifacts/:id` streams the bytes with `content-type`,
+  `content-length`, `content-disposition`, `etag` and artifact headers.
+- `HEAD /v1/artifacts/:id` returns the same metadata without a body.
+- `DELETE /v1/artifacts/:id` deletes bytes and catalog metadata.
+- `GET /v1/runs/:runId/artifacts?limit=100` lists descriptors for a run.
+
+The client exposes `getArtifact`, `listArtifacts` and `deleteArtifact`. Keep the
+bucket private; the handler authorizes the request and streams the bytes, or a
+host can use the descriptor to mint a short-lived signed URL.
+
 ## Approvals and durable runs
 
 Tools can declare risk, approval, idempotency, retries and credential names.
@@ -652,6 +699,28 @@ underlying work. External systems must enforce the supplied idempotency key to
 make keyed retries safe. Repeated tool call IDs are rejected within a run before
 Fevex repeats an effect.
 
+### Deadlines, admission and retention
+
+Set `deadlineMs` on a run request to cap wall-clock time. An expired deadline
+cancels the run with `run.cancelled` reason `timeout`; resuming or recovering
+after the absolute deadline persists that cancellation instead of continuing.
+
+`createFevex({ admission })` limits concurrent top-level runs globally or per
+tenant. The default tenant key is a non-empty `context.attributes.tenantId`;
+`tenantKey` and `authorize` support host-specific quotas. Counts are local to
+one runtime process.
+
+`createFevex({ limits: { maxEventsPerRun } })` caps non-control events per run.
+Pause, resume, approval, elicitation, wait and terminal events are always
+persisted so a run can always reach a durable state; use retention for a total
+storage cap.
+
+Terminal runs can be purged with `app.purgeRuns({ before, statuses, limit })`.
+SQLite and PostgreSQL implement the retention capability; custom stores can add
+`purgeRuns` to opt in. The API deletes only terminal runs and sessions left
+without runs; active work is untouched. Artifact retention and per-event payload
+byte limits remain host policies.
+
 ## Observability
 
 Add trace exporters to the application configuration; agent definitions stay
@@ -683,8 +752,50 @@ Traces contain only metadata by default. Output and safe error capture require
 an explicit `content.include` policy; sensitive object keys are redacted before
 an optional application redactor runs. Exporters run outside the run path: their
 errors never change the run result, and `flushObservability()` reports pending
-export failures. OpenTelemetry SDK setup, OTLP export and shutdown remain
-application responsibilities.
+export failures. Export work is bounded and deduplicated:
+
+```ts
+const app = createFevex({
+  models,
+  agents,
+  observability: {
+    exporters: [createOpenTelemetryExporter()],
+    exportQueue: {
+      concurrency: 4,
+      maxQueued: 100,
+      timeoutMs: 30_000,
+      maxFailures: 100,
+    },
+  },
+});
+
+await app.flushObservability({ timeoutMs: 5_000 });
+console.log(app.getObservabilityStats());
+```
+
+Workflow and team traces carry `kind` and a span per step. Agent steps expose
+`childRunId`; child agent traces carry `parentRunId` and `rootRunId`, and tool
+spans are nested under the model call that requested them. A dropped trace or a
+failed export is counted in `getObservabilityStats()`, and the next
+`flushObservability()` rejects with the failures accumulated since the previous
+flush. OpenTelemetry SDK setup, OTLP export and shutdown remain application
+responsibilities.
+
+## Graceful shutdown
+
+`shutdown` stops admission, drains active runs, cancels what remains at the
+deadline and flushes trace exports:
+
+```ts
+const result = await app.shutdown({ timeoutMs: 30_000 });
+console.log(result.timedOut, result.cancelledRunIds, result.observability);
+```
+
+New starts, resumes and recoveries fail with `RUNTIME_CLOSED` (HTTP `503`) once
+shutdown begins. The host closes its HTTP server, stores and external adapters
+after `shutdown` returns. See
+[Operations & soak tests](https://fevex.dev/docs/operations/) for crash recovery
+and the 1–8 hour load harness.
 
 ## Evaluations
 
@@ -871,12 +982,128 @@ Context providers are lazy per run. Memory is a replaceable store; the built-in
 store is in-memory substring search, not embeddings, vector search or durable
 storage.
 
+## Artifacts
+
+`@fevex/core/artifacts` stores large or binary outputs as references. Runs,
+events and prompts carry an `ArtifactDescriptor`; bytes stay in an
+`ArtifactStore`.
+
+```ts
+import {
+  FileSystemArtifactStore,
+  InMemoryArtifactStore,
+  S3ArtifactStore,
+  type S3ObjectClient,
+} from '@fevex/core/artifacts';
+
+const artifacts = new FileSystemArtifactStore({
+  rootDir: '.fevex/artifacts',
+  maxBytes: 10 * 1024 * 1024,
+});
+
+const descriptor = await artifacts.put(
+  {
+    filename: 'report.pdf',
+    mimeType: 'application/pdf',
+    bytes,
+  },
+  { tenantId: 'acme', runId: 'run-1' },
+);
+
+const stored = await artifacts.get(descriptor.artifactId, { tenantId: 'acme' });
+```
+
+Use `InMemoryArtifactStore` for tests. For S3, R2, MinIO or another
+S3-compatible service, wrap its SDK with the small `S3ObjectClient` interface;
+Fevex does not ship an object-storage SDK:
+
+```ts
+const client: S3ObjectClient = {
+  async putObject({ key, body, contentType }) {
+    await s3.send(new PutObjectCommand({
+      Bucket,
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+    }));
+  },
+  async getObject({ key }) {
+    try {
+      const result = await s3.send(new GetObjectCommand({ Bucket, Key: key }));
+      return new Uint8Array(await result.Body!.transformToByteArray());
+    } catch (error) {
+      if ((error as { name?: string }).name === 'NoSuchKey') return null;
+      throw error;
+    }
+  },
+  async deleteObject({ key }) {
+    await s3.send(new DeleteObjectCommand({ Bucket, Key: key }));
+  },
+};
+
+const artifacts = new S3ArtifactStore({ client, prefix: 'fevex' });
+```
+
+The bucket should stay private. The host authorizes the actor and serves a
+short-lived signed URL or streams the bytes; do not expose bucket URLs to the
+model. This subpath is local-first: use the filesystem store for development and
+single-node deployments, and the S3-compatible store for multi-instance
+production.
+
+For a queryable metadata index, compose the byte store with a catalog:
+
+```ts
+import { CatalogedArtifactStore, FileSystemArtifactStore } from '@fevex/core/artifacts';
+import { createSQLiteArtifactCatalog } from '@fevex/sqlite';
+
+const catalog = createSQLiteArtifactCatalog({ filename: '.fevex/artifacts.db' });
+const artifacts = new CatalogedArtifactStore({
+  store: new FileSystemArtifactStore({ rootDir: '.fevex/artifacts' }),
+  catalog,
+});
+
+const records = await artifacts.list({ runId: 'run-1' }, { tenantId: 'acme' });
+await artifacts.deleteByRun('run-1', { tenantId: 'acme' });
+```
+
+`@fevex/postgres` exposes the same catalog contract with
+`createPostgresArtifactCatalog`. The catalog stores only metadata; bytes stay in
+the filesystem or object storage.
+
+Pass the store to `createFevex` to expose it to tools as `context.artifacts`:
+
+```ts
+const save = defineTool({
+  name: 'save_report',
+  async execute(_input, context) {
+    return context.artifacts!.put({
+      filename: 'report.txt',
+      mimeType: 'text/plain',
+      bytes: new TextEncoder().encode('report'),
+    });
+  },
+});
+
+createFevex({
+  models,
+  agents,
+  tools: [save],
+  artifacts,
+});
+```
+
+The runtime injects `runId`, `sessionId`, tenant and actor into every artifact
+call. Each successful `put` emits `artifact.created` with the descriptor before
+`tool.completed`; a tool that writes and then fails still leaves the event and
+the artifact available.
+
 ## Public Exports
 
 | Import | Purpose |
 | --- | --- |
 | `@fevex/core` | Common runtime, definitions and contracts |
 | `@fevex/core/agents` | Agent definitions |
+| `@fevex/core/artifacts` | Artifact descriptors, local stores and S3-compatible adapter |
 | `@fevex/core/channels` | Channel adapters and message handling |
 | `@fevex/core/knowledge` | Context providers, skills and memory contracts |
 | `@fevex/core/models` | Provider-neutral model contracts |
@@ -886,7 +1113,7 @@ storage.
 | `@fevex/core/runtime` | Runs, sessions and store contracts |
 | `@fevex/core/sandbox` | Sandbox contract and local development sandbox |
 | `@fevex/core/policies` | Authorization policy contracts |
-| `@fevex/core/observability` | Trace, redaction and cost contracts |
+| `@fevex/core/observability` | Trace, bounded export queue, redaction and cost contracts |
 | `@fevex/core/evals` | Datasets, scorers, reporters and regressions |
 | `@fevex/core/testing` | Deterministic testing helpers |
 
@@ -959,8 +1186,10 @@ limit for the initial SSE read and every subsequent read. Full pages drain
 without the polling delay; short pages wait for `pollIntervalMs`. Stream demand
 controls progress, so a slow consumer retains at most one page plus the stream's
 single queued frame, rather than buffering the run's entire history. Disconnecting
-cancels polling. This bounds event counts, not the byte size of an individual event;
-per-event payload limits and data retention remain host responsibilities.
+cancels polling. `maxConnections` caps concurrent SSE streams. This bounds event
+counts, not the byte size of an individual event; per-event payload limits remain
+host responsibilities. Use `purgeRuns` for configurable retention of terminal
+runs.
 
 ### Run model identity
 

package/dist/agents/index.d.mts

@@ -1,2 +1,2 @@
-import { n as AgentLimits, r as defineAgent, t as AgentDefinition } from "../index-CaE864Kz.mjs";
+import { n as AgentLimits, r as defineAgent, t as AgentDefinition } from "../index-CzAi2Y_Z.mjs";
 export { AgentDefinition, AgentLimits, defineAgent };

package/dist/artifacts/index.d.mts

@@ -0,0 +1,2 @@
+import { A as ArtifactError, C as FileSystemArtifactStore, D as ArtifactCatalog, E as CatalogedArtifactStoreOptions, F as ArtifactStore, I as ArtifactStoreContext, L as ArtifactWrite, M as ArtifactId, N as ArtifactQuery, O as ArtifactContent, P as ArtifactRecord, R as artifactTenantId, S as InMemoryArtifactCatalog, T as CatalogedArtifactStore, _ as S3ArtifactStore, b as InMemoryArtifactStore, j as ArtifactErrorCode, k as ArtifactDescriptor, v as S3ArtifactStoreOptions, w as FileSystemArtifactStoreOptions, x as InMemoryArtifactStoreOptions, y as S3ObjectClient, z as assertArtifactId } from "../types-B8laW1hM.mjs";
+export { ArtifactCatalog, ArtifactContent, ArtifactDescriptor, ArtifactError, ArtifactErrorCode, ArtifactId, ArtifactQuery, ArtifactRecord, ArtifactStore, ArtifactStoreContext, ArtifactWrite, CatalogedArtifactStore, CatalogedArtifactStoreOptions, FileSystemArtifactStore, FileSystemArtifactStoreOptions, InMemoryArtifactCatalog, InMemoryArtifactStore, InMemoryArtifactStoreOptions, S3ArtifactStore, S3ArtifactStoreOptions, S3ObjectClient, artifactTenantId, assertArtifactId };

package/dist/artifacts/index.mjs

@@ -0,0 +1,2 @@
+import { a as CatalogedArtifactStore, c as assertArtifactId, i as FileSystemArtifactStore, n as InMemoryArtifactStore, o as ArtifactError, r as InMemoryArtifactCatalog, s as artifactTenantId, t as S3ArtifactStore } from "../artifacts-gUzemET7.mjs";
+export { ArtifactError, CatalogedArtifactStore, FileSystemArtifactStore, InMemoryArtifactCatalog, InMemoryArtifactStore, S3ArtifactStore, artifactTenantId, assertArtifactId };