@k2b/cloud 0.26.0 → 0.28.0

package/src/ai/open-tool-calls.ts

@@ -0,0 +1,87 @@
+import type { Message, Provider } from "@k2b/nessi";
+
+/** What the model reads for a call of an earlier turn that never returned. */
+export const AI_OPEN_TOOL_CALL_RESULT =
+  "No result: the turn ended before this call returned, so it may or may not have run. Check its effect before you repeat it.";
+
+/**
+ * nessi answers a call without a directly following result with this text before it calls the provider. It does not
+ * say whether the call ran, and it leaves a result stored after another message apart from its call. nessi does not
+ * export the text; the tests that run a request through nessi fail when it changes.
+ */
+const NESSI_INTERRUPTED_RESULT = "Tool call was interrupted before it returned a result.";
+
+const isNessiAnswer = (message: Message): boolean =>
+  message.role === "tool_result" && message.isError === true && message.result === NESSI_INTERRUPTED_RESULT;
+
+/**
+ * Where each call of the model message at `index` has its result: the first result for it before the next user
+ * message, or before a later model message with a call of the same ID, since some providers reuse call IDs from turn to
+ * turn.
+ */
+const resultsOf = (messages: readonly Message[], index: number, ids: ReadonlySet<string>): Map<string, number> => {
+  const found = new Map<string, number>();
+  for (let next = index + 1; next < messages.length && found.size < ids.size; next++) {
+    const later = messages[next]!;
+    if (later.role === "user") break;
+    if (later.role === "assistant" && later.content.some((block) => block.type === "tool_call" && ids.has(block.id))) break;
+    if (later.role === "tool_result" && ids.has(later.callId) && !found.has(later.callId)) found.set(later.callId, next);
+  }
+  return found;
+};
+
+/**
+ * Gives every call its result right after the message that made it. A call without one gets an error result; a result
+ * stored after another model message, such as a scheduled result delivered while the call ran, moves up to its call.
+ */
+const answerOpenCalls = (request: Message[]): Message[] => {
+  // nessi's own answers make way for the result stored apart from the call, or for a clearer answer.
+  const messages = request.some(isNessiAnswer) ? request.filter((message) => !isNessiAnswer(message)) : request;
+  let out: Message[] | null = null;
+  const moved = new Set<number>();
+  for (let index = 0; index < messages.length; index++) {
+    if (moved.has(index)) continue;
+    const message = messages[index]!;
+    out?.push(message);
+    if (message.role !== "assistant") continue;
+    const calls = message.content.flatMap((block) => (block.type === "tool_call" ? [block] : []));
+    if (calls.length === 0) continue;
+    const results = resultsOf(messages, index, new Set(calls.map((call) => call.id)));
+    const late = (at: number) => messages.slice(index + 1, at).some((later) => later.role === "assistant");
+    const misplaced = calls.filter((call) => {
+      const at = results.get(call.id);
+      return at === undefined || late(at);
+    });
+    if (misplaced.length === 0) continue;
+    out ??= messages.slice(0, index + 1);
+    for (const call of misplaced) {
+      const at = results.get(call.id);
+      if (at === undefined) {
+        out.push({ role: "tool_result", callId: call.id, name: call.name, result: AI_OPEN_TOOL_CALL_RESULT, isError: true });
+      } else {
+        out.push(messages[at]!);
+        moved.add(at);
+      }
+    }
+  }
+  return out ?? messages;
+};
+
+/**
+ * A turn that was stopped or failed while a call ran or waited for approval leaves that call without a result, and a
+ * scheduled result delivered while a call ran is stored between the call and its result. Providers reject such a
+ * history, so every later turn of the chat would fail, and the model could not tell whether the call ran. The request
+ * answers each open call as not returned and puts each result next to its call; the stored history keeps everything
+ * as it was, so the chat still shows an open call as not run. A running turn does not see scheduled results that
+ * arrived during it, and nessi answers every call before the next model call, so only earlier turns need this. nessi
+ * also answers an open call itself, but neither says that it may have run nor moves a result up to its call.
+ */
+export const answerOpenToolCalls = (provider: Provider): Provider => ({
+  name: provider.name,
+  family: provider.family,
+  model: provider.model,
+  contextWindow: provider.contextWindow,
+  capabilities: provider.capabilities,
+  complete: (request) => provider.complete({ ...request, messages: answerOpenCalls(request.messages) }),
+  stream: (request) => provider.stream({ ...request, messages: answerOpenCalls(request.messages) }),
+});

package/src/ai/protocol.ts

