@vellumai/assistant 0.10.2-dev.202606242234.c9e9e1d → 0.10.2-dev.202606242332.3fa9b2b

package/bun.lock

@@ -55,6 +55,7 @@
         "@types/node": "25.5.0",
         "@types/semver": "7.5.8",
         "@types/uuid": "10.0.0",
+        "@typescript/native-preview": "7.0.0-dev.20260624.1",
         "ajv": "8.18.0",
         "drizzle-kit": "0.31.10",
         "eslint": "10.0.3",
@@ -455,6 +456,22 @@
 
     "@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.57.0", "", { "dependencies": { "@typescript-eslint/types": "8.57.0", "eslint-visitor-keys": "^5.0.0" } }, "sha512-zm6xx8UT/Xy2oSr2ZXD0pZo7Jx2XsCoID2IUh9YSTFRu7z+WdwYTRk6LhUftm1crwqbuoF6I8zAFeCMw0YjwDg=="],
 
+    "@typescript/native-preview": ["@typescript/native-preview@7.0.0-dev.20260624.1", "", { "optionalDependencies": { "@typescript/native-preview-darwin-arm64": "7.0.0-dev.20260624.1", "@typescript/native-preview-darwin-x64": "7.0.0-dev.20260624.1", "@typescript/native-preview-linux-arm": "7.0.0-dev.20260624.1", "@typescript/native-preview-linux-arm64": "7.0.0-dev.20260624.1", "@typescript/native-preview-linux-x64": "7.0.0-dev.20260624.1", "@typescript/native-preview-win32-arm64": "7.0.0-dev.20260624.1", "@typescript/native-preview-win32-x64": "7.0.0-dev.20260624.1" }, "bin": { "tsgo": "bin/tsgo.js" } }, "sha512-ogwfNo1xuAutOF8RbTCo3Ut0q/65u2ucOeHizi6O14q+3vnelNS+u8qVC2QWXubMcwtuN5E9cbfPslvGC4kdwA=="],
+
+    "@typescript/native-preview-darwin-arm64": ["@typescript/native-preview-darwin-arm64@7.0.0-dev.20260624.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-g8CqDkYCHTCYdhBHXs5cMraBurOS+KrcMFxE0SsaKZoI6Tnp+le1aWvxUBbzNKJYyThHJqb/1mLopzEJxJCuKA=="],
+
+    "@typescript/native-preview-darwin-x64": ["@typescript/native-preview-darwin-x64@7.0.0-dev.20260624.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-P00JVvSV90eioYDuINAKmOSA8yhFTWLq6RvS5lrCfUuDlcgr2kSOgZAfFHIksHBVz6ZXpAXpa0dHPmc5SJ3Ymw=="],
+
+    "@typescript/native-preview-linux-arm": ["@typescript/native-preview-linux-arm@7.0.0-dev.20260624.1", "", { "os": "linux", "cpu": "arm" }, "sha512-eWHELvfQMkVRjafMd+3ATgM9p9yAergJaM4AOY8AekCNWnHFwUrp/ohh+ryyMUIqque5jjb/kuTiOiGj728I2Q=="],
+
+    "@typescript/native-preview-linux-arm64": ["@typescript/native-preview-linux-arm64@7.0.0-dev.20260624.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-cppM2yTZ/Gd1hOXy8NEJcUBxJ0O0zl9CU3OU1ZWZ/OHWWX/ukEzCCr94SUwJhjIWOylBCpIYkrvYoTwxNa94XQ=="],
+
+    "@typescript/native-preview-linux-x64": ["@typescript/native-preview-linux-x64@7.0.0-dev.20260624.1", "", { "os": "linux", "cpu": "x64" }, "sha512-FaB8rS+rKYz4nDrEsHsF3b4cn7eCKCYroMJReA375OuQ6PHcmCNQ6QlVetA0dfFBxTTgejmoKyfw9xgAA5P4Yw=="],
+
+    "@typescript/native-preview-win32-arm64": ["@typescript/native-preview-win32-arm64@7.0.0-dev.20260624.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-BgkqbCmSHDb5UxqWaFlFFJ/DHNT3lEUO4W8627ap6+QthJZuXk2imiHAX3PgYXC6en9fLLyR6jjcseAa4CCshg=="],
+
+    "@typescript/native-preview-win32-x64": ["@typescript/native-preview-win32-x64@7.0.0-dev.20260624.1", "", { "os": "win32", "cpu": "x64" }, "sha512-WaZ+ue63NgB2j/lqjirfevh/TqcsCxSqnKhGGiRnlxHyYIBcoq+x7KngyEnyGIaywJE1PcFeXA+2EMSIPlSEiQ=="],
+
     "@vellumai/ces-client": ["@vellumai/ces-client@file:../packages/ces-client", { "dependencies": { "@vellumai/service-contracts": "file:../service-contracts" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "@vellumai/credential-storage": ["@vellumai/credential-storage@file:../packages/credential-storage", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],

package/node_modules/@vellumai/service-contracts/package.json

@@ -6,6 +6,7 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./channels": "./src/channels.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
     "./ingress": "./src/ingress.ts",
     "./twilio-ingress": "./src/twilio-ingress.ts",

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

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+
+import { CHANNEL_IDS, isChannelId } from "../channels.js";
+
+describe("isChannelId", () => {
+  test("accepts every canonical channel id", () => {
+    for (const id of CHANNEL_IDS) {
+      expect(isChannelId(id)).toBe(true);
+    }
+  });
+
+  test("includes the internal channels no external surface ingresses", () => {
+    // `platform` (control plane) and `vellum` (native app) are part of the
+    // canonical vocabulary even though the gateway never ingresses them. The
+    // gateway's narrower list is a compile-time-asserted subset of this set,
+    // so these must remain canonical for that assertion to mean anything.
+    expect(isChannelId("platform")).toBe(true);
+    expect(isChannelId("vellum")).toBe(true);
+  });
+
+  test("rejects unknown strings and non-string values", () => {
+    expect(isChannelId("discord")).toBe(false);
+    expect(isChannelId("")).toBe(false);
+    expect(isChannelId(undefined)).toBe(false);
+    expect(isChannelId(null)).toBe(false);
+    expect(isChannelId(42)).toBe(false);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical channel-id vocabulary shared between the assistant daemon and the
+ * gateway.
+ *
+ * A "channel" is an external messaging surface an actor can reach the
+ * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
+ * internal ids (`vellum` for native app conversations, `platform` for the
+ * internal control plane). This is the single source of truth for that set:
+ * the assistant adopts it wholesale as its `ChannelId`, and the gateway
+ * asserts its own (narrower) inbound list is a subset of it so the two sides
+ * cannot silently drift.
+ *
+ * Both packages depend on `@vellumai/service-contracts`, so hoisting the set
+ * here (rather than maintaining a copy on each side) means adding or renaming
+ * a channel happens in exactly one place.
+ *
+ * Note that a consumer may legitimately handle only a *subset* of these — the
+ * gateway, for example, never ingresses `platform`. Use a local list guarded
+ * by `satisfies readonly ChannelId[]` for those cases rather than redefining
+ * the union.
+ */
+
+export const CHANNEL_IDS = [
+  "telegram",
+  "phone",
+  "vellum",
+  "whatsapp",
+  "slack",
+  "email",
+  "platform",
+  "a2a",
+] as const;
+
+export type ChannelId = (typeof CHANNEL_IDS)[number];
+
+export function isChannelId(value: unknown): value is ChannelId {
+  return (
+    typeof value === "string" &&
+    (CHANNEL_IDS as readonly string[]).includes(value)
+  );
+}

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -18,6 +18,7 @@
  * module so that both sides can depend on it without circular references.
  */
 
+export * from "./channels.js";
 export * from "./transport.js";
 export * from "./error.js";
 export * from "./handles.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.2-dev.202606242234.c9e9e1d",
+  "version": "0.10.2-dev.202606242332.3fa9b2b",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -24,6 +24,7 @@
     "lint:circular": "bun run scripts/check-circular-deps.ts",
     "lint:unused:production": "knip --production --include exports",
     "typecheck": "bunx tsc --noEmit",
+    "typecheck:fast": "bunx tsgo --noEmit",
     "test": "bash scripts/test.sh",
     "test:coverage": "COVERAGE=true bash scripts/test.sh",
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bash scripts/test.sh",
@@ -106,6 +107,7 @@
     "@types/node": "25.5.0",
     "@types/semver": "7.5.8",
     "@types/uuid": "10.0.0",
+    "@typescript/native-preview": "7.0.0-dev.20260624.1",
     "ajv": "8.18.0",
     "drizzle-kit": "0.31.10",
     "eslint": "10.0.3",

package/src/__tests__/conversation-surfaces-task-progress.test.ts

@@ -336,6 +336,35 @@ describe("task_progress surface compatibility", () => {
     });
   });
 
+  test("ui_show file_upload normalizes a comma-joined acceptedTypes string", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+
+    // The model may emit acceptedTypes as a comma-joined string; the renderer
+    // calls `.join`/`.some` on it, so the daemon hands the client a clean array.
+    const result = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "file_upload",
+      title: "Upload a receipt",
+      data: {
+        prompt: "Share the receipt",
+        acceptedTypes: "image/*, application/pdf",
+      },
+    });
+
+    expect(result.isError).toBe(false);
+
+    const showMessage = sent.find(
+      (msg): msg is UiSurfaceShow => msg.type === "ui_surface_show",
+    );
+    expect(showMessage).toBeDefined();
+    if (!showMessage || showMessage.surfaceType !== "file_upload") return;
+
+    expect(showMessage.data.acceptedTypes).toEqual([
+      "image/*",
+      "application/pdf",
+    ]);
+  });
+
   test("ui_show dynamic_page uses data.html when properly nested", async () => {
     const sent: ServerMessage[] = [];
     const ctx = makeContext(sent);

package/src/__tests__/guardian-expiry-notifier.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Tests for guardian request expiry side effects:
+ *
+ * 1. notifyExpiredGuardianRequest — per-kind behavior (requester notice for
+ *    access_request / tool_grant_request, interaction release for tool_approval,
+ *    no-op for pending_question), Slack DM routing, non-deliverable channels,
+ *    and best-effort (non-throwing) delivery.
+ * 2. Sweep integration — an expired request is transitioned to `expired` and the
+ *    requester is notified through the wired-in notifier.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Silence logging.
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+  truncateForLog: (value: string) => value,
+}));
+
+// Capture requester channel deliveries; optionally fail to exercise the
+// best-effort path.
+const deliveredReplies: Array<{
+  url: string;
+  payload: { chatId: string; text: string; assistantId?: string };
+}> = [];
+let deliveryError: Error | null = null;
+mock.module("../runtime/gateway-client.js", () => ({
+  deliverChannelReply: async (
+    url: string,
+    payload: { chatId: string; text: string; assistantId?: string },
+  ) => {
+    if (deliveryError) throw deliveryError;
+    deliveredReplies.push({ url, payload });
+  },
+}));
+
+// Capture hub broadcasts (interaction_resolved) emitted by pendingInteractions.
+const broadcasts: Array<Record<string, unknown>> = [];
+mock.module("../runtime/assistant-event-hub.js", () => ({
+  broadcastMessage: (msg: Record<string, unknown>) => {
+    broadcasts.push(msg);
+  },
+}));
+
+// The sweep withdraws cards via this module; we only assert it is invoked, and
+// mocking it keeps the sweep import light (no surface/slack transitive deps).
+let withdrawCalls = 0;
+mock.module("../approvals/guardian-card-withdrawal.js", () => ({
+  withdrawGuardianRequestCards: async () => {
+    withdrawCalls++;
+  },
+}));
+
+import { notifyExpiredGuardianRequest } from "../approvals/guardian-expiry-notifier.js";
+import type { CanonicalGuardianRequest } from "../memory/canonical-guardian-store.js";
+import {
+  createCanonicalGuardianRequest,
+  getCanonicalGuardianRequest,
+} from "../memory/canonical-guardian-store.js";
+import { getDb } from "../memory/db-connection.js";
+import { initializeDb } from "../memory/db-init.js";
+import * as pendingInteractions from "../runtime/pending-interactions.js";
+import { sweepExpiredCanonicalGuardianRequests } from "../runtime/routes/canonical-guardian-expiry-sweep.js";
+
+await initializeDb();
+
+/** Build a fully-populated canonical request, overriding the interesting bits. */
+function makeRequest(
+  overrides: Partial<CanonicalGuardianRequest> & { kind: string },
+): CanonicalGuardianRequest {
+  return {
+    id: "req-1",
+    sourceType: "channel",
+    sourceChannel: "telegram",
+    conversationId: "conv-1",
+    requesterExternalUserId: "req-user",
+    requesterChatId: "req-chat",
+    guardianExternalUserId: "guardian-user",
+    guardianPrincipalId: "guardian-principal",
+    callSessionId: null,
+    pendingQuestionId: null,
+    questionText: null,
+    requestCode: "ABC123",
+    toolName: null,
+    inputDigest: null,
+    commandPreview: null,
+    riskLevel: null,
+    activityText: null,
+    executionTarget: null,
+    status: "expired",
+    answerText: null,
+    decidedByExternalUserId: null,
+    decidedByPrincipalId: null,
+    followupState: null,
+    expiresAt: 1000,
+    createdAt: 1000,
+    updatedAt: 2000,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  deliveredReplies.length = 0;
+  broadcasts.length = 0;
+  deliveryError = null;
+  withdrawCalls = 0;
+  pendingInteractions.clear();
+});
+
+describe("notifyExpiredGuardianRequest", () => {
+  test("access_request: notifies the requester on their channel", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({
+        kind: "access_request",
+        sourceChannel: "telegram",
+        requesterChatId: "tg-chat",
+        requesterExternalUserId: "tg-user",
+      }),
+    );
+
+    expect(deliveredReplies).toHaveLength(1);
+    expect(deliveredReplies[0].url).toBe("/deliver/telegram");
+    expect(deliveredReplies[0].payload.chatId).toBe("tg-chat");
+    expect(deliveredReplies[0].payload.text).toContain(
+      "access request expired",
+    );
+  });
+
+  test("access_request on Slack: routes to the requester DM, not the channel", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({
+        kind: "access_request",
+        sourceChannel: "slack",
+        requesterChatId: "C0SHARED",
+        requesterExternalUserId: "U123",
+      }),
+    );
+
+    expect(deliveredReplies).toHaveLength(1);
+    expect(deliveredReplies[0].url).toBe("/deliver/slack");
+    // DM via the user id, never the shared channel id.
+    expect(deliveredReplies[0].payload.chatId).toBe("U123");
+  });
+
+  test("tool_grant_request: notice names the tool", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({
+        kind: "tool_grant_request",
+        sourceChannel: "telegram",
+        requesterChatId: "tg-chat",
+        toolName: "bash",
+      }),
+    );
+
+    expect(deliveredReplies).toHaveLength(1);
+    expect(deliveredReplies[0].payload.text).toContain('"bash"');
+    expect(deliveredReplies[0].payload.text).toContain("expired");
+  });
+
+  test("tool_approval: releases the pending interaction, sends no channel notice", async () => {
+    pendingInteractions.register("req-ta", {
+      conversationId: "conv-1",
+      kind: "confirmation",
+    });
+
+    await notifyExpiredGuardianRequest(
+      makeRequest({ id: "req-ta", kind: "tool_approval" }),
+    );
+
+    expect(pendingInteractions.get("req-ta")).toBeUndefined();
+    const resolvedEvent = broadcasts.find(
+      (b) => b.type === "interaction_resolved",
+    );
+    expect(resolvedEvent).toMatchObject({
+      requestId: "req-ta",
+      state: "cancelled",
+    });
+    expect(deliveredReplies).toHaveLength(0);
+  });
+
+  test("tool_approval: no registered interaction is a safe no-op", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({ id: "req-none", kind: "tool_approval" }),
+    );
+
+    expect(deliveredReplies).toHaveLength(0);
+    expect(broadcasts).toHaveLength(0);
+  });
+
+  test("pending_question: no notice (voice owns its lifecycle)", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({ kind: "pending_question", sourceChannel: "phone" }),
+    );
+
+    expect(deliveredReplies).toHaveLength(0);
+  });
+
+  test("non-deliverable channel: no notice", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({ kind: "access_request", sourceChannel: "vellum" }),
+    );
+
+    expect(deliveredReplies).toHaveLength(0);
+  });
+
+  test("missing requester chat: no notice", async () => {
+    await notifyExpiredGuardianRequest(
+      makeRequest({
+        kind: "access_request",
+        sourceChannel: "telegram",
+        requesterChatId: null,
+        requesterExternalUserId: null,
+      }),
+    );
+
+    expect(deliveredReplies).toHaveLength(0);
+  });
+
+  test("delivery failure is swallowed (best-effort)", async () => {
+    deliveryError = new Error("gateway down");
+
+    await expect(
+      notifyExpiredGuardianRequest(
+        makeRequest({
+          kind: "access_request",
+          sourceChannel: "telegram",
+          requesterChatId: "tg-chat",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+  });
+});
+
+describe("sweep integration", () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.run("DELETE FROM canonical_guardian_requests");
+    db.run("DELETE FROM canonical_guardian_deliveries");
+  });
+
+  test("expired access_request is transitioned and the requester is notified", async () => {
+    const request = createCanonicalGuardianRequest({
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "telegram",
+      requesterChatId: "tg-chat",
+      requesterExternalUserId: "tg-user",
+      guardianPrincipalId: "guardian-principal",
+      expiresAt: Date.now() - 1000, // already past
+    });
+
+    const expiredCount = await sweepExpiredCanonicalGuardianRequests();
+
+    expect(expiredCount).toBe(1);
+    expect(getCanonicalGuardianRequest(request.id)?.status).toBe("expired");
+    expect(withdrawCalls).toBe(1);
+    expect(deliveredReplies).toHaveLength(1);
+    expect(deliveredReplies[0].payload.text).toContain(
+      "access request expired",
+    );
+  });
+
+  test("not-yet-expired requests are left pending and unnotified", async () => {
+    const request = createCanonicalGuardianRequest({
+      kind: "access_request",
+      sourceType: "channel",
+      sourceChannel: "telegram",
+      requesterChatId: "tg-chat",
+      guardianPrincipalId: "guardian-principal",
+      expiresAt: Date.now() + 60_000, // still in the future
+    });
+
+    const expiredCount = await sweepExpiredCanonicalGuardianRequests();
+
+    expect(expiredCount).toBe(0);
+    expect(getCanonicalGuardianRequest(request.id)?.status).toBe("pending");
+    expect(deliveredReplies).toHaveLength(0);
+  });
+});

