@vellumai/assistant 0.5.16 → 0.6.1

package/AGENTS.md

@@ -12,6 +12,10 @@ 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.
 
+## Daemon startup philosophy
+
+The daemon must **never** block startup under *any circumstance*. All possible errors should be logged so that the assistant can recover from it's corrupted state after the fact.
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/ARCHITECTURE.md

@@ -17,7 +17,7 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - The same resolver is used by:
   - `/channels/inbound` (Telegram/WhatsApp path) before run orchestration.
   - Inbound Twilio voice setup (`RelayConnection.handleSetup`) to seed call-time actor context.
-- Runtime channel runs pass this as `trustContext`, and conversation runtime assembly injects `<inbound_actor_context>` (via `inboundActorContextFromTrustContext()`) into provider-facing prompts.
+- Runtime channel runs pass this as `trustContext`, and conversation runtime assembly includes actor context in the unified `<turn_context>` block (via `buildUnifiedTurnContextBlock()`) injected into provider-facing prompts.
 - Voice calls mirror the same prompt contract: `CallController` receives guardian context on setup and refreshes it immediately after successful voice challenge verification, so the first post-verification turn is grounded as `actor_role: guardian`.
 - Voice-specific behavior (DTMF/speech verification flow, relay state machine) remains voice-local; only actor-role resolution is shared.
 
@@ -634,14 +634,14 @@ The assistant feature-flag resolver (`src/config/assistant-feature-flags.ts`) is
 
 **Skill-gating guarantee:** Skill feature-flag gating is **opt-in**: only skills whose SKILL.md frontmatter contains a `featureFlag` field are gated. Skills without the field are always available regardless of feature flag state. For skills that declare a `featureFlag`, when the corresponding flag is OFF the skill is unavailable everywhere — it cannot appear in client UIs, model context, or runtime tool execution. This is enforced at six independent points:
 
-| Enforcement Point                  | Module                                                        | Effect                                                                                                                                                                                                      |
-| ---------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **1. Client skill list**           | `resolveSkillStates()` in `config/skill-state.ts`             | Skills with flag OFF are excluded from the resolved list returned to clients (macOS skill list, settings UI). The skill never appears in the client.                                                        |
-| **2. Capability memory seeding**   | `seedCatalogSkillMemories()` in `skills/skill-memory.ts`      | Skills with flag OFF are excluded from capability memory seeding. The model cannot discover them via semantic recall.                                                                                        |
-| **3. `skill_load` tool**           | `executeSkillLoad()` in `tools/skills/load.ts`                | If the model attempts to load a flagged-off skill by name, the tool returns an error: `"skill is currently unavailable (disabled by feature flag)"`.                                                        |
-| **4. Runtime tool projection**     | `projectSkillTools()` in `daemon/conversation-skill-tools.ts` | Even if a skill was previously active in a session (has `<loaded_skill>` markers in history), the per-turn projection drops it when the flag is OFF. Already-registered tools are unregistered.             |
-| **5. Included child skills**       | `executeSkillLoad()` in `tools/skills/load.ts`                | When a parent skill includes children via the `includes` directive, each child is independently checked against its feature flag. Flagged-off children are silently excluded from the loaded skill content. |
-| **6. Skill install gate**          | `installSkill()` in `daemon/handlers/skills.ts`               | When a client requests skill installation, the function checks the skill's feature flag before proceeding. If the flag is OFF, the install is rejected with an error.                                       |
+| Enforcement Point                | Module                                                        | Effect                                                                                                                                                                                                      |
+| -------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **1. Client skill list**         | `resolveSkillStates()` in `config/skill-state.ts`             | Skills with flag OFF are excluded from the resolved list returned to clients (macOS skill list, settings UI). The skill never appears in the client.                                                        |
+| **2. Capability memory seeding** | `seedSkillGraphNodes()` in `memory/graph/capability-seed.ts`  | Skills with flag OFF are excluded from capability memory seeding. The model cannot discover them via semantic recall.                                                                                       |
+| **3. `skill_load` tool**         | `executeSkillLoad()` in `tools/skills/load.ts`                | If the model attempts to load a flagged-off skill by name, the tool returns an error: `"skill is currently unavailable (disabled by feature flag)"`.                                                        |
+| **4. Runtime tool projection**   | `projectSkillTools()` in `daemon/conversation-skill-tools.ts` | Even if a skill was previously active in a session (has `<loaded_skill>` markers in history), the per-turn projection drops it when the flag is OFF. Already-registered tools are unregistered.             |
+| **5. Included child skills**     | `executeSkillLoad()` in `tools/skills/load.ts`                | When a parent skill includes children via the `includes` directive, each child is independently checked against its feature flag. Flagged-off children are silently excluded from the loaded skill content. |
+| **6. Skill install gate**        | `installSkill()` in `daemon/handlers/skills.ts`               | When a client requests skill installation, the function checks the skill's feature flag before proceeding. If the flag is OFF, the install is rejected with an error.                                       |
 
 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.
 
