@abot-ai/runtime 1.0.0 → 1.2.0

package/docs/configuration.md

@@ -31,11 +31,16 @@ AGENT_BRIDGE_TOKEN=
 LLM_RUNTIME_CONFIG_FILE=local/runtime.config.json
 ```
 
-`BRAVE_SEARCH_API_KEY` is optional for startup and URL fetching. The bundled
-Web plugin always exposes `web_fetch` and `web_search`; invoking `web_search`
-without a non-empty key returns a clear plugin configuration error without
-making a search request. The key never belongs in runtime JSON or a plugin
-manifest.
+`BRAVE_SEARCH_API_KEY` is optional. The bundled Web plugin always exposes
+`web_fetch` and `web_search`. A non-empty key selects Brave Search; without one,
+`web_search` uses Light search over a limited catalog of public Hebrew and
+English sources. Light reads those sources directly without an external search
+engine. A failing configured key does not silently switch providers. The key
+never belongs in runtime JSON or a plugin manifest.
+
+Light uses the Web plugin's defaults and an in-memory cache; no background
+crawler or separate service is installed. See
+[Known Limitations](known-limitations.md#web-search) for its coverage and limits.
 
 Provider configs should reference env var names:
 
@@ -85,6 +90,57 @@ and write it automatically to the generated model config:
 Use the same block when configuring an OpenAI model profile manually. Other
 providers are not implicitly assigned this policy by the initializer.
 
+## Passive Long-Term Memory
+
+Passive cross-session memory is opt-in. The default is equivalent to:
+
+```json
+{
+  "longTermMemory": {
+    "enabled": false,
+    "emitClientEvents": false
+  }
+}
+```
+
+Enable it through the shared Web UI or CLI onboarding flow whenever possible:
+
+```bash
+npm run memory -- enable --provider <provider-id> --model <embedding-model-id>
+```
+
+The flow creates a dedicated `models.embeddingProfiles` entry, performs a real
+embedding probe, validates the full config, and then atomically enables
+`longTermMemory`. A manual equivalent is:
+
+```json
+{
+  "models": {
+    "embeddingProfiles": {
+      "memory-embedding": {
+        "provider": "ollama",
+        "model": "<embedding-model-id>"
+      }
+    }
+  },
+  "longTermMemory": {
+    "enabled": true,
+    "emitClientEvents": false,
+    "embeddingProfileId": "memory-embedding"
+  }
+}
+```
+
+The referenced provider must already exist under `models.providers`. Embedding
+profiles accept `provider`, `model`, optional `label`, and optional JSON-safe
+`options`. Generation, reasoning, context-window, and output-budget fields are
+rejected because embedding and response-generation profiles have different
+contracts.
+
+`emitClientEvents` exposes bounded lifecycle status and counts, never memory
+content or vectors. See [Passive Long-Term Memory](long-term-memory.md) for
+storage, privacy, retrieval, and management behavior.
+
 ## Paths
 
 `environment.paths.runtimeDir` is environment-local generated runtime state.
@@ -180,27 +236,20 @@ request-runner config:
 ```
 
 `requestRunner.configRef` is resolved relative to the runtime config file, not
-the process working directory. The referenced file owns the complete set of
-runtime model-step mappings and timeouts plus the request context budget:
+the process working directory. The referenced file owns model-step routing
+overrides, timeout defaults and overrides, and the request context budget.
+Fresh configurations use request-runner schema version 2:
 
 ```json
 {
+  "schemaVersion": 2,
   "models": {
     "defaults": {
       "profileId": "default",
       "steps": {
-        "supervisor.decision": "supervisor.decision",
-        "supervisor.response": "supervisor.response",
-        "planner.decision": "planner.decision",
-        "planner.graph": "planner.graph",
-        "worker.decision": "worker.decision",
-        "worker.result": "supervisor.response",
-        "reviewer.decision": "reviewer.decision",
-        "degraded.finalization": "degraded.finalization",
-        "execution.decision": "execution.decision",
-        "execution.response": "execution.response",
-        "auditor.decision": "auditor.decision",
-        "context.compact": "context.compact",
+        "supervisor.response": "default",
+        "worker.result": "default",
+        "execution.response": "default",
         "tool_payload.raw": "toolPayload.raw"
       }
     }
@@ -210,24 +259,54 @@ runtime model-step mappings and timeouts plus the request context budget:
     "safetyReserveTokens": 1200,
     "attachmentReserveTokens": 1024
   },
+  "stepDefaults": {
+    "timeoutMs": 90000
+  },
   "steps": {
-    "supervisor.decision": { "timeoutMs": 90000 },
-    "supervisor.response": { "timeoutMs": 90000 },
-    "planner.decision": { "timeoutMs": 90000 },
-    "planner.graph": { "timeoutMs": 90000 },
-    "worker.decision": { "timeoutMs": 90000 },
-    "worker.result": { "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"
+      ]
+    }
   }
 }
 ```
 
