@vellumai/assistant 0.5.0 → 0.5.2

package/ARCHITECTURE.md

@@ -783,26 +783,26 @@ All client-server communication uses HTTP for request/response operations and Se
 
 The daemon emits two distinct error message types via SSE:
 
-| Message type         | Scope               | Purpose                                                                                                        | Payload                                                                       |
-| -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `conversation_error` | Conversation-scoped | Typed, actionable failures during conversation runtime (e.g., provider network error, rate limit, API failure) | `sessionId`, `code` (typed enum), `userMessage`, `retryable`, `debugDetails?` |
-| `error`              | Global              | Generic, non-session failures (e.g., daemon startup errors, unknown message types)                             | `message` (string)                                                            |
-
-**Design rationale:** `conversation_error` carries structured metadata (error code, retryable flag, debug details) so the client can present actionable UI — a toast with retry/dismiss buttons — rather than a generic error banner. The older `error` type is retained for backward compatibility with non-session contexts.
-
-### Session Error Codes
-
-| Code                        | Meaning                                                                 | Retryable |
-| --------------------------- | ----------------------------------------------------------------------- | --------- |
-| `PROVIDER_NETWORK`          | Unable to reach the LLM provider (connection refused, timeout, DNS)     | Yes       |
-| `PROVIDER_RATE_LIMIT`       | LLM provider rate-limited the request (HTTP 429)                        | Yes       |
-| `PROVIDER_API`              | Provider returned a server error (5xx) or retryable 4xx                 | Yes       |
-| `PROVIDER_BILLING`          | Invalid/expired API key or insufficient credits (HTTP 401, billing 4xx) | No        |
-| `CONTEXT_TOO_LARGE`         | Request exceeds the model's context window (HTTP 413, token limit)      | No        |
-| `SESSION_ABORTED`           | Non-user abort interrupted the request                                  | Yes       |
-| `SESSION_PROCESSING_FAILED` | Catch-all for unexpected processing failures                            | No        |
-| `REGENERATE_FAILED`         | Failed to regenerate a previous response                                | Yes       |
-| `UNKNOWN`                   | Unrecognized error that does not match any specific category            | No        |
+| Message type         | Scope               | Purpose                                                                                                        | Payload                                                                            |
+| -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `conversation_error` | Conversation-scoped | Typed, actionable failures during conversation runtime (e.g., provider network error, rate limit, API failure) | `conversationId`, `code` (typed enum), `userMessage`, `retryable`, `debugDetails?` |
+| `error`              | Global              | Generic, non-conversation failures (e.g., daemon startup errors, unknown message types)                        | `message` (string)                                                                 |
+
+**Design rationale:** `conversation_error` carries structured metadata (error code, retryable flag, debug details) so the client can present actionable UI — a toast with retry/dismiss buttons — rather than a generic error banner. The older `error` type is retained for backward compatibility with non-conversation contexts.
+
+### Conversation Error Codes
+
+| Code                             | Meaning                                                                 | Retryable |
+| -------------------------------- | ----------------------------------------------------------------------- | --------- |
+| `PROVIDER_NETWORK`               | Unable to reach the LLM provider (connection refused, timeout, DNS)     | Yes       |
+| `PROVIDER_RATE_LIMIT`            | LLM provider rate-limited the request (HTTP 429)                        | Yes       |
+| `PROVIDER_API`                   | Provider returned a server error (5xx) or retryable 4xx                 | Yes       |
+| `PROVIDER_BILLING`               | Invalid/expired API key or insufficient credits (HTTP 401, billing 4xx) | No        |
+| `CONTEXT_TOO_LARGE`              | Request exceeds the model's context window (HTTP 413, token limit)      | No        |
+| `CONVERSATION_ABORTED`           | Non-user abort interrupted the request                                  | Yes       |
+| `CONVERSATION_PROCESSING_FAILED` | Catch-all for unexpected processing failures                            | No        |
+| `REGENERATE_FAILED`              | Failed to regenerate a previous response                                | Yes       |
+| `UNKNOWN`                        | Unrecognized error that does not match any specific category            | No        |
 
 ### Error Classification
 