@@ -653,7 +653,7 @@ All six enforcement points derive the flag key via `skillFlagKey(skill)` — whi
 | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `src/config/assistant-feature-flags.ts`         | Canonical resolver: `isAssistantFeatureFlagEnabled()`, `getAssistantFeatureFlagDefaults()`, registry loader                                                               |
 | `src/config/skill-state.ts`                     | `skillFlagKey(skill)` — returns canonical flag key for skills with a `featureFlag` frontmatter field, `undefined` otherwise; `resolveSkillStates()` — enforcement point 1 |
-| `src/skills/skill-memory.ts`                    | `seedCatalogSkillMemories()` — enforcement point 2                                                                                                                        |
+| `src/memory/graph/capability-seed.ts`           | `seedSkillGraphNodes()` — enforcement point 2                                                                                                                             |
 | `src/tools/skills/load.ts`                      | `executeSkillLoad()` — enforcement points 3 and 5                                                                                                                         |
 | `src/daemon/conversation-skill-tools.ts`        | `projectSkillTools()` — enforcement point 4                                                                                                                               |
 | `src/config/schema.ts`                          | `AssistantConfig` Zod schema definition (feature flag values are no longer stored here)                                                                                   |
@@ -868,12 +868,12 @@ The session loop implements a deterministic overflow convergence pipeline that r
 
 The reducer (`context-overflow-reducer.ts`) applies four monotonically more aggressive tiers, each idempotent:
 
-| Tier                      | Reduction                                                                  | Effect                                                                                       |
-| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| 1. Forced compaction      | Emergency `maybeCompact()` with `force: true`, `minKeepRecentUserTurns: 0` | Summarizes older history more aggressively than normal compaction                            |
-| 2. Tool-result truncation | `truncateToolResultsAcrossHistory()` at 4,000 chars per result             | Shrinks verbose tool outputs (shell, file reads) across all retained messages                |
-| 3. Media/file stubbing    | `stripMediaPayloadsForRetry()`                                             | Replaces image and file content blocks with lightweight text stubs                           |
-| 4. Injection downgrade    | Sets `injectionMode` to `"minimal"`                                        | Drops runtime injections (workspace listing, temporal context, memory recall) to minimal set |
+| Tier                      | Reduction                                                                  | Effect                                                                                                                                                                     |
+| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1. Forced compaction      | Emergency `maybeCompact()` with `force: true`, `minKeepRecentUserTurns: 0` | Summarizes older history more aggressively than normal compaction                                                                                                          |
+| 2. Tool-result truncation | `truncateToolResultsAcrossHistory()` at 4,000 chars per result             | Shrinks verbose tool outputs (shell, file reads) across all retained messages                                                                                              |
+| 3. Media/file stubbing    | `stripMediaPayloadsForRetry()`                                             | Replaces image and file content blocks with lightweight text stubs; media in the latest user message is retained based on available token budget rather than a fixed count |
+| 4. Injection downgrade    | Sets `injectionMode` to `"minimal"`                                        | Drops runtime injections (workspace listing, temporal context, memory recall) to minimal set                                                                               |
 
 After each tier, the reducer re-estimates tokens. If the estimate is within budget, the loop breaks and the provider call proceeds. The loop is bounded by `maxAttempts` (default 3).
 
