@vellumai/assistant 0.3.15 → 0.3.18

package/docs/architecture/memory.md

@@ -366,14 +366,14 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 ## Temporal Context Injection — Date Grounding
 
-The session injects a `<temporal_context>` block into every user message at runtime, giving the model awareness of the current date, timezone, upcoming weekend/work week windows, and a 14-day horizon of labelled future dates. This enables reliable reasoning about future dates (e.g. "plan a trip for next weekend") without persisting volatile temporal data in conversation history.
+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, timezone source metadata, upcoming weekend/work week windows, and a 14-day horizon of labelled future dates. This enables reliable reasoning about future dates (e.g. "plan a trip for next weekend") without persisting volatile temporal data in conversation history.
 
 ### Per-turn flow
 
 ```mermaid
 graph TB
     subgraph "Per-Turn Flow"
-        BUILD["buildTemporalContext(timeZone)<br/>→ compact XML block"]
+        BUILD["buildTemporalContext(timeZone, hostTimeZone, userTimeZone)<br/>→ compact XML block"]
         INJECT["applyRuntimeInjections<br/>prepend temporal block<br/>to user message"]
         AGENT["AgentLoop.run(runMessages)"]
         STRIP["stripTemporalContext<br/>remove block from persisted history"]
@@ -387,7 +387,9 @@ graph TB
 ### 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.
-- **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic. The host timezone (`Intl.DateTimeFormat().resolvedOptions().timeZone`) is used by default.
+- **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 dynamic profile memory, then assistant host timezone.
+- **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic and timezone validation/canonicalization.
 - **Bounded output**: Hard-capped at 1500 characters and 14 horizon entries to prevent prompt bloat.
 - **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>`.
@@ -512,4 +514,3 @@ graph TB
 | `assistant/src/config/schema.ts` | `WorkspaceGitConfigSchema`: timeout, backoff, and enrichment queue configuration |
 
 ---
-

package/docs/architecture/scheduling.md

@@ -91,7 +91,7 @@ The `enforceRoutingIntent()` step runs after the LLM produces a channel selectio
 | Intent | Enforcement Rule |
 |--------|-----------------|
 | `single_channel` | No override. The LLM's channel selection stands. |
-| `multi_channel` | If the LLM selected < 2 channels and 2+ are connected, expand to all connected channels. |
+| `multi_channel` | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels. |
 | `all_channels` | Replace the LLM's selection with all connected channels. |
 
 When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
@@ -189,9 +189,9 @@ graph TD
 
 **Data tables:** `watchers` (config, watermark, status, error tracking) and `watcher_events` (detected events, dedup on `(watcher_id, external_id)`, disposition tracking).
 
-## Task Queue — Queued Task Execution and Review
+## Task Queue — Conversation-Managed Task Execution
 
-The Task Queue builds on top of the existing Tasks system to provide an ordered execution pipeline with human-in-the-loop review.
+The Task Queue provides an ordered execution pipeline with human-in-the-loop review. Task management happens entirely through conversation — the user creates, updates, runs, and reviews tasks by talking to the assistant. There is no standalone Tasks UI window.
 
 ### Terminology
 
@@ -258,19 +258,6 @@ flowchart TD
         DB[(SQLite)]
     end
 
-    subgraph "Daemon IPC Handlers"
-        HC[handleWorkItemCreate]
-        HU[handleWorkItemUpdate]
-        HCo[handleWorkItemComplete]
-        HR[handleWorkItemRunTask]
-        BC[tasks_changed broadcast]
-    end
-
-    subgraph "macOS Client"
-        TW[TasksWindowView]
-        DC[DaemonClient]
-    end
-
     TLA -->|"if_exists check"| DUPE
     DUPE -->|"no match"| WIS
     DUPE -->|"match found → reuse/update"| TLU
@@ -278,81 +265,10 @@ flowchart TD
     RWI --> WIS
     TLS --> WIS
     WIS --> DB
