@vellumai/assistant 0.4.42 → 0.4.44

package/docs/runbook-trusted-contacts.md

@@ -13,10 +13,9 @@ Operational procedures for inspecting, managing, and debugging the trusted conta
 # Base URL — assistant runtime (adjust if using a non-default port)
 BASE=http://localhost:7821
 
-# Bearer token: if running via the assistant's shell tools, $GATEWAY_AUTH_TOKEN
-# is injected automatically. For manual operator use, mint a token via the CLI
-# or use one from the daemon (e.g. from a recent shell env export).
-TOKEN=$GATEWAY_AUTH_TOKEN
+# Bearer token: for operator use, retrieve from the daemon process environment
+# or use `assistant` CLI commands which handle auth automatically.
+TOKEN=<your-bearer-token>
 ```
 
 ## 1. Inspect Trusted Contacts
@@ -35,8 +34,8 @@ curl -s "$BASE/v1/contacts?role=contact" \
 curl -s "$BASE/v1/contacts?channelType=telegram" \
   -H "Authorization: Bearer $TOKEN" | jq
 
-# SMS contacts only
-curl -s "$BASE/v1/contacts?channelType=sms" \
+# Voice contacts only
+curl -s "$BASE/v1/contacts?channelType=phone" \
   -H "Authorization: Bearer $TOKEN" | jq
 ```
 
@@ -117,14 +116,14 @@ sqlite3 ~/.vellum/workspace/data/db/assistant.db \
 
 ## 3. Inspect Pending Verification Sessions
 
-Verification challenges are stored in `channel_guardian_verification_challenges`. Active sessions have `status = 'awaiting_response'` and `expires_at > now`.
+Verification challenges are stored in `channel_verification_sessions`. 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 \
+   FROM channel_verification_sessions \
    WHERE status IN ('awaiting_response', 'pending_bootstrap') \
    AND expires_at > $(date +%s)000 \
    ORDER BY created_at DESC;"
@@ -200,7 +199,7 @@ 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 \
+   FROM channel_verification_sessions \
    WHERE expected_external_user_id = 'TARGET_USER_ID' \
    OR expected_chat_id = 'TARGET_CHAT_ID' \
    ORDER BY created_at DESC LIMIT 5;"
@@ -274,7 +273,7 @@ curl -s -X POST "$BASE/v1/contacts" \
   }' | jq
 ```
 
-For SMS contacts, use the E.164 phone number as the address and external user/chat ID:
+For voice contacts, use the E.164 phone number as the address and external user/chat ID:
 
 ```bash
 curl -s -X POST "$BASE/v1/contacts" \