@@ -2025,3 +2025,56 @@ The guardian trust system uses a three-valued `TrustClass` — `'guardian'`, `'t
 | `src/runtime/channel-retry-sweep.ts`          | Strict `trustClass` parser for retry sweep            |
 | `src/memory/channel-verification-sessions.ts` | `GuardianBinding` with required `guardianPrincipalId` |
 | `src/__tests__/trust-context-guards.test.ts`  | Guard tests enforcing trust-context type invariants   |
+
+### Managed Profiler Runtime
+
+Managed cloud assistants use Bun's built-in CPU and heap profiling to capture runtime performance data. The profiler subsystem consists of a persistent on-disk run store, a retention/pruning sweep, and HTTP routes for remote management.
+
+**Bun profiler flags:** Managed containers activate profiling by setting `VELLUM_PROFILER_MODE` (e.g. `cpu`, `heap`, `cpu+heap`) and `VELLUM_PROFILER_RUN_ID` environment variables before boot. Bun writes profiler artifacts (`.cpuprofile`, `.heapsnapshot`, markdown summaries) into the run directory.
+
+**Directory contract:**
+
+```
+<workspace>/data/profiler/
+  runs/
+    <runId>/
+      manifest.json          — run metadata (status, timestamps, byte count)
+      profile.cpuprofile     — Bun CPU profile output
+      profile-summary.md     — Bun-generated markdown summary
+      *.heapsnapshot          — Bun heap profile output (when heap mode active)
+```
+
+Each profiler run lives in its own sub-directory under `<workspace>/data/profiler/runs/<runId>/`. A `manifest.json` in each run directory records metadata: status (`active` or `completed`), creation/update timestamps, and total byte count. The active run (identified by `VELLUM_PROFILER_RUN_ID`) is never pruned.
+
+**Retention budgets:** On daemon startup and after explicit cleanup operations, the profiler sweep enforces three budgets:
+
+| Budget                                | Env var                       | Default |
+| ------------------------------------- | ----------------------------- | ------- |
+| Max total bytes across all runs       | `VELLUM_PROFILER_MAX_BYTES`   | 500 MB  |
+| Max number of completed runs retained | `VELLUM_PROFILER_MAX_RUNS`    | 10      |
+| Minimum free disk space               | `VELLUM_PROFILER_MIN_FREE_MB` | 200 MB  |
+
+Completed runs are pruned oldest-first until all budgets are satisfied. The active run is never deleted, even if it alone exceeds the byte budget.
+
+**Runtime HTTP endpoints (gateway-only, `internal.write` scope):**
+
+| Method   | Endpoint                          | Description                                                                      |
+| -------- | --------------------------------- | -------------------------------------------------------------------------------- |
+| `GET`    | `/v1/profiler/runs`               | List all profiler runs with manifest metadata, sorted newest-first               |
+| `GET`    | `/v1/profiler/runs/:runId`        | Detail view: manifest metadata, Bun markdown summary, active/retention state     |
+| `POST`   | `/v1/profiler/runs/:runId/export` | Package a single run directory as a tar.gz bundle (same size cap as log exports) |
+| `DELETE` | `/v1/profiler/runs/:runId`        | Delete a completed run; rejects active run deletion; recalculates disk budget    |
+
+These endpoints allow the platform (via vembda proxy) to enumerate, inspect, export, and clean up profiler runs without opening a shell on the assistant pod.
+
+**Key files:**
+
+| File                                       | Purpose                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| `src/daemon/profiler-run-store.ts`         | Manifest management, rescan, retention sweep                             |
+| `src/runtime/routes/profiler-routes.ts`    | HTTP route handlers for profiler run management                          |
+| `src/runtime/routes/archive-utils.ts`      | Shared tar.gz creation and size-cap utilities                            |
+| `src/config/env-registry.ts`               | Profiler env var accessors (`getProfilerRunId`, `getProfilerMode`, etc.) |
+| `src/util/platform.ts`                     | Profiler directory path helpers                                          |
+| `src/__tests__/profiler-run-store.test.ts` | Profiler store unit tests                                                |
+| `src/__tests__/profiler-routes.test.ts`    | Profiler HTTP route tests                                                |

package/Dockerfile

@@ -12,8 +12,8 @@ RUN apt-get update && apt-get install -y \
     g++ \
     && rm -rf /var/lib/apt/lists/*
 
-# Install bun
-RUN curl -fsSL https://bun.sh/install | bash
+# Install bun (pinned version)
+RUN curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
 ENV PATH="/root/.bun/bin:${PATH}"
 
 # Copy shared packages needed by assistant's repo-local dependencies
@@ -25,9 +25,6 @@ COPY packages/egress-proxy ./packages/egress-proxy
 COPY assistant/package.json assistant/bun.lock ./assistant/
 RUN cd /app/assistant && bun install --frozen-lockfile
 
-# Copy meta files needed by assistant (provider-env-vars.json)
-COPY meta/provider-env-vars.json ./meta/provider-env-vars.json
-
 # Copy source
 COPY assistant ./assistant
 

package/bun.lock

@@ -55,6 +55,10 @@
       },
     },
   },
+  "overrides": {
+    "lodash": "^4.18.0",
+    "path-to-regexp": "^8.4.0",
+  },
   "packages": {
     "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.16.1", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-1ad+Sc/0sCtZGHthxxvgEUo5Wsbw16I+aF+YwdiLnPwkZG8KAGUEAPK6LM6Pf69lCyJPt1Aomk1d+8oE3C4ZEw=="],
 
@@ -748,7 +752,7 @@
 
     "locate-path": ["locate-path@6.0.0", "", { "dependencies": { "p-locate": "^5.0.0" } }, "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw=="],
 
-    "lodash": ["lodash@4.17.23", "", {}, "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w=="],
+    "lodash": ["lodash@4.18.1", "", {}, "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q=="],
 
     "long": ["long@5.3.2", "", {}, "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA=="],
 
@@ -828,7 +832,7 @@
 
     "path-scurry": ["path-scurry@1.11.1", "", { "dependencies": { "lru-cache": "^10.2.0", "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" } }, "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA=="],
 
-    "path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
+    "path-to-regexp": ["path-to-regexp@8.4.2", "", {}, "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA=="],
 
     "pg-int8": ["pg-int8@1.0.1", "", {}, "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw=="],
 

package/docker-entrypoint.sh

@@ -6,4 +6,35 @@ if [ "$(id -u)" = "0" ] && [ "${VELLUM_WORKSPACE_DIR:-}" = "/workspace" ] && [ -
   git config --global --add safe.directory '/workspace/*' >/dev/null 2>&1 || true
 fi
 
-exec bun run src/daemon/main.ts
+# ── Bun profiler bootstrap ──────────────────────────────────────────────
+# When VELLUM_PROFILER_RUN_ID and VELLUM_PROFILER_MODE are set, prepare the
+# run directory on the workspace volume and append the appropriate Bun
+# profiler flags to BUN_OPTIONS. Bun's native --cpu-prof / --heap-prof
+# flags write Chrome-compatible .cpuprofile and .heapsnapshot artifacts.
+BUN_OPTIONS="${BUN_OPTIONS:-}"
+
+if [ -n "${VELLUM_PROFILER_RUN_ID:-}" ] && [ -n "${VELLUM_PROFILER_MODE:-}" ]; then
+  PROFILER_WORKSPACE="${VELLUM_WORKSPACE_DIR:-$HOME/.vellum/workspace}"
+  PROFILER_RUN_DIR="${PROFILER_WORKSPACE}/data/profiler/runs/${VELLUM_PROFILER_RUN_ID}"
+
+  # Ensure the run directory exists
+  mkdir -p "${PROFILER_RUN_DIR}"
+
+  case "${VELLUM_PROFILER_MODE}" in
+    cpu)
+      BUN_OPTIONS="${BUN_OPTIONS} --cpu-prof --cpu-prof-md --cpu-prof-dir=${PROFILER_RUN_DIR}"
+      ;;
+    heap)
+      BUN_OPTIONS="${BUN_OPTIONS} --heap-prof --heap-prof-md --heap-prof-dir=${PROFILER_RUN_DIR}"
+      ;;
+    cpu+heap|heap+cpu)
+      BUN_OPTIONS="${BUN_OPTIONS} --cpu-prof --cpu-prof-md --cpu-prof-dir=${PROFILER_RUN_DIR} --heap-prof --heap-prof-md --heap-prof-dir=${PROFILER_RUN_DIR}"
+      ;;
+    *)
+      echo "Warning: unknown VELLUM_PROFILER_MODE '${VELLUM_PROFILER_MODE}', skipping profiler flags" >&2
+      ;;
+  esac
+fi
+
+# shellcheck disable=SC2086
+exec bun --smol ${BUN_OPTIONS} run src/daemon/main.ts

package/docs/architecture/integrations.md

@@ -532,7 +532,7 @@ Each conversation is projected to a directory named `{isoDate}_{id}`:
 
 The disk view is updated at the daemon level, not automatically by the DB CRUD layer. Conversation creation, metadata updates, and deletion are synced from `conversation-crud.ts`, but message sync (`syncMessageToDisk`) is only called from daemon-level code paths (e.g. `conversation-messaging.ts`) — not from the CRUD `addMessage()` function. This means `messages.jsonl` reflects messages processed through the daemon's messaging pipeline, not every message write. All disk writes are best-effort; failures are logged but never thrown, so the disk view cannot break DB operations.
 
-> **Privacy note:** Conversation disk-view files live under `~/.vellum/workspace/conversations/` and are **excluded** from diagnostic log exports ("Send logs to Vellum") via the `WORKSPACE_SKIP_DIRS` filter in `log-export-routes.ts`. However, the SQLite database (`assistant.db`) is included in exports as a SQL dump, and it contains conversation messages and attachment data in its tables. The disk-view exclusion prevents the raw conversation files and decoded attachments from being exported, but conversation content stored in the database may still be present in the export.
+> **Privacy note:** Conversation disk-view files live under `~/.vellum/workspace/conversations/`. Workspace files are not included in diagnostic log exports ("Send logs to Vellum"). For conversation-scoped exports, conversation data is included as structured JSON tables (e.g. `messages.json`, `llm-request-logs.json`), not as a raw database dump.
 
 ```mermaid
 sequenceDiagram

