@k2b/cloud 0.39.0 → 0.40.0

package/src/ai/recent-resources.ts

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { listCapabilities } from "../_internal/registry";
+import { type CapabilityDispatchParams, dispatchCapability, QUERY_TIMEOUT_MS } from "../api/capabilities";
+import {
+  CloudResourceRefSchema,
+  capabilityResultSchema,
+  cloudResourceRefAppId,
+  LinkedCloudResourceReferenceSchema,
+  resolveCapabilityResourceReader,
+} from "../contracts/capabilities";
+import type { CapabilityRegistryEntry } from "../contracts/registry";
+import type { RequestAuthority } from "../server";
+import { resolveAppIdentityPresentation } from "../shared/app-presentation";
+import { LOCALE_HEADER } from "../shared/locale";
+import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
+import { createCodeSourceTool } from "./code-source-tools";
+import { RECENT_SENT_REF_LIMIT } from "./recent-sent-refs";
+import { addCloudResourceHrefs } from "./resource-refs";
+import { aiSkills } from "./skills";
+import { aiConversations } from "./store";
+import type { AiConversationService, AiRecentResource } from "./types";
+
+export const AiRecentResourceSchema: z.ZodType<AiRecentResource> = z
+  .object({
+    ref: CloudResourceRefSchema,
+    title: LinkedCloudResourceReferenceSchema.shape.title.unwrap(),
+    icon: LinkedCloudResourceReferenceSchema.shape.icon,
+    href: LinkedCloudResourceReferenceSchema.shape.href,
+    kind: z.string().min(1).max(120),
+    preview: z.string().max(160).optional(),
+    appName: z.string().min(1).max(120),
+    count: z.number().int().positive(),
+  })
+  .strict();
+
+const ReaderResult = capabilityResultSchema(z.unknown(), { consumer: true });
+const StudioData = z.object({
+  id: z.string(),
+  title: LinkedCloudResourceReferenceSchema.shape.title.unwrap(),
+  icon: LinkedCloudResourceReferenceSchema.shape.icon,
+  description: z.string().optional(),
+});
+const studioReader = async (input: {
+  id: string;
+  conversationId: string;
+  authority: RequestAuthority;
+  locale: string;
+  signal: AbortSignal;
+}): Promise<unknown> => {
+  const tool = createCodeSourceTool("code_read");
+  if (tool.location !== "server") throw new Error("Studio reader must run on the server.");
+  return tool.run(CODE_SOURCE_TOOLS.code_read.input.parse({ id: input.id }), {
+    actor: input.authority.actor,
+    conversationId: input.conversationId,
+    locale: input.locale,
+    signal: input.signal,
+    requestApproval: async () => false,
+    requestClientTool: async () => {
+      throw new Error("Recent resources cannot call client tools.");
+    },
+  });
+};
+
+export type AiRecentResourceDependencies = {
+  store?: Pick<AiConversationService, "listRecentSentResourceRefs">;
+  listRegistry?: () => Promise<CapabilityRegistryEntry[]>;
+  dispatch?: (params: CapabilityDispatchParams) => Promise<Response>;
+  skills?: Pick<typeof aiSkills, "list">;
+  studioReader?: typeof studioReader;
+  timeoutMs?: number;
+};
+
+const german = (locale: string) => locale.toLowerCase().split("-")[0] === "de";
+/** Skills and Studio apps belong to the Assistant, which has no capability presentation to read its name from. */
+const assistantName = (locale: string) => (german(locale) ? "Assistent" : "Assistant");
+
+/** First line only; reserve one character for the ellipsis and avoid splitting words. */
+export const recentResourcePreview = (value: string | undefined): string | undefined => {
+  const line = value?.split(/\r\n?|\n/, 1)[0]?.trim();
+  if (!line) return undefined;
+  if (line.length <= 160) return line;
+  const clipped = line.slice(0, 159);
+  const boundary = clipped.search(/\s+\S*$/);
+  return `${(boundary > 0 ? clipped.slice(0, boundary) : clipped).trimEnd()}…`;
+};
+
+/** Enforce the shared budget even when a dependency ignores cancellation. */
+const withinBudget = async <T>(signal: AbortSignal, run: () => Promise<T>): Promise<T> => {
+  signal.throwIfAborted();
+  let abort: () => void = () => {};
+  const aborted = new Promise<never>((_, reject) => {
+    abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+  });
+  try {
+    return await Promise.race([run(), aborted]);
+  } finally {
+    signal.removeEventListener("abort", abort);
+  }
+};
+
+export const listAiRecentResources = async (input: {
+  ownerUserId: string;
+  authority: RequestAuthority;
+  locale: string;
+  signal: AbortSignal;
+  dependencies?: AiRecentResourceDependencies;
+}): Promise<AiRecentResource[]> => {
+  const deps = input.dependencies ?? {};
+  const signal = AbortSignal.any([input.signal, AbortSignal.timeout(deps.timeoutMs ?? QUERY_TIMEOUT_MS)]);
+  // Unreadable history is no answer, not an empty one: the request fails, so the browser asks again at its next opening.
+  const sent = await withinBudget(signal, () =>
+    (deps.store ?? aiConversations).listRecentSentResourceRefs({ ownerUserId: input.ownerUserId }),
+  );
+  if (!sent.length || signal.aborted) return [];
+  const candidates = sent.slice(0, RECENT_SENT_REF_LIMIT);
+  const skillIds = candidates.flatMap(({ ref }) => (ref.type === "core.ai.skill" ? [ref.id] : []));
+  // Exactly the sent Skills, so a large Skill catalog never pushes one out; failing, they are left out like a reader.
+  const skills = skillIds.length
+    ? withinBudget(signal, () => (deps.skills ?? aiSkills).list(input.authority.accessSubject, { shortIds: skillIds })).catch(() => [])
+    : Promise.resolve([]);
+  const registry = candidates.some(({ ref }) => ref.type !== "core.ai.skill" && ref.type !== "assistant.artifact")
+    ? withinBudget(signal, deps.listRegistry ?? listCapabilities).catch(() => [])
+    : Promise.resolve([]);
+  const resources = await Promise.all(
+    candidates.map(async (candidate): Promise<AiRecentResource | null> => {
+      try {
+        signal.throwIfAborted();
+        const { ref, count } = candidate;
+        if (ref.type === "core.ai.skill") {
+          const skill = (await skills).find((skill) => skill.shortId === ref.id && skill.enabled !== false);
+          if (!skill) return null;
+          return {
+            ref,
+            count,
+            title: skill.name.slice(0, 500),
+            icon: "ti ti-sparkles",
+            kind: "Skill",
+            preview: recentResourcePreview(skill.description),
+            appName: assistantName(input.locale),
+          };
+        }
+        if (ref.type === "assistant.artifact") {
+          const { actor, accessSubject, credentialKind, scopes } = input.authority;
+          // code_read reconstructs a user session authority. Only use it when that is
+          // exactly this request's authority; never widen scoped/delegated credentials.
+          if (
+            credentialKind !== "session" ||
+            scopes.length ||
+            actor.kind !== "user" ||
+            actor.delegation ||
+            actor.sessionKind === "app" ||
+            accessSubject.type !== "user" ||
+            accessSubject.userId !== actor.user.id
+          )
+            return null;
+          const answer = ReaderResult.parse(
+            await withinBudget(signal, () =>
+              (deps.studioReader ?? studioReader)({
+                id: ref.id,
+                conversationId: candidate.conversationId,
+                authority: input.authority,
+                locale: input.locale,
+                signal,
+              }),
+            ),
+          );
+          signal.throwIfAborted();
+          const data = StudioData.parse(answer.data);
+          if (data.id !== ref.id || !data.title.trim()) return null;
+          const matched = answer.refs?.find((entry) => entry.type === ref.type && entry.id === ref.id);
+          const ownRef = matched ? LinkedCloudResourceReferenceSchema.parse(matched) : undefined;
+          const href = ownRef?.href ?? answer.links?.find((link) => link.rel === "open")?.href;
+          return {
+            ref,
+            count,
+            title: data.title,
+            icon: ownRef?.icon ?? data.icon,
+            href,
+            preview: recentResourcePreview(ownRef?.preview ?? data.description),
+            kind: german(input.locale) ? "Studio-App" : "Studio app",
+            appName: assistantName(input.locale),
+          };
+        }
+        const apps = await registry;
+        signal.throwIfAborted();
+        const appId = cloudResourceRefAppId(ref);
+        const app = apps.find((app) => app.appId === appId);
+        const reader = app && resolveCapabilityResourceReader(app.manifest, ref);
+        if (!app || !reader) return null;
+        const response = await withinBudget(signal, () =>
+          (deps.dispatch ?? dispatchCapability)({
+            request: new Request("http://localhost/api/ai/resources/recent", {
+              method: "POST",
+              headers: { [LOCALE_HEADER]: input.locale, "x-request-id": crypto.randomUUID() },
+              signal,
+            }),
+            kind: "queries",
+            origin: "assistant",
+            appId: app.appId,
+            capabilityId: reader.localId,
+            input: { id: ref.id },
+            authority: input.authority,
+            locale: input.locale,
+          }),
+        );
+        if (!response.ok) return null;
+        const answer = ReaderResult.parse(addCloudResourceHrefs(await withinBudget(signal, () => response.json()), apps));
+        const matched = answer.refs?.find((entry) => entry.type === ref.type && entry.id === ref.id);
+        const ownRef = matched ? LinkedCloudResourceReferenceSchema.parse(matched) : undefined;
+        if (!ownRef?.title?.trim()) return null;
+        signal.throwIfAborted();
+        const manifest = resolveCapabilityManifestPresentation(app.manifest, app.presentation, input.locale);
+        const type = manifest.types.find((type) => `${app.appId}.${type.localId}` === ref.type);
+        if (!type) return null;
+        const presentation = resolveAppIdentityPresentation(
+          { name: app.appName, description: app.appDescription, presentation: app.appPresentation },
+          input.locale,
+        );
+        return {
+          ref,
+          count,
+          title: ownRef.title,
+          icon: (ownRef.icon ?? type.icon ?? app.appIcon)?.slice(0, 120),
+          href: ownRef.href,
+          kind: type.title.slice(0, 120),
+          preview: recentResourcePreview(ownRef.preview),
+          appName: presentation.name.slice(0, 120),
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return resources.flatMap((resource) => {
+    const parsed = AiRecentResourceSchema.safeParse(resource);
+    return parsed.success ? [parsed.data] : [];
+  });
+};

package/src/ai/recent-sent-refs.ts

@@ -0,0 +1,38 @@
+import { parseAiResourceMarker } from "./resource-markers";
+import type { AiRecentSentResourceRef } from "./types";
+
+export const RECENT_SENT_REF_LIMIT = 8;
+// Look back 25 messages/conversations per displayed ref: useful sparse history without
+// scanning the owner's lifetime. insertMessageLocked (used by submitChatTurn and steering)
+// bumps conversation.updated_at, so newly sent turns enter this indexed window.
+export const RECENT_SENT_MESSAGE_SCAN_LIMIT = RECENT_SENT_REF_LIMIT * 25;
+export const RECENT_SENT_CONVERSATION_SCAN_LIMIT = RECENT_SENT_MESSAGE_SCAN_LIMIT;
+
+/**
+ * Rows arrive newest first and contain only marker text, never whole message bodies. Forking or copying a chat copies
+ * its messages with their short IDs, so a message ID counts once, however many chats hold a copy of it.
+ */
+export const collectRecentSentResourceRefs = (
+  messages: readonly { conversationId: string; messageId: string; lastSentAt: string; markers: readonly string[] }[],
+): AiRecentSentResourceRef[] => {
+  const refs = new Map<string, AiRecentSentResourceRef>();
+  const counted = new Set<string>();
+  for (const message of messages) {
+    if (counted.has(message.messageId)) continue;
+    counted.add(message.messageId);
+    const seen = new Set<string>();
+    for (const text of message.markers) {
+      const marker = parseAiResourceMarker(text);
+      if (!marker) continue;
+      const key = JSON.stringify([marker.ref.type, marker.ref.id]);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const existing = refs.get(key);
+      if (existing) existing.count++;
+      else if (refs.size < RECENT_SENT_REF_LIMIT) {
+        refs.set(key, { ref: marker.ref, count: 1, lastSentAt: message.lastSentAt, conversationId: message.conversationId });
+      }
+    }
+  }
+  return [...refs.values()];
+};

package/src/ai/routes.ts

@@ -1,7 +1,10 @@
 import { type Context, Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
+import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { listCapabilities } from "../_internal/registry";
+import { QUERY_TIMEOUT_MS } from "../api/capabilities";
+import { ErrorResponseSchema } from "../contracts";
 import { APPROVAL_CLIENT_HEADER } from "../contracts/approvals";
 import {
   type AccessSubject,
@@ -11,22 +14,28 @@ import {
   fail,
   getLocale,
   getTimeZone,
+  jsonResponse,
   ok,
   type RequestActor,
   rateLimit,
+  requiresAuth,
   respond,
   v,
 } from "../server";
 import { isAppSessionActor } from "../server/actor";
 import { isRequestCredentialCurrent } from "../server/middleware/auth";
+import { noTransform } from "../server/middleware/no-transform";
+import { REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "../server/request-timeout";
 import { approvalDecisionChannel } from "../services/approvals";
 import { ImageMetadataError } from "../services/image-metadata";
 import { logger } from "../services/logging";
 import { coreSettings } from "../services/settings/api";
 import { readThemeFromCookieHeader } from "../shared/theme";
+import { isUnknownActionOutcome } from "./action-review";
 import { assistantAiSettingsState, listAssistantAiModels, resolveAssistantAudioModel, selectAssistantAiModelId } from "./assistant-models";
 import { AI_AUDIO_MAX_BYTES } from "./audio-format";
 import { buildAiCapabilityCatalog } from "./capabilities";
+import { checkAiCapability, resolveAiCapabilityActor } from "./capability-execution";
 import { aiChatMessages } from "./chat/messages";
 import { getAiChatQuotas } from "./chat-quotas";
 import { aiChatTasks } from "./chat-tasks";
@@ -67,6 +76,8 @@ import {
 import { aiActorUser, aiPrefsUserId, aiUserPrefs } from "./prefs";
 import { aiProjects } from "./projects";
 import { projectPublicAiStoredMessages, publicAiStoredMessages } from "./public-projection";
+import { AiRecentResourceSchema, listAiRecentResources } from "./recent-resources";
+import { RECENT_SENT_REF_LIMIT } from "./recent-sent-refs";
 import { type AiChatRequestContext, resolveAiChatRequestContext as resolveContext } from "./request-context";
 import { aiResourceMarker } from "./resource-markers";
 import { isConversationResourceCursor } from "./resource-refs";
@@ -85,9 +96,10 @@ import { AI_SHORT_ID_PATTERN } from "./short-id";
 import { selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool } from "./skill-tool";
 import { aiSkills } from "./skills";
-import { aiConversations } from "./store";
+import { AI_TOOL_CHECK_STALE_MS, aiConversations, claimAiToolCheck, readAiToolCheck, settleAiToolCheck } from "./store";
 import { createAiConversationStreamResponse, loadAiStreamState } from "./stream";
 import { composeAiSystemPrompt } from "./system-prompt";
+import { aiToolAudit } from "./tool-audit";
 import { aiToolPromptHints } from "./tools";
 import type { AiConversation, AiTurn } from "./types";
 
@@ -305,6 +317,7 @@ export const aiRoutes = (() => {
 
   return (
     new Hono<AuthContext>()
+      .use("*", noTransform())
       .use(rateLimit())
       .use("*", auth.requireRole("authenticated"))
       .get("/status", async (c) => {
@@ -459,6 +472,42 @@ export const aiRoutes = (() => {
         });
         return respond(c, ok({ prompt, renderedAt: new Date().toISOString() }));
       })
+      .get(
+        "/resources/recent",
+        describeRoute({
+          tags: ["AI"],
+          summary: "List recently sent resources",
+          description: "Up to eight recently sent refs, with current reader-authorized metadata. Unreadable resources are omitted.",
+          ...requiresAuth,
+          responses: {
+            200: jsonResponse(
+              z.object({ resources: z.array(AiRecentResourceSchema).max(RECENT_SENT_REF_LIMIT) }),
+              "Current recent resources",
+            ),
+            401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+            403: jsonResponse(ErrorResponseSchema, "AI context unavailable"),
+          },
+        }),
+        // Titles come from app readers, so a scoped token needs the read scope the capability routes ask for.
+        auth.requireOAuthScope("read", "admin"),
+        async (c) => {
+          c.header("Cache-Control", "no-store");
+          const ctx = await resolveContext(c);
+          if (ctx instanceof Response) return ctx;
+          setRequestTimeout(c, Math.ceil(QUERY_TIMEOUT_MS / 1000) + REQUEST_IDLE_TIMEOUT_SECONDS);
+          try {
+            const resources = await listAiRecentResources({
+              ownerUserId: ctx.ownerUserId,
+              authority: auth.getAuthority(c),
+              locale: getLocale(c),
+              signal: c.req.raw.signal,
+            });
+            return respond(c, ok({ resources }));
+          } finally {
+            setRequestTimeout(c, REQUEST_IDLE_TIMEOUT_SECONDS);
+          }
+        },
+      )
       .get("/resources", v("query", UserResourcesQuerySchema), async (c) => {
         const ctx = await resolveContext(c);
         if (ctx instanceof Response) return ctx;
@@ -1158,6 +1207,101 @@ export const aiRoutes = (() => {
         await abortAiTurn({ conversationId: conversation.id, turnId: turn.id });
         return respond(c, ok({ ok: true }));
       })
+      .post("/conversations/:conversationId/turns/:turnId/calls/:callId/check", async (c) => {
+        const ctx = await resolveContext(c);
+        if (ctx instanceof Response) return ctx;
+        // The check runs with the person's session authority, so a scoped token or another client cannot borrow it.
+        if (ctx.actor.kind !== "user" || !ctx.signedInSession)
+          return respond(c, fail(err.forbidden("Action outcome checks require a signed-in browser session.")));
+        const conversation = await loadConversation(c, ctx);
+        if (!conversation) return notFound(c);
+        const turn = await loadTurn(conversation, c.req.param("turnId"));
+        const callId = c.req.param("callId");
+        if (!turn || !callId) return notFound(c);
+        const target = { conversationId: conversation.id, turnId: turn.id, callId };
+        // The app's Query may take its whole budget; the request must outlast it.
+        setRequestTimeout(c, Math.ceil(QUERY_TIMEOUT_MS / 1000) + REQUEST_IDLE_TIMEOUT_SECONDS);
+        try {
+          const messages = await aiConversations.listTurnMessages({
+            conversationId: conversation.id,
+            loopId: turn.id,
+            includeCompacted: true,
+          });
+          const message = messages.find(
+            ({ message }) =>
+              message.role === "assistant" && message.content.some((block) => block.type === "tool_call" && block.id === callId),
+          );
+          if (!message) return notFound(c);
+          const review = message.meta?.toolReviews?.[callId];
+          const previous = message.meta?.toolChecks?.[callId];
+          if (!review || !("sentence" in review) || !review.check) return respond(c, fail(err.conflict("This call has no outcome check.")));
+          if (!previous) {
+            // An unknown tool result ends executor recovery for this call, even while its turn is live. Without
+            // a result, only a terminal cut-off call may be checked. Both paths require evidence of dispatch.
+            const terminal = turn.status === "completed" || turn.status === "failed" || turn.status === "aborted";
+            const result = messages.find(({ message }) => message.role === "tool_result" && message.callId === callId)?.message;
+            const eligible = result
+              ? result.role === "tool_result" && result.isError === true && isUnknownActionOutcome(result.result)
+              : terminal;
+            if (!eligible || !(await aiToolAudit.hasCapabilityDispatch(target)))
+              return respond(c, fail(err.conflict("This call has no outcome check.")));
+          }
+          // A settled check answers again as it was stored, so a client whose last response got lost can recover
+          // without running the Query again.
+          if (previous?.state === "done" || previous?.state === "not_done") return respond(c, ok(previous));
+          const block =
+            message.message.role === "assistant"
+              ? message.message.content.find((block) => block.type === "tool_call" && block.id === callId)
+              : undefined;
+          const catalog = buildAiCapabilityCatalog(await listCapabilities());
+          const presentation = message.meta?.toolPresentations?.[callId];
+          const entry = catalog.find(
+            (entry) =>
+              entry.kind === "action" &&
+              (entry.name === (block?.type === "tool_call" ? block.name : undefined) ||
+                entry.providerName === (block?.type === "tool_call" ? block.name : undefined)) &&
+              (!presentation || presentation.appId === entry.appId),
+          );
+          if (!entry) return respond(c, fail(err.conflict("The Action's app is unavailable. Try the check again when it returns.")));
+          const authority = await resolveAiCapabilityActor({
+            conversationId: conversation.id,
+            persistedActor: ctx.actor,
+            store: aiConversations,
+          });
+          // One check at a time per call, across Core replicas and the executor: the claim is one conditional write,
+          // and no transaction stays open while the app's Query runs.
+          const claimedAt = new Date().toISOString();
+          const claimed = await claimAiToolCheck({
+            ...target,
+            first: !previous,
+            at: claimedAt,
+            staleBefore: new Date(Date.now() - AI_TOOL_CHECK_STALE_MS).toISOString(),
+          });
+          if (!claimed) {
+            const stored = await readAiToolCheck(target);
+            if (stored?.state === "done" || stored?.state === "not_done") return respond(c, ok(stored));
+            return respond(c, fail(err.conflict("An outcome check is already running for this call.")));
+          }
+          const answered = await checkAiCapability({
+            ...target,
+            entry,
+            check: review.check,
+            catalog,
+            authority,
+            // The receipt joins the stored review's sentence, so it is asked for in that language.
+            locale: review.locale,
+            context: { callId, signal: c.req.raw.signal },
+          });
+          if (await settleAiToolCheck({ ...target, claimedAt, check: answered })) return respond(c, ok(answered));
+          // The claim went stale and a newer check took over; its stored result is the answer.
+          const stored = await readAiToolCheck(target);
+          return stored && stored.state !== "checking"
+            ? respond(c, ok(stored))
+            : respond(c, fail(err.conflict("An outcome check is already running for this call.")));
+        } finally {
+          setRequestTimeout(c, REQUEST_IDLE_TIMEOUT_SECONDS);
+        }
+      })
       .post(
         "/conversations/:conversationId/turns/:turnId/actions/:callId",
         bodyLimit({ maxSize: AI_CLIENT_TOOL_ACTION_MAX_BYTES }),

package/src/ai/runtime.ts

@@ -47,6 +47,7 @@ import type {
 import { isAiImageMediaType } from "./types";
 import { validateAiTurnRequest } from "./validate";
 
+export { createAiTurnCodeAndClientTools } from "./default-tools";
 export type { ValidateAiTurnInput } from "./validate";
 export { isAiSettingsError, validateAiTurnRequest } from "./validate";
 

package/src/ai/skills-routes.ts

@@ -3,6 +3,7 @@ import { HTTPException } from "hono/http-exception";
 import { z } from "zod";
 import { AuthenticatedPrincipalSchema } from "../contracts/shared";
 import { type AuthContext, auth, err, fail, ok, rateLimit, respond, v } from "../server";
+import { noTransform } from "../server/middleware/no-transform";
 import { localizedAppName } from "../ssr/runtime";
 import { aiProjects } from "./projects";
 import {
@@ -63,6 +64,8 @@ type AiSkillsRouteDependencies = {
 
 const buildAiSkillsRoutes = (dependencies: AiSkillsRouteDependencies = {}) =>
   new Hono<AuthContext>()
+    // The list combines skills from separate grants; the writer of one can rename it next to another skill's text.
+    .use("*", noTransform())
     .onError((error, c) => {
       if (error instanceof AiSkillAppForbiddenError) return respond(c, fail(err.forbidden(error.message)));
       if (error instanceof HTTPException) return error.getResponse();

package/src/ai/skills.ts

@@ -522,7 +522,15 @@ const skillSnapshotFiles = (skill: AiSkill): { path: string; content: string }[]
   ...skill.references.map((reference) => ({ path: `${skill.name}/${reference.path}`, content: reference.content })),
 ];
 
-type SkillListOptions = { name?: string; query?: string; enabledOnly?: boolean; modelInvocableOnly?: boolean; limit?: number };
+type SkillListOptions = {
+  name?: string;
+  /** Only these Skills, by short ID, such as the ones a person recently sent. */
+  shortIds?: readonly string[];
+  query?: string;
+  enabledOnly?: boolean;
+  modelInvocableOnly?: boolean;
+  limit?: number;
+};
 async function listSkillSummaries(
   subject: AccessSubject | null,
   options: SkillListOptions & {
@@ -551,6 +559,7 @@ async function listSkillSummaries(
       ON disabled.skill_id = skill.id AND disabled.user_id = ${userId}::uuid
     WHERE access.permission <> 'none'
       AND ${options.name === undefined ? sql`true` : sql`skill.name = ${options.name}`}
+      AND ${options.shortIds === undefined ? sql`true` : sql`skill.short_id = ANY(${toPgTextArray([...options.shortIds])}::text[])`}
       AND (${!options.manageOnly} OR access.permission='admin')
       AND ${options.project ? sql`EXISTS(SELECT 1 FROM ai.project_skills link WHERE link.skill_id=skill.id AND link.project_id=${options.project.id}::uuid) = ${options.project.linked}` : sql`true`}
       AND (${!options.modelInvocableOnly} OR NOT manual_only)