@abot-ai/runtime 1.0.0 → 1.2.0

package/docs/publishing.md

@@ -3,10 +3,12 @@
 This checklist covers the repo state expected before opening `abot` as a
 public Git repository or publishing a package artifact.
 
-The private development checkout is not a release source: its `package.json`
-sets `private: true`, so direct `npm publish` is blocked. Every public Git
-repository and npm release must be created from a freshly built and verified
-public snapshot. Never copy or publish the private checkout directly.
+The private development checkout is the canonical product source. Its
+`package.json` sets `private: true`, so direct `npm publish` is blocked. Every
+public Git and npm release must be created from a freshly built and verified
+public snapshot of one exact private commit. Never copy or publish the private
+checkout directly, and never develop or hotfix product changes in the public
+repository.
 
 ## 1. Public Metadata
 
@@ -78,11 +80,14 @@ Inside the verified public snapshot, run:
 ```bash
 npm run check:runtime-package
 npm run check:publication
+npm run check:public-snapshot
 ```
 
 `check:runtime-package` validates the packed artifact. `check:publication`
-validates public repo hygiene. For a public package, the packed-artifact check
-also rejects any plugin set other than the exact public allowlist.
+validates public repo hygiene. `check:public-snapshot` verifies every payload
+file against `PUBLIC-SNAPSHOT.json`; the public `npm run validate` chain runs
+all three checks. For a public package, the packed-artifact check also rejects
+any plugin set other than the exact public allowlist.
 
 ## 5. Examples And Docs
 
@@ -97,17 +102,19 @@ Keep these public onboarding files in sync:
 - `docs/known-limitations.md`
 - `docs/plugins.md`
 - `docs/troubleshooting.md`
+- `src/runtime/README.md`
 - `examples/minimal-runtime-composition.ts`
 - `examples/runtime.config.example.json`
+- `examples/request-runner.config.example.json`
 - `plugins/`
 
 Example config must stay sanitized and must not include host-specific URLs
 except local development defaults.
 
-## 6. Initial Public Repository Export
+## 6. Build A Fresh Snapshot For Every Release
 
-From a clean, fully tracked private checkout, build a new snapshot into an
-empty directory:
+Select one clean, synchronized, fully tracked private commit. Validate it, then
+build a new snapshot into a fresh empty directory:
 
 ```bash
 npm run validate
@@ -115,26 +122,46 @@ npm run build:public-snapshot -- --output /absolute/path/to/empty/public-snapsho
 ```
 
 `build:public-snapshot` is a private-source export command. It is intentionally
-absent from the exported public package and must not become part of the public
-repository's normal development workflow.
+absent from the exported public package. Run it again for every release; do not
+reuse or edit an older snapshot.
 
-Use the snapshot once to seed the public Git repository. The generated
-`PUBLIC-SNAPSHOT.json` records that export; ordinary public changes do not
-rewrite or verify its frozen file hashes.
+The generated `PUBLIC-SNAPSHOT.json` records the exact exported tree. Validate
+the snapshot itself before producing a package artifact:
 
-## 7. Public Repository Releases
+```bash
+cd /absolute/path/to/empty/public-snapshot
+npm ci --ignore-scripts
+npm run validate
+npm pack
+```
 
-After the initial export, maintain and release directly from the public Git
-repository:
+If validation finds a defect or an incomplete dependency closure, stop and fix
+it in the private canonical repository. Validate that change there and generate
+a completely new snapshot. Do not patch the generated snapshot in place.
+
+## 7. Validate And Promote The Frozen Artifacts
+
+Install the exact tarball from the verified snapshot into a fresh consumer
+project. Exercise the installed binary, not a source-tree fallback:
 
 ```bash
-npm ci
-npm run validate
-npm pack --dry-run
+npm install /absolute/path/to/abot-ai-runtime-<version>.tgz
+npx --no-install abot --help
 ```
 
