@vellumai/assistant 0.3.18 → 0.3.20

package/src/memory/ingress-invite-store.ts

@@ -66,7 +66,7 @@ const DEFAULT_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 // Helpers
 // ---------------------------------------------------------------------------
 
-function hashToken(rawToken: string): string {
+export function hashToken(rawToken: string): string {
   return createHash('sha256').update(rawToken).digest('hex');
 }
 
@@ -268,6 +268,12 @@ export function redeemInvite(params: {
     return { error: 'invite_max_uses_reached' };
   }
 
+  // Enforce channel-scoped redemption: when the caller specifies a channel, it
+  // must match the channel the invite was created for.
+  if (params.sourceChannel && params.sourceChannel !== invite.sourceChannel) {
+    return { error: 'invite_channel_mismatch' };
+  }
+
   const newUseCount = invite.useCount + 1;
   const newStatus = newUseCount >= invite.maxUses ? 'redeemed' : 'active';
 
@@ -323,6 +329,94 @@ export function redeemInvite(params: {
   return { invite: updatedInvite, member: rowToMember(memberRow) };
 }
 
+// ---------------------------------------------------------------------------
+// recordInviteUse — consume one use without creating a member row
+// ---------------------------------------------------------------------------
+
+/**
+ * Increment an invite's use count and record redemption metadata without
+ * inserting a new member row. Used when reactivating an existing inactive
+ * member via invite — the member row already exists and just needs an
+ * update, so the transactional INSERT in `redeemInvite` would hit a
+ * unique-key constraint.
+ *
+ * Returns `true` if the use was recorded, or `false` if the invite was
+ * concurrently revoked/expired (the WHERE clause constrains to
+ * `status = 'active'` so a stale write is impossible).
+ */
+export function recordInviteUse(params: {
+  inviteId: string;
+  externalUserId?: string;
+  externalChatId?: string;
+}): boolean {
+  const db = getDb();
+  const now = Date.now();
+
+  const invite = db
+    .select()
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.id, params.inviteId))
+    .get();
+
+  if (!invite) return false;
+
+  const newUseCount = invite.useCount + 1;
+  const newStatus = newUseCount >= invite.maxUses ? 'redeemed' : 'active';
+
+  // Constrain the update to active invites so a concurrent revoke/expire
+  // prevents this write rather than silently overwriting the new status.
+  db.update(assistantIngressInvites)
+    .set({
+      useCount: newUseCount,
+      status: newStatus,
+      redeemedByExternalUserId: params.externalUserId ?? null,
+      redeemedByExternalChatId: params.externalChatId ?? null,
+      redeemedAt: now,
+      updatedAt: now,
+    })
+    .where(
+      and(
+        eq(assistantIngressInvites.id, invite.id),
+        eq(assistantIngressInvites.status, 'active'),
+      ),
+    )
+    .run();
+
+  // Re-read to confirm the update took effect (the WHERE clause constrains
+  // to status = 'active', so a concurrent revoke/expire would prevent it).
+  const updated = db
+    .select({ useCount: assistantIngressInvites.useCount })
+    .from(assistantIngressInvites)
+    .where(eq(assistantIngressInvites.id, invite.id))
+    .get();
+
+  return !!updated && updated.useCount === newUseCount;
+}
+
+// ---------------------------------------------------------------------------
+// markInviteExpired
+// ---------------------------------------------------------------------------
+
+/**
+ * Transition an invite's status to 'expired' in storage. This is safe to call
+ * even if the invite is already expired — the WHERE clause scopes the update
+ * to 'active' rows so it becomes a no-op in that case.
+ */
+export function markInviteExpired(inviteId: string): void {
+  const db = getDb();
+  const now = Date.now();
+
+  db.update(assistantIngressInvites)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(assistantIngressInvites.id, inviteId),
+        eq(assistantIngressInvites.status, 'active'),
+      ),
+    )
+    .run();
+}
+
 // ---------------------------------------------------------------------------
 // findByTokenHash
 // ---------------------------------------------------------------------------

package/src/memory/migrations/033-scoped-approval-grants.ts

@@ -0,0 +1,51 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Create the scoped_approval_grants table for channel-agnostic scoped
+ * approval grants.  Supports two scope modes:
+ *   - request_id: grant is scoped to a specific request
+ *   - tool_signature: grant is scoped to a tool name + input digest
+ *
+ * Grants are one-time-use (active -> consumed via CAS) and carry a
+ * mandatory TTL (expires_at).
+ */
+export function createScopedApprovalGrantsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS scoped_approval_grants (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      scope_mode TEXT NOT NULL,
+      request_id TEXT,
+      tool_name TEXT,
+      input_digest TEXT,
+      request_channel TEXT NOT NULL,
+      decision_channel TEXT NOT NULL,
+      execution_channel TEXT,
+      conversation_id TEXT,
+      call_session_id TEXT,
+      requester_external_user_id TEXT,
+      guardian_external_user_id TEXT,
+      status TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      consumed_at TEXT,
+      consumed_by_request_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+
+  // Index for request_id-based lookups (scope_mode = 'request_id')
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_request_id ON scoped_approval_grants(request_id) WHERE request_id IS NOT NULL`,
+  );
+
+  // Index for tool_signature-based lookups (scope_mode = 'tool_signature')
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_tool_sig ON scoped_approval_grants(tool_name, input_digest) WHERE tool_name IS NOT NULL`,
+  );
+
+  // Index for expiry sweeps
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_status_expires ON scoped_approval_grants(status, expires_at)`,
+  );
+}

package/src/memory/migrations/034-guardian-action-tool-metadata.ts

@@ -0,0 +1,12 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add tool_name and input_digest columns to guardian_action_requests for
+ * structured tool-approval tracking. These are nullable — informational
+ * ASK_GUARDIAN requests leave them NULL while tool-approval requests
+ * carry the tool identity and canonical input digest.
+ */
+export function migrateGuardianActionToolMetadata(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN tool_name TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN input_digest TEXT`); } catch { /* already exists */ }
+}