@@ -826,7 +826,7 @@ sequenceDiagram
 
     Note over Daemon: LLM call fails or<br/>processing error occurs
     Daemon->>Daemon: classifyConversationError(error, ctx)
-    Daemon->>DC: conversation_error {sessionId, code,<br/>userMessage, retryable, debugDetails?}
+    Daemon->>DC: conversation_error {conversationId, code,<br/>userMessage, retryable, debugDetails?}
     DC->>DC: broadcast to all subscribers
     DC->>VM: subscribe() stream delivers message
     VM->>VM: set conversationError property<br/>clear isThinking / isCancelling
@@ -837,7 +837,7 @@ sequenceDiagram
     alt User taps Retry (retryable == true)
         UI->>VM: retryAfterConversationError()
         VM->>VM: dismissConversationError()<br/>+ regenerateLastMessage()
-        VM->>DC: regenerate {sessionId}
+        VM->>DC: regenerate {conversationId}
         DC->>Daemon: HTTP POST /v1/messages
     else User taps Dismiss
         UI->>VM: dismissConversationError()
@@ -939,7 +939,7 @@ graph TB
     end
 
     SUBMIT --> SLASH_CHECK
-    SLASH_CHECK -->|"Yes (/model, /status, etc.)"| QA_ROUTE
+    SLASH_CHECK -->|"Yes (/models, /status, etc.)"| QA_ROUTE
     SLASH_CHECK -->|"No"| VOICE_CHECK
     VOICE_CHECK -->|"Yes"| QA_ROUTE
     VOICE_CHECK -->|"No"| CLASSIFIER
@@ -1017,12 +1017,12 @@ graph TB
 
     INPUT --> RESOLVE
     RESOLVE -->|"kind: passthrough"| PASSTHROUGH
-    RESOLVE -->|"kind: unknown<br/>(/model, /status, /commands, /pair,<br/>/models, provider shortcuts)"| HANDLED
+    RESOLVE -->|"kind: unknown<br/>(/models, /status, /commands, /pair)"| HANDLED
 ```
 
 Key behaviors:
 
-- **Built-in commands**: `/model`, `/models`, `/status`, `/commands`, `/pair`, and provider shortcuts (`/opus`, `/sonnet`, `/gpt4`, etc.) are handled directly by `resolveSlash()`. A deterministic `assistant_text_delta` + `message_complete` is emitted. No message persistence or model call occurs.
+- **Built-in commands**: `/models`, `/status`, `/commands`, and `/pair` are handled directly by `resolveSlash()`. A deterministic `assistant_text_delta` + `message_complete` is emitted. No message persistence or model call occurs.
 - **Passthrough**: Any input that does not match a built-in command passes through to the normal agent loop, including slash-like tokens that are not recognized.
 - **Queue**: Queued messages receive the same slash resolution.
 
@@ -1183,7 +1183,7 @@ The following capabilities ship as bundled skills in `assistant/src/config/bundl
 | `claude-code`   | Claude Code tool                                                                                                                                                                                                                                                  | Delegate coding tasks to Claude Code subprocess                                                                                                                                                                                                                                                      |
 | `computer-use`  | `computer_use_observe`, `computer_use_click`, `computer_use_type_text`, `computer_use_key`, `computer_use_scroll`, `computer_use_drag`, `computer_use_wait`, `computer_use_open_app`, `computer_use_run_applescript`, `computer_use_done`, `computer_use_respond` | Computer-use proxy tools — preactivated via `preactivatedSkillIds` in desktop sessions. Each tool forwards actions to the connected macOS client via `HostCuProxy`, which handles request/resolve proxying, step counting, loop detection, and observation formatting within the unified agent loop. |
 | `weather`       | `get-weather`                                                                                                                                                                                                                                                     | Fetch current weather data                                                                                                                                                                                                                                                                           |