package/docs/architecture/memory.md

@@ -501,9 +501,9 @@ This ensures that file writes, bash commands, host operations, and other mutatin
 
 ---
 
-## Workspace Context Injection — Runtime-Only Directory Awareness
+## Workspace Context Injection — Directory Awareness
 
-The session injects a workspace top-level directory listing into every user message at runtime, giving the model awareness of the sandbox filesystem structure without persisting it in conversation history.
+The session injects a `<workspace>` directory listing into the first user message and after compaction, giving the model awareness of the sandbox filesystem structure. The block persists in conversation history (old-format `<workspace_top_level>` blocks from pre-change history are stripped for backward compatibility).
 
 ### Lifecycle
 
@@ -516,7 +516,6 @@ graph TB
         CACHE["Cache rendered text<br/>workspaceTopLevelDirty = false"]
         INJECT["applyRuntimeInjections<br/>prepend workspace block<br/>to user message"]
         AGENT["AgentLoop.run(runMessages)"]
-        STRIP["stripWorkspaceTopLevelContext<br/>remove block from persisted history"]
     end
 
     subgraph "Dirty Triggers (tool_result handler)"
@@ -532,7 +531,6 @@ graph TB
     RENDER --> CACHE
     CACHE --> INJECT
     INJECT --> AGENT
