@vellumai/assistant 0.10.7-dev.202607102035.64f07ea → 0.10.7-staging.1

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 For error handling conventions (throw vs result objects vs null), see [docs/error-handling.md](docs/error-handling.md).
 
-Subdirectory-scoped rules live in local AGENTS.md files: `src/cli/`, `src/runtime/`, `src/approvals/`, `src/notifications/`, `src/plugins/`, `src/workspace/migrations/`.
+Subdirectory-scoped rules live in local AGENTS.md files: `src/cli/`, `src/runtime/`, `src/approvals/`, `src/notifications/`, `src/workspace/migrations/`.
 
 ## Adding new environment variables
 
@@ -12,8 +12,6 @@ When you introduce a new env var that the assistant process needs to read at run
 
 **Default to including it.** If the var doesn't contain secrets (e.g. a URL, a feature flag, a path, a mode string), add it. Only omit it if it carries credential material (tokens, passwords, private keys) — those must stay isolated to CES.
 
-`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs — assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`).
-
 ## Daemon startup philosophy
 
 The daemon must **never** block startup due to **subsystem** failures (DB, Qdrant, plugins, feature flags, etc.). If an individual subsystem fails, log the error and continue in degraded mode so the process remains reachable for health checks and diagnostics.

package/ARCHITECTURE.md

@@ -98,8 +98,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 | `src/runtime/auth/route-policy.ts`                | Route-level scope/principal enforcement                                                       |
 | `src/runtime/routes/guardian-bootstrap-routes.ts` | `POST /v1/guardian/init` (initial JWT issuance)                                               |
 | `src/runtime/routes/guardian-refresh-routes.ts`   | `POST /v1/guardian/refresh` (token rotation)                                                  |
-| `src/runtime/local-actor-identity.ts`             | `resolveLocalAuthContext` — synthetic local AuthContext + guardian principal lookup           |
-| `src/runtime/local-principal-trust.ts`            | `resolveLocalPrincipalTrustContext` — local-principal trust from the gateway guardian binding |
+| `src/runtime/local-actor-identity.ts`             | `resolveLocalGuardianContext` — deterministic local identity                                  |
 | `src/channels/channel-verification-sessions.ts`   | Guardian binding types, verification session management                                       |
 
 ### Channel-Agnostic Scoped Approval Grants
@@ -500,7 +499,7 @@ Voice invites use a short numeric code (6 digits) instead of a URL token. The gu
 
 **Call-time redemption subflow (`invite_redemption`):**
 
-1. Unknown caller dials in. The media-stream server resolves trust from the gateway trust verdict (a missing/failed verdict denies fail-closed). Caller is `unknown`, no pending guardian challenge.
+1. Unknown caller dials in. The media-stream server resolves trust (gateway trust verdict first, `resolveActorTrust` fallback inside `routeSetup`). Caller is `unknown`, no pending guardian challenge.
 2. `routeSetup` asks the gateway for the active voice invite bound to the caller's phone number (`get_active_voice_invite` IPC via `calls/gateway-invite-reader.ts`; fail-soft — any gateway failure falls through to the unverified path).
 3. If an active, non-expired invite exists, the `CallSetupFlow` runs the `invite_redemption` sub-flow (collecting the code via DTMF or spoken digits) and prompts the caller with personalized copy: `Welcome <friend-name>. Please enter the 6-digit code that <guardian-name> provided you to verify your identity.`
 4. The gateway's `redeem_voice_invite` engine validates: identity match, code hash match, expiry, use count. On success, the phone channel is activated in the gateway ACL and the call transitions to the normal call flow.
@@ -537,7 +536,7 @@ The voice inbound security model determines how unknown callers are handled when
 Unknown caller dials in
         |
         v
-gateway trust verdict → trustClass
+resolveActorTrust() → trustClass
         |
         ├── guardian / trusted_contact → normal call flow
         ├── blocked → immediate denial + disconnect
@@ -593,7 +592,7 @@ All guardian decisions for voice access requests flow through:
 | `src/runtime/access-request-helper.ts`         | Creates canonical access request and notifies guardian                                 |
 | `src/approvals/guardian-decision-primitive.ts` | `applyCanonicalGuardianDecision` — unified decision primitive                          |
 | `src/approvals/guardian-request-resolvers.ts`  | `access_request` resolver — voice direct activation, text-channel verification session |
