@vellumai/assistant 0.11.7-dev.202608282003.8ce5421 → 0.11.7-dev.202608282312.37594b7

package/ARCHITECTURE.md

@@ -203,7 +203,7 @@ The guardian request system provides a channel-agnostic, unified domain for all
 
 **Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path), `pending_question` (voice call question path), and `access_request` (trusted-contact verification session creation). New request kinds register resolvers without touching the core primitive.
 
-**Expiry:** the daemon's 60-second sweep (`src/runtime/routes/guardian-expiry-sweep.ts`) asks the gateway to CAS-expire pending requests past `expiresAt` (`guardian_requests_sweep_expired`) and fans out card withdrawal + requester notices from the returned rows; interaction-bound kinds (`tool_approval`, `pending_question`) are expired at daemon boot via `guardian_requests_expire_interaction_bound` since they die with the in-memory pending-interactions map. `src/calls/guardian-action-sweep.ts` sends the guardian-facing expiry notices for voice questions.
+**Expiry:** the daemon's 60-second sweep (`src/runtime/routes/guardian-expiry-sweep.ts`) lists a bounded batch of past-deadline pending requests (`guardian_requests_list_expired_pending`, read-only), fans out card withdrawal + requester notices per row, and only then confirms each with the per-request `guardian_requests_expire` CAS, so a lost response or crash leaves the row listed for the next round; interaction-bound kinds (`tool_approval`, `pending_question`) are expired at daemon boot via `guardian_requests_expire_interaction_bound` since they die with the in-memory pending-interactions map, and the boot call never touches persistent kinds. `src/calls/guardian-action-sweep.ts` sends the guardian-facing expiry notices for voice questions.
 
 **Key source files:**
 
