@fevex/core 0.1.0-alpha.0 → 0.1.0-alpha.10

package/README.md

@@ -6,7 +6,7 @@ TypeScript.
 Fevex gives you the small contracts needed to define agents, tools, model
 adapters, validation and tests without adopting a heavy runtime.
 
-> **Status:** early MVP. Fevex is usable for local, single-tool agent runs, but
+> **Status:** early MVP. Fevex is usable for bounded local agent runs, but
 > its API may change before the first stable release.
 
 ## Why Fevex
@@ -17,23 +17,38 @@ adapters, validation and tests without adopting a heavy runtime.
   runtime boundary.
 - **Small runtime:** one package, ESM, Node.js 20+, no database or service
   required.
-- **Observable:** successful and failed runs emit structured events.
-- **Testable:** `fevex/testing` includes a deterministic model and shared model
-  contract checks.
+- **Observable:** successful and failed runs emit structured events and optional
+  local traces.
+- **Testable:** `@fevex/core/testing` includes a deterministic model and shared
+  model contract checks; `@fevex/core/evals` adds local regression suites.
 
 ## Install
 
 ```bash
-npm install fevex
+npm install @fevex/core
 ```
 
-For official model adapters:
+The npm release pipeline publishes exactly three official packages:
 
 ```bash
-npm install fevex @fevex/openai
-npm install fevex @fevex/deepseek
+npm install @fevex/core @fevex/openai
+npm install @fevex/core @fevex/deepseek
 ```
 
+CI builds, typechecks, tests and tarball-smokes all ten 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 |
+| `@fevex/sandbox-docker` | Docker-backed production sandbox provider |
+
 Schemas are optional. The examples use Zod 4, but any Standard
 Schema-compatible validator can be used:
 
@@ -41,13 +56,27 @@ 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:
 
 ```ts
-import { createFevex, defineAgent, defineTool } from 'fevex';
-import { fakeModel } from 'fevex/testing';
+import { createFevex, defineAgent, defineTool } from '@fevex/core';
+import { fakeModel } from '@fevex/core/testing';
 import { z } from 'zod';
 
 const accountInput = z.object({
@@ -60,7 +89,7 @@ const accountOutput = z.object({
 });
 
 const getAccount = defineTool({
-  name: 'accounts.get',
+  name: 'accounts_get',
   description: 'Get an account by ID.',
   inputSchema: accountInput,
   outputSchema: accountOutput,
@@ -73,11 +102,11 @@ const model = fakeModel(
   {
     toolCalls: [{
       id: 'call-1',
-      name: 'accounts.get',
+      name: 'accounts_get',
       input: { accountId: 42 },
     }],
   },
-  { output: 'Account 42 is active.' },
+  { output: { answer: 'Account 42 is active.' } },
 );
 
 const app = createFevex({
@@ -85,48 +114,188 @@ const app = createFevex({
   agents: [defineAgent({
     name: 'support',
     instructions: 'Answer account questions clearly.',
-    tools: ['accounts.get'],
-    outputSchema: z.string(),
+    tools: ['accounts_get'],
+    outputSchema: z.object({ answer: z.string() }),
   })],
   tools: [getAccount],
 });
 
-const result = await app.runAgent<string, string>('support', {
+const result = await app.runAgent<string, { answer: string }>('support', {
   input: 'What is the status of account 42?',
 });
 
-console.log(result.output);
+console.log(result.output.answer);
 // Account 42 is active.
 ```
 
 `fakeModel` returns its configured responses in order and records every input in
 `model.calls`.
 
