@vellumai/assistant 0.10.6-dev.202607072040.fb971ce → 0.10.6-staging.1

package/AGENTS.md

@@ -12,27 +12,12 @@ 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.
 
 **Exception — duplicate daemon detection:** If the daemon cannot establish **any** client-facing transport because another daemon already holds both the IPC socket and HTTP port, it must exit immediately. A daemon with no transport is unmanageable (invisible to health checks, unreachable by stop commands) yet still runs background jobs (scheduler, memory worker, background wake) against the shared database, causing duplicate side effects.
 
-## DB migration readiness gating
-
-DB migrations run asynchronously during startup: the HTTP server binds (so `/healthz` answers) **before** `initializeDb()` finishes, and readiness is tracked in `src/daemon/daemon-readiness.ts` (`setDbMigrating` → `setDbReady`/`setDbMigrationFailed`). **No code may touch the database — `getDb()`, `getSqlite()`, drizzle queries, raw SQL — unless `getDbMigrationReadiness().ready` is true or its execution provably starts after `initializeDb()` settles in `daemon/lifecycle.ts`.** Querying earlier hits a partially-migrated schema ("no such table"/"no such column").
-
-Existing enforcement, which new code must not bypass:
-
-- **HTTP** requests are gated per-route in `runtime/http-server.ts`; **IPC** methods in `ipc/assistant-server.ts`; both derive their exempt set from `DB_MIGRATION_READINESS_EXEMPT_OPERATIONS` in `daemon-readiness.ts` (health/liveness probes only — anything exempted must never touch the DB).
-- **Message sinks** (`processMessage`, `processMessageInBackground`) guard via `assertDbMigrationsReadyForTurn()`.
-- **Background sweeps** are started by lifecycle only after migrations settle (`startRuntimeHttpServerBackgroundSweeps`).
-- The **migration-repair surface** (`admin/rollback-migrations` plus all `migrations/import*` / preflight transports and their job-status route) is additionally allowed in the terminal `failed` state only — see `DB_MIGRATION_FAILED_STATE_EXEMPT_OPERATIONS`. Never widen this to the `running` state: a rollback or import would race the in-flight migration runner. A successful repair does not clear the failed latch — the daemon must be restarted to re-run migrations and become ready.
-
-When adding a new background job, timer, signal handler, or transport entry point that reaches the DB, either start it after `initializeDb()` settles in lifecycle, or check `getDbMigrationReadiness().ready` (and skip/queue when unready) inside it. Do not add readiness waits to probe endpoints — `/healthz` must stay static and instant.
-
 ## Post-execution hooks
 
 Tool post-execution hooks (`src/daemon/tool-side-effects.ts`) run after a tool executor returns. They are an **observation-and-notification layer** only: refresh client-side state, broadcast events, kick off orthogonal background work (e.g. icon generation). Hooks must not re-do work the executor already performed, and must not attempt recovery when the executor failed — failures surface in the tool result for the LLM to act on.

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
@@ -424,18 +423,18 @@ External users who are not the guardian can gain access to the assistant through
 
 **Key source files:**
 
-| File                                                   | Purpose                                                                                         |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, unknown-contact rejection, verification code interception                          |
-| `src/runtime/routes/access-request-decision.ts`        | Guardian decision → verification session creation                                               |
-| `src/runtime/routes/guardian-approval-interception.ts` | Routes guardian decisions (button + conversational) to access request handler                   |
-| `src/runtime/channel-verification-service.ts`          | Verification session lifecycle, identity binding, rate limiting                                 |
-| `src/runtime/routes/contact-routes.ts`                 | HTTP/IPC handlers for contacts, channels, and invites (invite ops relay to gateway IPC)         |
+| File                                                   | Purpose                                                                       |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `src/runtime/routes/inbound-message-handler.ts`        | Ingress ACL, unknown-contact rejection, verification code interception        |
+| `src/runtime/routes/access-request-decision.ts`        | Guardian decision → verification session creation                             |
+| `src/runtime/routes/guardian-approval-interception.ts` | Routes guardian decisions (button + conversational) to access request handler |
+| `src/runtime/channel-verification-service.ts`          | Verification session lifecycle, identity binding, rate limiting               |
+| `src/runtime/routes/contact-routes.ts`                 | HTTP/IPC handlers for contacts, channels, and invites (invite ops relay to gateway IPC) |
 | `src/runtime/invite-service.ts`                        | Daemon-owned invite presentation (share link, guardian instruction) over gateway-minted invites |