@@ -267,19 +267,19 @@ Guardian requests (tool approvals, access requests, voice ASK_GUARDIAN questions
 
 **Voice consultation timeout:** When a voice call's ASK_GUARDIAN consultation times out before the guardian responds, the call controller expires the request via the gateway (`guardian_requests_expire` — deliveries expire with it), sends expiry notices to every surface the approval card reached (vellum conversations get an assistant message; external channels get a direct channel reply), and injects a `[GUARDIAN_TIMEOUT]` instruction so the model apologizes to the caller and offers a message or callback on the next voice turn.
 
-**Background expiry sweep:** Independent of any active call, a 60-second sweep asks the gateway to CAS-expire pending guardian requests past their `expiresAt` (`guardian_requests_sweep_expired` — a concurrent decision that wins the race is never overwritten), then fans out the side effects per expired row: withdrawing the approval cards on every surface, notifying the requester, and releasing any in-memory pending interaction.
+**Background expiry sweep:** Independent of any active call, a 60-second sweep lists pending guardian requests past their `expiresAt` (`guardian_requests_list_expired_pending`), runs the side effects per row (withdrawing the approval cards on every surface, notifying the requester, releasing any in-memory pending interaction), and then confirms each with the per-request `guardian_requests_expire` CAS; a decision arriving past the deadline loses to expiry atomically, since the decide CAS guards on `expires_at`.
 
 **Generated messaging requirement:** All user-facing copy in the guardian timeout/expiry path is generated through the `guardian-action-message-composer.ts` composition system, which uses a 2-tier priority chain: (1) daemon-injected LLM generator for natural, varied text; (2) deterministic fallback templates for reliability. No hardcoded user-facing strings exist in the flow files outside of internal log messages and LLM-instruction prompts. A guard test (`guardian-action-no-hardcoded-copy.test.ts`) enforces this invariant.
 
 **Key source files:**
 
-| File                                              | Purpose                                                                                                                                            |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/channels/gateway-guardian-requests.ts`       | Gateway-backed guardian-request client: typed wrappers over the `guardian_requests_*` IPC routes that own request/delivery state and expiry        |
-| `src/runtime/routes/guardian-expiry-sweep.ts`     | Periodic 60s sweep: gateway CAS-expiry (`guardian_requests_sweep_expired`) plus card-withdrawal, requester-notice, and pending-interaction fan-out |
-| `src/calls/call-controller.ts`                    | Voice timeout handling: expires the request, sends expiry notices, injects `[GUARDIAN_TIMEOUT]` instruction for the generated voice response       |
-| `src/calls/guardian-action-sweep.ts`              | Expiry notice delivery to guardian destinations (vellum conversation message or direct channel reply)                                              |
-| `src/runtime/guardian-action-message-composer.ts` | 2-tier text generation: daemon-injected LLM generator with deterministic fallback templates                                                        |
+| File                                              | Purpose                                                                                                                                                   |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/channels/gateway-guardian-requests.ts`       | Gateway-backed guardian-request client: typed wrappers over the `guardian_requests_*` IPC routes that own request/delivery state and expiry               |
+| `src/runtime/routes/guardian-expiry-sweep.ts`     | Periodic 60s sweep: bounded expired-pending list, per-row card-withdrawal, requester-notice, and pending-interaction fan-out, then per-request expire CAS |
+| `src/calls/call-controller.ts`                    | Voice timeout handling: expires the request, sends expiry notices, injects `[GUARDIAN_TIMEOUT]` instruction for the generated voice response              |
+| `src/calls/guardian-action-sweep.ts`              | Expiry notice delivery to guardian destinations (vellum conversation message or direct channel reply)                                                     |
+| `src/runtime/guardian-action-message-composer.ts` | 2-tier text generation: daemon-injected LLM generator with deterministic fallback templates                                                               |
 
 ### WhatsApp Channel (Meta Cloud API)
 

package/Dockerfile

@@ -117,6 +117,7 @@ RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 COPY --from=builder /app /app
 
 # Copy source after installing dependencies for better layer caching.
+COPY packages/avatar-catalog /app/packages/avatar-catalog
 COPY packages/avatar-manifest /app/packages/avatar-manifest
 COPY packages/ces-client /app/packages/ces-client
 COPY packages/service-contracts /app/packages/service-contracts

package/docs/trusted-contact-access.md

@@ -68,12 +68,12 @@ requested -> pending_guardian -> verification_pending -> active | denied | expir
 
 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 gateway `channel_verification_sessions` record when the session is created; the check itself is `checkIdentityMatch` (`gateway/src/verification/identity-match.ts`).
 
-| Channel   | Identity fields                                                                  | Binding behavior                                                                                                                                                                                                                                                                                                         |
-| --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat).                                                                                               |
-| Voice     | `expectedPhoneE164` = phone number in E.164 format                               | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                                                                                                                     |
+| Channel   | Identity fields                                                                                                                                                                                                                                                              | Binding behavior                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Telegram  | `expectedExternalUserId` = Telegram user ID, `expectedChatId` = Telegram chat ID                                                                                                                                                                                             | Both are taken from the original denied message's metadata. The `identityBindingStatus` is `'bound'`. Verification requires the actor's user ID or chat ID to match (user ID required when both are set on a shared chat).                                                                                                                                                                                                                                                                                                       |
+| Voice     | `expectedPhoneE164` = phone number in E.164 format                                                                                                                                                                                                                           | Phone-based identity binding. Verification requires the caller's number to match the expected phone.                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | Discord   | `expectedExternalUserId` = Discord user snowflake. `expectedChatId` is unset on the guardian-initiated and trusted-contact paths, and is the originating guild channel on the access-request approval path (`mint_outbound_session`), which sets it for every channel alike. | The code is delivered to a DM and answered there, but the DM channel does not exist until it is opened, so those two paths have no chat id to record at mint time. Where the approval path does set one, it is a room rather than an identity and never becomes a sufficient credential on its own: `checkIdentityMatch` requires the `expectedExternalUserId` match whenever both fields are set. That path also writes the room into `destinationAddress`, where it describes nothing the code is ever sent to (see LUM-3110). |
-| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                          | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                                                                                                                  |
+| Bootstrap | none yet (`identityBindingStatus: 'pending_bootstrap'`)                                                                                                                                                                                                                      | Unbound deep-link sessions use a 32-byte hex token instead of a numeric code; the identity is bound when the token is redeemed (`verification_sessions_bind_identity`).                                                                                                                                                                                                                                                                                                                                                          |
 
 **Anti-oracle invariant:** When identity verification fails, the error message is identical to the "invalid or expired code" message. This prevents attackers from distinguishing between a wrong code and a wrong identity, which would leak information about which identities have pending sessions.
 
