@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/runtime/channel-approval-types.ts

@@ -33,7 +33,7 @@ export {
  * `approve_once` / `reject` are the generic decision pair used by every
  * request kind. `trust` / `verify_code` / `leave_unverified` / `block` are the
  * introduction-card actions, valid only for `access_request` requests — the
- * canonical decision primitive rejects them for any other kind.
+ * guardian decision primitive rejects them for any other kind.
  */
 export const APPROVAL_ACTION_IDS = [
   "approve_once",

package/src/runtime/channel-reply-delivery.ts

@@ -75,13 +75,19 @@ function toDeliverableTextSegments(
         : stripped;
     })
     .filter((segment) => segment.trim().length > 0);
-  if (nonEmptySegments.length > 0) return nonEmptySegments;
+  if (nonEmptySegments.length > 0) {
+    return nonEmptySegments;
+  }
   // If the only text was <no_response/>, treat as intentional silence —
   // do not fall back to fallbackText.
-  if (hasNoResponseMarker(textSegments)) return [];
+  if (hasNoResponseMarker(textSegments)) {
+    return [];
+  }
   if (typeof fallbackText === "string") {
     const fallback = stripNoResponseMarkers(fallbackText);
-    if (fallback.length > 0) return [fallback];
+    if (fallback.length > 0) {
+      return [fallback];
+    }
   }
   return [];
 }
@@ -261,12 +267,7 @@ function readPersistedAssistantReply(msg: PersistedMessage): {
   rendered: RenderedHistoryContent;
   replyAttachments: RuntimeAttachmentMetadata[];
 } {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(msg.content);
-  } catch {
-    parsed = msg.content;
-  }
+  const parsed: unknown = msg.content;
   const rendered = renderHistoryContent(parsed);
 
   const linked = getAttachmentMetadataForMessage(msg.id);