-| `src/runtime/trust-verdict-consumer.ts`        | Gateway verdict → caller trust classification (`actorTrustContextFromVerdict`)         |
+| `src/runtime/actor-trust-resolver.ts`          | `resolveActorTrust` — caller trust classification                                      |
 | `src/contacts/canonical-guardian-store.ts`     | Canonical request persistence and CAS resolution                                       |
 
 ### Speech-to-Text (STT) Boundaries
@@ -735,7 +734,7 @@ The assistant-side live voice module is intentionally bounded under `src/live-vo
 
 Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming. For V1 latency-sensitive behavior, the selected `services.stt.provider` must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
 
-Live voice TTS uses `streamLiveVoiceTtsAudio()` and the configured `services.tts.provider`. The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all four catalog providers: ElevenLabs, Fish Audio, Deepgram, and xAI) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
+Live voice TTS uses `streamLiveVoiceTtsAudio()` and the configured `services.tts.provider`. The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Fish Audio is the current catalog provider with streaming synthesis support; non-streaming providers remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
 
 V1 is local/gateway-scoped. Managed/cloud WebSocket proxy support, cross-region routing, and p50/p95 latency guarantees are out of scope for this version. Metrics frames expose timing data for measurement, but the architecture does not promise a hard latency SLO.
 
@@ -786,7 +785,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`, `ces-tools`).
 
 **Resolution priority** (highest wins):
 