@@ -129,10 +129,10 @@ Separately, the admitted-mode introduction **nudge** (for a contact who cleared
 
 ### Stage: `expired`
 
-| Store                                            | Table                           | Record                                                                                                    |
-| ------------------------------------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| gateway `guardian-request-store.ts` (gateway DB) | `guardian_requests`             | Updated to `status: 'expired'` via `guardian_requests_sweep_expired` (the daemon's sweep runs every 60s). |
-| `session-store.ts` (gateway DB)                  | `channel_verification_sessions` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingSessionByHash()`.           |
+| Store                                            | Table                           | Record                                                                                                                                           |
+| ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| gateway `guardian-request-store.ts` (gateway DB) | `guardian_requests`             | Updated to `status: 'expired'` via the per-request `guardian_requests_expire` CAS, after the daemon's 60s sweep has run that row's side effects. |
+| `session-store.ts` (gateway DB)                  | `channel_verification_sessions` | Expires naturally: `expiresAt < Date.now()` makes it invisible to `findPendingSessionByHash()`.                                                  |
 
 ### Invites (alternative path)
 
@@ -216,10 +216,11 @@ sequenceDiagram
 
     else Guardian never responds
         Note over A: runGuardianExpirySweep()<br/>runs every 60 seconds
-        A->>GW: guardian_requests_sweep_expired (IPC)
-        GW->>GW: Approval TTL elapsed → status: 'expired' (CAS)
+        A->>GW: guardian_requests_list_expired_pending (IPC)
         A->>A: Withdraw approval cards on all surfaces
         A-->>U: "Your access request has expired."
+        A->>GW: guardian_requests_expire (IPC)
+        GW->>GW: status: 'expired' (CAS, the fan-out's receipt)
 
     else Code expires (requester never enters it)
         Note over GW: Verification session TTL: 10 min
@@ -232,7 +233,7 @@ sequenceDiagram
 
 ### Guardian never responds
 
-- The `runGuardianExpirySweep()` timer (`runtime/routes/guardian-expiry-sweep.ts`) runs every 60 seconds; the gateway CAS-transitions pending requests past their `expiresAt` to `status: 'expired'` (`guardian_requests_sweep_expired`) and returns the expired rows.
+- The `runGuardianExpirySweep()` timer (`runtime/routes/guardian-expiry-sweep.ts`) runs every 60 seconds; the gateway returns a bounded, read-only batch of pending requests past their `expiresAt` (`guardian_requests_list_expired_pending`), and the daemon confirms each row with the per-request `guardian_requests_expire` CAS only after running its side effects, so the fan-out is recoverable from state.
 - The daemon then withdraws the now-stale approval cards on every surface and notifies the requester that the request expired.
 
 ### Verification code expires

package/knip.json

@@ -15,6 +15,7 @@
   "ignore": ["src/config/preloaded-apps/**"],
   "ignoreDependencies": [
     "@microsoft/api-extractor",
+    "@vellumai/avatar-catalog",
     "@vellumai/avatar-manifest",
     "@vellumai/ces-client",
     "@vellumai/credential-storage",

package/node_modules/@vellumai/avatar-catalog/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@vellumai/avatar-catalog",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./colors": "./src/colors.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/{src/avatar/character-components.ts → node_modules/@vellumai/avatar-catalog/src/catalog.ts}

@@ -1,43 +1,18 @@
-interface BodyShapeDefinition {
-  id: string;
-  viewBox: { width: number; height: number };
-  faceCenter: { x: number; y: number };
-  svgPath: string;
-}
-
-interface EyePathDefinition {
-  svgPath: string;
-  color: string; // hex e.g. "#F2F2F2"
-}
-
-interface EyeStyleDefinition {
-  id: string;
-  sourceViewBox: { width: number; height: number };
-  eyeCenter: { x: number; y: number };
-  paths: EyePathDefinition[];
-}
-
-interface ColorDefinition {
-  id: string;
-  hex: string; // e.g. "#4C9B50"
-}
-
-interface FaceCenterOverride {
-  bodyShape: string;
-  eyeStyle: string;
-  faceCenter: { x: number; y: number };
-}
-
-interface CharacterComponents {
-  bodyShapes: BodyShapeDefinition[];
-  eyeStyles: EyeStyleDefinition[];
-  colors: ColorDefinition[];
-  faceCenterOverrides: FaceCenterOverride[];
-}
+import { AVATAR_COLORS } from "./colors.js";
+import type { CharacterComponents } from "./types.js";
 
 const SCLERA = "#F2F2F2";
 const PUPIL = "#1A1A1A";
 
+/**
+ * Every body shape, eye style, and face-centre override an avatar can be
+ * composed from, plus the palette re-exposed on `colors`.
+ *
+ * This is the single definition. The daemon serves it over
+ * `/avatar/character-components`; clients that must compose an avatar before
+ * the daemon answers (a hatching screen, a chooser card) import it directly
+ * so no copy has to be kept in step with this one.
+ */
 export function getCharacterComponents(): CharacterComponents {
   return {
     bodyShapes: [
@@ -369,14 +344,7 @@ export function getCharacterComponents(): CharacterComponents {
       },
     ],
 
-    colors: [
-      { id: "green", hex: "#4C9B50" },
-      { id: "orange", hex: "#E9642F" },
-      { id: "pink", hex: "#DB4B77" },
-      { id: "purple", hex: "#A665C9" },
-      { id: "teal", hex: "#0E9B8B" },
-      { id: "yellow", hex: "#E9C91A" },
-    ],
+    colors: AVATAR_COLORS,
 
     faceCenterOverrides: [
       // Ghost body — shift non-native eyes from y=167 -> y=200

package/node_modules/@vellumai/avatar-catalog/src/colors.ts

@@ -0,0 +1,19 @@
+import type { ColorDefinition } from "./types.js";
+
+/**
+ * The avatar colour palette, in the order the picker offers it.
+ *
+ * Its own module because the palette is the one part of the catalog that
+ * boot-path code needs: a sidebar pin resolves a stored colour id on first
+ * render, and the accent CSS variable falls back to the first entry before
+ * the daemon's own catalog arrives. Importing the shapes to reach six hex
+ * values would put ~47 kB of SVG path data on that path.
+ */
+export const AVATAR_COLORS: ColorDefinition[] = [
+  { id: "green", hex: "#4C9B50" },
+  { id: "orange", hex: "#E9642F" },
+  { id: "pink", hex: "#DB4B77" },
+  { id: "purple", hex: "#A665C9" },
+  { id: "teal", hex: "#0E9B8B" },
+  { id: "yellow", hex: "#E9C91A" },
+];

package/node_modules/@vellumai/avatar-catalog/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @vellumai/avatar-catalog: the single definition of the components an
+ * assistant's character avatar is composed from.
+ *
+ * The daemon serves this catalog over `/avatar/character-components` and
+ * renders PNGs from it; clients bundle it because an avatar has to compose
+ * before the daemon can answer (the hatching screen, the assistant chooser,
+ * a transcript's subagent chips). Bundling is why this is a package rather
+ * than a daemon module every client copies.
+ *
+ * The palette is deliberately not re-exported here. It lives behind
+ * `@vellumai/avatar-catalog/colors`, and importing it from that subpath is
+ * what keeps boot-path code (a sidebar pin resolving a stored colour id, the
+ * accent variable's fallback) off the ~47 kB of SVG path data the shapes
+ * carry. Re-exporting it would make the expensive import the convenient one.
+ *
+ * The shapes' types stay internal for the same reason they were private to
+ * the daemon module this package replaces: the wire contract for this data is
+ * the route's `responseBody` schema, which clients consume through their
+ * generated OpenAPI types. A hand-written type exported from here would be a
+ * second name for that shape, and the closer one to reach for.
+ *
+ * Leaf package: no dependencies, no runtime imports.
+ */
+export { getCharacterComponents } from "./catalog.js";

package/node_modules/@vellumai/avatar-catalog/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Shapes for the catalog literal in this package.
+ *
+ * Declared here rather than derived from the generated OpenAPI types because
+ * this is a leaf package with no dependencies, and the clients that consume
+ * those generated types depend on it rather than the other way round. The
+ * canonical wire shape is the `avatar/character-components` route's
+ * `responseBody` schema; these are not exported so no consumer picks them up
+ * as a second name for it.
+ */
+
+export interface BodyShapeDefinition {
+  id: string;
+  viewBox: { width: number; height: number };
+  faceCenter: { x: number; y: number };
+  svgPath: string;
+}
+
+export interface EyePathDefinition {
+  svgPath: string;
+  color: string; // hex e.g. "#F2F2F2"
+}
+
+export interface EyeStyleDefinition {
+  id: string;
+  sourceViewBox: { width: number; height: number };
+  eyeCenter: { x: number; y: number };
+  paths: EyePathDefinition[];
+}
+
+export interface ColorDefinition {
+  id: string;
+  hex: string; // e.g. "#4C9B50"
+}
+
+export interface FaceCenterOverride {
+  bodyShape: string;
+  eyeStyle: string;
+  faceCenter: { x: number; y: number };
+}
+
+export interface CharacterComponents {
+  bodyShapes: BodyShapeDefinition[];
+  eyeStyles: EyeStyleDefinition[];
+  colors: ColorDefinition[];
+  faceCenterOverrides: FaceCenterOverride[];
+}

package/node_modules/@vellumai/avatar-catalog/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/gateway-client/src/__tests__/guardian-request-contract.test.ts

@@ -31,8 +31,7 @@ import {
   ListGuardianRequestsIpcParamsSchema,
   ListPendingGuardianRequestsByDestinationIpcParamsSchema,
   ListPendingGuardianRequestsByScopeIpcParamsSchema,
-  SweepExpiredGuardianRequestsIpcParamsSchema,
-  SweepExpiredGuardianRequestsIpcResponseSchema,
+  ListExpiredPendingGuardianRequestsIpcParamsSchema,
   UpdateGuardianRequestIpcParamsSchema,
   type GuardianRequestWire,
 } from "../guardian-request-contract.js";
@@ -439,29 +438,20 @@ describe("decide IPC schemas", () => {
 });
 
 describe("expiry IPC schemas", () => {
-  test("expire and sweep round-trip", () => {
+  test("expire and expired-pending list round-trip", () => {
     expect(ExpireGuardianRequestIpcParamsSchema.parse({ id: "req-1" })).toEqual(
       { id: "req-1" },
     );
 
     expect(
-      SweepExpiredGuardianRequestsIpcParamsSchema.parse({
+      ListExpiredPendingGuardianRequestsIpcParamsSchema.parse({
         now: 1_700_000_000_000,
+        limit: 50,
       }),
-    ).toEqual({ now: 1_700_000_000_000 });
-    expect(SweepExpiredGuardianRequestsIpcParamsSchema.parse({})).toEqual({});
-    // The sweep returns full rows so the daemon fan-out never re-reads.
-    const expiredRow = { ...accessRequest, status: "expired" as const };
-    expect(
-      SweepExpiredGuardianRequestsIpcResponseSchema.parse({
-        expired: [expiredRow],
-      }),
-    ).toEqual({ expired: [expiredRow] });
-    expect(() =>
-      SweepExpiredGuardianRequestsIpcResponseSchema.parse({
-        expired: ["req-1"],
-      }),
-    ).toThrow();
+    ).toEqual({ now: 1_700_000_000_000, limit: 50 });
+    expect(ListExpiredPendingGuardianRequestsIpcParamsSchema.parse({})).toEqual(
+      {},
+    );
 
     expect(
       ExpireInteractionBoundIpcResponseSchema.parse({ expired: 3 }),

package/node_modules/@vellumai/gateway-client/src/guardian-request-contract.ts

@@ -189,7 +189,7 @@ export const GUARDIAN_REQUESTS_IPC_METHODS = {
   decide: "guardian_requests_decide",
   expire: "guardian_requests_expire",
   expireInteractionBound: "guardian_requests_expire_interaction_bound",
-  sweepExpired: "guardian_requests_sweep_expired",
+  listExpiredPending: "guardian_requests_list_expired_pending",
   createDelivery: "guardian_requests_create_delivery",
   updateDelivery: "guardian_requests_update_delivery",
   listDeliveries: "guardian_requests_list_deliveries",
@@ -201,6 +201,32 @@ export const GUARDIAN_REQUESTS_IPC_METHODS = {
   getByPendingQuestion: "guardian_requests_get_by_pending_question",
 } as const;
 
+/**
+ * The delivery-row statuses this codebase writes and matches on.
+ *
+ * `GuardianRequestDeliverySchema.status` stays a plain `z.string()` rather
+ * than an enum built from these: the column is persisted, so a row written
+ * by a different build must still read rather than throw on parse. These
+ * constants exist so a call site names a value instead of spelling it, not
+ * to close the set.
+ *
+ * `pending` is the creation default; `sent` and `failed` carry the
+ * notification delivery result the recorder maps in; `expired` is stamped
+ * when the request itself expires; `withdrawn` is the daemon's per-surface
+ * receipt that a card was durably withdrawn, which the gateway's
+ * per-request expire preserves and a retrying withdrawal skips.
+ */
+export const DELIVERY_STATUS = {
+  pending: "pending",
+  sent: "sent",
+  failed: "failed",
+  expired: "expired",
+  withdrawn: "withdrawn",
+} as const;
+
+export type DeliveryStatus =
+  (typeof DELIVERY_STATUS)[keyof typeof DELIVERY_STATUS];
+
 export type GuardianRequestsIpcMethod =
   (typeof GUARDIAN_REQUESTS_IPC_METHODS)[keyof typeof GUARDIAN_REQUESTS_IPC_METHODS];
 
@@ -418,7 +444,7 @@ const OUTCOME_TYPES_BY_DECISION_STATUS: Record<
 /**
  * Request for `guardian_requests_decide` (status CAS + optional ACL outcome).
  * Decisions only resolve a pending request to approved/denied — expiry has
- * `guardian_requests_expire`/`_sweep_expired` — so a malformed call can never
+ * `guardian_requests_expire`/`_list_expired_pending`, so a malformed call can never
  * apply an `aclOutcome` while leaving the request decidable again. The
  * outcome type must agree with the status: activation/minting only on
  * approval, seeding/blocking only on denial.
@@ -508,26 +534,22 @@ export type ExpireInteractionBoundIpcResponse = z.infer<
   typeof ExpireInteractionBoundIpcResponseSchema
 >;
 
-/** Request for `guardian_requests_sweep_expired` (`now` defaults gateway-side). */
-export const SweepExpiredGuardianRequestsIpcParamsSchema = z.object({
-  now: z.number().optional(),
-});
-
-export type SweepExpiredGuardianRequestsIpcParams = z.infer<
-  typeof SweepExpiredGuardianRequestsIpcParamsSchema
->;
-
 /**
- * Response for `guardian_requests_sweep_expired`: the full expired rows, so
- * the daemon's card-withdrawal/notification fan-out never needs a follow-up
- * read that could fail after the status flip and strand the side effects.
+ * Request for `guardian_requests_list_expired_pending` (`now` defaults
+ * gateway-side; `limit` bounds the batch and is capped gateway-side).
+ * Read-only: the rows stay `pending` until the daemon has run each one's
+ * expiry side effects and confirms with `guardian_requests_expire`, so a
+ * lost response leaves the work discoverable by the next sweep round
+ * instead of silently done. Past-deadline pending rows are undecidable
+ * either way: every decision path checks `expiresAt` before any write.
  */
-export const SweepExpiredGuardianRequestsIpcResponseSchema = z.object({
-  expired: z.array(GuardianRequestSchema),
+export const ListExpiredPendingGuardianRequestsIpcParamsSchema = z.object({
+  now: z.number().optional(),
+  limit: z.number().optional(),
 });
 
-export type SweepExpiredGuardianRequestsIpcResponse = z.infer<
-  typeof SweepExpiredGuardianRequestsIpcResponseSchema
+export type ListExpiredPendingGuardianRequestsIpcParams = z.infer<
+  typeof ListExpiredPendingGuardianRequestsIpcParamsSchema
 >;
 
 // ---------------------------------------------------------------------------

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -268,8 +268,8 @@ export {
   ListGuardianRequestsIpcParamsSchema,
   ListPendingGuardianRequestsByDestinationIpcParamsSchema,
   ListPendingGuardianRequestsByScopeIpcParamsSchema,
-  SweepExpiredGuardianRequestsIpcParamsSchema,
-  SweepExpiredGuardianRequestsIpcResponseSchema,
+  DELIVERY_STATUS,
+  ListExpiredPendingGuardianRequestsIpcParamsSchema,
   UpdateGuardianRequestDeliveryIpcParamsSchema,
   UpdateGuardianRequestIpcParamsSchema,
 } from "./guardian-request-contract.js";
@@ -279,6 +279,7 @@ export type {
   CreateGuardianRequestIpcParams,
   DecideGuardianRequestIpcParams,
   DecideGuardianRequestIpcResponse,
+  DeliveryStatus,
   ExpireGuardianRequestIpcParams,
   ExpireInteractionBoundIpcParams,
   ExpireInteractionBoundIpcResponse,
@@ -306,8 +307,7 @@ export type {
   ListGuardianRequestsIpcParams,
   ListPendingGuardianRequestsByDestinationIpcParams,
   ListPendingGuardianRequestsByScopeIpcParams,
-  SweepExpiredGuardianRequestsIpcParams,
-  SweepExpiredGuardianRequestsIpcResponse,
+  ListExpiredPendingGuardianRequestsIpcParams,
   UpdateGuardianRequestDeliveryIpcParams,
   UpdateGuardianRequestIpcParams,
 } from "./guardian-request-contract.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.7-dev.202608282003.8ce5421",
+  "version": "0.11.7-dev.202608282312.37594b7",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -43,6 +43,7 @@
     "@qdrant/js-client-rest": "1.17.0",
     "@resvg/resvg-js": "2.6.2",
     "@slack/types": "2.22.0",
+    "@vellumai/avatar-catalog": "file:../packages/avatar-catalog",
     "@vellumai/avatar-manifest": "file:../packages/avatar-manifest",
     "@vellumai/ces-client": "file:../packages/ces-client",
     "@vellumai/credential-storage": "file:../packages/credential-storage",
@@ -87,6 +88,7 @@
     "node": ">=20.12.0"
   },
   "bundledDependencies": [
+    "@vellumai/avatar-catalog",
     "@vellumai/avatar-manifest",
     "@vellumai/ces-client",
     "@vellumai/credential-storage",