@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/runtime/routes/oauth-request-hints.ts

@@ -0,0 +1,149 @@
+/**
+ * The hint the request doors attach to a provider response, composed from
+ * the response and the connection facts alone. The route gathers the facts;
+ * nothing here reads a store, a config, or a connection, so a hint's wording
+ * is assertable without booting the route.
+ *
+ * The status hints are an ordered list and the first rule that applies wins.
+ * The order is precedence, not coincidence: a provider's own reported failure
+ * outranks every status, and an HTML 403 must be judged before the generic
+ * 401/403 rule or it is never reached. The missing-scope hint is not a rule
+ * in the list; it is prepended to whichever hint applied, or stands alone.
+ */
+
+export interface RequestHintFacts {
+  /** The provider key the request was made under. */
+  provider: string;
+  status: number;
+  headers: Record<string, string>;
+  /**
+   * The provider's own one-line account of a refusal inside a 2xx, from its
+   * declared ok field; absent when the status is the whole verdict.
+   */
+  reportedFailure?: string;
+  /**
+   * The channel whose bot credential served the request. Absent when the
+   * request acted as a person through their OAuth integration.
+   */
+  botChannel?: string;
+  /** The provider runs in platform-managed mode. */
+  managed: boolean;
+  /**
+   * The base URL the request resolved against: an absolute URL's own origin,
+   * otherwise the provider's configured base. Absent when neither is set.
+   */
+  resolvedBaseUrl?: string;
+  /** Required scopes the resolved connection's stored grant lacks. */
+  missingScopes: readonly string[];
+}
+
+interface RequestHintRule {
+  name: string;
+  applies(facts: RequestHintFacts): boolean;
+  render(facts: RequestHintFacts): string;
+}
+
+/** The status hints in precedence order; the first rule that applies wins. */
+export const REQUEST_HINT_RULES: readonly RequestHintRule[] = [
+  {
+    // The body carries the provider's own error code, so the hint says only
+    // why a 2xx is being reported as a failure.
+    name: "provider reported failure",
+    applies: (facts) => facts.reportedFailure !== undefined,
+    render: (facts) =>
+      `${facts.reportedFailure} in the response body. The body names the error.`,
+  },
+  {
+    // An API refuses with JSON. A 403 carrying an HTML page is a resource
+    // host (a file host, a sign-in page) refusing this identity: the same
+    // token is what the API accepts, and the resource is simply not visible
+    // to it. Blaming the credential sends the caller off to reconnect one
+    // that works.
+    name: "resource not visible",
+    applies: (facts) => facts.status === 403 && isHtmlResponse(facts.headers),
+    render: (facts) => {
+      const identity = facts.botChannel
+        ? `${facts.botChannel} bot`
+        : "connected account";
+      const requestHost = hostnameOf(facts.resolvedBaseUrl);
+      return (
+        `Request returned HTTP 403 with an HTML page${requestHost ? ` from ${requestHost}` : ""}, not an API error. ` +
+        `That usually means the ${identity} cannot see this resource: it is not shared with it, or the scope it needs is missing. ` +
+        `Check the resource's access before treating the credential as revoked; ` +
+        (facts.botChannel
+          ? `'assistant channels get ${facts.botChannel}' reports the credential itself.`
+          : `'assistant oauth status ${facts.provider}' reports the credential itself.`)
+      );
+    },
+  },
+  {
+    // The recovery steps follow the credential's kind, not the door the
+    // request came through: a channel bot's token was stored by the channel's
+    // setup, so the OAuth status and connect commands cannot repair it.
+    name: "credential rejected",
+    applies: (facts) => facts.status === 401 || facts.status === 403,
+    render: (facts) =>
+      facts.botChannel
+        ? `Request returned HTTP ${facts.status}. The ${facts.botChannel} bot credential was rejected; it may have been revoked or reinstalled with fewer scopes.\n\n` +
+          `Run 'assistant channels get ${facts.botChannel}' to re-probe the channel and see what it reports.\n` +
+          `To reconnect, run the channel's setup skill again.`
+        : facts.managed
+          ? `Request returned HTTP ${facts.status}. The OAuth token may be expired or revoked.\n\n` +
+            `Run 'assistant oauth status ${facts.provider}' to check connection health.\n` +
+            `To reconnect, run 'assistant oauth connect --help'.`
+          : `Request returned HTTP ${facts.status}. The OAuth token may be expired or revoked.\n\n` +
+            `Run 'assistant oauth status ${facts.provider}' to check connection status.\n` +
+            `To reconnect, run 'assistant oauth connect --help'.`,
+  },
+  {
+    // An HTML 404 (rather than a JSON API error) is the signature of a request
+    // reaching a valid host but a path that host does not serve, such as a
+    // relative path resolved against a base URL that points at the wrong
+    // product. Surface the resolved base so the caller can tell where the path
+    // landed, and steer them to an absolute URL for non-default services.
+    name: "path not served",
+    applies: (facts) => facts.status === 404 && isHtmlResponse(facts.headers),
+    render: (facts) =>
+      `Request returned HTTP ${facts.status} with an HTML body, which usually means ` +
+      `the path does not exist on the base URL it resolved against.\n\n` +
+      `This request used base URL "${facts.resolvedBaseUrl ?? "(none configured)"}" (relative paths are joined onto it). ` +
+      `If you meant a different service on this provider, pass an absolute URL ` +
+      `(e.g. https://host/full/path) so the host and full path are set explicitly.`,
+  },
+];
+
+/**
+ * The hint for one provider response, or undefined when nothing applies.
+ * A missing-scope hint is prepended to the status hint, or stands alone: a
+ * connection made before a scope was required keeps working for every call
+ * that does not need it, so the gap is named on every request.
+ */
+export function composeRequestHint(
+  facts: RequestHintFacts,
+): string | undefined {
+  const hint = REQUEST_HINT_RULES.find((rule) => rule.applies(facts))?.render(
+    facts,
+  );
+  if (facts.missingScopes.length === 0) {
+    return hint;
+  }
+  const scopeHint =
+    `The ${facts.provider} connection is missing required scopes: ${facts.missingScopes.join(", ")}. ` +
+    `It was connected before they were required, so calls that need them fail. ` +
+    `Reconnect it from Integrations, or run 'assistant oauth connect ${facts.provider}', to grant them.`;
+  return hint ? `${scopeHint}\n\n${hint}` : scopeHint;
+}
+
+/** True when the response's Content-Type header indicates an HTML body. */
+function isHtmlResponse(headers: Record<string, string>): boolean {
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === "content-type") {
+      return value.toLowerCase().includes("text/html");
+    }
+  }
+  return false;
+}
+
+function hostnameOf(url: string | undefined): string | undefined {
+  return url && URL.canParse(url) ? new URL(url).hostname : undefined;
+}

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