+## Durable workflows
+
+Workflows require a `DurableRunStore`. Their definition owns the input, output,
+event and limit contracts:
+
+```ts
+const review = defineWorkflow({
+  name: 'review',
+  version: '2',
+  inputSchema: z.object({ draft: z.string() }),
+  outputSchema: z.string(),
+  events: {
+    'review.approved': {
+      payloadSchema: z.object({ approved: z.literal(true) }),
+      requireActor: true,
+    },
+  },
+  limits: { maxSteps: 8, maxToolCalls: 12 },
+  async run(step, input) {
+    const draft = await step.agent('draft', 'writer', { input });
+    const approval = await step.waitForEvent('approval', 'review.approved');
+    return `${draft.output} (${approval.actor?.id}, ${approval.receivedAt})`;
+  },
+});
+```
+
+Input is validated and transformed before the initial checkpoint is stored.
+Output is always validated with the definition schema, including after a pause
+or recovery. Effective workflow limits combine definition and request limits;
+agent steps additionally combine their own agent/request limits. These values
+are checkpointed so recovery cannot silently widen a budget.
+
+`stepId` is the durable identity of a step: keep it stable while its meaning is
+stable. Increment `version` when replay order, business rules or step meanings
+change. Completed agent steps are reused on replay and `step.agent` always
+returns `{ runId, sessionId, output, usage? }`, without a transient `events`
+field.
+
+Child execution context inherits the workflow context. Namespace, attributes
+and prompt values are merged; an authenticated parent actor cannot be replaced
+by a child. `parallel` waits for every declared task to settle, records durable
+child successes, reports multiple failures in declaration order and resolves
+multiple pauses one at a time. Arbitrary promises used in `parallel` must be
+pure or replay-safe; side effects belong in durable agent/tool steps.
+
+External events must be declared. `waitForEvent` returns
+`{ payload, actor, receivedAt }`; payload and required actor are checked before
+the checkpoint changes. Cancelling a workflow first cancels its running or
+paused children. Compensation runs in reverse completed-step order; if both the
+workflow and compensation fail, the terminal error is a stable
+`AggregateError`.
+
+Durable executions start with a checkpoint v2 and lease in the same atomic
+store operation. An external worker may recover an orphaned `running` run after
+its lease expires:
+
+```ts
+await app.recoverRun(runId, { actor: { id: 'recovery-worker', type: 'service' } });
+```
+
+Paused runs use `resumeRun`; terminal runs and older checkpoints are rejected.
+Fevex does not poll globally: deployments need an external orphan detector and
+a scheduler that calls `resumeRun` for elapsed timers. Exactly-once protection
+is limited to keyed/idempotent tools and durable steps.
+
+## Advanced teams
+
+Teams are an opt-in coordination layer on the durable workflow engine. They
+reuse registered agents and cannot widen an agent's model, tools, policies,
+sandbox or limits:
+
+```ts
+const model = fakeModel(
+  { output: 'plan' },
+  { output: 'research' },
+  { output: 'code' },
+  { output: 'approved' },
+);
+
+const softwareTeam = defineTeam({
+  name: 'software-team',
+  version: '1',
+  supervisor: 'planner',
+  members: [
+    { agent: 'researcher', role: 'research' },
+    { agent: 'coder', role: 'implementation' },
+    { agent: 'reviewer', role: 'review' },
+  ],
+  limits: { maxDelegations: 12, maxParallel: 2 },
+  async run(team, input) {
+    const plan = await team.delegate('plan', {
+      agent: 'planner',
+      task: input,
+      expectedOutput: 'Implementation plan',
+    });
+    const work = await team.parallel('work', {
+      research: () =>
+        team.delegate('research', { agent: 'researcher', task: plan.output }),
+      implementation: () =>
+        team.delegate('implementation', { agent: 'coder', task: plan.output }),
+    });
+    return (
+      await team.handoff('review', {
+        from: 'coder',
+        to: 'reviewer',
+        reason: 'Final review',
+        task: work,
+      })
+    ).output;
+  },
+});
+
+const app = createFevex({ models, agents, teams: [softwareTeam] });
+const result = await app.runTeam('software-team', { input: 'Implement the change.' });
+```
+
+Delegation and parallel step IDs are durable identities and must remain stable
+within a team version. Team runs emit `team.*` events and relay child events
+with `teamDelegationId` and `teamAgentName`. `startTeam`, `streamTeam`,
+`getTeamRun`, `resumeRun`, `recoverRun` and `cancelRun` use the same durable
+store as agents and workflows.
+
+This release intentionally omits automatic routers, network/graph modes,
+quorum, shared blackboards and nested teams. Coordination remains explicit
+TypeScript and shared context travels through task inputs, outputs and the
+existing memory contracts.
+
 ## Connect A Model
 
 Real providers connect through the small `ModelGateway` contract:
 
 ```ts
-import type { ModelGateway } from 'fevex/models';
+import type { ModelGateway } from '@fevex/core/models';
 
 export const model: ModelGateway = {
-  async generate({ messages, tools, outputSchema, signal }) {
-    const response = await yourProvider.generate({
-      messages,
-      tools,
-      outputSchema,
-      signal,
-    });
-
-    return {
-      output: response.output,
-      toolCalls: response.toolCalls,
-      usage: response.usage,
-    };
+  async *stream(input) {
+    for await (const event of yourProvider.stream(input)) {
+      if (event.type === 'text.delta') {
+        yield { type: 'output.delta', delta: event.text };
+      } else if (event.type === 'completed') {
+        yield {
+          type: 'completed',
+          result: {
+            output: event.output,
+            toolCalls: event.toolCalls,
+            usage: event.usage,
+            providerState: event.providerState,
+          },
+        };
+      }
+    }
   },
 };
 ```
 