@@ -284,7 +283,7 @@ curl -s -X POST "$BASE/v1/contacts" \
     "displayName": "Bob",
     "role": "contact",
     "channels": [{
-      "type": "sms",
+      "type": "phone",
       "address": "+15551234567",
       "externalUserId": "+15551234567",
       "externalChatId": "+15551234567",
@@ -302,7 +301,7 @@ Expired sessions are already invisible to the verification flow (filtered by `ex
 
 ```bash
 sqlite3 ~/.vellum/workspace/data/db/assistant.db \
-  "DELETE FROM channel_guardian_verification_challenges \
+  "DELETE FROM channel_verification_sessions \
    WHERE expires_at < $(date +%s)000 \
    AND status IN ('awaiting_response', 'pending_bootstrap');"
 ```

package/docs/trusted-contact-access.md

@@ -35,7 +35,7 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 5. **Guardian receives the verification code.** The assistant delivers the code to the guardian's verified channel (Telegram chat, SMS, etc.).
 6. **Guardian gives the code to the requester out-of-band** (in person, text message, phone call, etc.). This out-of-band transfer is the trust anchor: it proves the requester has a real-world relationship with the guardian.
 7. **Requester enters the code** back to the assistant on the same channel. The inbound message handler intercepts bare 6-digit codes when a pending verification session exists for that channel.
-8. **Assistant verifies the code and activates the user.** `validateAndConsumeChallenge()` hashes the code, matches it against the pending session, verifies identity binding (the code must come from the expected channel identity), consumes the challenge, and calls `upsertContactChannel()` with `status: 'active'` and `policy: 'allow'`.
+8. **Assistant verifies the code and activates the user.** `validateAndConsumeVerification()` hashes the code, matches it against the pending session, verifies identity binding (the code must come from the expected channel identity), consumes the session, and calls `upsertContactChannel()` with `status: 'active'` and `policy: 'allow'`.
 9. **All subsequent messages are accepted normally.** The ingress ACL finds an active member record and allows the message through.
 
 ## Lifecycle States
@@ -44,18 +44,18 @@ Design doc defining how unknown users gain access to a Vellum assistant via chan
 requested -> pending_guardian -> verification_pending -> active | denied | expired
 ```
 
-| State                  | Description                                                                                                        | Store representation                                                                                                                                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `requested`            | Unknown user messaged the assistant and was rejected. The system records the access attempt.                       | No member record exists. The rejection is logged in `channel_inbound_events`. A notification signal is emitted via `emitNotificationSignal()`.                                                              |
-| `pending_guardian`     | The guardian has been notified and a decision is pending.                                                          | A `channel_guardian_approval_requests` record exists with `status: 'pending'`, `toolName: 'ingress_access_request'`.                                                                                        |
-| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter.    | `channel_guardian_verification_challenges` record with `status: 'awaiting_response'`, identity-bound to the requester's expected channel identity. The approval request is updated to `status: 'approved'`. |
-| `active`               | The requester entered the correct code. They are now a trusted contact.                                            | `contact_channels` record with `status: 'active'`, `policy: 'allow'`. The verification session is `status: 'consumed'`.                                                                                     |
-| `denied`               | The guardian explicitly denied the request.                                                                        | The approval request has `status: 'denied'`. No member record is created (or if one existed, it remains unchanged).                                                                                         |
-| `expired`              | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Approval request: `status: 'expired'` (set by `sweepExpiredGuardianApprovals()`). Verification session: expires naturally when `expiresAt < Date.now()`.                                                    |
+| State                  | Description                                                                                                        | Store representation                                                                                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `requested`            | Unknown user messaged the assistant and was rejected. The system records the access attempt.                       | No member record exists. The rejection is logged in `channel_inbound_events`. A notification signal is emitted via `emitNotificationSignal()`.                                                   |
+| `pending_guardian`     | The guardian has been notified and a decision is pending.                                                          | A `channel_guardian_approval_requests` record exists with `status: 'pending'`, `toolName: 'ingress_access_request'`.                                                                             |
+| `verification_pending` | The guardian approved. A verification session is active with a 6-digit code waiting for the requester to enter.    | `channel_verification_sessions` record with `status: 'awaiting_response'`, identity-bound to the requester's expected channel identity. The approval request is updated to `status: 'approved'`. |
+| `active`               | The requester entered the correct code. They are now a trusted contact.                                            | `contact_channels` record with `status: 'active'`, `policy: 'allow'`. The verification session is `status: 'consumed'`.                                                                          |
+| `denied`               | The guardian explicitly denied the request.                                                                        | The approval request has `status: 'denied'`. No member record is created (or if one existed, it remains unchanged).                                                                              |
+| `expired`              | The guardian never responded (approval TTL elapsed) or the requester never entered the code (session TTL elapsed). | Approval request: `status: 'expired'` (set by `sweepExpiredGuardianApprovals()`). Verification session: expires naturally when `expiresAt < Date.now()`.                                         |
 
 ## Identity Binding Rules
 
-Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the `channel_guardian_verification_challenges` record when the session is created.
+Identity binding ensures the verification code can only be consumed by the intended recipient on the intended channel. The binding fields are set on the `channel_verification_sessions` record when the session is created.
 
 | Channel  | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                                          |
 | -------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -76,42 +76,42 @@ Identity binding ensures the verification code can only be consumed by the inten
 
 ### Stage: `pending_guardian` (guardian notified, awaiting decision)
 
-| Store                       | Table                                | Record                                                                                                                                                                                                                                                                                   |
-| --------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | `status: 'pending'`, `toolName: 'ingress_access_request'`, `requesterExternalUserId`, `requesterChatId`, `guardianExternalUserId`, `guardianChatId` (resolved from the `contacts`/`contact_channels` tables where `role = 'guardian'`), `expiresAt` (GUARDIAN_APPROVAL_TTL_MS from now). |
-| `notification_events`       | `notification_events`                | Event with `sourceEventName: 'ingress.access_request'`, links to the conversation.                                                                                                                                                                                                       |
-| `notification_decisions`    | `notification_decisions`             | Decision engine output: which channels to notify, confidence, reasoning.                                                                                                                                                                                                                 |
-| `notification_deliveries`   | `notification_deliveries`            | Per-channel delivery records (Telegram, vellum, etc.).                                                                                                                                                                                                                                   |
+| Store                                                        | Table                                | Record                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_guardian_approval_requests` | `status: 'pending'`, `toolName: 'ingress_access_request'`, `requesterExternalUserId`, `requesterChatId`, `guardianExternalUserId`, `guardianChatId` (resolved from the `contacts`/`contact_channels` tables where `role = 'guardian'`), `expiresAt` (GUARDIAN_APPROVAL_TTL_MS from now). |
+| `notification_events`                                        | `notification_events`                | Event with `sourceEventName: 'ingress.access_request'`, links to the conversation.                                                                                                                                                                                                       |
+| `notification_decisions`                                     | `notification_decisions`             | Decision engine output: which channels to notify, confidence, reasoning.                                                                                                                                                                                                                 |
+| `notification_deliveries`                                    | `notification_deliveries`            | Per-channel delivery records (Telegram, vellum, etc.).                                                                                                                                                                                                                                   |
 
 ### Stage: `verification_pending` (guardian approved, code issued)
 
-| Store                       | Table                                      | Record                                                                                                                                                                                                                                                                              |
-| --------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests`       | Updated to `status: 'approved'`, `decidedByExternalUserId` set.                                                                                                                                                                                                                     |
-| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | New record: `status: 'awaiting_response'`, `identityBindingStatus: 'bound'`, `expectedExternalUserId`/`expectedChatId`/`expectedPhoneE164` set to the requester's identity, `challengeHash` = SHA-256 of the 6-digit code, `expiresAt` = 10 minutes from creation, `codeDigits: 6`. |
+| Store                                                        | Table                                | Record                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_guardian_approval_requests` | Updated to `status: 'approved'`, `decidedByExternalUserId` set.                                                                                                                                                                                                                     |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_verification_sessions`      | New record: `status: 'awaiting_response'`, `identityBindingStatus: 'bound'`, `expectedExternalUserId`/`expectedChatId`/`expectedPhoneE164` set to the requester's identity, `challengeHash` = SHA-256 of the 6-digit code, `expiresAt` = 10 minutes from creation, `codeDigits: 6`. |
 
 ### Stage: `active` (code verified, trusted contact created)
 
-| Store                       | Table                                      | Record                                                                                                                                                                                                      |
-| --------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `contacts-write.ts`         | `contacts` / `contact_channels`            | Upserted via `upsertContactChannel()`: creates a contact record and a `contact_channels` entry with `status: 'active'`, `policy: 'allow'`, channel type, `externalUserId`, `externalChatId`, `displayName`. |
-| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set.                                                                                                                        |
-| `channel-guardian-store.ts` | `channel_guardian_rate_limits`             | Reset via `resetRateLimit()` on successful verification.                                                                                                                                                    |
+| Store                                                        | Table                           | Record                                                                                                                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contacts-write.ts`                                          | `contacts` / `contact_channels` | Upserted via `upsertContactChannel()`: creates a contact record and a `contact_channels` entry with `status: 'active'`, `policy: 'allow'`, channel type, `externalUserId`, `externalChatId`, `displayName`. |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_verification_sessions` | Updated to `status: 'consumed'`, `consumedByExternalUserId`, `consumedByChatId` set.                                                                                                                        |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_guardian_rate_limits`  | Reset via `resetRateLimit()` on successful verification.                                                                                                                                                    |
 
 ### Stage: `denied` (guardian rejected)
 
-| Store                       | Table                                | Record                                                        |
-| --------------------------- | ------------------------------------ | ------------------------------------------------------------- |
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests` | Updated to `status: 'denied'`, `decidedByExternalUserId` set. |
+| Store                                                        | Table                                | Record                                                        |
+| ------------------------------------------------------------ | ------------------------------------ | ------------------------------------------------------------- |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_guardian_approval_requests` | Updated to `status: 'denied'`, `decidedByExternalUserId` set. |
 
 No member record is created. No verification session is created.
 
 ### Stage: `expired`
 
-| Store                       | Table                                      | Record                                                                                            |
-| --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `channel-guardian-store.ts` | `channel_guardian_approval_requests`       | Updated to `status: 'expired'` by `sweepExpiredGuardianApprovals()` (runs every 60s).             |
-| `channel-guardian-store.ts` | `channel_guardian_verification_challenges` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingChallengeByHash()`. |
+| Store                                                        | Table                                | Record                                                                                          |
+| ------------------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_guardian_approval_requests` | Updated to `status: 'expired'` by `sweepExpiredGuardianApprovals()` (runs every 60s).           |
+| `guardian-approvals.ts` / `channel-verification-sessions.ts` | `channel_verification_sessions`      | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingSessionByHash()`. |
 
 ### Invites (alternative path)
 
@@ -171,7 +171,7 @@ sequenceDiagram
 
         U->>A: Send "847293" on same channel
         A->>A: parseGuardianVerifyCommand() → bare 6-digit code
-        A->>A: validateAndConsumeChallenge()
+        A->>A: validateAndConsumeVerification()
         A->>A: Identity check: actorId matches expected
         A->>A: Hash matches, not expired → consume
         A->>A: upsertContactChannel(status: 'active', policy: 'allow')
@@ -211,20 +211,20 @@ sequenceDiagram
 ### Verification code expires
 
 - Verification sessions have a 10-minute TTL (`CHALLENGE_TTL_MS`).
-- After expiry, `findPendingChallengeByHash()` filters by `expiresAt > now`, so the code silently becomes invalid.
+- After expiry, `findPendingSessionByHash()` filters by `expiresAt > now`, so the code silently becomes invalid.
 - The requester receives the generic "code is invalid or has expired" message.
 - The guardian can re-initiate the flow by approving again, which creates a new session (auto-revoking any prior pending sessions).
 
 ### Wrong code entered
 
-- `validateAndConsumeChallenge()` hashes the input and looks for a matching challenge. No match returns a generic failure.
+- `validateAndConsumeVerification()` hashes the input and looks for a matching session. No match returns a generic failure.
 - The invalid attempt is recorded via `recordInvalidAttempt()` with a sliding window (`RATE_LIMIT_WINDOW_MS = 15 min`).
 - After `RATE_LIMIT_MAX_ATTEMPTS = 5` failures within the window, the actor is locked out for `RATE_LIMIT_LOCKOUT_MS = 30 min`.
 - The lockout message is identical to the "invalid code" message (anti-oracle).
 
 ### Identity mismatch
 
-- If the code is entered from a different channel identity than expected (e.g., a different Telegram user ID), the identity check in `validateAndConsumeChallenge()` fails.
+- If the code is entered from a different channel identity than expected (e.g., a different Telegram user ID), the identity check in `validateAndConsumeVerification()` fails.
 - The error message is identical to "invalid or expired" to prevent identity oracle attacks.
 - The attempt counts toward the rate limit.
 
@@ -250,9 +250,9 @@ sequenceDiagram
 
 ### Code reuse prevention
 
-- Each verification session creates a single `channel_guardian_verification_challenges` record.
-- `consumeChallenge()` atomically sets `status: 'consumed'`, making the code permanently unusable.
-- `findPendingChallengeByHash()` only matches challenges with `status IN ('pending', 'pending_bootstrap', 'awaiting_response')`, so consumed challenges are invisible.
+- Each verification session creates a single `channel_verification_sessions` record.
+- `consumeSession()` atomically sets `status: 'consumed'`, making the code permanently unusable.
+- `findPendingSessionByHash()` only matches sessions with `status IN ('pending', 'pending_bootstrap', 'awaiting_response')`, so consumed sessions are invisible.
 
 ### Session supersession
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.4.42",
+  "version": "0.4.44",
   "type": "module",
   "bin": {
     "assistant": "./src/index.ts"
@@ -10,13 +10,8 @@
     "daemon:restart:http": "RUNTIME_HTTP_PORT=7821 bun run src/index.ts daemon restart",
     "db:generate": "drizzle-kit generate",
     "db:push": "drizzle-kit push",
-    "ipc:inventory": "bun run scripts/ipc/check-contract-inventory.ts",
-    "ipc:inventory:update": "bun run scripts/ipc/check-contract-inventory.ts --update",
-    "generate:ipc": "bun run scripts/ipc/generate-swift.ts",
-    "check:ipc-generated": "bun run scripts/ipc/generate-swift.ts --check",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "ipc:check-swift-drift": "bun run scripts/ipc/check-swift-decoder-drift.ts",
     "lint": "eslint",
     "typecheck": "bunx tsc --noEmit",
     "test": "bash scripts/test.sh",
@@ -24,12 +19,13 @@
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bash scripts/test.sh",
     "test:bench": "find src/__tests__ -maxdepth 1 -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
     "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
-    "postinstall": "cd .. && git config core.hooksPath .githooks 2>/dev/null || true"
+    "postinstall": "cd .. && git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.42",
     "@anthropic-ai/sdk": "^0.39.0",
     "@google/genai": "^1.40.0",
+    "@hono/node-server": "^1.19.11",
     "@modelcontextprotocol/sdk": "^1.15.1",
     "@qdrant/js-client-rest": "^1.16.2",
     "@sentry/node": "^10.38.0",
@@ -40,6 +36,7 @@
     "dotenv": "^17.3.1",
     "drizzle-orm": "^0.38.4",
     "esbuild": "^0.24.0",
+    "hono": "^4.12.5",
     "ink": "^6.7.0",
     "jszip": "^3.10.1",
     "minimatch": "^10.2.4",
@@ -47,8 +44,8 @@
     "pino": "^9.6.0",
     "pino-pretty": "^13.1.3",
     "playwright": "^1.58.2",
-    "preact": "^10.25.0",
     "postgres": "^3.4.8",
+    "preact": "^10.25.0",
     "qrcode": "^1.5.4",
     "react": "^19.2.4",
     "rrule": "^2.8.1",

package/src/__tests__/access-request-decision.test.ts

@@ -57,12 +57,12 @@ mock.module("../runtime/gateway-client.js", () => ({
   },
 }));
 
+import { getDb, initializeDb, resetDb } from "../memory/db.js";
 import {
   createApprovalRequest,
   getApprovalRequestById,
-} from "../memory/channel-guardian-store.js";
-import { getDb, initializeDb, resetDb } from "../memory/db.js";
-import { findActiveSession } from "../runtime/channel-guardian-service.js";
+} from "../memory/guardian-approvals.js";
+import { findActiveSession } from "../runtime/channel-verification-service.js";
 import {
   deliverVerificationCodeToGuardian,
   handleAccessRequestDecision,
@@ -91,7 +91,7 @@ const GUARDIAN_APPROVAL_TTL_MS = 5 * 60 * 1000;
 function resetState(): void {
   const db = getDb();
   db.run("DELETE FROM channel_guardian_approval_requests");
-  db.run("DELETE FROM channel_guardian_verification_challenges");
+  db.run("DELETE FROM channel_verification_sessions");
   deliverReplyCalls.length = 0;
 }
 

package/src/__tests__/active-skill-tools.test.ts

@@ -1,10 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import type { Message } from "../providers/types.js";
-import {
-  deriveActiveSkillIds,
-  deriveActiveSkills,
-} from "../skills/active-skill-tools.js";
+import { deriveActiveSkills } from "../skills/active-skill-tools.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -37,9 +34,9 @@ function textMsg(role: "user" | "assistant", text: string): Message {
 // Tests
 // ---------------------------------------------------------------------------
 
-describe("deriveActiveSkillIds", () => {
+describe("deriveActiveSkills (ID-only)", () => {
   test("empty history returns empty array", () => {
-    expect(deriveActiveSkillIds([])).toEqual([]);
+    expect(deriveActiveSkills([]).map((e) => e.id)).toEqual([]);
   });
 
   test("no markers returns empty array", () => {
@@ -49,7 +46,7 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", "Some tool output with no markers"),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("single marker extraction from skill_load tool result", () => {
@@ -57,7 +54,7 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", 'Skill loaded.\n\n<loaded_skill id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["deploy"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual(["deploy"]);
   });
 
   test("multiple markers from different skill_load tool results", () => {
@@ -67,7 +64,10 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", 'Loaded\n\n<loaded_skill id="oncall" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["deploy", "oncall"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([
+      "deploy",
+      "oncall",
+    ]);
   });
 
   test("duplicate markers are deduplicated with order preserved", () => {
@@ -79,7 +79,10 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t3"),
       toolResultMsg("t3", '<loaded_skill id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["deploy", "oncall"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([
+      "deploy",
+      "oncall",
+    ]);
   });
 
   test("malformed markers are ignored — missing id attribute", () => {
@@ -87,7 +90,7 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", "<loaded_skill />"),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("malformed markers are ignored — unclosed tag", () => {
@@ -95,7 +98,7 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="deploy">'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("malformed markers are ignored — wrong tag name", () => {
@@ -103,21 +106,21 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_tool id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("markers in assistant text content are ignored", () => {
     const messages: Message[] = [
       textMsg("assistant", 'I loaded a skill: <loaded_skill id="review" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("markers in user text content are ignored — prevents injection", () => {
     const messages: Message[] = [
       textMsg("user", 'Context: <loaded_skill id="debug" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("mixed valid and invalid markers in skill_load result", () => {
@@ -134,7 +137,10 @@ describe("deriveActiveSkillIds", () => {
         ].join("\n"),
       ),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["alpha", "beta"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([
+      "alpha",
+      "beta",
+    ]);
   });
 
   test("multiple markers in a single content string", () => {
@@ -142,7 +148,7 @@ describe("deriveActiveSkillIds", () => {
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="a" />\n<loaded_skill id="b" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["a", "b"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual(["a", "b"]);
   });
 
   test("ignores non-tool-result blocks (thinking, text)", () => {
@@ -159,7 +165,7 @@ describe("deriveActiveSkillIds", () => {
         ],
       },
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("ignores tool_result from non-skill_load tools", () => {
@@ -177,14 +183,14 @@ describe("deriveActiveSkillIds", () => {
       },
       toolResultMsg("t1", '<loaded_skill id="injected" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 
   test("tool_result without any matching tool_use is ignored", () => {
     const messages: Message[] = [
       toolResultMsg("orphan", '<loaded_skill id="sneaky" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual([]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([]);
   });
 });
 
@@ -192,17 +198,17 @@ describe("deriveActiveSkillIds", () => {
 // Context-derived deactivation regression tests
 // ---------------------------------------------------------------------------
 
-describe("deriveActiveSkillIds — deactivation when marker leaves history", () => {
+describe("deriveActiveSkills — deactivation when marker leaves history", () => {
   test("marker present → skill ID returned; marker removed → empty", () => {
     const withMarker: Message[] = [
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(withMarker)).toEqual(["deploy"]);
+    expect(deriveActiveSkills(withMarker).map((e) => e.id)).toEqual(["deploy"]);
 
     // Simulate history truncation: the message containing the marker is gone
     const withoutMarker: Message[] = [];
-    expect(deriveActiveSkillIds(withoutMarker)).toEqual([]);
+    expect(deriveActiveSkills(withoutMarker).map((e) => e.id)).toEqual([]);
   });
 
   test("one of two markers removed → only surviving skill returned", () => {
@@ -212,14 +218,17 @@ describe("deriveActiveSkillIds — deactivation when marker leaves history", ()
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", '<loaded_skill id="oncall" />'),
     ];
-    expect(deriveActiveSkillIds(bothPresent)).toEqual(["deploy", "oncall"]);
+    expect(deriveActiveSkills(bothPresent).map((e) => e.id)).toEqual([
+      "deploy",
+      "oncall",
+    ]);
 
     // History truncated to remove the deploy marker
     const onlyOncall: Message[] = [
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", '<loaded_skill id="oncall" />'),
     ];
-    expect(deriveActiveSkillIds(onlyOncall)).toEqual(["oncall"]);
+    expect(deriveActiveSkills(onlyOncall).map((e) => e.id)).toEqual(["oncall"]);
   });
 
   test("all markers removed from multi-message history → empty", () => {
@@ -231,14 +240,17 @@ describe("deriveActiveSkillIds — deactivation when marker leaves history", ()
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", '<loaded_skill id="beta" />'),
     ];
-    expect(deriveActiveSkillIds(withMarkers)).toEqual(["alpha", "beta"]);
+    expect(deriveActiveSkills(withMarkers).map((e) => e.id)).toEqual([
+      "alpha",
+      "beta",
+    ]);
 
     // History truncated to only keep non-marker messages
     const noMarkers: Message[] = [
       textMsg("user", "Hello"),
       textMsg("assistant", "Done"),
     ];
-    expect(deriveActiveSkillIds(noMarkers)).toEqual([]);
+    expect(deriveActiveSkills(noMarkers).map((e) => e.id)).toEqual([]);
   });
 
   test("marker replaced by different content in same position → skill gone", () => {
@@ -246,14 +258,14 @@ describe("deriveActiveSkillIds — deactivation when marker leaves history", ()
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(original)).toEqual(["deploy"]);
+    expect(deriveActiveSkills(original).map((e) => e.id)).toEqual(["deploy"]);
 
     // Same structure but marker text replaced (e.g. message edited/summarized)
     const replaced: Message[] = [
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", "Deployment complete."),
     ];
-    expect(deriveActiveSkillIds(replaced)).toEqual([]);
+    expect(deriveActiveSkills(replaced).map((e) => e.id)).toEqual([]);
   });
 
   test("derive is stateless — consecutive calls with different histories are independent", () => {
@@ -261,17 +273,17 @@ describe("deriveActiveSkillIds — deactivation when marker leaves history", ()
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="deploy" />'),
     ];
-    expect(deriveActiveSkillIds(history1)).toEqual(["deploy"]);
+    expect(deriveActiveSkills(history1).map((e) => e.id)).toEqual(["deploy"]);
 
     // Calling with a completely different history does not carry over state
     const history2: Message[] = [
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", '<loaded_skill id="oncall" />'),
     ];
-    expect(deriveActiveSkillIds(history2)).toEqual(["oncall"]);
+    expect(deriveActiveSkills(history2).map((e) => e.id)).toEqual(["oncall"]);
 
     // Empty history returns empty, confirming no leaked state
-    expect(deriveActiveSkillIds([])).toEqual([]);
+    expect(deriveActiveSkills([]).map((e) => e.id)).toEqual([]);
   });
 });
 
@@ -392,14 +404,17 @@ describe("deriveActiveSkills", () => {
     expect(deriveActiveSkills(messages)).toEqual([]);
   });
 
-  test("deriveActiveSkillIds backward-compat wrapper still works with versioned markers", () => {
+  test("mapping to IDs works with versioned markers", () => {
     const messages: Message[] = [
       skillLoadUseMsg("t1"),
       toolResultMsg("t1", '<loaded_skill id="deploy" version="v1:abc123" />'),
       skillLoadUseMsg("t2"),
       toolResultMsg("t2", '<loaded_skill id="oncall" />'),
     ];
-    expect(deriveActiveSkillIds(messages)).toEqual(["deploy", "oncall"]);
+    expect(deriveActiveSkills(messages).map((e) => e.id)).toEqual([
+      "deploy",
+      "oncall",
+    ]);
   });
 
   test("tool_result with empty string content is handled gracefully", () => {