@k2b/cloud 0.25.0 → 0.27.0

package/src/services/outgoing-mail/store.ts

@@ -0,0 +1,286 @@
+import { type SQL, sql } from "bun";
+import { listApps } from "../../_internal/registry";
+import {
+  type AdminMailApp,
+  type AdminMailProfile,
+  type MailAppAccess,
+  MailAppAccessSchema,
+  type MailErrorCode,
+  type MailProfile,
+  type MailProfileInput,
+  MailProfileInputSchema,
+  MailProfileKeySchema,
+} from "../../contracts/outgoing-mail";
+import type { AppRegistryEntry } from "../../contracts/registry";
+import { type AuditActor, audit } from "../audit";
+import { toPgTextArray } from "../postgres";
+import { decryptValue, encryptValue } from "../settings/crypto";
+
+export class OutgoingMailError extends Error {
+  constructor(
+    public readonly code: MailErrorCode,
+    message: string,
+    public readonly status: 400 | 404 | 409 | 502 = 400,
+  ) {
+    super(message);
+  }
+}
+export type MailAuditContext = { actor: AuditActor; requestId?: string };
+type ProfileRow = {
+  id: string;
+  key: string;
+  name: string;
+  from_address: string;
+  from_name: string | null;
+  smtp_host: string;
+  smtp_port: number;
+  smtp_secure: boolean;
+  smtp_user: string | null;
+  has_password: boolean;
+  pace_per_minute: number;
+  daily_recipient_limit: number | null;
+  max_attachment_bytes: number;
+  is_default: boolean;
+  revision: number;
+  created_at: Date | string;
+  updated_at: Date | string;
+  updated_by: string | null;
+};
+const columns = (db: SQL) => db`id, key, name, from_address, from_name, smtp_host, smtp_port, smtp_secure, smtp_user,
+  (smtp_password_encrypted IS NOT NULL) AS has_password, pace_per_minute, daily_recipient_limit, max_attachment_bytes,
+  is_default, revision, created_at, updated_at, updated_by`;
+const timestamp = (value: Date | string) => new Date(value).toISOString();
+const keyValue = (key: string) => {
+  const result = MailProfileKeySchema.safeParse(key);
+  if (!result.success) throw new OutgoingMailError("invalid_profile", "Invalid profile key.");
+  return result.data;
+};
+const unknown = (): never => {
+  throw new OutgoingMailError("profile_unknown", "Outgoing mail profile does not exist.", 404);
+};
+const locked = async <T>(run: (tx: SQL) => Promise<T>): Promise<T> =>
+  sql.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtextextended('outgoing_mail.policy', 0))`;
+    return run(tx);
+  });
+const record = (db: SQL, context: MailAuditContext, action: string, target: string) =>
+  audit.record(
+    {
+      ...context,
+      action: `outgoing_mail.${action}`,
+      outcome: "allowed",
+      target: { type: action.startsWith("profile.") ? "outgoing_mail_profile" : "outgoing_mail_app", id: target },
+    },
+    db,
+  );
+const accessRows = async (db: SQL) => {
+  const access = await db<{ app_id: string; mode: "default" | "selected" }[]>`SELECT app_id, mode FROM outgoing_mail.app_access`;
+  const grants = await db<
+    { app_id: string; key: string }[]
+  >`SELECT ap.app_id, p.key FROM outgoing_mail.app_profiles ap JOIN outgoing_mail.profiles p ON p.id = ap.profile_id ORDER BY p.key`;
+  return { access, grants };
+};
+const mapProfile = (row: ProfileRow, appCount: number): AdminMailProfile => ({
+  key: row.key,
+  name: row.name,
+  fromAddress: row.from_address,
+  fromName: row.from_name,
+  smtpHost: row.smtp_host,
+  smtpPort: row.smtp_port,
+  smtpSecure: row.smtp_secure,
+  smtpUser: row.smtp_user,
+  hasPassword: row.has_password,
+  pacePerMinute: row.pace_per_minute,
+  dailyRecipientLimit: row.daily_recipient_limit,
+  maxAttachmentBytes: row.max_attachment_bytes,
+  isDefault: row.is_default,
+  revision: row.revision,
+  createdAt: timestamp(row.created_at),
+  updatedAt: timestamp(row.updated_at),
+  updatedBy: row.updated_by,
+  appCount,
+});
+const list = async (db: SQL = sql, registeredApps?: readonly AppRegistryEntry[]): Promise<AdminMailProfile[]> => {
+  const apps = registeredApps ?? (await listApps());
+  const rows = await db<ProfileRow[]>`SELECT ${columns(db)} FROM outgoing_mail.profiles ORDER BY is_default DESC, name, key`;
+  const { access, grants } = await accessRows(db);
+  const selected = new Set(access.filter((a) => a.mode === "selected").map((a) => a.app_id));
+  const defaults = apps.filter((app) => app.platformPermissions?.includes("mail:send") && !selected.has(app.id));
+  return rows.map((row) =>
+    mapProfile(row, grants.filter((g) => g.key === row.key && selected.has(g.app_id)).length + (row.is_default ? defaults.length : 0)),
+  );
+};
+const get = async (key: string): Promise<AdminMailProfile> => {
+  keyValue(key);
+  return (await list()).find((profile) => profile.key === key) ?? unknown();
+};
+const put = async (
+  key: string,
+  value: MailProfileInput,
+  context: MailAuditContext,
+): Promise<{ profile: AdminMailProfile; created: boolean }> => {
+  keyValue(key);
+  const parsed = MailProfileInputSchema.safeParse(value);
+  if (!parsed.success) throw new OutgoingMailError("invalid_profile", "Invalid outgoing mail profile configuration.");
+  const input = parsed.data;
+  const apps = await listApps();
+  return locked(async (tx) => {
+    const [before] = await tx<ProfileRow[]>`SELECT ${columns(tx)} FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (before && input.revision === undefined)
+      throw new OutgoingMailError("profile_exists", "Profile exists; provide its current revision.", 409);
+    if (input.revision !== undefined && (!before || input.revision !== before.revision))
+      throw new OutgoingMailError("revision_conflict", "Profile revision changed; reload before replacing it.", 409);
+    if (
+      before?.has_password &&
+      input.smtpPassword === undefined &&
+      before.smtp_host.trim().toLowerCase() !== input.smtpHost.trim().toLowerCase()
+    )
+      throw new OutgoingMailError("invalid_profile", "Enter the SMTP password again, or remove it, when you change the SMTP host.");
+    const password =
+      input.smtpPassword === undefined ? undefined : input.smtpPassword === null ? null : await encryptValue(input.smtpPassword);
+    if (before) {
+      await tx`UPDATE outgoing_mail.profiles SET name = ${input.name}, from_address = ${input.fromAddress}, from_name = ${input.fromName},
+        smtp_host = ${input.smtpHost}, smtp_port = ${input.smtpPort}, smtp_secure = ${input.smtpSecure}, smtp_user = ${input.smtpUser},
+        smtp_password_encrypted = CASE WHEN ${password !== undefined} THEN ${password ?? null} ELSE smtp_password_encrypted END,
+        pace_per_minute = ${input.pacePerMinute}, daily_recipient_limit = ${input.dailyRecipientLimit}, max_attachment_bytes = ${input.maxAttachmentBytes},
+        revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE key = ${key}`;
+    } else {
+      await tx`INSERT INTO outgoing_mail.profiles(id, key, name, from_address, from_name, smtp_host, smtp_port, smtp_secure, smtp_user,
+        smtp_password_encrypted, pace_per_minute, daily_recipient_limit, max_attachment_bytes, is_default, updated_by)
+        VALUES (${crypto.randomUUID()}::uuid, ${key}, ${input.name}, ${input.fromAddress}, ${input.fromName}, ${input.smtpHost}, ${input.smtpPort},
+          ${input.smtpSecure}, ${input.smtpUser}, ${password ?? null}, ${input.pacePerMinute}, ${input.dailyRecipientLimit}, ${input.maxAttachmentBytes},
+          NOT EXISTS(SELECT 1 FROM outgoing_mail.profiles), ${context.actor.userId ?? null})`;
+    }
+    await record(tx, context, before ? "profile.update" : "profile.create", key);
+    return { profile: (await list(tx, apps)).find((p) => p.key === key)!, created: !before };
+  });
+};
+const setDefault = async (key: string, context: MailAuditContext): Promise<AdminMailProfile> => {
+  keyValue(key);
+  const apps = await listApps();
+  return locked(async (tx) => {
+    const [target] = await tx<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (!target) unknown();
+    await tx`UPDATE outgoing_mail.profiles SET is_default = false, revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE is_default AND key <> ${key}`;
+    await tx`UPDATE outgoing_mail.profiles SET is_default = true, revision = revision + 1, updated_at = now(), updated_by = ${context.actor.userId ?? null} WHERE key = ${key} AND NOT is_default`;
+    await record(tx, context, "profile.set_default", key);
+    return (await list(tx, apps)).find((p) => p.key === key)!;
+  });
+};
+const remove = async (key: string, context: MailAuditContext): Promise<void> => {
+  keyValue(key);
+  await locked(async (tx) => {
+    const [before] = await tx<{ is_default: boolean }[]>`SELECT is_default FROM outgoing_mail.profiles WHERE key = ${key}`;
+    if (!before) return unknown();
+    if (before.is_default)
+      throw new OutgoingMailError("profile_is_default", "Choose another default profile before deleting this one.", 409);
+    await tx`DELETE FROM outgoing_mail.profiles WHERE key = ${key}`;
+    await record(tx, context, "profile.delete", key);
+  });
+};
+const appsState = async (
+  db: SQL = sql,
+  registeredApps?: readonly AppRegistryEntry[],
+): Promise<{ defaultProfile: string | null; items: AdminMailApp[] }> => {
+  const registered = registeredApps ?? (await listApps());
+  const { access, grants } = await accessRows(db);
+  const [profile] = await db<{ key: string }[]>`SELECT key FROM outgoing_mail.profiles WHERE is_default`;
+  const ids = new Set([...registered.map((app) => app.id), ...access.map((a) => a.app_id)]);
+  const items = [...ids]
+    .map((appId): AdminMailApp => {
+      const app = registered.find((a) => a.id === appId);
+      const mode = access.find((a) => a.app_id === appId)?.mode ?? "default";
+      return {
+        appId,
+        name: app?.name ?? appId,
+        registered: !!app,
+        declared: !!app?.platformPermissions?.includes("mail:send"),
+        mode,
+        profiles: mode === "selected" ? grants.filter((g) => g.app_id === appId).map((g) => g.key) : [],
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name) || a.appId.localeCompare(b.appId));
+  return { defaultProfile: profile?.key ?? null, items };
+};
+const setAppAccess = async (appId: string, value: MailAppAccess, context: MailAuditContext): Promise<AdminMailApp> => {
+  if (appId === "core") throw new OutgoingMailError("invalid_profile", "Core's system email always uses the default profile.");
+  if (!appId.trim()) throw new OutgoingMailError("invalid_profile", "Application id is required.");
+  const parsed = MailAppAccessSchema.safeParse(value);
+  if (!parsed.success) throw new OutgoingMailError("invalid_profile", "Invalid application access policy.");
+  const input = parsed.data;
+  const registered = await listApps();
+  return locked(async (tx) => {
+    const keys = input.mode === "selected" ? [...new Set(input.profiles)] : [];
+    const rows = await tx<
+      { id: string; key: string }[]
+    >`SELECT id, key FROM outgoing_mail.profiles WHERE key = ANY(${toPgTextArray(keys)}::text[])`;
+    if (rows.length !== keys.length) throw new OutgoingMailError("profile_unknown", "An outgoing mail profile does not exist.");
+    await tx`DELETE FROM outgoing_mail.app_profiles WHERE app_id = ${appId}`;
+    if (input.mode === "default") await tx`DELETE FROM outgoing_mail.app_access WHERE app_id = ${appId}`;
+    else {
+      await tx`INSERT INTO outgoing_mail.app_access(app_id, mode, updated_by) VALUES (${appId}, 'selected', ${context.actor.userId ?? null})
+        ON CONFLICT(app_id) DO UPDATE SET mode = 'selected', updated_at = now(), updated_by = EXCLUDED.updated_by`;
+      for (const row of rows) await tx`INSERT INTO outgoing_mail.app_profiles(app_id, profile_id) VALUES (${appId}, ${row.id}::uuid)`;
+    }
+    await record(tx, context, "app_access.update", appId);
+    return (
+      (await appsState(tx, registered)).items.find((app) => app.appId === appId) ?? {
+        appId,
+        name: appId,
+        registered: false,
+        declared: false,
+        mode: "default",
+        profiles: [],
+      }
+    );
+  });
+};
+const profilesForApp = async (appId: string): Promise<MailProfile[]> => {
+  const rows = await sql<
+    {
+      key: string;
+      name: string;
+      from_address: string;
+      is_default: boolean;
+      max_attachment_bytes: number;
+      daily_recipient_limit: number | null;
+    }[]
+  >`
+    SELECT p.key, p.name, p.from_address, p.is_default, p.max_attachment_bytes, p.daily_recipient_limit
+    FROM outgoing_mail.profiles p WHERE
+      CASE WHEN EXISTS(SELECT 1 FROM outgoing_mail.app_access WHERE app_id = ${appId} AND mode = 'selected')
+      THEN EXISTS(SELECT 1 FROM outgoing_mail.app_profiles WHERE app_id = ${appId} AND profile_id = p.id)
+      ELSE p.is_default END ORDER BY p.is_default DESC, p.name, p.key`;
+  return rows.map((row) => ({
+    key: row.key,
+    name: row.name,
+    from: row.from_address,
+    default: row.is_default,
+    maxAttachmentBytes: row.max_attachment_bytes,
+    quota: { dailyRecipients: row.daily_recipient_limit, usedLast24h: 0 },
+  }));
+};
+export const outgoingMailStore = { list, get, put, setDefault, delete: remove, apps: appsState, setAppAccess, profilesForApp };
+
+/** Platform email send path only. Never use this helper to shape API or CLI responses. */
+export const resolveMailCredentials = async (key?: string) => {
+  const [row] = await sql<(ProfileRow & { smtp_password_encrypted: string | null })[]>`
+    SELECT ${columns(sql)}, smtp_password_encrypted FROM outgoing_mail.profiles WHERE ${key === undefined ? sql`is_default` : sql`key = ${keyValue(key)}`}`;
+  if (!row)
+    throw new OutgoingMailError(
+      "profile_unknown",
+      key ? "Outgoing mail profile does not exist." : "Configure a default outgoing mail profile before sending email.",
+      404,
+    );
+  const password = row.smtp_password_encrypted === null ? null : await decryptValue(row.smtp_password_encrypted);
+  if (password !== null && typeof password !== "string") throw new Error("Outgoing mail SMTP password is invalid.");
+  return {
+    fromAddress: row.from_address,
+    fromName: row.from_name,
+    smtpHost: row.smtp_host,
+    smtpPort: row.smtp_port,
+    smtpSecure: row.smtp_secure,
+    smtpUser: row.smtp_user,
+    smtpPassword: password,
+  };
+};

package/src/services/outgoing-mail/test-send.ts

@@ -0,0 +1,40 @@
+import { audit } from "../audit";
+import { get } from "../settings";
+import { type MailAuditContext, OutgoingMailError, resolveMailCredentials } from "./store";
+import { buildMailTransport } from "./transport";
+
+export const smtpFailureMessage = (error: unknown, secrets: readonly (string | null)[]): string => {
+  let message = error instanceof Error ? error.message : "SMTP delivery failed.";
+  for (const secret of secrets.filter((s): s is string => !!s)) {
+    for (const representation of [secret, Buffer.from(secret).toString("base64")])
+      message = message.split(representation).join("[REDACTED]");
+  }
+  return message;
+};
+export const outgoingMailTest = {
+  async send(key: string, recipient: string, context: MailAuditContext): Promise<void> {
+    const profile = await resolveMailCredentials(key);
+    const event = { ...context, action: "outgoing_mail.profile.test", target: { type: "outgoing_mail_profile", id: key } };
+    // Fail before the external effect if audit storage is unavailable.
+    await audit.record({ ...event, outcome: "allowed" });
+    const transport = buildMailTransport(profile);
+    try {
+      await transport.sendMail({
+        from: { address: profile.fromAddress, name: profile.fromName ?? (await get<string>("app.name")) },
+        to: recipient,
+        subject: "Cloud test email",
+        text: "This is a test email from Cloud. SMTP delivery is configured correctly if you received it.",
+      });
+    } catch (error) {
+      const message = smtpFailureMessage(error, [
+        profile.smtpPassword,
+        profile.smtpUser,
+        profile.smtpUser ? `\0${profile.smtpUser}\0${profile.smtpPassword ?? ""}` : null,
+      ]);
+      await audit.recordResultAfterSideEffect({ ...event, result: { ok: false, error: { code: "smtp_failed", message, status: 500 } } });
+      throw new OutgoingMailError("smtp_failed", message, 502);
+    } finally {
+      transport.close();
+    }
+  },
+};

package/src/services/outgoing-mail/transport.ts

@@ -0,0 +1,13 @@
+import { createTransport } from "nodemailer";
+import type { resolveMailCredentials } from "./store";
+
+export const buildMailTransport = (profile: Awaited<ReturnType<typeof resolveMailCredentials>>) =>
+  createTransport({
+    host: profile.smtpHost,
+    port: profile.smtpPort,
+    secure: profile.smtpSecure,
+    ...(profile.smtpUser ? { auth: { user: profile.smtpUser, pass: profile.smtpPassword ?? "" } } : {}),
+    connectionTimeout: 10000,
+    greetingTimeout: 10000,
+    socketTimeout: 60000,
+  });

package/src/services/settings/core-settings.ts

@@ -292,7 +292,7 @@ export const CORE_SETTINGS = {
     default: 30,
     min: 0,
     description:
-      "Maximum running time per AI turn. Zero or an empty field disables this limit. Existing turns keep their original budget; request and tool timeouts still apply.",
+      "Maximum running time per AI turn. In the last tenth, the Assistant stops using tools and answers. Zero or an empty field disables this limit. Existing turns keep their original budget; request and tool timeouts still apply.",
   },
   "ai.max_tool_result_chars": {
     kind: "number",
@@ -672,43 +672,6 @@ export const CORE_SETTINGS = {
     description: "Account request denial email template (HTML). Subject: Account Request Update",
     templateVars: ["FIRST_NAME", "REASON", "CONTACT_EMAIL", "APP_NAME"] as readonly string[],
   },
-  "mail.noreply.smtp_host": {
-    kind: "string",
-    label: "SMTP Host",
-    default: "",
-    description: "SMTP server hostname",
-    placeholder: "e.g. smtp.example.org",
-  },
-  "mail.noreply.smtp_port": {
-    kind: "number",
-    label: "SMTP Port",
-    default: 587,
-    min: 1,
-    max: 65535,
-    description: "SMTP server port (587 for STARTTLS, 465 for SSL)",
-  },
-  "mail.noreply.from": {
-    kind: "email",
-    label: "From Address",
-    default: "",
-    description: "From email address",
-    placeholder: "e.g. noreply@example.org",
-  },
-  "mail.noreply.user": {
-    kind: "string",
-    label: "SMTP User",
-    default: "",
-    description: "SMTP username",
-    placeholder: "e.g. noreply@example.org",
-  },
-  "mail.noreply.password": {
-    kind: "secret",
-    label: "SMTP Password",
-    default: "",
-    description: "SMTP password",
-    placeholder: "SMTP password",
-  },
-
   // ── Security ────────────────────────────────────────────────────────────
   "security.rate_limit_per_second": {
     kind: "number",

package/src/services/settings/store.ts

@@ -136,7 +136,11 @@ export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unk
  */
 export const allKnownKeys = (): string[] => SETTINGS.map((d) => d.key);
 
-const knownKeysWith = (extraKnownKeys: readonly string[]) => Array.from(new Set([...allKnownKeys(), ...extraKnownKeys]));
+// Retain the prior SMTP configuration for one release so operators can roll back.
+const retainedLegacyKeys = ["smtp_host", "smtp_port", "from", "user", "password"].map((key) => `mail.noreply.${key}`);
+
+const knownKeysWith = (extraKnownKeys: readonly string[]) =>
+  Array.from(new Set([...allKnownKeys(), ...retainedLegacyKeys, ...extraKnownKeys]));
 
 export const listLegacyKeys = async (extraKnownKeys: readonly string[] = []): Promise<LegacySettingRow[]> => {
   const knownKeys = knownKeysWith(extraKnownKeys);

package/src/shared/ai-model-request-settings.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { AiExtraBodySchema, AiReasoningEffortSchema, AiRequestHeadersSchema } from "./ai-request-options";
+
+export const AiModelRequestSettingsUpdateSchema = z
+  .object({
+    expected: z.string().min(1),
+    reasoningEffort: AiReasoningEffortSchema.nullable(),
+    extraBody: AiExtraBodySchema.nullable().optional(),
+    requestHeaders: AiRequestHeadersSchema.optional(),
+    clearRequestHeaders: z.boolean().optional(),
+  })
+  .strict();
+export type AiModelRequestSettingsUpdate = z.infer<typeof AiModelRequestSettingsUpdateSchema>;
+export const AiModelRequestSettingsSchema = z.object({
+  id: z.string(),
+  reasoningEffort: z.string().nullable(),
+  extraBody: z.record(z.string(), z.unknown()).nullable(),
+  requestHeaderNames: z.array(z.string()),
+  revision: z.string(),
+});
+export type AiModelRequestSettings = z.infer<typeof AiModelRequestSettingsSchema>;

package/src/shared/ai-platform-prompt.ts

@@ -58,7 +58,7 @@ Use search_tools only when the needed operation is unknown. If a loaded Skill or
 {%- if appToolsEnabled %}
 
 # Cloud app tools
-Installed apps publish live Queries and Actions through tool discovery. Calls run with the current user's permissions and the owning app authorizes every call; catalog visibility is not access. Search with a known appId when possible, load only needed names, and treat Query or Action as read/write metadata rather than a search filter. Reuse returned typed resource refs unchanged. Missing tools may be temporary. Claim success only after the call succeeds.
+Installed apps publish live Queries and Actions through tool discovery. Calls run with the current user's permissions and the owning app authorizes every call; catalog visibility is not access. Search with a known appId when possible, load only needed names, and treat Query or Action as read/write metadata rather than a search filter. Reuse returned typed resource refs unchanged. If load_tools reports a tool as unavailable, follow its reason: look up an unknown name once with search_tools; otherwise do not search or retry for it again in this turn, and continue with what is available or tell the user what is missing. Claim success only after the call succeeds.
 {%- endif %}
 {%- if hasFiles %}
 

package/src/shared/ai-request-options.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+
+// nessi 0.15 deep-merges extraBody last. Reserve identity/content, tool/loop
+// control, structured output, and profile-owned generation settings across all
+// adapters so an escape hatch cannot replace Cloud's request or quota budget.
+export const AI_RESERVED_EXTRA_BODY_KEYS = [
+  "model",
+  "models",
+  "route",
+  "messages",
+  "system",
+  "contents",
+  "systemInstruction",
+  "tools",
+  "tool_choice",
+  "toolConfig",
+  "parallel_tool_calls",
+  "stream",
+  "stream_options",
+  "response_format",
+  "structured_outputs",
+  "format",
+  "temperature",
+  "n",
+  "max_tokens",
+  "max_completion_tokens",
+  "reasoning_effort",
+  "reasoning",
+] as const;
+const keyName = (key: string) => key.replace(/_/g, "").toLowerCase();
+const reserved = new Set(AI_RESERVED_EXTRA_BODY_KEYS.map(keyName));
+const unsafeKeys = new Set(["__proto__", "constructor", "prototype"]);
+const nestedReserved = new Map<string, ReadonlySet<string>>([
+  [
+    keyName("generationConfig"),
+    new Set(["responseSchema", "responseJsonSchema", "responseMimeType", "temperature", "maxOutputTokens", "candidateCount"].map(keyName)),
+  ],
+  [keyName("output_config"), new Set(["format"].map(keyName))],
+  [keyName("options"), new Set(["temperature", "num_predict"].map(keyName))],
+]);
+const plainObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null &&
+  typeof value === "object" &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+export const AiReasoningEffortSchema = z.preprocess(
+  (value) => (typeof value === "string" && !value.trim() ? undefined : value),
+  z
+    .string()
+    .trim()
+    .min(1)
+    .max(32)
+    .regex(/^[a-z0-9_-]+$/)
+    .optional(),
+);
+
+export const AiExtraBodySchema = z
+  .custom<Record<string, unknown>>(plainObject, "Extra parameters must be a plain JSON object.")
+  .superRefine((body, ctx) => {
+    if (!plainObject(body)) return;
+    try {
+      if (new TextEncoder().encode(JSON.stringify(body)).byteLength > 8192) {
+        ctx.addIssue({ code: "custom", message: "Extra parameters exceed 8 KiB of UTF-8 JSON." });
+        return;
+      }
+    } catch {
+      ctx.addIssue({ code: "custom", message: "Extra parameters must contain serializable JSON values." });
+      return;
+    }
+    let invalidJson = false;
+    const seen = new Set<object>();
+    const pending: { value: unknown; path: (string | number)[] }[] = [{ value: body, path: [] }];
+    while (pending.length) {
+      const entry = pending.pop()!;
+      const { value, path } = entry;
+      if (
+        value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))
+      )
+        continue;
+      if (!Array.isArray(value) && !plainObject(value)) {
+        invalidJson = true;
+        continue;
+      }
+      if (seen.has(value)) continue;
+      seen.add(value);
+      for (const [key, child] of Object.entries(value)) {
+        if (unsafeKeys.has(key))
+          ctx.addIssue({ code: "custom", path: [...path, key], message: "Prototype keys are not allowed in extra parameters." });
+        pending.push({ value: child, path: [...path, key] });
+      }
+    }
+    if (invalidJson) {
+      ctx.addIssue({ code: "custom", message: "Extra parameters must contain only JSON values." });
+      return;
+    }
+    for (const key of Object.keys(body)) {
+      const normalizedKey = keyName(key);
+      if (reserved.has(normalizedKey))
+        ctx.addIssue({
+          code: "custom",
+          path: [key],
+          message:
+            normalizedKey === "reasoning" || normalizedKey === "reasoningeffort"
+              ? "Use the thinking-level field (reasoningEffort) instead."
+              : "This parameter is owned by Cloud; use the model profile fields instead.",
+        });
+      const nested = body[key];
+      const reservedChildren = nestedReserved.get(normalizedKey);
+      if (reservedChildren && !plainObject(nested))
+        ctx.addIssue({
+          code: "custom",
+          path: [key],
+          message: "This parameter must be a plain JSON object so Cloud can preserve its owned settings.",
+        });
+      if (plainObject(nested))
+        for (const child of Object.keys(nested)) {
+          if (reservedChildren?.has(keyName(child)))
+            ctx.addIssue({
+              code: "custom",
+              path: [key, child],
+              message: "This parameter is owned by Cloud's generation or structured-output settings.",
+            });
+        }
+    }
+  })
+  .meta({
+    type: "object",
+    additionalProperties: true,
+    description: "Extra provider parameters (at most 8192 bytes of UTF-8 JSON); Cloud-owned request keys are reserved.",
+  });
+
+const reservedHeaders = new Set(["content-type", "content-length", "host", "connection", "transfer-encoding"]);
+// Validate with metadata-only messages: never include a submitted header value.
+export const AiRequestHeadersSchema = z
+  .custom<Record<string, string | null>>(plainObject, "Extra headers must be a JSON object of names to strings or null.")
+  .superRefine((headers, ctx) => {
+    if (!plainObject(headers)) return;
+    if (Object.keys(headers).length > 32) ctx.addIssue({ code: "custom", message: "At most 32 extra headers are allowed." });
+    const names = new Set<string>();
+    for (const [name, value] of Object.entries(headers)) {
+      const lower = name.toLowerCase();
+      if (name.length > 128 || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+        ctx.addIssue({ code: "custom", path: [name], message: "Header names must be HTTP tokens of at most 128 characters." });
+      if (names.has(lower)) ctx.addIssue({ code: "custom", path: [name], message: "Duplicate header names are case-insensitive." });
+      names.add(lower);
+      if (reservedHeaders.has(lower)) ctx.addIssue({ code: "custom", path: [name], message: "This HTTP header is reserved." });
+      if (value !== null && (typeof value !== "string" || value.length > 4096 || /[^\t\x20-\x7E]/.test(value)))
+        ctx.addIssue({
+          code: "custom",
+          path: [name],
+          message: "Header values must be strings of at most 4096 printable ASCII characters, spaces or tabs, or null to remove.",
+        });
+    }
+  })
+  .meta({
+    type: "object",
+    maxProperties: 32,
+    propertyNames: { type: "string", maxLength: 128, pattern: "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" },
+    additionalProperties: { anyOf: [{ type: "string", maxLength: 4096, pattern: "^[\\t\\x20-\\x7E]*$" }, { type: "null" }] },
+    writeOnly: true,
+  });
+
+export const AI_REQUEST_HEADERS_PROVIDER_ERROR = "Extra headers are only supported for vLLM and OpenAI-compatible endpoints.";
+export const providerSupportsRequestHeaders = (provider: string): boolean => provider === "vllm" || provider === "openai-compatible";
+
+/** Case-insensitive PATCH. Canonical Authorization avoids duplicate casing in nessi's Bearer overwrite. */
+export const patchAiRequestHeaders = (current: Record<string, string>, patch: Record<string, string | null>): Record<string, string> => {
+  AiRequestHeadersSchema.parse(patch);
+  const result: Record<string, string> = Object.fromEntries(Object.entries(current));
+  for (const [name, value] of Object.entries(patch)) {
+    for (const stored of Object.keys(result)) if (stored.toLowerCase() === name.toLowerCase()) delete result[stored];
+    if (value !== null)
+      Object.defineProperty(result, name.toLowerCase() === "authorization" ? "Authorization" : name, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+      });
+  }
+  AiRequestHeadersSchema.parse(result);
+  return result;
+};

package/src/shared/app-presentation.ts

@@ -27,6 +27,15 @@ const mergedTranslation = (catalog: AppPresentationCatalog, requestedLocale: str
   }, {});
 };
 