-| `app-builder`   | `app_create`, `app_list`, `app_query`, `app_update`, `app_delete`, `app_file_list`, `app_file_read`, `app_file_edit`, `app_file_write`                                                                                                                            | Dynamic app authoring — CRUD and file-level editing for persistent apps (activated via `skill_load app-builder`; `app_open` remains a core proxy tool)                                                                                                                                               |
+| `app-builder`   | `app_create`, `app_delete`, `app_refresh`, `app_generate_icon`                                                                                                                                                                                                    | Dynamic app authoring — create and manage persistent apps; file editing uses generic file tools plus `app_refresh` (activated via `skill_load app-builder`; `app_open` remains a core proxy tool)                                                                                                    |
 | `self-upgrade`  | (instruction-only)                                                                                                                                                                                                                                                | Self-improvement workflow                                                                                                                                                                                                                                                                            |
 | `start-the-day` | (instruction-only)                                                                                                                                                                                                                                                | Morning briefing routine                                                                                                                                                                                                                                                                             |
 
@@ -1525,7 +1525,7 @@ sequenceDiagram
 
 ### Key design decisions
 
-- **Recursion guard**: A module-level `Set<sessionId>` prevents concurrent swarms within the same session while allowing independent sessions to run their own swarms in parallel.
+- **Recursion guard**: A module-level `Set<conversationId>` prevents concurrent swarms within the same conversation while allowing independent conversations to run their own swarms in parallel.
 - **Abort signal**: The tool checks `context.signal?.aborted` before planning and before execution. The signal is also forwarded into `executeSwarm` and the worker backend, enabling cooperative cancellation of in-flight workers.
 - **DAG scheduling**: Tasks with dependencies are topologically ordered. Independent tasks run in parallel up to `maxWorkers`.
 - **Per-task retries**: Failed tasks retry up to `maxRetriesPerTask` before being marked failed. Dependents are transitively blocked.
@@ -1568,7 +1568,7 @@ sequenceDiagram
 
     Note over Daemon: Processing previous request...<br/>Reaches safe tool-loop checkpoint
 
-    Daemon-->>DC: generation_handoff (sessionId, queuedCount)
+    Daemon-->>DC: generation_handoff (conversationId, queuedCount)
     Note over Daemon: Daemon yields current generation
 
     Daemon-->>DC: message_dequeued
@@ -1585,7 +1585,7 @@ sequenceDiagram
 
 ## Trace System — Debug Panel Data Flow
 
-The trace system provides real-time observability of daemon session internals. Each session creates a `TraceEmitter` that emits structured `trace_event` SSE events as the session processes requests, makes LLM calls, and executes tools.
+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
@@ -1636,41 +1636,41 @@ sequenceDiagram
     TE-->>DC: trace_event (message_complete)
     DC-->>TS: ingest()
 
-    Note over TS: Events deduplicated by eventId,<br/>ordered by sequence + timestampMs,<br/>grouped by session and requestId,<br/>capped at 5000 per session
+    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 eventsBySession
+    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 session lifecycle:
-
-| Kind                        | Emitted by         | When                                                                                            |
-| --------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
-| `request_received`          | Handlers / Session | User message or surface action arrives                                                          |
-| `request_queued`            | Handlers / Session | Message queued while session is busy                                                            |
-| `request_dequeued`          | Session            | Queued message begins processing                                                                |
-| `llm_call_started`          | Session            | LLM API call initiated                                                                          |
-| `llm_call_finished`         | Session            | LLM API call completed (carries `inputTokens`, `outputTokens`, `latencyMs`)                     |
-| `assistant_message`         | Session            | 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`)                                                    |
-| `secret_detected`           | ToolTraceListener  | Secret found in tool output                                                                     |
-| `generation_handoff`        | Session            | Yielding to next queued message                                                                 |
-| `message_complete`          | Session            | Full request processing finished                                                                |
-| `generation_cancelled`      | Session            | User cancelled the generation                                                                   |
-| `request_error`             | Handlers / Session | Unrecoverable error during processing (includes queue-full rejection and persist-failure paths) |
+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`)                                                    |
+| `secret_detected`           | ToolTraceListener       | Secret found in tool output                                                                     |
+| `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-session): Constructed with a `sessionId` 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 session's `EventBus` via `onAny()` and translates tool domain events (`tool.execution.started`, `tool.execution.finished`, `tool.execution.failed`, `tool.permission.requested`, `tool.permission.decided`, `tool.secret.detected`) into trace events through the `TraceEmitter`.
+- **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`, `tool.secret.detected`) 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 session and requestId, and enforces a retention cap of 5,000 events per session. 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).
+- **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.
 
 ---