-| `src/contacts/contact-store.ts`                        | Contact read queries — lookup, search, list, and channel operations                             |
-| `src/memory/guardian-approvals.ts`                     | Approval request persistence                                                                    |
-| `src/channels/channel-verification-sessions.ts`        | Verification challenge persistence                                                              |
-| `src/config/bundled-skills/contacts/SKILL.md`          | Unified skill for contact management, access control, and invite links                          |
+| `src/contacts/contact-store.ts`                        | Contact read queries — lookup, search, list, and channel operations           |
+| `src/memory/guardian-approvals.ts`                     | Approval request persistence                                                  |
+| `src/channels/channel-verification-sessions.ts`        | Verification challenge persistence                                            |
+| `src/config/bundled-skills/contacts/SKILL.md`          | Unified skill for contact management, access control, and invite links        |
 
 ### Guardian-Initiated Invite Links
 
@@ -481,11 +480,11 @@ A complementary access-granting flow where the guardian proactively creates a sh
 
 **Channel adapter status:**
 
-| Channel  | Status   | Prerequisites                                                                                                                                             |
-| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Telegram | Shipped  | Bot username resolved from credential metadata or config                                                                                                  |
+| Channel  | Status   | Prerequisites                                                                                                                                                 |
+| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Telegram | Shipped  | Bot username resolved from credential metadata or config                                                                                                      |
 | Voice    | Shipped  | Identity-bound voice code redemption via DTMF/speech in the call setup flow. Always-on canonical behavior with personalized friend/guardian name prompts. |
-| Slack    | Deferred | Needs DM-safe ingress — Socket Mode handles channel messages but DM-initiated invite flows need routing                                                   |
+| Slack    | Deferred | Needs DM-safe ingress — Socket Mode handles channel messages but DM-initiated invite flows need routing                                                       |
 
 ### Voice Invite Flow (invite_redemption)
 
@@ -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.
@@ -515,17 +514,17 @@ Voice invites use a short numeric code (6 digits) instead of a URL token. The gu
 
 **Key source files:**
 
-| File                                                      | Purpose                                                                                                                                |
-| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `gateway/src/verification/invite-redemption.ts` (gateway) | Core redemption engine + gateway-ingress token/code intercept — validation, atomic claim, ACL activation, discriminated-union outcomes |
-| `src/runtime/channel-invite-transport.ts`                 | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface                                               |
-| `src/runtime/channel-invite-transports/telegram.ts`       | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction                                            |
-| `src/runtime/channel-invite-transports/voice.ts`          | Voice transport adapter — code-based redemption metadata                                                                               |
-| `src/daemon/guardian-invite-intent.ts`                    | Intent detection — routes create/list/revoke requests into the contacts skill                                                          |
-| `src/runtime/invite-service.ts`                           | Daemon-owned invite presentation (share link, guardian instruction, channel handle) over gateway-minted invites                        |
-| `src/runtime/routes/contact-routes.ts`                    | HTTP/IPC invite handlers — relay mint/list/revoke/redeem to the gateway's invite IPC routes                                            |
-| `src/calls/call-setup-flow.ts`                            | Transport-agnostic call setup flow — `invite_redemption` sub-flow (always-on canonical behavior)                                       |
-| `src/calls/gateway-invite-reader.ts`                      | Gateway IPC read of the active voice invite for a caller identity                                                                      |
+| File                                                | Purpose                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `gateway/src/verification/invite-redemption.ts` (gateway) | Core redemption engine + gateway-ingress token/code intercept — validation, atomic claim, ACL activation, discriminated-union outcomes  |
+| `src/runtime/channel-invite-transport.ts`           | Transport adapter registry with `buildShareableInvite` / `extractInboundToken` interface                           |
+| `src/runtime/channel-invite-transports/telegram.ts` | Telegram adapter — `t.me/<bot>?start=iv_<token>` deep links, `/start iv_<token>` extraction                        |
+| `src/runtime/channel-invite-transports/voice.ts`    | Voice transport adapter — code-based redemption metadata                                                           |
+| `src/daemon/guardian-invite-intent.ts`              | Intent detection — routes create/list/revoke requests into the contacts skill                                      |
+| `src/runtime/invite-service.ts`                     | Daemon-owned invite presentation (share link, guardian instruction, channel handle) over gateway-minted invites    |
+| `src/runtime/routes/contact-routes.ts`              | HTTP/IPC invite handlers — relay mint/list/revoke/redeem to the gateway's invite IPC routes                        |
+| `src/calls/call-setup-flow.ts`                      | Transport-agnostic call setup flow — `invite_redemption` sub-flow (always-on canonical behavior)                   |
+| `src/calls/gateway-invite-reader.ts`                | Gateway IPC read of the active voice invite for a caller identity                                                  |
 
 ### Voice Inbound Security Model (Canonical)
 