-The public package explicitly sets `private: false`; the private development
-checkout explicitly sets `private: true`. Public `check:publication` validates
-the current repository rather than the initial export receipt. Tag or run
-`npm publish` only after current-tree validation and artifact review succeed on
-the real release machine.
+Also verify empty-config Web UI onboarding, non-destructive provider/profile
+addition, default-profile selection, and the packaged Web UI. For an upgrade,
+install the candidate tarball over a real prior-version consumer without
+rerunning init and confirm that its local config remains unchanged.
+
+The public repository is a generated distribution projection, not an
+independent maintenance branch. Promote only the contents of the verified
+snapshot. Any proposed public-repository fix must first return to the private
+canonical repository and pass the complete flow again.
+
+Publishing the frozen snapshot, running `npm publish`, pushing a public tag, and
+creating a GitHub Release are separate external mutations. Perform them only
+after explicit authorization names the exact private commit, snapshot tree,
+tarball, and version. Never overwrite a version already published to npm; a
+post-release defect ships from a new private commit under a new semantic
+version.

package/docs/runtime-invariant-coverage.md

@@ -4,23 +4,24 @@ 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`                                                        |
+| 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 v17 commit. Under `supervisor-worker-v1`, terminal Planner and Worker results receive a runtime-owned, constant-size `work_result_v1` receipt; supplied work receipts are rejected, lineage is derived and fingerprint-verified from that ledger, and `execution-agent-v1` receives none. Planner Graph and Auditor outputs remain passive terminal child results.                        | `src/runtime/orchestration/role-calls/`, `src/runtime/steps/planner-graph/`, `src/runtime/steps/auditor-decision/`                                                                                                                                     | `role-call-ledger.test.ts`, `role-call-work-result-receipt-reducer.test.ts`, `role-call-planner-work-result-receipt.test.ts`, `execution-agent-advisory-executors.test.ts`, `supervisor-request-runner.test.ts`                              |
+| Planner's semantic contract requires declaring every currently known execution outcome before the first child dispatch; schema and parser mechanically bind exactly one independently completable production item per Worker dispatch. A directly bound Worker receives that item, explicit dependencies, supervision evidence, and its own capability-result lane without the broader request, Planner objective, or sibling execution summaries.                          | `src/runtime/steps/planner-decision/`, `src/runtime/steps/worker-decision/`, `src/runtime/context/request-tool-results.ts`                                                                                                                             | `planner-plan-contract.test.ts`, `planner-single-item-dispatch.test.ts`, `planner-worker-context-isolation.test.ts`, `planner-worker-tool-result-scope.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; principal, controls, runtime-issued direct-Planner-item receipt, and admitted evidence are mechanically bounded before model invocation. Root and non-Planner Worker payloads retain the exact request source; a canonically bound Planner item omits it. Work-result receipts and derived lineage are stripped before Worker raw payload and result authoring while optional semantic checkpoints remain. | `src/runtime/orchestration/worker-capabilities/payload-author.ts`, `src/runtime/request/worker-capability-payload.ts`, `src/runtime/steps/worker-decision/`                                                                                            | `planner-worker-context-isolation.test.ts`, `registered-tool-worker-assignment-provenance.test.ts`, `worker-capability-payload-author.test.ts`, `worker-payload-dependency-projection-pr1.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`                                                                                                                                    |
+| Exhausted direct controls structured-output validation commits `reconsider_capability_selection` without executing an adapter. Its passive projection records the exact selection fingerprint but makes no semantic judgment, chooses no replacement, and suppresses no later 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; cross-call provenance moves only through compact runtime-owned receipts and ledger-derived lineage on explicit dependency or supervision lanes. A Planner-item Worker receives no sibling execution summaries; callers, siblings and unrelated requests receive no implicit evidence.                     | `src/runtime/orchestration/worker-capabilities/settled-results.ts`, `src/runtime/context/request-tool-results.ts`, `src/runtime/orchestration/role-calls/`, `src/runtime/steps/worker-decision/`, `src/runtime/steps/execution-agent/state-context.ts` | `planner-worker-tool-result-scope.test.ts`, `role-call-dependency-work-receipt-pr1.test.ts`, `role-call-work-receipt-continuation-pr1.test.ts`, `worker-decision.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
 

package/docs/runtime-library.md

@@ -167,6 +167,21 @@ 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.
+
+### Passive Long-Term Memory
+
+Long-term memory is a separate core service for relevant cross-session facts;
+it is not the current-session history checkpoint and does not depend on a
+plugin. It is disabled by default and receives a dedicated embedding profile.
+
+`createRuntimeApplication(config)` exposes management through
+`runtime.services.longTermMemory`; `createDefaultRuntimeDependencies(config)`
+exposes the same service as `runtime.longTermMemory`. Hosts may call
+`status()`, `list()`, `delete({ id })`, and `clear()` without accessing vector
+data.
+The normal request path alone owns passive retrieval and candidate persistence.
+
+See [Passive Long-Term Memory](long-term-memory.md) for setup and contracts.
 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
@@ -207,7 +222,7 @@ 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`,
+`capability.controls`, `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

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

@@ -7,25 +7,34 @@ 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`                                    |
+| Boundary                   | Instructions and schema                                                                                               | Executable validation                                                                                                                                                                                                                     | Primary coverage                                                                                                                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Supervisor decision        | `src/runtime/steps/supervisor-decision/`                                                                              | strict parser, default-policy child contracts, exact canonical root, and runtime-owned receipt plus verified lineage for returned Planner/Worker results                                                                                  | `supervisor-decision.test.ts`, `role-call-work-receipt-continuation-pr1.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, complete known plan declaration, one-Worker-item dispatch, and runtime-owned receipt plus verified lineage for the returned Worker                             | `planner-decision.test.ts`, `planner-plan-contract.test.ts`, `role-call-work-receipt-continuation-pr1.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, and compact receipts for explicit dependency results; a directly bound Planner item excludes the broader request, Planner objective, and sibling tool-result lane     | `worker-decision.test.ts`, `worker-capability-decision.test.ts`, `role-call-dependency-work-receipt-pr1.test.ts`, `planner-worker-context-isolation.test.ts`, `planner-worker-tool-result-scope.test.ts` |
+| Worker result              | `src/runtime/steps/worker-decision/result-author.ts`                                                                  | raw text from the exact projected Worker assignment and evidence; Planner-item results retain the same narrowed boundary                                                                                                                  | `worker-decision.test.ts`, `planner-worker-context-isolation.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, immutable controls and payload contract; only a runtime-issued direct-Planner-item receipt can omit source; work-result receipts and lineage are removed before raw authoring | `planner-worker-context-isolation.test.ts`, `worker-capability-payload-author.test.ts`, `worker-payload-dependency-projection-pr1.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.
 