+The stream must emit visible text or JSON fragments as `output.delta` followed
+by exactly one `completed` event. Fevex rejects missing or duplicate terminals,
+post-terminal events and a final output that does not match the accumulated
+deltas.
+
+`providerState` is opaque, provider-specific continuation data. Fevex carries
+it between model steps within one run and never adds it to agent messages,
+events or `RunResult`. A direct `ModelGateway` consumer must pass it unchanged
+to the next call; it is ephemeral and should not be inspected or persisted.
+
 Provider integrations remain outside the core package. The first official
 adapter is `@fevex/openai`, authored by Fevex over the native OpenAI HTTP API:
 
@@ -147,39 +316,94 @@ import { createDeepSeek } from '@fevex/deepseek';
 
 const model = createDeepSeek({
   apiKey: process.env.DEEPSEEK_API_KEY!,
-})('deepseek-chat');
+  schemaPolicy: 'best-effort',
+})('deepseek-v4-flash');
 ```
 
 Applications can still implement `ModelGateway` directly as shown above.
 
+Official adapters preserve ordinary model text exactly. JSON-looking text is
+still a string unless `outputSchema` is present; structured output is then
+parsed as JSON and validated locally by Fevex. Tool names must match
+`[A-Za-z0-9_-]{1,64}`.
+
+`modelOptions` remains a provider escape hatch, but Fevex-owned request fields
+take precedence: model, messages, tools, tool choice, schema format,
+parallelism and preventive token limits cannot be replaced. Compatible options
+such as temperature, metadata and provider-only reasoning settings are kept.
+
 ## Validation
 
+`createFevex` validates the complete composition before returning the app,
+including JavaScript values that bypass TypeScript. Invalid registrations throw
+`FevexConfigurationError` with a stable `code`, while preserving a readable
+message.
+
+Codes follow one rule: `INVALID_CONFIG` covers the shape of the root config
+object, and every registered entity gets its own code.
+
+| Entity | Invalid | Duplicated by name | Referenced but missing |
+|---|---|---|---|
+| Model | `INVALID_MODEL` | — | `MISSING_MODEL` |
+| Agent | `INVALID_AGENT` | `DUPLICATE_AGENT` | — |
+| Tool | `INVALID_TOOL` | `DUPLICATE_TOOL` | `MISSING_TOOL` |
+| Workflow | `INVALID_WORKFLOW` | `DUPLICATE_WORKFLOW` | — |
+| Team | `INVALID_TEAM` | `DUPLICATE_TEAM` | — |
+| Context provider | `INVALID_CONTEXT_PROVIDER` | `DUPLICATE_CONTEXT_PROVIDER` | — |
+| Connection | `INVALID_CONNECTION` | — | — |
+| Policy | `INVALID_POLICY` | — | — |
+
+Connections have no duplicate code of their own: two connections sharing a name
+produce colliding `<connection>__<tool>` entries and fail with
+`DUPLICATE_TOOL`.
+
+The app captures a shallow snapshot of registered definitions, tool lists,
+limits, model options and `onEvent`. Mutating those caller-owned containers
+after `createFevex` does not reconfigure a running app. Model gateways, schemas,
+tool functions and nested provider-option values remain cooperative runtime
+references and are not frozen.
+
 Fevex accepts
 [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema)
 validators for:
 
+- agent, workflow and team input before it is persisted;
 - tool input before `execute`;
 - tool output before it is returned to the model;
-- final agent output before it is returned to the application.
+- final agent, workflow and team output before it is returned to the application;
+- declared workflow event payloads before a wait is resolved.
 
 Schemas may transform values. The transformed result must still be JSON-safe.
-The schema passed to `runAgent` takes precedence over the agent schema for that
-run. Plain JSON Schema objects are not executable validators and are not
+Schemas belong to agent, workflow or team definitions; requests cannot replace an output
+contract. Plain JSON Schema objects are not executable validators and are not
 accepted by these fields.
 
 When a model adapter needs schemas, Fevex converts authoring schemas that also
 implement Standard JSON Schema into JSON Schema 2020-12 before calling
-`ModelGateway.generate`. Adapters receive transportable JSON Schema in
-`ToolSpec.inputSchema` and `ModelGenerateInput.outputSchema`; they never receive
+`ModelGateway.stream`. Adapters receive transportable JSON Schema in
+`ToolSpec.inputSchema` and `ModelInput.outputSchema`; they never receive
 the application's executable validators. If a run needs a schema at the model
 boundary and the schema cannot be converted, Fevex fails before invoking the
 model with `SCHEMA_NOT_TRANSPORTABLE`.
 
+Transportable does not mean supported by every provider. Official adapters use
+`schemaPolicy: "strict"` by default and validate their provider's documented
+subset before making an HTTP request. Unsupported schemas fail with
+`PROVIDER_SCHEMA_UNSUPPORTED`. Use `schemaPolicy: "best-effort"` explicitly
+when local validation is sufficient and provider-level schema adherence is not
+required; invalid model output can still fail locally and may require a retry
+owned by the caller.
+
+| Boundary | OpenAI strict | DeepSeek strict | Best effort |
+| --- | --- | --- | --- |
+| Tool input | Structured Outputs subset | Strict tools subset on `/beta` | Forwarded without provider guarantee |
+| Final output | Structured Outputs subset | Unsupported | JSON instruction plus local validation |
+
 Use `testModelGateway` to verify a custom model adapter against the shared
 contract:
 
 ```ts