+/** Resolve only an app's display name and description, for consumers that carry no other app metadata. */
+export const resolveAppIdentityPresentation = (
+  app: { name: string; description: string; presentation?: AppPresentationCatalog },
+  requestedLocale: string,
+): { name: string; description: string } => {
+  const translation = app.presentation ? mergedTranslation(app.presentation, requestedLocale) : {};
+  return { name: translation.name ?? app.name, description: translation.description ?? app.description };
+};
+
 /** Resolve only human presentation; stable app identity, routes, icons, and authorization stay untouched. */
 export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocale: string): T => {
   if (!app.presentation) return app;
@@ -34,8 +43,7 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
   if (Object.keys(translation).length === 0) return app;
   return {
     ...app,
-    name: translation.name ?? app.name,
-    description: translation.description ?? app.description,
+    ...resolveAppIdentityPresentation(app, requestedLocale),
     adminNav: app.adminNav?.map((group) => ({
       ...group,
       label: (group.id && translation.adminGroups?.[group.id]) || group.label,

package/src/ssr/admin-navigation.ts

@@ -14,7 +14,7 @@ export const buildAdminGroups = (apps: readonly RuntimeContext["apps"][number][]
   const t = platformMessages.resolve([locale]).t;
   const settingsLinks: AdminLink[] = [
     { href: "/admin/settings?tab=general", icon: "ti-app-window", label: t.general },
-    { href: "/admin/settings?tab=mail", icon: "ti-mail", label: "Mail" },
+    { href: "/admin/outgoing-mail", icon: "ti-mail", label: t.outgoingMail },
     { href: "/admin/settings?tab=pdf-rendering", icon: "ti-file-type-pdf", label: t.pdfRendering },
     { href: "/admin/settings?tab=email-templates", icon: "ti-template", label: t.emailTemplates },
     { href: "/admin/settings?tab=security", icon: "ti-shield-lock", label: t.security },