@@ -226,6 +226,12 @@ const mcpPluginIntegrationSchema = z.object({
   }),
   logo: z.string(),
   oauthProvider: z.string().optional(),
+  category: z
+    .string()
+    .optional()
+    .describe(
+      "Where the integrations catalog files the entry: a slug from the shared integration-category vocabulary, passed through as the catalog declares it.",
+    ),
 });
 
 const pluginSearchMatchSchema = z.object({

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

@@ -379,16 +379,55 @@ const createRequestSchema = z.object({
   tags: z.array(z.string()).optional().describe("Tag slugs"),
 });
 
+/** Item fields the roadmap service reserves for staff on an update. */
+const STAFF_ONLY_UPDATE_FIELDS = new Set(["status", "tags"]);
+
+function listFields(fields: string[]): string {
+  return `${fields.join(", ")} ${fields.length === 1 ? "is" : "are"}`;
+}
+
+/**
+ * Why an update carrying fields other than title and description is refused.
+ * A staff-only field and an unknown one need different remedies, so each is
+ * named for what it is.
+ */
+function unsupportedUpdateFieldsMessage(keys: string[]): string {
+  const staffOnly = keys.filter((k) => STAFF_ONLY_UPDATE_FIELDS.has(k));
+  const unknown = keys.filter((k) => !STAFF_ONLY_UPDATE_FIELDS.has(k));
+  const reasons = [
+    ...(staffOnly.length > 0
+      ? [`${listFields(staffOnly)} set by Vellum staff`]
+      : []),
+    ...(unknown.length > 0
+      ? [`${listFields(unknown)} not a roadmap update field`]
+      : []),
+  ];
+  return `An assistant can change only an item's title and description; ${reasons.join("; ")}.`;
+}
+
+/**
+ * Only the fields the roadmap service lets this assistant change. An
+ * assistant is always the author tier there, never staff, and an author may
+ * edit only an open item's title and description; status and tags are staff
+ * triage and answer 403. Strict, so a caller that sends anything else learns
+ * why here instead of from the upstream refusal.
+ */
 const updateRequestSchema = z
-  .object({
-    title: z.string().optional(),
-    description: z.string().optional(),
-    status: z.string().optional(),
-    tags: z.array(z.string()).optional().describe("Tag slugs"),
-  })
+  .strictObject(
+    {
+      title: z.string().optional(),
+      description: z.string().optional(),
+    },
+    {
+      error: (issue) =>
+        issue.code === "unrecognized_keys"
+          ? unsupportedUpdateFieldsMessage(issue.keys)
+          : undefined,
+    },
+  )
   .refine(
     (patch) => Object.values(patch).some((v) => v !== undefined),
-    "At least one of title, description, status or tags is required.",
+    "At least one of title or description is required.",
   );
 
 type RoadmapItem = z.infer<typeof itemSchema>;
@@ -684,7 +723,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Update a roadmap item",
     description:
-      "Updates a roadmap item. At least one field is required; the roadmap service decides which items this assistant may edit.",
+      "Updates the title or description of a roadmap item this assistant filed, while the item is still open. Status and tags are set by Vellum staff.",
     tags: ["roadmap"],
     pathParams: SLUG_PARAM,
     requestBody: updateRequestSchema,

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

@@ -213,6 +213,7 @@ const scheduleSchema = z.object({
   mode: z.enum(["notify", "execute", "script", "wake", "workflow"]),
   status: z.enum(["active", "firing", "fired", "cancelled"]),
   routingIntent: z.enum(["single_channel", "multi_channel", "all_channels"]),
+  quiet: z.boolean(),
   reuseConversation: z.boolean(),
   wakeConversationId: z.string().nullable(),
   workflowName: z.string().nullable(),
@@ -381,6 +382,7 @@ function serializeSchedule(
     mode: j.mode,
     status: j.status,
     routingIntent: j.routingIntent,
+    quiet: j.quiet,
     reuseConversation: j.reuseConversation,
     wakeConversationId: j.wakeConversationId,
     workflowName: j.workflowName,

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

@@ -16,10 +16,7 @@ import {
 } from "../../acp/acp-credentials.js";
 import {
   getPlatformAssistantId,
-  setPlatformAssistantId,
   setPlatformBaseUrl,
-  setPlatformOrganizationId,
-  setPlatformUserId,
 } from "../../config/env.js";
 import { getConfig } from "../../config/loader.js";
 import { maybeDefaultSpeechToManaged } from "../../config/managed-speech-defaults.js";
@@ -41,6 +38,7 @@ import {
   refreshProvidersAfterSecretChange,
   refreshProvidersForRotatedCredential,
 } from "../../providers/inference/credential-rotation.js";
+import { validateJevApiKey } from "../../providers/jev/client.js";
 import { validateMinimaxApiKey } from "../../providers/minimax/client.js";
 import { validateOpenAIApiKey } from "../../providers/openai/client.js";
 import { validatePoolsideApiKey } from "../../providers/poolside/client.js";
@@ -79,6 +77,48 @@ const log = getLogger("runtime-http");
 const CES_READY_POLL_INTERVAL_MS = 500;
 const CES_READY_POLL_TIMEOUT_MS = 30_000;
 
+const WRITABLE_VELLUM_CREDENTIAL_FIELDS = [
+  "assistant_api_key",
+  "webhook_secret",
+  "platform_base_url",
+] as const;
+
+function isWritableVellumCredentialField(field: string): boolean {
+  return (WRITABLE_VELLUM_CREDENTIAL_FIELDS as readonly string[]).includes(
+    field,
+  );
+}
+
+async function persistCredential(
+  service: string,
+  field: string,
+  value: string,
+): Promise<void> {
+  const key = credentialKey(service, field);
+  const stored = await setSecureKeyAsync(key, value);
+  if (!stored) {
+    throw new InternalError(
+      `Failed to store credential in secure storage (backend: ${getActiveBackendName()})`,
+    );
+  }
+  if (!isNonSecretPlatformField(service, field)) {
+    try {
+      const scrubbed = await scrubStoredCredentialFromTranscripts(value);
+      log.info(
+        { service, field, ...scrubbed },
+        "Credential stored; scrubbed value from recent transcripts",
+      );
+    } catch (err) {
+      log.warn(
+        { err, service, field },
+        "Credential stored, but transcript scrub failed",
+      );
+    }
+  }
+  upsertCredentialMetadata(service, field, {});
+  await syncManualTokenConnection(service);
+}
+
 let apiKeyGeneration = 0;
 
 async function queueApiKeyPropagation(
@@ -263,6 +303,15 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
           );
           return { success: false, error: validation.reason };
         }
+      } else if (name === "typesafe") {
+        const validation = await validateJevApiKey(value);
+        if (!validation.valid) {
+          log.warn(
+            { provider: name, reason: validation.reason },
+            "API key validation failed",
+          );
+          return { success: false, error: validation.reason };
+        }
       }
 
       const stored = await setSecureKeyAsync(
@@ -307,10 +356,50 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
           'For credential type, name must be in "service:field" format (e.g. "github:api_token")',
         );
       }
-      assertMetadataWritable();
       const service = name.slice(0, colonIdx);
       const field = name.slice(colonIdx + 1);
 
+      if (service === "vellum") {
+        if (!isWritableVellumCredentialField(field)) {
+          throw new BadRequestError(
+            `Unknown vellum credential: ${field}. Allowed fields: ${WRITABLE_VELLUM_CREDENTIAL_FIELDS.join(", ")}`,
+          );
+        }
+        assertMetadataWritable();
+        await persistCredential(service, field, value);
+        if (field === "platform_base_url") {
+          setPlatformBaseUrl(value);
+        }
+        if (isPlatformManagedCredential(service, field)) {
+          await refreshProvidersAfterSecretChange();
+          // Close the first-boot race where the startup capability seed ran before
+          // the managed embedding credential was provisioned, leaving skill/CLI
+          // pages unseeded until restart. Detached, must not block the response.
+          void maybeReseedCapabilitiesAfterManagedCredential(getConfig());
+          if (field === "assistant_api_key") {
+            await notifyCesOfAssistantApiKeyUpdate(value, getCesClient());
+          }
+        } else {
+          await refreshProvidersForRotatedCredential(service, field);
+        }
+        if (field === "assistant_api_key" || field === "platform_base_url") {
+          // Managed-speech availability needs the API key, the assistant ID,
+          // and the base URL. Fire on each write that completes a piece of
+          // that set; the hook no-ops until the connection is complete.
+          // Detached, must not block the response.
+          void maybeDefaultSpeechToManaged();
+          // Same last-write-wins shape: the startup syncs no-op before live
+          // registration, so re-enqueue them here. Both dedup and no-op until
+          // the client and assistant id exist.
+          syncWorkspaceIdentityToPlatform();
+          syncAvatarToPlatform();
+        }
+        log.info({ service, field }, "Credential added via HTTP");
+        return { success: true, type, name };
+      }
+
+      assertMetadataWritable();
+
       // Reject an Anthropic API key pasted into the ACP OAuth-token field (a 401
       // footgun) as a 400 rather than letting it persist and fail at runtime.
       if (service === ACP_SERVICE) {
@@ -324,104 +413,8 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
         }
       }
 
-      const key = credentialKey(service, field);
-
-      const TRIMMED_IDENTITY_FIELDS = new Set([
-        "platform_assistant_id",
-        "platform_organization_id",
-        "platform_user_id",
-      ]);
-      const isTrimmedIdentity =
-        service === "vellum" && TRIMMED_IDENTITY_FIELDS.has(field);
-      const effectiveValue = isTrimmedIdentity ? value.trim() : value;
-
-      if (isTrimmedIdentity && effectiveValue === "") {
-        const deleteResult = await deleteSecureKeyAsync(key);
-        if (deleteResult === "error") {
-          throw new InternalError(
-            `Failed to delete stale credential from secure storage: ${service}:${field}`,
-          );
-        }
-        if (field === "platform_assistant_id") {
-          setPlatformAssistantId(undefined);
-        } else if (field === "platform_organization_id") {
-          setPlatformOrganizationId(undefined);
-        } else if (field === "platform_user_id") {
-          setPlatformUserId(undefined);
-        }
-        deleteCredentialMetadata(service, field);
-      } else {
-        const stored = await setSecureKeyAsync(key, effectiveValue);
-        if (!stored) {
-          throw new InternalError(
-            `Failed to store credential in secure storage (backend: ${getActiveBackendName()})`,
-          );
-        }
-        if (!isNonSecretPlatformField(service, field)) {
-          // Same seam as the api_key branch: the scrub runs immediately after
-          // the secure-store write, before side effects that can throw. The
-          // value IS stored at this point; the scrub is best-effort hygiene
-          // and must stay invisible to the caller. Counts only — never the
-          // value.
-          try {
-            const scrubbed =
-              await scrubStoredCredentialFromTranscripts(effectiveValue);
-            log.info(
-              { service, field, ...scrubbed },
-              "Credential stored; scrubbed value from recent transcripts",
-            );
-          } catch (err) {
-            log.warn(
-              { err, service, field },
-              "Credential stored, but transcript scrub failed",
-            );
-          }
-        }
-        upsertCredentialMetadata(service, field, {});
-        await syncManualTokenConnection(service);
-        if (service === "vellum" && field === "platform_base_url") {
-          setPlatformBaseUrl(effectiveValue);
-        }
-        if (service === "vellum" && field === "platform_assistant_id") {
-          setPlatformAssistantId(effectiveValue || undefined);
-        }
-        if (service === "vellum" && field === "platform_organization_id") {
-          setPlatformOrganizationId(effectiveValue || undefined);
-        }
-        if (service === "vellum" && field === "platform_user_id") {
-          setPlatformUserId(effectiveValue || undefined);
-        }
-      }
-      if (isPlatformManagedCredential(service, field)) {
-        await refreshProvidersAfterSecretChange();
-        // Close the first-boot race where the startup capability seed ran before
-        // the managed embedding credential was provisioned, leaving skill/CLI
-        // pages unseeded until restart. Detached — must not block the response.
-        void maybeReseedCapabilitiesAfterManagedCredential(getConfig());
-        if (service === "vellum" && field === "assistant_api_key") {
-          await notifyCesOfAssistantApiKeyUpdate(value, getCesClient());
-        }
-      } else if (!isTrimmedIdentity) {
-        await refreshProvidersForRotatedCredential(service, field);
-      }
-      if (
-        service === "vellum" &&
-        (field === "assistant_api_key" ||
-          field === "platform_assistant_id" ||
-          field === "platform_base_url")
-      ) {
-        // Managed-speech availability needs the API key, the assistant ID,
-        // and the base URL, and the CLI connect path stores all three
-        // concurrently — fire on each so the last write to land triggers the
-        // defaulting; the hook no-ops until the connection is complete.
-        // Detached — must not block the response.
-        void maybeDefaultSpeechToManaged();
-        // Same last-write-wins shape: the startup syncs no-op before live
-        // registration, so re-enqueue them here. Both dedup and no-op until
-        // the client and assistant id exist.
-        syncWorkspaceIdentityToPlatform();
-        syncAvatarToPlatform();
-      }
+      await persistCredential(service, field, value);
+      await refreshProvidersForRotatedCredential(service, field);
       log.info({ service, field }, "Credential added via HTTP");
       return { success: true, type, name };
     }