@@ -282,9 +283,11 @@ function readPersistedAssistantReply(msg: PersistedMessage): {
 }
 
 function isToolResultUserMessage(msg: PersistedMessage): boolean {
-  if (msg.role !== "user") return false;
+  if (msg.role !== "user") {
+    return false;
+  }
   try {
-    const parsed = JSON.parse(msg.content) as unknown;
+    const parsed = msg.content as unknown;
     return (
       Array.isArray(parsed) &&
       parsed.length > 0 &&
@@ -306,7 +309,9 @@ export function findAssistantReplyMessageIdForTurn(
 ): string | undefined {
   const msgs = getMessages(conversationId);
   const userIndex = msgs.findIndex((msg) => msg.id === userMessageId);
-  if (userIndex === -1) return undefined;
+  if (userIndex === -1) {
+    return undefined;
+  }
 
   let turnEndIndex = msgs.length;
   for (let i = userIndex + 1; i < msgs.length; i++) {
@@ -446,7 +451,9 @@ export async function deliverReplyViaCallback(
 
   const msgs = getMessages(conversationId);
   for (let i = msgs.length - 1; i >= 0; i--) {
-    if (msgs[i].role !== "assistant") continue;
+    if (msgs[i].role !== "assistant") {
+      continue;
+    }
     const delivered = await deliverPersistedAssistantMessageViaCallback(
       msgs[i],
       externalChatId,
@@ -454,7 +461,9 @@ export async function deliverReplyViaCallback(
       assistantId,
       options,
     );
-    if (delivered) break;
+    if (delivered) {
+      break;
+    }
   }
 }
 
@@ -477,9 +486,13 @@ export async function deliverReplyViaCallback(
 function makeChannelTsReconciler(messageId: string): (ts: string) => void {
   let applied = false;
   return (ts: string): void => {
-    if (applied) return;
+    if (applied) {
+      return;
+    }
     applied = true;
-    if (!ts) return;
+    if (!ts) {
+      return;
+    }
     try {
       // Re-read the row's current metadata so a concurrent edit-propagation
       // write (e.g. `editedAt`) is not clobbered. `updateMessageMetadata`
@@ -489,7 +502,9 @@ function makeChannelTsReconciler(messageId: string): (ts: string) => void {
       // `readSlackMetadata` which rejects the partial form for lacking
       // channelTs — exactly the state we are reconciling).
       const row = getMessageById(messageId);
-      if (row === null || row.metadata === null) return;
+      if (row === null || row.metadata === null) {
+        return;
+      }
       let envelope: Record<string, unknown>;
       try {
         envelope = JSON.parse(row.metadata) as Record<string, unknown>;
@@ -498,11 +513,15 @@ function makeChannelTsReconciler(messageId: string): (ts: string) => void {
       }
       const slackMetaRaw =
         typeof envelope.slackMeta === "string" ? envelope.slackMeta : null;
-      if (slackMetaRaw === null) return;
+      if (slackMetaRaw === null) {
+        return;
+      }
       // If the existing slackMeta already parses cleanly via the strict
       // reader, channelTs is already present (a prior reconciliation ran,
       // or backfill stamped the field) — nothing to do.
-      if (readSlackMetadata(slackMetaRaw) !== null) return;
+      if (readSlackMetadata(slackMetaRaw) !== null) {
+        return;
+      }
       // Lenient parse of the partial slackMeta so we can preserve every
       // field already written by `handleMessageComplete` (source,
       // eventKind, channelId, threadTs, ...) while patching channelTs in.

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -2,23 +2,23 @@
  * Bridge trusted-contact confirmation_request events to guardian.question notifications.
  *
  * When a trusted-contact channel session creates a confirmation_request (tool approval),
- * this helper emits a guardian.question notification signal and persists canonical
+ * this helper emits a guardian.question notification signal and persists guardian-request
  * delivery rows to guardian destinations (Telegram/Slack/Vellum), enabling the guardian
  * to approve via callback/request-code path.
  *
  * Modeled after the tool-grant-request-helper pattern. Designed to be called from
  * both the daemon event registrar (server.ts) and the HTTP hub publisher
  * (conversation-routes.ts) — the two paths that create confirmation_request
- * canonical records.
+ * guardian requests.
  */
 
-import type { CanonicalGuardianRequest } from "../contacts/canonical-guardian-store.js";
+import type { GuardianRequestWire } from "../channels/gateway-guardian-requests.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
+import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import {
   recordApprovalCardDelivery,
   recordGuardianRequestDeliveries,
-} from "../notifications/canonical-delivery-recorder.js";
-import { emitNotificationSignal } from "../notifications/emit-signal.js";
+} from "../notifications/guardian-delivery-recorder.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./assistant-scope.js";
@@ -32,8 +32,8 @@ const log = getLogger("confirmation-request-guardian-bridge");
 // ---------------------------------------------------------------------------
 
 export interface BridgeConfirmationRequestParams {
-  /** The canonical guardian request already persisted for this confirmation_request. */
-  canonicalRequest: CanonicalGuardianRequest;
+  /** The guardian request already persisted for this confirmation_request. */
+  guardianRequest: GuardianRequestWire;
   /** Guardian runtime context from the session. */
   trustContext: TrustContext;
   /** Conversation ID where the confirmation_request was emitted. */
@@ -74,7 +74,7 @@ export async function bridgeConfirmationRequestToGuardian(
   params: BridgeConfirmationRequestParams,
 ): Promise<BridgeConfirmationRequestResult> {
   const {
-    canonicalRequest,
+    guardianRequest,
     trustContext,
     conversationId,
     toolName,
@@ -109,36 +109,39 @@ export async function bridgeConfirmationRequestToGuardian(
     return { skipped: true, reason: "no_guardian_binding" };
   }
 
-  // Validate that the binding's guardian identity matches the canonical request's
+  // Validate that the binding's guardian identity matches the request's
   // guardian identity. A mismatch can occur if a guardian rebind happens between
   // message ingress and confirmation emission — sending the notification to the
   // new binding would leak requester/tool metadata to the wrong recipient.
   //
-  // Both sides are canonicalized before comparison because the canonical request
-  // value was normalized by toTrustContext() (verdict and local resolution
+  // Both sides are canonicalized before comparison because the request's
+  // guardian id was normalized by toTrustContext() (verdict and local resolution
   // both route through it) while the binding stores the raw identity. On
   // phone channels the same guardian can have format variance
   // (e.g. "+1 555-123-4567" vs "+15551234567") that would cause a false mismatch.
-  const canonicalBindingId = canonicalizeInboundIdentity(
+  const canonicalizedBindingGuardianId = canonicalizeInboundIdentity(
     sourceChannel,
     binding.guardianExternalUserId,
   );
-  const canonicalRequestId = canonicalRequest.guardianExternalUserId
+  const canonicalizedRequestGuardianId = guardianRequest.guardianExternalUserId
     ? canonicalizeInboundIdentity(
         sourceChannel,
-        canonicalRequest.guardianExternalUserId,
+        guardianRequest.guardianExternalUserId,
       )
     : null;
-  if (canonicalRequestId && canonicalBindingId !== canonicalRequestId) {
+  if (
+    canonicalizedRequestGuardianId &&
+    canonicalizedBindingGuardianId !== canonicalizedRequestGuardianId
+  ) {
     log.warn(
       {
         sourceChannel,
         assistantId,
         bindingGuardianId: binding.guardianExternalUserId,
-        expectedGuardianId: canonicalRequest.guardianExternalUserId,
-        requestId: canonicalRequest.id,
+        expectedGuardianId: guardianRequest.guardianExternalUserId,
+        requestId: guardianRequest.id,
       },
-      "Guardian binding identity does not match canonical request guardian — skipping notification to prevent misrouting",
+      "Guardian binding identity does not match the request guardian — skipping notification to prevent misrouting",
     );
     return { skipped: true, reason: "binding_identity_mismatch" };
   }
@@ -148,13 +151,13 @@ export async function bridgeConfirmationRequestToGuardian(
     trustContext.requesterExternalUserId ||
     "unknown";
 
-  const questionText = canonicalRequest.activityText
-    ? `Approve tool: ${toolName} — ${canonicalRequest.activityText}`
+  const questionText = guardianRequest.activityText
+    ? `Approve tool: ${toolName} — ${guardianRequest.activityText}`
     : `Approve tool: ${toolName}`;
 
   // The vellum delivery row is created up front in onConversationCreated so the
   // in-app client sees it immediately; the post-resolve recorder reuses it.
-  let vellumDeliveryId: string | undefined;
+  let vellumDeliveryIdPromise: Promise<string | undefined> | undefined;
 
   // Emit guardian.question notification so the guardian is alerted.
   const signalPromise = emitNotificationSignal({
@@ -170,41 +173,44 @@ export async function bridgeConfirmationRequestToGuardian(
     },
     contextPayload: {
       requestKind: "tool_approval",
-      requestId: canonicalRequest.id,
+      requestId: guardianRequest.id,
       requestCode:
-        canonicalRequest.requestCode ??
-        canonicalRequest.id.slice(0, 6).toUpperCase(),
+        guardianRequest.requestCode ??
+        guardianRequest.id.slice(0, 6).toUpperCase(),
       sourceChannel,
       requesterExternalUserId: trustContext.requesterExternalUserId,
       requesterChatId: trustContext.requesterChatId ?? null,
       requesterIdentifier: senderLabel,
       toolName,
       questionText,
-      riskLevel: canonicalRequest.riskLevel ?? undefined,
-      commandPreview: canonicalRequest.commandPreview ?? undefined,
+      riskLevel: guardianRequest.riskLevel ?? undefined,
+      commandPreview: guardianRequest.commandPreview ?? undefined,
     },
-    dedupeKey: `tc-confirmation-request:${canonicalRequest.id}`,
+    dedupeKey: `tc-confirmation-request:${guardianRequest.id}`,
+    // The broadcaster awaits the returned promise, so the delivery row is
+    // durable before the client can act on the conversation.
     onConversationCreated: (info) => {
-      vellumDeliveryId = recordApprovalCardDelivery({
-        requestId: canonicalRequest.id,
+      vellumDeliveryIdPromise ??= recordApprovalCardDelivery({
+        requestId: guardianRequest.id,
         channel: "vellum",
         conversationId: info.conversationId,
-      })?.id;
+      }).then((delivery) => delivery?.id);
+      return vellumDeliveryIdPromise.then(() => undefined);
     },
   });
 
   // Record deliveries from the notification pipeline (fire-and-forget).
   void signalPromise
-    .then((signalResult) => {
-      recordGuardianRequestDeliveries({
-        requestId: canonicalRequest.id,
+    .then(async (signalResult) => {
+      await recordGuardianRequestDeliveries({
+        requestId: guardianRequest.id,
         deliveryResults: signalResult.deliveryResults,
-        vellumDeliveryId,
+        vellumDeliveryId: await vellumDeliveryIdPromise,
       });
     })
     .catch((err) => {
       log.warn(
-        { err, requestId: canonicalRequest.id },
+        { err, requestId: guardianRequest.id },
         "Failed to record channel deliveries for guardian bridge",
       );
     });
@@ -214,8 +220,8 @@ export async function bridgeConfirmationRequestToGuardian(
       sourceChannel,
       requesterExternalUserId: trustContext.requesterExternalUserId,
       toolName,
-      requestId: canonicalRequest.id,
-      requestCode: canonicalRequest.requestCode,
+      requestId: guardianRequest.id,
+      requestCode: guardianRequest.requestCode,
     },
     "Guardian notified of trusted-contact confirmation request",
   );
@@ -223,6 +229,6 @@ export async function bridgeConfirmationRequestToGuardian(
   // Return the signal ID synchronously from the promise-producing call.
   // The actual signal ID is not available until the promise resolves, but
   // callers only need to know it was bridged — the ID is for diagnostics.
-  // We use the canonical request ID as a stable correlation key.
-  return { bridged: true, signalId: canonicalRequest.id };
+  // We use the guardian request ID as a stable correlation key.
+  return { bridged: true, signalId: guardianRequest.id };
 }

package/src/runtime/for-chat-mint-registry.ts

@@ -0,0 +1,118 @@
+/**
+ * for-chat-mint-registry — daemon-side record of `--for-chat` reveals that
+ * actually executed.
+ *
+ * The chat-credential-reveal persist guard re-mints sentinel-shaped spans
+ * whose `service:field` identity matches a `--for-chat` reveal from the
+ * current turn (see `guardForChatSentinels`). The authority for "a
+ * `--for-chat` reveal happened" must be the reveal ROUTE itself — the one
+ * place that enforces the feature flag and proves the credential exists —
+ * never a string parse of the requested shell command: a segment that
+ * merely quotes or comments out a reveal invocation (`echo 'assistant
+ * credentials reveal --for-chat …'`) would otherwise allowlist an identity
+ * for re-minting without the route ever running, letting forged sentinels
+ * survive persistence.
+ *
+ * So: `handleCredentialsReveal` records every successful `--for-chat` mint
+ * here (identity + the exact canonical sentinel it returned), and the
+ * conversation loop asks for mints recorded since its turn started. The
+ * stored sentinel doubles as the re-mint replacement — no vault re-read,
+ * and a tampered type label can't survive because the replacement is the
+ * daemon's own original mint.
+ *
+ * Scope: records are bound to the executing conversation by the reveal
+ * NONCE (see `reveal-nonce.ts`) — a daemon-held secret the shell tools
+ * export to the tool subprocess and the CLI forwards with the reveal. A
+ * predictable identifier (a conversation id in a body field or env var)
+ * would not do: the command under execution can override its subprocess
+ * env and redirect the mint to any conversation it can name, and staging
+ * alone cannot disambiguate CONCURRENT turns (staging is a parse — a turn
+ * that merely quotes a reveal command stages the same identity an
+ * overlapping turn legitimately executes). The consumer accepts a mint
+ * only when its nonce matches the consumer's own conversation AND its
+ * identity was staged by that run's own `tool_use` commands (see
+ * `turnForChatMints` in `conversation-agent-loop-handlers.ts`).
+ * `credentials reveal` is a high-risk, approval-gated command; earning a
+ * mint for a conversation requires an actual route call from that
+ * conversation's own tool shell.
+ */
+
+/** A successful `--for-chat` reveal: identity plus the minted sentinel. */
+export interface ForChatMint {
+  service: string;
+  field: string;
+  /** The canonical sentinel the reveal route returned for this credential. */
+  sentinel: string;
+  /**
+   * The conversation-bound reveal nonce the CLI forwarded (see
+   * `reveal-nonce.ts`). Consumers match on it exactly.
+   */
+  nonce: string;
+}
+
+interface MintRecord extends ForChatMint {
+  seq: number;
+  atMs: number;
+}
+
+/**
+ * Retention guards. Records are tiny (one short sentinel string each), so
+ * the bounds exist only to keep a pathological reveal loop from growing the
+ * array unboundedly. The age bound comfortably outlives any single turn —
+ * a watermark from a turn older than this has long since been superseded.
+ */
+const MAX_RECORDS = 256;
+const MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+let counter = 0;
+let records: MintRecord[] = [];
+
+/**
+ * Watermark for "now". A turn captures this at start; mints recorded after
+ * the capture are the ones `forChatMintsSince` returns for that turn.
+ */
+export function currentForChatMintWatermark(): number {
+  return counter;
+}
+
+/** Record a successful `--for-chat` reveal. Called by the reveal route. */
+export function recordForChatMint(mint: ForChatMint): void {
+  counter += 1;
+  records.push({ ...mint, seq: counter, atMs: Date.now() });
+  const cutoff = Date.now() - MAX_AGE_MS;
+  if (records.length > MAX_RECORDS || records[0]!.atMs < cutoff) {
+    records = records.filter((r) => r.atMs >= cutoff).slice(-MAX_RECORDS);
+  }
+}
+
+/**
+ * Mints recorded after `watermark`, deduplicated per nonce+identity (latest
+ * wins — one conversation re-revealing the same credential re-mints the
+ * same canonical sentinel). The nonce is part of the dedupe key on purpose:
+ * consumers filter the result by THEIR nonce afterwards, so an
+ * identity-only dedupe would let a concurrent conversation's later reveal
+ * of the same credential clobber this conversation's legitimate mint and
+ * neutralize its echoed sentinel. Callers MUST intersect the result with
+ * their own trusted staging context before treating a mint as re-mint
+ * authority — see the module doc.
+ */
+export function forChatMintsSince(watermark: number): ForChatMint[] {
+  const byNonceAndIdentity = new Map<string, ForChatMint>();
+  for (const r of records) {
+    if (r.seq > watermark) {
+      byNonceAndIdentity.set(`${r.nonce}\u0000${r.service}\u0000${r.field}`, {
+        service: r.service,
+        field: r.field,
+        sentinel: r.sentinel,
+        nonce: r.nonce,
+      });
+    }
+  }
+  return [...byNonceAndIdentity.values()];
+}
+
+/** Test-only: drop all records and reset the watermark counter. */
+export function resetForChatMintRegistryForTest(): void {
+  counter = 0;
+  records = [];
+}

package/src/runtime/guardian-action-service.ts

@@ -2,15 +2,15 @@
  * Shared service for processing guardian action decisions.
  *
  * Encapsulates the core business logic — validation, conversation scoping,
- * canonical decision application, and result mapping — so both the HTTP
- * handler and the message handler can delegate here without duplicating code.
+ * decision application, and result mapping — so both the HTTP handler and
+ * the message handler can delegate here without duplicating code.
  */
 
-import { applyCanonicalGuardianDecision } from "../approvals/guardian-decision-primitive.js";
+import { applyGuardianDecision } from "../approvals/guardian-decision-primitive.js";
 import {
-  getCanonicalGuardianRequest,
-  isRequestInConversationScope,
-} from "../contacts/canonical-guardian-store.js";
+  getGuardianRequestOrNull,
+  isGuardianRequestInScopeOrFalse,
+} from "../channels/gateway-guardian-requests.js";
 import {
   APPROVAL_ACTION_IDS,
   isApprovalAction,
@@ -62,15 +62,14 @@ export type ProcessGuardianDecisionResult =
 // ---------------------------------------------------------------------------
 
 /**
- * Process a guardian decision through the canonical request primitive.
+ * Process a guardian decision through the unified decision primitive.
  *
  * Validates the action, checks conversation scope if applicable, applies the
- * canonical decision, and maps the result to a caller-agnostic shape that
- * both HTTP and message handlers can interpret.
+ * decision, and maps the result to a caller-agnostic shape that both HTTP
+ * and message handlers can interpret.
  *
- * Valid actions are the `ApprovalAction` union; the canonical primitive
- * additionally scopes the introduction-card actions to `access_request`
- * requests.
+ * Valid actions are the `ApprovalAction` union; the primitive additionally
+ * scopes the introduction-card actions to `access_request` requests.
  */
 export async function processGuardianDecision(
   params: ProcessGuardianDecisionParams,
@@ -87,22 +86,28 @@ export async function processGuardianDecision(
     };
   }
 
-  // 2. Verify conversationId scoping before applying the canonical decision.
-  //    The decision is allowed when the conversationId matches the request's
+  // 2. Verify conversationId scoping before applying the decision. The
+  //    decision is allowed when the conversationId matches the request's
   //    source conversation OR a recorded delivery destination conversation.
+  //    Reads degrade fail-closed: an unreachable gateway scopes to not_found
+  //    (and the decide below fails loudly anyway).
   if (conversationId) {
-    const canonicalRequest = getCanonicalGuardianRequest(requestId);
+    const request = await getGuardianRequestOrNull(requestId);
     if (
-      canonicalRequest &&
-      canonicalRequest.conversationId &&
-      !isRequestInConversationScope(requestId, conversationId, channel)
+      request &&
+      request.sourceConversationId &&
+      !(await isGuardianRequestInScopeOrFalse(
+        requestId,
+        conversationId,
+        channel,
+      ))
     ) {
       return { ok: true, applied: false, reason: "not_found" };
     }
   }
 
-  // 3. Apply the canonical decision
-  const canonicalResult = await applyCanonicalGuardianDecision({
+  // 3. Apply the decision through the gateway-native primitive
+  const decisionResult = await applyGuardianDecision({
     requestId,
     action,
     actorContext: {
@@ -115,29 +120,29 @@ export async function processGuardianDecision(
   });
 
   // 4. Map the canonical result
-  if (canonicalResult.applied) {
-    if (canonicalResult.resolverFailed) {
+  if (decisionResult.applied) {
+    if (decisionResult.resolverFailed) {
       return {
         ok: true,
         applied: false,
         reason: "resolver_failed",
-        resolverFailureReason: canonicalResult.resolverFailureReason,
-        requestId: canonicalResult.requestId,
+        resolverFailureReason: decisionResult.resolverFailureReason,
+        requestId: decisionResult.requestId,
       };
     }
 
     return {
       ok: true,
       applied: true,
-      requestId: canonicalResult.requestId,
-      replyText: canonicalResult.resolverReplyText,
+      requestId: decisionResult.requestId,
+      replyText: decisionResult.resolverReplyText,
     };
   }
 
   return {
     ok: true,
     applied: false,
-    reason: canonicalResult.reason,
+    reason: decisionResult.reason,
     requestId,
   };
 }

package/src/runtime/guardian-decision-types.ts

@@ -24,8 +24,8 @@ export interface GuardianDecisionPrompt {
   conversationId: string;
   callSessionId: string | null;
   /**
-   * Canonical request kind (e.g. 'tool_approval', 'pending_question').
-   * Present when the prompt originates from the canonical guardian request
+   * Guardian request kind (e.g. 'tool_approval', 'pending_question').
+   * Present when the prompt originates from the guardian request
    * store. Absent for legacy-only prompts.
    */
   kind?: string;