+In schema version 2, `models.defaults.steps` is a sparse override map. A
+missing model-step mapping resolves to the same id as the step, so an identity
+entry such as `"capability.controls": "capability.controls"` is unnecessary.
+The four entries above are the canonical non-identity overrides: three raw
+response steps use the base `default` profile, while `tool_payload.raw` uses
+the existing `toolPayload.raw` calibration slot. An explicit target may still
+select a model profile, invocation profile, or calibration slot; an unknown
+explicit target is rejected rather than replaced with a default.
+
+`stepDefaults.timeoutMs` supplies the timeout for every step. The root `steps`
+object is also sparse: add `timeoutMs` only when a step differs from the
+default, and add `instructionRefs` only when that step needs additional
+instructions. A missing step entry therefore uses the default timeout and has
+no additional instruction references.
+
+A request-runner config with no `schemaVersion` is the legacy v1 format
+published with ABot 1.0.0. It remains supported and is normalized in memory;
+the loader does not rewrite it, and adding a runtime model step does not require
+the user to add a new identity mapping. `schemaVersion: 2` is the only explicit
+supported version. Any other explicit value is rejected before the config is
+used or written.
+
+A fresh `abot init` creates schema version 2. Running init against an existing
+project without `--force` preserves its request-runner config byte for byte,
+including a legacy v1 file. Package upgrades never run a config migration or
+rewrite automatically; `--force` remains an explicit request to replace the
+local starter files.
+
 Every materialized model profile declares its physical context capacity with
 top-level `contextWindowTokens`. The selected profile supplies that capacity;
 the request-runner context block supplies only admission headroom.
@@ -236,21 +315,30 @@ the request-runner context block supplies only admission headroom.
 subtracted while projecting messages so the prompt does not consume the whole
 context window; it is never forwarded to a provider as an output limit. Model
 steps may vary their prompt contract, timeout, format, or other generation
-controls, but they do not receive a shared per-step output-token cap.
+controls, but configuration does not define a shared per-step output-token cap.
 The Ollama adapter still sends a finite provider-native `num_predict`, derived
-mechanically from the final provider input, the physical context remainder,
-and a strict bounded output schema when one applies.
-
-All three root fields and every invoked step are required. Unknown fields,
-missing steps, and extra step ids are rejected during configuration loading.
-`worker.result` is a raw-text authoring step. It may reuse a model profile's
-existing raw-response calibration slot, as shown above, without changing its
-distinct runtime identity.
+mechanically from the final provider input and the physical context remainder.
+Registered core-decision steps additionally retain their internal output-token
+limit. Output schema size does not impose another generation limit; schema
+projection, validation, input estimation, and compaction remain unchanged.
+
+The required context fields remain explicit. Unknown fields, unknown step ids,
+and invalid explicit overrides are rejected during configuration loading;
+omitting a mapping or step entry uses the schema version 2 defaults described
+above. `instructionRefs` are resolved relative to the request-runner config.
+The `abot init` command installs the two default root-response methodologies
+beside the local configuration, and the same references are applied to
+`supervisor.response` and `execution.response`. They are presentation guidance
+only and cannot alter the available actions, output contract, or runtime
+authority.
+`worker.result` is a raw-text authoring step. The canonical override selects the
+base `default` profile without changing the step's distinct runtime identity;
+an installation may still configure a more specific explicit target.
 `planner.decision` remains the delegated MAIN Planner contract and keeps its
 configured methodology references. `planner.graph` is the separate structured
 graph proposal/decline contract used by the Execution Agent advisory Planner;