@@ -19,6 +19,12 @@ import type { AiConversation, AiFrontendToolMode, AiStoredMessage, AiToolPresent
 
 export const AI_WIRE_VERSION = 1;
 
+/**
+ * Lease of a turn worker. A running turn whose worker is gone is claimed again after one lease, so a running turn
+ * that sends nothing for this long either works silently or lost an update; a client then reloads the turn's state.
+ */
+export const AI_TURN_LEASE_MS = 45_000;
+
 export type AiToolBlockStatus = "running" | "awaiting_approval" | "awaiting_client" | "completed" | "failed" | "rejected";
 
 export type AiTurnBlock =

package/src/ai/provider.ts

@@ -11,9 +11,10 @@ const commonOptions = (profile: AiModelProfile, apiKey?: string) => ({
   contextWindow: profile.contextWindow,
   temperature: profile.temperature,
   timeouts: PROVIDER_TIMEOUTS,
+  extraBody: profile.extraBody,
 });
 
-export const createAiProvider = (profile: AiModelProfile, apiKey?: string): Provider => {
+export const createAiProvider = (profile: AiModelProfile, apiKey?: string, headers?: Record<string, string>): Provider => {
   if (profile.capabilities.includes("transcription")) throw new Error("Transcription profiles cannot be used for chat generation.");
   switch (profile.provider) {
     case "openai":
@@ -32,6 +33,7 @@ export const createAiProvider = (profile: AiModelProfile, apiKey?: string): Prov
         contextWindow: profile.contextWindow,
         temperature: profile.temperature,
         timeouts: PROVIDER_TIMEOUTS,
+        extraBody: profile.extraBody,
       });
     case "vllm":
       return openAICompatible({
@@ -39,9 +41,11 @@ export const createAiProvider = (profile: AiModelProfile, apiKey?: string): Prov
         model: profile.model,
         baseURL: profile.baseURL ?? "http://localhost:8000/v1",
         apiKey,
+        headers,
         contextWindow: profile.contextWindow,
         temperature: profile.temperature,
         timeouts: PROVIDER_TIMEOUTS,
+        extraBody: profile.extraBody,
         compat: {
           toolCallIdPolicy: "passthrough",
           supportsUsageInStreaming: true,
@@ -58,9 +62,11 @@ export const createAiProvider = (profile: AiModelProfile, apiKey?: string): Prov
         model: profile.model,
         baseURL: profile.baseURL,
         apiKey,
+        headers,
         contextWindow: profile.contextWindow,
         temperature: profile.temperature,
         timeouts: PROVIDER_TIMEOUTS,
+        extraBody: profile.extraBody,
       });
   }
 };

package/src/ai/quota-provider.ts

@@ -54,8 +54,8 @@ export function inferenceProvider(
             ctx,
             inputTokens,
             request.maxOutputTokens ?? profile.maxOutputTokens,
-            // Nessi's Anthropic adapter defaults to 1024; other adapters use the model default.
-            provider.family === "anthropic" ? 1024 : provider.contextWindow,
+            // Nessi's Anthropic adapter defaults to 8192; other adapters use the model default.
+            provider.family === "anthropic" ? 8192 : provider.contextWindow,
           );
         } catch (error) {
           if (!(error instanceof AiBackgroundAdmissionError) || !error.retryable || Date.now() >= deadline) throw error;

package/src/ai/request-headers.ts

@@ -0,0 +1,117 @@
+import { sql } from "bun";
+import { toPgTextArray } from "../services/postgres";
+import { decryptValue, encryptValue } from "../services/settings/crypto";
+import {
+  AI_REQUEST_HEADERS_PROVIDER_ERROR,
+  AiRequestHeadersSchema,
+  patchAiRequestHeaders,
+  providerSupportsRequestHeaders,
+} from "../shared/ai-request-options";
+import type { AiModelProfile } from "./types";
+
+type SqlClient = typeof sql;
+export type AiRequestHeaderPatch = { profileId: string; patch: unknown };
+
+const decryptHeaders = async (profileId: string, secret: string): Promise<Record<string, string>> => {
+  try {
+    const parsed = AiRequestHeadersSchema.safeParse(await decryptValue(secret));
+    if (parsed.success && Object.values(parsed.data).every((value) => typeof value === "string"))
+      return patchAiRequestHeaders({}, parsed.data);
+  } catch {}
+  console.warn(`[ai] ignoring unreadable request headers for profile ${JSON.stringify(profileId)}`);
+  return {};
+};
+
+/** Secrets stay server-side, in a separate encrypted row like provider API keys. */
+export const getAiRequestHeaders = async (profileId: string, db: SqlClient = sql): Promise<Record<string, string>> => {
+  const [row] = await db<{ secret: string }[]>`SELECT secret FROM ai.model_request_headers WHERE profile_id = ${profileId}`;
+  return row ? decryptHeaders(profileId, row.secret) : {};
+};
+
+export const setAiRequestHeaders = async (profileId: string, headers: Record<string, string>, db: SqlClient = sql): Promise<void> => {
+  const normalized = patchAiRequestHeaders({}, headers);
+  if (!Object.keys(normalized).length) {
+    await db`DELETE FROM ai.model_request_headers WHERE profile_id = ${profileId}`;
+    return;
+  }
+  const encrypted = await encryptValue(normalized);
+  await db`INSERT INTO ai.model_request_headers (profile_id, secret) VALUES (${profileId}, ${encrypted})
+    ON CONFLICT (profile_id) DO UPDATE SET secret = EXCLUDED.secret, updated_at = now()`;
+};
+
+/** Admin reads contain names only. Never serialize header values into profiles. */
+export const listAiRequestHeaderNames = async (db: SqlClient = sql): Promise<Record<string, string[]>> => {
+  const rows = await db<{ profile_id: string; secret: string }[]>`SELECT profile_id, secret FROM ai.model_request_headers`;
+  const names: Record<string, string[]> = {};
+  for (const row of rows)
+    Object.defineProperty(names, row.profile_id, {
+      value: Object.keys(await decryptHeaders(row.profile_id, row.secret)).sort(),
+      enumerable: true,
+    });
+  return names;
+};
+
+export const pruneAiRequestHeaders = async (keepProfileIds: readonly string[], db: SqlClient = sql): Promise<void> => {
+  if (!keepProfileIds.length) await db`DELETE FROM ai.model_request_headers`;
+  else await db`DELETE FROM ai.model_request_headers WHERE profile_id <> ALL(${toPgTextArray([...keepProfileIds])}::text[])`;
+};
+
+/** Follow credentials: changing provider discards stored secrets; omission preserves them on the same provider. */
+export const planAiProfileRequestHeaders = (input: {
+  currentProfiles: readonly AiModelProfile[];
+  nextProfiles: readonly AiModelProfile[];
+  existingNames: Record<string, string[]>;
+  submitted: readonly AiRequestHeaderPatch[];
+}): { keepHeaderProfileIds: string[]; patches: { profileId: string; patch: Record<string, string | null> }[]; error?: string } => {
+  const current = new Map(input.currentProfiles.map((profile) => [profile.id, profile]));
+  const keepHeaderProfileIds = input.nextProfiles
+    .filter(
+      (profile) =>
+        providerSupportsRequestHeaders(profile.provider) &&
+        current.get(profile.id)?.provider === profile.provider &&
+        !profile.capabilities.includes("transcription"),
+    )
+    .map((profile) => profile.id);
+  const patches: { profileId: string; patch: Record<string, string | null> }[] = [];
+  for (const submitted of input.submitted) {
+    const profile = input.nextProfiles.find((profile) => profile.id === submitted.profileId);
+    const parsed = AiRequestHeadersSchema.safeParse(submitted.patch);
+    if (!parsed.success)
+      return { keepHeaderProfileIds: [], patches: [], error: `requestHeaders: ${zodHeaderMessage(parsed.error.issues)}` };
+    if (!profile || !providerSupportsRequestHeaders(profile.provider))
+      return { keepHeaderProfileIds: [], patches: [], error: AI_REQUEST_HEADERS_PROVIDER_ERROR };
+    if (profile.capabilities.includes("transcription"))
+      return {
+        keepHeaderProfileIds: [],
+        patches: [],
+        error: "requestHeaders: Request settings are not supported on transcription profiles.",
+      };
+    const oldNames =
+      keepHeaderProfileIds.includes(profile.id) && Object.hasOwn(input.existingNames, profile.id) ? input.existingNames[profile.id]! : [];
+    try {
+      patchAiRequestHeaders(Object.fromEntries(oldNames.map((name) => [name, ""])), parsed.data);
+    } catch {
+      return {
+        keepHeaderProfileIds: [],
+        patches: [],
+        error: "requestHeaders: At most 32 extra headers are allowed after applying the patch.",
+      };
+    }
+    patches.push({ profileId: profile.id, patch: parsed.data });
+  }
+  return { keepHeaderProfileIds, patches };
+};
+
+const zodHeaderMessage = (issues: readonly { path: readonly PropertyKey[]; message: string }[]) =>
+  issues.map((issue) => `${issue.path.map(String).join(".") || "headers"}: ${issue.message}`).join("; ");
+
+/** Apply after pruning so a provider change cannot inherit old secrets. Call inside the settings transaction. */
+export const storeAiRequestHeaderPlan = async (
+  plan: ReturnType<typeof planAiProfileRequestHeaders>,
+  db: SqlClient = sql,
+): Promise<void> => {
+  if (plan.error) throw new Error(plan.error);
+  await pruneAiRequestHeaders(plan.keepHeaderProfileIds, db);
+  for (const { profileId, patch } of plan.patches)
+    await setAiRequestHeaders(profileId, patchAiRequestHeaders(await getAiRequestHeaders(profileId, db), patch), db);
+};

package/src/ai/routes.ts

@@ -10,6 +10,7 @@ import {
   err,
   fail,
   getLocale,
+  getTimeZone,
   ok,
   type RequestActor,
   rateLimit,
@@ -19,6 +20,7 @@ import {
 import { isRequestCredentialCurrent } from "../server/middleware/auth";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
+import { readThemeFromCookieHeader } from "../shared/theme";
 import type { AiToolApprovalContext } from "./approvals";
 import { assistantAiSettingsState, listAssistantAiModels, selectAssistantAiModelId } from "./assistant-models";
 import { AI_AUDIO_MAX_BYTES } from "./audio-format";
@@ -168,10 +170,26 @@ const resourcesQuerySchema = (scope: "conversation" | "user") =>
     limit: z.coerce.number().int().min(1).max(100).optional(),
   });
 const ConversationResourcesQuerySchema = resourcesQuerySchema("conversation");
+const ConversationSourcesQuerySchema = ConversationResourcesQuerySchema.extend({
+  /** Kinds separated by commas, for example `web,activity,resource`. */
+  kind: z
+    .string()
+    .max(64)
+    .transform((value) => value.split(","))
+    .pipe(z.array(z.enum(["result", "web", "file", "resource", "activity"])).min(1))
+    .optional(),
+  observed: z.enum(["true", "false"]).optional(),
+});
 const UserResourcesQuerySchema = resourcesQuerySchema("user");
 
-const FilesListQuerySchema = z.object({ prefix: z.string().optional() });
+const FilesListQuerySchema = z.object({
+  prefix: z.string().optional(),
+  /** Pages by path: pass the last path of a page as `after`. Without `limit`, every file comes newest first. */
+  limit: z.coerce.number().int().min(1).max(1000).optional(),
+  after: z.string().max(4096).optional(),
+});
 const FilePathQuerySchema = z.object({ path: z.string().min(1) });
+const FileDeleteQuerySchema = FilePathQuerySchema.extend({ recursive: z.enum(["true", "false"]).optional() });
 const FileWriteSchema = z.object({
   path: z.string().min(1),
   content: z.string().max(12_000_000),
@@ -425,6 +443,7 @@ export const aiRoutes = (() => {
           memory: memory?.text,
           timeZone,
           locale: promptLocale,
+          skillCreatorAvailable: availableSkills.some((skill) => skill.name === "skill-creator"),
         });
         return respond(c, ok({ prompt, renderedAt: new Date().toISOString() }));
       })
@@ -629,7 +648,7 @@ export const aiRoutes = (() => {
           ),
         );
       })
