@abot-ai/runtime 1.0.0

package/docs/running-locally.md

@@ -0,0 +1,184 @@
+# Running Locally
+
+`abot` is a runtime library plus local service entrypoints. A complete
+source-checkout setup usually has:
+
+- a model provider, such as Ollama or OpenAI
+- the model gateway process
+- the runtime bridge client process
+- optionally the local web UI proxy
+
+When `@abot-ai/runtime` is installed from npm, the packaged CLI starts the model
+gateway and Web UI together:
+
+```bash
+npx abot start
+```
+
+The remaining commands in this guide are the equivalent source-checkout
+workflow for contributors.
+
+## 1. Prepare Config
+
+```bash
+npm install
+npm run init -- --provider ollama --model <model-id>
+```
+
+The init command requires an explicit provider and concrete provider model id.
+It creates `.env`, `local/runtime.config.json`,
+`local/models/default.config.json`, and the local runtime directories. Make
+sure `.env` contains:
+
+```bash
+LLM_RUNTIME_CONFIG_FILE=local/runtime.config.json
+```
+
+## 2. Choose A Model Provider
+
+### Ollama
+
+ABot Runtime includes the Ollama adapter, but it does not install Ollama or
+download a model. Install Ollama from the
+[official download page](https://ollama.com/download), choose a concrete
+`<model-id>` from the [Ollama model library](https://ollama.com/library), and
+start the Ollama service using the instructions for your platform.
+
+Once the service is running, pull the chosen model and verify that the Ollama
+API lists it:
+
+```bash
+ollama pull <model-id>
+curl http://127.0.0.1:11434/api/tags
+```
+
+Use that same `<model-id>` in `local/models/default.config.json`. The generated
+provider config expects Ollama at:
+
+```text
+http://127.0.0.1:11434
+```
+
+`127.0.0.1` means the loopback network of the runtime process. It works only
+when Ollama is reachable in that same host/network namespace. In particular:
+
+- a runtime in WSL may need the Windows host address when Ollama runs on Windows
+- a runtime in a container needs an address for Ollama outside that container
+- a remote Ollama service needs its reachable host name or IP address
+
+In those layouts, pass the URL that the runtime can reach during
+initialization:
+
+```bash
+npm run init -- --provider ollama --model <model-id> --base-url http://<ollama-host>:11434
+```
+
+Docker Desktop can usually reach Ollama on its Windows or macOS host at
+`http://host.docker.internal:11434`. WSL, other container layouts, and remote
+hosts may use a different address. Run the `/api/tags` check against the chosen
+URL from the runtime environment. You can also edit
+`models.providers.ollama.baseUrl` in `local/runtime.config.json` later.
+
+### OpenAI
+
+Set the API key in `.env`:
+
+```bash
+OPENAI_API_KEY=...
+```
+
+Then configure an OpenAI provider/profile in `local/runtime.config.json`.
+For a new checkout,
+`npm run init -- --provider openai --model <model-id>` creates that
+provider/profile for you and selects the recommended
+`execution-agent-v1` policy in its model config.
+
+To add OpenAI to a runtime that already has another model, keep the existing
+configuration and create a distinct profile:
+
+```bash
+npm run add-model -- --profile <profile-id> --provider openai --model <model-id>
+```
+
+Use `--default` only when the new profile should become the default selection.
+It does not delete or replace any existing provider or profile. Restart the
+model gateway and Web UI after adding the model.
+
+## 3. Optional Workspace Providers
+
+`workspaceDir` is an optional host/library source path. The current
+Supervisor-led `RuntimeHost.start(...)` path does not inject a
+`WorkspaceProvider` or `ConversationContextProvider`.
+
+Hosts that consume those public ports directly may use
+`createSourceWorkspaceProvider(...)`, `createCompiledWorkspaceProvider(...)`,
+or the related multi-workspace factory. Capability skills are loaded only from
+the selected packages under `plugins/`.
+
+## 4. Start The Model Gateway
+
+```bash
+npm run model-gateway
+```
+
+By default it listens on:
+
+```text
+http://127.0.0.1:3000
+```
+
+Logs go under the resolved `sharedDir` at `logs/model-gateway.jsonl`, unless
+`MODEL_GATEWAY_TRACE_FILE` is set.
+
+## 5. Start The Runtime Bridge Client
+
+In another terminal:
+
+```bash
+npm run dev
+```
+
+This starts the runtime host from `index.ts` and connects to
+`agentBridgeUrl` from the active config.
+
+If you do not have a bridge server running, the process can start but cannot
+serve app requests. In that case, use the library APIs directly or run your
+own bridge host. See [bridge-compatibility.md](bridge-compatibility.md) for the
+runtime/bridge ownership split.
+
+## 6. Optional Web UI
+
+```bash
+npm run web-ui
+```
+
+The source-checkout web UI defaults to a direct local runtime backend. It
+serves the browser UI, accepts `/web-api` chat requests, and streams runtime
+events over `/web-realtime` without requiring an external bridge.
+
+The environment picker is loaded from `environment.profiles` in the active
+runtime config. Its initial selection is `environment.default`, or
+`LLM_RUNTIME_WEB_ENVIRONMENT` when you explicitly set a web UI default.
+
+Use bridge mode only when you intentionally want the web UI to talk through an
+external bridge:
+
+```bash
+LLM_RUNTIME_WEB_BACKEND=bridge npm run web-ui
+```
+
+The web UI transport is optional local tooling. It relays to runtime or bridge
+endpoints; it is not the source of truth for sessions, events, or final request
+state.
+
+## Runtime Output
+
+Generated state is ignored by git:
+
+- `.runtime/`
+- `dist/`
+- `logs/`
+- `sessions/`
+
+Delete generated state only when you intentionally want to reset local runtime
+history, logs, memory, configured work artifacts, or compiled context.

package/docs/runtime-invariant-coverage.md

@@ -0,0 +1,39 @@
+# Runtime Invariant Coverage
+
+This map records the invariants that protect the single request kernel across
+the default `supervisor-worker-v1` policy and the opt-in
+`execution-agent-v1` policy.
+
+| Invariant                                                                                                                                                                                                                                                                                                             | Owner                                                                                                                                                            | Primary coverage                                                                                                                |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Every request creates one canonical root and one RoleCall ledger; only that root may commit the final response.                                                                                                                                                                                                       | `src/runtime/request/handler.ts`, `src/runtime/request/runner.ts`, `src/runtime/request/root-execution-kernel.ts`, `src/runtime/orchestration/role-calls/`       | `root-execution-kernel-policy-mechanics.test.ts`, `role-call-ledger.test.ts`, `request-finalization.test.ts`                    |
+| The handler resolves one compiled execution policy from the selected model profile and supplies its same authority to capability composition and the runner. Omission remains `supervisor-worker-v1`.                                                                                                                 | `src/runtime/model/model-selection.ts`, `src/runtime/request/handler.ts`, `src/runtime/request/role-executor-composition.ts`                                     | `model-execution-policy.test.ts`, `request-execution-policy-composition.test.ts`                                                |
+| `supervisor-worker-v1` retains the delegated Supervisor, Planner, Worker, and Reviewer contracts; `execution-agent-v1` changes model-facing contracts and authority without adding another runner, ledger, reducer, capability engine, or finalizer.                                                                  | `src/runtime/request/root-execution-kernel.ts`, `src/runtime/request/role-executor-composition.ts`                                                               | `root-execution-kernel-policy-mechanics.test.ts`, `supervisor-request-runner.test.ts`, `execution-agent-request-runner.test.ts` |
+| Role choice is model-owned and limited to the exact subordinate contracts registered by the frozen policy.                                                                                                                                                                                                            | `src/runtime/steps/*`, `src/runtime/orchestration/role-executors/`, `src/runtime/orchestration/role-calls/`                                                      | `role-executor-registry.test.ts`, `planner-decision.test.ts`, `execution-agent-advisory-executors.test.ts`                      |
+| Every subordinate result returns to its exact caller through an exact-head ledger commit. Planner Graph and Auditor outputs are passive terminal child results, never executable plan or completion state.                                                                                                            | `src/runtime/orchestration/role-calls/`, `src/runtime/steps/planner-graph/`, `src/runtime/steps/auditor-decision/`                                               | `role-call-ledger.test.ts`, `execution-agent-advisory-executors.test.ts`, `supervisor-request-runner.test.ts`                   |
+| Capability authority is validated against the frozen policy and bound to the exact authorized call and activation: Worker for the default policy, canonical root for the direct policy. Both use the same binding and adapter engine.                                                                                 | `src/runtime/orchestration/role-calls/`, `src/runtime/orchestration/worker-capabilities/`, `src/runtime/request/root-execution-kernel.ts`                        | `root-execution-kernel-policy-mechanics.test.ts`, `worker-capability-binding.test.ts`, `execution-agent-request-runner.test.ts` |
+| Worker and root payloads use the same `tool_payload.raw` author; the principal, accepted intent, controls, exact request source, and admitted evidence are mechanically bounded before model invocation.                                                                                                              | `src/runtime/orchestration/worker-capabilities/payload-author.ts`, `src/runtime/request/worker-capability-payload.ts`                                            | `worker-capability-payload-author.test.ts`, `execution-agent-request-runner.test.ts`                                            |
+| Direct capability continuations use strict provider-native assistant tool calls followed by their exact linked tool results; linkage, order, names, content, and token accounting are validated.                                                                                                                      | `src/model-gateway/message-contract.ts`, `src/runtime/steps/execution-agent/state-context.ts`                                                                    | `tool-interaction.test.ts`, `tool-interaction-token-estimator.test.ts`, `execution-agent-context.test.ts`                       |
+| A declined direct refinement commits `reconsider_capability_selection`, records the exact selection fingerprint, advances the same root activation, and executes no adapter. Its passive projection chooses no replacement and suppresses no later model selection.                                                   | `src/runtime/orchestration/role-calls/`, `src/runtime/orchestration/role-calls/capability-selection-reconsideration.ts`, `src/runtime/steps/execution-agent/`    | `role-call-ledger.test.ts`, `execution-agent-context.test.ts`, `execution-agent-request-runner.test.ts`                         |
+| Delegated Worker control decisions remain strict JSON while its substantive result uses the existing raw authoring boundary. Only `execution-agent-v1` opts into byte-exact terminal text; default finalization remains normalized.                                                                                   | `src/runtime/steps/worker-decision/`, `src/runtime/steps/execution-agent/`, `src/runtime/lifecycle/request-finalizer.ts`                                         | `worker-decision.test.ts`, `execution-agent-request-runner.test.ts`, `request-finalization.test.ts`                             |
+| Capability adapters report bounded operation outcomes and never decide semantic completion.                                                                                                                                                                                                                           | `src/runtime/adapters/registered-tool-worker-capabilities.ts`, `src/capabilities/tool-executor.ts`                                                               | `registered-tool-worker-capabilities.test.ts`, `tool-executor.test.ts`, `normal-invocation.test.ts`                             |
+| Every capability settlement, whether produced by a delegated Worker or the direct root, atomically persists exactly one validated canonical `CapabilityAdapterResult`. Running executions cannot carry a result; invalid, non-JSON-safe, cyclic, or oversized evidence cannot settle and is never silently truncated. | `src/runtime/orchestration/capability-adapters/result.ts`, `src/runtime/orchestration/worker-capabilities/execution.ts`, `src/runtime/orchestration/role-calls/` | `registered-tool-worker-capabilities.test.ts`, `worker-capability-binding.test.ts`, `role-call-ledger.test.ts`                  |
+| The complete canonical result is projected only to the exact producing call and its later same-call payload author. Direct native tool linkage is not duplicated; callers, siblings, unrelated requests, and other roles retain bounded receipts and ordinary child handoffs.                                         | `src/runtime/orchestration/worker-capabilities/settled-results.ts`, `src/runtime/steps/worker-decision/`, `src/runtime/steps/execution-agent/state-context.ts`   | `worker-decision.test.ts`, `worker-capability-payload-author.test.ts`, `execution-agent-context.test.ts`                        |
+| Delegated Planner client events project committed canonical plan state and never write progress. Planner Graph advisories do not create canonical plan items.                                                                                                                                                         | `src/runtime/request/role-call-planner-events.ts`, `src/runtime/request/planner-plan-events.ts`, `src/runtime/steps/planner-graph/`                              | `role-call-planner-events.test.ts`, `execution-agent-advisory-executors.test.ts`                                                |
+| Final response persistence and terminal request completion remain one shared request-finalizer boundary for both policies.                                                                                                                                                                                            | `src/runtime/lifecycle/request-finalizer.ts`                                                                                                                     | `request-finalization.test.ts`, `execution-agent-request-runner.test.ts`                                                        |
+
+## Client Compatibility
+
+Delegated Planner events retain the existing `planner.plan.*` names and
+`stage=development_plan` payload field. This is a client presentation contract,
+not evidence of a separate request path or semantic routing state. A
+`planner.graph` advisory is only a returned role result and does not create
+those plan events.
+
+## Regression Rule
+
+Test behavior at the owning boundary. Do not encode one observed role or tool
+sequence as the general rule. A cross-cutting change must cover default direct
+response, delegation, Worker and root capability execution, advisory return,
+native continuation, client events, failure finalization, persisted output,
+and an unrelated-policy negative control as applicable.

package/docs/runtime-library.md

@@ -0,0 +1,289 @@
+# Runtime Library Usage
+
+`abot` exposes the runtime composition surface as a library. Consumers
+should import public runtime entrypoints only, not internal request execution,
+loop, profile, model, context, or tool modules.
+
+For the external plugin contract, see [plugins.md](plugins.md).
+For the stable runtime ports and event/session/tool semantics, see
+[runtime-public-contracts.md](runtime-public-contracts.md).
+For prompt/policy contract ownership, see
+[runtime-prompt-policy-contracts.md](runtime-prompt-policy-contracts.md).
+For invariant coverage, see
+[runtime-invariant-coverage.md](runtime-invariant-coverage.md).
+For bridge/runtime ownership, see [bridge-compatibility.md](bridge-compatibility.md).
+For current limitations, see [known-limitations.md](known-limitations.md).
+For package and publication gates, see [publishing.md](publishing.md).
+
+## Basic Composition
+
+For a minimal composition example, see
+[`examples/minimal-runtime-composition.ts`](../examples/minimal-runtime-composition.ts).
+
+```ts
+import {
+  createDefaultRuntimeDependencies,
+  loadRuntimeConfig,
+} from "@abot-ai/runtime/runtime";
+
+const config = loadRuntimeConfig({ rootDir: process.cwd() });
+const runtime = createDefaultRuntimeDependencies(config);
+
+const handle = runtime.host.start({
+  runtimeConfig: config,
+  runtimeId: config.runtimeId,
+  agentBridgeUrl: config.agentBridgeUrl,
+  agentBridgeToken: config.agentBridgeToken,
+  eventSinkFactory: runtime.events,
+  modelGatewayClient: runtime.models,
+  sessionStore: runtime.sessions,
+  attachmentStore: runtime.attachments,
+  toolRegistry: runtime.tools,
+});
+
+process.on("SIGINT", async () => {
+  await handle.stop();
+  process.exit(0);
+});
+```
+
+## Runtime Config
+
+The default host reads `runtime.config.json`, then lets environment variables
+override supported values. The public schema is available as
+`@abot-ai/runtime/runtime.config.schema.json`. The package ships
+`examples/runtime.config.example.json` as a sanitized starting point; it does
+not ship the repository-local `runtime.config.json`.
+
+```json
+{
+  "environment": {
+    "default": "prod",
+    "paths": {
+      "sharedDir": ".runtime/shared",
+      "compiledDir": ".runtime/compiled",
+      "workspaceDir": "workspace"
+    },
+    "profiles": {
+      "prod": {
+        "paths": {
+          "runtimeDir": ".runtime/prod",
+          "agentWorkDir": ".runtime/prod/agent-work",
+          "sessionsDir": ".runtime/prod/sessions",
+          "attachmentsDir": ".runtime/prod/attachments"
+        }
+      },
+      "dev": {
+        "paths": {
+          "runtimeDir": ".runtime/dev",
+          "agentWorkDir": ".runtime/dev/agent-work",
+          "sessionsDir": ".runtime/dev/sessions",
+          "attachmentsDir": ".runtime/dev/attachments"
+        }
+      }
+    }
+  },
+  "logging": {
+    "enabled": true,
+    "rotation": {
+      "maxFileSizeMb": 20,
+      "maxFiles": 10,
+      "maxAgeDays": 7
+    }
+  },
+  "plugins": {
+    "enabled": true,
+    "allow": ["*"],
+    "deny": []
+  },
+  "models": {
+    "providers": {
+      "ollama": {
+        "type": "ollama",
+        "baseUrl": "http://127.0.0.1:11434",
+        "keepAlive": "3m"
+      }
+    },
+    "profiles": {
+      "default": {
+        "configRef": "./models/default.config.json"
+      }
+    }
+  },
+  "requestRunner": {
+    "configRef": "./request-runner.config.json"
+  }
+}
+```
+
+`environment.paths.runtimeDir` is the generated/live runtime state root for one
+runtime environment. By default, sessions, plugin-owned state, and runtime
+logs live under that environment's `.runtime` subtree.
+`environment.paths.sharedDir` is generated/live state shared by multiple runtime
+environments, such as model-gateway logs. `environment.paths.compiledDir` is for
+optional generated context artifacts. `environment.paths.workspaceDir` is an
+optional workspace context source. `environment.paths.agentWorkDir` is the
+configured primary root for plugin-created and modified artifacts; `.` and
+relative paths resolve beneath it. `logging` controls the active JSONL trace at
+the resolved `traceFile`: `enabled` toggles writes,
+`rotation.maxFileSizeMb` rotates the active file by size, `rotation.maxFiles`
+limits retained rotated siblings, and `rotation.maxAgeDays` prunes rotated
+siblings by age. `runtime.logs.tail` continues to read only the active file.
+
+Every installed capability and its skill bindings are declared by one package
+under `plugins/`. The request-scoped Worker capability provider projects the
+selected manifest operations and guidance from that catalog. Its name is
+retained for compatibility; the same provider, binding, and payload author also
+serve a policy-authorized canonical root. Directly passing a custom
+`eventSinkFactory`, `modelGatewayClient`, `sessionStore`, `attachmentStore`, or
+`toolRegistry` into `RuntimeHost.start(...)` remains an adapter escape hatch,
+but bypasses the corresponding default config-driven composition.
+`plugins.enabled`, `plugins.allow`, and `plugins.deny` are the only root
+availability controls. Selectors may name `*`, a plugin, a capability, or
+`plugin.capability`; deny entries win. Concrete contracts, implementation
+defaults, secret declarations, and operation-level skill bindings live in the
+matching `plugins/<id>/plugin.json` package.
+When the active registry has no tools, no policy principal sees capability
+affordances. The selected root may still answer directly, and delegated roles
+may still return substantive results from supplied context or stable knowledge.
+The runtime never fabricates a role decision or final assistant response.
+
+`models.providers` declares provider adapter ids such as `ollama` and `openai`;
+model profiles reference configured providers by id. API keys stay out of JSON:
+OpenAI profiles use `apiKeyEnv`, usually `OPENAI_API_KEY`. `apiKeyEnv` is the
+environment variable name, never the key value itself. `models.profiles.*`
+can define provider model names, generation settings (`temperature`, `topP`,
+`reasoningEffort`), the required physical context capacity
+(`contextWindowTokens`), and context-projection settings
+(`formatTokenAccounting` and `tokenEstimation`). Omission uses safe `estimate`
+mode with zero fixed overhead; `none` disables format-token charges. Tool
+observation and artifact projection are owned by their runtime context
+contracts rather than model-profile calibration.
+The runtime uses context budgets when assembling request history, and the
+model-gateway maps provider generation settings to the provider payload.
+Current-session history is retained in the canonical transcript and projected
+to root decision/response steps as one passive semantic checkpoint plus recent
+complete turns. The runtime invokes the shared `context.compact` model step at
+the physical context threshold, persists the checkpoint with compare-and-swap,
+and keeps the latest ten complete turns raw. There is no profile-level message
+cap and no plugin or model-selected history checkout.
+For Ollama, `models.providers.<id>.keepAlive` owns model residency and a model
+profile may use `options.num_ctx` for a lower stable provider allocation. The
+gateway admits against the lower of that allocation and the declared
+`contextWindowTokens`, then projects the effective value as Ollama `num_ctx`.
+Calibration may tune context projection, but cannot change physical capacity
+or provider allocation.
+Additional provider protocols implement the public
+`@abot-ai/runtime/model-gateway` adapter contract and are injected into the
+gateway host. Adapter-owned, JSON-safe configuration belongs under the
+provider's `settings` object. The runtime and gateway core do not branch on a
+custom provider name, and an unregistered adapter id fails explicitly.
+Configured profiles are composed only from host configuration and any referenced
+profile file. The runtime does not inject model sampling settings; every such
+value comes from configuration.
+The main runtime `models` object is the installed-model catalog: providers and
+profiles. Large profile definitions can live in separate files through
+`models.profiles.<id>.configRef`, resolved relative to the runtime config file.
+This keeps provider/model catalog data separate from request execution policy.
+Each model profile may also select one registered model-facing execution
+contract:
+
+```json
+{
+  "execution": {
+    "policy": "execution-agent-v1"
+  }
+}
+```
+
+The field is optional. Omission resolves to the behavior-compatible
+`supervisor-worker-v1`; a configured profile may explicitly opt into
+`execution-agent-v1`. Selection is frozen once per request and changes only
+model-facing contracts and mechanical authority over the one shared kernel. It
+is not an ordered steps array, model-strength heuristic, second runner, or
+mid-request fallback. The loader keeps this orchestration metadata out of
+provider-profile and model-gateway payloads.
+
+Model profiles can expose independent calibration slots for
+`supervisor.decision`, `supervisor.response`, `planner.decision`,
+`planner.graph`, `worker.decision`, `worker.result`, `reviewer.decision`,
+`execution.decision`, `execution.response`, `auditor.decision`,
+`degraded.finalization`, and utility tool steps. `planner.decision` is the
+delegated Planner contract; `planner.graph` is the distinct passive advisory
+contract for `execution-agent-v1`. A raw step such as `worker.result` may also
+reuse an existing raw-response calibration slot. The request-runner
+`models.defaults.steps` map selects those semantic slot ids. The selected model
+remains the base, and the slot applies that model's generation, context, and
+optional format overlay.
+`reasoningEffort` accepts `none`, `minimal`, `low`, `medium`, `high`, and
+`xhigh`; the OpenAI adapter omits `temperature` and `topP` whenever a reasoning
+profile is invoked with active reasoning.
+Client `modelPreference` remains request-wide unless model policy explicitly
+overrides it. Runtime model selection resolves through the shared model policy;
+request-runner step mappings provide the configured model-step selection.
+The gateway logs the resolved profile/provider/model as
+`model.invocation.resolved`; use that event rather than the model's own answer
+when checking which model handled a request.
+
+`requestRunner.configRef` is required and resolves relative to the runtime
+config file. The referenced `request-runner.config.json` owns the request
+context budget plus every invoked model-step mapping and timeout. It does not
+select an execution policy, entry contract, role hierarchy, or fixed sequence.
+The selected model profile supplies `execution.policy`; the runtime then creates
+one canonical root and RoleCall ledger regardless of which root contract is
+active.
+
+Within the request-runner context budget, `outputReserveTokens` is input
+headroom: the runtime subtracts it before admitting prompt messages. It is not
+forwarded as a provider output-token cap. The selected profile's
+`contextWindowTokens` remains the physical capacity for every calibrated step.
+
+Root request, inactivity, model-step, and stream timeout defaults remain
+available under `timeouts`. Per-step `timeoutMs` values in the request-runner
+config bound the corresponding configured request-runner model calls.
+
+## Public Entry Points
+
+- `@abot-ai/runtime`
+- `@abot-ai/runtime/runtime`
+- `@abot-ai/runtime/runtime/config`
+- `@abot-ai/runtime/runtime/composition`
+- `@abot-ai/runtime/runtime/default-adapters`
+- `@abot-ai/runtime/runtime/adapters`
+- `@abot-ai/runtime/runtime/ports`
+- `@abot-ai/runtime/plugin-sdk`
+- `@abot-ai/runtime/model-gateway`
+- `@abot-ai/runtime/runtime.config.schema.json`
+
+## Adapter Boundary
+
+Use `@abot-ai/runtime/runtime/adapters` when you want the built-in file-backed
+implementations:
+
+```ts
+import {
+  createCompiledWorkspaceProvider,
+  createFileSessionStore,
+  createInMemorySessionStore,
+  createMultiWorkspaceProvider,
+  createSourceWorkspaceProvider,
+} from "@abot-ai/runtime/runtime/adapters";
+```
+
+Use `@abot-ai/runtime/runtime/ports` for TypeScript types when providing custom
+implementations from another host.
+
+`createDefaultRuntimeDependencies(config)` exposes attachment persistence as
+`runtime.attachments`; pass it to `RuntimeHost.start(...)` as
+`attachmentStore`. Hosts that need a custom file-backed attachment store can
+use `createFileAttachmentStore(...)` from `@abot-ai/runtime/runtime`, while
+`createDefaultAttachmentStore(config)` is available from
+`@abot-ai/runtime/runtime/default-adapters`.
+
+`createInMemorySessionStore(...)` is useful for embedded hosts, tests, and
+short-lived runtimes that do not want file persistence.
+
+`createSourceWorkspaceProvider(...)` reads workspace markdown directly.
+`createMultiWorkspaceProvider(...)` can route multiple workspace providers
+through one `WorkspaceProvider` port. Capability skill mappings and Markdown
+come only from the selected packages under `plugins/`.

package/docs/runtime-prompt-policy-contracts.md

@@ -0,0 +1,70 @@
+# Runtime Model and Policy Contracts
+
+Model instructions are runtime behavior whenever output is parsed into a strict
+decision. The runtime has one canonical root kernel and RoleCall ledger. A
+request-frozen execution policy selects the model-facing root and subordinate
+contracts without selecting a fixed workflow.
+
+## Structured Model Boundaries
+
+| Boundary                   | Instructions and schema                                                                                               | Executable validation                                                                                                                       | Primary coverage                                                                                   |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Supervisor decision        | `src/runtime/steps/supervisor-decision/`                                                                              | strict parser, default-policy child contracts, exact canonical root                                                                         | `supervisor-decision.test.ts`, `supervisor-request-runner.test.ts`                                 |
+| Supervisor response        | `src/runtime/steps/supervisor-response/`                                                                              | exact active root and bounded returned-child context; legacy normalized terminal mode                                                       | `supervisor-response.test.ts`, `supervisor-request-runner.test.ts`, `request-finalization.test.ts` |
+| Execution Agent decision   | `src/runtime/steps/execution-agent/`                                                                                  | strict parser, direct-policy actions and root capability authority, exact canonical state                                                   | `execution-agent-decision.test.ts`, `execution-agent-request-runner.test.ts`                       |
+| Execution Agent response   | `src/runtime/steps/execution-agent/response-*`                                                                        | raw non-empty bounded text from the exact accepted response state; direct-policy exact terminal mode only                                   | `execution-agent-request-runner.test.ts`, `request-finalization.test.ts`                           |
+| Delegated Planner decision | `src/runtime/steps/planner-decision/`                                                                                 | strict parser, exact Planner caller, registered delegated child contracts                                                                   | `planner-decision.test.ts`, `role-call-planner-events.test.ts`                                     |
+| Planner Graph advisory     | `src/runtime/steps/planner-graph/`                                                                                    | bounded acyclic proposal or decline from the exact advisory objective; no execution authority                                               | `execution-agent-advisory-executors.test.ts`, `execution-agent-request-runner.test.ts`             |
+| Worker decision            | `src/runtime/steps/worker-decision/`                                                                                  | strict parser, exact Worker activation, offered capability catalog                                                                          | `worker-decision.test.ts`, `worker-capability-decision.test.ts`                                    |
+| Worker result              | `src/runtime/steps/worker-decision/result-author.ts`                                                                  | raw text from the exact projected Worker assignment and evidence                                                                            | `worker-decision.test.ts`, `supervisor-request-runner.test.ts`                                     |
+| Reviewer decision          | `src/runtime/steps/reviewer-decision/`                                                                                | strict parser and bounded supplied-work projection                                                                                          | `reviewer-decision.test.ts`, `supervisor-request-runner.test.ts`                                   |
+| Auditor advisory           | `src/runtime/steps/auditor-decision/`                                                                                 | typed criteria, whole canonical evidence entries, and omission-gated pass                                                                   | `execution-agent-advisory-executors.test.ts`, `execution-agent-request-runner.test.ts`             |
+| Capability payload         | `src/runtime/orchestration/worker-capabilities/payload-author.ts`, `src/runtime/request/worker-capability-payload.ts` | frozen-policy Worker or root principal, selected operation, accepted intent, immutable controls, exact request source, and payload contract | `worker-capability-payload-author.test.ts`, `execution-agent-request-runner.test.ts`               |
+| Degraded finalization      | `src/runtime/steps/degraded-finalization/`                                                                            | bounded failure rendering only                                                                                                              | `degraded-finalization.test.ts`, `request-finalization.test.ts`                                    |
+
+Instructions explain semantic choices. Parsers validate exact output shapes.
+The RoleCall ledger and shared capability binding remain the executable
+authority; prompt text never writes canonical state.
+
+## Authority Rules
+
+- Every request has one canonical root. The frozen policy selects its
+  Supervisor or Execution Agent model-facing contract; only that root can
+  return the final user-facing response.
+- Omission selects `supervisor-worker-v1` and preserves the delegated MAIN
+  contract. A configured profile may explicitly select `execution-agent-v1`;
+  there is no prompt-based selection or mid-request fallback.
+- An active role model alone chooses its next semantic action.
+- The delegated Planner coordinates a bounded sub-process. `planner.graph` is
+  a distinct direct-policy advisory that only proposes or declines a bounded
+  graph; neither gains root response authority.
+- Worker owns capability selection under `supervisor-worker-v1`; the canonical
+  root owns it under `execution-agent-v1`. Both use the same binding, payload
+  author, adapter execution, and settlement mechanics.
+- Reviewer returns advisory findings to its exact caller. Runtime code does not
+  automatically remediate or finalize from a verdict.
+- Auditor returns a passive verdict over explicitly supplied criteria and whole
+  evidence entries. Missing or omitted evidence cannot produce pass.
+- `reconsider_capability_selection` is a canonical mechanical transition after
+  direct refinement declines a selection. It executes nothing, chooses no
+  replacement, and cannot be treated as tool evidence or completion.
+- A child result returns only to its exact caller frame.
+- Runtime code must not infer role choice from prompt words, paths, tool names,
+  task categories, or model prose.
+
+## Editing Rule
+
+When changing a model or policy boundary, update its owner and matching
+coverage:
+
+- decision shape: prompt, format, parser, and role test;
+- execution-policy authority: code-owned policy composition, RoleCall reducer,
+  and cross-policy negative controls;
+- call legality: role-call reducer/registry and ledger tests;
+- capability contract: shared capability binding/payload author or concrete
+  adapter tests;
+- client presentation: post-commit event projector and event-contract tests;
+- final persistence: request finalizer and session/request tests.
+
+Keep production guidance generic. Concrete tool behavior belongs to the tool or
+plugin, and client presentation must never become orchestration state.