+## Configured Root Response Methodology
+
+`supervisor.response` and `execution.response` share the configured
+`response-ux.md` and `memory-informed-response.md` references. The first is
+always-active editorial guidance. The second governs restrained use of the
+optional passive long-term-memory projection. Neither methodology changes the
+response schema, current user intent, evidence requirements, routing, action,
+or completion authority.
+
 ## Authority Rules
 
 - Every request has one canonical root. The frozen policy selects its
@@ -35,19 +44,30 @@ authority; prompt text never writes canonical state.
   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.
+- The delegated Planner coordinates a bounded sub-process. Before its first
+  child dispatch it declares every currently known execution outcome, then
+  binds exactly one independently completable production item whenever it
+  dispatches Worker. A later activation may select the next pending production
+  item after consuming the bound Worker result. Other registered child-role
+  contracts are unchanged. `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.
+- Under `supervisor-worker-v1`, the runtime alone issues `work_result_v1` for a
+  terminal Planner or Worker result. The exact caller may receive the compact
+  receipt and a fingerprint-verified lineage projection derived from the
+  canonical ledger. They establish provenance only; the active model still
+  owns the semantic next action and must not treat them as proof of correctness.
+  Model-supplied receipts are rejected and `execution-agent-v1` is unchanged.
 - 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.
+  direct controls refinement exhausts structured-output validation. It
+  executes nothing, makes no semantic judgment, 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.

package/docs/troubleshooting.md

@@ -62,6 +62,27 @@ Provider config should contain only the env var name:
 }
 ```
 
