@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/AGENTS.md

@@ -89,7 +89,7 @@ The rule exists because test machinery and production code have **inverted invar
 
 Concretely:
 
-- **Test helpers** (e.g. `src/__tests__/*-test-helpers.ts`) use only node stdlib, `bun:test`, and sibling helpers. If they need to manipulate shared state that production code also reads, both sides declare a typed slot under `globalThis.vellumAssistant.*` and read/write that slot independently. The slot shape is duplicated by design — the helper and the production module both reference the namespace, neither imports the other.
+- **Test helpers** (e.g. `src/__tests__/*-test-helpers.ts`) use only node stdlib, `bun:test`, and sibling helpers. If they need to manipulate shared state that production code also reads, both sides read/write a typed slot under `globalThis.vellumAssistant.*`. The namespace shape is declared once, in the ambient `src/vellum-assistant-namespace.d.ts` (`VellumAssistantNamespace` and its slot value types) — the helper and the production module both refer to those global types by name, so they agree on the shape without either importing the other. Because that declaration is ambient (pure compile-time type info that reaches into no `src/` module), referring to it adds nothing to a helper's runtime import graph, so the no-`src/`-imports invariant still holds. To add a slot: declare its value type in that `.d.ts`, add the optional property to `VellumAssistantNamespace`, and have the owning module plus its test helper reference those globals instead of declaring their own copies.
 - **The test preload** (`src/__tests__/test-preload.ts`) is the strictest: it must not import from `src/` at all. Its only static imports are node stdlib, `bun:test`, and helpers in `src/__tests__/`. Importing from a source module risks running its import-time side effects before the workspace override is set.
 - **The preload verifier** (`src/__tests__/test-preload-verifier.ts`) runs after the main preload and asserts the override took effect (`VELLUM_WORKSPACE_DIR` must resolve under `os.tmpdir()`).
 - **Destructive ops** (e.g. `rmSync(dbPath, ...)`) in tests must call `assertNotLiveDb(path)` from `src/__tests__/assert-not-live-db.js` immediately before the destructive call. The check is a per-callsite belt to the preload-verifier suspenders.

package/ARCHITECTURE.md

@@ -374,10 +374,9 @@ External users who are not the guardian can gain access to the assistant through
 **Notification signals:** The flow emits signals at each lifecycle transition via `emitNotificationSignal()`:
 
 - `ingress.access_request` — unknown contact denied, guardian notified