-import { testModelGateway } from 'fevex/testing';
+import { testModelGateway } from '@fevex/core/testing';
 
 await testModelGateway(model);
 ```
@@ -204,42 +428,876 @@ The MVP emits:
 
 ```text
 run.started
+model.started
+model.output.delta
 model.completed
+context.compacted
+tool.started
 tool.completed
 tool.failed
 run.completed
 run.failed
+run.cancelled
+```
+
+`streamAgent` yields each persisted event as it happens. Use
+`model.output.delta` to render output incrementally:
+
+```ts
+for await (const event of app.streamAgent('support', { input: 'Hello' })) {
+  if (event.type === 'model.output.delta') {
+    process.stdout.write(event.payload.delta);
+  }
+}
 ```
 
 Successful runs also return their events in `RunResult.events`.
+Every event has a unique `id` and a run-local `sequence` starting at `1`.
+`model.completed` includes the current step and accumulated usage.
+Tool events include the current step, tool call ID and tool name.
+`run.completed` includes the final JSON output and accumulated usage.
+
+`onEvent` is a best-effort observer isolated from execution. Its exceptions do
+not fail the run, and it continues receiving later events. Fevex does not await
+a Promise returned by the observer, but absorbs its rejection to avoid an
+unhandled rejection.
+
+Consume the same execution incrementally with `streamAgent`:
+
+```ts
+for await (const event of app.streamAgent('support', {
+  input: 'What is the status of account 42?',
+})) {
+  console.log(event.type, event.payload);
+}
+```
+
+The stream emits `run.failed` before propagating the original error.
+Cancellation emits `run.cancelled` with a safe `aborted` or `timeout` reason,
+then propagates the original abort reason. `streamAgent` applies backpressure:
+the run advances only while the consumer requests events, and abandoning the
+iterable cancels and persists that local execution.
+
+## Sessions and consultable runs
+
+Every run belongs to a session. Omit `sessionId` to create one, then pass the
+returned ID to continue the conversation:
+
+```ts
+const first = await app.runAgent('support', {
+  input: 'What is the status of account 42?',
+});
+
+const second = await app.runAgent('support', {
+  input: 'What should I do next?',
+  sessionId: first.sessionId,
+});
+```
+
+Only completed interactions enter session history. Failed and cancelled runs do
+not affect the next prompt. Replace old history with an application-provided
+summary when needed:
+
+```ts
+await app.compactSession(first.sessionId, 'Account 42 is active.');
+```
+
+Automatic compaction is opt-in through a context budget:
+
+```ts
+const support = defineAgent({
+  name: 'support',
+  instructions: 'Answer clearly.',
+  contextBudget: { contextWindow: 128_000, reserveOutputTokens: 8_000 },
+});
+```
+
+Before each model call, Fevex estimates the prompt. Above 80% of the usable
+window it replaces older completed turns with a summary, keeps system
+instructions, the current request and the latest tool batch intact, and emits
+`context.compacted`. The summary is cached on the session and reused across
+runs; the original history is not rewritten. Use `compaction.compactor` to
+inject a summarizer; the default is a deterministic digest and
+`createModelContextCompactor` provides a model-backed option. Redact event
+summaries with `compaction.redactSummary` and read counters with
+`app.getCompactionStats()`.
+`limits.maxInputTokens` is still the cumulative spend cap, while
+`contextBudget.contextWindow` is the model context window.
+
+Use `startAgent` when execution must continue without consuming a stream:
+
+```ts
+const started = await app.startAgent('support', {
+  input: 'Check account 42.',
+});
+
+const run = await app.getRun(started.id);
+const events = await app.listEvents(started.id);
+const laterEvents = await app.listEvents(started.id, {
+  after: events.at(-1)?.id,
+});
+
+await app.cancelRun(started.id);
+```
+
+`AgentRun`, `Session` and events are serializable snapshots. `listEvents` orders
+by `sequence`; `after` accepts an event ID from the same run as a stable cursor.
+Unknown cursors fail instead of silently replaying events.
+
+`createFevex` uses `InMemoryRunStore` by default. Supply `runStore` to replace
+it. The default survives only while the process lives, and one run at a time
+may update a session.
+
+The built-in durable stores reserve each session atomically when creating an
+agent, workflow or team run. A competing run receives `RUN_CONFLICT` before
+calling its model or tools. A paused or orphaned run keeps its reservation:
+resume, recover or cancel that run before starting another. Lease expiry permits
+recovery of the same run; it does not free its conversation for a new run.
+
+`Session.revision` is store-managed. Creation, history commits and compaction
+check the snapshot revision and advance it atomically. Compaction rejects active
+or paused sessions and stale snapshots. On conflict, reload the session and
+decide whether to retry; never automatically retry external effects.
+
+Custom durable adapters must implement these guarantees in `createExecution`,
+`commitExecution` and `saveSession`, and pass `testRunStore`.
+`ExecutionCreate.session` is now required for existing sessions as well as new
+ones. A legacy session without a revision is treated as revision zero.
+The low-level `saveRun` API is for trusted storage maintenance; it must not be
+used to bypass runtime reservation or overwrite active runs.
+
+Upgrade all workers and adapters together; old workers do not enforce session
+reservation. Every durable commit also validates the lease owner, generation and expiry in
+the same transaction as the run revision. Acquisition advances the generation,
+including when an owner ID is reused. Release expires the lease without deleting
+that counter; stale workers cannot commit, renew or release a newer generation.
+
+Custom adapters must accept `ExecutionCommit.lease` and the generation argument
+to `releaseLease`. Initialize `RunLease.generation` to zero for creation or
+acquisition and retain the generation assigned by the store on success.
+Renewal keeps the same generation and cannot revive an expired lease.
+
+Renewal errors surface as `FevexRunError` with code `RUN_CONFLICT` and the original
+error in `cause`. Local cleanup does not persist cancellation after ownership is lost.
+A lost, failed or blocked renewal aborts local execution; the runtime will not
+start further work or persist results under that token. The orphaned run remains
+available for recovery. External effects already in flight still need
+idempotency or fencing in the external system.
+
+Migrate storage before restarting workers. Legacy leases get generation zero
+and cannot commit or renew; recovery can acquire a new generation after they
+expire. Never run old and new workers together during this upgrade.
+
+## HTTP protocol
+
+`@fevex/core/http` exposes the runtime through versioned JSON and SSE using
+native Fetch types:
+
+```ts
+import { createFevexHttpHandler, createFevexHttpClient } from '@fevex/core/http';
+
+const handler = createFevexHttpHandler({ fevex: app });
+const client = createFevexHttpClient({ baseUrl: 'http://localhost:3001' });
+
+const run = await client.startRun('support', { input: 'Check account 42.' });
+for await (const event of client.observeRun(run.id)) {
+  console.log(event.type);
+}
+```
+
+Protocol v3 also exposes `client.startWorkflow(...)` and
+`client.startTeam(...)`; all run kinds share observation, resume, recovery and
+cancellation endpoints.
+
+Hosts pass authenticated `ExecutionContext` separately to `handler(request,
+{ context })`. Observation reconnects with `Last-Event-ID`; disconnecting an
+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.
+Approval pauses before credentials are resolved or the effect starts:
+
+```ts
+const charge = defineTool({
+  name: 'charge',
+  risk: 'sensitive',
+  approval: 'required',
+  idempotency: 'keyed',
+  credentials: ['payments-api-key'],
+  retry: { maxAttempts: 3, backoffMs: 200, maxBackoffMs: 2_000 },
+  async execute(input, context) {
+    const apiKey = await context.getCredential('payments-api-key');
+    return chargeCustomer(input, {
+      apiKey,
+      idempotencyKey: context.idempotencyKey,
+    });
+  },
+});
+```
+
+`runAgent` throws `RunPausedError`, `streamAgent` emits `run.paused`, and
+`startAgent` leaves the paused snapshot consultable. Continue an approval from
+any runtime sharing the durable store:
+
+```ts
+await app.resumeRun(runId, {
+  type: 'approval',
+  approvalId,
+  decision: 'approve',
+  actor: { id: 'reviewer-42' },
+});
+```
+
+Use `InMemoryRunStore` for ephemeral runs, `@fevex/sqlite` for local durability,
+or `@fevex/postgres` across multiple processes:
+
+```ts
+import { createSQLiteRunStore } from '@fevex/sqlite';
+
+const runStore = createSQLiteRunStore({
+  filename: '.fevex/runs.db',
+});
+```
+
+SQLite creates and migrates its local file automatically. PostgreSQL migrations
+remain explicit and are intended for server deployments.
+
+Policies run before approval resolution, credentials and each effect or retry.
+Credential values are not stored or sent to the model, and tool outputs that
+contain a resolved value are rejected.
+
+## Limits
+
+Agent runs default to 8 model steps and 16 sequential tool calls. Override
+them on the agent:
+
+```ts
+defineAgent({
+  name: 'support',
+  instructions: 'Answer account questions clearly.',
+  limits: {
+    maxSteps: 4,
+    maxToolCalls: 6,
+    maxInputTokens: 10_000,
+    maxOutputTokens: 2_000,
+  },
+});
+```
+
+Input token limits are cumulative run budgets checked from provider usage after
+each model response. Output token limits are also sent to model gateways as the
+remaining preventive cap, then verified from reported usage. A configured token
+limit fails explicitly when the gateway does not report the corresponding usage
+field. Set a token limit to `false` to leave it unlimited.
+
+Cancellation is immediate from the caller's perspective. Models, tools and
+schema validators still need to honor the supplied `AbortSignal` to stop their
+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
+unchanged:
+
+```ts
+import { createOpenTelemetryExporter } from '@fevex/opentelemetry';
+
+const app = createFevex({
+  models,
+  agents,
+  tools,
+  observability: {
+    exporters: [createOpenTelemetryExporter()],
+    calculateCost({ usage }) {
+      return {
+        amount: (usage.totalTokens ?? 0) * 0.000_001,
+        currency: 'USD',
+      };
+    },
+  },
+});
+
+await app.runAgent('support', { input: 'Hello' });
+await app.flushObservability();
+```
+
+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. 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
+
+`@fevex/core/evals` runs local datasets sequentially with fresh sessions:
+
+```ts
+import {
+  exactOutputScorer,
+  runEvaluation,
+  toolSelectionScorer,
+} from '@fevex/core/evals';
+
+const report = await runEvaluation({
+  app,
+  suiteName: 'support-regression',
+  targetVersion: 'v2',
+  agentName: 'support',
+  dataset: {
+    name: 'support',
+    version: '1',
+    cases: [{
+      id: 'active-account',
+      input: 'Check account 42',
+      expected: {
+        output: { answer: 'Account 42 is active.' },
+        tools: ['accounts_get'],
+      },
+    }],
+  },
+  scorers: [exactOutputScorer(), toolSelectionScorer()],
+});
+```
+
+Built-in deterministic scorers cover exact output, ordered or unordered tool
+selection, forbidden tools, max latency, max tokens and max cost. Use
+`serializeEvalReport` for a canonical, versionable JSON baseline, `jsonReporter`
+or `textReporter` with your own write callback, and `compareEvaluationReports`
+to fail CI when cases disappear, passing scores fail or scores drop beyond the
+configured tolerance.
+
+## Connections
+
+Connections turn remote tool providers into normal Fevex tools. Names are local
+and explicit: a connection named `docs` with remote tool `search` is exposed to
+agents as `docs__search`.
+
+```ts
+import { createFevex, defineAgent, defineConnection } from '@fevex/core';
+import { createMcpToolProvider } from '@fevex/mcp';
+
+const docs = defineConnection({
+  name: 'docs',
+  provider: createMcpToolProvider({ url: 'https://example.com/mcp' }),
+  allowlist: ['search'],
+  timeoutMs: 30_000,
+  tools: {
+    search: {
+      description: 'Search docs.',
+      inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+    },
+  },
+});
+
+createFevex({
+  models: {},
+  agents: [defineAgent({
+    name: 'assistant',
+    instructions: 'Help.',
+    tools: ['docs__search'],
+  })],
+  connections: [docs],
+});
+```
+
+Fevex owns allowlists, timeouts, approvals, policies and safe error messages.
+MCP metadata and annotations are treated as untrusted hints. The first MCP
+adapter supports Streamable HTTP only; `stdio`, resources, prompts and legacy
+HTTP+SSE stay out of scope.
+
+OpenAPI providers use the same connection contract:
+
+```ts
+import { createOpenApiToolProvider } from '@fevex/openapi';
+
+const billing = defineConnection({
+  name: 'billing',
+  provider: createOpenApiToolProvider({
+    document: openApiDocument,
+    operations: { allow: ['getInvoice'] },
+    headers: () => ({ Authorization: `Bearer ${process.env.BILLING_TOKEN}` }),
+  }),
+  allowlist: ['getInvoice'],
+});
+```
+
+`@fevex/openapi` accepts bundled JSON OpenAPI 3.1.x documents, local refs and
+JSON request/response bodies. It rejects unsupported JSON Schema keywords,
+remote refs, YAML, OpenAPI 3.0/3.2 and non-JSON payloads instead of silently
+dropping constraints.
+
+## Tool search and large results
+
+Agents with large tool catalogs can expose `fevex__search_tools` instead of
+sending every schema on every turn:
+
+```ts
+defineAgent({
+  name: 'support',
+  instructions: 'Answer with the available tools.',
+  tools: [...],
+  toolSearch: { mode: 'auto', threshold: 30, pinned: ['accounts_get'] },
+});
+```
+
+`auto` enables search above the threshold, `on` always does and `off` exposes
+every tool. Search only indexes the agent's own tools; allowlists, policies and
+approvals still apply when a loaded tool executes. Add `semantic.embeddings` to
+fuse lexical and vector candidates with Reciprocal Rank Fusion; failures fall
+back to lexical. An optional `semantic.reranker` can reorder the fused top
+candidates.
+
+Tools can cap serialized results with `maxResultBytes`, or an agent/run can set
+`limits.maxToolResultBytes`. The default cap is 1 MiB; use `false` to disable it.
+Store larger outputs through `context.artifacts` and return the descriptor;
+otherwise the run fails with `TOOL_RESULT_TOO_LARGE`.
+
+## Channels
+
+`@fevex/core/channels` provides a small adapter contract and `handleChannelInput`
+for hosting apps that receive messages from another surface:
+
+```ts
+import { handleChannelInput } from '@fevex/core/channels';
+
+const sessions = new Map<string, string>();
+
+const result = await handleChannelInput(
+  { id: 'm1', conversationId: 'c1', text: 'hello' },
+  {
+    fevex: app,
+    agentName: 'assistant',
+    adapter: {
+      name: 'memory',
+      async parse(input) {
+        return {
+          id: input.id,
+          deliveryId: input.id,
+          conversationId: input.conversationId,
+          content: input.text,
+        };
+      },
+      async deliver(output) {
+        return output;
+      },
+    },
+    resolveSessionId(message) {
+      return sessions.get(message.conversationId);
+    },
+  },
+);
+
+if (!result.ignored) sessions.set(result.message.conversationId, result.run.sessionId);
+```
+
+The helper emits local channel events around the run. Slack verification,
+acknowledgement, durable redelivery and deduplication remain outside this core
+helper and belong to the Slack adapter phase.
+
+## Knowledge and memory
+
+`@fevex/core/knowledge` keeps external context separate from sessions:
+
+```ts
+import {
+  InMemoryMemoryStore,
+  createFevex,
+  defineAgent,
+  defineContextProvider,
+  defineSkill,
+} from '@fevex/core';
+
+const app = createFevex({
+  models,
+  memoryStore: new InMemoryMemoryStore(),
+  contextProviders: [
+    defineSkill({
+      name: 'refunds',
+      instructions: 'Refunds are allowed for 30 days after purchase.',
+    }),
+    defineContextProvider({
+      name: 'account',
+      async read({ context }) {
+        return [{ id: 'tier', content: `Plan: ${context?.attributes?.plan ?? 'free'}` }];
+      },
+    }),
+  ],
+  agents: [
+    defineAgent({
+      name: 'support',
+      instructions: 'Answer with business context.',
+      skills: ['refunds'],
+      context: ['account'],
+      memory: { read: true, write: true },
+    }),
+  ],
+});
+```
+
+For longer instructions, keep them in an explicit `SKILL.md` file. Only the
+frontmatter metadata enters the prompt; the body loads on demand:
+
+```ts
+import { createAgentsMdContextProvider, loadSkillFile } from '@fevex/core';
+
+const refunds = await loadSkillFile('./skills/refunds/SKILL.md');
+
+const app = createFevex({
+  models,
+  contextProviders: [refunds, createAgentsMdContextProvider('./AGENTS.md')],
+  agents: [
+    defineAgent({
+      name: 'support',
+      instructions: 'Answer with business context.',
+      skills: ['refunds'],
+      context: ['agents-md'],
+    }),
+  ],
+});
+```
+
+`SKILL.md` uses `name` and `description` frontmatter. The reserved
+`fevex__load_skill` tool loads the body and lists files under `references/`,
+`scripts/` and `assets/`; scripts are not executed by the runtime. Paths are
+explicit, with no automatic discovery.
+
+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` | Common runtime, definitions and contracts |
-| `fevex/agents` | Agent definitions |
-| `fevex/models` | Provider-neutral model contracts |
-| `fevex/tools` | Tool definitions and execution context |
-| `fevex/runtime` | Run request and result contracts |
-| `fevex/testing` | Deterministic testing helpers |
+| `@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 |
+| `@fevex/core/tools` | Tool, connection and provider contracts |
+| `@fevex/core/workflows` | Durable workflow definitions |
+| `@fevex/core/teams` | Multiagent team definitions |
+| `@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, bounded export queue, redaction and cost contracts |
+| `@fevex/core/evals` | Datasets, scorers, reporters and regressions |
+| `@fevex/core/testing` | Deterministic testing helpers |
+
+All subpaths ship in the same `@fevex/core` package.
+
+## Source Layout
 