@@ -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
@@ -587,13 +586,13 @@ All guardian decisions for voice access requests flow through:
 
 | File                                           | Purpose                                                                                |
 | ---------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `src/calls/call-setup-router.ts`               | Inbound call decision tree (`routeSetup`)                                              |
-| `src/calls/call-setup-flow.ts`                 | Name capture, verification, and invite sub-flows over the media-stream transport       |
-| `src/calls/guardian-wait-controller.ts`        | Guardian approval wait — hold messaging, heartbeats, poll/timeout                      |
+| `src/calls/call-setup-router.ts`              | Inbound call decision tree (`routeSetup`)                                               |
+| `src/calls/call-setup-flow.ts`                 | Name capture, verification, and invite sub-flows over the media-stream transport        |
+| `src/calls/guardian-wait-controller.ts`        | Guardian approval wait — hold messaging, heartbeats, poll/timeout                       |
 | `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
@@ -604,13 +603,13 @@ Audio-to-text conversion occurs in six distinct runtime boundaries, each with it
 
 **Boundary overview:**
 
-| Boundary                     | Runtime                                             | Provider (current)                           | Adapter module                                                                                                                                                                                                                                             | Caller                                                  |
-| ---------------------------- | --------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| **Telephony (media-stream)** | Daemon process (Twilio Media Streams WebSocket)     | Configured STT provider (via `services.stt`) | `src/calls/media-stream-stt-session.ts`, `src/providers/speech-to-text/resolve.ts`, streaming provider adapters                                                                                                                                            | `src/calls/media-stream-server.ts`                      |
-| **Daemon batch**             | Daemon process (REST API to provider)               | Configured STT provider (via `services.stt`) | `src/stt/daemon-batch-transcriber.ts`                                                                                                                                                                                                                      | `src/runtime/routes/inbound-stages/transcribe-audio.ts` |
-| **Conversation streaming**   | Daemon process (WebSocket-based)                    | Configured STT provider (via `services.stt`) | `src/stt/stt-stream-session.ts`, `src/providers/speech-to-text/deepgram-realtime.ts`, `src/providers/speech-to-text/google-gemini-live-stream.ts`, `src/providers/speech-to-text/openai-whisper-stream.ts`, `src/providers/speech-to-text/xai-realtime.ts` | Web/Electron dictation client via gateway WS proxy      |
-| **Live voice channel**       | Assistant process (gateway-authenticated WebSocket) | Configured STT provider (via `services.stt`) | `src/runtime/http-server.ts`, `src/live-voice/live-voice-session-manager.ts`, `src/live-voice/live-voice-session.ts`, `src/providers/speech-to-text/resolve.ts`, streaming provider adapters                                                               | Web/Electron live voice client via `/v1/live-voice`     |
-| **Client service-first**     | Web/Electron via gateway → daemon                   | Configured STT provider (via `services.stt`) | `src/runtime/routes/stt-routes.ts`                                                                                                                                                                                                                         | Web/Electron dictation and voice clients                |
+| Boundary                   | Runtime                                                                       | Provider (current)                           | Adapter module                                                                                                                                                                                                                                             | Caller                                                  |
+| -------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| **Telephony (media-stream)** | Daemon process (Twilio Media Streams WebSocket)                             | Configured STT provider (via `services.stt`) | `src/calls/media-stream-stt-session.ts`, `src/providers/speech-to-text/resolve.ts`, streaming provider adapters                                                                                                                                            | `src/calls/media-stream-server.ts`                      |
+| **Daemon batch**           | Daemon process (REST API to provider)                                         | Configured STT provider (via `services.stt`) | `src/stt/daemon-batch-transcriber.ts`                                                                                                                                                                                                                      | `src/runtime/routes/inbound-stages/transcribe-audio.ts` |
+| **Conversation streaming** | Daemon process (WebSocket-based)                                              | Configured STT provider (via `services.stt`) | `src/stt/stt-stream-session.ts`, `src/providers/speech-to-text/deepgram-realtime.ts`, `src/providers/speech-to-text/google-gemini-live-stream.ts`, `src/providers/speech-to-text/openai-whisper-stream.ts`, `src/providers/speech-to-text/xai-realtime.ts` | Web/Electron dictation client via gateway WS proxy      |
+| **Live voice channel**     | Assistant process (gateway-authenticated WebSocket)                           | Configured STT provider (via `services.stt`) | `src/runtime/http-server.ts`, `src/live-voice/live-voice-session-manager.ts`, `src/live-voice/live-voice-session.ts`, `src/providers/speech-to-text/resolve.ts`, streaming provider adapters                                                               | Web/Electron live voice client via `/v1/live-voice`     |
+| **Client service-first**   | Web/Electron via gateway → daemon                                             | Configured STT provider (via `services.stt`) | `src/runtime/routes/stt-routes.ts`                                                                                                                                                                                                                         | Web/Electron dictation and voice clients                |
 
 **Telephony boundary (media-stream):**
 
@@ -625,18 +624,18 @@ A credential preflight (`resolveTelephonyCredentialReadiness()` in `src/calls/te
 
 Key modules:
 