-- `ingress.trusted_contact.guardian_decision` — guardian approved or denied
-- `ingress.trusted_contact.verification_sent` — code created and delivered
+- `ingress.trusted_contact.guardian_decision` — the guardian's verdict (the payload's `decision` field carries approved/denied; exactly one lifecycle signal fires per denial)
+- `ingress.trusted_contact.verification_sent` — code created and delivered (stands in for `guardian_decision` on approve so the pipeline doesn't announce approval before verification)
 - `ingress.trusted_contact.activated` — requester verified, contact active
-- `ingress.trusted_contact.denied` — guardian explicitly denied
 
 **HTTP API (for management):**
 
@@ -752,7 +751,7 @@ Conversation starters follow the same pattern via `GET /v1/conversation-starters
 
 The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is the canonical module for determining whether an assistant feature flag is enabled. It loads default values from the unified registry at `meta/feature-flags/feature-flag-registry.json` (bundled copy at `src/config/feature-flag-registry.json`) and resolves the effective state for each declared assistant-scope flag. Assistant feature flags are declaration-driven assistant-scoped booleans that can gate any assistant behavior; skill availability is one consumer.
 
-**Canonical key format:** Simple kebab-case (e.g., `contacts`, `voice-mode`).
+**Canonical key format:** Simple kebab-case (e.g., `contacts`, `browser`).
 
 **Resolution priority** (highest wins):
 
@@ -780,7 +779,7 @@ The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is
 
 All six enforcement points derive the flag key via `skillFlagKey(skill)` — which returns `undefined` for ungated skills, short-circuiting the check — and then call `isAssistantFeatureFlagEnabled(flagKey, config)` for consistency.
 
-**Migration path:** The legacy `skills.<id>.enabled` and `feature_flags.<id>.enabled` key formats are no longer supported. All code must use simple kebab-case keys (e.g., `contacts`, `voice-mode`). Guard tests enforce canonical key usage and declaration coverage for literal key references in the unified registry.
+**Migration path:** The legacy `skills.<id>.enabled` and `feature_flags.<id>.enabled` key formats are no longer supported. All code must use simple kebab-case keys (e.g., `contacts`, `browser`). Guard tests enforce canonical key usage and declaration coverage for literal key references in the unified registry.
 
 **Key source files:**
 

package/README.md

@@ -145,7 +145,7 @@ All approval prompt delivery paths use a **fail-closed** policy -- if the prompt
 
 ### Plain-Text Fallback for Non-Rich Channels
 
-Channels that do not support rich inline approval UI (e.g., inline keyboards) receive plain-text instructions embedded in the message body. The `channelSupportsRichApprovalUI()` check determines whether to send the structured `promptText` (for rich channels like Telegram) or the `plainTextFallback` string (for all other channels). The fallback text includes instructions so the user can respond via text; the conversational approval engine then classifies the free-text response.
+Channels that do not support rich inline approval UI (e.g., inline keyboards) receive plain-text instructions embedded in the message body. The `supportsInlineOptions` channel capability (`channelSupportsInlineOptions()`) determines whether to send the structured `promptText` (for channels whose adapter renders inline buttons like Telegram) or the `plainTextFallback` string (for all other channels). The fallback text includes instructions so the user can respond via text; the conversational approval engine then classifies the free-text response.
 
 ### Key modules
 

package/docs/architecture/memory.md

@@ -1,31 +1,53 @@
 # Memory Architecture
 
-Assistant memory and context-injection architecture.
+Assistant memory and context-injection architecture. For the memory plugin's
+internal layering contract — the tier/directory map, the frozen-name registry,
+and the v1/v2 deletion runbooks — see
+`src/plugins/defaults/memory/AGENTS.md`.
 
 ## Tiers
 
 An assistant runs exactly one memory tier, derived by `memoryTier()` in
 `src/config/memory-tier.ts`:
 
-| Tier  | Selected when                                | Injection source                              |
-| ----- | -------------------------------------------- | --------------------------------------------- |
-| `off` | `memory.enabled === false`                   | none                                          |
-| `v3`  | `memory.v3.live === true`                    | v3 lanes + card (`v3/injector.ts`)            |
-| `v2`  | `memory.v2.enabled === true` and v3 not live | v2 activation/router engine (`v2/`)           |
-| `v1`  | otherwise                                    | PKB `<knowledge_base>` block (`pkb/`, legacy) |
+| Tier  | Selected when                                | Injection source                                 |
+| ----- | -------------------------------------------- | ------------------------------------------------ |
+| `off` | `memory.enabled === false`                   | none                                             |
+| `v3`  | `memory.v3.live === true`                    | v3 lanes + card (`v3/injector.ts`)               |
+| `v2`  | `memory.v2.enabled === true` and v3 not live | v2 activation/router engine (`v2/`)              |
+| `v1`  | otherwise                                    | PKB `<knowledge_base>` block (`v1/pkb/`, legacy) |
 
 New workspaces are switched to `v3` at creation (workspace migration 105).
 `v1` and the `v2` injection engine are in retirement; v3 is the target state.
 
-## The concept-page substrate (`v3/substrate/`)
+### Tier predicates
+
+Tier decisions are made through named predicates in
+`src/config/memory-v3-gate.ts`, never by reading `memory.v2.*` / `memory.v3.*`
+directly — `memory.v2.enabled` defaults true and typically stays set on v3-live
+assistants, so a raw read misbehaves under v3. `memoryTier()` is fully derived
+from those predicates, so the telemetry buckets and the runtime gates can never
+disagree. The two that shape this document are `usesConceptPageMemory()` (the
+substrate is live) and `isMemoryV3Live()` (v3 is the injected source).
+
+The full predicate table — what each one is true for and, importantly, exactly
+which machinery it gates — is in `src/plugins/defaults/memory/AGENTS.md`, which
+is authoritative. Consult it before gating new code.
+
+The memory plugin is layered into tier directories (`substrate/`, `v1/`, `v2/`,
+`v3/`) that never import each other — multi-tier composition is confined to a
+frozen set of spine files, and both rules plus the raw-tier-key ban are enforced
+by `src/plugins/defaults/memory/__tests__/memory-tier-boundary-guard.test.ts`.
+
+## The concept-page substrate (`substrate/`)
 
 The durable core shared by v2 and v3 is the **concept-page substrate**:
 markdown articles under `memory/concepts/` (plus the aggregate views
 `essentials.md`, `threads.md`, `recent.md` and the intake `buffer.md`), their
 cached page index, and the concept-page Qdrant collection with dense + BM25
 sparse vectors. It lives in
-`src/plugins/defaults/memory/v3/substrate/` because it is memory-v3's
-foundation — the v2 injection engine is just a second (transitional) consumer.
+`src/plugins/defaults/memory/substrate/`; it is memory-v3's foundation, and
+the v2 injection engine is a second (transitional) consumer.
 
 Substrate activation is a single predicate, `usesConceptPageMemory()` in
 `src/config/memory-v3-gate.ts`: memory on AND (`memory.v3.live` OR
@@ -50,7 +72,7 @@ graph LR
 - `handleRemember` (`graph/tool-handlers.ts`) appends timestamped bullets to
   `memory/buffer.md` + the daily archive whenever memory is enabled. Facts may
   carry `[[slug]]` page hints that consolidation reads first when filing.
-- **Consolidation** (`v3/substrate/consolidation-job.ts`) is a background
+- **Consolidation** (`substrate/consolidation-job.ts`) is a background
   agent conversation that files buffer entries into concept pages, rewrites
   the aggregate views, and trims the buffer. Scheduling
   (`maybeEnqueueGraphMaintenanceJobs` in `jobs-worker.ts`):
@@ -67,10 +89,10 @@ graph LR
 ### Read paths
 
 - **v3 (live)**: per-turn lane selection over concept pages — dense/sparse
-  retrieval (`v3/substrate/sim.ts` over the concept-page collection),
+  retrieval (`substrate/sim.ts` over the concept-page collection),
   learned edges, entity/hot/fresh/core sets — rendered as the `<memory>`
   card by `v3/injector.ts`. The static `<info>` block
-  (`v3/substrate/static-context.ts`: essentials/threads/recent/buffer) also
+  (`substrate/static-context.ts`: essentials/threads/recent/buffer) also
   injects whenever the substrate is active.
 - **v2 (transitional)**: activation/router engine in `v2/`
   (`activation.ts`, `router.ts`, `reranker.ts`, `injection.ts`) selects
@@ -82,7 +104,7 @@ graph LR
 
 ### Boot-time maintenance
 
-`v3/substrate/memory-v2-startup.ts`, invoked from the memory plugin's
+`substrate/boot-maintenance.ts`, invoked from the memory plugin's
 startup path: skill + CLI-command capability seeding into the concept-page
 collection, BM25 corpus-stats rebuild, and collection schema
 reconcile/reembed. All gated on `usesConceptPageMemory()`.
@@ -94,22 +116,37 @@ substrate as a backend-agnostic node/edge graph for the web Memory tab:
 concept pages as nodes, authored links + learned co-selection associations as
 edges, and `memory/buffer.md` entries as `pending` nodes
 (`graph-topology/pending-buffer.ts`) so a just-saved fact appears before
-consolidation files it. Gated on the `memory-concept-graph` feature flag +
-`memory.v3.live`. `GET /v1/memory-graph-node` serves node detail, including
-`buffer:` ids for pending entries.
+consolidation files it. Gated on `isV3TierActive()` — memory enabled and
+`memory.v3.live` — which is also the source of the cheap `graph_supported`
+bit on `GET /v1/memory/stats`, so the advertised capability and the actual
+build can never drift. The same predicate gates procedural-memory-as-skills,
+so both v3-tier features honor the Memory opt-out identically. `GET /v1/memory-graph-node` serves node detail,
+including `buffer:` ids for pending entries.
 
 ## Capture beyond `remember`
 
 - **Retrospective** (`memory-retrospective-*.ts`): periodic per-conversation
   review pass that saves what wasn't captured in the moment (and, on v3-live
   assistants, authors procedural skills).
-- **Sweep** (`v3/substrate/sweep-job.ts`, `memory.v2.sweep_enabled`, default
-  off): idle-debounced extraction of recent messages into the buffer.
+- **Sweep** (`substrate/sweep-job.ts`, `sweep_enabled` substrate tunable,
+  default off): idle-debounced extraction of recent messages into the buffer.
 
 ## Config namespaces
 
-Substrate tuning still lives under the historical `memory.v2.*` keys
-(consolidation intervals/limits, embedding + retrieval weights) and v3 lane
-tuning under `memory.v3.*`. The `memory.v2.enabled` flag gates only the v2
-injection engine's turn-time selection; the substrate runs whenever
+Substrate tuning resolves from `memory.substrate.*` with fallback to the
+historical `memory.v2.*` keys: every substrate tunable (consolidation
+intervals/limits, embedding + retrieval weights, BM25 parameters, sweep
+toggle) is optional under `memory.substrate`, and `resolveSubstrateTuning`
+(`substrate/tuning.ts`) — the substrate's single config choke point — falls
+back per key to the `memory.v2` twin, which supplies the effective defaults
+and which the v2 injection engine also reads. v2 engine-only keys (activation
+weights, router, rerank) live only under `memory.v2.*`, and v3 lane tuning
+under `memory.v3.*`. The `memory.v2.enabled` flag gates only the v2 injection
+engine's turn-time selection; the substrate runs whenever
 `usesConceptPageMemory()` holds.
+
+`src/plugins/defaults/memory/AGENTS.md` carries the details that matter when
+you touch this: the three substrate keys whose names differ from their v2 twin,
+the three disjoint places the dense/sparse sum-to-1 invariant is checked, and
+why workspace migration 135 copies only explicitly-set NON-DEFAULT `memory.v2`
+tunables into `memory.substrate`.

package/docs/error-handling.md

@@ -71,11 +71,11 @@ Returning `undefined` is acceptable only for **lookup functions** where "not fou
 | Subagent manager (`subagent/manager.ts`)              | Throws for precondition violations, string literal unions for expected outcomes | Depth limit exceeded is a bug; `sendMessage` returns `'not_found' \| 'terminal' \| 'queue_full'` as expected states            |
 | Interactive UI (`cli/commands/ui.ts`)                 | Result object (`InteractiveUiResult`) with `status` + exit codes                | User cancel and timeout are expected operational outcomes, not errors. IPC failures are exceptional.                           |
 
-## 4. Interactive UI interactions (`assistant ui confirm` / `assistant ui request`)
+## 4. Interactive UI Interactions (`assistant ui confirm` / `assistant ui request`)
 
 The `assistant ui` commands present blocking interactive surfaces (confirmations, forms) to the user and wait for a response. Their error model distinguishes three categories:
 
-### Expected outcomes (not errors)
+### Expected Outcomes (Not Errors)
 
 User decisions — including declining — are normal operational results:
 
@@ -92,7 +92,7 @@ User decisions — including declining — are normal operational results:
 
 Scripts must handle all three non-confirmation outcomes. A `cancelled` status means the user deliberately chose not to proceed — log it as a normal flow, not an error. A `timed_out` status means the user was unresponsive — abort without side effects.
 
-### Cancellation reasons (`ui request` only)
+### Cancellation Reasons (`ui request` only)
 
 When using `assistant ui request --json`, a `cancelled` result includes a `cancellationReason` field that distinguishes **user-driven** cancellations from **operational fail-closed** cancellations. This allows scripts to choose different recovery strategies depending on why the surface was cancelled.
 

package/docs/guardian-request-flow.md

@@ -0,0 +1,112 @@
+# Guardian requests: the interactive-request pipeline
+
+This is the end-to-end map of how an interactive request — anything the
+assistant needs a person to decide or answer — reaches a user on any channel
+and how their response resolves it. **It is the canonical rail for interactive
+channel features.** If you are adding a feature that shows buttons/options on
+a channel and waits for a reply, extend the seams below; do **not** build a
+per-feature watcher, callback scheme, or parallel delivery stack (that
+anti-pattern was retired in #35642 and again in the ask_question redesign).
+
+## The lifecycle
+
+```
+  tool / flow parks a pending interaction        (runtime/pending-interactions.ts)
+        │
+        ▼ promotion (fire-and-forget, at the emitter)
+  guardian_requests row, gateway-owned           (permissions/confirmation-guardian-request.ts,
+  create → decide(CAS) → expire/sweep             permissions/question-guardian-request.ts,
+        │                                         gateway/src/db/guardian-request-store.ts)
+        ▼ bridge emits guardian.question signal
+  notification pipeline                          (notifications/emit-signal.ts →
+  decision engine → destination resolver →        decision-engine.ts → destination-resolver.ts →
+  broadcaster builds the card context ONCE        broadcaster.ts: resolveApprovalContext /
+  (generic actions[] + plainTextFallback)         resolveQuestionOptionsContext)
+        │
+        ▼ per-channel rendering ONLY
+  channel adapters                               (notifications/adapters/{telegram,slack,macos,platform},
+  telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
+  card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
+        │
+        ▼ user responds: button tap / emoji reaction / "CODE <reply>" / bare text
+  guardian reply router                          (runtime/guardian-reply-router.ts, invoked from
+  reactions → callbacks → request codes →         routes/inbound-stages/guardian-reply-intercept.ts,
+  bare answer → explicit approve/reject → NL      BEFORE background dispatch — replies to parked
+        │                                         prompts resolve inline, never deferred)
+        ▼ one decision primitive
+  applyGuardianDecision                          (approvals/guardian-decision-primitive.ts:
+  status CAS + ACL outcome, atomic;               first-writer-wins; card withdrawal on decide)
+        │
+        ▼ per-kind follow-through
+  resolver registry                              (approvals/guardian-request-resolvers.ts)
+  tool_approval → confirmation resume             pending_question → voice answerCall OR
+  access_request → ACL outcome                    ask_question interaction resolve
+```
+
+## Who owns what
+
+| Concern                                 | Owner                                                    | Never                               |
+| --------------------------------------- | -------------------------------------------------------- | ----------------------------------- |
+| The "what": card text, actions, options | broadcaster context build (once per broadcast)           | built per-adapter                   |
+| The "how": channel-native rendering     | `notifications/adapters/<channel>`                       | domain logic, payload parsing       |
+| Request state                           | gateway `guardian_requests` (+ deliveries)               | daemon-side request tables          |
+| Decisions                               | `applyGuardianDecision` (CAS, atomic ACL outcome)        | inline decision logic at call sites |
+| Kind-specific follow-through            | resolver registry (`kind` → resolver)                    | switch statements in the router     |
+| Reply understanding                     | guardian reply router (codes, buttons, reactions, modes) | per-feature inbound intercepts      |
+
+Two instruction modes exist per request kind (`notifications/guardian-question-mode.ts`):
+**approval** ("CODE approve" / approve–reject buttons) and **answer**
+("CODE <your answer>" / option buttons). `pending_question` is answer-mode.
+
+## Worked example: `ask_question` on a channel
+
+1. The tool parks on `QuestionPrompter` when the turn can deliver a card
+   (`ToolContext.supportsGuardianQuestionCards` — single-question batch,
+   guardian turn, channel in `GUARDIAN_QUESTION_CARD_CHANNELS`); otherwise it
+   returns the plain-text fallback.
+2. The prompter promotes the interaction to a `pending_question` row
+   (`permissions/question-guardian-request.ts` — request id = interaction
+   requestId, mirroring `tool_approval`) and bridges it
+   (`runtime/question-request-guardian-bridge.ts`).
+3. The broadcaster renders the options as card actions with answer-token ids
+   (`answer_<idx>` / `answer_skip` — `buildQuestionOptionActionId`); adapters
+   need no changes, ever.
+4. A tap arrives as `apr:<requestId>:answer_<idx>`; the router recognizes the
+   token for answer-mode requests. A bare text reply while exactly one
+   answer-mode request is pending IS the answer. "CODE <text>" works like any
+   request.
+5. The `pending_question` resolver (no `callSessionId` → ask_question branch)
+   maps the token/text to a submission and settles the interaction via
+   `resolvePendingQuestion` — the same core `/v1/question-response` uses — so
+   the parked tool returns and the turn continues.
+6. Lifecycle: answered elsewhere / timed out → the orphan sweep in
+   `conversation-routes.ts` expires the row (voice rows, which carry
+   `callSessionId`, are exempt); daemon restart → boot's
+   `expire_interaction_bound`.
+
+## Adding a new interactive request kind
+
+1. Add the kind to `GuardianRequestKindSchema`
+   (`packages/gateway-client/src/guardian-request-contract.ts`).
+2. Promote at the emitter (mirror `confirmation-guardian-request.ts`) and
+   bridge to `emitNotificationSignal` with a typed payload
+   (`guardian-question-mode.ts` schemas).
+3. If the card needs non-default actions, add a context branch in the
+   broadcaster — actions are generic `{id,label}`; adapters are untouched.
+4. Add reply-mode config (`REQUEST_KIND_MODE_CONFIG`) if the kind answers
+   rather than approves.
+5. Register a resolver (`guardian-request-resolvers.ts`) for the kind's
+   follow-through.
+
+That is the whole checklist. If a design requires touching the inbound
+message handler, a channel transport, or a new callback prefix, the design is
+at the wrong level.
+
+## Legacy rail (in-turn approval interception)
+
+`routes/guardian-approval-interception.ts` + the approval prompt watcher in
+`background-dispatch.ts` predate this pipeline: they deliver a guardian's own
+tool-approval prompt in-channel mid-turn and resolve `apr:` taps against the
+in-memory confirmation directly. They remain load-bearing for that flow, and
+the reply router runs first for everything the pipeline owns. Converge new
+work on the pipeline; do not extend the legacy interception.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -17,6 +17,7 @@
     "./rpc": "./src/rpc.ts",
     "./attachment-naming": "./src/attachment-naming.ts",
     "./redacted-credential": "./src/redacted-credential.ts",
+    "./secret-detection": "./src/secret-detection.ts",
     "./error": "./src/error.ts"
   },
   "scripts": {

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/channels.test.ts

@@ -18,8 +18,16 @@ describe("isChannelId", () => {
     expect(isChannelId("vellum")).toBe(true);
   });
 
+  test("includes discord", () => {
+    // Discord is canonical vocabulary ahead of its ingress implementation:
+    // the gateway's inbound list and the admission-policy seed both derive
+    // from CHANNEL_IDS, so it must be here for a Discord message to be
+    // routable and to carry an admission floor at all.
+    expect(isChannelId("discord")).toBe(true);
+  });
+
   test("rejects unknown strings and non-string values", () => {
-    expect(isChannelId("discord")).toBe(false);
+    expect(isChannelId("mastodon")).toBe(false);
     expect(isChannelId("")).toBe(false);
     expect(isChannelId(undefined)).toBe(false);
     expect(isChannelId(null)).toBe(false);