@vellumai/assistant 0.12.4 → 0.12.5-dev.202609251017.e467a6c

package/docs/architecture/memory.md

@@ -214,7 +214,15 @@ static substrate context remain available. When the answer depends on a saved pe
 fact that is absent from that context, the front-door rule escalates instead of
 guessing.
 
-The escalated leg runs the ordinary memory pipeline before the quality model.
+The escalated leg normally runs the memory pipeline before the quality model.
+During screen sharing, the front door can emit `[ESCALATE_SCREEN]` for an
+annotation or immediate on-screen action answerable from the screen and
+current conversation. The bridge skips fresh retrieval only when that verdict
+and an active screen share are both present. This per-turn policy gates the
+legacy hook and both v3 injectors, including re-injection, and clears at turn
+release. Static context and historical memory blocks remain available.
+Requests needing saved facts or preferences absent from context, uncertain
+classifications, and ordinary `[ESCALATE]` verdicts retain retrieval.
 V3 retrieval routes on the latest visible caller message, ignoring the hidden
 continuation message used to start that leg. The selector uses low effort to
 keep retrieval latency bounded. This keeps current-turn memory work off the

package/docs/architecture/scheduling.md

@@ -2,6 +2,12 @@
 
 Recurring schedules, watchers, and queued task execution architecture.
 
+## Execute-mode completion and time limits
+
+An execute-mode run owns its automatic result notification, including results from background commands and subagents. The scheduler waits for the firing's own active turns, queued continuations, commands, child tasks, and command wakes to settle before marking the run successful and emitting `schedule.result`. Unrelated work in a reused conversation does not extend the wait. Ownership is recorded before asynchronous turn setup, covers dequeued messages while their processing claim and persistence are pending, and follows wakes through queueing, hydration, and execution. Dequeued dispatches retain a cancellation signal for teardown until the active turn takes over. User interrupts preserve accepted user prompts during that handoff; started turns remain cancellable. Background work retains its original timing through queueing, dispatch, active processing, and command wakes. The reply-notification gate and persisted-history check apply that timing to suppress stale kickoff alerts without hiding replies to newer user requests. Quiet runs skip this fallback, and explicit successful delivery suppresses duplicates.
+
+The wait shares the run's `timeouts.scheduleTurnTimeoutSec` budget. If delegated work exceeds that budget, the scheduler records an error, cancels only commands, child tasks, queued continuations, and the active turn owned by that run. User work and other runs in the same conversation remain intact. The attempt follows the existing retry and exhaustion-alert policy; partial output never emits a success notification. Scheduled command wakes carry `cronRunId`, check the persisted run status before starting, and observe cancellation while running, so a late callback cannot restart a failed attempt.
+
 ## Recurrence Schedules — Cron and RRULE Dual-Syntax Engine
 
 The scheduler supports two recurrence syntaxes for recurring tasks:
@@ -88,11 +94,13 @@ sequenceDiagram
 
 The `enforceRoutingIntent()` step runs after the LLM produces a channel selection but before deterministic checks. It acts as a post-decision guard:
 
-| Intent           | Enforcement Rule                                                                                  |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| `single_channel` | No override. The LLM's channel selection stands.                                                  |
-| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels. |
-| `all_channels`   | Replace the LLM's selection with all connected channels.                                          |
+| Intent           | Enforcement Rule                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `single_channel` | Cap delivery to one channel: the signal's source channel when it is connected, otherwise the first channel the LLM selected. |
+| `multi_channel`  | If the LLM selected < 2 channels and 2+ are connected, expand to at least two connected channels.                            |
+| `all_channels`   | Replace the LLM's selection with all connected channels.                                                                     |
+
+A decision the LLM suppressed (`shouldNotify: false`) is left alone under every intent. A signal with no routing intent keeps the LLM's selection.
 
 When enforcement changes the decision, the updated `selectedChannels` and annotated `reasoningSummary` are re-persisted to `notification_decisions` so the audit trail reflects what was actually dispatched.
 

