@k2b/cloud 0.6.0-rc.0

package/src/ai/chat/builtin-tools.tsx

@@ -0,0 +1,428 @@
+import { fileIcons } from "@k2b/stdlib";
+import { useLocale } from "@k2b/ui";
+import { For, type JSX, Show } from "solid-js";
+import { formatAiFileSize } from "../attachments";
+import type { AiTurnBlock } from "../protocol";
+import { aiToolIcon, displayToolName, formatToolDetailText, isRecord } from "./message-utils";
+import { AiToolActivity } from "./tool-disclosure";
+import { aiChatMessages } from "./messages";
+
+type ToolBlock = Extract<AiTurnBlock, { kind: "tool" }>;
+
+const SPECIALIZED_TOOL_NAMES = new Set([
+  "search_tools",
+  "load_tools",
+  "load_skill",
+  "list_apps",
+  "search_help",
+  "read_help",
+  "search_project",
+  "read_project_knowledge",
+  "list_files",
+  "read_file",
+  "write_file",
+  "calculate",
+  "view_image",
+  "markdown_to_pdf",
+  "local_bash",
+  "read_cloud_resource",
+]);
+
+export const hasSpecializedBuiltinToolView = (name: string, result?: unknown): boolean =>
+  SPECIALIZED_TOOL_NAMES.has(name) &&
+  (name !== "load_skill" || (isRecord(result) && typeof result.name === "string" && typeof result.description === "string")) &&
+  (name !== "read_cloud_resource" || (isRecord(result) && typeof result.summary === "string" && result.summary.trim().length > 0));
+
+const text = (value: unknown): string => (typeof value === "string" ? value : "");
+const number = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+const records = (value: unknown): Record<string, unknown>[] => (Array.isArray(value) ? value.filter(isRecord) : []);
+const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1) || path;
+
+function DetailSurface(props: { children: JSX.Element }) {
+  return (
+    <div class="w-full min-w-0 rounded-md bg-zinc-100/70 p-1 text-xs [box-shadow:var(--ui-control-recess)] dark:bg-zinc-950/70">
+      {props.children}
+    </div>
+  );
+}
+
+function ResultList(props: { children: JSX.Element }) {
+  return <div class="flex w-full min-w-0 flex-col text-xs">{props.children}</div>;
+}
+
+function EmptyRow(props: { children: JSX.Element }) {
+  return <p class="px-2 py-1.5 text-dimmed">{props.children}</p>;
+}
+
+function ResultRow(props: { icon: string; title: string; description?: string; meta?: string }) {
+  return (
+    <div class="flex min-w-0 items-center gap-1.5 px-2 py-1.5">
+      <i class={`ti ${props.icon} shrink-0 text-sm text-dimmed`} aria-hidden="true" />
+      <span class="max-w-[42%] shrink-0 truncate font-medium text-primary">{props.title}</span>
+      <Show when={props.description}>
+        <span class="shrink-0 text-dimmed" aria-hidden="true">
+          ·
+        </span>
+        <span class="min-w-0 flex-1 truncate text-dimmed">{props.description}</span>
+      </Show>
+      <Show when={props.meta}>
+        <span class="shrink-0 text-dimmed" aria-hidden="true">
+          ·
+        </span>
+        <span class="shrink-0 text-[11px] text-dimmed">{props.meta}</span>
+      </Show>
+    </div>
+  );
+}
+
+function CompletedActivity(props: {
+  block: ToolBlock;
+  label: string;
+  description?: string;
+  defaultOpen?: boolean;
+  children?: JSX.Element;
+}) {
+  return (
+    <AiToolActivity
+      blockId={props.block.id}
+      icon={aiToolIcon(props.block.name)}
+      label={props.label}
+      description={props.description}
+      defaultOpen={props.defaultOpen}
+      bodyInset={false}
+    >
+      {props.children}
+    </AiToolActivity>
+  );
+}
+
+function SearchToolsView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const tools = () => records(result().tools);
+  const query = () => text(args().query) || "Tools";
+  return (
+    <CompletedActivity block={props.block} label={`Search tools: ${query()}`} description={`${tools().length} found`}>
+      <ResultList>
+        <Show when={tools().length > 0} fallback={<EmptyRow>No tools found.</EmptyRow>}>
+          <For each={tools()}>
+            {(tool) => (
+              <ResultRow
+                icon={tool.kind === "action" ? "ti-bolt" : tool.kind === "query" ? "ti-search" : aiToolIcon(text(tool.name))}
+                title={text(tool.title) || displayToolName(text(tool.name))}
+                description={text(tool.description)}
+                meta={text(tool.appId) || text(tool.kind)}
+              />
+            )}
+          </For>
+        </Show>
+      </ResultList>
+    </CompletedActivity>
+  );
+}
+
+function ListAppsView(props: { block: ToolBlock }) {
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const apps = () => {
+    const value = result().apps;
+    return isRecord(value) ? Object.entries(value) : [];
+  };
+  return (
+    <CompletedActivity block={props.block} label="List apps" description={`${apps().length} available`}>
+      <ResultList>
+        <Show when={apps().length > 0} fallback={<EmptyRow>No capability apps available.</EmptyRow>}>
+          <For each={apps()}>{([appId, description]) => <ResultRow icon="ti-apps" title={appId} description={text(description)} />}</For>
+        </Show>
+      </ResultList>
+    </CompletedActivity>
+  );
+}
+
+function LoadToolsView(props: { block: ToolBlock }) {
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const titles = (): Record<string, unknown> => {
+    const value = result().titles;
+    return isRecord(value) ? value : {};
+  };
+  const groups = () =>
+    (
+      [
+        ["Loaded", result().loaded],
+        ["Already loaded", result().alreadyLoaded],
+        ["Missing", result().missing],
+        ["Evicted", result().evicted],
+      ] as const
+    ).flatMap(([label, value]) =>
+      Array.isArray(value) && value.length > 0 ? [{ label, names: value.filter((name): name is string => typeof name === "string") }] : [],
+    );
+  const loadedCount = () => {
+    const value = result().loaded;
+    return Array.isArray(value) ? value.length : 0;
+  };
+  return (
+    <CompletedActivity block={props.block} label="Load tools" description={`${loadedCount()} loaded`}>
+      <Show when={groups().length > 0}>
+        <ResultList>
+          <For each={groups()}>
+            {(group) => (
+              <For each={group.names}>
+                {(name) => <ResultRow icon={aiToolIcon(name)} title={text(titles()[name]) || name} meta={group.label} />}
+              </For>
+            )}
+          </For>
+        </ResultList>
+      </Show>
+    </CompletedActivity>
+  );
+}
+
+function LoadSkillView(props: { block: ToolBlock }) {
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  return (
+    <CompletedActivity block={props.block} label={`Loaded skill ${text(result().name)}`}>
+      <DetailSurface>
+        <p class="whitespace-pre-wrap px-2 py-1.5 leading-5 text-secondary">{text(result().description)}</p>
+      </DetailSurface>
+    </CompletedActivity>
+  );
+}
+
+function SearchHelpView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const documents = () => records(result().documents);
+  const query = () => text(args().query) || "Help";
+  return (
+    <CompletedActivity block={props.block} label={`Search help: ${query()}`} description={`${documents().length} found`}>
+      <ResultList>
+        <Show when={documents().length > 0} fallback={<EmptyRow>No Help articles found.</EmptyRow>}>
+          <For each={documents()}>
+            {(document) => (
+              <ResultRow
+                icon="ti-help-circle"
+                title={text(document.title) || text(document.documentId)}
+                description={text(document.description)}
+                meta={text(document.appName) || text(document.appId)}
+              />
+            )}
+          </For>
+        </Show>
+      </ResultList>
+    </CompletedActivity>
+  );
+}
+
+function ReadHelpView(props: { block: ToolBlock }) {
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const document = (): Record<string, unknown> | null => {
+    const value = result().document;
+    return isRecord(value) ? value : null;
+  };
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={document() ? `Read help: ${text(document()!.title)}` : "Read help"}
+      description={document() ? text(document()!.appName) || text(document()!.appId) : "Article not found"}
+    />
+  );
+}
+
+function SearchProjectView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const items = () => records(result().items);
+  const query = () => text(args().query);
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={query() ? `Search Project: ${query()}` : "List Project sources"}
+      description={`${items().length} found${result().truncated === true ? "+" : ""}`}
+    >
+      <ResultList>
+        <Show when={items().length > 0} fallback={<EmptyRow>No Project sources found.</EmptyRow>}>
+          <For each={items()}>
+            {(item) => {
+              const kind = text(item.kind);
+              const path = text(item.path);
+              const ref = isRecord(item.ref) ? `${text(item.ref.type)}:${text(item.ref.id)}` : "";
+              return (
+                <ResultRow
+                  icon={
+                    kind === "file"
+                      ? fileIcons.getFileIcon({ name: basename(path), type: "file", mimeType: text(item.mediaType) })
+                      : kind === "reference"
+                        ? "ti-link"
+                        : "ti-book"
+                  }
+                  title={text(item.title) || basename(path) || ref}
+                  description={path || ref}
+                  meta={kind}
+                />
+              );
+            }}
+          </For>
+        </Show>
+      </ResultList>
+    </CompletedActivity>
+  );
+}
+
+function ReadProjectKnowledgeView(props: { block: ToolBlock }) {
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  return <CompletedActivity block={props.block} label={`Read Project knowledge: ${text(result().title) || "Entry"}`} />;
+}
+
+function ListFilesView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const files = () => records(result().files);
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={`List files: ${text(args().path) || "/"}`}
+      description={`${files().length} found${result().truncated === true ? "+" : ""}`}
+    >
+      <ResultList>
+        <Show when={files().length > 0} fallback={<EmptyRow>No files found.</EmptyRow>}>
+          <For each={files()}>
+            {(file) => {
+              const path = text(file.path);
+              return (
+                <ResultRow
+                  icon={fileIcons.getFileIcon({ name: basename(path), type: "file", mimeType: text(file.mediaType) })}
+                  title={basename(path)}
+                  description={path}
+                  meta={number(file.size) > 0 ? formatAiFileSize(number(file.size)) : text(file.origin)}
+                />
+              );
+            }}
+          </For>
+        </Show>
+      </ResultList>
+    </CompletedActivity>
+  );
+}
+
+function FileOperationView(props: { block: ToolBlock; verb: string; resultPath?: string }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const path = () => props.resultPath || text(result().path) || text(args().path);
+  const size = () => number(result().size);
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={`${props.verb}: ${basename(path()) || "File"}`}
+      description={[path(), size() > 0 ? formatAiFileSize(size()) : ""].filter(Boolean).join(" · ")}
+    />
+  );
+}
+
+function ReadFileView(props: { block: ToolBlock }) {
+  const locale = useLocale();
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const path = () => text(result().path) || (isRecord(props.block.args) ? text(props.block.args.path) : "");
+  const range = () => {
+    const start = number(result().offset);
+    const end = number(result().nextOffset);
+    const t = aiChatMessages(locale());
+    return end > start
+      ? t.byteRange({ start: start.toLocaleString(locale()), end: end.toLocaleString(locale()) })
+      : t.read;
+  };
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={`Read file: ${basename(path())}`}
+      description={`${range()}${result().eof === true ? " · complete" : " · more available"}`}
+    />
+  );
+}
+
+function CalculateView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  return <CompletedActivity block={props.block} label={text(args().expression) || "Calculate"} description={text(result().result)} />;
+}
+
+function ViewImageView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const path = () => text(result().path) || text(args().path);
+  return (
+    <CompletedActivity block={props.block} label={`Inspect image: ${basename(path())}`} defaultOpen>
+      <DetailSurface>
+        <p class="whitespace-pre-wrap px-2 py-1.5 leading-5 text-secondary">{text(result().description)}</p>
+      </DetailSurface>
+    </CompletedActivity>
+  );
+}
+
+function LocalBashView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  return (
+    <CompletedActivity block={props.block} label="Local Bash">
+      <div class="flex w-full min-w-0 flex-col gap-2">
+        <pre class="max-h-40 w-full min-w-0 overflow-auto whitespace-pre-wrap rounded-md bg-zinc-100 p-2 font-mono text-[11px] leading-4 text-primary [box-shadow:var(--ui-control-recess)] dark:bg-zinc-950/70">
+          {text(args().command)}
+        </pre>
+        <pre class="max-h-64 w-full min-w-0 overflow-auto whitespace-pre-wrap rounded-md bg-zinc-100 p-2 font-mono text-[11px] leading-4 text-primary [box-shadow:var(--ui-control-recess)] dark:bg-zinc-950/70">
+          {formatToolDetailText(props.block.name, props.block.result)}
+        </pre>
+      </div>
+    </CompletedActivity>
+  );
+}
+
+function CloudResourceView(props: { block: ToolBlock }) {
+  const args = () => (isRecord(props.block.args) ? props.block.args : {});
+  const result = () => (isRecord(props.block.result) ? props.block.result : {});
+  const summary = () => text(result().summary);
+  return (
+    <CompletedActivity
+      block={props.block}
+      label={`Read resource: ${text(args().type)}:${text(args().id)}`}
+      description={summary() || undefined}
+    />
+  );
+}
+
+export function SpecializedBuiltinToolBlock(props: { block: ToolBlock }) {
+  switch (props.block.name) {
+    case "search_tools":
+      return <SearchToolsView block={props.block} />;
+    case "load_tools":
+      return <LoadToolsView block={props.block} />;
+    case "load_skill":
+      return <LoadSkillView block={props.block} />;
+    case "list_apps":
+      return <ListAppsView block={props.block} />;
+    case "search_help":
+      return <SearchHelpView block={props.block} />;
+    case "read_help":
+      return <ReadHelpView block={props.block} />;
+    case "search_project":
+      return <SearchProjectView block={props.block} />;
+    case "read_project_knowledge":
+      return <ReadProjectKnowledgeView block={props.block} />;
+    case "list_files":
+      return <ListFilesView block={props.block} />;
+    case "read_file":
+      return <ReadFileView block={props.block} />;
+    case "write_file":
+      return <FileOperationView block={props.block} verb="Wrote file" />;
+    case "calculate":
+      return <CalculateView block={props.block} />;
+    case "view_image":
+      return <ViewImageView block={props.block} />;
+    case "markdown_to_pdf": {
+      const result = isRecord(props.block.result) ? props.block.result : {};
+      return <FileOperationView block={props.block} verb="Created PDF" resultPath={text(result.path)} />;
+    }
+    case "local_bash":
+      return <LocalBashView block={props.block} />;
+    case "read_cloud_resource":
+      return <CloudResourceView block={props.block} />;
+    default:
+      return null;
+  }
+}

