@vellumai/assistant 0.3.27 → 0.4.0

package/src/agent/loop.ts

@@ -4,6 +4,8 @@ import { truncateOversizedToolResults } from '../context/tool-result-truncation.
 import { getHookManager } from '../hooks/manager.js';
 import type { ContentBlock,Message, Provider, ToolDefinition } from '../providers/types.js';
 import type { ToolResultContent } from '../providers/types.js';
+import type { SensitiveOutputBinding } from '../tools/sensitive-output-placeholders.js';
+import { applyStreamingSubstitution, applySubstitutions } from '../tools/sensitive-output-placeholders.js';
 import { getLogger, isDebug, truncateForLog } from '../util/logger.js';
 
 const log = getLogger('agent-loop');
@@ -63,14 +65,14 @@ export class AgentLoop {
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
   private resolveSystemPrompt: ((history: Message[]) => ResolvedSystemPrompt) | null;
-  private toolExecutor: ((name: string, input: Record<string, unknown>, onOutput?: (chunk: string) => void) => Promise<{ content: string; isError: boolean; diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean }; status?: string; contentBlocks?: ContentBlock[] }>) | null;
+  private toolExecutor: ((name: string, input: Record<string, unknown>, onOutput?: (chunk: string) => void) => Promise<{ content: string; isError: boolean; diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean }; status?: string; contentBlocks?: ContentBlock[]; sensitiveBindings?: SensitiveOutputBinding[] }>) | null;
 
   constructor(
     provider: Provider,
     systemPrompt: string,
     config?: Partial<AgentLoopConfig>,
     tools?: ToolDefinition[],
-    toolExecutor?: (name: string, input: Record<string, unknown>, onOutput?: (chunk: string) => void) => Promise<{ content: string; isError: boolean; diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean }; status?: string; contentBlocks?: ContentBlock[] }>,
+    toolExecutor?: (name: string, input: Record<string, unknown>, onOutput?: (chunk: string) => void) => Promise<{ content: string; isError: boolean; diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean }; status?: string; contentBlocks?: ContentBlock[]; sensitiveBindings?: SensitiveOutputBinding[] }>,
     resolveTools?: (history: Message[]) => ToolDefinition[],
     resolveSystemPrompt?: (history: Message[]) => ResolvedSystemPrompt,
   ) {
@@ -97,6 +99,12 @@ export class AgentLoop {
     const debug = isDebug();
     const rlog = requestId ? log.child({ requestId }) : log;
 
+    // Per-run substitution map for sensitive output placeholders.
+    // Bindings are accumulated from tool results; placeholders are
+    // resolved in streamed deltas and final assistant message text.
+    const substitutionMap = new Map<string, string>();
+    let streamingPending = '';
+
     while (true) {
       if (signal?.aborted) break;
 
@@ -188,7 +196,17 @@ export class AgentLoop {
             config: providerConfig,
             onEvent: (event) => {
               if (event.type === 'text_delta') {
-                onEvent({ type: 'text_delta', text: event.text });
+                // Apply sensitive-output placeholder substitution (chunk-safe)
+                if (substitutionMap.size > 0) {
+                  const combined = streamingPending + event.text;
+                  const { emit, pending } = applyStreamingSubstitution(combined, substitutionMap);
+                  streamingPending = pending;
+                  if (emit.length > 0) {
+                    onEvent({ type: 'text_delta', text: emit });
+                  }
+                } else {
+                  onEvent({ type: 'text_delta', text: event.text });
+                }
               } else if (event.type === 'thinking_delta') {
                 onEvent({ type: 'thinking_delta', thinking: event.thinking });
               } else if (event.type === 'input_json_delta') {
@@ -238,6 +256,20 @@ export class AgentLoop {
           durationMs: providerDurationMs,
         });
 
+        // Flush any buffered streaming text from the substitution pipeline
+        if (streamingPending.length > 0) {
+          const flushed = applySubstitutions(streamingPending, substitutionMap);
+          if (flushed.length > 0) {
+            onEvent({ type: 'text_delta', text: flushed });
+          }
+          streamingPending = '';
+        }
+
+        // Build the assistant message with placeholder-only text.
+        // Both provider history and persisted conversation store must retain
+        // placeholders so the model never sees real sensitive values — neither
+        // on subsequent loop turns nor on session reload from the database.
+        // Substitution to real values happens only in streamed text_delta events.
         const assistantMessage: Message = {
           role: 'assistant',
           content: response.content,
@@ -391,6 +423,17 @@ export class AgentLoop {
           toolResults = await toolExecutionPromise;
         }
 
+        // Merge sensitive output bindings from tool results into the
+        // per-run substitution map. Bindings carry placeholder->value pairs
+        // that are resolved in streamed text deltas and final message text.
+        for (const { result } of toolResults) {
+          if (result.sensitiveBindings) {
+            for (const binding of result.sensitiveBindings) {
+              substitutionMap.set(binding.placeholder, binding.value);
+            }
+          }
+        }
+
         // Collect result blocks preserving tool_use order (Promise.all maintains order)
         const rawResultBlocks: ContentBlock[] = toolResults.map(({ toolUse, result }) => ({
           type: 'tool_result' as const,

package/src/approvals/guardian-decision-primitive.ts

@@ -12,6 +12,11 @@
  *   5. Guardian approval record update
  *   6. Scoped grant minting on approve
  *
+ * The canonical path (`applyCanonicalGuardianDecision`) adds:
+ *   7. Canonical request lookup and status validation
+ *   8. CAS resolution via `resolveCanonicalGuardianRequest`
+ *   9. Kind-specific resolver dispatch via the resolver registry
+ *
  * Security invariants enforced here:
  *   - Decision application is identity-bound to expected guardian identity
  *   - Decisions are first-response-wins (CAS-like stale protection)
@@ -20,11 +25,18 @@
  */
 
 import type { ChannelId } from '../channels/types.js';
+import {
+  type CanonicalGuardianRequest,
+  type CanonicalRequestStatus,
+  getCanonicalGuardianRequest,
+  resolveCanonicalGuardianRequest,
+} from '../memory/canonical-guardian-store.js';
 import {
   type GuardianApprovalRequest,
   updateApprovalDecision,
 } from '../memory/channel-guardian-store.js';
 import type {
+  ApprovalAction,
   ApprovalDecisionResult,
 } from '../runtime/channel-approval-types.js';
 import {
@@ -36,6 +48,11 @@ import type { ApplyGuardianDecisionResult } from '../runtime/guardian-decision-t
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getLogger } from '../util/logger.js';
 import { mintGrantFromDecision } from './approval-primitive.js';
+import {
+  type ActorContext,
+  type ChannelDeliveryContext,
+  getResolver,
+} from './guardian-request-resolvers.js';
 
 const log = getLogger('guardian-decision-primitive');
 
@@ -189,3 +206,271 @@ export function applyGuardianDecision(params: ApplyGuardianDecisionParams): Appl
     requestId: result.requestId,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Consolidated canonical grant minting
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a scoped approval grant from a canonical guardian request.
+ *
+ * Works for all request kinds that carry tool metadata (toolName + inputDigest).
+ * Requests without tool metadata are silently skipped — grant minting only
+ * applies to tool-approval flows.
+ *
+ * Fails silently on error — grant minting is best-effort and must never
+ * block the approval flow.
+ */
+export function mintCanonicalRequestGrant(params: {
+  request: CanonicalGuardianRequest;
+  actorChannel: string;
+  guardianExternalUserId?: string;
+}): { minted: boolean } {
+  const { request, actorChannel, guardianExternalUserId } = params;
+
+  if (!request.toolName || !request.inputDigest) {
+    return { minted: false };
+  }
+
+  const result = mintGrantFromDecision({
+    assistantId: 'self',
+    scopeMode: 'tool_signature',
+    toolName: request.toolName,
+    inputDigest: request.inputDigest,
+    requestChannel: request.sourceChannel ?? 'unknown',
+    decisionChannel: actorChannel,
+    executionChannel: null,
+    conversationId: request.conversationId ?? null,
+    callSessionId: request.callSessionId ?? null,
+    guardianExternalUserId: guardianExternalUserId ?? null,
+    requesterExternalUserId: request.requesterExternalUserId ?? null,
+    expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+  });
+
+  if (result.ok) {
+    log.info(
+      {
+        event: 'canonical_grant_minted',
+        requestId: request.id,
+        toolName: request.toolName,
+        conversationId: request.conversationId,
+      },
+      'Minted scoped approval grant for canonical guardian request',
+    );
+    return { minted: true };
+  }
+
+  log.error(
+    {
+      event: 'canonical_grant_mint_failed',
+      reason: result.reason,
+      requestId: request.id,
+      toolName: request.toolName,
+    },
+    'Failed to mint scoped approval grant for canonical request (non-fatal)',
+  );
+  return { minted: false };
+}
+
+// ---------------------------------------------------------------------------
+// Canonical guardian decision primitive
+// ---------------------------------------------------------------------------
+
+/** Valid actions for canonical guardian decisions. */
+const VALID_CANONICAL_ACTIONS: ReadonlySet<ApprovalAction> = new Set([
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+export interface ApplyCanonicalGuardianDecisionParams {
+  /** The canonical request ID to resolve. */
+  requestId: string;
+  /** The decision action. */
+  action: ApprovalAction;
+  /** Actor context for the entity making the decision. */
+  actorContext: ActorContext;
+  /** Optional user-supplied text (e.g. answer text for pending questions). */
+  userText?: string;
+  /** Optional channel delivery context — present when the decision arrived via a channel message. */
+  channelDeliveryContext?: ChannelDeliveryContext;
+}
+
+export type CanonicalDecisionResult =
+  | { applied: true; requestId: string; grantMinted: boolean; resolverFailed?: boolean; resolverFailureReason?: string }
+  | { applied: false; reason: 'not_found' | 'already_resolved' | 'identity_mismatch' | 'invalid_action' | 'expired'; detail?: string };
+
+/**
+ * Apply a guardian decision through the canonical request primitive.
+ *
+ * This is the future single write path for all guardian decisions.  It
+ * operates on the canonical_guardian_requests table and dispatches to
+ * kind-specific resolvers via the resolver registry.
+ *
+ * Steps:
+ *   1. Look up the canonical request by ID
+ *   2. Validate: exists, pending status, identity match, valid action
+ *   3. Downgrade approve_always to approve_once (guardian-on-behalf invariant)
+ *   4. CAS resolve the canonical request atomically
+ *   5. Dispatch to kind-specific resolver
+ *   6. Mint grant if applicable
+ */
+export async function applyCanonicalGuardianDecision(
+  params: ApplyCanonicalGuardianDecisionParams,
+): Promise<CanonicalDecisionResult> {
+  const { requestId, action, actorContext, userText, channelDeliveryContext } = params;
+
+  // 1. Look up the canonical request
+  const request = getCanonicalGuardianRequest(requestId);
+  if (!request) {
+    log.warn(
+      { event: 'canonical_decision_not_found', requestId },
+      'Canonical request not found',
+    );
+    return { applied: false, reason: 'not_found' };
+  }
+
+  // 2a. Validate status is pending
+  if (request.status !== 'pending') {
+    log.info(
+      { event: 'canonical_decision_already_resolved', requestId, currentStatus: request.status },
+      'Canonical request already resolved',
+    );
+    return { applied: false, reason: 'already_resolved' };
+  }
+
+  // 2b. Validate action is valid
+  if (!VALID_CANONICAL_ACTIONS.has(action)) {
+    log.warn(
+      { event: 'canonical_decision_invalid_action', requestId, action },
+      'Invalid action for canonical decision',
+    );
+    return { applied: false, reason: 'invalid_action', detail: `invalid action: ${action}` };
+  }
+
+  // 2c. Validate identity: actor must match guardian_external_user_id
+  // unless the actor is trusted (desktop) or the request has no guardian binding.
+  if (
+    request.guardianExternalUserId &&
+    !actorContext.isTrusted &&
+    actorContext.externalUserId !== request.guardianExternalUserId
+  ) {
+    log.warn(
+      {
+        event: 'canonical_decision_identity_mismatch',
+        requestId,
+        expectedGuardian: request.guardianExternalUserId,
+        actualActor: actorContext.externalUserId,
+      },
+      'Actor identity does not match expected guardian',
+    );
+    return { applied: false, reason: 'identity_mismatch' };
+  }
+
+  // 2d. Check expiry
+  if (request.expiresAt && new Date(request.expiresAt).getTime() < Date.now()) {
+    log.info(
+      { event: 'canonical_decision_expired', requestId, expiresAt: request.expiresAt },
+      'Canonical request has expired',
+    );
+    return { applied: false, reason: 'expired' };
+  }
+
+  // 3. Downgrade approve_always to approve_once for guardian-on-behalf requests.
+  // Guardians cannot permanently allowlist tools on behalf of requesters.
+  const effectiveAction: ApprovalAction = action === 'approve_always'
+    ? 'approve_once'
+    : action;
+
+  // 4. CAS resolve: atomically transition from 'pending' to terminal status
+  const targetStatus: CanonicalRequestStatus = effectiveAction === 'reject'
+    ? 'denied'
+    : 'approved';
+
+  const resolved = resolveCanonicalGuardianRequest(requestId, 'pending', {
+    status: targetStatus,
+    answerText: userText,
+    decidedByExternalUserId: actorContext.externalUserId,
+  });
+
+  if (!resolved) {
+    // CAS failed — someone else resolved it first
+    log.info(
+      { event: 'canonical_decision_cas_failed', requestId },
+      'CAS resolution failed (race condition — first writer wins)',
+    );
+    return { applied: false, reason: 'already_resolved' };
+  }
+
+  // 5. Dispatch to kind-specific resolver
+  let resolverFailed = false;
+  let resolverFailureReason: string | undefined;
+  const resolver = getResolver(request.kind);
+  if (resolver) {
+    const resolverResult = await resolver.resolve({
+      request: resolved,
+      decision: { action: effectiveAction, userText },
+      actor: actorContext,
+      channelDeliveryContext,
+    });
+
+    if (!resolverResult.ok) {
+      log.warn(
+        {
+          event: 'canonical_decision_resolver_failed',
+          requestId,
+          kind: request.kind,
+          reason: resolverResult.reason,
+        },
+        `Resolver for kind '${request.kind}' failed: ${resolverResult.reason}`,
+      );
+      // The canonical request is already resolved (CAS succeeded), so we don't
+      // roll back.  Flag the failure and fall through to grant minting so that
+      // callers see applied: true (reflecting the committed DB state) while
+      // still being informed that the resolver had an issue.
+      resolverFailed = true;
+      resolverFailureReason = resolverResult.reason;
+    }
+  } else {
+    log.info(
+      { event: 'canonical_decision_no_resolver', requestId, kind: request.kind },
+      `No resolver registered for kind '${request.kind}' — CAS resolution only`,
+    );
+  }
+
+  // 6. Mint grant if the decision is an approval with tool metadata.
+  // Skip when the resolver failed — minting a grant on a failed side effect
+  // would allow the tool to execute without the intended resolver action
+  // (e.g. answerCall) having succeeded.
+  let grantMinted = false;
+  if (effectiveAction !== 'reject' && !resolverFailed) {
+    const grantResult = mintCanonicalRequestGrant({
+      request: resolved,
+      actorChannel: actorContext.channel,
+      guardianExternalUserId: actorContext.externalUserId ?? resolved.guardianExternalUserId ?? undefined,
+    });
+    grantMinted = grantResult.minted;
+  }
+
+  log.info(
+    {
+      event: 'canonical_decision_applied',
+      requestId,
+      kind: request.kind,
+      action: effectiveAction,
+      targetStatus,
+      grantMinted,
+      resolverFailed,
+    },
+    resolverFailed
+      ? 'Canonical guardian decision applied (CAS committed) but resolver failed'
+      : 'Canonical guardian decision applied successfully',
+  );
+
+  return {
+    applied: true,
+    requestId,
+    grantMinted,
+    ...(resolverFailed ? { resolverFailed, resolverFailureReason } : {}),
+  };
+}