@k2b/cloud 0.25.0 → 0.27.0

package/src/ai/turn-policy.ts

@@ -0,0 +1,247 @@
+import type { Provider, Tool, ToolResolver } from "@k2b/nessi";
+import type { AiToolBlockStatus } from "./protocol";
+
+/** Calls that only find or load other tools. */
+const DISCOVERY_TOOL_NAMES = new Set(["search_tools", "list_apps", "load_tools"]);
+/** Discovery calls in a row, without a completed working step, that earn a hint: three app lookups of search plus load. */
+const DISCOVERY_STREAK_LIMIT = 6;
+/** The last tenth of a turn's run time limit is kept for the answer. */
+const FINAL_ANSWER_BUDGET_SHARE = 0.1;
+
+export type AiTurnFinalReason = "tool_rounds" | "run_time" | "loop";
+export type AiTurnHint = "repeated_failure" | "discovery_loop";
+export type AiTurnPolicyDecision = { kind: "hint"; hints: AiTurnHint[] } | { kind: "final_answer"; reason: AiTurnFinalReason };
+
+/** A finished tool call under the name the model called it by. */
+export type AiTurnPolicyToolCall = { name: string; args?: unknown; status: AiToolBlockStatus; result?: unknown };
+
+const FINAL_ANSWER_CAUSE: Record<AiTurnFinalReason, string> = {
+  tool_rounds: "The configured tool-round budget has been reached, so no more tools are available in this turn.",
+  run_time: "The run time limit of this turn is almost reached, so no more tools are available in this turn.",
+  loop: "This turn kept repeating steps that made no progress, so no more tools are available in this turn.",
+};
+
+const FINAL_ANSWER_CLOSE: Record<AiTurnFinalReason, string> = {
+  tool_rounds: "",
+  run_time: " Say which parts are still open; the user can continue the task with a new message.",
+  loop: " Say what blocked you and what the user can do about it.",
+};
+
+const finalAnswerPrompt = (reason: AiTurnFinalReason) =>
+  `# Final response
+${FINAL_ANSWER_CAUSE[reason]} Answer the user's request now with the best result supported by the evidence already gathered. State any material uncertainty or incomplete part clearly.${FINAL_ANSWER_CLOSE[reason]}`;
+
+const listFormat = new Intl.ListFormat("en", { type: "conjunction" });
+
+/** Names a hint may repeat: only tools the model was offered, never a name it made up. */
+const offeredNames = (names: readonly string[], offered: ReadonlySet<string>) => {
+  const known = names.filter((name) => offered.has(name));
+  return listFormat.format(known.length < names.length ? [...known, "a tool that is not available"] : known);
+};
+
+const hintPrompt = (hints: { repeatedFailures: string[]; discoveryStreak: number | null }, offered: ReadonlySet<string>) =>
+  [
+    "# Turn check",
+    hints.repeatedFailures.length > 0
+      ? `Calls to ${offeredNames(hints.repeatedFailures, offered)} failed twice with the same input. Do not repeat them with that input. Change your approach, or tell the user what blocks you.`
+      : undefined,
+    hints.discoveryStreak !== null
+      ? `You searched for or loaded tools ${hints.discoveryStreak} times in a row without completing another step. Stop searching. Use the tools you already have, load the ones a search found, or tell the user what is not available in this turn.`
+      : undefined,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+/** A completed load_tools call that made at least one more tool callable. */
+const loadedTools = ({ name, status, result }: AiTurnPolicyToolCall) =>
+  name === "load_tools" &&
+  status === "completed" &&
+  typeof result === "object" &&
+  result !== null &&
+  "loaded" in result &&
+  Array.isArray(result.loaded) &&
+  result.loaded.length > 0;
+
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object")
+    return `{${Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+      .join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+};
+
+const withPrompt = (systemPrompt: string | undefined, suffix: string | null) =>
+  suffix ? `${systemPrompt ?? ""}\n\n${suffix}`.trim() : systemPrompt;
+
+/**
+ * Keeps a chat turn from ending without an answer (#530).
+ *
+ * The policy is checked before every model call:
+ * - the same call (tool name and input) failing twice, or six discovery calls
+ *   in a row without a completed working step, adds a one-time hint to the next
+ *   model call;
+ * - either pattern after its hint, a positive `maxToolRounds` that is used up,
+ *   or the last tenth of the run time limit ends tool use: the next model call
+ *   gets no tools and a prompt to answer with what the turn has. If that call
+ *   still asks for tools, the turn fails instead of looping without them.
+ *
+ * Rejected approvals are user decisions, not failures, and loading tools a
+ * search found does not continue a discovery loop. A steering message starts
+ * the loop checks over. The deadline abort stays as the backstop when a single
+ * model or tool call outlasts the reserve. Calls a resumed attempt already
+ * finished seed the counts without a hint of their own; a hint the earlier
+ * attempt gave is not remembered.
+ */
+export const applyAiTurnPolicy = (input: {
+  provider: Provider;
+  tools: Tool[] | ToolResolver;
+  maxToolRounds?: number;
+  issuedToolRounds: number;
+  completedToolRounds: number;
+  /** Epoch milliseconds when the run time limit ends; null without a limit. */
+  deadline: number | null;
+  runBudgetMs: number | null;
+  /** Tool calls this turn finished before this attempt and after its last steering message, oldest first. */
+  finishedToolCalls?: readonly AiTurnPolicyToolCall[];
+  onDecision?: (decision: AiTurnPolicyDecision) => void;
+  now?: () => number;
+}): {
+  provider: Provider;
+  tools: ToolResolver;
+  maxTurns?: number;
+  noteToolRound: () => void;
+  noteToolCall: (call: AiTurnPolicyToolCall) => void;
+  noteSteering: () => void;
+} => {
+  const now = input.now ?? Date.now;
+  const limit = Math.floor(input.maxToolRounds ?? 0);
+  const issuedAtStart = Math.max(0, Math.floor(input.issuedToolRounds));
+  let completed = Math.max(0, Math.floor(input.completedToolRounds));
+  // nessi resolves the tools once more to finish a round an earlier attempt left open.
+  let resumingRound = issuedAtStart > completed;
+  const reserveMs = input.runBudgetMs && input.runBudgetMs > 0 ? input.runBudgetMs * FINAL_ANSWER_BUDGET_SHARE : 0;
+
+  const failures = new Map<string, number>();
+  let repeatedFailures = new Set<string>();
+  let discoveryStreak = 0;
+  // A discovery call since the last check that made no new tool callable.
+  let discoveredSinceCheck = false;
+  const hinted = new Set<AiTurnHint>();
+  let finalReason: AiTurnFinalReason | null = null;
+  let completedAtFinal = 0;
+  let pendingHint: string | null = null;
+  let offered = new Set<string>();
+
+  const noteToolCall = (call: AiTurnPolicyToolCall) => {
+    const { name, args, status } = call;
+    if (status !== "completed" && status !== "failed") return;
+    if (status === "failed") {
+      const key = `${name}\u0000${canonicalJson(args)}`;
+      const count = (failures.get(key) ?? 0) + 1;
+      failures.set(key, count);
+      if (count >= 2) repeatedFailures.add(name);
+    }
+    if (DISCOVERY_TOOL_NAMES.has(name)) {
+      discoveryStreak += 1;
+      if (!loadedTools(call)) discoveredSinceCheck = true;
+    } else if (status === "completed") {
+      discoveryStreak = 0;
+    }
+  };
+  for (const call of input.finishedToolCalls ?? []) noteToolCall(call);
+  repeatedFailures = new Set();
+  discoveredSinceCheck = false;
+
+  const reserveReached = () => input.deadline !== null && reserveMs > 0 && input.deadline - now() <= reserveMs;
+  const endToolUse = (reason: AiTurnFinalReason) => {
+    finalReason = reason;
+    completedAtFinal = completed;
+    pendingHint = null;
+    input.onDecision?.({ kind: "final_answer", reason });
+  };
+
+  const check = () => {
+    if (finalReason) return;
+    if (limit > 0 && completed >= limit) endToolUse("tool_rounds");
+    else if (reserveReached()) endToolUse("run_time");
+    else {
+      const triggered: AiTurnHint[] = [];
+      if (repeatedFailures.size > 0) triggered.push("repeated_failure");
+      if (discoveredSinceCheck && discoveryStreak >= DISCOVERY_STREAK_LIMIT) triggered.push("discovery_loop");
+      if (triggered.some((hint) => hinted.has(hint))) endToolUse("loop");
+      else if (triggered.length > 0) {
+        for (const hint of triggered) hinted.add(hint);
+        pendingHint = hintPrompt(
+          {
+            repeatedFailures: triggered.includes("repeated_failure") ? [...repeatedFailures] : [],
+            discoveryStreak: triggered.includes("discovery_loop") ? discoveryStreak : null,
+          },
+          offered,
+        );
+        input.onDecision?.({ kind: "hint", hints: triggered });
+      }
+    }
+    repeatedFailures = new Set();
+    discoveredSinceCheck = false;
+  };
+
+  const tools: ToolResolver = async () => {
+    if (resumingRound) resumingRound = false;
+    else check();
+    if (finalReason) {
+      if (completed > completedAtFinal) throw new Error("The model did not produce a final answer without tools.");
+      return [];
+    }
+    const resolved = typeof input.tools === "function" ? await input.tools() : input.tools;
+    offered = new Set(resolved.map((tool) => tool.def.name));
+    return resolved;
+  };
+  const provider: Provider = {
+    name: input.provider.name,
+    family: input.provider.family,
+    model: input.provider.model,
+    contextWindow: input.provider.contextWindow,
+    capabilities: input.provider.capabilities,
+    complete: (request) => input.provider.complete(request),
+    stream: async function* (request) {
+      // Compaction may run between the tool check and this call; the reserve still holds.
+      if (!finalReason && reserveReached()) endToolUse("run_time");
+      let overflowed = false;
+      for await (const event of input.provider.stream({
+        ...request,
+        tools: finalReason ? [] : request.tools,
+        systemPrompt: withPrompt(request.systemPrompt, finalReason ? finalAnswerPrompt(finalReason) : pendingHint),
+      })) {
+        if (event.type === "issue" && event.issue.kind === "provider_error" && event.issue.contextOverflow) overflowed = true;
+        yield event;
+      }
+      // nessi compacts an overflowed request and sends it again; the hint goes with it.
+      if (!overflowed) pendingHint = null;
+    },
+  };
+
+  return {
+    provider,
+    tools,
+    // Nessi checks this before provider calls. The extra round is the tool-free
+    // synthesis call after the last allowed tool-using round.
+    ...(limit > 0 ? { maxTurns: Math.max(1, limit - issuedAtStart + 1) } : {}),
+    noteToolRound: () => {
+      completed += 1;
+    },
+    noteToolCall,
+    noteSteering: () => {
+      // New user input: the loop checks start over, and a loop's final answer may use tools again.
+      failures.clear();
+      repeatedFailures = new Set();
+      discoveryStreak = 0;
+      discoveredSinceCheck = false;
+      hinted.clear();
+      pendingHint = null;
+      finalReason = null;
+    },
+  };
+};

package/src/ai/turn-timing.ts

@@ -80,6 +80,36 @@ export function createTurnTimingRecorder(turnId: string, db = sql) {
   };
 }
 
+/**
+ * Time a turn waited for the person: approvals and answers until they were given. A tool the browser runs by itself
+ * waits only until it starts; a secret prompt waits for its answer even though the browser claimed it. An open wait
+ * ends now.
+ */
+const actionWaits = (turnId: string, db: typeof sql) =>
+  db<{ start: Date; end: Date; open: boolean }[]>`SELECT a.created_at AS start,
+    COALESCE(w.end, now()) AS end, w.end IS NULL AS open
+    FROM ai.pending_actions a LEFT JOIN ai.tool_calls t ON t.turn_id=a.turn_id AND t.call_id=a.call_id
+    CROSS JOIN LATERAL (SELECT CASE WHEN a.kind='client_tool' AND a.tool_name<>'code_secret' THEN LEAST(t.started_at,a.resolved_at)
+      ELSE a.resolved_at END AS end) w
+    WHERE a.turn_id=${turnId}::uuid`;
+
+/**
+ * Waits of a running turn by the same rules as its durable timing: `actionWaitMs` is the time already waited, and
+ * `waitingSince` the start of the wait that is still open, overlapping waits counted once.
+ */
+export async function activeTurnWaits(turnId: string, db = sql): Promise<{ actionWaitMs: number; waitingSince: string | null }> {
+  const rows = await actionWaits(turnId, db);
+  const waits = union(rows.map((x) => ({ start: new Date(x.start).getTime(), end: new Date(x.end).getTime() })));
+  const opens = rows.filter((x) => x.open).map((x) => new Date(x.start).getTime());
+  const openStart = opens.length > 0 ? Math.min(...opens) : null;
+  // An open wait reaches until now, so the merged wait that holds it is the last one.
+  const current = openStart === null ? undefined : waits.find((x) => x.start <= openStart && openStart <= x.end);
+  return {
+    actionWaitMs: duration(waits.filter((x) => x !== current)),
+    waitingSince: current ? new Date(current.start).toISOString() : null,
+  };
+}
+
 export async function withDurableTurnTiming(turnId: string, aggregate: LoopAggregate, db = sql): Promise<LoopAggregate> {
   const [turn] = await db<
     { start: Date; end: Date }[]
@@ -95,9 +125,7 @@ export async function withDurableTurnTiming(turnId: string, aggregate: LoopAggre
   const tools = await db<
     { start: Date; end: Date }[]
   >`SELECT started_at AS start,COALESCE(completed_at,now()) AS end FROM ai.tool_calls WHERE turn_id=${turnId}::uuid AND started_at IS NOT NULL`;
-  const waits = await db<{ start: Date; end: Date }[]>`SELECT a.created_at AS start,
-    CASE WHEN a.kind='client_tool' THEN LEAST(COALESCE(t.started_at,a.resolved_at,now()),COALESCE(a.resolved_at,now())) ELSE COALESCE(a.resolved_at,now()) END AS end
-    FROM ai.pending_actions a LEFT JOIN ai.tool_calls t ON t.turn_id=a.turn_id AND t.call_id=a.call_id WHERE a.turn_id=${turnId}::uuid`;
+  const waits = await actionWaits(turnId, db);
   const intervals = (rows: { start: Date; end: Date | null }[]) =>
     rows.flatMap((x) => (x.end ? [{ start: new Date(x.start).getTime(), end: new Date(x.end).getTime() }] : []));
   return {

package/src/ai/types.ts

@@ -45,6 +45,8 @@ export type AiModelProfile = {
   contextWindow?: number;
   temperature?: number;
   maxOutputTokens?: number;
+  reasoningEffort?: string;
+  extraBody?: Record<string, unknown>;
   /** Maximum deferred tools retained per conversation. Missing or <= 0 keeps all loaded tools. */
   maxLoadedTools?: number;
   /** Tool-using model rounds per chat turn. Missing or <= 0 is unlimited. */
@@ -296,7 +298,7 @@ export type AiStoredMessage = {
       trigger: "scheduled" | "manual";
     };
     toolPresentations?: Record<string, AiToolPresentation>;
-    toolOutcomes?: Record<string, "rejected">;
+    toolOutcomes?: Record<string, "rejected" | "approved">;
   } | null;
   /** Private owner feedback for this rendered assistant response. Never enters model context. */
   feedback?: AiMessageFeedback | null;
@@ -510,7 +512,14 @@ export type AiConversationResourceOccurrence = AiConversationResourceRef & {
   chat: Pick<AiConversation, "shortId" | "title" | "updatedAt">;
 };
 
-export type AiConversationSourceKind = "web" | "file" | "resource" | "activity";
+/**
+ * - `result`: something the assistant delivered with `present` (a file, `path` set), `code_open` (an app, `ref` set) or
+ *   `code_present` (a chat visualization, neither set; `sourceCallId` names it).
+ * - `web`: a page read with `web_extract`; `activity`: a web search, one entry per query.
+ * - `resource`: a Cloud resource a tool call read, or one indexed as Project context without a call.
+ * - `file`: a conversation file.
+ */
+export type AiConversationSourceKind = "result" | "web" | "file" | "resource" | "activity";
 
 export type AiConversationSource = {
   kind: AiConversationSourceKind;
@@ -528,15 +537,23 @@ export type AiConversationSource = {
   lastSeenAt: string;
   sourceTurnId: string | null;
   sourceCallId: string | null;
+  /**
+   * Chat position of the source: the assistant message that holds `sourceCallId`, otherwise the start of its turn.
+   * Use it as the `message` link target; null when the turn is gone.
+   */
+  sourceMessageSeq: number | null;
 };
 
 export type AiConversationSourceObservation = {
-  kind: "web" | "activity";
+  kind: "result" | "web" | "activity";
   key: string;
   title: string;
+  /** For `result`, the delivered description; a new delivery always replaces it, also with none. */
   preview?: string;
   icon?: string;
   href?: string;
+  /** The delivered Cloud resource of a `result`, for example an opened app. */
+  ref?: CloudResourceRef;
 };
 
 export type AiConversationFileSnapshotEntry = {
@@ -707,7 +724,11 @@ export type AiConversationService = {
     search?: string;
     before?: string;
     limit?: number;
-  }): Promise<{ sources: AiConversationSource[]; nextCursor?: string }>;
+    /** Only these kinds; all kinds when omitted. */
+    kinds?: readonly AiConversationSourceKind[];
+    /** Only resources a tool call read; leaves out resources indexed as Project context without a call. */
+    observed?: boolean;
+  }): Promise<{ sources: AiConversationSource[]; nextCursor?: string; total: number }>;
   getCapabilityInvocationOrigin(input: { idempotencyKey: string; toolName: string }): Promise<{
     conversationId: string;
     conversationShortId: string;
@@ -864,7 +885,15 @@ export type AiConversationService = {
   getLatestTurn(input: { conversationId: string }): Promise<AiTurn | null>;
   getTurn(input: { conversationId: string; turnId: string }): Promise<AiTurn | null>;
   getTurnByShortId(input: { conversationId: string; shortId: string }): Promise<AiTurn | null>;
-  getActiveTurn(input: { conversationId: string }): Promise<{ turn: AiTurn; liveBlocks: AiTurnBlock[]; liveSeq: number } | null>;
+  getActiveTurn(input: { conversationId: string }): Promise<{
+    turn: AiTurn;
+    liveBlocks: AiTurnBlock[];
+    liveSeq: number;
+    /** Time spent waiting for answered user actions. */
+    actionWaitMs: number;
+    /** Start of the oldest unanswered user action, if the turn waits now. */
+    waitingSince: string | null;
+  } | null>;
   /**
    * Claim a turn attempt. Increments attempt and takes the lease atomically.
    * `from: "queue"` claims queued or lease-expired running turns; `from: "waiting"`
@@ -944,6 +973,8 @@ export type AiConversationService = {
     toolPresentations?: ReadonlyMap<string, AiToolPresentation>;
     /** Mutable call-id set read only when a rejected tool result is persisted. */
     rejectedToolCallIds?: ReadonlySet<string>;
+    /** Mutable call-id set read only when the result of a call the user approved is persisted. */
+    approvedToolCallIds?: ReadonlySet<string>;
   }): SessionStore;
 };
 

package/src/api/admin-ai-quotas.ts

@@ -1,12 +1,15 @@
 import { Hono, type MiddlewareHandler } from "hono";
+import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { AiBackgroundCostError, backgroundCostState, releaseBackgroundCostStop } from "../ai/inference-calls";
 import { setAiModelPricing } from "../ai/model-pricing";
+import { AiModelRequestSettingsInvalid, getAiModelRequestSettings, setAiModelRequestSettings } from "../ai/model-request-settings";
 import { quotaAdminConfig, quotaReport } from "../ai/quota-report";
 import { AiQuotaError, aiQuotas } from "../ai/quotas";
 import { readAiSettingsState } from "../ai/settings";
-import { type AuthContext, auth, v } from "../server";
+import { type AuthContext, auth, jsonResponse, requiresAdmin, v } from "../server";
 import { AiModelPricingSchema, hasBillableAiPricing } from "../shared/ai-costs";
+import { AiModelRequestSettingsSchema, AiModelRequestSettingsUpdateSchema } from "../shared/ai-model-request-settings";
 import {
   AiQuotaConfigSchema,
   AiQuotaIdentitySchema,
@@ -21,6 +24,7 @@ export const createAdminAiQuotaRoutes = (authenticate: MiddlewareHandler<AuthCon
   new Hono<AuthContext>()
     .use("*", authenticate)
     .onError((error, c) => {
+      if (error instanceof AiModelRequestSettingsInvalid) return c.json({ message: error.message }, 400);
       if (error instanceof AiQuotaError || error instanceof AiBackgroundCostError)
         return c.json({ error: error.code, message: error.message }, 409);
       throw error;
@@ -46,6 +50,37 @@ export const createAdminAiQuotaRoutes = (authenticate: MiddlewareHandler<AuthCon
         return c.json(await setAiModelPricing(c.req.param("id")!, data.pricing, data.expected, c.get("user")!.id));
       },
     )
+    .get(
+      "/models/:id/settings",
+      describeRoute({
+        tags: ["Administration"],
+        summary: "Read masked model request settings",
+        ...requiresAdmin,
+        responses: { 200: jsonResponse(AiModelRequestSettingsSchema, "Model request settings (header names only)") },
+      }),
+      async (c) => {
+        c.header("Cache-Control", "no-store");
+        return c.json(await getAiModelRequestSettings(c.req.param("id")!));
+      },
+    )
+    .put(
+      "/models/:id/settings",
+      describeRoute({
+        tags: ["Administration"],
+        summary: "Patch model request settings with a revision guard",
+        ...requiresAdmin,
+        responses: {
+          200: jsonResponse(AiModelRequestSettingsSchema, "Updated model request settings (header names only)"),
+          400: jsonResponse(z.object({ message: z.string() }), "Invalid model request settings"),
+          409: jsonResponse(z.object({ message: z.string(), error: z.string() }), "Model request settings changed"),
+        },
+      }),
+      v("json", AiModelRequestSettingsUpdateSchema),
+      async (c) => {
+        c.header("Cache-Control", "no-store");
+        return c.json(await setAiModelRequestSettings(c.req.param("id")!, c.req.valid("json"), c.get("user")!.id));
+      },
+    )
     .get("/background", async (c) => c.json(await backgroundCostState()))
     .post("/background/release", async (c) => c.json(await releaseBackgroundCostStop(c.get("user")!.id)))
     .get("/report", v("query", AiQuotaReportQuerySchema), async (c) => c.json(await quotaReport(c.req.valid("query"))))

package/src/api/admin-core-settings.ts

@@ -19,6 +19,7 @@ import {
   aiModelAccess,
   splitAiModelAccess,
 } from "../ai/model-access";
+import { listAiRequestHeaderNames, planAiProfileRequestHeaders, storeAiRequestHeaderPlan } from "../ai/request-headers";
 import { parseAiModelProfiles, planAiProfileCredentials, validateAiSettingsConfiguration } from "../ai/settings";
 import { type AiSettingsIssueWithMessage, aiSettingsNotSavedMessage, describeAiSettingsIssues } from "../ai/settings-messages";
 import { type AuthContext, auth, getLocale, jsonResponse, requiresAdmin, v } from "../server";
@@ -27,7 +28,6 @@ import { readAccountCategoryPolicy } from "../services/account-category-policy";
 import { audit } from "../services/audit";
 import { validateFreeIpaCaCert } from "../services/freeipa-config";
 import { testFreeIpaConnection } from "../services/ipa/connection";
-import { sendEmail } from "../services/notifications/email";
 import { GotenbergRenderError, testGotenberg } from "../services/pdf";
 import * as settings from "../services/settings";
 import { SETTINGS_MAP, validateSettingValue } from "../services/settings/defaults";
@@ -43,10 +43,6 @@ const BulkSaveSchema = z.union([
     .strict(),
   z.record(z.string(), z.unknown()).transform((updates) => ({ updates, resets: [] as string[] })),
 ]);
-const TestEmailSchema = z.object({
-  recipient: z.email(),
-});
-
 const LEGAL_DOCUMENTS = [
   { kind: "terms", path: "/legal/terms" },
   { kind: "privacy", path: "/legal/privacy" },
@@ -101,6 +97,7 @@ type AiSettingsMutationPlan = {
   /** Structured validation issues with stable codes; `errors` carries the same messages keyed by setting. */
   issues?: AiSettingsIssueWithMessage[];
   keepCredentialProfileIds?: string[];
+  headerPlan?: ReturnType<typeof planAiProfileRequestHeaders>;
   modelProfileIds?: string[];
 };
 
@@ -168,6 +165,17 @@ const prepareAiSettingsMutation = async (
     keepCredentialProfileIds = credentialPlan.keepCredentialProfileIds;
   }
 
+  const headerPlan =
+    profilesUpdated || profilesReset
+      ? planAiProfileRequestHeaders({
+          currentProfiles: currentParsed.profiles,
+          nextProfiles: nextParsed.profiles,
+          existingNames: profilesUpdated ? await listAiRequestHeaderNames() : {},
+          submitted: aiSplit?.requestHeaders ?? [],
+        })
+      : undefined;
+  if (headerPlan?.error) return { errors: { [AI_PROFILES_KEY]: headerPlan.error } };
+
   const issues = validateAiSettingsConfiguration({
     enabled: nextEnabled,
     defaultModelId: String(valueAfterMutation(AI_DEFAULT_MODEL_KEY, currentDefaultModelId ?? "", updates, resets)),
@@ -183,6 +191,7 @@ const prepareAiSettingsMutation = async (
   return {
     errors: described.errors,
     issues: described.issues,
+    headerPlan,
     keepCredentialProfileIds,
     modelProfileIds: profilesUpdated || profilesReset ? nextParsed.profiles.map((profile) => profile.id) : undefined,
   };
@@ -294,24 +303,6 @@ const app = new Hono<AuthContext>()
   .delete("/legacy", auth.requireRole("admin"), async (c) => {
     return c.json(await settingsDeleteLegacyKeys(await liveSettingKeys()));
   })
-  .post("/test-email", auth.requireRole("admin"), v("json", TestEmailSchema), async (c) => {
-    const { recipient } = c.req.valid("json");
-    const sentAt = new Date().toISOString();
-
-    try {
-      await sendEmail(recipient, "Cloud test email", {
-        rawHtml: `
-          <p>This is a test email from Cloud.</p>
-          <p>If you received this message, SMTP delivery is configured correctly.</p>
-          <p style="margin-top:24px;color:#71717a;font-size:12px;">Sent at ${sentAt}</p>
-        `,
-      });
-      return c.json({ ok: true });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to send test email";
-      return c.json({ message }, 500);
-    }
-  })
   .post("/run-ai-enrichment", auth.requireRole("admin"), async (c) => {
     try {
       // Small manual batch — the cron handles bulk; this is "kick it now".
@@ -463,6 +454,7 @@ const app = new Hono<AuthContext>()
         } else if (aiPlan.keepCredentialProfileIds) {
           await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
         }
+        if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
         if (aiPlan.modelProfileIds) {
           await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, accessChanges, tx);
         }
@@ -524,6 +516,7 @@ const app = new Hono<AuthContext>()
         if (aiPlan.keepCredentialProfileIds) {
           await pruneAiCredentials(aiPlan.keepCredentialProfileIds, tx);
         }
+        if (aiPlan.headerPlan) await storeAiRequestHeaderPlan(aiPlan.headerPlan, tx);
         if (aiPlan.modelProfileIds) {
           await aiModelAccess.syncProfiles(aiPlan.modelProfileIds, [], tx);
         }

package/src/api/admin-outgoing-mail.ts

@@ -0,0 +1,62 @@
+import { type Context, Hono, type MiddlewareHandler } from "hono";
+import { validator } from "hono-openapi";
+import { z } from "zod";
+import { MailAppAccessSchema, MailProfileInputSchema, MailProfileKeySchema } from "../contracts/outgoing-mail";
+import { type AuthContext, auth } from "../server";
+import { type MailAuditContext, OutgoingMailError, outgoingMailStore } from "../services/outgoing-mail/store";
+import { outgoingMailTest } from "../services/outgoing-mail/test-send";
+
+const validate = <Target extends "param" | "json", Schema extends z.ZodType>(target: Target, schema: Schema) =>
+  validator(target, schema, (result, c) => {
+    if (!result.success) {
+      const issue = result.error?.[0];
+      const path = issue?.path?.map((part) => (typeof part === "object" && "key" in part ? String(part.key) : String(part))).join(".");
+      return c.json(
+        {
+          code: "invalid_profile" as const,
+          message: issue ? `${path ? `${path}: ` : ""}${issue.message}` : "Invalid outgoing mail configuration.",
+        },
+        400,
+      );
+    }
+  });
+const context = (c: Context<AuthContext>): MailAuditContext => ({
+  actor: { userId: c.get("user").id, uid: c.get("user").uid, provider: c.get("user").provider, roles: c.get("user").roles },
+  requestId: c.req.header("x-request-id"),
+});
+export const createAdminOutgoingMailRoutes = (authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin")) =>
+  new Hono<AuthContext>()
+    .use("*", authenticate)
+    .use("*", async (c, next) => {
+      c.header("Cache-Control", "no-store");
+      await next();
+    })
+    .onError((error, c) => {
+      if (error instanceof OutgoingMailError) return c.json({ error: error.code, code: error.code, message: error.message }, error.status);
+      throw error;
+    })
+    .get("/profiles", async (c) => c.json({ items: await outgoingMailStore.list() }))
+    .get("/profiles/:key", async (c) => c.json(await outgoingMailStore.get(c.req.param("key"))))
+    .put(
+      "/profiles/:key",
+      validate("param", z.object({ key: MailProfileKeySchema })),
+      validate("json", MailProfileInputSchema),
+      async (c) => {
+        const result = await outgoingMailStore.put(c.req.valid("param").key, c.req.valid("json"), context(c));
+        return c.json(result.profile, result.created ? 201 : 200);
+      },
+    )
+    .post("/profiles/:key/default", async (c) => c.json(await outgoingMailStore.setDefault(c.req.param("key")!, context(c))))
+    .delete("/profiles/:key", async (c) => {
+      await outgoingMailStore.delete(c.req.param("key")!, context(c));
+      return c.body(null, 204);
+    })
+    .post("/profiles/:key/test", validate("json", z.object({ recipient: z.email() }).strict()), async (c) => {
+      await outgoingMailTest.send(c.req.param("key")!, c.req.valid("json").recipient, context(c));
+      return c.json({ ok: true as const });
+    })
+    .get("/apps", async (c) => c.json(await outgoingMailStore.apps()))
+    .put("/apps/:appId", validate("json", MailAppAccessSchema), async (c) =>
+      c.json(await outgoingMailStore.setAppAccess(c.req.param("appId")!, c.req.valid("json"), context(c))),
+    );
+export default createAdminOutgoingMailRoutes();

package/src/api/index.ts

@@ -29,6 +29,7 @@ import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminIdentityRoutes from "./admin-identity";
 import adminLifecycleRoutes from "./admin-lifecycle";
 import adminLinuxIdentityRoutes from "./admin-linux-identities";
+import adminOutgoingMailRoutes from "./admin-outgoing-mail";
 import adminRailRoutes from "./admin-rail";
 import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
 import { createAppApprovalRoutes } from "./app-approval";
@@ -77,6 +78,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/admin/core/ai-projects", adminAiProjectsRoutes)
     .route("/admin/core/ai-skills", adminAiSkillsRoutes)
     .route("/admin/core/announcements", adminAnnouncementRoutes)
+    .route("/admin/core/outgoing-mail", adminOutgoingMailRoutes)
     .route("/admin/core/settings", adminCoreSettingsRoutes)
     .route("/admin/core/rail", adminRailRoutes)
     .route("/admin/core/linux-identities", adminLinuxIdentityRoutes)