package/src/memory/migrations/035-guardian-action-supersession.ts

@@ -0,0 +1,23 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add supersession metadata columns to guardian_action_requests and
+ * create an index for efficient pending-request lookups by call session.
+ *
+ * - superseded_by_request_id: links to the request that replaced this one
+ * - superseded_at: timestamp when supersession occurred
+ * - Index (call_session_id, status, created_at DESC) for fast lookups of
+ *   the most recent pending request per call session
+ *
+ * The existing expired_reason column already supports 'superseded' as a
+ * value — this migration adds the structural metadata to track the
+ * supersession chain.
+ */
+export function migrateGuardianActionSupersession(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN superseded_by_request_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN superseded_at INTEGER`); } catch { /* already exists */ }
+
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_guardian_action_requests_session_status_created ON guardian_action_requests(call_session_id, status, created_at DESC)`,
+  );
+}

package/src/memory/migrations/index.ts

@@ -34,6 +34,9 @@ export { migrateGuardianVerificationPurpose } from './030-guardian-verification-
 export { migrateConversationsThreadTypeIndex } from './031-conversations-thread-type-index.js';
 export { migrateGuardianDeliveryConversationIndex } from './032-guardian-delivery-conversation-index.js';
 export { migrateNotificationDeliveryThreadDecision } from './032-notification-delivery-thread-decision.js';
+export { createScopedApprovalGrantsTable } from './033-scoped-approval-grants.js';
+export { migrateGuardianActionToolMetadata } from './034-guardian-action-tool-metadata.js';
+export { migrateGuardianActionSupersession } from './035-guardian-action-supersession.js';
 export { createCoreTables } from './100-core-tables.js';
 export { createWatchersAndLogsTables } from './101-watchers-and-logs.js';
 export { addCoreColumns } from './102-alter-table-columns.js';

package/src/memory/schema.ts

@@ -843,9 +843,15 @@ export const guardianActionRequests = sqliteTable('guardian_action_requests', {
   lateAnsweredAt: integer('late_answered_at'),
   followupAction: text('followup_action'),                          // call_back | message_back | decline
   followupCompletedAt: integer('followup_completed_at'),
+  toolName: text('tool_name'),                                        // tool identity for tool-approval requests
+  inputDigest: text('input_digest'),                                  // canonical SHA-256 digest of tool input
+  supersededByRequestId: text('superseded_by_request_id'),            // links to the request that replaced this one
+  supersededAt: integer('superseded_at'),                             // epoch ms when supersession occurred
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
-});
+}, (table) => [
+  index('idx_guardian_action_requests_session_status_created').on(table.callSessionId, table.status, table.createdAt),
+]);
 
 // ── Guardian Action Deliveries (per-channel delivery tracking) ───────
 
@@ -1075,3 +1081,31 @@ export const conversationAssistantAttentionState = sqliteTable('conversation_ass
   index('idx_conv_attn_state_assistant_latest_msg').on(table.assistantId, table.latestAssistantMessageAt),
   index('idx_conv_attn_state_assistant_last_seen').on(table.assistantId, table.lastSeenAssistantMessageAt),
 ]);
+
+// ── Scoped Approval Grants ──────────────────────────────────────────
+
+export const scopedApprovalGrants = sqliteTable('scoped_approval_grants', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  scopeMode: text('scope_mode').notNull(),           // 'request_id' | 'tool_signature'
+  requestId: text('request_id'),
+  toolName: text('tool_name'),
+  inputDigest: text('input_digest'),
+  requestChannel: text('request_channel').notNull(),
+  decisionChannel: text('decision_channel').notNull(),
+  executionChannel: text('execution_channel'),        // null = any channel
+  conversationId: text('conversation_id'),
+  callSessionId: text('call_session_id'),
+  requesterExternalUserId: text('requester_external_user_id'),
+  guardianExternalUserId: text('guardian_external_user_id'),
+  status: text('status').notNull(),                   // 'active' | 'consumed' | 'expired' | 'revoked'
+  expiresAt: text('expires_at').notNull(),
+  consumedAt: text('consumed_at'),
+  consumedByRequestId: text('consumed_by_request_id'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+}, (table) => [
+  index('idx_scoped_grants_request_id').on(table.requestId),
+  index('idx_scoped_grants_tool_sig').on(table.toolName, table.inputDigest),
+  index('idx_scoped_grants_status_expires').on(table.status, table.expiresAt),
+]);