-All subpaths ship in the same `fevex` package.
+Each public subpath is a folder under `src`. Its `index.ts` is intentionally a
+small export barrel; contracts and implementations live in files named after
+their responsibility. For example, `runtime/run-store.ts` owns persistence
+contracts while `runtime/in-memory-run-store.ts` owns the development
+implementation. Keep provider-neutral public contracts in their domain folder
+and orchestration details under `src/internal`.
+
+When adding a feature:
+
+- extend an existing responsibility before creating a new abstraction;
+- keep platform or provider-specific behavior outside `@fevex/core`;
+- export public API only through the domain barrel and preserve existing
+  subpath imports;
+- document lifecycle, persistence, security and replay semantics; avoid
+  comments that only restate the TypeScript signature;
+- add the smallest test that exercises the behavior at its public boundary.
 
 ## Current Scope
 
 The MVP intentionally supports:
 
-- one model response, or one model-tool-model cycle;
-- an in-memory runtime;
-- synchronous event observers;
+- bounded multi-step model-tool loops with sequential tool execution;
+- native provider streaming and durable, consultable runs;
+- synchronous event observers and `AsyncIterable` event streaming;
+- local traces, OpenTelemetry export and deterministic evaluation suites;
 - optional Standard Schema validation;
-- `AbortSignal` cancellation.
+- immediate `AbortSignal` cancellation with cooperative underlying work.
 