-it has its own mapping, timeout, output contract, and model calibration and does
-not inherit `planner.decision` instruction references.
+it receives its own normalized mapping, timeout, output contract, and model
+calibration and does not inherit `planner.decision` instruction references.
 The request runner has no configurable role hierarchy or fixed sequence. A
 model profile may select one code-owned execution policy; omission uses the
 current Supervisor/Worker behavior:
@@ -374,15 +462,15 @@ loss before a checkpoint covers those turns.
 supported. Tool observations and artifact context are projected by their
 owning runtime contracts; model profiles cannot override those boundaries.
 
-The request-runner config maps internal `modelStep` ids to semantic calibration
-slot ids:
+The request-runner config maps internal `modelStep` ids only when a target
+differs from the schema version 2 identity default:
 
 ```json
 {
   "models": {
     "defaults": {
       "steps": {
-        "supervisor.decision": "supervisor.decision"
+        "tool_payload.raw": "toolPayload.raw"
       }
     }
   }
@@ -428,12 +516,13 @@ Use this bounded workflow:
 
 The common slots and their first tuning targets are:
 
-| Step family                     | Slots                                                                                                                                                                 | Tune first                                                                                                                                                                 |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Step family                     | Slots                                                                                                                                                                 | Tune first                                                                                                                                                                              |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Routing and decisions           | `supervisor.decision`, `worker.decision`, `planner.decision`, `planner.graph`, `reviewer.decision`, `execution.decision`, `auditor.decision`, `degraded.finalization` | Keep the required structured `format`, then verify complete structured output and deterministic sampling. Add short model-specific instructions only when measured behavior needs them. |
-| User-facing or delegated output | `supervisor.response`, `worker.result`, `execution.response`                                                                                                          | Sampling and any intentional provider-native output controls. Do not force JSON unless that step's contract requires it.                                                    |
-| Context compaction              | `context.compact`                                                                                                                                                     | Structured format and preservation of facts that later steps still require; physical capacity remains profile-owned.                                                       |
-| Literal tool payloads           | `toolPayload.raw`                                                                                                                                                     | Literal-payload instructions and any intentional provider-native output controls. Verify the produced payload or artifact directly, not the model's description of it.     |
+| Capability control authoring    | `capability.controls`                                                                                                                                                 | Preserve the structured controls contract without applying the short decision-output ceiling.                                                                                           |
+| User-facing or delegated output | `supervisor.response`, `worker.result`, `execution.response`                                                                                                          | Sampling and any intentional provider-native output controls. Do not force JSON unless that step's contract requires it.                                                                |
+| Context compaction              | `context.compact`                                                                                                                                                     | Structured format and preservation of facts that later steps still require; physical capacity remains profile-owned.                                                                    |
+| Literal tool payloads           | `toolPayload.raw`                                                                                                                                                     | Literal-payload instructions and any intentional provider-native output controls. Verify the produced payload or artifact directly, not the model's description of it.                  |
 
 `timeoutMs` addresses provider latency only; raising it does not improve model
 reasoning. Top-level `contextWindowTokens` declares the concrete model
@@ -443,9 +532,10 @@ but a provider may intentionally omit unsupported sampling fields, such as
 temperature for an enabled OpenAI reasoning mode.
 
 An omitted slot inherits the model profile's base generation and context. The
-packaged request-runner example already maps each semantic step to its matching
-calibration slot, so most users only need to edit the profile file for the
-model they are tuning.
+packaged schema version 2 request-runner example lists only the four canonical
+non-identity overrides; all other steps resolve to their matching calibration
+slot automatically. Most users therefore only need to edit the profile file
+for the model they are tuning.
 
 ## Schema
 

package/docs/installation.md

@@ -91,6 +91,24 @@ npx abot add-model --profile <profile-id> --provider openai --model <model-id>
 Add `--default` only to select that profile as the default. It does not delete
 the profiles that are already configured.
 
+### Optional Passive Long-Term Memory
+
+Long-term memory is disabled by default. After a provider is configured, choose
+an embedding model and enable it through the Web UI Config workspace or CLI:
+
+```bash
+npx abot memory status
+npx abot memory models --provider <provider-id>
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+ABot does not install or choose the embedding model. The enable command performs
+a real probe, writes config only after it succeeds, and reports that the Runtime
+must be restarted. OpenAI users enter the embedding model id manually; Ollama
+users can discover model ids installed at the configured Ollama endpoint.
+
+See [Passive Long-Term Memory](long-term-memory.md) before enabling persistence.
+
 ## Use As A Library
 
 After the package is published:
@@ -134,10 +152,16 @@ The package includes the public plugin catalog. Additional consumer plugins may
 be installed under `<consumer-root>/plugins`. A consumer plugin cannot replace
 a bundled plugin: duplicate plugin ids fail closed.
 
-Web URL fetching is available through the bundled Web plugin without a search
-credential. Set `BRAVE_SEARCH_API_KEY` to make `web_search` operational. With
-no key, `web_fetch` remains operational and a `web_search` invocation fails
-locally with a configuration error before any search request is made.
+The passive long-term memory service belongs to the Runtime core and does not
+depend on the bundled `memory` plugin.
+
+The bundled Web plugin supports URL fetching and Light search without a search
+credential. Light searches a limited catalog of public Hebrew and English
+sources directly; it does not query an external search engine or provide
+whole-web coverage. Set `BRAVE_SEARCH_API_KEY` to use Brave Search instead.
+A configured Brave key that fails remains a Brave error. See
+[Known Limitations](known-limitations.md#web-search) for Light's discovery and
+cache boundaries.
 
 ## Run From Source
 

package/docs/known-limitations.md

@@ -61,6 +61,38 @@ plugin entrypoints are not currently supported.
 Plugin behavior belongs inside the plugin. Runtime orchestration should only
 see the generic selected catalog and execution results.
 
+## Web Search
+
+With a configured `BRAVE_SEARCH_API_KEY`, `web_search` uses Brave Search and
+preserves its authentication and rate-limit errors. Without a key, Light search
+discovers and ranks pages within a catalog of public Hebrew and English
+sources. It contacts content sources directly, without another search engine.
+
+Light does not maintain a whole-web index. Its source selection, crawl depth,
+candidate count, response sizes, and request deadline are bounded. Results may
+be partial because a source is unavailable, disallows crawling, or exceeds a
+budget. Zero matches mean no matches in the inspected sources, not that the
+information is absent from the web. Source coverage accompanies the results.
+
+The document cache exists only in the plugin instance's memory, bounded to
+16 MiB of serialized content and 500 documents. Feed entries expire within
+five minutes and page entries within 30 minutes; origin directives can shorten
+these lifetimes. Restarting the runtime clears the cache. There is no background
+crawl, browser rendering, or persistent search database. Content that requires
+JavaScript may therefore be unavailable. Exact public URL fetching remains a
+separate `web_fetch` capability with its existing public-network restrictions.
+
+## Passive Long-Term Memory
+
+Passive long-term memory is disabled by default and requires an embedding model
+selected and operated by the consumer. ABot provides OpenAI and Ollama adapter
+contracts, but it does not install, download, or choose that model.
+
+Ollama exposes installed-model discovery. OpenAI does not expose equivalent
+discovery through this integration, so its embedding model id is entered
+manually. If an enabled embedding provider becomes unavailable, memory
+retrieval or saving is skipped while the completed user response is preserved.
+
 ## Web UI
 
 The packaged Web UI is the primary local GUI. Its default backend talks directly

package/docs/long-term-memory.md

@@ -0,0 +1,181 @@
+# Passive Long-Term Memory
+
+ABot Runtime can retain selected user facts and preferences across sessions.
+This feature is passive: the model does not invoke a memory tool, and the
+Runtime core remains the only owner of retrieval, filtering, deduplication,
+storage, and deletion.
+
+Long-term memory is disabled by default. Enabling it is an explicit consumer
+choice because it may persist personal information between conversations.
+
+## How It Works
+
+The Supervisor path separates memory proposal from the user-facing response.
+When long-term memory is enabled, `supervisor.response` first performs one
+structured candidate-only call:
+
+```json
+{
+  "memoryCandidates": [
+    {
+      "content": "A durable fact or preference established by the user.",
+      "tags": ["normalized-later-by-core"]
+    }
+  ]
+}
+```
+
+`memoryCandidates` is empty when there is nothing durable to propose. The
+Supervisor then authors the complete user-facing response through its ordinary
+raw-text contract, without a JSON wrapper. Invalid or unavailable candidate
+authoring is isolated to an empty candidate list and cannot replace or
+invalidate that raw response. This sequential split adds the candidate-call
+latency before the Supervisor response is delivered.
+
+`execution.response` retains the combined strict envelope containing both
+`finalResponse` and `memoryCandidates`; its external response contract is
+unchanged.
+
+Candidate data remains internal and is processed after the final assistant
+response is persisted. Persistence runs through a Runtime-owned background
+queue; response completion never waits for embedding or memory-store work.
+
+Before the next terminal response is authored, the Runtime retrieves a small
+relevant set from the cross-session pool. Retrieval uses provider embeddings
+plus bounded lexical, tag, and recency scoring. The projection is passive
+reference context; it is never treated as a new user request or an instruction.
+
+Retrieval, candidate policy, filtering, deduplication, and persistence are
+shared by `supervisor.response` and `execution.response`; only their authoring
+contracts differ. Decision, planning, Worker, Reviewer, payload, and tool
+contexts do not receive the long-term memory projection.
+
+Both response paths also share the same configured response-experience
+methodology. It applies whether memory is enabled or disabled. Relevant memory
+is an optional passive layer that may improve continuity and useful defaults;
+it never replaces the current request, forces a personal reference, or grants
+action authority.
+
+## Enable It
+
+Configure an ordinary model provider first with `abot init` or `abot add-model`.
+Then choose an embedding model exposed by that provider. ABot does not choose,
+install, or download an embedding model.
+
+For a packaged installation:
+
+```bash
+npx abot memory status
+npx abot memory models --provider <provider-id>
+npx abot memory enable --provider <provider-id> --model <embedding-model-id>
+```
+
+From a source checkout, use the equivalent commands:
+
+```bash
+npm run memory -- status
+npm run memory -- models --provider <provider-id>
+npm run memory -- enable --provider <provider-id> --model <embedding-model-id>
+```
+
+Add `--emit-events` to expose bounded lifecycle events to clients. Enablement
+performs a real embedding probe and validates the complete candidate config
+before writing it. The previous config is backed up, and a restart is required
+after enablement or disablement.
+
+The Config workspace in the packaged Web UI uses the same onboarding service.
+It can list configured providers, discover models when the provider supports
+discovery, probe and enable a selected model, or disable the feature. A provider
+without discovery support accepts a model id entered by the user.
+
+## Configuration Contract
+
+The onboarding flow writes a dedicated embedding profile and binds the feature
+to it:
+
+```json
+{
+  "models": {
+    "embeddingProfiles": {
+      "memory-embedding": {
+        "label": "Long-term memory embeddings",
+        "provider": "ollama",
+        "model": "<embedding-model-id>"
+      }
+    }
+  },
+  "longTermMemory": {
+    "enabled": true,
+    "emitClientEvents": false,
+    "embeddingProfileId": "memory-embedding"
+  }
+}
+```
+
+Embedding profiles are intentionally separate from generation profiles. They
+accept `provider`, `model`, optional `label`, and provider-owned JSON-safe
+`options`; generation, reasoning, context-window, and output settings are not
+valid embedding-profile fields.
+
+When disabled, no repository read, embedding request, model-output envelope,
+or memory lifecycle event is added to the response path.
+
+## Providers
+
+- Ollama uses its `/api/embed` contract and can discover locally installed
+  model ids through `/api/tags`.
+- OpenAI uses `/embeddings`. Model discovery is not exposed by that provider,
+  so the consumer supplies the embedding model id.
+- A custom model-gateway adapter may implement `embed` and optional
+  `listEmbeddingModels` without changing Runtime memory policy.
+
+If the selected embedding provider becomes unavailable during a request, the
+Runtime skips memory retrieval or persistence, records a bounded diagnostic,
+and preserves normal response delivery.
+
+## Storage, Privacy, And Management
+
+The default adapter stores canonical records and their derived vector index at:
+
+```text
+<runtimeDir>/long-term-memory/memory.json
+```
+
+The file is runtime-generated local state and must not be published or
+committed. Canonical records contain content, normalized tags, timestamps, and
+source session/request provenance. Derived vectors are versioned by model
+fingerprint and are rebuilt when that fingerprint or vector dimension changes.
+
+The core rejects obvious secrets such as private keys, labeled passwords, API
+keys, and common token formats. Exact duplicates are merged mechanically;
+semantic similarity alone never overwrites an existing record.
+
+Library hosts can manage the pool through the composed service:
+
+```ts
+const runtime = createRuntimeApplication(config);
+
+await runtime.services.longTermMemory.status();
+await runtime.services.longTermMemory.list({ limit: 50 });
+await runtime.services.longTermMemory.delete({ id: memoryId });
+await runtime.services.longTermMemory.clear();
+```
+
+Management APIs return canonical records, not embedding vectors.
+
+## Client Events
+
+With `emitClientEvents: true`, clients may receive bounded lifecycle events:
+
+- `memory.retrieval.started|completed|failed`
+- `memory.save.queued`
+
+The save event confirms only that background persistence was scheduled. Its
+completion or failure is diagnostic-only and cannot change the completed user
+response. Client events contain lifecycle status and counts only. They never
+include memory content, tags, vectors, credentials, or the model's internal
+candidates.
+
+The bundled `memory` plugin remains a separate, explicit user-invoked
+capability. Passive long-term memory does not depend on that plugin and remains
+operational if the plugin is disabled or removed.

package/docs/plugins.md

@@ -127,19 +127,34 @@ must be unique bounded lowercase ids matching
 built-in conventions, not a closed enum. Manifests that omit both levels remain
 compatible and use the plugin name as their single catalog group.
 
-The delegated Supervisor and Planner receive only an aggregate catalog of these
-group ids, membership counts, descriptions, and declared effects. When either
-invokes a Worker against a non-empty catalog, it supplies one or more group
-ids; the runtime stores that scope on the Worker call and exposes the OR-union
-of matching capabilities. The Worker still selects the concrete capability and
-controls.
-
-Each group description is generated from every member capability's manifest
-id and summary in stable order. There is no second category-description JSON or
-manually maintained routing registry.
-
-Under `execution-agent-v1`, the canonical root receives the same aggregate
-group projection and may mechanically open or extend its own RoleCall scope.
+The delegated Supervisor and Planner select group ids when invoking a Worker
+against a non-empty catalog. The runtime stores that scope on the Worker call
+and exposes the OR-union of matching capabilities. The Worker still selects
+the concrete capability and controls.
+
+Supervisor routing receives one optional, passive text brief from the same
+request-filtered registry used by `capability-brief`. It chooses the richest
+complete representation that fits: tool names with operation ids and groups,
+tool names by group, group counts and effects, or no brief. The brief replaces
+the previous aggregate catalog text; group ids remain in the response schema
+in every mode. It includes no tool descriptions, inputs, or operating
+instructions. Its 512-token estimate ceiling is further reduced by existing
+context headroom, including history and instruction reserves. No subset of
+tools is selected to fit, and no model call summarizes the catalog.
+This admission uses the context estimate at projection time. A later provider
+token count, steering update, or structured-output repair can still trigger
+the existing context-compaction path; the brief is not reselected there.
+
+The SDK exports `buildToolAvailabilityBrief` for the unchanged on-demand plugin
+output and `buildToolAvailabilityOverview` for informational representations.
+The runtime context helper owns token admission and the passive reference
+message; another step can explicitly attach it using the existing context
+reference API. Supervisor's working-directory and response phases do not
+receive it. Planner retains its existing group-routing projection.
+
+Under `execution-agent-v1`, the canonical root receives group descriptions
+generated from member capability ids and summaries, and may mechanically open
+or extend its own RoleCall scope.
 It then selects a concrete capability only from that active scope. Scope
 updates, capability binding, payload authoring, adapter execution, and
 settlement use the same ledger and capability engine as delegated Worker