package/src/__tests__/ui-file-upload-surface.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { FileUploadSurfaceDataSchema } from "../api/surfaces.js";
 import type {
   FileUploadSurfaceData,
   UiSurfaceShowFileUpload,
@@ -103,3 +104,88 @@ describe("UI surface tool registration", () => {
     ]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// FileUploadSurfaceDataSchema coercion
+// ---------------------------------------------------------------------------
+//
+// `acceptedTypes` is contractually a string[], but the model frequently emits a
+// comma-joined string or a bare string. The renderer calls `.join`/`.some` on
+// it, so the schema coerces every shape to the array contract.
+
+describe("FileUploadSurfaceDataSchema coercion", () => {
+  test("passes a well-formed payload through unchanged", () => {
+    expect(
+      FileUploadSurfaceDataSchema.parse({
+        prompt: "Share the receipt PDF",
+        acceptedTypes: ["image/*", "application/pdf"],
+        maxFiles: 3,
+      }),
+    ).toEqual({
+      prompt: "Share the receipt PDF",
+      acceptedTypes: ["image/*", "application/pdf"],
+      maxFiles: 3,
+    });
+  });
+
+  test("coerces a comma-joined acceptedTypes string into an array", () => {
+    expect(
+      FileUploadSurfaceDataSchema.parse({
+        prompt: "p",
+        acceptedTypes: "image/*, application/pdf",
+      }).acceptedTypes,
+    ).toEqual(["image/*", "application/pdf"]);
+  });
+
+  test("wraps a single acceptedTypes string into a one-element array", () => {
+    expect(
+      FileUploadSurfaceDataSchema.parse({ acceptedTypes: "application/pdf" })
+        .acceptedTypes,
+    ).toEqual(["application/pdf"]);
+  });
+
+  test("the parsed acceptedTypes always supports .join", () => {
+    const parsed = FileUploadSurfaceDataSchema.parse({
+      acceptedTypes: "image/*,application/pdf",
+    });
+    // `.join` is the call the renderer makes on `acceptedTypes`.
+    expect(parsed.acceptedTypes?.join(",")).toBe("image/*,application/pdf");
+  });
+
+  test("drops blanks and non-string entries from an array", () => {
+    expect(
+      FileUploadSurfaceDataSchema.parse({
+        acceptedTypes: [" application/pdf ", "", null, 42, {}],
+      }).acceptedTypes,
+    ).toEqual(["application/pdf", "42"]);
+  });
+
+  test("treats a non-string, non-array acceptedTypes as absent", () => {
+    expect(
+      FileUploadSurfaceDataSchema.parse({ acceptedTypes: { pdf: true } })
+        .acceptedTypes,
+    ).toBeUndefined();
+    expect(
+      FileUploadSurfaceDataSchema.parse({ acceptedTypes: null }).acceptedTypes,
+    ).toBeUndefined();
+  });
+
+  test("coerces numeric-string maxFiles and drops invalid numbers", () => {
+    const parsed = FileUploadSurfaceDataSchema.parse({
+      maxFiles: "2",
+      maxSizeBytes: "not-a-number",
+    });
+    expect(parsed.maxFiles).toBe(2);
+    expect(parsed.maxSizeBytes).toBeUndefined();
+  });
+
+  test("never rejects a fully malformed payload", () => {
+    expect(
+      FileUploadSurfaceDataSchema.safeParse({
+        prompt: 5,
+        acceptedTypes: 99,
+        maxFiles: -1,
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/api/index.ts

@@ -477,7 +477,12 @@ export {
   type WorkflowLeaf,
   WorkflowLeafSchema,
 } from "./responses/workflow-journal.js";
-export { type CardSurfaceData, CardSurfaceDataSchema } from "./surfaces.js";
+export {
+  type CardSurfaceData,
+  CardSurfaceDataSchema,
+  type FileUploadSurfaceData,
+  FileUploadSurfaceDataSchema,
+} from "./surfaces.js";
 
 /**
  * Canonical SSE event schema for the assistant runtime.

package/src/api/surfaces.ts

@@ -11,9 +11,9 @@
  * normalizer *supports* — anything the model sends outside these fields is
  * dropped (and logged) there, which is how we learn the shapes to recover.
  *
- * Card is the first surface type migrated to a canonical schema; the remaining
- * types still live as hand-written interfaces in
- * `daemon/message-types/surfaces.ts` pending migration.
+ * Card and file_upload use canonical schemas; the remaining types are
+ * hand-written interfaces in `daemon/message-types/surfaces.ts` pending
+ * migration.
  */
 
 import { z } from "zod";
@@ -31,3 +31,39 @@ export const CardSurfaceDataSchema = z.object({
   templateData: z.record(z.string(), z.unknown()).optional(),
 });
 export type CardSurfaceData = z.infer<typeof CardSurfaceDataSchema>;
+
+/**
+ * Accepted MIME-type / extension patterns for a `file_upload` surface.
+ *
+ * The renderer consumes this as a `string[]` — it calls `.join`/`.some`/
+ * `.length` on the value — but the model may emit a single comma-joined string
+ * ("image/*, application/pdf") or a bare string. Coercing every shape to a
+ * clean `string[]` keeps that array invariant intact: a string is split on
+ * commas; array entries are stringified and trimmed; blanks and any non-array
+ * value collapse to `undefined` (no restriction).
+ */
+const FileUploadAcceptedTypesSchema = z.preprocess((value) => {
+  const items =
+    typeof value === "string"
+      ? value.split(",")
+      : Array.isArray(value)
+        ? value
+        : [];
+  const cleaned = items
+    .map((item) =>
+      typeof item === "string" || typeof item === "number"
+        ? String(item).trim()
+        : "",
+    )
+    .filter((item) => item.length > 0);
+  return cleaned.length > 0 ? cleaned : undefined;
+}, z.array(z.string()).optional());
+
+export const FileUploadSurfaceDataSchema = z.object({
+  prompt: z.coerce.string().optional(),
+  acceptedTypes: FileUploadAcceptedTypesSchema,
+  /** A non-positive or non-numeric value is dropped rather than rejecting the surface. */
+  maxFiles: z.coerce.number().int().positive().optional().catch(undefined),
+  maxSizeBytes: z.coerce.number().positive().optional().catch(undefined),
+});
+export type FileUploadSurfaceData = z.infer<typeof FileUploadSurfaceDataSchema>;

package/src/approvals/guardian-channel-delivery.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared addressing helpers for guardian requester-facing channel notices.
+ *
+ * Requester notices (approval, denial, expiry) are delivered straight to the
+ * requester's chat via `deliverChannelReply` — independent of the
+ * guardian-facing notification pipeline. Centralizing the addressing rules here
+ * keeps the decision resolvers and the timer-driven expiry sweep from drifting
+ * apart on how a requester is reached.
+ */
+
+/**
+ * Resolve the callback-less delivery route for a channel (e.g. `/deliver/slack`).
+ *
+ * Used when there is no inbound reply callback URL to post back to — the
+ * guardian decided off-channel (desktop), or the expiry sweep fired on a timer
+ * with no originating request in hand. Returns null for channels that have no
+ * deliverable route (e.g. email, the in-app vellum surface).
+ */
+export function resolveDeliverCallbackUrlForChannel(
+  channel: string,
+): string | null {
+  switch (channel) {
+    case "telegram":
+    case "whatsapp":
+    case "slack":
+      return `/deliver/${channel}`;
+    default:
+      return null;
+  }
+}