+## Long-Term Memory Cannot Be Enabled
+
+First confirm that the provider already exists in `models.providers` and that
+the embedding model is available from the same provider endpoint used by the
+Runtime. Then run:
+
+```bash
+npx abot memory status
+npx abot memory models --provider <provider-id>
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+The provider may report that model discovery is unsupported; this is expected
+for OpenAI and means the model id must be entered manually. Enablement writes no
+configuration unless the real embedding probe and full config validation pass.
+
+After enabling or disabling memory, restart ABot. If memory later becomes
+unavailable, inspect the Runtime trace for `runtime.long_term_memory` diagnostics.
+The normal final response should still complete because memory failures are
+isolated from response delivery.
+
 ## Runtime Connects But App Requests Do Not Arrive
 
 The runtime bridge client connects outbound to `agentBridgeUrl`. Make sure the

package/examples/models/default.config.json

@@ -11,6 +11,7 @@
   "calibration": {
     "supervisor.decision": { "format": "json" },
     "worker.decision": { "format": "json" },
+    "capability.controls": { "format": "json" },
     "planner.decision": { "format": "json" },
     "planner.graph": { "format": "json" },
     "reviewer.decision": { "format": "json" },

package/examples/request-runner.config.example.json

@@ -1,20 +1,12 @@
 {
+  "schemaVersion": 2,
   "models": {
     "defaults": {
       "profileId": "default",
       "steps": {
-        "supervisor.decision": "supervisor.decision",
         "supervisor.response": "default",
-        "worker.decision": "worker.decision",
         "worker.result": "default",
-        "planner.decision": "planner.decision",
-        "planner.graph": "planner.graph",
-        "reviewer.decision": "reviewer.decision",
-        "degraded.finalization": "degraded.finalization",
-        "execution.decision": "execution.decision",
         "execution.response": "default",
-        "auditor.decision": "auditor.decision",
-        "context.compact": "context.compact",
         "tool_payload.raw": "toolPayload.raw"
       }
     }
@@ -24,19 +16,21 @@
     "safetyReserveTokens": 1200,
     "attachmentReserveTokens": 1024
   },
+  "stepDefaults": {
+    "timeoutMs": 90000
+  },
   "steps": {
-    "supervisor.decision": { "timeoutMs": 90000 },
-    "supervisor.response": { "timeoutMs": 90000 },
-    "worker.decision": { "timeoutMs": 90000 },
-    "worker.result": { "timeoutMs": 90000 },
-    "planner.decision": { "timeoutMs": 90000 },
-    "planner.graph": { "timeoutMs": 90000 },
-    "reviewer.decision": { "timeoutMs": 90000 },
-    "degraded.finalization": { "timeoutMs": 90000 },
-    "execution.decision": { "timeoutMs": 90000 },
-    "execution.response": { "timeoutMs": 90000 },
-    "auditor.decision": { "timeoutMs": 90000 },
-    "context.compact": { "timeoutMs": 90000 },
-    "tool_payload.raw": { "timeoutMs": 90000 }
+    "supervisor.response": {
+      "instructionRefs": [
+        "../methodologies/response-ux.md",
+        "../methodologies/memory-informed-response.md"
+      ]
+    },
+    "execution.response": {
+      "instructionRefs": [
+        "../methodologies/response-ux.md",
+        "../methodologies/memory-informed-response.md"
+      ]
+    }
   }
 }

package/examples/runtime.config.example.json

@@ -57,6 +57,10 @@
       }
     }
   },
+  "longTermMemory": {
+    "enabled": false,
+    "emitClientEvents": false
+  },
   "requestRunner": {
     "configRef": "./request-runner.config.json"
   }

package/methodologies/memory-informed-response.md

@@ -0,0 +1,15 @@
+# Memory-Informed Root Response
+
+When `runtime_long_term_memory_reference_v1` is present, treat it as optional
+passive context. Use only entries that are genuinely relevant to the current
+request, and let them improve continuity, useful defaults, tone, or recognition
+of personal significance without making the response revolve around memory.
+
+Never force a memory reference, announce that information was stored, expose
+internal memory state, or attribute a statement to memory machinery. If the
+projected entries add no value, ignore them.
+
+The current message and relevant conversation override stale or conflicting
+memory. Memory is not user intent, an instruction, action authority, evidence,
+or proof of completion. This guidance affects response presentation only and
+does not change the candidate-authoring or storage contract.

package/methodologies/response-ux.md

@@ -0,0 +1,17 @@
+# Root Response Experience
+
+Fulfill the current user request first. Shape the response, level of detail,
+ordering, and tone around what is useful at this point in the conversation,
+rather than following a fixed response template.
+
+Write clearly, directly, and naturally. Do not treat the response as terminal
+by default. Look for a natural way to create conversational momentum: deepen
+the topic, surface a meaningful implication or connection, or ask one specific
+follow-up question grounded in what the user actually said. Avoid obligatory
+summaries, repeated conclusions, fixed closings, generic offers, canned
+questions, manufactured warmth, and artificial conversation extension.
+
+Use editorial judgment without changing the accepted request or inventing
+facts. Current user instructions and supplied evidence remain authoritative.
+This guidance affects presentation only; it grants no routing, action, or
+completion authority.

package/package.json

@@ -10,6 +10,7 @@
     "@types/ws": "^8.18.1",
     "@vscode/ripgrep": "1.18.0",
     "dotenv": "^17.4.1",
+    "htmlparser2": "10.0.0",
     "jszip": "^3.10.1",
     "pdf-parse": "2.4.5",
     "postcss": "^8.5.26",
@@ -18,9 +19,9 @@
   "description": "Open runtime for local AI agents.",
   "devDependencies": {
     "@types/node": "^25.5.2",
-    "esbuild": "^0.27.7",
+    "esbuild": "^0.28.2",
     "prettier": "^3.8.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.23.13",
     "typescript": "^6.0.2",
     "vitest": "^4.1.11"
   },
@@ -88,6 +89,7 @@
     "docs/configuration.md",
     "docs/installation.md",
     "docs/known-limitations.md",
+    "docs/long-term-memory.md",
     "docs/plugins.md",
     "docs/publishing.md",
     "docs/running-locally.md",
@@ -97,6 +99,8 @@
     "docs/runtime-public-contracts.md",
     "docs/tool-execution-result-evidence-contract.md",
     "docs/troubleshooting.md",
+    "methodologies/response-ux.md",
+    "methodologies/memory-informed-response.md",
     "examples/minimal-runtime-composition.ts",
     "examples/runtime-library-host.ts",
     "examples/runtime.config.example.json",
@@ -146,6 +150,7 @@
     "check:model-step-registry": "tsx scripts/write-model-step-registry.ts --check",
     "check:plugin-build": "npm run typecheck:plugins && tsx scripts/build-public-plugins.ts --check",
     "check:plugins": "tsx scripts/check-plugins.ts",
+    "check:public-snapshot": "tsx scripts/public-snapshot/check-public-snapshot.ts",
     "check:publication": "tsx scripts/check-publication-readiness.ts",
     "check:runtime-package": "tsx scripts/check-runtime-package-contents.ts",
     "clean-dist": "tsx scripts/clean-dist.ts",
@@ -154,16 +159,18 @@
     "dev": "tsx index.ts",
     "generate:model-step-registry": "tsx scripts/write-model-step-registry.ts",
     "init": "tsx scripts/init-runtime.ts",
+    "memory": "tsx scripts/configure-long-term-memory.ts",
     "model-gateway": "tsx src/model-gateway/server.ts",
     "smoke:packed-runtime-package": "tsx scripts/smoke-packed-runtime-package.ts",
     "smoke:runtime-package": "tsx scripts/smoke-runtime-package-import.ts",
     "test": "vitest",
+    "typecheck:all": "tsc -p tsconfig.json --noEmit",
     "typecheck:plugins": "tsc -p tsconfig.plugins.json",
-    "validate": "npm run check:plugin-build && npm test -- --run && npm run build && npm run check:plugins && npm run smoke:runtime-package && npm run check:runtime-package && npm run smoke:packed-runtime-package && npm run check:publication",
+    "validate": "npm run check:plugin-build && npm run typecheck:all && npm test -- --run && npm run build && npm run check:plugins && npm run smoke:runtime-package && npm run check:runtime-package && npm run smoke:packed-runtime-package && npm run check:publication && npm run check:public-snapshot",
     "web-ui": "tsx src/web-ui/server.ts",
     "web-ui:install-user-services": "tsx scripts/install-runtime-web-ui-user-services.ts"
   },
   "type": "module",
   "types": "./dist/src/runtime/index.d.ts",
-  "version": "1.0.0"
+  "version": "1.2.0"
 }