-    AGENT --> STRIP
 
     FILE_EDIT --> DIRTY
     FILE_WRITE --> DIRTY
@@ -544,7 +542,7 @@ graph TB
 - **Scope**: Sandbox workspace only (`~/.vellum/workspace`). Non-recursive — only top-level directories.
 - **Bounded**: Maximum 120 directory entries (`MAX_TOP_LEVEL_ENTRIES`). Excess is truncated with a note.
 - **Prepend, not append**: The workspace block is prepended to the user message content so that Anthropic cache breakpoints continue to land on the trailing user text block, preserving prompt cache efficiency.
-- **Runtime-only**: The injected `<workspace_top_level>` block is stripped from `this.messages` after the agent loop completes. It never persists in conversation history or the database.
+- **Persists in history**: The injected `<workspace>` block persists in conversation history, giving the model workspace grounding across turns. Legacy `<workspace_top_level>` blocks from pre-change history are stripped for backward compatibility.
 - **Dirty-refresh**: The scanner runs once on the first turn, then only re-runs after a successful mutation tool (`file_edit`, `file_write`, `bash`). Failed tool results do not trigger a refresh.
 - **Injection ordering**: Workspace context is injected after other runtime injections (active surface, etc.) via `applyRuntimeInjections`, but because it is **prepended** to content blocks, it appears first in the final message.
 