-      .get("/conversations/:conversationId/sources", v("query", ConversationResourcesQuerySchema), async (c) => {
+      .get("/conversations/:conversationId/sources", v("query", ConversationSourcesQuerySchema), async (c) => {
         const ctx = await resolveContext(c);
         if (ctx instanceof Response) return ctx;
         const conversation = await loadConversation(c, ctx);
@@ -643,6 +662,8 @@ export const aiRoutes = (() => {
               search: query.q,
               before: query.cursor,
               limit: query.limit,
+              kinds: query.kind,
+              observed: query.observed === "true",
             }),
           ),
         );
@@ -865,6 +886,8 @@ export const aiRoutes = (() => {
             userMessage: message,
             actor: ctx.actor,
             locale: getLocale(c),
+            theme: readThemeFromCookieHeader(c.req.header("cookie")),
+            timeZone: getTimeZone(c),
             requestedModelId: body.modelProfileId ?? project?.defaultModelProfileId ?? undefined,
             modelPolicy: ctx.modelPolicy,
             project: project ?? undefined,
@@ -972,6 +995,8 @@ export const aiRoutes = (() => {
             userMessage: message,
             actor: ctx.actor,
             locale: getLocale(c),
+            theme: readThemeFromCookieHeader(c.req.header("cookie")),
+            timeZone: getTimeZone(c),
             requestedModelId,
             modelPolicy: ctx.modelPolicy,
             systemPrompt,
@@ -1127,7 +1152,12 @@ export const aiRoutes = (() => {
         if (ctx instanceof Response) return ctx;
         const conversation = await loadConversation(c, ctx);
         if (!conversation) return notFound(c);
-        const files = await aiFileStore.list({ conversationId: conversation.id, prefix: c.req.valid("query").prefix ?? "/" });
+        const query = c.req.valid("query");
+        const files = await aiFileStore.list({
+          conversationId: conversation.id,
+          prefix: query.prefix ?? "/",
+          ...(query.limit ? { limit: query.limit, after: query.after } : {}),
+        });
         return respond(c, ok({ files, totalBytes: await aiFileStore.totalBytes(conversation.id) }));
       })
       .post("/conversations/:conversationId/dictations", bodyLimit({ maxSize: AI_AUDIO_MAX_BYTES + 65_536 }), async (c) => {
@@ -1307,14 +1337,18 @@ export const aiRoutes = (() => {
           "Cache-Control": "private, no-store",
         });
       })
-      .delete("/conversations/:conversationId/files", v("query", FilePathQuerySchema), async (c) => {
+      .delete("/conversations/:conversationId/files", v("query", FileDeleteQuerySchema), async (c) => {
         const ctx = await resolveContext(c);
         if (ctx instanceof Response) return ctx;
         const conversation = await loadConversation(c, ctx);
         if (!conversation) return notFound(c);
-        const path = normalizeAiFilePath(c.req.valid("query").path);
+        const query = c.req.valid("query");
+        const path = normalizeAiFilePath(query.path);
         if (!path) return fileNotFound(c);
-        const removed = await aiFileStore.remove({ conversationId: conversation.id, path, recursive: false });
+        // A folder goes with everything below it, never the whole chat at once.
+        const recursive = query.recursive === "true";
+        if (recursive && path === "/") return respond(c, fail(err.badInput("Choose a folder below /.")));
+        const removed = await aiFileStore.remove({ conversationId: conversation.id, path, recursive });
         if (removed === 0) return fileNotFound(c);
         return respond(c, ok({ deleted: true }));
       })

package/src/ai/run-timeout.ts

@@ -1,12 +1,11 @@
+import type { AiTurnError } from "./types";
+
 /** Preserve why execution stopped instead of reporting an operator deadline as a user abort. */
 export class AiRunTimeout extends Error {
   constructor(readonly budgetMs: number | null) {
     super("AI_RUN_TIMEOUT");
   }
-  messageFor(locale?: string): string {
-    const minutes = this.budgetMs ? this.budgetMs / 60_000 : null;
-    return locale?.startsWith("de")
-      ? `Laufzeitlimit${minutes ? ` von ${minutes} Minuten` : ""} erreicht. Du kannst die Aufgabe mit einer neuen Nachricht fortsetzen.`
-      : `Run time limit${minutes ? ` of ${minutes} minutes` : ""} reached. You can continue the task with a new message.`;
+  turnError(): AiTurnError {
+    return this.budgetMs ? { code: "time_limit", limitMinutes: Math.round(this.budgetMs / 60_000) } : { code: "time_limit" };
   }
 }

package/src/ai/runtime.ts

@@ -13,6 +13,7 @@ import { startAiDictationRuntime } from "./dictation-runtime";
 import { AiTurnExecutor } from "./executor";
 import { canonicalizeAiConversationAttachments, snapshotAiConversationFiles } from "./file-context";
 import { drainQueuedMessages } from "./message-queue";
+import { AI_TURN_LEASE_MS } from "./protocol";
 import { aiQuotas } from "./quotas";
 import { parseAiResourceMarker } from "./resource-markers";
 import { isAiVisionModelConfigured } from "./settings";
@@ -43,7 +44,6 @@ export { isAiSettingsError, validateAiTurnRequest } from "./validate";
 const log = logger("ai:runtime");
 
 const AI_WORKER_ID = `worker-${crypto.randomUUID()}`;
-const AI_TURN_LEASE_MS = 45_000;
 const AI_TURN_HEARTBEAT_MS = 3_000;
 const AI_TURN_WORKER_CONCURRENCY = 8;
 const AI_TURN_MAX_ATTEMPTS = 5;
@@ -94,6 +94,8 @@ export type SubmitAiChatTurnInput = {
   userMessage: Message;
   actor?: RequestActor;
   locale?: string;
+  theme?: "light" | "dark";
+  timeZone?: string;
   modelPolicy?: AiModelPolicy;
   requestedModelId?: string;
   /** Optional instructions that apply only to this turn. */
@@ -155,6 +157,8 @@ export const prepareAiChatTurn = async (input: SubmitAiChatTurnInput) => {
     chatId: input.chatId,
     actor: input.actor,
     ...(input.locale ? { locale: input.locale } : {}),
+    ...(input.theme ? { theme: input.theme } : {}),
+    ...(input.timeZone ? { timeZone: input.timeZone } : {}),
     modelPolicy: input.modelPolicy,
     requestedModelId,
     systemPrompt: input.systemPrompt,
@@ -190,6 +194,8 @@ export const deliverAiInterChatMessage = async (input: {
   chatId?: string;
   actor: RequestActor;
   locale?: string;
+  theme?: "light" | "dark";
+  timeZone?: string;
   modelPolicy?: AiModelPolicy;
   systemPrompt?: string;
   project?: AiChatTurnRunConfig["project"];
@@ -209,6 +215,8 @@ export const deliverAiInterChatMessage = async (input: {
     chatId: input.chatId,
     actor: input.actor,
     ...(input.locale ? { locale: input.locale } : {}),
+    ...(input.theme ? { theme: input.theme } : {}),
+    ...(input.timeZone ? { timeZone: input.timeZone } : {}),
     modelPolicy: input.modelPolicy,
     systemPrompt: input.systemPrompt,
     project: input.project,

package/src/ai/settings.ts

@@ -1,9 +1,17 @@
 import { z } from "zod";
 import { coreSettings } from "../services";
 import { AiModelPricingSchema } from "../shared/ai-costs";
+import {
+  AI_REQUEST_HEADERS_PROVIDER_ERROR,
+  AiExtraBodySchema,
+  AiReasoningEffortSchema,
+  AiRequestHeadersSchema,
+  providerSupportsRequestHeaders,
+} from "../shared/ai-request-options";
 import { getAiCredential, listAiCredentialProfileIds } from "./credentials";
 import { AI_FIRECRAWL_API_KEY_SETTING_KEY } from "./firecrawl-tools";
 import { createAiProvider } from "./provider";
+import { getAiRequestHeaders } from "./request-headers";
 import {
   AI_DATA_BOUNDARIES,
   AI_MODEL_CAPABILITIES,
@@ -93,12 +101,20 @@ const ModelProfileSchema = z
     contextWindow: z.number().int().positive().optional(),
     temperature: z.number().min(0).max(2).optional(),
     maxOutputTokens: z.number().int().positive().optional(),
+    reasoningEffort: AiReasoningEffortSchema,
+    extraBody: AiExtraBodySchema.optional(),
+    requestHeaders: AiRequestHeadersSchema.optional(),
     maxLoadedTools: z.number().int().optional(),
     maxToolRounds: z.number().int().optional(),
     pricing: AiModelPricingSchema.optional(),
   })
   .superRefine((profile, ctx) => {
+    if (profile.requestHeaders !== undefined && !providerSupportsRequestHeaders(profile.provider))
+      ctx.addIssue({ code: "custom", path: ["requestHeaders"], message: AI_REQUEST_HEADERS_PROVIDER_ERROR });
     if (profile.capabilities?.includes("transcription")) {
+      for (const key of ["reasoningEffort", "extraBody", "requestHeaders"] as const)
+        if (profile[key] !== undefined)
+          ctx.addIssue({ code: "custom", path: [key], message: "Request settings are not supported on transcription profiles." });
       if (profile.pricing) ctx.addIssue({ code: "custom", path: ["pricing"], message: "Audio pricing is not supported." });
       if (profile.capabilities.some((capability) => capability !== "transcription")) {
         ctx.addIssue({ code: "custom", path: ["capabilities"], message: "Audio transcription cannot be combined with chat capabilities." });
@@ -128,7 +144,7 @@ const profileToPublic = (profile: AiModelProfile): AiPublicModelProfile => ({
 });
 
 const normalizeProfile = (raw: z.infer<typeof ModelProfileSchema>): AiModelProfile => {
-  const { capabilities, dataBoundary, dataPolicy: legacyDataPolicy, tags: _legacyTags, ...profile } = raw;
+  const { requestHeaders: _requestHeaders, capabilities, dataBoundary, dataPolicy: legacyDataPolicy, tags: _legacyTags, ...profile } = raw;
   return {
     ...profile,
     capabilities: normalizeCapabilities(capabilities),
@@ -522,7 +538,8 @@ export const resolveAiModelFromState = async (
     });
   }
 
-  return { profile, provider: createAiProvider(profile, credential?.trim() || undefined) };
+  const headers = providerSupportsRequestHeaders(profile.provider) ? await getAiRequestHeaders(profile.id) : {};
+  return { profile, provider: createAiProvider(profile, credential?.trim() || undefined, headers) };
 };
 
 const isUsableProfile = (profile: AiModelProfile, credentialProfileIds: ReadonlySet<string>): boolean =>

package/src/ai/skill-seeds.ts

@@ -14,6 +14,29 @@ Help the user turn a recurring workflow, specialist knowledge, or a set of instr
 - Ask only about a missing choice that would materially change discovery, behavior, or output. If the request is already clear, draft the Skill directly.
 - Preserve the user's scope. Do not turn one example, preference, or past failure into a universal rule unless the user clearly intends that.
 
+## Choose the right place
+
+Recommend the lightest place that does the job:
+
+- one lasting fact or preference, such as reports always as PDF: personalization memory;
+- always using one mailbox, notebook, or Space for a kind of request: a personalization workflow default, which Assistant learns from the user's stated rule or repeated use;
+- rules for one Project's shared work: Project instructions;
+- a recurring procedure, judgment, or output format used across chats: a Skill;
+- work that should run at a set time: a scheduled task, which can load the Skill;
+- a repeated calculation or an interactive tool: a Studio App that the Skill references.
+
+## Draft from the conversation
+
+When the Skill comes from work in this conversation, capture what made it succeed:
+
+- when to load it, as narrowly as the user's real requests: name the subject, such as the team or the report, not only the output format;
+- the steps and the exact capability IDs that worked, so later runs can call load_tools without searching;
+- every correction the user made, rewritten as a positive rule; corrections are the most valuable content;
+- the output shape, as a compact template when layout matters;
+- inputs by role and title, such as "the Space Sales"; when a personalization workflow default already routes this kind of request, refer to it instead of repeating it. Never copy IDs of mailboxes, Spaces, notebooks, records, or other resources from the chat; the exact ID of a Studio App the Skill calls is the one exception.
+
+Keep only procedure, format, and stable references. Leave out content from attachments, mails, web pages, or other quoted data; names of people or customers, amounts, and example records from this chat; one-off values; and failed attempts. Before the create review, tell the user in one or two sentences what the Skill will do and when it will load.
+
 ## Design the Skill
 
 ### Name
@@ -59,9 +82,10 @@ Read the draft once as if you were a different Assistant receiving it later. Che
 - the workflow can run without private conversation context;
 - instructions are direct, non-repetitive, and compatible with available capabilities;
 - examples generalize beyond the original case;
+- it holds no names of people or customers, amounts, records, or resource IDs from this conversation, except the exact ID of a Studio App it calls;
 - no surprising mutation, permission expansion, or external side effect is implied.
 
-For an existing Skill, read it first and preserve fields the user did not ask to change. Prefer a narrow correction over accumulating rules for every observed example.
+For an existing Skill, read it first and preserve fields the user did not ask to change. Prefer a narrow correction over accumulating rules for every observed example. Built-in Skills and Skills shared with others change for everyone who uses them, so change one only when you can edit it and the user wants the change for everyone. \`core.ai.skill.read\` shows your permission, and \`core.ai.skill.access.read\` shows who else can use a Skill you manage. Otherwise leave the Skill unchanged. When personalization memory is on, a correction meant only for the user can become a preference; memory saves only the user's own words, so ask the user to state the rule, such as "always write mails formally".
 
 ## Use Cloud Skill capabilities
 
@@ -82,6 +106,10 @@ Pass the exact current revision to mutations and read again after a revision con
 
 Creating, changing, and deleting Skills are reviewed mutations. Prepare the concrete content the user requested, then use the Capability review instead of asking for an extra confirmation that duplicates it.
 
+## After saving
+
+Say that the Skill now loads for matching requests and can also be selected with /skill. When a later run needs a correction, update the Skill narrowly instead of creating another one. Share it only when the user asks.
+
 ## Optional App-backed workflows
 
 A Skill can reference a reusable Studio App and its published actions instead of duplicating code. Load \`assistant-code-mode\` only when building, changing, or discovering such an App is useful. Apps may be stateless scripts, agent-only services with shared data, dashboards, or a combination. Many Skills need no code and many Apps need no Skill.
@@ -195,6 +223,7 @@ Use these defaults unless the user asks otherwise or a more specific loaded Skil
 - For text lookup across Spaces, use \`spaces.item.search\`. For overdue, assigned or inactive tasks use \`spaces.task.focus\`; filter at the server instead of enumerating every Space.
 - For a date-bounded calendar use \`spaces.event.agenda\`. Follow every cursor, including after an empty page: pagination groups series with their overrides. Collect all pages and sort by startsAt for a chronological agenda. Use returned occurrences; do not expand recurrence rules yourself or equate a series anchor with the next occurrence.
 - Select a writable Space through \`spaces.space.browse\`. A known Space can be listed directly with \`spaces.task.list\` or \`spaces.event.list\`. Read \`spaces.space.read\` only when column/tag IDs or configuration are needed.
+- List entries show at most three assignees and tags: when \`assigneeCount\` is larger than the number of \`assignees\`, state the total (for example "3 of 11") or read the item before naming everyone. \`relationsTruncated\` signals that a relation preview is partial.
 - Read a selected \`spaces.item.read\` before changing its content or deleting it. Use a task for work and an event only with explicit valid start and end. Select assignees from \`spaces.space.assignee.list\`, never inferred names or invented IDs.
 
 ## Make focused changes
@@ -438,7 +467,7 @@ const BUILTIN_CLOUD_AI_SKILLS: AiSkillTemplate[] = [
   ASSISTANT_CODE_MODE_SKILL,
   ASSISTANT_DATA_ANALYSIS_SKILL,
   {
-    version: 6,
+    version: 7,
     key: "grids:cloud-grids",
     name: "cloud-grids",
     description:
@@ -447,11 +476,10 @@ const BUILTIN_CLOUD_AI_SKILLS: AiSkillTemplate[] = [
     references: [{ path: "references/query-tasks.md", content: CLOUD_GRIDS_QUERY_REFERENCE }],
   },
   {
-    version: 2,
+    version: 3,
     key: "assistant:cloud-assistant",
     name: "cloud-assistant",
-    description:
-      "Use for work involving Cloud Assistant itself: finding or reading earlier conversations, recovering resources used in chats, messaging another conversation, or creating and managing reminders and recurring scheduled chat work.",
+    description: `Use for work involving Cloud Assistant itself: finding or reading earlier conversations, recovering resources used in chats, messaging another conversation, or creating and managing reminders and recurring scheduled chat work. Also use when a request refers to earlier work, such as "like last time", "as last week", or "the report you made me".`,
     instructions: CLOUD_ASSISTANT_INSTRUCTIONS,
   },
   {
@@ -463,7 +491,7 @@ const BUILTIN_CLOUD_AI_SKILLS: AiSkillTemplate[] = [
     instructions: SCHEDULED_TASKS_INSTRUCTIONS,
   },
   {
-    version: 2,
+    version: 3,
     key: "core:skill-creator",
     name: "skill-creator",
     description:
@@ -496,7 +524,7 @@ const BUILTIN_CLOUD_AI_SKILLS: AiSkillTemplate[] = [
     instructions: CLOUD_CONTACTS_INSTRUCTIONS,
   },
   {
-    version: 1,
+    version: 2,
     key: "spaces:cloud-spaces",
     name: "cloud-spaces",
     description:

package/src/ai/skills.ts

@@ -562,7 +562,33 @@ async function linkedSkillProjects(skillId: string, subject: AccessSubject | nul
   return result;
 }
 
+export type AiConversationSkillUse = { name: string; description: string; turns: number; lastLoadedAt: string };
+
 export const aiSkills = {
+  /**
+   * Skills a chat loaded, from the revision snapshots its turns pinned, most recently loaded first. The caller resolves
+   * the chat for its owner first; this is the chat's own history and does not recheck current Skill access.
+   */
+  async listConversationUses(conversationId: string, limit = 50): Promise<AiConversationSkillUse[]> {
+    const rows = await sql<{ name: string; description: string; turns: number | string; last_loaded_at: Date | string }[]>`
+      SELECT snapshot.skill_name AS name,
+             (array_agg(snapshot.description ORDER BY snapshot.loaded_at DESC))[1] AS description,
+             count(*) AS turns, max(snapshot.loaded_at) AS last_loaded_at
+      FROM ai.turn_skill_snapshots snapshot
+      JOIN ai.turns turn ON turn.id = snapshot.turn_id
+      WHERE turn.conversation_id = ${conversationId}::uuid
+      GROUP BY snapshot.skill_name
+      ORDER BY max(snapshot.loaded_at) DESC, snapshot.skill_name ASC
+      LIMIT ${Math.min(Math.max(Math.floor(limit), 1), 100)}
+    `;
+    return rows.map((row) => ({
+      name: row.name,
+      description: row.description,
+      turns: Number(row.turns),
+      lastLoadedAt: (row.last_loaded_at instanceof Date ? row.last_loaded_at : new Date(row.last_loaded_at)).toISOString(),
+    }));
+  },
+
   async seedOnce(template: AiSkillTemplate): Promise<void> {
     const { fields, hash } = validateTemplate(template);
     await sql.begin(async (tx) => {