package/docs/architecture/integrations.md

@@ -1,6 +1,6 @@
 # Integrations Architecture
 
-OAuth, messaging adapters, script proxy, and asset-tool architecture.
+OAuth, messaging adapters, script proxy, and conversation disk view architecture.
 
 ## Integrations — OAuth2 + Unified Messaging
 
@@ -514,90 +514,85 @@ The proxy subsystem is fully wired, including credential injection. The session
 
 ---
 
-## Asset Search and Materialize — Cross-Conversation Media Reuse
+## Conversation Disk View — Filesystem-Based Conversation Access
 
-The `asset_search` and `asset_materialize` tools enable the assistant to discover and use previously uploaded media assets (images, documents, audio) across conversations. Assets are stored as base64-encoded blobs in the `attachments` table and linked to messages via the `message_attachments` join table.
+The conversation disk view projects conversation metadata, messages, and attachments to a browsable filesystem layout under `~/.vellum/workspace/conversations/`. This enables the assistant to search, read, and manipulate conversation data (including media attachments) using standard file tools (`read_file`, `glob`, `grep`) rather than dedicated asset search tools.
 
-### Asset Discovery and Materialization Flow
+### Directory Layout
 
-```mermaid
-sequenceDiagram
-    participant Model as LLM
-    participant Search as asset_search tool
-    participant DB as SQLite (attachments)
-    participant Visibility as media-visibility-policy
-    participant Materialize as asset_materialize tool
-    participant Sandbox as Sandbox filesystem
-
-    Model->>Search: search(mime_type: "image/*", recency: "last_7_days")
-    Search->>DB: query attachments (filters)
-    DB-->>Search: matching rows (metadata only, no base64)
-    Search->>Visibility: filterVisibleAttachments(results, currentContext)
-    Note over Visibility: Private-conversation attachments filtered out<br/>unless viewer is in the same conversation
-    Visibility-->>Search: visible results
-    Search-->>Model: metadata list (IDs, filenames, types, sizes)
-
-    Model->>Materialize: materialize(attachment_id, destination_path)
-    Materialize->>Materialize: sandboxPolicy(destination_path)
-    Materialize->>DB: load attachment (including base64 data)
-    Materialize->>Visibility: isAttachmentVisible(attachmentCtx, currentCtx)
-    Note over Visibility: Second visibility check at materialize time<br/>prevents TOCTOU between search and materialize
-    Materialize->>Materialize: size check (max 100 MB)
-    Materialize->>Sandbox: write decoded bytes to destination
-    Materialize-->>Model: "Materialized 'photo.jpg' to /workspace/media/photo.jpg"
-```
+Each conversation is projected to a directory named `{isoDate}_{id}`:
 
-### Private Conversation Visibility Gate
+```
+~/.vellum/workspace/conversations/
+  2025-01-15T10-30-00.000Z_abc123/
+    meta.json             # Conversation metadata (id, title, type, channel, timestamps)
+    messages.jsonl        # Flattened message log (one JSON object per line)
+    attachments/          # Decoded attachment files (original filenames, collision-safe)
+      photo.png
+      document.pdf
+```
 
-Attachments from private conversations are only visible to the same private conversation. Standard-conversation attachments are visible everywhere. The policy is enforced at both the search and materialize stages to prevent cross-conversation data leakage.
+### Write-Through Sync
 