-
-    HC --> WIS
-    HU --> WIS
-    HCo --> WIS
-    HR --> WIS
-    HC --> BC
-    HU --> BC
-    HCo --> BC
-    HR --> BC
-
-    BC -->|"via socket"| DC
-    DC -->|"onTasksChanged"| TW
-    TW -->|"debounced refetch (300ms)"| DC
 ```
 
 **Key behaviors:**
 
+- **Conversation-first management** — All task operations (create, update, run, review, delete) are performed through natural language conversation with the assistant, which invokes the model tools (`task_list_add`, `task_list_update`, `task_list_show`) on the user's behalf.
 - **`task_list_update`** uses `resolveWorkItem` to find the target work item by work item ID, task ID, or title (case-insensitive exact match). When multiple items match by task ID or title, the resolver applies a deterministic tie-break (lowest priority tier, then earliest `createdAt`).
 - **`task_list_add`** has duplicate prevention via the `if_exists` parameter (default: `reuse_existing`). Before creating, it calls `findActiveWorkItemsByTitle` to check for active items with the same title. If a match is found, the tool either returns the existing item (`reuse_existing`), updates it in place (`update_existing`), or proceeds to create a duplicate (`create_duplicate`).
-- **All daemon work-item handlers** (`handleWorkItemCreate`, `handleWorkItemUpdate`, `handleWorkItemComplete`, `handleWorkItemRunTask`) emit a `tasks_changed` broadcast after mutations via `ctx.broadcast({ type: 'tasks_changed' })`. They also emit the more specific `work_item_status_changed` with the affected item's current state.
-- **The macOS Tasks window** (`TasksWindowView`) subscribes to both `tasks_changed` and `work_item_status_changed` callbacks on `DaemonClient`. Both trigger a debounced refetch (300ms) so rapid successive mutations coalesce into a single re-fetch.
-
-### IPC Messages
-
-**Client → Server:**
-
-| Message | Purpose |
-|---------|---------|
-| `work_items_list` | List work items, filterable by status |
-| `work_item_get` | Fetch a single work item with full details |
-| `work_item_create` | Create a new work item pointing to a Task |
-| `work_item_update` | Update title, notes, priority, or sort order |
-| `work_item_complete` | Mark an item as `done` after review |
-| `work_item_run_task` | Trigger execution of a queued work item |
-| `work_item_delete` | Delete a work item from the queue |
-
-**Server → Client (push):**
-
-| Message | Purpose |
-|---------|---------|
-| `work_item_status_changed` | Notify the client when a work item transitions state (includes item snapshot) |
-| `tasks_changed` | Lightweight broadcast after any work-item mutation; triggers client-side refetch |
-
-### Run-Button State Machine
-
-When the user clicks "Run" on a queued work item, the button follows a deterministic state machine:
-
-```
-idle (visible) → in-flight (hidden) → success/failure → re-enabled (via refetch)
-```
-
-**Sequence:**
-
-1. **Idle** — The run button is visible only when `item.status == "queued"`. The `TasksWindowRow` renders it conditionally based on the `WorkItemStatus` enum.
-2. **In-flight** — The client sends `work_item_run_task` with the work item ID. The daemon validates the request, sets the item's status to `running`, and returns `work_item_run_task_response` with `success: true`. It then broadcasts `work_item_status_changed` and `tasks_changed`. The client's debounced refetch picks up the `running` status, which hides the run button and shows a spinner in the status column.
-3. **Completion** — The daemon executes the task asynchronously. On success, the item transitions to `awaiting_review`; on failure, to `failed`. Both trigger another `work_item_status_changed` + `tasks_changed` broadcast, which the client refetches and renders accordingly (showing a "Reviewed" button for `awaiting_review`, or the run button again for `failed` to allow retry).
-
-**Error handling in `work_item_run_task_response`:**
-
-The response includes a typed `errorCode` field (`WorkItemRunTaskErrorCode`) so the client can deterministically decide what to do without parsing error strings:
-
-| `errorCode` | Meaning | Client behavior |
-|-------------|---------|-----------------|
-| `not_found` | Work item does not exist (deleted concurrently) | Refetch removes the stale row |
-| `already_running` | Item is already executing | No-op; status column already shows spinner |
-| `invalid_status` | Item is `done` or `archived` and cannot be run | Refetch updates the row to reflect terminal status |
-| `no_task` | The associated Task template was deleted | Refetch; row may show an error state |
-
-In all error cases, the subsequent `tasks_changed` broadcast triggers a refetch that brings the UI back to a consistent state, so the button is never stuck in a disabled/hidden state without a path to recovery.
-
-### Delete Flow
-
-Deletion uses optimistic UI with rollback:
-
-1. **Optimistic removal** — `TasksWindowViewModel.removeTask()` snapshots the current `items` array, then immediately removes the target item with animation.
-2. **IPC request** — Sends `work_item_delete` with the item ID. The daemon looks up the item; if found, deletes it and responds with `work_item_delete_response { success: true }`, then broadcasts `tasks_changed`.
-3. **Failure rollback** — If the send throws (socket error), the view model restores the snapshot with animation. If the daemon responds with `success: false` (item not found), the `onWorkItemDeleteResponse` callback triggers a full refetch to reconcile.
-

package/docs/runbook-trusted-contacts.md

@@ -0,0 +1,283 @@
+# Trusted Contacts — Operator Runbook
+
+Operational procedures for inspecting, managing, and debugging the trusted contact access flow. All HTTP commands use the gateway API (default `http://localhost:7830`) with bearer authentication.
+
+## Prerequisites
+
+```bash
+# Read the bearer token
+TOKEN=$(cat ~/.vellum/http-token)
+
+# Base URL (adjust if using a non-default port)
+BASE=http://localhost:7830
+```
+
+## 1. Inspect Trusted Contacts (Members)
+
+### List all active trusted contacts
+
+```bash
+curl -s "$BASE/v1/ingress/members?status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+### Filter by channel
+
+```bash
+# Telegram contacts only
+curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+
+# SMS contacts only
+curl -s "$BASE/v1/ingress/members?sourceChannel=sms&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+### List all members (including revoked and blocked)
+
+```bash
+curl -s "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" | jq
+```
+
+Response shape:
+```json
+{
+  "ok": true,
+  "members": [
+    {
+      "id": "uuid",
+      "sourceChannel": "telegram",
+      "externalUserId": "123456789",
+      "externalChatId": "123456789",
+      "displayName": "Alice",
+      "username": "alice_handle",
+      "status": "active",
+      "policy": "allow",
+      "lastSeenAt": 1700000000000,
+      "createdAt": 1699000000000
+    }
+  ]
+}
+```
+
+## 2. Inspect Pending Access Requests
+
+Access requests are stored in the `channel_guardian_approval_requests` table. Use SQLite to inspect pending requests directly.
+
+### Via SQLite CLI
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, requester_external_user_id, requester_chat_id, \
+   guardian_external_user_id, status, tool_name, created_at, expires_at \
+   FROM channel_guardian_approval_requests \
+   WHERE tool_name = 'ingress_access_request' AND status = 'pending' \
+   ORDER BY created_at DESC;"
+```
+
+### Check all access requests (including resolved)
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, requester_external_user_id, status, \
+   decided_by_external_user_id, created_at \
+   FROM channel_guardian_approval_requests \
+   WHERE tool_name = 'ingress_access_request' \
+   ORDER BY created_at DESC LIMIT 20;"
+```
+
+## 3. Inspect Pending Verification Sessions
+
+Verification challenges are stored in `channel_guardian_verification_challenges`. Active sessions have `status = 'awaiting_response'` and `expires_at > now`.
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, status, identity_binding_status, \
+   expected_external_user_id, expected_chat_id, expected_phone_e164, \
+   expires_at, created_at \
+   FROM channel_guardian_verification_challenges \
+   WHERE status IN ('awaiting_response', 'pending_bootstrap') \
+   AND expires_at > $(date +%s)000 \
+   ORDER BY created_at DESC;"
+```
+
+## 4. Force-Revoke a Trusted Contact
+
+### Via HTTP API
+
+First, find the member's `id` from the list endpoint, then revoke:
+
+```bash
+# Find the member
+MEMBER_ID=$(curl -s "$BASE/v1/ingress/members?sourceChannel=telegram&status=active" \
+  -H "Authorization: Bearer $TOKEN" | jq -r '.members[] | select(.externalUserId == "TARGET_USER_ID") | .id')
+
+# Revoke with reason
+curl -s -X DELETE "$BASE/v1/ingress/members/$MEMBER_ID" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "Revoked by operator"}' | jq
+```
+
+### Block a member (stronger than revoke)
+
+Blocking prevents the member from re-entering the flow without explicit unblocking.
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members/$MEMBER_ID/block" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "Blocked by operator"}' | jq
+```
+
+### Via SQLite (emergency)
+
+If the HTTP API is unavailable:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "UPDATE assistant_ingress_members \
+   SET status = 'revoked', revoked_reason = 'Emergency operator revocation', \
+   updated_at = $(date +%s)000 \
+   WHERE external_user_id = 'TARGET_USER_ID' AND source_channel = 'telegram';"
+```
+
+## 5. Debug Verification Failures
+
+### Check rate limit state
+
+If a user is getting "invalid or expired code" errors, they may be rate-limited:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT * FROM channel_guardian_rate_limits \
+   WHERE external_user_id = 'TARGET_USER_ID' \
+   OR chat_id = 'TARGET_CHAT_ID' \
+   ORDER BY created_at DESC LIMIT 5;"
+```
+
+### Reset rate limits for a user
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "DELETE FROM channel_guardian_rate_limits \
+   WHERE external_user_id = 'TARGET_USER_ID' AND channel = 'telegram';"
+```
+
+### Check verification challenge state
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT id, channel, status, identity_binding_status, \
+   expected_external_user_id, expected_chat_id, expected_phone_e164, \
+   expires_at, consumed_by_external_user_id \
+   FROM channel_guardian_verification_challenges \
+   WHERE expected_external_user_id = 'TARGET_USER_ID' \
+   OR expected_chat_id = 'TARGET_CHAT_ID' \
+   ORDER BY created_at DESC LIMIT 5;"
+```
+
+### Common verification failure causes
+
+| Symptom | Likely cause | Resolution |
+|---------|-------------|------------|
+| "Invalid or expired code" (correct code) | Identity mismatch: the code was entered from a different user/chat than expected | Verify the requester is using the same account that originally requested access |
+| "Invalid or expired code" (correct code, correct user) | Rate-limited (5+ failures in 15 min window) | Wait 30 minutes or reset rate limits via SQLite |
+| "Invalid or expired code" (old code) | Code TTL expired (10 min) | Guardian must re-approve to generate a new code |
+| Code never delivered to guardian | `deliverChannelReply` failed | Check daemon logs for "Failed to deliver verification code to guardian" |
+| No notification to guardian | No guardian binding for channel | Verify guardian is bound: check `channel_guardian_bindings` table |
+
+## 6. Check Notification Delivery Status
+
+### Check if the access request notification was delivered
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT ne.id, ne.source_event_name, ne.dedupe_key, ne.created_at, \
+   nd.channel, nd.status, nd.confidence \
+   FROM notification_events ne \
+   LEFT JOIN notification_decisions nd ON nd.event_id = ne.id \
+   WHERE ne.source_event_name LIKE 'ingress.%' \
+   ORDER BY ne.created_at DESC LIMIT 20;"
+```
+
+### Check delivery records
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT ndel.id, ndel.channel, ndel.status, ndel.error_message, \
+   ndel.created_at, ne.source_event_name \
+   FROM notification_deliveries ndel \
+   JOIN notification_events ne ON ne.id = ndel.event_id \
+   WHERE ne.source_event_name LIKE 'ingress.%' \
+   ORDER BY ndel.created_at DESC LIMIT 20;"
+```
+
+### Check lifecycle signals
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "SELECT source_event_name, source_channel, dedupe_key, created_at \
+   FROM notification_events \
+   WHERE source_event_name LIKE 'ingress.trusted_contact.%' \
+   ORDER BY created_at DESC LIMIT 20;"
+```
+
+## 7. Manually Add a Trusted Contact (Bypass Verification)
+
+If the verification flow cannot be completed, an operator can directly create an active member:
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceChannel": "telegram",
+    "externalUserId": "123456789",
+    "externalChatId": "123456789",
+    "displayName": "Alice",
+    "policy": "allow",
+    "status": "active"
+  }' | jq
+```
+
+For SMS contacts, use the E.164 phone number as the external user/chat ID:
+
+```bash
+curl -s -X POST "$BASE/v1/ingress/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceChannel": "sms",
+    "externalUserId": "+15551234567",
+    "externalChatId": "+15551234567",
+    "displayName": "Bob",
+    "policy": "allow",
+    "status": "active"
+  }' | jq
+```
+
+## 8. Clean Up Expired Data
+
+### Purge expired verification sessions
+
+Expired sessions are already invisible to the verification flow (filtered by `expires_at`), but you can clean them up:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "DELETE FROM channel_guardian_verification_challenges \
+   WHERE expires_at < $(date +%s)000 \
+   AND status IN ('awaiting_response', 'pending_bootstrap');"
+```
+
+### Purge expired approval requests
+
+The `sweepExpiredGuardianApprovals()` timer handles this automatically every 60 seconds, but manual cleanup:
+
+```bash
+sqlite3 ~/.vellum/workspace/data/db/assistant.db \
+  "UPDATE channel_guardian_approval_requests \
+   SET status = 'expired' \
+   WHERE status = 'pending' AND expires_at < $(date +%s)000;"
+```