@@ -557,50 +555,49 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 | File                                                    | Role                                                                                                                                       |
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
 | `assistant/src/workspace/top-level-scanner.ts`          | Synchronous directory scanner with `MAX_TOP_LEVEL_ENTRIES` cap                                                                             |
-| `assistant/src/workspace/top-level-renderer.ts`         | Renders `TopLevelSnapshot` to `<workspace_top_level>` XML block                                                                            |
-| `assistant/src/daemon/conversation-runtime-assembly.ts` | Runtime injections and strip helpers (`<workspace_top_level>`, `<temporal_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`) |
+| `assistant/src/workspace/top-level-renderer.ts`         | Renders `TopLevelSnapshot` to `<workspace>` XML block                                                                                      |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | Runtime injections and legacy-block strip helpers (`<workspace>`, `<turn_context>`, `<channel_onboarding_playbook>`, `<onboarding_mode>`)  |
 | `assistant/src/onboarding/onboarding-orchestrator.ts`   | Builds assistant-owned onboarding runtime guidance from channel playbook + transport metadata                                              |
-| `assistant/src/daemon/conversation-agent-loop.ts`       | Agent loop orchestration, runtime injection wiring, strip chain                                                                            |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Agent loop orchestration, runtime injection wiring, legacy-block strip chain                                                               |
 
 ---
 
-## Temporal Context Injection — Date Grounding
+## Turn Context Injection — Date & Actor Grounding
 
-The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, current local time, current UTC time, and timezone source metadata. This enables reliable reasoning about dates and times without persisting volatile temporal data in conversation history.
+The session injects a unified `<turn_context>` block into every user message, giving the model awareness of the current timestamp (with timezone), interface, channel, and actor identity. This replaces the former separate `<temporal_context>`, `<inbound_actor_context>`, and per-channel turn context blocks. The unified block persists in conversation history so the assistant retains temporal and actor grounding across turns. Legacy blocks from pre-change history are stripped for backward compatibility.
+
+The `timestamp:` field format is: `2026-04-02 (Wed) 14:30:00 -05:00 (America/Chicago)` — date, abbreviated weekday, local time, UTC offset, and IANA timezone name.
 
 ### Per-turn flow
 
 ```mermaid
 graph TB
     subgraph "Per-Turn Flow"
-        BUILD["buildTemporalContext(timeZone, hostTimeZone, userTimeZone)<br/>→ compact XML block"]
-        INJECT["applyRuntimeInjections<br/>prepend temporal block<br/>to user message"]
+        BUILD["buildUnifiedTurnContextBlock()<br/>→ unified XML block with timestamp,<br/>actor context, channel context"]
+        INJECT["applyRuntimeInjections<br/>prepend turn_context block<br/>to user message"]
         AGENT["AgentLoop.run(runMessages)"]
-        STRIP["stripTemporalContext<br/>remove block from persisted history"]
     end
 
     BUILD --> INJECT
     INJECT --> AGENT
-    AGENT --> STRIP
 ```
 
 ### Key design decisions
 
