@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/runtime/routes/conversation-query-routes.ts

@@ -37,8 +37,9 @@ import {
 } from "../../config/loader.js";
 import { AssistantConfigSchema } from "../../config/schema.js";
 import { getSchemaAtPath } from "../../config/schema-utils.js";
-import { ProfileEntry } from "../../config/schemas/llm.js";
+import { LLMConfigFragment, ProfileEntry } from "../../config/schemas/llm.js";
 import { VALID_MEMORY_EMBEDDING_PROVIDERS } from "../../config/schemas/memory-storage.js";
+import { ServiceModeSchema } from "../../config/schemas/services.js";
 import { getConfigWatcher } from "../../daemon/config-watcher.js";
 import {
   getEmbeddingConfigInfo,
@@ -74,7 +75,7 @@ import { type LogRow } from "../../memory/llm-request-log-store.js";
 import { getMemoryRecallLogByMessageIds } from "../../memory/memory-recall-log-store.js";
 import { getMemoryV2ActivationLogByMessageIds } from "../../memory/memory-v2-activation-log-store.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../memory/v2/constants.js";
-import { getMemoryV3SelectionForInspector } from "../../plugins/defaults/memory-v3-shadow/selection-log-store.js";
+import { getMemoryV3SelectionForInspectorByMessageIds } from "../../plugins/defaults/memory-v3-shadow/selection-log-store.js";
 import {
   createConnection,
   listConnections,
@@ -468,6 +469,187 @@ function readPlainObject(value: unknown): Record<string, unknown> | undefined {
   return value as Record<string, unknown>;
 }
 
+const WireProfileEntry = ProfileEntry.extend({
+  supportsVision: z.boolean().optional(),
+})
+  .passthrough()
+  .meta({ id: "ProfileEntry" });
+
+/**
+ * Wire shape of the `memory` section in config responses. Passthrough
+ * preserves fields beyond `enabled` and `v2` so the client doesn't strip
+ * unrecognised memory config that newer daemons may add.
+ */
+const MemoryWireConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    v2: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
+  })
+  .passthrough()
+  .meta({ id: "MemoryConfig" });
+
+/**
+ * Response schema for `GET /v1/config`.
+ *
+ * Describes the wire shape of the raw `settings.json` response after
+ * context-default filling and vision-flag enrichment. All top-level fields
+ * are optional because the on-disk config may be sparse. Additional
+ * top-level config sections beyond what's typed here are preserved via
+ * passthrough — this schema types the fields that web/macOS clients consume
+ * without restricting the full config surface.
+ */
+const ConfigGetResponseSchema = z
+  .object({
+    llm: z
+      .object({
+        default: LLMConfigFragment.extend({
+          provider_connection: z.string().optional(),
+        }).optional(),
+        profiles: z.record(z.string(), WireProfileEntry).optional(),
+        profileOrder: z.array(z.string()).optional(),
+        activeProfile: z.string().optional(),
+        callSites: z
+          .record(
+            z.string(),
+            LLMConfigFragment.extend({
+              profile: z.string().optional(),
+            }).nullable(),
+          )
+          .optional(),
+        profileSession: z
+          .object({
+            defaultTtlSeconds: z.number().optional(),
+            maxTtlSeconds: z.number().optional(),
+          })
+          .optional(),
+        pricingOverrides: z.array(z.unknown()).optional(),
+      })
+      .passthrough()
+      .optional(),
+    memory: MemoryWireConfigSchema.optional(),
+    services: z
+      .object({
+        "web-search": z
+          .object({
+            mode: ServiceModeSchema.optional(),
+            provider: z.string().optional(),
+          })
+          .passthrough()
+          .optional(),
+        "image-generation": z
+          .object({ mode: ServiceModeSchema.optional() })
+          .passthrough()
+          .optional(),
+        inference: z
+          .object({ mode: ServiceModeSchema.optional() })
+          .passthrough()
+          .optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough()
+  .meta({ id: "ConfigGetResponse" });
+
+/**
+ * Given a `z.object(...)` schema, returns a new schema where every property
+ * is `.nullable().optional()`. Used to express PATCH body semantics where any
+ * field can be `null` (meaning "delete via deep-merge") or omitted (unchanged).
+ */
+function nullablePartial(schema: z.ZodObject<z.ZodRawShape>) {
+  const shape: Record<string, z.ZodType> = {};
+  for (const [key, value] of Object.entries(schema.shape)) {
+    shape[key] = (value as z.ZodType).nullable().optional();
+  }
+  return z.object(shape);
+}
+
+/**
+ * A single profile entry within a PATCH body. All fields are
+ * `.nullable().optional()`: `null` = delete via deep-merge, omitted =
+ * unchanged. Named so HeyAPI generates `ProfilePatchEntry` as a top-level
+ * export in the SDK.
+ */
+const ProfilePatchEntrySchema = nullablePartial(ProfileEntry)
+  .passthrough()
+  .meta({ id: "ProfilePatchEntry" });
+
+/**
+ * A single call-site override within a PATCH body.
+ */
+const CallSiteOverrideDraftSchema = nullablePartial(
+  LLMConfigFragment.extend({ profile: z.string().optional() }),
+)
+  .passthrough()
+  .meta({ id: "CallSiteOverrideDraft" });
+
+/**
+ * Request body schema for `PATCH /v1/config`.
+ *
+ * Mirrors the response shape but every field is `.nullable().optional()`:
+ * omitted keys are left unchanged by the daemon's deep-merge, `null` values
+ * delete the key. Uses the same Zod enums as `ConfigGetResponseSchema` so
+ * the generated SDK produces literal-union types — no hand-written patch
+ * types needed downstream.
+ */
+const ConfigPatchRequestSchema = z
+  .object({
+    llm: z
+      .object({
+        default: nullablePartial(
+          LLMConfigFragment.extend({
+            provider_connection: z.string().optional(),
+          }),
+        )
+          .passthrough()
+          .nullable()
+          .optional(),
+        profiles: z
+          .record(z.string(), ProfilePatchEntrySchema.nullable())
+          .optional(),
+        profileOrder: z.array(z.string()).optional(),
+        activeProfile: z.string().nullable().optional(),
+        callSites: z
+          .record(z.string(), CallSiteOverrideDraftSchema.nullable())
+          .optional(),
+        profileSession: z
+          .object({
+            defaultTtlSeconds: z.number().optional(),
+            maxTtlSeconds: z.number().optional(),
+          })
+          .nullable()
+          .optional(),
+      })
+      .passthrough()
+      .optional(),
+    memory: MemoryWireConfigSchema.nullable().optional(),
+    services: z
+      .object({
+        "web-search": z
+          .object({
+            mode: ServiceModeSchema.optional(),
+            provider: z.string().optional(),
+          })
+          .passthrough()
+          .nullable()
+          .optional(),
+        "image-generation": z
+          .object({ mode: ServiceModeSchema.optional() })
+          .passthrough()
+          .nullable()
+          .optional(),
+        inference: z
+          .object({ mode: ServiceModeSchema.optional() })
+          .passthrough()
+          .nullable()
+          .optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough()
+  .meta({ id: "ConfigPatchRequest" });
+
 function handleGetConfig() {
   try {
     const config = applyContextDefaultsToRawConfig(loadRawConfig());
@@ -623,7 +805,10 @@ async function handlePatchConfig({ body }: RouteHandlerArgs) {
   deepMergeOverwrite(raw, patch);
 
   await commitConfigWrite(raw, "patch");
-  return { ok: true };
+
+  const merged = applyContextDefaultsToRawConfig(loadRawConfig());
+  enrichProfilesWithVisionFlag(merged);
+  return merged;
 }
 
 /**
@@ -950,12 +1135,11 @@ async function handleGetLlmContext({
   // turn finishes — see `assistant/src/memory/conversation-crud.ts`.
   const conversationTotalEstimatedCostUsd =
     conversation?.totalEstimatedCost ?? null;
-  const memoryV3Selection = message
-    ? await getMemoryV3SelectionForInspector(
-        message.conversationId,
-        memoryV2Activation?.turn ?? null,
-      )
-    : null;
+  // v3 selections are keyed to the turn's message ids (stamped by the turn-end
+  // backfill), independent of v2's tracker turn — so the panel shows whenever
+  // the turn has v3 data, regardless of v2/v3 turn-counter drift.
+  const memoryV3Selection =
+    await getMemoryV3SelectionForInspectorByMessageIds(turnMessageIds);
   return {
     messageId,
     conversationKind,
@@ -1201,6 +1385,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get full config",
     description: "Return the raw settings.json configuration object.",
     tags: ["config"],
+    responseBody: ConfigGetResponseSchema,
     handler: handleGetConfig,
   },
   {
@@ -1215,8 +1400,8 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Deep-merge a partial JSON object into the settings.json configuration.",
     tags: ["config"],
-    requestBody: z.record(z.string(), z.unknown()),
-    responseBody: z.object({ ok: z.boolean() }),
+    requestBody: ConfigPatchRequestSchema,
+    responseBody: ConfigGetResponseSchema,
     handler: handlePatchConfig,
   },
   {

package/src/runtime/routes/conversation-routes.ts

@@ -97,6 +97,7 @@ import {
   getOrCreateConversation,
 } from "../../memory/conversation-key-store.js";
 import { searchConversations } from "../../memory/conversation-queries.js";
+import { MEMORY_RETROSPECTIVE_FORK_SOURCE } from "../../memory/memory-retrospective-constants.js";
 import { recordOnboardingEvent } from "../../memory/onboarding-events-store.js";
 import { buildSlackMessageDeepLinks } from "../../messaging/providers/slack/deep-link.js";
 import {
@@ -681,12 +682,23 @@ export function handleListMessages({
   // is left visible, the result will render as a standalone orphan because
   // `mergeToolResultsIntoAssistantMessages` has nothing to merge it into.
   //
+  // Exception: memory-retrospective fork conversations show their hidden rows
+  // (the retrospective instruction) so the run is readable as a distinct turn
+  // and its LLM call is inspectable. The instruction row also separates the
+  // copied source tail from the review turn, so `mergeConsecutiveAssistantMessages`
+  // no longer folds the review into the source's last assistant message. This
+  // is display-only and scoped to the fork source; the LLM-side `getMessages`
+  // loader is unfiltered regardless.
+  //
   // Only renderable roles reach this UI-facing transcript. `system` rows (a
   // permitted `MessageRole`, e.g. skill-authored context) are agent-context
   // scaffolding, never a displayed turn, so they are dropped here at the
   // source rather than narrowed away per-client.
+  const isRetrospectiveFork =
+    getConversation(resolvedConversationId)?.source ===
+    MEMORY_RETROSPECTIVE_FORK_SOURCE;
   const visibleFilter = (m: MessageRow) =>
-    !isHiddenMessage(m.metadata) &&
+    (isRetrospectiveFork || !isHiddenMessage(m.metadata)) &&
     (m.role === "user" || m.role === "assistant");
 
   if (isPaginated) {
@@ -1030,6 +1042,7 @@ export function persistOnboardingArtifacts(onboarding: {
   tasks: string[];
   tone: string;
   userName?: string;
+  occupation?: string;
   assistantName?: string;
   priorAssistants?: string[];
   cohort?: string;
@@ -2693,6 +2706,7 @@ export const ROUTES: RouteDefinition[] = [
           tasks: z.array(z.string()),
           tone: z.string(),
           userName: z.string().optional(),
+          occupation: z.string().optional(),
           assistantName: z.string().optional(),
           googleConnected: z.boolean().optional(),
           googleScopes: z.array(z.string()).optional(),

package/src/runtime/routes/credential-prompt-routes.ts

@@ -8,14 +8,12 @@
 
 import { z } from "zod";
 
-import { requestSecretStandalone } from "../../daemon/handlers/shared.js";
-import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
-import { credentialKey } from "../../security/credential-key.js";
-import { setSecureKeyAsync } from "../../security/secure-keys.js";
 import {
-  assertMetadataWritable,
-  upsertCredentialMetadata,
-} from "../../tools/credentials/metadata-store.js";
+  formatSlackChannelStatus,
+  persistPromptedCredential,
+} from "../../credential-execution/prompted-credential.js";
+import { requestSecretStandalone } from "../../daemon/handlers/shared.js";
+import { assertMetadataWritable } from "../../tools/credentials/metadata-store.js";
 import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -37,9 +35,11 @@ const CredentialPromptParams = z.object({
   label: z.string().min(1),
   description: z.string().optional(),
   placeholder: z.string().optional(),
+  usageDescription: z.string().optional(),
   allowedDomains: z.array(z.string()).optional(),
   allowedTools: z.array(z.string()).optional(),
   injectionTemplates: z.array(InjectionTemplateSchema).optional(),
+  conversationId: z.string().optional(),
 });
 
 // ---------------------------------------------------------------------------
@@ -51,6 +51,7 @@ export type CredentialPromptResult = {
   error?: string;
   service?: string;
   field?: string;
+  message?: string;
 };
 
 // ---------------------------------------------------------------------------
@@ -68,8 +69,10 @@ async function handleCredentialPrompt({ body = {} }: RouteHandlerArgs) {
     label: validated.label,
     description: validated.description,
     placeholder: validated.placeholder,
+    purpose: validated.usageDescription,
     allowedTools: validated.allowedTools,
     allowedDomains: validated.allowedDomains,
+    conversationId: validated.conversationId,
   });
 
   if (!result.value) {
@@ -80,23 +83,41 @@ async function handleCredentialPrompt({ body = {} }: RouteHandlerArgs) {
     return { ok: false, error: reason };
   }
 
-  const key = credentialKey(validated.service, validated.field);
-  const stored = await setSecureKeyAsync(key, result.value);
-  if (!stored) {
-    return { ok: false, error: "Failed to store credential" };
+  const persisted = await persistPromptedCredential({
+    service: validated.service,
+    field: validated.field,
+    value: result.value,
+    delivery: result.delivery,
+    policy: {
+      allowedTools: validated.allowedTools,
+      allowedDomains: validated.allowedDomains,
+      usageDescription: validated.usageDescription,
+      injectionTemplates: validated.injectionTemplates,
+    },
+  });
+
+  if (persisted.outcome === "error") {
+    return { ok: false, error: persisted.message };
   }
 
-  upsertCredentialMetadata(validated.service, validated.field, {
-    allowedTools: validated.allowedTools,
-    allowedDomains: validated.allowedDomains,
-    injectionTemplates: validated.injectionTemplates,
-  });
-  await syncManualTokenConnection(validated.service);
+  if (persisted.outcome === "transient") {
+    return {
+      ok: true,
+      service: validated.service,
+      field: validated.field,
+      message: `One-time credential provided for ${validated.service}/${validated.field}. The value was not saved and will be consumed by the next operation.`,
+    };
+  }
+
+  const slackStatus = persisted.slackChannel
+    ? formatSlackChannelStatus(persisted.slackChannel).trim()
+    : "";
 
   return {
     ok: true,
     service: validated.service,
     field: validated.field,
+    message: slackStatus.length > 0 ? slackStatus : undefined,
   };
 }
 
@@ -124,6 +145,7 @@ export const ROUTES: RouteDefinition[] = [
       error: z.string().optional(),
       service: z.string().optional(),
       field: z.string().optional(),
+      message: z.string().optional(),
     }),
   },
 ];

package/src/runtime/routes/empty-state-greeting-cache.ts

@@ -0,0 +1,65 @@
+/**
+ * Caching layer for the empty-state (new-chat) greeting generated via the
+ * `POST /v1/btw` side-chain with `conversationKey: "greeting"`.
+ *
+ * Stores a single greeting string with a configurable TTL
+ * (`ui.emptyStateGreetingCacheTtlMs`, default 4h). A TTL of `0` (or less)
+ * disables caching entirely — reads always miss and writes are skipped — so
+ * the greeting regenerates on every request. This is the knob a workspace
+ * sets to always receive a fresh greeting.
+ *
+ * Storage uses the existing `memory_checkpoints` table (simple key-value
+ * store), mirroring {@link ./identity-intro-cache.ts}.
+ */
+
+import { getConfig } from "../../config/loader.js";
+import {
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../../memory/checkpoints.js";
+
+const CHECKPOINT_KEY_TEXT = "empty_state:greeting:text";
+const CHECKPOINT_KEY_TIMESTAMP = "empty_state:greeting:cached_at";
+
+function cacheTtlMs(): number {
+  return getConfig().ui.emptyStateGreetingCacheTtlMs;
+}
+
+/**
+ * Return the cached greeting if present and within the configured TTL.
+ * Returns `null` when caching is disabled (TTL <= 0), the cache is empty,
+ * or the entry has expired.
+ */
+export function getCachedEmptyStateGreeting(): string | null {
+  const ttl = cacheTtlMs();
+  if (ttl <= 0) return null; // caching disabled — always regenerate
+
+  try {
+    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
+    const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+    if (!text || !timestampStr) return null;
+
+    const cachedAt = Number(timestampStr);
+    if (Number.isNaN(cachedAt) || Date.now() - cachedAt > ttl) return null;
+
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a freshly generated greeting along with the current timestamp.
+ * No-ops when caching is disabled (TTL <= 0) so a zero-TTL workspace never
+ * writes a stale entry.
+ */
+export function setCachedEmptyStateGreeting(text: string): void {
+  if (cacheTtlMs() <= 0) return; // caching disabled — skip write
+
+  try {
+    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
+    setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, String(Date.now()));
+  } catch {
+    // Cache write failure is non-fatal — next request will regenerate.
+  }
+}

package/src/runtime/routes/heartbeat-routes.ts

@@ -25,6 +25,13 @@ import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError } from "./errors.js";
+import {
+  paginateRuns,
+  parseRunsBeforeCursor,
+  parseRunsLimit,
+  RUNS_NEXT_CURSOR_SCHEMA,
+  RUNS_PAGINATION_QUERY_PARAMS,
+} from "./runs-pagination.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("heartbeat-routes");
@@ -34,15 +41,18 @@ const log = getLogger("heartbeat-routes");
 // ---------------------------------------------------------------------------
 
 function handleListRuns(queryParams: Record<string, string>) {
-  const rawLimit = Number(queryParams.limit ?? 20);
-  const limit = Number.isFinite(rawLimit)
-    ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
-    : 20;
+  const limit = parseRunsLimit(queryParams, 20);
+  const before = parseRunsBeforeCursor(queryParams);
 
-  const runs = listHeartbeatRuns(limit);
+  const { rows, nextCursor } = paginateRuns(
+    listHeartbeatRuns(limit + 1, before),
+    limit,
+    (r) => r.scheduledFor,
+  );
   const now = Date.now();
   return {
-    runs: runs.map((r) => {
+    nextCursor,
+    runs: rows.map((r) => {
       const conversation = r.conversationId
         ? getConversation(r.conversationId)
         : null;
@@ -113,13 +123,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List heartbeat runs",
     description: "Return recent heartbeat conversation runs.",
     tags: ["heartbeat"],
-    queryParams: [
-      {
-        name: "limit",
-        schema: { type: "integer" },
-        description: "Max runs to return (default 20, max 100)",
-      },
-    ],
+    queryParams: RUNS_PAGINATION_QUERY_PARAMS(20),
     responseBody: z.object({
       runs: z
         .array(
@@ -140,6 +144,7 @@ export const ROUTES: RouteDefinition[] = [
           }),
         )
         .describe("Heartbeat run records"),
+      nextCursor: RUNS_NEXT_CURSOR_SCHEMA,
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListRuns(queryParams ?? {}),

package/src/runtime/routes/image-generation-routes.ts

@@ -2,6 +2,10 @@ import { z } from "zod";
 
 import { getConfig } from "../../config/loader.js";
 import { resolveImageGenCredentials } from "../../media/image-credentials.js";
+import {
+  describeImageModels,
+  resolveImageModel,
+} from "../../media/image-models.js";
 import {
   generateImage,
   mapImageGenError,
@@ -77,8 +81,22 @@ async function handleImageGenerationGenerate(
   const config = getConfig();
   const svc = config.services["image-generation"];
 
+  // Resolve tier aliases (fast, quality, openai) to concrete model IDs via
+  // the registry; reject unknown values with the current catalog so the
+  // error is self-describing rather than a stale enum.
+  let resolvedModel = model as string | undefined;
+  if (typeof resolvedModel === "string" && resolvedModel) {
+    const entry = resolveImageModel(resolvedModel);
+    if (!entry) {
+      throw new BadRequestError(
+        `Unknown model "${resolvedModel}". Available models and aliases:\n${describeImageModels()}`,
+      );
+    }
+    resolvedModel = entry.id;
+  }
+
   // Derive provider from explicit model override when supplied
-  const provider = providerForModel(model, svc.provider);
+  const provider = providerForModel(resolvedModel, svc.provider);
 
   // Resolve credentials
   const { credentials, errorHint } = await resolveImageGenCredentials({
@@ -103,7 +121,7 @@ async function handleImageGenerationGenerate(
       sourceImages: sourceImages as
         | Array<{ mimeType: string; dataBase64: string }>
         | undefined,
-      model: (model as string | undefined) ?? svc.model,
+      model: resolvedModel ?? svc.model,
       variants: clampedVariants,
     });
 

package/src/runtime/routes/inbound-message-handler.ts

@@ -4,6 +4,8 @@
  * verification, guardian action answers, approval interception, and
  * invite token redemption.
  */
+import type { SourceMetadata } from "@vellumai/gateway-client";
+
 import {
   attachmentsToContentBlocks,
   type MessageAttachmentInput,
@@ -127,16 +129,16 @@ function trimMetadataString(
 
 function parseSlackActorTimezoneMetadata(
   sourceChannel: string,
-  metadata: Record<string, unknown> | undefined,
+  metadata: SourceMetadata | undefined,
 ): SlackActorTimezoneMetadata | undefined {
   if (sourceChannel !== "slack") return undefined;
 
-  const timezone = trimMetadataString(metadata, "timezone");
-  const timezoneLabel = trimMetadataString(metadata, "timezoneLabel");
-  const rawOffset = metadata?.timezoneOffsetSeconds;
+  const timezone = metadata?.timezone?.trim() || undefined;
+  const timezoneLabel = metadata?.timezoneLabel?.trim() || undefined;
   const timezoneOffsetSeconds =
-    typeof rawOffset === "number" && Number.isFinite(rawOffset)
-      ? rawOffset
+    metadata?.timezoneOffsetSeconds != null &&
+    Number.isFinite(metadata.timezoneOffsetSeconds)
+      ? metadata.timezoneOffsetSeconds
       : undefined;
 
   if (
@@ -193,17 +195,16 @@ function resolveSlackTranscriptTimestampTimezone(
 
 function resolveInboundClientTimezone(params: {
   bodyClientTimezone?: unknown;
-  sourceMetadata?: Record<string, unknown>;
+  sourceMetadata?: SourceMetadata;
   conversationId: string;
 }): string | undefined {
   const bodyClientTimezone =
     typeof params.bodyClientTimezone === "string"
       ? canonicalizeTimeZone(params.bodyClientTimezone)
       : undefined;
-  const metadataClientTimezone =
-    typeof params.sourceMetadata?.clientTimezone === "string"
-      ? canonicalizeTimeZone(params.sourceMetadata.clientTimezone)
-      : undefined;
+  const metadataClientTimezone = params.sourceMetadata?.clientTimezone
+    ? canonicalizeTimeZone(params.sourceMetadata.clientTimezone)
+    : undefined;
   return (
     bodyClientTimezone ??
     metadataClientTimezone ??
@@ -248,7 +249,7 @@ export async function handleChannelInbound({
     attachmentIds?: string[];
     actorExternalId?: string;
     actorUsername?: string;
-    sourceMetadata?: Record<string, unknown>;
+    sourceMetadata?: SourceMetadata;
     replyCallbackUrl?: string;
     callbackQueryId?: string;
     callbackData?: string;