@aexhq/sdk 0.40.15 → 0.41.0

package/dist/_contracts/run-retention.d.ts

@@ -1,209 +0,0 @@
-import type { RunStatus } from "./status.js";
-export declare const RUN_RETENTION_SCHEMA_VERSION = 1;
-export declare const RUN_DELETION_MANIFEST_KIND = "aex.run_deletion_manifest.v1";
-export declare const RUN_DELETION_JOB_KIND = "aex.run_deletion_job.v1";
-export declare const RUN_DELETION_MANIFEST_CONTENT_TYPE = "application/json; charset=utf-8";
-export declare const RUN_RETENTION_REDACTION_SCANNER_VERSION = 1;
-export declare const RUN_DELETION_REASONS: readonly ["manual_delete", "retention_gc"];
-export type RunDeletionReason = (typeof RUN_DELETION_REASONS)[number];
-export declare const RUN_DELETION_MANIFEST_MODES: readonly ["dry_run", "final"];
-export type RunDeletionManifestMode = (typeof RUN_DELETION_MANIFEST_MODES)[number];
-export declare const RUN_DELETION_CANDIDATE_STATUSES: readonly ["selected", "blocked"];
-export type RunDeletionCandidateStatus = (typeof RUN_DELETION_CANDIDATE_STATUSES)[number];
-export declare const RUN_DELETION_BLOCKERS: readonly ["non_terminal", "retention_policy_disabled", "unexpired", "held", "retention_exempt", "unresolved_cleanup", "unresolved_custody"];
-export type RunDeletionBlocker = (typeof RUN_DELETION_BLOCKERS)[number];
-export declare const RUN_DELETION_COUNT_CLASSES: readonly ["object_store_objects", "outputs", "logs", "events", "assets", "db_event_rows", "db_output_rows", "capture_failures", "storage_samples", "custody_manifests"];
-export type RunDeletionCountClass = (typeof RUN_DELETION_COUNT_CLASSES)[number];
-export declare const RUN_DELETION_COUNT_STATUSES: readonly ["counted", "not_counted", "partial", "failed"];
-export type RunDeletionCountStatus = (typeof RUN_DELETION_COUNT_STATUSES)[number];
-export declare const RUN_DELETION_JOB_STATUSES: readonly ["queued", "planning", "blocked", "manifest_written", "deleting", "delete_failed", "completed", "failed"];
-export type RunDeletionJobStatus = (typeof RUN_DELETION_JOB_STATUSES)[number];
-export declare const RUN_DELETION_PROOF_STATUSES: readonly ["not_started", "running", "completed", "failed"];
-export type RunDeletionProofStatus = (typeof RUN_DELETION_PROOF_STATUSES)[number];
-export declare const RUN_DELETION_WRITE_STATUSES: readonly ["not_written", "written", "write_failed"];
-export type RunDeletionWriteStatus = (typeof RUN_DELETION_WRITE_STATUSES)[number];
-export declare const RUN_RETENTION_EXCLUDED_VALUE_CLASSES: readonly ["raw_paths", "object_keys", "filenames", "object_sizes", "hashes", "provider_ids", "vault_ids", "resource_ids", "resource_handles", "signed_urls"];
-export type RunRetentionExcludedValueClass = (typeof RUN_RETENTION_EXCLUDED_VALUE_CLASSES)[number];
-export interface RunRetentionPolicyV1 {
-    readonly mode: "retain_indefinitely" | "delete_after_days";
-    readonly manualDelete: "enabled";
-    readonly automaticDeletion: "disabled" | "enabled";
-    readonly retentionDays?: number;
-}
-export interface RunRetentionPolicyInput {
-    readonly automaticDeletion?: boolean;
-    readonly retentionDays?: number;
-}
-export interface RunDeletionCandidateRunV1 {
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly status: RunStatus | string;
-    readonly createdAt?: string;
-    readonly terminalAt?: string;
-    readonly held?: boolean;
-    readonly retentionExempt?: boolean;
-    readonly unresolvedCleanup?: boolean;
-    readonly unresolvedCustody?: boolean;
-}
-export interface RunDeletionBlockerV1 {
-    readonly code: RunDeletionBlocker;
-    readonly observedAt: string;
-}
-export interface RunDeletionCandidateV1 {
-    readonly status: RunDeletionCandidateStatus;
-    readonly reason: RunDeletionReason;
-    readonly evaluatedAt: string;
-    readonly eligibleAt?: string;
-    readonly blockers: readonly RunDeletionBlockerV1[];
-}
-export interface RunDeletionCandidateInput {
-    readonly run: RunDeletionCandidateRunV1;
-    readonly reason: RunDeletionReason;
-    readonly policy?: RunRetentionPolicyV1 | RunRetentionPolicyInput;
-    readonly now: string;
-}
-export interface RunDeletionCountV1 {
-    readonly class: RunDeletionCountClass | string;
-    readonly count: number;
-    readonly status: RunDeletionCountStatus;
-    readonly countedAt?: string;
-    readonly errorClass?: string;
-}
-export interface RunDeletionManifestRunV1 {
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly status: RunStatus | string;
-    readonly createdAt?: string;
-    readonly terminalAt?: string;
-    readonly eligibleAt?: string;
-}
-export interface RunDeletionManifestRequestV1 {
-    readonly reason: RunDeletionReason;
-    readonly actorClass: "user" | "api_key" | "system" | "operator";
-}
-export interface RunDeletionManifestSummaryV1 {
-    readonly totalCount: number;
-    readonly failedCountClasses: number;
-    readonly partialCountClasses: number;
-    readonly blockerCount: number;
-    readonly counts: readonly RunDeletionCountV1[];
-}
-export interface RunDeletionManifestRedactionV1 {
-    readonly policy: "counts_status_timestamps_only";
-    readonly scannerVersion: typeof RUN_RETENTION_REDACTION_SCANNER_VERSION;
-    readonly excludes: readonly RunRetentionExcludedValueClass[];
-}
-export interface RunDeletionManifestV1 {
-    readonly schemaVersion: typeof RUN_RETENTION_SCHEMA_VERSION;
-    readonly kind: typeof RUN_DELETION_MANIFEST_KIND;
-    readonly generatedAt: string;
-    readonly mode: RunDeletionManifestMode;
-    readonly run: RunDeletionManifestRunV1;
-    readonly request: RunDeletionManifestRequestV1;
-    readonly candidate: RunDeletionCandidateV1;
-    readonly summary: RunDeletionManifestSummaryV1;
-    readonly redaction: RunDeletionManifestRedactionV1;
-}
-export interface RunDeletionManifestInput {
-    readonly generatedAt: string;
-    readonly mode: RunDeletionManifestMode;
-    readonly run: RunDeletionCandidateRunV1;
-    readonly request: RunDeletionManifestRequestV1;
-    readonly candidate?: RunDeletionCandidateV1;
-    readonly policy?: RunRetentionPolicyV1 | RunRetentionPolicyInput;
-    readonly counts?: readonly RunDeletionCountV1[];
-}
-export interface RunDeletionManifestProofV1 {
-    readonly status: RunDeletionWriteStatus;
-    readonly mode?: RunDeletionManifestMode;
-    readonly writtenAt?: string;
-}
-export interface RunDeletionPurgeProofV1 {
-    readonly status: RunDeletionProofStatus;
-    readonly startedAt?: string;
-    readonly completedAt?: string;
-    readonly deletedObjectCount?: number;
-}
-export interface RunDeletionOrderProofV1 {
-    readonly manifest: RunDeletionManifestProofV1;
-    readonly purge: RunDeletionPurgeProofV1;
-}
-export interface RunDeletionJobV1 {
-    readonly schemaVersion: typeof RUN_RETENTION_SCHEMA_VERSION;
-    readonly kind: typeof RUN_DELETION_JOB_KIND;
-    readonly jobId: string;
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly reason: RunDeletionReason;
-    readonly mode: RunDeletionManifestMode;
-    readonly status: RunDeletionJobStatus;
-    readonly createdAt: string;
-    readonly updatedAt?: string;
-    readonly order: RunDeletionOrderProofV1;
-    readonly candidate?: RunDeletionCandidateV1;
-    readonly summary?: RunDeletionManifestSummaryV1;
-}
-export interface RunDeletionJobInput {
-    readonly jobId: string;
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly reason: RunDeletionReason;
-    readonly mode: RunDeletionManifestMode;
-    readonly status: RunDeletionJobStatus;
-    readonly createdAt: string;
-    readonly updatedAt?: string;
-    readonly order: RunDeletionOrderProofV1;
-    readonly candidate?: RunDeletionCandidateV1;
-    readonly summary?: RunDeletionManifestSummaryV1;
-}
-export interface RunDeletionManifestWriteObject {
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly contentType: typeof RUN_DELETION_MANIFEST_CONTENT_TYPE;
-    readonly manifest: RunDeletionManifestV1;
-}
-export interface RunDeletionManifestObjectStore {
-    putRunDeletionManifestObject(object: RunDeletionManifestWriteObject): Promise<void>;
-}
-export interface RunDeletionManifestWriteResult {
-    readonly status: "written";
-    readonly schemaVersion: typeof RUN_RETENTION_SCHEMA_VERSION;
-    readonly runId: string;
-    readonly workspaceId: string;
-    readonly writtenAt: string;
-    readonly mode: RunDeletionManifestMode;
-}
-export interface RunDeletionManifestWriter {
-    writeRunDeletionManifest(input: RunDeletionManifestInput): Promise<RunDeletionManifestWriteResult>;
-}
-export type RunRetentionRedactionReason = "forbidden_field_name" | "signed_url" | "object_store_key" | "vault_id" | "private_resource_handle" | "hash_like_value";
-export interface RunRetentionRedactionFinding {
-    readonly path: string;
-    readonly reason: RunRetentionRedactionReason;
-    readonly valueLength?: number;
-}
-export declare class RunRetentionValidationError extends Error {
-    readonly code = "run_retention_contract_invalid";
-    constructor(message: string);
-}
-export declare class RunRetentionRedactionError extends Error {
-    readonly code = "run_retention_payload_not_public_safe";
-    readonly findings: readonly RunRetentionRedactionFinding[];
-    constructor(findings: readonly RunRetentionRedactionFinding[]);
-}
-export declare class FakeRunDeletionManifestObjectStore implements RunDeletionManifestObjectStore {
-    #private;
-    putRunDeletionManifestObject(object: RunDeletionManifestWriteObject): Promise<void>;
-    getByRunId(runId: string): RunDeletionManifestV1 | undefined;
-    get(runId: string): RunDeletionManifestV1 | undefined;
-    listRunIds(): readonly string[];
-}
-export declare function createRunDeletionManifestWriter(store: RunDeletionManifestObjectStore): RunDeletionManifestWriter;
-export declare function writeRunDeletionManifest(store: RunDeletionManifestObjectStore, input: RunDeletionManifestInput): Promise<RunDeletionManifestWriteResult>;
-export declare function buildRunRetentionPolicy(input?: RunRetentionPolicyInput): RunRetentionPolicyV1;
-export declare function evaluateRunDeletionCandidate(input: RunDeletionCandidateInput): RunDeletionCandidateV1;
-export declare function buildRunDeletionManifest(input: RunDeletionManifestInput): RunDeletionManifestV1;
-export declare function assertRunDeletionOrder(proof: RunDeletionOrderProofV1): void;
-export declare function buildRunDeletionJob(input: RunDeletionJobInput): RunDeletionJobV1;
-export declare function scanRunRetentionPayloadForSensitiveValues(input: unknown): readonly RunRetentionRedactionFinding[];
-export declare function assertPublicSafeRunRetentionPayload(input: unknown): void;