-- **Fresh each turn**: `buildTemporalContext()` is called at the start of every agent loop invocation, ensuring the model always sees the current date even in long-running conversations.
+- **Fresh each turn**: `buildUnifiedTurnContextBlock()` is called at the start of every agent loop invocation, ensuring the model always sees the current timestamp even in long-running conversations.
 - **Clock source invariant**: Absolute time (`now`) always comes from the assistant host clock (`Date.now()`), never from channel/client clocks.
-- **Timezone precedence**: If `ui.userTimezone` is configured, temporal context uses it for local-date interpretation. Otherwise it falls back to memory-stored timezone, then assistant host timezone.
+- **Timezone precedence**: If `ui.userTimezone` is configured, turn context uses it for local-date interpretation. Otherwise it falls back to memory-stored timezone, then assistant host timezone.
 - **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic and timezone validation/canonicalization.
-- **Runtime-only**: The injected `<temporal_context>` block is stripped from `this.messages` after the agent loop completes via `stripTemporalContext`. It never persists in conversation history.
-- **Specific strip prefix**: The strip function matches the exact injected prefix (`<temporal_context>\nToday:`) to avoid accidentally removing user-authored text that starts with `<temporal_context>`.
-- **Retry paths**: Temporal context is included in all three `applyRuntimeInjections` call sites (main path, compact retry, media-trim retry).
+- **Persists in history**: The `<turn_context>` block persists in conversation history. Legacy `<temporal_context>`, `<inbound_actor_context>`, and separate channel context blocks from pre-change history are stripped for backward compatibility.
+- **Retry paths**: Turn context is included in all `applyRuntimeInjections` call sites (main path, compact retry, media-trim retry).
 
 ### Key files
 
-| File                                                    | Role                                                                                    |
-| ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `assistant/src/daemon/date-context.ts`                  | `buildTemporalContext()` — generates the `<temporal_context>` XML block                 |
-| `assistant/src/daemon/conversation-runtime-assembly.ts` | `injectTemporalContext()` / `stripTemporalContext()` helpers                            |
-| `assistant/src/daemon/conversation-agent-loop.ts`       | Wiring: computes temporal context, passes to `applyRuntimeInjections`, strips after run |
+| File                                                    | Role                                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/daemon/date-context.ts`                  | `formatTurnTimestamp()` — generates the timestamp string used in `<turn_context>`                             |
+| `assistant/src/daemon/conversation-runtime-assembly.ts` | `buildUnifiedTurnContextBlock()` — constructs the unified `<turn_context>` block; legacy block strip helpers  |
+| `assistant/src/daemon/conversation-agent-loop.ts`       | Wiring: builds turn context, passes to `applyRuntimeInjections`                                               |
 
 ---
 

package/knip.json

@@ -5,7 +5,8 @@
     "scripts/**/*.ts",
     "src/daemon/main.ts",
     "src/messaging/providers/*/types.ts",
-    "src/messaging/providers/*/client.ts"
+    "src/messaging/providers/*/client.ts",
+    "src/memory/graph/inspect.ts"
   ],
   "project": ["src/**/*.ts", "src/**/*.tsx", "scripts/**/*.ts"],
   "ignoreDependencies": [