ai-runtime-engine 3.0.0 → 3.0.1

package/docs/architecture.md

@@ -27,6 +27,9 @@ its own.
 | Learning | What providers/skills/plans work better? | `src/learning/**` |
 | Comparison | How do candidates compare, by evidence? | `src/comparison/**` |
 | Executions | How does a long run persist and resume? | `src/executions/**` |
+| Capabilities | What can a task *do*; what does a goal require? | `src/capabilities/**` |
+| MCP | Which external servers add tools/context? | `src/mcp/**` |
+| Agents | What bounded sub-work can a step delegate? | `src/agents/**` |
 
 Conversation ≠ Memory ≠ Learning ≠ Repository ≠ Execution — separate stores, separate rules.
 
@@ -75,4 +78,5 @@ backward compatible and independently usable.
 Offline and deterministic: a `MockProvider` stands in for real adapters, and injected clocks make timing
 reproducible. Every phase kept the full suite green (typecheck + tests + build), added regression coverage
 for new behavior, and ran an adversarial security/logic review before merge. CI runs all three on every
-push and PR.
+push and PR, across a matrix of Node 22 and 24 on Linux and Windows, plus a tarball-contents audit and a
+test-count integrity check.

package/docs/router.md

@@ -1,6 +1,6 @@
 # Router engine reference
 
-The **router** is the engine beneath the [Runtime](../README.md#how-to-use-it): the vendor-agnostic
+The **router** is the engine beneath the [Runtime](../README.md#what-you-can-do): the vendor-agnostic
 `AI` class that turns a task into a routed, executed, validated result. Most users only touch it through
 the Runtime — but it is fully usable on its own (`import { AI } from 'ai-runtime-engine'`), and this document is
 its complete reference: configuration, the `run()` API, providers, tasks/capabilities, routing internals,

package/docs/security.md

@@ -8,9 +8,10 @@ first-class and tested. The runtime is always authoritative — nothing it *read
 
 Tool output, file contents, web pages, and MCP results enter the model context as tagged **data blocks**,
 never in instruction position. They cannot change permissions, obtain secrets, run commands, bypass
-approvals, or modify policy. Built-in skills fence file/web content with `wrapUntrusted`, and an injection
-heuristic flags likely prompt-injection. A request to "handle my list/emails/etc." authorizes *reading*
-the items, not executing whatever they contain.
+approvals, or modify policy. Built-in skills fence file/web content with `wrapUntrusted`, which neutralizes
+ANY fence marker inside the content (not just its own label), so nested or foreign-labeled fences cannot
+forge a boundary when several blocks share one prompt. An injection heuristic flags likely prompt-injection.
+A request to "handle my list/emails/etc." authorizes *reading* the items, not executing whatever they contain.
 
 ## Filesystem jail
 
@@ -24,15 +25,27 @@ from outside the workspace.
 ## Shell
 
 Allowlist-first: only commands in `permissions.shell.allowedCommands` run without approval; anything else
-requires approval. A destructive denylist (`rm -rf`, `git reset --hard`, force-push, …) requires approval
-**even when allowlisted**. Execution is confined to the working directory, with a filtered environment, a
-timeout, an `AbortSignal`, and process-tree cancellation.
+requires approval. Two denylists require approval **even when allowlisted**: destructive commands
+(`rm -rf`, `git reset --hard`, force-push, `sudo`, …) and **eval-capable** commands — interpreters run
+with inline-code/preload flags (`node -e`/`-r`, `python -c/-m`, `perl -M`, the `awk` family, …), package
+and script runners (`npx`, `npm exec`/`run`/`init`, `deno task`, …), container `run`/`exec`, argv-indirection
+wrappers (`env`, `xargs`, `nice`, `timeout`, `find -exec`, …), and non-default `make -f`. The allowlist
+matches an absolute path by basename but never a relative or workspace-internal path (realpath-checked),
+so a model cannot write an executable and run it under an allowlisted name.
+
+This backstop is **best-effort, not exhaustive**: a denylist over interpreters/wrappers cannot cover every
+one. Allowlisting an interpreter or a package manager INHERENTLY grants code execution — prefer allowlisting
+specific leaf tools. Known accepted residuals: running a *script file* via an interpreter (the same case as
+`node build.js`, deliberately allowed), dependency-install lifecycle scripts (they run by design), and a
+few obscure exec vectors (`sed`/`rename` `e`-flag, git aliases). Execution is confined to the working
+directory, with a filtered environment, a timeout, an `AbortSignal`, and process-tree cancellation.
 
 ## Permissions (deny-by-default)
 
 Reads are allowed (and jailed). Writes, shell, git commit/push, and network are **off** until granted in
 config under `permissions:`. `ExecutionPolicy` is the single authority; approvals persist across process
-exit and are surfaced on resume.
+exit and are surfaced on resume. Every file the runtime writes under `~/.ai-runtime/` is created
+owner-only (`0600` files, `0700` directories) on POSIX, so state is not world-readable on a shared host.
 
 ## Credentials
 
@@ -41,6 +54,12 @@ Secret values live in `.env` (gitignored). Every CLI/telemetry line passes throu
 redaction before egress — the terminal and CI logs are treated as egress sinks. Telemetry is metadata
 only and can never store prompts.
 
+Optional encryption at rest (`runtime.storage.encrypt`) uses AES-256-GCM with a **scrypt**-derived key
+(the `aienc2` envelope, per-record salt); legacy `aienc1` and plaintext records are read transparently and
+upgrade on rewrite. A decryption failure is reported honestly: an authentication failure means *wrong key
+OR tampering OR corruption*, not a certain wrong key, and it surfaces as an error rather than a silently
+empty store.
+
 ## Learning can never override a hard gate
 
 Learned outcomes and user preferences feed only **soft** scoring. A dedicated test proves that no

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-runtime-engine",
-  "version": "3.0.0",
-  "description": "AI Runtime \u2014 a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
+  "version": "3.0.1",
+  "description": "AI Runtime — a provider-agnostic AI runtime and orchestration platform. Point it at whatever AI providers you have; it routes each task to the best available model. Ships the `ai-runtime` CLI and the `Runtime`/`AI` library API.",
   "type": "module",
   "license": "ISC",
   "author": "pavan",
@@ -59,6 +59,8 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test --test-timeout=120000 \"tests/**/*.test.ts\"",
+    "test:ci": "node scripts/check-test-baseline.mjs",
+    "docs:check": "node scripts/check-doc-links.mjs",
     "test:unit": "node --import tsx --test --test-timeout=120000 \"tests/unit/**/*.test.ts\"",
     "test:integration": "node --import tsx --test --test-timeout=120000 \"tests/integration/**/*.test.ts\"",
     "test:contract": "node --import tsx --test --test-timeout=120000 \"tests/contract/**/*.test.ts\"",