package/src/ai/chat/capability-table.tsx

@@ -0,0 +1,87 @@
+import { ButtonLink, DataTable, type DataTableColumn, useLocale } from "@k2b/ui";
+import { createMemo, For, Show } from "solid-js";
+import { CapabilitySemanticLinkSchema, CapabilityTablePresentationSchema, capabilityDataAtPath } from "../../contracts/capabilities";
+import { aiChatMessages } from "./messages";
+
+export const capabilityTable = (result: unknown) => {
+  if (!result || typeof result !== "object") return null;
+  const presentation = CapabilityTablePresentationSchema.safeParse(capabilityDataAtPath(result, ["presentation"]));
+  if (!presentation.success) return null;
+  const rows = capabilityDataAtPath(capabilityDataAtPath(result, ["data"]), presentation.data.rowsPath);
+  if (!Array.isArray(rows)) return null;
+  return { presentation: presentation.data, rows };
+};
+
+export const capabilityCellText = (value: unknown): string => {
+  if (value === undefined || value === null) return "—";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value) ?? "—";
+};
+
+export function CapabilityTablePreview(props: { result: unknown; label: string }) {
+  const locale = useLocale();
+  const t = () => aiChatMessages(locale());
+  const table = createMemo(() => capabilityTable(props.result));
+  const linksId = "row-links";
+  const columns = createMemo<DataTableColumn<unknown>[]>(() => {
+    const value = table();
+    if (!value) return [];
+    return [
+      ...value.presentation.columns.map((column, index) => ({
+        id: String(index),
+        header: column.label,
+        value: (row: unknown) => capabilityCellText(capabilityDataAtPath(row, column.path)),
+        align: column.format === "number" ? ("right" as const) : ("left" as const),
+      })),
+      ...(value.presentation.rowLinksPath ? [{ id: linksId, header: t().tableLinks }] : []),
+    ];
+  });
+  const rowLinks = (row: unknown) => {
+    const path = table()?.presentation.rowLinksPath;
+    const links = path ? capabilityDataAtPath(row, path) : undefined;
+    return Array.isArray(links)
+      ? links.slice(0, 20).flatMap((link) => {
+          const parsed = CapabilitySemanticLinkSchema.safeParse(link);
+          return parsed.success ? [parsed.data] : [];
+        })
+      : [];
+  };
+  return (
+    <Show when={table()}>
+      {(value) => (
+        <div class="my-2 min-w-0 space-y-2">
+          <DataTable
+            rows={value().rows.slice(0, 100)}
+            columns={columns()}
+            density="compact"
+            surface="plain"
+            ariaLabel={props.label}
+            class="max-h-80 overflow-auto"
+            empty={<span>{t().tableEmpty}</span>}
+            renderCell={({ row, col, value: cell }) =>
+              col.id === linksId ? (
+                <For each={rowLinks(row)}>
+                  {(link) => (
+                    <ButtonLink href={link.href} target="_blank" rel="noopener noreferrer" variant="ghost" size="xs">
+                      {link.title ?? t().tableOpen}
+                    </ButtonLink>
+                  )}
+                </For>
+              ) : (
+                <span class="block max-w-80 truncate" title={String(cell)}>
+                  {String(cell)}
+                </span>
+              )
+            }
+          />
+          <Show when={value().rows.length > 100}>
+            <p class="text-sm text-secondary">{t().tableCapped}</p>
+          </Show>
+          <Show when={capabilityDataAtPath(props.result, ["page", "hasMore"]) === true}>
+            <p class="text-sm text-secondary">{t().tableMore}</p>
+          </Show>
+        </div>
+      )}
+    </Show>
+  );
+}

