@k2b/cloud 0.26.0 → 0.27.0

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

@@ -168,10 +168,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 +441,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 +646,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 +660,8 @@ export const aiRoutes = (() => {
               search: query.q,
               before: query.cursor,
               limit: query.limit,
+              kinds: query.kind,
+              observed: query.observed === "true",
             }),
           ),
         );
@@ -1127,7 +1146,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 +1331,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/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;

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.
@@ -438,7 +466,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:
@@ -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:

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) => {

package/src/ai/solid.ts

@@ -6,7 +6,7 @@ export {
   type CreateAiChatControllerOptions,
   createAiChatController,
 } from "./client/controller";
-export { conversationFileSource } from "./client/file-source";
+export { type ConversationFileSource, conversationFileSource } from "./client/file-source";
 export {
   type AiActiveTurn,
   type AiChatProjection,

package/src/ai/store.ts

@@ -304,10 +304,10 @@ const rowToConversationResourceRef = (row: ConversationResourceRefRow): AiConver
 });
 
 type ResourceCursor = { at: string; type: string; id: string };
-const encodeResourceCursor = (row: ConversationResourceRefRow): string =>
-  encodeURIComponent(JSON.stringify({ at: iso(row.last_seen_at), type: row.resource_type, id: row.resource_id } satisfies ResourceCursor));
-const encodeSourceCursor = (row: ConversationSourceRow): string =>
-  encodeURIComponent(JSON.stringify({ at: iso(row.last_seen_at), type: row.source_kind, id: row.source_key } satisfies ResourceCursor));
+const encodeResourceCursor = (row: ConversationResourceRefRow & { cursor_at: string }): string =>
+  encodeURIComponent(JSON.stringify({ at: row.cursor_at, type: row.resource_type, id: row.resource_id } satisfies ResourceCursor));
+const encodeSourceCursor = (row: ConversationSourceRow & { cursor_at: string }): string =>
+  encodeURIComponent(JSON.stringify({ at: row.cursor_at, type: row.source_kind, id: row.source_key } satisfies ResourceCursor));
 const decodeResourceCursor = (value: string | undefined): ResourceCursor | null => {
   if (!value) return null;
   try {
@@ -348,6 +348,7 @@ const rowToConversationSource = (row: ConversationSourceRow): AiConversationSour
   lastSeenAt: iso(row.last_seen_at),
   sourceTurnId: row.source_turn_id,
   sourceCallId: row.source_call_id,
+  sourceMessageSeq: null,
 });
 
 const rowToInterChatMessage = (row: InterChatMessageRow): AiInterChatMessage => ({
@@ -389,10 +390,10 @@ const interChatMessageSelect = () => sql`
 `;
 
 type ResourceOccurrenceCursor = ResourceCursor & { chat: string };
-const encodeResourceOccurrenceCursor = (row: ConversationResourceOccurrenceRow): string =>
+const encodeResourceOccurrenceCursor = (row: ConversationResourceOccurrenceRow & { cursor_at: string }): string =>
   encodeURIComponent(
     JSON.stringify({
-      at: iso(row.last_seen_at),
+      at: row.cursor_at,
       type: row.resource_type,
       id: row.resource_id,
       chat: row.conversation_short_id,
@@ -1440,9 +1441,19 @@ export const aiConversations: AiConversationService = {
             preview = COALESCE(EXCLUDED.preview, ai.conversation_resource_refs.preview),
             icon = COALESCE(EXCLUDED.icon, ai.conversation_resource_refs.icon),
             href = COALESCE(EXCLUDED.href, ai.conversation_resource_refs.href),
-            source_turn_id = COALESCE(EXCLUDED.source_turn_id, ai.conversation_resource_refs.source_turn_id),
+            -- Project context is indexed on every turn without a call. It must not move a resource a tool call
+            -- read to the latest turn, or the chat would show it as read just now.
+            source_turn_id = CASE
+              WHEN EXCLUDED.source_call_id IS NULL AND ai.conversation_resource_refs.source_call_id IS NOT NULL
+                THEN ai.conversation_resource_refs.source_turn_id
+              ELSE COALESCE(EXCLUDED.source_turn_id, ai.conversation_resource_refs.source_turn_id)
+            END,
             source_call_id = COALESCE(EXCLUDED.source_call_id, ai.conversation_resource_refs.source_call_id),
-            last_seen_at = now()
+            last_seen_at = CASE
+              WHEN EXCLUDED.source_call_id IS NULL AND ai.conversation_resource_refs.source_call_id IS NOT NULL
+                THEN ai.conversation_resource_refs.last_seen_at
+              ELSE now()
+            END
         `;
       }
     });
@@ -1452,9 +1463,10 @@ export const aiConversations: AiConversationService = {
     const limit = Math.min(Math.max(Math.floor(input.limit ?? 20), 1), 100);
     const pattern = searchPattern(input.search);
     const cursor = decodeResourceCursor(input.before);
-    const rows = await sql<ConversationResourceRefRow[]>`
+    const rows = await sql<(ConversationResourceRefRow & { cursor_at: string })[]>`
       SELECT indexed.resource_type, indexed.resource_id, indexed.title, indexed.preview, indexed.icon, indexed.href,
-             source_turn.short_id AS source_turn_id, indexed.source_call_id, indexed.first_seen_at, indexed.last_seen_at
+             source_turn.short_id AS source_turn_id, indexed.source_call_id, indexed.first_seen_at, indexed.last_seen_at,
+             to_char(indexed.last_seen_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS cursor_at
       FROM ai.conversation_resource_refs indexed
       LEFT JOIN ai.turns source_turn ON source_turn.id = indexed.source_turn_id
       WHERE indexed.conversation_id = ${input.conversationId}::uuid
@@ -1475,11 +1487,12 @@ export const aiConversations: AiConversationService = {
     const limit = Math.min(Math.max(Math.floor(input.limit ?? 20), 1), 100);
     const pattern = searchPattern(input.search);
     const cursor = decodeResourceOccurrenceCursor(input.before);
-    const rows = await sql<ConversationResourceOccurrenceRow[]>`
+    const rows = await sql<(ConversationResourceOccurrenceRow & { cursor_at: string })[]>`
       SELECT indexed.resource_type, indexed.resource_id, indexed.title, indexed.preview, indexed.icon, indexed.href,
              source_turn.short_id AS source_turn_id, indexed.source_call_id, indexed.first_seen_at, indexed.last_seen_at,
              conversation.short_id AS conversation_short_id, conversation.title AS conversation_title,
-             conversation.updated_at AS conversation_updated_at
+             conversation.updated_at AS conversation_updated_at,
+             to_char(indexed.last_seen_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS cursor_at
       FROM ai.conversation_resource_refs indexed
       JOIN ai.conversations conversation ON conversation.id = indexed.conversation_id
       LEFT JOIN ai.turns source_turn ON source_turn.id = indexed.source_turn_id
@@ -1502,17 +1515,21 @@ export const aiConversations: AiConversationService = {
     const source = input.source;
     await sql`
       INSERT INTO ai.conversation_sources (
-        conversation_id, kind, source_key, title, preview, icon, href, source_turn_id, source_call_id
+        conversation_id, kind, source_key, title, preview, icon, href, resource_type, resource_id, source_turn_id, source_call_id
       ) VALUES (
         ${input.conversationId}::uuid, ${source.kind}, ${source.key}, ${source.title}, ${source.preview ?? null},
-        ${source.icon ?? null}, ${source.href ?? null}, ${input.turnId ?? null}::uuid, ${input.callId ?? null}
+        ${source.icon ?? null}, ${source.href ?? null}, ${source.ref?.type ?? null}, ${source.ref?.id ?? null},
+        ${input.turnId ?? null}::uuid, ${input.callId ?? null}
       )
       ON CONFLICT (conversation_id, kind, source_key)
       DO UPDATE SET
         title = EXCLUDED.title,
-        preview = COALESCE(EXCLUDED.preview, ai.conversation_sources.preview),
+        -- A new delivery describes the result anew; an old description must not outlive changed content.
+        preview = CASE WHEN EXCLUDED.kind = 'result' THEN EXCLUDED.preview ELSE COALESCE(EXCLUDED.preview, ai.conversation_sources.preview) END,
         icon = COALESCE(EXCLUDED.icon, ai.conversation_sources.icon),
         href = COALESCE(EXCLUDED.href, ai.conversation_sources.href),
+        resource_type = COALESCE(EXCLUDED.resource_type, ai.conversation_sources.resource_type),
+        resource_id = COALESCE(EXCLUDED.resource_id, ai.conversation_sources.resource_id),
         occurrences = ai.conversation_sources.occurrences +
           CASE WHEN ai.conversation_sources.source_call_id IS DISTINCT FROM EXCLUDED.source_call_id THEN 1 ELSE 0 END,
         source_turn_id = COALESCE(EXCLUDED.source_turn_id, ai.conversation_sources.source_turn_id),
@@ -1525,50 +1542,85 @@ export const aiConversations: AiConversationService = {
     const limit = Math.min(Math.max(Math.floor(input.limit ?? 20), 1), 100);
     const pattern = searchPattern(input.search);
     const cursor = decodeResourceCursor(input.before);
-    const rows = await sql<ConversationSourceRow[]>`
-      SELECT *
-      FROM (
-        SELECT source.kind AS source_kind, source.source_key, source.title, source.preview,
-               source.icon, source.href, NULL::text AS path, NULL::text AS media_type, NULL::bigint AS size,
-               NULL::text AS resource_type, NULL::text AS resource_id, source.occurrences,
-               turn.short_id AS source_turn_id, source.source_call_id, source.first_seen_at, source.last_seen_at
-        FROM ai.conversation_sources source
-        LEFT JOIN ai.turns turn ON turn.id = source.source_turn_id
-        WHERE source.conversation_id = ${input.conversationId}::uuid
-
-        UNION ALL
-
-        SELECT 'file' AS source_kind, file.path AS source_key,
-               regexp_replace(file.path, '^.*/', '') AS title, 'Attached to the conversation' AS preview,
-               CASE WHEN file.media_type LIKE 'image/%' THEN 'ti ti-photo' ELSE 'ti ti-file' END AS icon,
-               NULL::text AS href, file.path, file.media_type, file.size,
-               NULL::text AS resource_type, NULL::text AS resource_id, 1 AS occurrences,
-               NULL::text AS source_turn_id, NULL::text AS source_call_id,
-               file.updated_at AS first_seen_at, file.updated_at AS last_seen_at
-        FROM ai.files file
-        WHERE file.conversation_id = ${input.conversationId}::uuid
-
-        UNION ALL
-
-        SELECT 'resource' AS source_kind, indexed.resource_type || ':' || indexed.resource_id AS source_key,
-               COALESCE(indexed.title, indexed.resource_type || ' ' || indexed.resource_id) AS title,
-               indexed.preview, indexed.icon, indexed.href, NULL::text AS path, NULL::text AS media_type, NULL::bigint AS size,
-               indexed.resource_type, indexed.resource_id, 1 AS occurrences,
-               turn.short_id AS source_turn_id, indexed.source_call_id, indexed.first_seen_at, indexed.last_seen_at
-        FROM ai.conversation_resource_refs indexed
-        LEFT JOIN ai.turns turn ON turn.id = indexed.source_turn_id
-        WHERE indexed.conversation_id = ${input.conversationId}::uuid
-      ) source
-      WHERE (${pattern}::text IS NULL OR LOWER(source.title || ' ' || COALESCE(source.preview, '') || ' ' || source.source_key) LIKE ${pattern})
-        AND (${cursor?.at ?? null}::timestamptz IS NULL OR (source.last_seen_at, source.source_kind, source.source_key) <
-          (${cursor?.at ?? null}::timestamptz, ${cursor?.type ?? null}::text, ${cursor?.id ?? null}::text))
-      ORDER BY source.last_seen_at DESC, source.source_kind DESC, source.source_key DESC
-      LIMIT ${limit + 1}
-    `;
-    const page = rows.slice(0, limit);
+    const kinds = input.kinds?.length ? toPgTextArray([...input.kinds]) : null;
+    const observed = input.observed === true;
+    const rows = await sql<(ConversationSourceRow & { total: number | string; source_message_seq: number | null; cursor_at: string })[]>`
+      WITH matched AS (
+        SELECT *
+        FROM (
+          SELECT source.kind AS source_kind, source.source_key, source.title, source.preview,
+                 source.icon, source.href, file.path, file.media_type, file.size,
+                 source.resource_type, source.resource_id, source.occurrences,
+                 turn.short_id AS source_turn_id, source.source_turn_id AS turn_uuid, source.source_call_id,
+                 source.first_seen_at, source.last_seen_at
+          FROM ai.conversation_sources source
+          LEFT JOIN ai.turns turn ON turn.id = source.source_turn_id
+          LEFT JOIN ai.files file
+            ON source.kind = 'result' AND file.conversation_id = source.conversation_id AND file.path = source.source_key
+          WHERE source.conversation_id = ${input.conversationId}::uuid
+
+          UNION ALL
+
+          SELECT 'file' AS source_kind, file.path AS source_key,
+                 regexp_replace(file.path, '^.*/', '') AS title, 'Attached to the conversation' AS preview,
+                 CASE WHEN file.media_type LIKE 'image/%' THEN 'ti ti-photo' ELSE 'ti ti-file' END AS icon,
+                 NULL::text AS href, file.path, file.media_type, file.size,
+                 NULL::text AS resource_type, NULL::text AS resource_id, 1 AS occurrences,
+                 NULL::text AS source_turn_id, NULL::uuid AS turn_uuid, NULL::text AS source_call_id,
+                 file.updated_at AS first_seen_at, file.updated_at AS last_seen_at
+          FROM ai.files file
+          WHERE file.conversation_id = ${input.conversationId}::uuid
+
+          UNION ALL
+
+          SELECT 'resource' AS source_kind, indexed.resource_type || ':' || indexed.resource_id AS source_key,
+                 COALESCE(indexed.title, indexed.resource_type || ' ' || indexed.resource_id) AS title,
+                 indexed.preview, indexed.icon, indexed.href, NULL::text AS path, NULL::text AS media_type, NULL::bigint AS size,
+                 indexed.resource_type, indexed.resource_id, 1 AS occurrences,
+                 turn.short_id AS source_turn_id, indexed.source_turn_id AS turn_uuid, indexed.source_call_id,
+                 indexed.first_seen_at, indexed.last_seen_at
+          FROM ai.conversation_resource_refs indexed
+          LEFT JOIN ai.turns turn ON turn.id = indexed.source_turn_id
+          WHERE indexed.conversation_id = ${input.conversationId}::uuid
+        ) source
+        WHERE (${kinds}::text[] IS NULL OR source.source_kind = ANY(${kinds}::text[]))
+          AND (NOT ${observed} OR source.source_kind <> 'resource' OR source.source_call_id IS NOT NULL)
+          AND (${pattern}::text IS NULL OR LOWER(source.title || ' ' || COALESCE(source.preview, '') || ' ' || source.source_key) LIKE ${pattern})
+      ),
+      page AS (
+        SELECT *
+        FROM matched source
+        WHERE ${cursor?.at ?? null}::timestamptz IS NULL OR (source.last_seen_at, source.source_kind, source.source_key) <
+          (${cursor?.at ?? null}::timestamptz, ${cursor?.type ?? null}::text, ${cursor?.id ?? null}::text)
+        ORDER BY source.last_seen_at DESC, source.source_kind DESC, source.source_key DESC
+        LIMIT ${limit + 1}
+      )
+      SELECT page.*, to_char(page.last_seen_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS cursor_at, totals.total,
+             COALESCE(
+               (SELECT message.seq FROM ai.messages message
+                WHERE message.conversation_id = ${input.conversationId}::uuid AND message.loop_id = page.turn_uuid::text
+                  AND message.role = 'assistant' AND page.source_call_id IS NOT NULL
+                  AND (CASE WHEN jsonb_typeof(message.message) = 'string' THEN (message.message #>> '{}')::jsonb ELSE message.message END) -> 'content'
+                      @> jsonb_build_array(jsonb_build_object('type', 'tool_call', 'id', page.source_call_id))
+                ORDER BY message.seq ASC
+                LIMIT 1),
+               (SELECT min(message.seq) FROM ai.messages message
+                WHERE message.conversation_id = ${input.conversationId}::uuid AND message.loop_id = page.turn_uuid::text)
+             ) AS source_message_seq
+      FROM (SELECT count(*) AS total FROM matched) totals
+      LEFT JOIN page ON true
+      ORDER BY page.last_seen_at DESC, page.source_kind DESC, page.source_key DESC
+    `;
+    // One row carries the total even when the page is empty.
+    const total = Number(rows[0]?.total ?? 0);
+    const page = rows.filter((row) => row.source_kind !== null).slice(0, limit);
     return {
-      sources: page.map(rowToConversationSource),
+      sources: page.map((row) => ({
+        ...rowToConversationSource(row),
+        sourceMessageSeq: row.source_message_seq === null ? null : Number(row.source_message_seq),
+      })),
       ...(rows.length > limit && page.at(-1) ? { nextCursor: encodeSourceCursor(page.at(-1)!) } : {}),
+      total,
     };
   },