package/docs/desktop-browser-cli.md

@@ -53,8 +53,9 @@ Non-platform assistants keep their connected-computer behavior.
 Explicit `target: "connected-computer"` or `target_client_id` selects a connected
 computer on every client. The selected target never falls back to another
 computer when unavailable. The virtual desktop uses a fixed 1440x810 display.
-Observations return full-screen screenshots and mouse actions use the same
-screen coordinates.
+Observations return full-screen screenshots and mouse actions use screen
+points. Screenshot metadata uses the transport-optimized image dimensions and
+provides per-axis conversion from image pixels to those screen points.
 Viewer resizing scales the canvas locally without changing the desktop layout.
 
 Observe first and pass the returned `observation_id` with each native action.

package/docs/guardian-request-flow.md

@@ -24,7 +24,7 @@ anti-pattern was retired in #35642 and again in the ask_question redesign).
   (generic actions[] + plainTextFallback)         resolveQuestionContext)
         │
         ▼ per-channel rendering ONLY
-  channel adapters                               (notifications/adapters/{telegram,slack,macos,platform},
+  channel adapters                               (notifications/adapters/{telegram,slack,discord,macos,platform},
   telegram: inline keyboard; slack: blocks;       vellum: conversation card via approval-card-builder)
   card deliveries recorded per channel            (guardian-delivery-recorder.ts → guardian_request_deliveries)
         │

package/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -67,8 +67,31 @@ describe("notificationAvatarDiscHex", () => {
 });
 
 describe("notificationAvatarSvg", () => {
+  test("fills the entire circular crop with a custom image", () => {
+    const svg = notificationAvatarSvg({
+      kind: "image",
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(attributes("image", svg)).toMatchObject({
+      x: "0",
+      y: "0",
+      width: "256",
+      height: "256",
+      preserveAspectRatio: "xMidYMid slice",
+      "clip-path": "url(#notification-avatar-disc)",
+    });
+    expect(allAttributes("circle", svg)[1]).toEqual({
+      cx: "128",
+      cy: "128",
+      r: "128",
+    });
+  });
+
   test("draws one disc and one inset avatar at the default size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -100,6 +123,7 @@ describe("notificationAvatarSvg", () => {
     // upload fill the square instead of letterboxing is the pair of attributes
     // asserted here.
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
     });
@@ -121,6 +145,7 @@ describe("notificationAvatarSvg", () => {
 
   test("scales the geometry to a custom size", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: "#E9642F",
       size: 100,
@@ -142,6 +167,7 @@ describe("notificationAvatarSvg", () => {
 
   test("carries a non-PNG inner raster with its own media type", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       innerMediaType: "image/jpeg",
       accentHex: "#E9642F",
@@ -154,6 +180,7 @@ describe("notificationAvatarSvg", () => {
 
   test("paints the fallback disc when there is no accent", () => {
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
     });
@@ -164,8 +191,21 @@ describe("notificationAvatarSvg", () => {
 });
 
 describe("notificationAvatarGeometry", () => {
+  test("custom images reach the disc edge at any output size", () => {
+    expect(notificationAvatarGeometry("image")).toEqual({
+      radius: 128,
+      offset: 0,
+      inner: 256,
+    });
+    expect(notificationAvatarGeometry("image", 100)).toEqual({
+      radius: 50,
+      offset: 0,
+      inner: 100,
+    });
+  });
+
   test("derives the disc, the border and the avatar edge from the size", () => {
-    expect(notificationAvatarGeometry(100)).toEqual({
+    expect(notificationAvatarGeometry("character", 100)).toEqual({
       radius: 50,
       offset: 11,
       inner: 78,
@@ -173,15 +213,19 @@ describe("notificationAvatarGeometry", () => {
   });
 
   test("measures the default size when given none", () => {
-    expect(notificationAvatarGeometry()).toEqual(
-      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    expect(notificationAvatarGeometry("character")).toEqual(
+      notificationAvatarGeometry("character", NOTIFICATION_AVATAR_SIZE),
     );
   });
 
   test("is the geometry the SVG is drawn with", () => {
     const size = 100;
-    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const { radius, offset, inner } = notificationAvatarGeometry(
+      "character",
+      size,
+    );
     const svg = notificationAvatarSvg({
+      kind: "character",
       innerPngBase64: PNG_BASE64,
       accentHex: null,
       size,

package/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -15,11 +15,12 @@
  */
 
 import { isAvatarAccentHex } from "./accent.js";
+import type { AvatarKind } from "./manifest.js";
 
 /** Output edge in pixels: large enough for an iOS notification thumbnail. */
 export const NOTIFICATION_AVATAR_SIZE = 256;
 
-/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+/** Free disc on each side of a character avatar, as a fraction of the edge. */
 export const NOTIFICATION_AVATAR_INSET = 0.11;
 
 /** The disc when the assistant has no accent. */
@@ -48,7 +49,7 @@ export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
  * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
  * a disc rendered by an older spec even when the avatar itself is unchanged.
  */
-export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 2;
 
 /** The id the inner raster's clip path is referenced by inside the document. */
 const CLIP_ID = "notification-avatar-disc";
@@ -74,24 +75,26 @@ export function notificationAvatarDiscHex(accentHex: string | null): string {
 
 /** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
 export type NotificationAvatarMediaType =
-  | "image/png"
-  | "image/jpeg"
-  | "image/gif";
+  "image/png" | "image/jpeg" | "image/gif";
 
 /**
  * The three measurements the drawing derives from the edge: the disc's radius,
  * which is also its centre; the free border around the avatar; and the
  * avatar's own edge. Every rasterizer reads them from here, so the daemon's
  * SVG and the desktop canvas cannot drift.
+ * Custom images fill the disc; character avatars retain space around their
+ * silhouette.
  */
 export function notificationAvatarGeometry(
+  kind: Exclude<AvatarKind, "none">,
   size: number = NOTIFICATION_AVATAR_SIZE,
 ): { radius: number; offset: number; inner: number } {
-  const offset = size * NOTIFICATION_AVATAR_INSET;
+  const offset = kind === "character" ? size * NOTIFICATION_AVATAR_INSET : 0;
   return { radius: size / 2, offset, inner: size - 2 * offset };
 }
 
 export interface NotificationAvatarSvgOptions {
+  kind: Exclude<AvatarKind, "none">;
   /** The avatar raster to draw inside the disc, base64 with no data prefix. */
   innerPngBase64: string;
   /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
@@ -107,7 +110,7 @@ function px(value: number): string {
 
 /**
  * The notification avatar as an SVG document: a filled disc with the avatar
- * drawn inset into it.
+ * filling it for custom images or inset for character avatars.
  *
  * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
  * canvas does, so a portrait or landscape upload fills the square instead of
@@ -119,12 +122,13 @@ function px(value: number): string {
  * rasterizer is known to render it.
  */
 export function notificationAvatarSvg({
+  kind,
   innerPngBase64,
   innerMediaType = "image/png",
   accentHex,
   size = NOTIFICATION_AVATAR_SIZE,
 }: NotificationAvatarSvgOptions): string {
-  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const { radius, offset, inner } = notificationAvatarGeometry(kind, size);
   const href = `data:${innerMediaType};base64,${innerPngBase64}`;
   const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
   return (

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/guardian-requests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  GUARDIAN_DECISION_ACTION_IDS,
+  isDenyingGuardianAction,
+  isParkGuardianAction,
+} from "../guardian-requests.js";
+
+describe("guardian decision actions", () => {
+  test("reject, leave_unverified and block deny; every other action approves", () => {
+    const denying = GUARDIAN_DECISION_ACTION_IDS.filter(
+      isDenyingGuardianAction,
+    );
+    expect(denying).toEqual(["reject", "leave_unverified", "block"]);
+  });
+
+  test("only leave_unverified parks the sender", () => {
+    const parking = GUARDIAN_DECISION_ACTION_IDS.filter(isParkGuardianAction);
+    expect(parking).toEqual(["leave_unverified"]);
+  });
+
+  test("an absent or unknown action neither denies nor parks", () => {
+    expect(isDenyingGuardianAction(undefined)).toBe(false);
+    expect(isParkGuardianAction("approve_always")).toBe(false);
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -1,7 +1,8 @@
 /**
- * Canonical vocabulary for a guardian request's lifecycle status, shared by
- * the gateway that owns the request rows, the daemon that decides and
- * projects them, and the web that renders the projection.
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
  */
 import { z } from "zod";
 
@@ -16,3 +17,76 @@ export const GuardianRequestStatusSchema = z.enum(
   GUARDIAN_REQUEST_STATUS_VALUES,
 );
 export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `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.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/__tests__/guardian-requests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  GUARDIAN_DECISION_ACTION_IDS,
+  isDenyingGuardianAction,
+  isParkGuardianAction,
+} from "../guardian-requests.js";
+
+describe("guardian decision actions", () => {
+  test("reject, leave_unverified and block deny; every other action approves", () => {
+    const denying = GUARDIAN_DECISION_ACTION_IDS.filter(
+      isDenyingGuardianAction,
+    );
+    expect(denying).toEqual(["reject", "leave_unverified", "block"]);
+  });
+
+  test("only leave_unverified parks the sender", () => {
+    const parking = GUARDIAN_DECISION_ACTION_IDS.filter(isParkGuardianAction);
+    expect(parking).toEqual(["leave_unverified"]);
+  });
+
+  test("an absent or unknown action neither denies nor parks", () => {
+    expect(isDenyingGuardianAction(undefined)).toBe(false);
+    expect(isParkGuardianAction("approve_always")).toBe(false);
+  });
+});

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -1,7 +1,8 @@
 /**
- * Canonical vocabulary for a guardian request's lifecycle status, shared by
- * the gateway that owns the request rows, the daemon that decides and
- * projects them, and the web that renders the projection.
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
  */
 import { z } from "zod";
 
@@ -16,3 +17,76 @@ export const GuardianRequestStatusSchema = z.enum(
   GUARDIAN_REQUEST_STATUS_VALUES,
 );
 export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `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.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;

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

@@ -15,6 +15,7 @@
  */
 
 import type { KnownBlock } from "@slack/types";
+import { GuardianActionEmphasisSchema } from "@vellumai/service-contracts/guardian-requests";
 import { z } from "zod";
 
 // ---------------------------------------------------------------------------
@@ -41,10 +42,7 @@ export type AttachmentMetadata = z.infer<typeof AttachmentMetadataSchema>;
 export const ApprovalActionOptionSchema = z.object({
   id: z.string(),
   label: z.string(),
-  // Surface-agnostic button weight. Renderers translate it to their platform
-  // token (Slack primary/danger, Surface primary/destructive); absent means
-  // the renderer applies its own default styling.
-  emphasis: z.enum(["primary", "secondary", "destructive"]).optional(),
+  emphasis: GuardianActionEmphasisSchema.optional(),
 });
 
 export type ApprovalActionOption = z.infer<typeof ApprovalActionOptionSchema>;

package/node_modules/@vellumai/service-contracts/src/__tests__/guardian-requests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  GUARDIAN_DECISION_ACTION_IDS,
+  isDenyingGuardianAction,
+  isParkGuardianAction,
+} from "../guardian-requests.js";
+
+describe("guardian decision actions", () => {
+  test("reject, leave_unverified and block deny; every other action approves", () => {
+    const denying = GUARDIAN_DECISION_ACTION_IDS.filter(
+      isDenyingGuardianAction,
+    );
+    expect(denying).toEqual(["reject", "leave_unverified", "block"]);
+  });
+
+  test("only leave_unverified parks the sender", () => {
+    const parking = GUARDIAN_DECISION_ACTION_IDS.filter(isParkGuardianAction);
+    expect(parking).toEqual(["leave_unverified"]);
+  });
+
+  test("an absent or unknown action neither denies nor parks", () => {
+    expect(isDenyingGuardianAction(undefined)).toBe(false);
+    expect(isParkGuardianAction("approve_always")).toBe(false);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/guardian-requests.ts

@@ -1,7 +1,8 @@
 /**
- * Canonical vocabulary for a guardian request's lifecycle status, shared by
- * the gateway that owns the request rows, the daemon that decides and
- * projects them, and the web that renders the projection.
+ * Canonical vocabulary for guardian requests, shared by the gateway that owns
+ * the request rows, the daemon that decides and projects them, and the web
+ * that renders the projection: a request's lifecycle status, the actions a
+ * guardian can decide it with, and the weight a card gives each action.
  */
 import { z } from "zod";
 
@@ -16,3 +17,76 @@ export const GuardianRequestStatusSchema = z.enum(
   GUARDIAN_REQUEST_STATUS_VALUES,
 );
 export type GuardianRequestStatus = z.infer<typeof GuardianRequestStatusSchema>;
+
+/**
+ * The actions a guardian can decide a request with.
+ *
+ * `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.
+ */
+export const GUARDIAN_DECISION_ACTION_IDS = [
+  "approve_once",
+  "reject",
+  "trust",
+  "verify_code",
+  "leave_unverified",
+  "block",
+] as const;
+export const GuardianDecisionActionIdSchema = z.enum(
+  GUARDIAN_DECISION_ACTION_IDS,
+);
+export type GuardianDecisionActionId = z.infer<
+  typeof GuardianDecisionActionIdSchema
+>;
+
+/** Actions that resolve a request to `denied`; every other one approves. */
+export const GUARDIAN_DENYING_ACTION_VALUES = [
+  "reject",
+  "leave_unverified",
+  "block",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+/**
+ * The denying actions that park the sender at `unverified`: a neutral hold,
+ * not a rejection. A parked contact is still admitted under the permissive
+ * admission floors (`any_contact`, `strangers`) and can be trusted or verified
+ * later; contrast `block` (revoked, a hard keep-out) and `reject` (an explicit
+ * decline). All three resolve the request to `denied`, so a resolved card
+ * consults this to read a park neutrally rather than as a denial.
+ */
+export const GUARDIAN_PARK_ACTION_VALUES = [
+  "leave_unverified",
+] as const satisfies readonly GuardianDecisionActionId[];
+
+const DENYING_ACTIONS: ReadonlySet<string> = new Set(
+  GUARDIAN_DENYING_ACTION_VALUES,
+);
+const PARK_ACTIONS: ReadonlySet<string> = new Set(GUARDIAN_PARK_ACTION_VALUES);
+
+/** True when `action` resolves a request to `denied`. */
+export function isDenyingGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && DENYING_ACTIONS.has(action);
+}
+
+/** True when `action` parks the sender at `unverified`. */
+export function isParkGuardianAction(action: string | undefined): boolean {
+  return action !== undefined && PARK_ACTIONS.has(action);
+}
+
+/**
+ * Surface-agnostic weight of a card action. Each renderer translates it to
+ * its own token (Slack primary/danger, a web button variant); absent means the
+ * renderer's default.
+ */
+export const GUARDIAN_ACTION_EMPHASIS_VALUES = [
+  "primary",
+  "secondary",
+  "destructive",
+] as const;
+export const GuardianActionEmphasisSchema = z.enum(
+  GUARDIAN_ACTION_EMPHASIS_VALUES,
+);
+export type GuardianActionEmphasis = z.infer<
+  typeof GuardianActionEmphasisSchema
+>;