@@ -464,8 +457,7 @@ async function handleReadSecret({ body }: RouteHandlerArgs) {
   try {
     let accountKey: string;
     let prefetchedResult:
-      | Awaited<ReturnType<typeof getSecureKeyResultAsync>>
-      | undefined;
+      Awaited<ReturnType<typeof getSecureKeyResultAsync>> | undefined;
 
     if (type === "api_key") {
       if (
@@ -609,6 +601,9 @@ async function handleDeleteSecret({ body }: RouteHandlerArgs) {
         );
       }
       const service = name.slice(0, colonIdx);
+      if (service === "vellum") {
+        throw new BadRequestError("Vellum credentials cannot be deleted");
+      }
       const field = name.slice(colonIdx + 1);
       assertMetadataWritable();
       const key = credentialKey(service, field);
@@ -624,21 +619,6 @@ async function handleDeleteSecret({ body }: RouteHandlerArgs) {
         );
       }
       deleteCredentialMetadata(service, field);
-      if (service === "vellum" && field === "platform_base_url") {
-        setPlatformBaseUrl(undefined);
-      }
-      if (service === "vellum" && field === "platform_assistant_id") {
-        setPlatformAssistantId(undefined);
-      }
-      if (service === "vellum" && field === "platform_organization_id") {
-        setPlatformOrganizationId(undefined);
-      }
-      if (service === "vellum" && field === "platform_user_id") {
-        setPlatformUserId(undefined);
-      }
-      if (isPlatformManagedCredential(service, field)) {
-        await refreshProvidersAfterSecretChange();
-      }
       invalidateConnectionsAfterCredentialDelete(affectedConnections);
       log.info({ service, field }, "Credential deleted via HTTP");
       return { success: true, type, name };

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

@@ -662,10 +662,16 @@ async function handleToolPermissionSimulate({ body = {} }: RouteHandlerArgs) {
     const manifestOverride = resolveManifestOverride(toolName);
     // Permission Simulator path: registered tool wins, then explicit
     // manifest override, then the standard inference rules.
-    const executionTarget =
-      getTool(toolName)?.executionTarget ??
-      manifestOverride?.execution_target ??
-      resolveExecutionTarget({ name: toolName });
+    const tool = getTool(toolName);
+    const executionTarget = resolveExecutionTarget(
+      {
+        name: toolName,
+        executionTarget:
+          tool?.executionTarget ?? manifestOverride?.execution_target,
+        getExecutionTarget: tool?.getExecutionTarget,
+      },
+      input,
+    );
     const executionContext =
       isInteractive === false ? "headless" : "conversation";
     const policyContext = { executionTarget, executionContext } as const;

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

@@ -86,7 +86,7 @@ function handleWatcherCreate({ body = {} }: RouteHandlerArgs) {
   const credentialService =
     credentialServiceOverride ?? provider.requiredCredentialService;
 
-  const watcher = createWatcher({
+  return createWatcher({
     name,
     providerId,
     actionPrompt,
@@ -94,8 +94,6 @@ function handleWatcherCreate({ body = {} }: RouteHandlerArgs) {
     pollIntervalMs,
     configJson: config ? JSON.stringify(config) : null,
   });
-
-  return watcher;
 }
 
 function handleWatcherList({ body = {} }: RouteHandlerArgs) {

package/src/runtime/trust-class.test.ts

@@ -1,11 +1,12 @@
 import { afterEach, describe, expect, test } from "bun:test";
 
+import { TRUST_CLASS_VALUES } from "@vellumai/gateway-client";
+
 import { resolveCapabilities } from "./capabilities.js";
 import {
   derivePersonaTrustFlags,
   isContactTrustClass,
   type PersonaTrustFlags,
-  trustClassSchema,
 } from "./trust-class.js";
 
 describe("isContactTrustClass", () => {
@@ -27,7 +28,7 @@ describe("isContactTrustClass", () => {
   test("agrees with derivePersonaTrustFlags for every trust class", () => {
     // The predicate and the persona flags encode the same grouping; pin them
     // together so neither can drift without failing here.
-    for (const trustClass of trustClassSchema.options) {
+    for (const trustClass of TRUST_CLASS_VALUES) {
       expect(isContactTrustClass(trustClass)).toBe(
         derivePersonaTrustFlags(trustClass).isTrustedContact,
       );
@@ -46,7 +47,7 @@ describe("derivePersonaTrustFlags", () => {
   });
 
   test("trusted_contact and unverified_contact derive identical contact flags", () => {
-    // The admission-only equivalence documented on trustClassSchema: the two
+    // The admission-only equivalence documented in trust-class.ts: the two
     // classes must never drift apart at the persona layer.
     const expected: PersonaTrustFlags = {
       trustClass: "trusted_contact",
@@ -82,9 +83,9 @@ describe("derivePersonaTrustFlags", () => {
   });
 
   test("exactly one flag is true for every trust class", () => {
-    // Iterates the Zod enum so a newly added class is covered automatically
+    // Iterates the canonical class list so a newly added class is covered
     // (the helper itself won't compile until the new class gets a case).
-    for (const trustClass of trustClassSchema.options) {
+    for (const trustClass of TRUST_CLASS_VALUES) {
       const flags = derivePersonaTrustFlags(trustClass);
       const trueCount = [
         flags.isGuardian,
@@ -128,7 +129,7 @@ describe("derivePersonaTrustFlags", () => {
       isTrustedContact: "social-engineering-defense",
       isStranger: "stranger-warning",
     };
-    for (const trustClass of trustClassSchema.options) {
+    for (const trustClass of TRUST_CLASS_VALUES) {
       const flags = derivePersonaTrustFlags(trustClass);
       const guidance = resolveCapabilities(trustClass).promptTrustGuidance;
       for (const [flag, expected] of Object.entries(guidanceByFlag)) {

package/src/runtime/trust-class.ts

@@ -1,10 +1,9 @@
 /**
- * Trust classification for an inbound actor — the single source of truth for
- * both the {@link TrustClass} type and the Zod enum ({@link trustClassSchema})
- * that validates it in persisted message metadata.
- *
- * Kept as a leaf module (imports only `zod`) so the runtime trust layer and the
- * persistence schema can share one definition without a circular import.
+ * The daemon's reading of an inbound actor's trust class. The vocabulary
+ * itself ({@link TrustClass}, `TrustClassSchema`) belongs to the gateway,
+ * which classifies every actor; it lives in `@vellumai/gateway-client`
+ * (`trust-verdict-contract.ts`) and is re-exported here, never redeclared.
+ * This module holds what the daemon derives from a class:
  *
  * - `'guardian'`: The sender matches the active guardian binding for this
  *   (assistant, channel). Guardians have full control-plane access and
@@ -21,21 +20,14 @@
  *   actors are fail-closed with no escalation path.
  */
 
-import { z } from "zod";
-
-export const trustClassSchema = z.enum([
-  "guardian",
-  "trusted_contact",
-  "unverified_contact",
-  "unknown",
-]);
+import type { TrustClass } from "@vellumai/gateway-client";
 
-export type TrustClass = z.infer<typeof trustClassSchema>;
+export type { TrustClass };
 
 /**
  * Whether a trust class names a known non-guardian contact — the
  * `trusted_contact` / `unverified_contact` pair whose admission-only
- * equivalence is documented on {@link trustClassSchema}.
+ * equivalence is documented in this module's header.
  *
  * Accepts a raw string (not just `TrustClass`) because several call sites
  * classify trust classes read back from persisted turn metadata, which may
@@ -75,7 +67,7 @@ export interface PersonaTrustFlags {
  *   needs the opposite default — fail closed, so a turn that never resolved an
  *   actor still renders the guardrail rather than a guardian exemption.
  * - `unverified_contact` derives identically to `trusted_contact`, making the
- *   admission-only equivalence documented on {@link trustClassSchema}
+ *   admission-only equivalence documented in this module's header
  *   executable in one place.
  * - The switch is exhaustive with no default: adding a `TrustClass` member is a
  *   compile error here, forcing a deliberate persona decision for the new