-It does not yet include streaming, retries, persistence, approvals, a CLI or
-official provider adapters. `AgentDefinition.limits` is reserved and has no
-runtime effect yet.
+It does not include a CLI, hosted observability service, model-judge evals or
+human evaluation workflows.
 
 ## License
 
 Apache-2.0
+
+### Connection discovery isolation
+
+Connection tool metadata is discovered for each resolution using that caller's
+context. The core does not cache catalogs or rejected discovery promises across
+calls. A failed discovery can therefore recover on the next attempt without
+recreating the runtime. Providers must scope their own state to an identity;
+`@fevex/mcp` binds each instance to its first resolved header set and rejects
+changes. Use a separate MCP provider/connection per identity and recreate it when
+credentials rotate. This adds discovery requests in exchange for avoiding stale
+or cross-identity catalogs. Tool calls are not automatically replayed by MCP.
+
+### Paged event reads and SSE
+
+`listEvents(runId, { after, limit, order })` returns events whose sequence is
+strictly greater than the cursor's sequence. `order` is `asc` by default;
+`{ order: 'desc', limit: 1 }` retrieves the latest event. `limit` must be a positive
+safe integer. Omitting it preserves the existing complete-result behavior.
+Unknown cursors and cursors belonging to another run reject with
+`FevexRunError` code `INVALID_CURSOR` (HTTP 400).
+
+SQLite and PostgreSQL resolve the cursor by ID and filter, order and limit in
+SQL using the existing `(run_id, sequence)` index. Prior event payloads are not
+loaded to find the cursor. Custom run stores must implement these options and
+the cursor error contract before being used with the updated HTTP handler.
+
+The HTTP handler accepts `eventPageSize` (default 100, range 1–1000). It uses this
+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. `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
+
+Agent runs retain the effective `modelName` and a `modelMetadata` snapshot when
+the gateway supplies metadata. Traces and cost calculators use this identity,
+including per-request model overrides, after terminal checkpoint cleanup and
+across pause/resume. These fields are optional for older stored runs; resuming
+an older run fills them from its checkpoint's resolved model.
+
+### Local sandbox limits
+
+The local development sandbox sends `SIGTERM` on timeout or cancellation, then
+`SIGKILL` after 100 ms if the process has not closed. Cancellation rejects with
+the caller's reason after process cleanup. Output limits apply separately to
+stdout and stderr in UTF-8 bytes, omitting an incomplete trailing character.
+This subprocess control does not provide operating-system isolation.
+
+### Production sandbox
+
+Use `@fevex/sandbox-docker` for isolated runs. It creates one long-lived
+container and workspace per run, uses `--network none` by default, drops Linux
+capabilities, applies PID, memory and CPU limits, and only forwards explicit
+environment variables. Fevex calls `cleanupRun` after terminal runs and
+`dispose` during shutdown; paused runs keep their resources for resume.
+
+```ts
+import { createDockerSandbox } from '@fevex/sandbox-docker';
+
+const sandbox = createDockerSandbox({
+  image: 'oven/bun:1-alpine',
+  commands: ['bun', 'sh'],
+  workspaceRoot: '/var/lib/fevex/sandboxes',
+});
+```