-| Module                                              | Purpose                                                                                               |
-| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Module                                              | Purpose                                                                          |
+| --------------------------------------------------- | -------------------------------------------------------------------------------- |
 | `src/calls/twilio-routes.ts`                        | Voice webhook handler; generates `<Connect><Stream>` TwiML, enforces the inbound credential preflight |
-| `src/calls/telephony-credential-preflight.ts`       | Combined STT + TTS credential-readiness resolver                                                      |
-| `src/calls/media-stream-parser.ts`                  | Twilio Media Streams protocol parser                                                                  |
-| `src/calls/media-turn-detector.ts`                  | Energy-based VAD turn detector for raw audio (batch mode)                                             |
-| `src/calls/media-stream-stt-session.ts`             | STT session — streaming/batch mode selection and transcription via `services.stt`                     |
-| `src/calls/media-stream-audio-transcode.ts`         | Mu-law ↔ PCM16 codecs and resampling                                                                  |
-| `src/calls/call-transport.ts`                       | Transport interface decoupling CallController from wire protocol                                      |
-| `src/calls/media-stream-output.ts`                  | Output adapter for sending TTS audio back via Media Streams                                           |
-| `src/calls/media-stream-server.ts`                  | WebSocket server binding media-stream lifecycle to call sessions and setup flows                      |
-| `gateway/src/http/routes/twilio-media-websocket.ts` | Gateway WebSocket proxy for Media Streams frames                                                      |
+| `src/calls/telephony-credential-preflight.ts`       | Combined STT + TTS credential-readiness resolver                                 |
+| `src/calls/media-stream-parser.ts`                  | Twilio Media Streams protocol parser                                             |
+| `src/calls/media-turn-detector.ts`                  | Energy-based VAD turn detector for raw audio (batch mode)                        |
+| `src/calls/media-stream-stt-session.ts`             | STT session — streaming/batch mode selection and transcription via `services.stt` |
+| `src/calls/media-stream-audio-transcode.ts`         | Mu-law ↔ PCM16 codecs and resampling                                             |
+| `src/calls/call-transport.ts`                       | Transport interface decoupling CallController from wire protocol                 |
+| `src/calls/media-stream-output.ts`                  | Output adapter for sending TTS audio back via Media Streams                      |
+| `src/calls/media-stream-server.ts`                  | WebSocket server binding media-stream lifecycle to call sessions and setup flows |
+| `gateway/src/http/routes/twilio-media-websocket.ts` | Gateway WebSocket proxy for Media Streams frames                                 |
 
 Guard tests in `__tests__/twilio-routes-twiml.test.ts` and `__tests__/twilio-routes.test.ts` assert that every supported STT provider yields `<Connect><Stream>` TwiML for both inbound and outbound calls.
 