-```mermaid
-graph TB
-    subgraph "Visibility Rules"
-        ATT_STD["Attachment from<br/>standard conversation"]
-        ATT_PVT["Attachment from<br/>private conversation"]
+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.
 
-        VIEWER_ANY["Any conversation<br/>(standard or private)"]
-        VIEWER_SAME["Same private conversation<br/>(matching conversationId)"]
-        VIEWER_OTHER["Different private conversation<br/>or standard conversation"]
-    end
+> **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.
 
-    ATT_STD -->|"always visible"| VIEWER_ANY
-    ATT_PVT -->|"visible"| VIEWER_SAME
-    ATT_PVT -->|"hidden"| VIEWER_OTHER
+```mermaid
+sequenceDiagram
+    participant CRUD as conversation-crud.ts
+    participant Daemon as conversation-messaging.ts
+    participant DiskView as conversation-disk-view.ts
+    participant FS as Filesystem
+
+    Note over CRUD,FS: Conversation creation (CRUD layer)
+    CRUD->>CRUD: INSERT conversation row
+    CRUD->>DiskView: initConversationDir(conv)
+    DiskView->>FS: mkdir + write meta.json
+
+    Note over Daemon,FS: Message insertion (daemon layer)
+    Daemon->>CRUD: addMessage(convId, role, content)
+    CRUD->>CRUD: INSERT message row
+    Daemon->>DiskView: syncMessageToDisk(convId, msgId, createdAtMs)
+    DiskView->>DiskView: flattenContentBlocks(content)
+    DiskView->>FS: append JSONL record to messages.jsonl
+    DiskView->>FS: reference files already materialized in attachments/
+
+    Note over CRUD,FS: Conversation update (CRUD layer)
+    CRUD->>CRUD: UPDATE conversation row
+    CRUD->>DiskView: updateMetaFile(conv)
+    DiskView->>FS: rewrite meta.json
+
+    Note over CRUD,FS: Conversation deletion (CRUD layer)
+    CRUD->>CRUD: DELETE conversation row
+    CRUD->>DiskView: removeConversationDir(id, createdAtMs)
+    DiskView->>FS: rm -rf conversation directory
 ```
 
-**Source conversation lookup**: The `getAttachmentSourceConversations()` function traces an attachment's lineage through `message_attachments` -> `messages` -> `conversations` to determine which conversations it belongs to and whether any of them are private.
+### Content Flattening
 
-**Mixed-source attachments**: If an attachment is linked to messages in both standard and private conversations (e.g., the user shared the same file in two conversations), the attachment is treated as globally visible because at least one source is non-private.
+Message content (stored as JSON `ContentBlock[]` in the DB) is flattened for the JSONL log:
 
-**Orphan attachments**: Attachments with no message linkage (orphans) are treated as universally visible rather than hidden, since they have no private-conversation provenance.
+- **Text blocks** are concatenated into a single `content` string.
+- **Tool use blocks** are extracted into a `toolCalls` array (`{ name, input }`).
+- **Tool result blocks** are extracted into a `toolResults` array.
+- **Image/file blocks** are skipped — they are represented via the `attachments/` subdirectory instead.
 
-### Search Capabilities
+### Attachment Projection
 
-| Parameter         | Type   | Description                                                                                    |
-| ----------------- | ------ | ---------------------------------------------------------------------------------------------- |
-| `mime_type`       | string | MIME type filter with wildcard support (`image/*`, `application/pdf`)                          |
-| `filename`        | string | Case-insensitive substring match on original filename                                          |
-| `recency`         | enum   | Time-based filter: `last_hour`, `last_24_hours`, `last_7_days`, `last_30_days`, `last_90_days` |
-| `conversation_id` | string | Scope results to attachments in a specific conversation                                        |
-| `limit`           | number | Maximum results (default 20, max 100)                                                          |
+Attachments are materialized into `conversations/<conversation>/attachments/` as soon as they are linked to a message. During disk-view sync, the JSONL record reuses those filenames directly and only falls back to materializing legacy rows that have not been projected yet. Filename collisions are still resolved by appending a numeric suffix (e.g., `photo-2.png`, `photo-3.png`).
 
-### Materialize Safeguards
+### Backfill Migration
 
-- **Sandbox path enforcement**: Destination path must resolve inside the sandbox working directory
-- **Size limit**: 100 MB ceiling prevents materializing excessively large attachments
-- **Double visibility check**: Both `asset_search` and `asset_materialize` independently verify visibility, preventing TOCTOU races between search and use
-- **Risk level**: Both tools are `RiskLevel.Low` since they read existing data and write only within the sandbox
+Existing conversations created before the disk view was introduced are backfilled by workspace migration `009-backfill-conversation-disk-view`, which replays all conversations and their messages through the disk-view sync functions.
 
 ### Key Source Files
 
-| File                                              | Role                                                                                          |
-| ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `assistant/src/tools/assets/search.ts`            | `asset_search` tool — cross-conversation attachment metadata search with visibility filtering |
-| `assistant/src/tools/assets/materialize.ts`       | `asset_materialize` tool — decode and write attachment to sandbox path                        |
-| `assistant/src/daemon/media-visibility-policy.ts` | Pure policy module — `isAttachmentVisible()`, `filterVisibleAttachments()`                    |
-| `assistant/src/memory/schema.ts`                  | `attachments` and `message_attachments` table schemas                                         |
-| `assistant/src/memory/conversation-crud.ts`       | `getConversationType()` — conversation type lookup for visibility context                     |
+| File                                                                        | Role                                                                                  |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `assistant/src/memory/conversation-disk-view.ts`                            | Disk view module — init, update, sync, remove, content flattening                     |
+| `assistant/src/memory/conversation-crud.ts`                                 | DB CRUD layer — calls init, update, and remove disk-view functions (not message sync) |
+| `assistant/src/daemon/conversation-messaging.ts`                            | Daemon messaging pipeline — calls `syncMessageToDisk` after message insertion         |
+| `assistant/src/workspace/migrations/009-backfill-conversation-disk-view.ts` | Backfill migration for pre-existing conversations                                     |
 
 ---

package/docs/credential-execution-service.md

@@ -46,7 +46,7 @@ CES exposes exactly three tools to the assistant, registered as a **deliberate e
 
 ### Tool registration
 
-CES tools use the standard `class ... implements Tool` registration pattern. This is explicitly approved as a deliberate exception to the no-new-tools policy because:
+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
@@ -223,7 +223,7 @@ 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. **CES tools are the only approved exception to the no-new-tools policy** for credential-bearing execution. 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.
@@ -400,5 +400,5 @@ The following capabilities are intentionally deferred beyond v1:
 
 - [Security architecture](architecture/security.md) — existing credential broker and permission model
 - [AGENTS.md](../../AGENTS.md) — tooling direction and CES exception
-- [Tools AGENTS.md](../src/tools/AGENTS.md) — no-new-tools policy and CES exception
+- [Tools AGENTS.md](../src/tools/AGENTS.md) — tooling direction and CES exception
 - [Network traffic matrix](../../../vellum-assistant-platform/docs/network-traffic-matrix.md) — managed pod network policies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/__tests__/agent-loop.test.ts

@@ -1629,4 +1629,115 @@ describe("AgentLoop", () => {
     );
     expect(textBlock!.text).toBe("Normal response with no placeholders.");
   });
+
+  // Tool error retry nudge — when a tool returns isError: true, the loop
+  // should inject a system_notice nudging the LLM to retry instead of ending.
+  test("injects retry nudge system_notice when tool returns an error", async () => {
+    const { provider, calls } = createMockProvider([
+      // First turn: LLM calls a tool that errors
+      toolUseResponse("t1", "read_file", { path: "/missing.txt" }),
+      // Second turn: LLM retries after seeing the error + nudge
+      toolUseResponse("t2", "read_file", { path: "/existing.txt" }),
+      // Third turn: LLM responds with success
+      textResponse("Got the file."),
+    ]);
+
+    let callCount = 0;
+    const toolExecutor = async (
+      _name: string,
+      _input: Record<string, unknown>,
+    ) => {
+      callCount++;
+      if (callCount === 1) {
+        return {
+          content:
+            '{"error":"name is required and must be a non-empty string"}',
+          isError: true,
+        };
+      }
+      return { content: "file contents", isError: false };
+    };
+
+    const loop = new AgentLoop(
+      provider,
+      "system",
+      {},
+      dummyTools,
+      toolExecutor,
+    );
+    await loop.run([userMessage], () => {});
+
+    // Provider should have been called 3 times (error -> retry -> final text)
+    expect(calls).toHaveLength(3);
+
+    // The second call's messages should contain the retry nudge system_notice
+    const secondCallMessages = calls[1].messages;
+    const toolResultMessage = secondCallMessages[secondCallMessages.length - 1];
+    expect(toolResultMessage.role).toBe("user");
+
+    const retryNudge = toolResultMessage.content.find(
+      (b): b is Extract<ContentBlock, { type: "text" }> =>
+        b.type === "text" && b.text.includes("looks recoverable"),
+    );
+    expect(retryNudge).toBeDefined();
+
+    // The third call should NOT have the retry nudge (successful tool result)
+    const thirdCallMessages = calls[2].messages;
+    const thirdToolResultMessage =
+      thirdCallMessages[thirdCallMessages.length - 1];
+    const noRetryNudge = thirdToolResultMessage.content.find(
+      (b): b is Extract<ContentBlock, { type: "text" }> =>
+        b.type === "text" && b.text.includes("looks recoverable"),
+    );
+    expect(noRetryNudge).toBeUndefined();
+  });
+
+  // Retry nudge stops after MAX_CONSECUTIVE_ERROR_NUDGES (3) consecutive errors
+  test("stops injecting retry nudge after 3 consecutive error turns", async () => {
+    const { provider, calls } = createMockProvider([
+      // 4 consecutive error turns, then final text
+      toolUseResponse("t1", "read_file", { path: "/a" }),
+      toolUseResponse("t2", "read_file", { path: "/b" }),
+      toolUseResponse("t3", "read_file", { path: "/c" }),
+      toolUseResponse("t4", "read_file", { path: "/d" }),
+      textResponse("Giving up."),
+    ]);
+
+    const toolExecutor = async (
+      _name: string,
+      _input: Record<string, unknown>,
+    ) => {
+      return { content: "service unavailable", isError: true };
+    };
+
+    const loop = new AgentLoop(
+      provider,
+      "system",
+      {},
+      dummyTools,
+      toolExecutor,
+    );
+    await loop.run([userMessage], () => {});
+
+    expect(calls).toHaveLength(5);
+
+    // Helper to check if a call's last user message has the retry nudge
+    const hasRetryNudge = (callIndex: number): boolean => {
+      const msgs = calls[callIndex].messages;
+      const lastMsg = msgs[msgs.length - 1];
+      return lastMsg.content.some(
+        (b) =>
+          b.type === "text" &&
+          "text" in b &&
+          (b as { text: string }).text.includes("looks recoverable"),
+      );
+    };
+
+    // Turns 1-3 should have the nudge
+    expect(hasRetryNudge(1)).toBe(true);
+    expect(hasRetryNudge(2)).toBe(true);
+    expect(hasRetryNudge(3)).toBe(true);
+    // Turn 4 should NOT have the nudge (exceeded limit)
+    expect(hasRetryNudge(4)).toBe(false);
+  });
 });

package/src/__tests__/always-loaded-tools-guard.test.ts

@@ -2,8 +2,8 @@
  * Guard test: always-loaded tool count
  *
  * This test asserts the exact set of tools that are active when no client is
- * connected, no host proxy is available, no attachments are present, and no
- * special channel capabilities exist. This represents the minimal "always-loaded"
+ * connected, no host proxy is available, and no special channel capabilities
+ * exist. This represents the minimal "always-loaded"
  * baseline that is sent to the LLM on every turn.
  *
  * Adding a tool to this set increases token cost for every request. If this test
@@ -32,14 +32,13 @@ describe("always-loaded tool count", () => {
     await initializeTools();
     const allDefs = buildToolDefinitions();
 
-    // Minimal context: no client, no attachments, no capabilities
+    // Minimal context: no client, no capabilities
     const minimalContext: SkillProjectionContext = {
       skillProjectionState: new Map(),
       skillProjectionCache: {},
       coreToolNames: new Set(),
       toolsDisabledDepth: 0,
       hasNoClient: true,
-      hasAttachments: false,
       channelCapabilities: undefined,
     };