package/docs/outputs.md

@@ -1,267 +0,0 @@
----
-title: Outputs
----
-
-# Outputs
-
-Every session produces durable metadata (status, events, cleanup state) and an outputs namespace. By default, managed runs capture the regular files present in the container when the agent exits, EXCLUDING the inputs the platform itself materialized for you (your mounted `files`/`skills`) — those are excluded by IDENTITY (their exact destination paths and skill-dir prefixes), not by any before/after timing comparison. There is no default or official output directory. Use `outputs.allowedDirs` only when you want to narrow capture to specific roots, and `outputs.deniedDirs` to subtract noise. `session.download()` returns the public session record — metadata, typed events, and captured output bytes — as a zip; the per-namespace verbs (`session.outputs().download()` / `session.events().download()` / `session.downloadMetadata()`) return one slice each.
-
-The output verbs below hang off the session's `outputs()` accessor
-(`session.outputs().list()`, `.read()`, `.download()`, …). Reach a handle from a
-live session (`openSession` / `run`) or reopen one later with
-`aex.openSession(sessionId)`; the client also exposes cross-session reads under
-`aex.sessions.*`.
-
-## Quickstart
-
-```ts
-import { Models } from "@aexhq/sdk";
-
-const session = await aex.openSession({
-  model: Models.CLAUDE_HAIKU_4_5,
-  apiKeys: { anthropic: apiKey }
-});
-
-await session.send("Produce a report and save it as a file.").done();
-await session.wait();
-await session.download({ to: "./session.zip" });
-```
-
-```bash
-npx aex download <session-id> --out ./session.zip --api-key …
-```
-
-## The three namespaces
-
-A session's downloadable content is organised into three logical namespaces, each with a matching verb. Every zip is assembled **client-side** from the public read endpoints (session record + `session.events().list()` + `session.outputs().list()` + per-output `/download`) — there is no server-side archive route.
-
-| Namespace | What it holds | Verb | CLI |
-| --- | --- | --- | --- |
-| `outputs` | The session's real deliverables. | `session.outputs().download()` | `download <id> --only outputs` |
-| `events` | Typed event-channel records (`events.jsonl`) plus a namespace manifest. | `session.events().download()` | `download <id> --only events` |
-| `metadata` | The session record (`run.json`) plus a namespace manifest. | `session.downloadMetadata()` | `download <id> --only metadata` |
-
-Platform diagnostics are stored outside the public archive under `runs/<runId>/internal/logs/` for internal/admin access only. They are not exposed by the SDK download helpers or the public CLI.
-
-## What `session.download()` returns
-
-`session.download()` is the **whole-session** verb — it bundles the public namespaces as top-level folders. It is distinct from `session.outputs().download(selector)`, which fetches a single file. Layout:
-
-```
-metadata/run.json     # run record (status, runId, timestamps, snapshot)
-metadata/submission.json # public-safe submission snapshot, when available
-metadata/cost.json    # public cost telemetry, when available
-events/events.jsonl   # typed event-channel records, ordered
-outputs/<name>        # one file per deliverable
-manifest.json         # RunRecordManifestV1
-```
-
-`manifest.json` is the versioned `RunRecordManifestV1` described in [Run record](run-record.md). It carries:
-
-| Field | Meaning |
-| --- | --- |
-| `schemaVersion` / `runRecordSchemaVersion` | Manifest and run-record contract versions. |
-| `runId` | The run the zip was assembled for. |
-| `namespaces[]` / `files[]` | Namespace inventory and per-file presence state. Optional submission/cost files are marked `present` only when the client assembled actual entries; custody remains `pending` until its writer/read path exists. |
-| `outputs[]` | `{ id, filename, sizeBytes?, contentType? }` — one row per file successfully written under `outputs/`. |
-| `errors[]` | `{ namespace, id, filename, message }` — per-artifact byte fetches that failed during assembly. Best-effort: a failure records an entry here and is skipped from the tree rather than aborting the whole zip. |
-
-The single-namespace verbs return the same per-file bytes at the zip root (e.g. `session.outputs().download()` -> `report.txt` + `manifest.json`; `session.events().download()` -> `events.jsonl` + `manifest.json`; `session.downloadMetadata()` -> `run.json` + `manifest.json`).
-
-## Downloading one output
-
-`session.outputs().download(selector)` returns a `Uint8Array`. Omit the selector to download the whole outputs namespace as a zip; pass an output from `session.outputs().list()`, an `{ id }`, or a path selector against the listed `Output.filename` values to download one file:
-
-```ts
-const allOutputs = await session.outputs().download();
-await session.outputs().download(undefined, { to: "./outputs.zip" });
-
-const report = await session.outputs().download({ path: "reports/report.txt" });
-console.log(new TextDecoder().decode(report));
-
-const looseReport = await session.outputs().download({ path: "report.txt", match: "suffix" });
-console.log(looseReport.byteLength);
-```
-
-## Reading one output as text
-
-`session.outputs().read(selector, options?)` reads ONE output file as byte-capped, decoded UTF-8 text. It streams the file and stops at `options.maxBytes` (default 50 KB, ceiling 10 MB), so a large deliverable never fully buffers — this is the read built for handing a session's output to an LLM tool. Select the file by `{ path }` (suffix-matchable) or `{ id }`. To read from a session id without a live handle, use `aex.sessions.outputs(sessionId).read(selector, options?)` — the same accessor, addressed by id.
-
-```ts
-const { text, truncated, totalBytes } = await session.outputs().read(
-  { path: "report.md", match: "suffix" },
-  { maxBytes: 50_000, grep: "error" }
-);
-
-if (truncated) {
-  // text is a prefix of a larger file — narrow with `grep` or a tighter `path`.
-}
-```
-
-Check `truncated` before treating `text` as complete. Pass `options.grep` (a substring or `RegExp`) to keep only matching lines of the capped text. The returned `output` is the matched `Output` record, and `totalBytes` is the file's full size when the server reports it.
-
-## Finding outputs
-
-`session.outputs().list(query?)` can filter the captured output list client-side. Use `session.outputs().find(query)` when you want discovery to be explicit, or `session.outputs().findOne(query)` when exactly one file is expected:
-
-```ts
-const images = await session.outputs().find({ type: "image" });
-const jsonReports = await session.outputs().list({
-  dir: "reports",
-  extension: ".json"
-});
-
-const report = await session.outputs().findOne({
-  filename: "summary.json",
-  contentType: "application/json"
-});
-if (report) {
-  const bytes = await session.outputs().download(report);
-}
-```
-
-Query fields compose with AND semantics:
-
-| Field | Match |
-| --- | --- |
-| `path` | Exact normalized output path. Leading `/` and `outputs/` are ignored. |
-| `filename` | Basename match, as a string or `RegExp`. |
-| `dir` / `recursive` | Directory prefix. `recursive` defaults to `true`; set `false` for direct children only. |
-| `extension` | Case-insensitive extension, with or without a leading dot. |
-| `contentType` | Exact content type or a prefix wildcard such as `image/*`. |
-| `type` | High-level type: `text`, `json`, `image`, `audio`, `video`, `pdf`, `archive`, `binary`, or `unknown`. |
-
-`session.outputs().findOne(query)` returns `null` when nothing matches and throws `RunStateError` when the query matches more than one output.
-
-## Searching outputs
-
-Search is metadata-only (reference hits — filename / extension / content type — no bytes). `filename` accepts a `string` (case-insensitive substring) or a `RegExp`. A content-shaped query (`content`/`text`/…) throws a typed "content search unsupported" rather than silently returning zero hits.
-
-```ts
-// One session's outputs:
-const hits = await session.outputs().search({ filename: /report/i });
-
-// Across every run in the workspace (or scope with runIds):
-const all = await aex.outputs.search({ extension: "md", runIds: ["run-a", "run-b"] });
-```
-
-Each hit is `{ runId, outputId, filename?, sizeBytes?, contentType? }`; read the bytes with `session.outputs().read(...)` / `.download(...)`.
-
-## CLI
-
-The `aex outputs` verb is a thin pass-through over the same SDK accessor, so every per-file operation has a subcommand (`npx aex` on a local install):
-
-```bash
-npx aex outputs <session-id>                          # list captured outputs (NDJSON)
-npx aex outputs read <session-id> <path>              # read one file as capped text (JSON)
-npx aex outputs download <session-id> <path> --out f  # download one file's raw bytes
-npx aex outputs link <session-id> <path>              # mint a temporary download URL (JSON)
-npx aex outputs find <session-id> --name S --ext E --type T
-npx aex outputs search --query S --ext E --run-id ID  # cross-run metadata search
-```
-
-`aex outputs search` (no session id) is the cross-run search (`aex.outputs.search`); the whole-namespace zip stays `aex download <session-id>`.
-
-## Temporary output links
-
-Use `session.outputs().link(selectorOrQuery, options?)` when another process, browser, media tag, or downloader needs a direct artifact URL instead of bytes buffered through the SDK.
-
-```ts
-const link = await session.outputs().link(
-  { path: "reports/summary.json" },
-  { expiresIn: "15m" }
-);
-
-console.log(link.url, link.expiresAt);
-```
-
-Selectors can be an output id, an `Output` object, a path selector, or an `OutputQuery`. `expiresIn` accepts seconds or `"15m"`, `"1h"`, or `"1d"`; the default is `"1h"`.
-
-The returned URL is a reusable bearer URL until it expires. Anyone who has it can read that artifact during the TTL. aex does not promise one-time use or early revocation for these direct artifact URLs.
-
-For large files, `session.outputs().fetch()` mints the same temporary URL and returns the `Response` from fetching it directly, without adding the SDK API key to that second request:
-
-```ts
-const response = await session.outputs().fetch({ type: "video", filename: /clip\.mp4$/ });
-const stream = response.body;
-```
-
-## Lifecycle behaviour
-
-`session.download()` works at any session state — it reads whatever the public endpoints currently expose, so the zip reflects the session as of the call:
-
-| Run state | Behaviour |
-| --- | --- |
-| `queued` / `claiming` / `provisioning` | `metadata/run.json` reflects the early state; `events/` and `outputs/` are typically empty. |
-| `provider_running`, mid-session / `capturing_outputs` / `cleaning_up` | Whatever events + outputs have been captured so far. Call again after the session parks for the complete set. |
-| `idle` / `suspended` (parked between turns) | The complete archive for every turn sent so far; a later turn appends to it. |
-| `succeeded` / `failed` / `timed_out` / `cancelled` | The complete typed event archive + all captured outputs. |
-
-## `outputs.allowedDirs` — override capture roots
-
-```ts
-aex.openSession({
-  /* ... */
-  outputs: {
-    allowedDirs: ["/workspace/reports", "/workspace/state"]
-  }
-});
-```
-
-When omitted, aex captures the whole filesystem delta. When supplied, `outputs.allowedDirs` is a whitelist that replaces that default with the listed roots. In other words, explicit `outputs.allowedDirs` narrows capture; it does not add paths on top of `/`.
-
-Validation:
-
-- absolute UNIX paths only (`/...`),
-- no `..` segments, no NUL bytes,
-- maximum 32 entries,
-- maximum 512 bytes per entry.
-
-Runtime notes:
-
-- The managed runtime captures the regular files under the capture roots at terminal time, EXCLUDING the inputs the platform itself materialized (your mounted `files`/`skills`) by IDENTITY — their exact destination paths and skill-dir prefixes are threaded into the capture filter, so an untouched mounted input is never re-emitted as an output regardless of path policy or timing.
-- If you pass an explicit root that does not exist by terminal time, that root contributes no files.
-
-## `outputs.deniedDirs` — subtract noise
-
-```ts
-aex.openSession({
-  /* ... */
-  outputs: {
-    deniedDirs: ["node_modules", "/var/cache", "*.tmp"]
-  }
-});
-```
-
-`outputs.deniedDirs` is subtracted from the capture roots. Entries may be an absolute subtree (`/var/cache`), a bare path segment (`node_modules`), or a `*.ext` extension match. Denied entries beat allowed roots. Platform-mandatory excludes, including pseudo-filesystems and secret/platform paths, always apply and cannot be re-included.
-
-Mechanism (no platform-magical paths — this is honest):
-
-1. The hosted platform materializes the workspace (your mounted `files`/`skills`) and records the exact destination paths + skill-dir prefixes it wrote.
-2. The agent runs normally. There is no extra model turn and no synthetic sync instruction.
-3. When the agent exits, the runner scans the capture roots and drops any file whose path is a materialized INPUT (exact path or under a materialized skill dir) — inputs are excluded by WHO PUT THEM THERE (the platform), not by timing.
-4. The runner uploads the remaining regular files to durable run artifact storage. Diagnostic log paths are routed to internal diagnostics under `runs/<runId>/internal/logs/`; other paths are routed to `outputs`.
-
-Cost: output capture does not add a model turn. The runner pays a filesystem scan and upload cost near the end of the run.
-
-Capture notes:
-
-- Files over a configured per-file size cap are skipped.
-- Once total file or byte caps are reached, remaining changed files are dropped from upload.
-- Files that vanish between scan and upload are skipped.
-- Upload failures are recorded in runner diagnostics. The zip's `manifest.errors[]` only records byte fetches that failed while assembling the download archive.
-
-## Runs without explicit `outputs.allowedDirs`
-
-Metadata still gets the full treatment. aex captures every regular file the run created or modified outside mandatory platform excludes. A run that produces no files still returns a whole-session zip with `metadata/run.json`, `events/events.jsonl`, and `manifest.json` (manifest `outputs: []`).
-
-## Mid-session download semantics
-
-Mid-session calls are **best-effort and side-effect-free**: they expose whatever artifacts have already been uploaded. Files written by the agent are normally uploaded near terminal, after the runner scans the capture roots. If you need the full output set, wait for the session to park and call `session.download()` again.
-
-## Safety
-
-- Filenames are sanitized for cross-platform safety; collisions are disambiguated with a short id suffix before the extension.
-- Downloads stay within the requested local directory.
-- The archive endpoint is workspace-scoped (`outputs:read` scope) and rate-limited (`AEX_RATE_LIMIT_RUN_ARCHIVE_PER_MINUTE`, default 30/min/workspace).
-- `manifest.json` never contains file bytes — only ids, paths, sizes, content types.

