ai-runtime-engine 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to `ai-runtime` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to [Semantic
+Versioning](https://semver.org/). Development history and rationale live in
+[docs/DECISIONS.md](docs/DECISIONS.md) and [docs/PROGRESS.md](docs/PROGRESS.md).
+
+## [1.1.0] — 2026-08-29
+
+Closes out the two items 1.0 deferred. Additive and backward compatible.
+
+### Added
+
+- **npm skill packs** — a skill pack is any npm package that exports `skills: Skill[]`. Name installed
+  packs under `skills.packages` in config and the Runtime loads them from `node_modules` as trusted
+  dependencies (not workspace-jailed, unlike local `.ai-runtime/skills/` files). Ships an example pack,
+  `packages/example-skills` (`ai-runtime-example-skills`), and turns the repo into an npm workspace.
+- **Windows CI** — GitHub Actions now runs the typecheck/test/build matrix on `windows-latest` as well as
+  `ubuntu-latest` (`fail-fast: false`). Symlink-specific tests skip cleanly where symlink creation needs
+  elevation; a multi-hop symlink-chain jail test was added.
+
+## [1.0.0] — 2026-08-29
+
+First stable release. `ai-runtime` grew from a provider-agnostic AI **router** into a full **AI Runtime &
+Orchestration Platform** — the `Runtime` facade sits on top of the unchanged router (every model call
+still goes through `AI.run()`). The router's public API (`AI`, `AI.run()`, config, providers, tasks, CLI
+commands) is preserved and backward compatible.
+
+### Added — the Runtime
+
+- **Modes** — `auto | chat | plan | execute | orchestrate | agent | compare | debug`, with
+  per-run > config > env > detection precedence; a mode is never overridden, and unavailable modes
+  degrade to chat with a notice.
+- **Interactive terminal** — bare `ai-runtime` opens a REPL (natural language + slash commands); a
+  one-shot `run` for CI. Typed lifecycle events + a host contract.
+- **Conversations & memory** — verbatim conversation history (recoverable, secret-scrubbed), and durable
+  scoped memory with local BM25 retrieval, conflict supersession, and cascading deletion. Stateless mode
+  for CI/ephemeral use; monorepo-isolated local state under `~/.ai-runtime/`.
+- **Context compiler & token budgets** — budget-aware context assembly with retention levels, redundancy
+  removal, artifact references, and loss validation.
+- **Tools, permissions & skills** — deny-by-default permissions, a workspace path jail, allowlist-first
+  shell, git gating, and an untrusted-data boundary; versioned skills that validate by evidence.
+- **Planning & orchestration** — structured plans limited to registered skills/tools, an evidence-based
+  DAG executor, a replanning orchestrator, plan approval, and dry-run (zero mutations).
+- **Persistent executions & resume** — executions persisted before they start, a best-effort ownership
+  lease with heartbeat, checkpoints, `requestId` idempotency, and drift-aware resume/reconciliation.
+- **Comparison** — fan a task across models; agreement / differences / contradictions / missing info with
+  **evidence-first** ranking (a supplied validator beats a judge model).
+- **Exclude / prefer routing** — a hard exclude filter (visible in the trace) and a soft prefer nudge,
+  resolved from env + config + per-run.
+- **Learning & feedback** — provider/skill/workflow/plan outcome learning and `/feedback`, feeding only
+  soft provider preferences; a safety test proves learning can never override a hard gate.
+- **Local skill discovery** — auto-load manifests and module skills from `.ai-runtime/skills/`, discover
+  more across the workspace (report-only), all path-jailed.
+- **Bootstrap & maintenance** — `setup` (ask-before-mutation), `info`, an extended `doctor --json`, and
+  `cleanup` (opt-in retention + cache + integrity).
+
+### Security
+
+- Untrusted-data boundary; workspace path jail (tested against `..`, absolute paths, and symlinks);
+  allowlist-first shell with a destructive denylist; secrets named by env var only and redacted at every
+  egress. Every phase shipped an adversarial security review; the confirmed findings — including path-jail
+  escapes and resume/lease concurrency issues — were fixed and regression-tested.
+
+### Engineering
+
+- TypeScript, ESM, Node ≥ 22; offline-deterministic test suite; typecheck + full suite + build green at
+  every phase gate. GitHub Actions CI runs typecheck, tests, and build on every push and PR.
+
+## [0.1.0] — 2026-08-26
+
+Initial release: the provider-agnostic AI **router** — capability-based routing, filtering, seven-dimension
+scoring, evidence validation, fallback, health tracking, learning-based scoring, multi-model verification,
+budgets, MCP tools, OpenAPI-based adapter generation, and the `AI` class + CLI.
+
+[1.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.1.0
+[1.0.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v1.0.0
+[0.1.0]: https://github.com/pavankhandelwal21/ai-runtime/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 pavan
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,489 @@
+# ai-runtime
+
+**A provider-agnostic AI runtime for building and running AI features — without locking yourself to one vendor.**
+
+You point it at whatever AI providers you have (cloud APIs, a local model, or an internal endpoint). It
+routes each request to the best available model, and gives you a whole runtime on top of that: modes,
+an interactive terminal, memory, skills, tools, planning, orchestration, comparison, and learning.
+
+```ts
+import { Runtime } from 'ai-runtime-engine';
+
+const runtime = await Runtime.load();                 // reads your config + .env
+const result  = await runtime.run({ input: 'Fix the failing tests' });
+console.log(result.response?.text);
+```
+
+> **The idea:** providers are replaceable; capabilities are durable. You never have to know *which*
+> provider handled a request — you describe what you want, and the runtime picks the right model and runs it.
+
+> 📘 **New here?** Start with the **[hands-on Guide](docs/GUIDE.md)** — install to first run, with runnable
+> examples you can try offline (no API key needed).
+
+---
+
+## Contents
+
+- [What it is](#what-it-is)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [How to use it](#how-to-use-it) — modes, terminal, memory, skills, orchestration, comparison, learning
+- [Configuration](#configuration)
+- [What you need to do](#what-you-need-to-do) — a getting-started checklist
+- [CLI commands](#cli-commands)
+- [Package & distribution](#package--distribution)
+- [Security & privacy](#security--privacy)
+- [Troubleshooting](#troubleshooting)
+- [Further reading](#further-reading)
+- [Development](#development)
+
+---
+
+## What it is
+
+Hardcoding one AI provider means vendor lock-in, availability risk, and painful migrations — and different
+providers are better at different things (reasoning, speed, cost, privacy), while any of them can be
+rate-limited, out of quota, or down.
+
+`ai-runtime` separates **provider support** from **provider availability**. Configure whatever you have
+once; then, on every request, the runtime:
+
+1. figures out **what kind of work** it is (a quick answer, a plan, a multi-step task, a comparison…),
+2. **routes** it to the best model you have that can actually do it (by capability, health, privacy, cost),
+3. **executes** through one normalized interface and **validates** the result,
+4. **falls back** to the next-best model if something fails, and
+5. returns a clean result with a full trace of how it decided.
+
+Around that router sits the **Runtime**: an interactive terminal, conversation history, durable memory,
+context building, a skill/tool system with permissions, planning and orchestration, resumable long-running
+tasks, model comparison, and learning from outcomes. Everything runs over native `fetch` — **no provider
+SDKs**.
+
+---
+
+## Requirements
+
+- **Node.js 22 or newer.**
+- Git is optional (used to detect your workspace).
+- At least one AI provider — a cloud API key, or a local model via [Ollama](https://ollama.com) (no key needed).
+
+---
+
+## Install
+
+The npm package is **`ai-runtime-engine`**. Installing it gives you both a **library** and the
+**`ai-runtime`** command-line tool (the command name is `ai-runtime` — a package name need not match its
+command name).
+
+```bash
+# in your project (library + local CLI via `npx ai-runtime`)
+npm install ai-runtime-engine
+
+# or install globally to get the `ai-runtime` command on your PATH
+npm install -g ai-runtime-engine
+```
+
+Requires Node 22+. Use it as a library:
+
+```ts
+import { Runtime, AI } from 'ai-runtime-engine';
+```
+
+> **Naming:** the **product** is *AI Runtime*, the **npm package** is `ai-runtime-engine`, and the **CLI
+> command** is `ai-runtime`. The main API is `Runtime`; the lower-level router is `AI`.
+
+---
+
+## Quick start
+
+### Option A — the terminal (fastest)
+
+```bash
+npm install -g ai-runtime-engine   # (or use `npx ai-runtime …` from a project that installed it)
+
+ai-runtime setup     # detects your workspace, generates config + .env.example (asks before each write)
+# → add a provider key to .env, OR install Ollama for a local, no-key model
+ai-runtime doctor    # check that a provider is configured and reachable
+ai-runtime           # open the interactive terminal — just type what you want
+```
+
+### Option B — in code
+
+```ts
+import { Runtime } from 'ai-runtime-engine';
+
+const runtime = await Runtime.load({ workspace: process.cwd() });
+const r = await runtime.run({ input: 'Summarize what this repo does' });
+console.log(r.response?.text);
+```
+
+### Try it with no keys (offline)
+
+Use the built-in mock provider to see everything work without any credentials — great for tests and demos:
+
+```ts
+import { Runtime, MockProvider, makeModel } from 'ai-runtime-engine';
+
+const runtime = new Runtime();
+runtime.ai.registerProvider(new MockProvider({
+  id: 'demo',
+  models: [makeModel({ providerId: 'demo', id: 'demo-1', caps: { intelligence: ['reasoning'], output: ['text'] } })],
+}));
+const r = await runtime.run({ input: 'hello' });
+console.log(r.response?.text, r.routing?.selected);   // includes the full routing decision
+```
+
+---
+
+## How it works
+
+A request goes through one vendor-agnostic path. You provide the capabilities (providers, tools, skills,
+a workspace); the runtime decides *how* to use them.
+
+```
+runtime.run({ input })
+   │
+   ▼  resolve MODE (auto-detected, or set by you): chat · plan · execute · orchestrate · agent · compare · debug
+   │
+   ▼  build the model context under a token budget (workspace summary, memory, your request)
+   │
+   ▼  route to the best model  ──►  the ONE router:  filter (capability/health/privacy/cost) → score → pick
+   │                                                 → execute → validate → fall back on failure
+   │
+   ▼  for multi-step work: plan → run tools/skills as a DAG (succeed a step only on evidence) → replan on failure
+   │
+   ▼  result  { ok, response, routing trace, + plan / execution / comparison / memory as relevant }
+```
+
+Two principles hold everywhere:
+
+- **One router.** Every model call — chat, planning, comparison, a skill's own call — goes through the same
+  router. There's never a second, hidden selection engine.
+- **Evidence over claims.** A step "succeeds" only when there's proof (a tool returned ok, a validator
+  passed) — never because a model said "done."
+
+For the engine's internals (scoring dimensions, strategies, provider contracts, the `AI` API), see
+[docs/router.md](docs/router.md).
+
+---
+
+## How to use it
+
+Load the runtime once, then `run()` requests. It resolves a **mode** and dispatches.
+
+```ts
+const runtime = await Runtime.load({ workspace: process.cwd() });
+runtime.ai.registerProvider(myProvider);   // register providers the same way as the router
+const r = await runtime.run({ input: 'Explain this stack trace: …' });
+```
+
+### Modes
+
+Every run resolves to one of eight modes. **`auto`** (the default) detects intent; you can force any mode
+per run (`{ mode: 'plan' }`), in config (`runtime.defaultMode`), or via `AI_DEFAULT_MODE`. Precedence:
+per-run > config > env > detection — an explicit mode is never overridden.
+
+| Mode | What it does |
+|---|---|
+| `chat` | A single conversational answer (memory- and workspace-aware). |
+| `plan` | Produce a structured plan; execute nothing. |
+| `execute` | Run a planned sequence once. |
+| `orchestrate` | Plan → execute → observe → replan until done or a limit is hit. |
+| `agent` | A longer autonomous loop with hard stops (iterations, budget, permissions). |
+| `debug` | Evidence-first investigation (gather → hypotheses → validate → conclude). |
+| `compare` | Fan the same task across models and analyze the results. |
+
+Mode is *what kind of work*; **autonomy** is *how much independent action* — `chat`/`plan` need no approval,
+`execute`/`orchestrate` ask before acting, `agent` runs autonomously within limits.
+
+### Interactive terminal
+
+Bare `ai-runtime` opens a REPL: type natural language, or use slash commands to inspect and steer —
+`/mode`, `/status`, `/info`, `/providers`, `/models`, `/skills [discover]`, `/tools`, `/permissions`,
+`/memory`, `/conversations`, `/resume`, `/executions`, `/compare`, `/feedback`, `/learning`, `/doctor`,
+`/cleanup`, `/dry-run`. For CI, `ai-runtime run "<input>" [--mode m] [--dry-run]` is the one-shot equivalent.
+
+### Conversations & memory
+
+Conversations are saved verbatim (recoverable, with secrets scrubbed). Memory is durable, scoped facts —
+say "remember that we use Postgres" and it's kept, retrieved when relevant, and superseded when it changes.
+Turn persistence off entirely with `Runtime.load({ persistence: 'disabled' })` (for CI/ephemeral use).
+
+### Skills & tools (and your own)
+
+**Tools** are concrete operations — `filesystem`, `shell`, and `git` are built in; add your own. They're
+**deny-by-default**: reads are allowed and jailed to your workspace, but writes, shell, git commit/push,
+and network are off until you grant them in config.
+
+**Skills** are reusable capabilities that compose tools. Beyond the built-ins, the runtime **loads your
+own local skills**:
+
+- Drop a manifest (`*.skill.yaml`) or a JS module (`*.skill.mjs`) into **`.ai-runtime/skills/`** — auto-loaded.
+- `ai-runtime skills --discover` scans the rest of your repo and **reports** other skill files without
+  loading them (you enable one deliberately).
+- Install a **skill pack** (any npm package that exports `skills`) and name it under `skills.packages`.
+
+```yaml
+# .ai-runtime/skills/read-changelog.skill.yaml — a declarative skill (composes tools, no code)
+id: read-changelog
+version: 1.0.0
+name: Read changelog
+description: read CHANGELOG.md
+steps:
+  - tool: filesystem
+    input: { op: read, path: CHANGELOG.md }
+```
+
+### Planning, orchestration & dry-run
+
+For multi-step work, the runtime plans (using only your registered skills/tools), runs the plan as a DAG,
+succeeds a step only on evidence, and replans on failure. **Dry-run** (`run --dry-run`, `/dry-run`) shows
+the plan and what it *would* touch — with zero changes made.
+
+### Persistent executions & resume
+
+Longer runs are saved before they start and can be resumed. Resume never blindly continues: it re-checks
+your workspace (git state, touched files, config) and replans if anything drifted. `/executions`,
+`/resume-execution <id>`, `/pause`, `/cancel`.
+
+### Comparison
+
+`compare` mode (or `runtime.compare(...)`) runs the same task across models and shows where they agree,
+differ, and contradict each other. If you supply a way to *check* each answer (e.g. run the tests), the one
+that passes wins — evidence beats opinion.
+
+### Steering which models get used
+
+- **Exclude = a hard filter.** An excluded provider/model is **never** selected (it still shows in the
+  routing trace as `⊘ excluded by user configuration`).
+- **Prefer = a soft preference.** A preferred model is nudged up, but a preferred-but-incapable/unhealthy
+  one still loses.
+- **Neither configured = normal routing** across all eligible models.
+
+Set them in config `routing:`, per run (`runtime.run({ input, routing: {…} })`), or via environment
+variables — they combine, so an exclusion set anywhere always holds:
+
+```bash
+AI_EXCLUDE_PROVIDERS=ollama
+AI_EXCLUDE_MODELS=gemini:model-a,groq:model-b     # provider:model, or a bare model id
+AI_PREFER_PROVIDERS=gemini
+AI_PREFER_MODELS=groq:model-c
+```
+
+**Learning** — the runtime learns which providers/skills work from real outcomes and your `/feedback`, and
+turns that into *soft* preferences only. **Learning can never override an exclusion** (nor a privacy rule,
+a pin, a required capability, or the budget) — a guarantee proven by a dedicated test.
+
+---
+
+## Configuration
+
+Three places, and only these:
+
+| Path | What | In git? |
+|---|---|---|
+| `.ai-runtime/config.yaml` | Project config — runtime settings + providers (env-var **names** only). Falls back to root `ai-runtime.yaml`. | ✅ commit it |
+| `.env` | The secret **values** for the env vars your config names. | ❌ gitignored |
+| `~/.ai-runtime/` | Local state — conversations, memory, executions, cache, learning. Override with `AI_RUNTIME_HOME`. | ❌ never in git |
+
+A minimal config:
+
+```yaml
+# .ai-runtime/config.yaml
+runtime:
+  defaultMode: auto
+providers:
+  - id: gemini
+    kind: gemini
+    apiKeyEnv: GEMINI_API_KEY   # the NAME of the env var — never the value
+  - id: ollama                  # local, no key required
+    kind: ollama
+```
+
+**Provider API keys** go in `.env` — the config names the variable, the value lives here. Each provider
+kind has a default variable name (override with `apiKeyEnv`): `GEMINI_API_KEY`, `GROQ_API_KEY`,
+`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY` (Ollama needs none).
+
+**Optional runtime variables** — all optional; unset means the built-in default:
+
+| Variable | Effect |
+|---|---|
+| `AI_DEFAULT_MODE` | Default mode when a run doesn't set one (`auto` by default). |
+| `AI_DEFAULT_STRATEGY` | Default routing strategy. |
+| `AI_CONTEXT_MAX_TOKENS` | Token budget for the compiled model context. |
+| `AI_MAX_COST_USD` · `AI_MAX_CALLS` | Per-run spend / call guardrails. |
+| `AI_MEMORY_ENABLED` | Set `false` to disable memory. |
+| `AI_LEARNING_ENABLED` | Set `false` to disable outcome learning. |
+| `AI_EXCLUDE_PROVIDERS` · `AI_EXCLUDE_MODELS` | Hard-exclude providers / models (see [steering](#steering-which-models-get-used)). |
+| `AI_PREFER_PROVIDERS` · `AI_PREFER_MODELS` | Soft-prefer providers / models. |
+| `AI_CONVERSATION_RETENTION_DAYS` · `AI_EXECUTION_RETENTION_DAYS` · `AI_ARTIFACT_RETENTION_DAYS` | Retention for `cleanup` (unset = keep everything). |
+| `AI_RUNTIME_HOME` | Override the `~/.ai-runtime/` state directory. |
+| `AI_TELEMETRY_ENABLED` | *Reserved — not yet honored by the runtime.* Telemetry is metadata-only and set in config. |
+
+`ai-runtime setup` writes the config and `.env.example` for you (asking first), and `ai-runtime info` shows
+everything resolved. For the full router config (routing strategies, scoring weights, privacy posture,
+telemetry, self-declared providers), see [docs/router.md](docs/router.md).
+
+### Providers
+
+If no provider is configured, `ai-runtime setup` and `ai-runtime doctor` walk you through adding one.
+Recommended starters:
+
+| Provider | Type | Key | Where to get it |
+|---|---|---|---|
+| **Google Gemini** | Cloud API | `GEMINI_API_KEY` | https://aistudio.google.com/apikey |
+| **Groq** | Cloud API | `GROQ_API_KEY` | https://console.groq.com/keys |
+| **OpenRouter** | Cloud API (aggregator) | `OPENROUTER_API_KEY` | https://openrouter.ai/keys |
+| **Ollama** | Local (no key) | — | https://ollama.com |
+
+Cloud providers need an API key; **Ollama** runs models locally with no key. Availability, models, and any
+free/paid tiers are set by each provider — check their site for current terms.
+
+---
+
+## What you need to do
+
+A getting-started checklist:
+
+1. **Install** — Node 22+, then `npm install -g ai-runtime-engine` (or add it to a project). Verify with
+   `ai-runtime --help`.
+2. **Scaffold** — run `ai-runtime setup`. It creates `.ai-runtime/config.yaml`, `.env.example`, and
+   `.gitignore` entries (asking before each write).
+3. **Add a provider** — either put a real key in `.env` (e.g. `GEMINI_API_KEY=…`), or install
+   [Ollama](https://ollama.com) for a local model with no key.
+4. **Check it** — `ai-runtime doctor` confirms a provider is configured and reachable.
+5. **Use it** — `ai-runtime` (terminal), `ai-runtime run "…"` (one-shot), or `Runtime.load().run(…)` (code).
+6. **Go further (optional)** — add skills to `.ai-runtime/skills/`, grant write/shell permissions under
+   `permissions:` when you want the runtime to act, and set `routing:` to steer model selection.
+
+---
+
+## CLI commands
+
+The commands you'll use day to day:
+
+| Command | What it does |
+|---|---|
+| `ai-runtime` | Open the interactive terminal. |
+| `ai-runtime setup` | Detect the workspace and scaffold config (asks before writing). |
+| `ai-runtime run "<input>" [--mode m] [--dry-run] [--json]` | Run one request (one-shot, for scripts/CI). |
+| `ai-runtime info [--json]` | Read-only summary: workspace, providers, skills, tools, memory, storage. |
+| `ai-runtime doctor [--json]` | Diagnose config, `.env` (by name), providers, models, store, permissions, git. |
+| `ai-runtime skills [--discover]` | List available skills; `--discover` reports skill files elsewhere in the repo. |
+| `ai-runtime cleanup [--dry-run] [--yes]` | Enforce retention, drop the cache, validate the store. |
+| `ai-runtime executions` · `resume-execution <id>` | List and resume persisted executions. |
+
+The engine also ships lower-level commands (`route`, `providers`, `models`, `capabilities`, `probe`,
+`discover`, `benchmark`, `presets`, `telemetry`) — see [docs/router.md](docs/router.md). Run any command
+with `--help` for its flags.
+
+### Inside the interactive terminal
+
+Type a request in plain language, or use a slash command to inspect and steer. The commands that exist
+today:
+
+```
+/help                          show all commands
+/status  /info                 workspace, mode, provider count · full runtime summary
+/mode [name]                   show or set the mode (auto|chat|plan|…)
+/providers                     list providers + access state
+/providers/all models          list every provider's models
+/providers/<id> [models|capabilities|health]   inspect one provider
+/providers/setup               how to add a provider (keys / Ollama)
+/models                        list all known models
+/skills [discover]  /tools  /permissions
+/memory [list|search <q>|delete <id>|clear]
+/conversations  /resume <id>
+/executions  /resume-execution <id>  /pause <id>  /cancel <id>
+/compare <request>             compare across all providers
+/feedback <text>  /learning    record feedback · show what was learned
+/dry-run                       toggle dry-run (plan only, no changes)
+/doctor  /cleanup  /config     diagnostics · retention preview · resolved config
+/clear  /exit
+```
+
+---
+
+## Package & distribution
+
+| | |
+|---|---|
+| **Product** | AI Runtime |
+| **npm package** | `ai-runtime-engine` |
+| **CLI command** | `ai-runtime` |
+| **Source repository** | private |
+| **Project config** | `.ai-runtime/config.yaml` (committed) |
+| **Secrets** | `.env` (gitignored) |
+| **Runtime state** | `~/.ai-runtime/` (never committed) |
+
+The public npm package contains the **distributed runtime code** (compiled `dist/`), this README, and the
+changelog. It **does not** contain any of your data — no API keys, `.env`, memory, conversations, execution
+state, local indexes, cache, or other runtime state; those live only on your machine under `~/.ai-runtime/`
+and `.env`, and are never part of the package.
+
+The **source repository is private**; the npm package is public. Note that a public npm package still ships
+runnable code — publishing to npm distributes the compiled implementation to anyone who installs it. It
+does not hide the implementation from package consumers; keeping the *repository* private only keeps the
+source history and development materials private.
+
+---
+
+## Security & privacy
+
+- Everything the runtime reads through tools, files, the web, or MCP is treated as **data, never
+  instructions** — it can't change permissions, obtain secrets, run commands, or bypass approvals.
+- Filesystem access is **jailed to your workspace** (tested against `..`, absolute paths, and symlinks).
+  Shell is allowlist-first with a destructive-command denylist; writes, commit/push, and network are
+  each gated and off by default.
+- **Secrets are named by env var only** in config; an inline key is rejected at load, and every value is
+  redacted at every egress — including the terminal and logs.
+- **Privacy:** high-sensitivity input is kept off cloud providers unless you explicitly allow it.
+
+Full details in [docs/security.md](docs/security.md).
+
+---
+
+## Troubleshooting
+
+- **"No compatible AI provider is available"** — run `ai-runtime doctor`: it shows which provider keys are
+  set (by name), which providers authenticated, and how many models are usable. Add a key to `.env`, or a
+  provider to config; with none, `ai-runtime setup` lists free/local options (Ollama needs no key).
+- **A provider is never chosen** — check `doctor` for its health and `/providers` for its access state; a
+  provider you excluded shows as `⊘ excluded by user configuration` in the routing trace.
+- **Writes or shell are refused** — that's deny-by-default; grant them under `permissions:` in config
+  (destructive shell always asks). Use `--dry-run` to preview what a run would touch.
+- **A local skill isn't loading** — `ai-runtime skills --discover` shows what was found and any load errors;
+  module skills load only from `.ai-runtime/skills/` or a configured `skills.paths`.
+- **Nothing persists** — you may be in stateless mode (`persistence: 'disabled'`) or have `AI_*_ENABLED`
+  toggles off; `ai-runtime info` shows storage status.
+
+---
+
+## Further reading
+
+- **[docs/GUIDE.md](docs/GUIDE.md)** — a hands-on, study-friendly guide: install → first run → how it works
+  → worked examples, runnable offline.
+- **[docs/architecture.md](docs/architecture.md)** — how the two layers fit together, the one-router
+  invariant, and the lifecycle of a request.
+- **[docs/router.md](docs/router.md)** — the router engine reference: config keys, strategies, scoring,
+  providers, the `AI` API, and advanced features.
+- **[docs/security.md](docs/security.md)** — the full security model.
+- **[CHANGELOG.md](CHANGELOG.md)** — version history.
+
+---
+
+## Development
+
+TypeScript, ESM, Node ≥ 22. The test suite is fully offline and deterministic.
+
+```bash
+npm install
+npm run typecheck     # tsc --noEmit (strict)
+npm test              # node:test — offline, no keys, no network
+npm run build         # tsc → dist/ (ESM + .d.ts)
+npm run cli -- info   # run the CLI from source
+```
+
+CI (GitHub Actions) runs typecheck, tests, and build on Linux and Windows for every push and pull request.

package/dist/artifacts/artifacts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Artifact store — the content owner behind ArtifactRef. Large outputs (traces, diffs, logs, reports)
+ * are written here once and passed around the runtime as compact references; the context compiler
+ * decides if/when to inline the content. Backed by a store Area (checksummed, atomic). No-op when the
+ * store is disabled (stateless mode).
+ */
+import type { Clock } from '../util/clock.js';
+import type { Area } from '../store/area.js';
+import type { ArtifactRef } from '../runtime/types.js';
+export interface PutArtifactInput {
+    type: string;
+    source: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class ArtifactStore {
+    private readonly area;
+    private readonly clock;
+    private counter;
+    constructor(area: Area, clock?: Clock);
+    get enabled(): boolean;
+    /** Store content and return a reference. The content lives here; callers pass the ref around. */
+    put(input: PutArtifactInput): ArtifactRef;
+    /** Resolve a reference back to its content (undefined if missing/corrupt). */
+    resolve(ref: ArtifactRef): string | undefined;
+    list(): string[];
+    delete(id: string): void;
+}

package/dist/artifacts/artifacts.js

@@ -0,0 +1,46 @@
+/**
+ * Artifact store — the content owner behind ArtifactRef. Large outputs (traces, diffs, logs, reports)
+ * are written here once and passed around the runtime as compact references; the context compiler
+ * decides if/when to inline the content. Backed by a store Area (checksummed, atomic). No-op when the
+ * store is disabled (stateless mode).
+ */
+import { createHash } from 'node:crypto';
+import { systemClock } from '../util/clock.js';
+export class ArtifactStore {
+    area;
+    clock;
+    counter = 0;
+    constructor(area, clock = systemClock) {
+        this.area = area;
+        this.clock = clock;
+    }
+    get enabled() {
+        return this.area.enabled;
+    }
+    /** Store content and return a reference. The content lives here; callers pass the ref around. */
+    put(input) {
+        const id = `art_${this.clock.now().toString(36)}_${(this.counter += 1).toString(36)}`;
+        const checksum = createHash('sha256').update(input.content).digest('hex');
+        this.area.writeJson(id, { content: input.content, type: input.type, source: input.source, checksum, ...(input.metadata ? { metadata: input.metadata } : {}) });
+        return {
+            id,
+            type: input.type,
+            source: input.source,
+            contentRef: id,
+            checksum,
+            size: input.content.length,
+            ...(input.metadata ? { metadata: input.metadata } : {}),
+        };
+    }
+    /** Resolve a reference back to its content (undefined if missing/corrupt). */
+    resolve(ref) {
+        const rec = this.area.tryReadJson(ref.contentRef);
+        return rec?.content;
+    }
+    list() {
+        return this.area.listIds();
+    }
+    delete(id) {
+        this.area.remove(id);
+    }
+}