package/src/ai/chat/composer-adapter.ts

@@ -0,0 +1,169 @@
+import type { ChatAttachment, ChatModelOption, ChatSubmitInput } from "@k2b/ui";
+import { AI_TURN_IMAGE_MAX_TOTAL_BYTES } from "../limits";
+import type { AiResourceMarker } from "../resource-markers";
+import type { AiPublicModelProfile, AiUserContentPart } from "../types";
+import {
+  type AiComposerAttachment,
+  FILE_INPUT_ACCEPT,
+  imageSrc,
+  MAX_ATTACHMENTS,
+  type PendingAiImage,
+  type PendingAiVfsFile,
+  readImageFile,
+  readVfsFile,
+} from "./message-utils";
+
+export type { AiComposerAttachment } from "./message-utils";
+
+export const AI_PASTED_TEXT_ATTACHMENT_THRESHOLD = 8_000;
+export const AI_COMPOSER_TEXT_MAX_CHARS = 20_000;
+const AI_COMPOSER_TEXT_MAX_BYTES = AI_COMPOSER_TEXT_MAX_CHARS * 4;
+const AI_PASTED_TEXT_FILE_NAME = /^pasted-(?:text|[a-f0-9]{8})(?:-\d+)?\.txt$/i;
+
+export type AiComposerSendInput = {
+  message?: string;
+  content?: AiUserContentPart[];
+  files?: File[];
+  resources?: AiResourceMarker[];
+  storedFiles?: Array<{ path: string; mediaType: string; size: number; version: number }>;
+};
+
+export type AiComposerFileResult = {
+  attachments: AiComposerAttachment[];
+  errors: string[];
+  discarded: number;
+};
+
+export const aiComposerFileAccept = FILE_INPUT_ACCEPT;
+
+export const aiChatModelOptions = (profiles: readonly AiPublicModelProfile[]): ChatModelOption[] =>
+  profiles.map((profile) => ({
+    id: profile.id,
+    label: profile.label,
+    description: profile.model,
+    image: profile.image,
+    icon: profile.capabilities.includes("vision") ? "ti ti-photo-spark" : "ti ti-message",
+    capabilities: profile.capabilities,
+  }));
+
+const isTextAttachment = (
+  attachment: AiComposerAttachment,
+): attachment is Extract<AiComposerAttachment, { kind: "file" | "stored-file" }> =>
+  (attachment.kind === "file" || attachment.kind === "stored-file") &&
+  (attachment.mediaType.startsWith("text/") || ["application/json", "application/xml", "application/yaml"].includes(attachment.mediaType));
+
+const attachmentName = (attachment: AiComposerAttachment): string =>
+  isTextAttachment(attachment) && AI_PASTED_TEXT_FILE_NAME.test(attachment.name) ? "Pasted text" : attachment.name;
+
+export const aiChatAttachments = (
+  attachments: readonly AiComposerAttachment[],
+  options: { onShowText?: (attachment: AiComposerAttachment) => void | Promise<void> } = {},
+): ChatAttachment[] =>
+  attachments.map((attachment) => ({
+    id: attachment.id,
+    name: attachmentName(attachment),
+    size: "size" in attachment ? attachment.size : undefined,
+    kind: attachment.kind === "image" ? "image" : attachment.kind === "resource" ? "resource" : "file",
+    icon:
+      attachment.kind === "image"
+        ? "ti ti-photo"
+        : isTextAttachment(attachment)
+          ? "ti ti-file-text"
+          : attachment.icon.startsWith("ti ")
+            ? attachment.icon
+            : `ti ${attachment.icon}`,
+    href: attachment.kind === "resource" ? attachment.href : undefined,
+    previewUrl: attachment.kind === "image" ? imageSrc(attachment) : undefined,
+    data: attachment,
+    action:
+      options.onShowText && isTextAttachment(attachment) && attachment.size <= AI_COMPOSER_TEXT_MAX_BYTES
+        ? {
+            id: "show-text",
+            label: "Show in text field",
+            icon: "ti ti-text-plus",
+            onSelect: () => options.onShowText?.(attachment),
+          }
+        : undefined,
+  }));
+
+export const createAiPastedTextFile = (text: string): File =>
+  new File([text], `pasted-${crypto.randomUUID().replaceAll("-", "").slice(0, 8)}.txt`, { type: "text/plain" });
+
+export const shouldAttachAiPastedText = (text: string, currentTextLength = 0): boolean =>
+  text.length >= AI_PASTED_TEXT_ATTACHMENT_THRESHOLD || currentTextLength + text.length > AI_COMPOSER_TEXT_MAX_CHARS;
+
+const isAiComposerAttachment = (value: unknown): value is AiComposerAttachment => {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<AiComposerAttachment>;
+  return (
+    ["image", "file", "stored-file", "resource"].includes(candidate.kind ?? "") &&
+    typeof candidate.id === "string" &&
+    typeof candidate.name === "string"
+  );
+};
+
+export const aiComposerAttachmentRecords = (attachments: readonly ChatAttachment[]): AiComposerAttachment[] =>
+  attachments.map((attachment) => attachment.data).filter(isAiComposerAttachment);
+
+export const aiComposerSendInput = (input: ChatSubmitInput): AiComposerSendInput => {
+  const attachments = aiComposerAttachmentRecords(input.attachments);
+  const files = attachments.filter(
+    (attachment): attachment is PendingAiImage | PendingAiVfsFile => attachment.kind === "image" || attachment.kind === "file",
+  );
+  const resources = attachments
+    .filter((attachment) => attachment.kind === "resource")
+    .map((attachment) => ({ ref: attachment.ref, title: attachment.name, icon: attachment.icon, href: attachment.href }));
+  const storedFiles = attachments
+    .filter((attachment) => attachment.kind === "stored-file")
+    .map(({ path, mediaType, size, version }) => ({ path, mediaType, size, version }));
+  const content =
+    attachments.length > 0
+      ? ([...(input.text ? [{ type: "text" as const, text: input.text }] : [])] satisfies AiUserContentPart[])
+      : undefined;
+
+  return {
+    message: input.text || undefined,
+    content: content?.length ? content : undefined,
+    files: files.length ? files.map((attachment) => attachment.file) : undefined,
+    resources: resources.length ? resources : undefined,
+    storedFiles: storedFiles.length ? storedFiles : undefined,
+  };
+};
+
+export const readAiComposerFiles = async (
+  files: readonly File[],
+  options: {
+    acceptsImages?: boolean;
+    currentCount?: number;
+    currentImageBytes?: number;
+  },
+): Promise<AiComposerFileResult> => {
+  const remaining = Math.max(0, MAX_ATTACHMENTS - (options.currentCount ?? 0));
+  const candidates = files.slice(0, remaining);
+  const errors: string[] = [];
+  const attachments: AiComposerAttachment[] = [];
+  let imageBytes = options.currentImageBytes ?? 0;
+
+  for (const file of candidates) {
+    if (file.type.startsWith("image/") && options.acceptsImages === false) {
+      errors.push(`${file.name}: choose a Vision model or configure the view_image fallback.`);
+      continue;
+    }
+    if (file.type.startsWith("image/") && imageBytes + file.size > AI_TURN_IMAGE_MAX_TOTAL_BYTES) {
+      errors.push(`${file.name}: image attachments exceed the ${AI_TURN_IMAGE_MAX_TOTAL_BYTES / (1024 * 1024)} MB total limit.`);
+      continue;
+    }
+    try {
+      attachments.push(file.type.startsWith("image/") ? await readImageFile(file) : await readVfsFile(file));
+      if (file.type.startsWith("image/")) imageBytes += file.size;
+    } catch (error) {
+      errors.push(error instanceof Error ? error.message : `${file.name}: attachment failed.`);
+    }
+  }
+
+  return {
+    attachments,
+    errors,
+    discarded: Math.max(0, files.length - candidates.length),
+  };
+};