package/docs/run-config.md

@@ -1,58 +0,0 @@
----
-title: Run configuration
----
-
-# Run configuration
-
-A run config is the credential-free subset of the session options (`openSession` / `run`) that you can keep in code or load from a JSON file. It is not a platform object, saved definition, DSL, trigger, or persistent agent profile. aex only stores the immutable session record created when the session lands.
-
-Allowed fields:
-
-- `model` - required.
-- `system` - optional system message.
-- `mcpServers` - array of `McpServerRef`; headers are split into the vaulted secrets channel server-side.
-- `environment` - `{ networking?, packages?, variables? }`. Networking is open by default; set `networking.mode` to `limited` only when you want an allowlist. `variables` are merged into the in-container `RUNTIME.env` / `RUNTIME.json` mounts. (Run secrets go in `environment.secrets`, which carries live `Secret` instances and is not part of a shareable config.)
-- `runtime` - optional managed-runtime preset. Prefer `Sizes` in TypeScript.
-- `metadata` - non-secret structured metadata.
-- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd?, maxTurns? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap; `maxTurns` caps the agent's iteration count for the turn (a positive integer — omit to accept the platform default of 20, clamped to the ceiling). See [Limits & quotas](limits-and-quotas.md).
-
-`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `skills`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `skills` entries built with `Skill.fromDir(...)`, `Skill.fromUrl(...)`, or the other `Skill.from*` factories, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentRunId` option. The wire contract carries a per-run `limits` object (the exported `RunLimits` type: `maxConcurrentChildRuns`, `maxSubagentDepth`, `maxSpendUsd`, `maxTurns`), and the session surface exposes its spend and iteration dials via `overrides.maxSpendUsd` and `overrides.maxTurns`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
-
-Secrets never live in run config. Pass provider keys through the top-level
-`apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or
-the equivalent host-mode flags (`--anthropic-api-key`, `--mcp-auth`) in the CLI.
-See [Secrets](secrets.md) for secret lifecycles and [Credentials](credentials.md)
-for credential handling.
-
-## Reuse in code
-
-Use an ordinary function when you want reusable typed parameters. aex does not store or execute this function; it only receives the parameters you pass.
-
-```ts
-import { Models } from "@aexhq/sdk";
-
-function summarise(topic: string) {
-  return {
-    model: Models.CLAUDE_HAIKU_4_5,
-    system: "You are a concise automation agent.",
-    message: `Write a short answer about ${topic}.`
-  };
-}
-
-await aex.run({
-  ...summarise("agent-first SDK design"),
-  apiKeys: { anthropic: apiKey }
-});
-```
-
-## CLI
-
-The `aex run` host subcommand accepts the same run config either as a JSON file:
-
-```bash
-aex run --config ./run.json \
-  --api-key "$AEX_API_KEY" \
-  --anthropic-api-key "$ANTHROPIC_API_KEY"
-```
-
-...or as explicit flags (`--model`, `--system`, `--prompt`, `--mcp`, `--mcp-auth`, `--runtime-size`, `--run-timeout`, `--metadata`). The two modes are mutually exclusive. Composition inputs attach with repeatable flags that map onto the SDK's `Skill`/`Tool`/`AgentsMd`/`File` factories: `--skill @bundle` (workspace skill), `--tool @tool.js` (custom tool module), `--agents-md @AGENTS.md`, and `--file @path` (mount a file into `/workspace`).