@@ -1771,6 +1770,99 @@ sequenceDiagram
 
 ---
 
+## Trace System — Debug Panel Data Flow
+
+The trace system provides real-time observability of daemon conversation internals. Each conversation creates a `TraceEmitter` that emits structured `trace_event` SSE events as the conversation processes requests, makes LLM calls, and executes tools.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Chat as ChatView
+    participant DC as DaemonClient
+    participant Daemon as Session (Daemon)
+    participant TE as TraceEmitter
+    participant EB as EventBus
+    participant TTL as ToolTraceListener
+    participant LLM as LLM Provider
+    participant TS as TraceStore (Swift)
+    participant DP as DebugPanel
+
+    User->>Chat: send message
+    Chat->>DC: user_message
+    DC->>Daemon: HTTP
+
+    Daemon->>TE: emit(request_received)
+    TE-->>DC: trace_event (request_received)
+    DC-->>TS: onTraceEvent → ingest()
+
+    Daemon->>LLM: API call
+    Daemon->>TE: emit(llm_call_started)
+    TE-->>DC: trace_event (llm_call_started)
+    DC-->>TS: ingest()
+
+    LLM-->>Daemon: streaming response
+    Daemon->>TE: emit(llm_call_finished, tokens + latency)
+    TE-->>DC: trace_event (llm_call_finished)
+    DC-->>TS: ingest()
+
+    Note over Daemon,EB: Tool execution triggers domain events
+
+    Daemon->>EB: tool.execution.started
+    EB->>TTL: onAny(event)
+    TTL->>TE: emit(tool_started)
+    TE-->>DC: trace_event (tool_started)
+    DC-->>TS: ingest()
+
+    Daemon->>EB: tool.execution.finished
+    EB->>TTL: onAny(event)
+    TTL->>TE: emit(tool_finished, durationMs)
+    TE-->>DC: trace_event (tool_finished)
+    DC-->>TS: ingest()
+
+    Daemon->>TE: emit(message_complete)
+    TE-->>DC: trace_event (message_complete)
+    DC-->>TS: ingest()
+
+    Note over TS: Events deduplicated by eventId,<br/>ordered by sequence + timestampMs,<br/>grouped by conversation and requestId,<br/>capped at 5000 per conversation
+
+    TS-->>DP: @Published eventsByConversation
+    Note over DP: Metrics strip: requests, LLM calls,<br/>tokens (in/out), avg latency, failures<br/>Timeline: events grouped by requestId
+```
+
+### Trace Event Kinds
+
+Events emitted during a conversation lifecycle:
+
+| Kind                        | Emitted by              | When                                                                                            |
+| --------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `request_received`          | Handlers / Conversation | User message or surface action arrives                                                          |
+| `request_queued`            | Handlers / Conversation | Message queued while conversation is busy                                                       |
+| `request_dequeued`          | Conversation            | Queued message begins processing                                                                |
+| `llm_call_started`          | Conversation            | LLM API call initiated                                                                          |
+| `llm_call_finished`         | Conversation            | LLM API call completed (carries `inputTokens`, `outputTokens`, `latencyMs`)                     |
+| `assistant_message`         | Conversation            | Assistant response assembled (carries `toolUseCount`)                                           |
+| `tool_started`              | ToolTraceListener       | Tool execution begins                                                                           |
+| `tool_permission_requested` | ToolTraceListener       | Permission check needed (carries `riskLevel`)                                                   |
+| `tool_permission_decided`   | ToolTraceListener       | Permission granted or denied (carries `decision`)                                               |
+| `tool_finished`             | ToolTraceListener       | Tool execution completed (carries `durationMs`)                                                 |
+| `tool_failed`               | ToolTraceListener       | Tool execution failed (carries `durationMs`)                                                    |
+| `generation_handoff`        | Conversation            | Yielding to next queued message                                                                 |
+| `message_complete`          | Conversation            | Full request processing finished                                                                |
+| `generation_cancelled`      | Conversation            | User cancelled the generation                                                                   |
+| `request_error`             | Handlers / Conversation | Unrecoverable error during processing (includes queue-full rejection and persist-failure paths) |
+
+### Architecture
+
+- **TraceEmitter** (daemon, per-conversation): Constructed with a `conversationId` and a `sendToClient` callback. Maintains a monotonic sequence counter for stable ordering. Truncates summaries to 200 chars and attribute values to 500 chars. Each call to `emit()` sends a `trace_event` SSE event to connected clients.
+- **ToolTraceListener** (daemon): Subscribes to the conversation's `EventBus` via `onAny()` and translates tool domain events (`tool.execution.started`, `tool.execution.finished`, `tool.execution.failed`, `tool.permission.requested`, `tool.permission.decided`) into trace events through the `TraceEmitter`.
+- **DaemonClient** (Swift, shared): Decodes `trace_event` SSE events into `TraceEventMessage` structs and invokes the `onTraceEvent` callback.
+- **TraceStore** (Swift, macOS): `@MainActor ObservableObject` that ingests `TraceEventMessage` structs. Deduplicates by `eventId`, maintains stable sort order (sequence, then timestampMs, then insertion order), groups events by conversation and requestId, and enforces a retention cap of 5,000 events per conversation. Each request group is classified with a terminal status: `completed` (via `message_complete`), `cancelled` (via `generation_cancelled`), `handedOff` (via `generation_handoff`), `error` (via `request_error` or any event with `status == "error"`), or `active` (no terminal event yet).
+- **DebugPanel** (Swift, macOS): SwiftUI view that observes `TraceStore`. Displays a metrics strip (request count, LLM calls, total tokens, average latency, tool failures) and a `TraceTimelineView` showing events grouped by requestId with color-coded status indicators. The timeline auto-scrolls to new events while the user is at the bottom; scrolling up pauses auto-scroll and shows a "Jump to bottom" button that resumes it.
+
+---
+
+---
+
 ## Assistant Events — SSE Transport Layer
 
 The assistant-events system provides a single, shared publish path that fans out to all connected clients via HTTP SSE. The `ServerMessage` payload is wrapped in an `AssistantEvent` envelope and serialised as JSON.
@@ -2004,6 +2096,7 @@ Connected channels are resolved at signal emission time: vellum is always includ
 | Sandbox filesystem                       | `$VELLUM_WORKSPACE_DIR`                                | Real filesystem tree                | Node FS APIs                       | Persistent across sessions                              |
 | Tool permission rules                    | `~/.vellum/protected/trust.json`                       | JSON                                | File I/O                           | Permanent                                               |
 | Web users & assistants                   | PostgreSQL                                             | Relational                          | Drizzle ORM (pg)                   | Permanent                                               |
+| Trace events                             | In-memory (TraceStore)                                 | Structured events                   | Swift ObservableObject             | Max 5,000 per session, ephemeral                        |
 | Media embed settings                     | `$VELLUM_WORKSPACE_DIR/config.json` (`ui.mediaEmbeds`) | JSON                                | `WorkspaceConfigIO` (atomic merge) | Permanent                                               |
 | Media embed MIME cache                   | In-memory (`ImageMIMEProbe`)                           | `NSCache` (500 entries)             | HTTP HEAD                          | Ephemeral; cleared on app restart                       |
 | Tasks & task runs                        | `$VELLUM_WORKSPACE_DIR/data/db/assistant.db`           | SQLite                              | Drizzle ORM                        | Permanent                                               |

package/Dockerfile

@@ -1,4 +1,3 @@
-# syntax=docker/dockerfile:1.20@sha256:26147acbda4f14c5add9946e2fd2ed543fc402884fd75146bd342a7f6271dc1d
 # Use debian as base image
 FROM debian:trixie-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a AS builder
 
@@ -17,24 +16,33 @@ RUN apt-get update && apt-get install -y \
 RUN curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
 ENV PATH="/root/.bun/bin:${PATH}"
 
-# We must include every workspace member's manifest to validate and install the
-# workspace lockfile via --frozen-lockfile.
-# Note that we don't need source code to resolve cross-workspace dependencies.
-COPY package.json bun.lock ./
-COPY patches ./patches
-COPY clients/macos/package.json ./clients/macos/
-COPY clients/web/package.json ./clients/web/
-COPY cli/package.json ./cli/
-COPY gateway/package.json ./gateway/
-COPY credential-executor/package.json ./credential-executor/
-COPY assistant/package.json ./assistant/
-COPY assistant/src/api/package.json ./assistant/src/api/
-COPY --parents packages/*/package.json ./
-
-RUN bun install --frozen-lockfile --ignore-scripts \
-    --filter='./assistant' --filter='./assistant/src/api'
-
-# The repo-root .dockerignore decides which skills (and files) ship.
+# Copy shared packages needed by assistant's repo-local dependencies
+COPY packages/ces-client ./packages/ces-client
+COPY packages/service-contracts ./packages/service-contracts
+COPY packages/credential-storage ./packages/credential-storage
+COPY packages/egress-proxy ./packages/egress-proxy
+COPY packages/environments ./packages/environments
+COPY packages/gateway-client ./packages/gateway-client
+COPY packages/ipc-server-utils ./packages/ipc-server-utils
+COPY packages/slack-text ./packages/slack-text
+COPY packages/twilio-client ./packages/twilio-client
+
+# Install deps for shared packages whose source is loaded at runtime.
+# Without this, bun's module resolution walks up from packages/<name>/src/
+# and can't find the package's own deps (zod, transitive file: refs)
+# because only assistant/node_modules gets populated.
+RUN cd /app/packages/ces-client && bun install --frozen-lockfile
+RUN cd /app/packages/gateway-client && bun install --frozen-lockfile
+RUN cd /app/packages/service-contracts && bun install --frozen-lockfile
+
+# Install assistant dependencies first for cache reuse
+COPY assistant/package.json assistant/bun.lock ./assistant/
+RUN cd /app/assistant && bun install --frozen-lockfile
+
+# Copy bundled first-party skills and install their deps. The repo-root
+# .dockerignore is the single source of truth for which skills (and which
+# files within them) ship in the assistant image -- adding or removing a
+# bundled skill is a .dockerignore edit, not a Dockerfile edit.
 COPY skills ./skills
 RUN set -eu; for pkg in /app/skills/*/package.json; do \
       [ -e "$pkg" ] || continue; \
@@ -114,19 +122,9 @@ RUN apt-get update && apt-get install -y \
 COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
 RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 
+# Copy installed deps, shared packages, and bundled skills from the builder stage.
 COPY --from=builder /app /app
 
-# Copy source after installing dependencies for better layer caching.
-COPY packages/ces-client /app/packages/ces-client
-COPY packages/service-contracts /app/packages/service-contracts
-COPY packages/credential-storage /app/packages/credential-storage
-COPY packages/egress-proxy /app/packages/egress-proxy
-COPY packages/environments /app/packages/environments
-COPY packages/gateway-client /app/packages/gateway-client
-COPY packages/ipc-server-utils /app/packages/ipc-server-utils
-COPY packages/slack-text /app/packages/slack-text
-COPY packages/twilio-client /app/packages/twilio-client
-
 COPY assistant /app/assistant
 
 # Install assistant CLI launcher backed by the bundled assistant package

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.