@@ -814,7 +813,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`, `ces-tools`). Guard tests enforce canonical key usage and declaration coverage for literal key references in the unified registry.
 
 **Key source files:**
 
@@ -857,10 +856,11 @@ graph LR
 
     subgraph "$VELLUM_WORKSPACE_DIR/data/db/assistant.db (SQLite + WAL)"
         direction TB
-        CONV["conversations<br/>───────────────<br/>id, title, timestamps<br/>token counts, estimated cost<br/>context_summary (compaction)<br/>conversation_type: 'standard' | 'background' | 'scheduled'"]
+        CONV["conversations<br/>───────────────<br/>id, title, timestamps<br/>token counts, estimated cost<br/>context_summary (compaction)<br/>conversation_type: 'standard' | 'background' | 'scheduled'<br/>memory_scope_id: 'default' | '_pkb_workspace' | 'subagent:&lt;id&gt;'"]
         MSG["messages<br/>───────────────<br/>id, conversation_id (FK)<br/>role: user | assistant<br/>content: JSON array<br/>created_at"]
         TOOL["tool_invocations<br/>───────────────<br/>tool_name, input, result<br/>decision, risk_level<br/>duration_ms"]
         SEG["memory_segments<br/>───────────────<br/>Text chunks for retrieval<br/>Linked to messages<br/>token_estimate per segment"]
+        ITEMS["memory_items<br/>───────────────<br/>Extracted facts/entities<br/>kind, subject, statement<br/>confidence, fingerprint (dedup)<br/>verification_state, scope_id<br/>first/last seen timestamps"]
         SUM["memory_summaries<br/>───────────────<br/>scope: conversation | weekly<br/>Compressed history for context<br/>window management"]
         EMB["memory_embeddings<br/>───────────────<br/>target: segment | item | summary<br/>provider + model metadata<br/>vector_json (float array)<br/>Powers semantic search"]
         JOBS["memory_jobs<br/>───────────────<br/>Async task queue<br/>Types: embed, extract,<br/>summarize, backfill, cleanup<br/>Status: pending → running →<br/>completed | failed"]

package/README.md

@@ -252,7 +252,7 @@ The channel guardian service generates verification challenge instructions with
 The vellum channel (macOS) uses JWTs to bind guardian identity to HTTP requests. This enables identity-based authentication for the local desktop channel, paralleling how external channels (Telegram) use `actorExternalId` for guardian identity. The CLI authenticates using its bearer token obtained during `hatch`.
 
 - **Bootstrap**: After hatch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The endpoint is idempotent -- repeated calls with the same device return the same principal but mint fresh credentials. The CLI does not bootstrap separately; it uses the bearer token minted during `hatch`.
-- **Local identity**: Local connections get a server-side synthetic `AuthContext` via `resolveLocalAuthContext()` (`runtime/local-actor-identity.ts`) without requiring a JWT; trust derives from the gateway guardian binding via `resolveLocalPrincipalTrustContext()` (`runtime/local-principal-trust.ts`), failing closed to unknown.
+- **Local identity**: Local connections resolve identity server-side via `resolveLocalGuardianContext()` without requiring a JWT.
 - **HTTP enforcement**: All vellum HTTP routes require a valid JWT via the `Authorization: Bearer <jwt>` header. The JWT carries identity claims (`sub` with principal type and ID) and scope permissions. Route-level enforcement in `route-policy.ts` checks scopes and principal types.
 - **Startup migration**: On gateway start, `ensureVellumGuardianBinding()` in `gateway/src/auth/guardian-bootstrap.ts` backfills a vellum guardian binding for existing installations so the identity system works without requiring a manual bootstrap step.
 

package/docs/architecture/memory.md

@@ -155,6 +155,7 @@ graph TB
         EMBED_Q["Generate dense + sparse<br/>query embeddings"]
         HYBRID["Hybrid Search<br/>dense + sparse RRF on Qdrant"]
         MERGE["Merge + Deduplicate<br/>weighted score combination"]
+        SCOPE["Scope Filter<br/>scope_id filtering<br/>(strict | global_fallback)<br/>Subagents: own scope + 'default'"]
         TIER["Tier Classification<br/>score > 0.8 → tier 1<br/>score > 0.6 → tier 2<br/>below → dropped"]
         STALE["Staleness Computation<br/>kind-specific lifetimes<br/>+ reinforcement from<br/>source conversation count"]
         DEMOTE["Stale Demotion<br/>very_stale tier 1 → tier 2"]
@@ -214,7 +215,8 @@ graph TB
     EMBED_Q --> SPARSE_GEN
     EMBED_Q --> HYBRID
     HYBRID --> RRF
-    HYBRID --> MERGE
+    HYBRID --> SCOPE
+    SCOPE --> MERGE
     MERGE --> TIER
     TIER --> STALE
     STALE --> DEMOTE

package/docs/credential-execution-service.md

@@ -34,15 +34,23 @@ For local single-user and development deployments, the assistant spawns CES as a
 
 For managed multi-tenant deployments, CES runs as a sidecar container in the same pod. Communication occurs over a **bootstrap Unix socket** mounted at a well-known path in a shared `emptyDir` volume. The sidecar starts independently and the assistant connects to the socket on startup.
 
-## CES RPC Operations
+## CES Tools
 
-CES implements three credential-execution RPC operations. Credential values are materialized only inside the CES process (`credential-executor/` package); a caller sends credential handles and receives sanitized results, never plaintext secret material.
+CES exposes exactly three tools to the assistant, registered as a **deliberate exception** to the skill-first tool direction (see `AGENTS.md` and `assistant/src/tools/AGENTS.md`). These tools are not skills because they require hard process-boundary isolation that skill scripts cannot provide.
 
-| Operation                    | Purpose                                                                                                                                                                             |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run_authenticated_command`  | Execute a shell command with credential environment variables injected by CES. The credential values are set in the CES process environment only — never transmitted to the caller. |
-| `make_authenticated_request` | Execute an HTTP request with credential-bearing headers/auth injected by CES. CES performs the HTTP call and returns the response body and status to the caller.                    |
-| `manage_secure_command_tool` | Register and manage secure command tool bundles in the CES toolstore. Handles bundle lifecycle (registration, unregistration) for manifest-driven credential-bearing commands.      |
+| Tool                         | Purpose                                                                                                                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run_authenticated_command`  | Execute a shell command with credential environment variables injected by CES. The credential values are set in the CES process environment only — never transmitted to the assistant. |
+| `make_authenticated_request` | Execute an HTTP request with credential-bearing headers/auth injected by CES. CES performs the HTTP call and returns the response body and status to the assistant.                    |
+| `manage_secure_command_tool` | Register and manage secure command tool bundles in the CES toolstore. Handles bundle lifecycle (registration, unregistration) for manifest-driven credential-bearing commands.         |
+
+### Tool registration
+
+CES tools use the standard `class ... implements Tool` registration pattern. These are justified exceptions to the general preference for skills because:
+
+- The security boundary requires that credential materialization happens in a separate process
+- Skill scripts run inside the assistant process and cannot enforce the hard isolation invariant
+- The tools are thin RPC stubs; the actual logic lives in the `credential-executor/` package
 
 ## Locked Decisions
 
@@ -217,13 +225,47 @@ These invariants are enforced by guard tests and code review:
 
 1. **No cross-package source imports**: `assistant/` must not import from `credential-executor/` and vice versa. Communication is RPC only. Shared types flow through `packages/` only.
 2. **No credential values in assistant process memory**: The assistant sends credential handles (not values) to CES. CES materializes and uses them internally.
-3. **Credential-bearing execution goes through CES RPC**: operations that must materialize a credential run inside the CES process across the hard process boundary. All other credential use continues through the existing broker for local deployments.
+3. **CES tools justify tool registrations over skills** for credential-bearing execution because of the hard process-boundary isolation requirement. All other credential use continues through the existing broker for local deployments.
 4. **Grants and audit logs are CES-internal**: The assistant cannot read CES grant tables or audit logs directly. CES exposes grant status and audit summaries via RPC responses.
 5. **No generic authenticated HTTP clients in secure commands**: `curl`, `wget`, `httpie`, interpreters, and shell trampolines are structurally denied as secure command entrypoints. This is checked at manifest validation and re-checked at execution time.
 6. **Managed CES container runs as non-root**: The CES Docker image runs as `uid 1001` (user `ces`). The CES data volume is owned by this user.
 7. **Single active bootstrap connection**: In managed mode, CES accepts one connection on the bootstrap socket and unlinks the socket path while that connection is live, so no second process can connect concurrently. CES is a long-lived sidecar: when the active session ends (the assistant disconnects or its container restarts), CES re-binds the socket and awaits the assistant's reconnection rather than shutting down. At most one connection is ever active; the sidecar only exits on SIGTERM/SIGINT.
 
-## Guarantees by deployment mode
+## Rollout
+
+CES is rolled out incrementally via feature flags, all defaulting to `false` (off). The flags are ordered to allow progressive enablement without user-facing disruption.
+
+### Feature flag order
+
+Enable flags in this order. Each flag is safe to enable independently, but later flags depend on earlier ones being on for meaningful behavior.
+
+| Order | Flag                  | Gate                                                                                                                                                | Safe to enable alone?                                                                                                           |
+| ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | `ces-tools`           | Register CES tools (`run_authenticated_command`, `make_authenticated_request`, `manage_secure_command_tool`) in the agent loop                      | Yes — tools register but are not invoked unless the agent discovers credentials that require CES                                |
+| 2     | `ces-shell-lockdown`  | Enforce shell lockdown for untrusted agents with CES-active credentials; direct shell access to credentialed services is denied                     | Yes — only activates when CES credentials are present                                                                           |
+| 3     | `ces-secure-install`  | Route tool/command installation through CES secure bundle pipeline instead of direct shell                                                          | Yes — falls back to standard install if CES is unavailable                                                                      |
+| 4     | `ces-grant-audit`     | Gate CLI execution of grant listing, grant revocation, and audit inspection commands (commands are always registered but check the flag at runtime) | Yes — read-only inspection surfaces                                                                                             |
+| 5     | `ces-managed-sidecar` | Use managed sidecar transport (Unix socket) instead of local child-process transport                                                                | **No** — requires the CES sidecar container to be present in the pod template. Only enable after the sidecar image is deployed. |
+
+### Dark-launching the managed sidecar
+
+To dark-launch CES in managed deployments without user impact:
+
+1. **Deploy the CES container image** via the `credential_executor_image` field in `POST /v1/internal/assistant-image-releases/`. The warm-pool manager picks it up and includes it in pod templates. The CES container starts, binds its bootstrap socket and health port (8090), but does nothing until an assistant connects.
+
+2. **Verify sidecar health** using kubelet probes: `/healthz` (liveness, returns `{"status": "ok"}`) and `/readyz` (readiness, always returns 200; includes `rpcConnected` field for observability).
+
+3. **Enable `ces-tools`** first on a test cohort. The assistant spawns a local CES child process and registers tools. Verify tool registration, grant creation, and audit logging work end-to-end without affecting existing workflows.
+
+4. **Enable `ces-managed-sidecar`** on the same cohort. The assistant switches from child-process transport to the bootstrap Unix socket. CES `/readyz` always returns 200 with `{"status": "ok", "rpcConnected": <boolean>}`; check the `rpcConnected` field to verify the assistant has connected.
+
+5. **Progressive rollout**: Widen the cohort by enabling flags on more assistants. Monitor for grant failures, materializer errors, and egress proxy issues.
+
+### Local deployment rollout
+
+Local deployments do not require image changes. Enabling `ces-tools` causes the assistant to spawn CES as a child process automatically. The remaining flags can be enabled in any order.
+
+### Guarantees by deployment mode
 
 | Guarantee                                  | Local                                                                                                 | Managed                                                                                                                                          |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -234,6 +276,51 @@ These invariants are enforced by guard tests and code review:
 | Secret scrubbing in HTTP responses         | Defense-in-depth only                                                                                 | Defense-in-depth only                                                                                                                            |
 | `host_bash` restriction                    | Policy-only (trust rules can deny, but the tool exists)                                               | Policy-only (same; managed deployments should deny `host_bash` for untrusted agents)                                                             |
 
+## Rollback
+
+### Disabling CES entirely
+
+Turn off all CES feature flags. The assistant stops registering CES tools and reverts to the pre-CES credential broker for all credential operations. No data migration is needed — CES grant and audit state is CES-private and does not affect the assistant's own tables.
+
+Flag disable order:
+
+> **Important — managed deployments**: In managed containers, the assistant image does not ship the `credential-executor` binary, so local CES transport is unavailable. Disabling `ces-managed-sidecar` while `ces-tools` is still enabled will break credentialed tool execution because the assistant cannot fall back to local discovery. Always disable `ces-tools` before `ces-managed-sidecar` in managed deployments.
+
+**Local deployments** (reverse of enable order):
+
+1. `ces-managed-sidecar` — assistant reverts to local child-process transport
+2. `ces-grant-audit` — inspection surfaces disappear
+3. `ces-secure-install` — tool installation reverts to direct shell
+4. `ces-shell-lockdown` — shell lockdown is lifted
+5. `ces-tools` — CES tools are unregistered from the agent loop
+
+**Managed deployments** (`ces-tools` must be disabled before the sidecar):
+
+1. `ces-grant-audit` — inspection surfaces disappear
+2. `ces-secure-install` — tool installation reverts to direct shell
+3. `ces-shell-lockdown` — shell lockdown is lifted
+4. `ces-tools` — CES tools are unregistered; assistant reverts to the pre-CES credential broker
+5. `ces-managed-sidecar` — sidecar transport is deactivated (safe now that no CES tools are registered)
+
+### Removing the managed sidecar
+
+If the CES sidecar container causes pod scheduling issues or resource pressure:
+
+1. Disable `ces-tools` on all assistants first (prevents the assistant from attempting CES calls).
+2. Disable `ces-managed-sidecar` on all assistants.
+3. Remove the CES container and its volume mounts from the pod template in vembda.
+4. CES grant/audit data on the `/ces-data` volume is orphaned and can be cleaned up at convenience.
+
+The assistant reverts to the pre-CES credential broker once `ces-tools` is disabled.
+
+### Partial rollback
+
+Individual flags can be disabled independently:
+
+- Disabling `ces-shell-lockdown` alone re-allows direct shell access to credentialed services while keeping CES tools available.
+- Disabling `ces-grant-audit` alone removes inspection surfaces without affecting CES execution.
+- Disabling `ces-secure-install` alone reverts tool installation to direct shell without affecting CES command execution.
+
 ## Residual Risks
 
 Risks that are acknowledged and accepted for v1, documented here so they are explicit rather than implied.