@k2b/cloud 0.6.0-rc.0

package/src/account/avatar-upload.ts

@@ -0,0 +1,149 @@
+import { createCroppedImageCanvas, type ImageCropState } from "@k2b/ui";
+import { MAX_AVATAR_BYTES, MAX_AVATAR_DATA_URL_LENGTH } from "../contracts";
+
+const ACCEPTED_AVATAR_TYPES = new Set(["image/png", "image/jpeg", "image/webp"]);
+const MAX_SOURCE_AVATAR_BYTES = 32 * 1024 * 1024;
+const AVATAR_CANVAS_SIZES = [256, 192, 160, 128, 96, 64] as const;
+const AVATAR_OUTPUT_ATTEMPTS = [
+  { type: "image/webp", qualities: [0.86, 0.76, 0.66, 0.56, 0.46, 0.36] },
+  { type: "image/jpeg", qualities: [0.84, 0.74, 0.64, 0.54, 0.44, 0.34] },
+  { type: "image/png", qualities: [undefined] },
+] as const;
+
+export class AvatarUploadError extends Error {
+  constructor(readonly code: "type_invalid" | "too_large" | "empty" | "unsupported" | "compression_failed") {
+    super(code);
+    this.name = "AvatarUploadError";
+  }
+}
+
+const blobToDataUrl = (blob: Blob): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error("Failed to read avatar image."));
+    reader.readAsDataURL(blob);
+  });
+
+const canvasToBlob = (canvas: HTMLCanvasElement, type: string, quality?: number): Promise<Blob | null> =>
+  new Promise((resolve) => canvas.toBlob(resolve, type, quality));
+
+const fitsAvatarLimits = async (blob: Blob): Promise<string | null> => {
+  if (blob.size > MAX_AVATAR_BYTES) return null;
+  const dataUrl = await blobToDataUrl(blob);
+  return dataUrl.length <= MAX_AVATAR_DATA_URL_LENGTH ? dataUrl : null;
+};
+
+const loadImage = async (file: File): Promise<HTMLImageElement> => {
+  const url = URL.createObjectURL(file);
+  const image = new Image();
+  image.src = url;
+  try {
+    await image.decode();
+    return image;
+  } catch {
+    await new Promise<void>((resolve, reject) => {
+      image.onload = () => resolve();
+      image.onerror = () => reject(new Error("Failed to decode avatar image."));
+    });
+    return image;
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+};
+
+export const validateAvatarSourceFile = (file: File): void => {
+  if (!ACCEPTED_AVATAR_TYPES.has(file.type)) {
+    throw new AvatarUploadError("type_invalid");
+  }
+  if (file.size > MAX_SOURCE_AVATAR_BYTES) {
+    throw new AvatarUploadError("too_large");
+  }
+};
+
+export const createAvatarDataUrlFromFile = async (file: File, cropState?: ImageCropState): Promise<string> => {
+  validateAvatarSourceFile(file);
+
+  if (cropState) {
+    for (const size of AVATAR_CANVAS_SIZES) {
+      const canvas = await createCroppedImageCanvas(file, cropState, { width: size, height: size });
+
+      for (const attempt of AVATAR_OUTPUT_ATTEMPTS) {
+        for (const quality of attempt.qualities) {
+          const blob = await canvasToBlob(canvas, attempt.type, quality);
+          if (!blob || blob.type !== attempt.type) continue;
+          const dataUrl = await fitsAvatarLimits(blob);
+          if (dataUrl) return dataUrl;
+        }
+      }
+    }
+
+    throw new AvatarUploadError("compression_failed");
+  }
+
+  const image = await loadImage(file);
+  const sourceSize = Math.min(image.naturalWidth, image.naturalHeight);
+  if (!sourceSize) throw new AvatarUploadError("empty");
+
+  const sourceX = Math.floor((image.naturalWidth - sourceSize) / 2);
+  const sourceY = Math.floor((image.naturalHeight - sourceSize) / 2);
+
+  for (const size of AVATAR_CANVAS_SIZES) {
+    const canvas = document.createElement("canvas");
+    canvas.width = size;
+    canvas.height = size;
+    const context = canvas.getContext("2d");
+    if (!context) throw new AvatarUploadError("unsupported");
+    context.drawImage(image, sourceX, sourceY, sourceSize, sourceSize, 0, 0, size, size);
+
+    for (const attempt of AVATAR_OUTPUT_ATTEMPTS) {
+      for (const quality of attempt.qualities) {
+        const blob = await canvasToBlob(canvas, attempt.type, quality);
+        if (!blob || blob.type !== attempt.type) continue;
+        const dataUrl = await fitsAvatarLimits(blob);
+        if (dataUrl) return dataUrl;
+      }
+    }
+  }
+
+  throw new AvatarUploadError("compression_failed");
+};
+
+export const pickAvatarDataUrl = (): Promise<string | null> =>
+  new Promise((resolve, reject) => {
+    const input = document.createElement("input");
+    let settled = false;
+    input.type = "file";
+    input.accept = "image/png,image/jpeg,image/webp";
+
+    const settle = (value: string | null, error?: unknown) => {
+      if (settled) return;
+      settled = true;
+      window.removeEventListener("focus", handleFocus);
+      input.remove();
+      if (error) reject(error);
+      else resolve(value);
+    };
+
+    const handleFocus = () => {
+      setTimeout(() => {
+        if (!input.files?.length) settle(null);
+      }, 250);
+    };
+
+    input.onchange = async () => {
+      const file = input.files?.[0];
+      if (!file) {
+        settle(null);
+        return;
+      }
+      try {
+        settle(await createAvatarDataUrlFromFile(file));
+      } catch (error) {
+        settle(null, error);
+      }
+    };
+
+    window.addEventListener("focus", handleFocus);
+    input.click();
+  });

package/src/account/ui.ts

@@ -0,0 +1,3 @@
+export { CloudAvatar, type CloudAvatarProps } from "./Avatar";
+export { type AvatarUploadDialogOptions, openAvatarUploadDialog } from "./avatar-upload-dialog";
+export { default as EntitySearch, type EntitySearchPrincipal } from "./EntitySearch";

package/src/ai/admin.ts

@@ -0,0 +1,47 @@
+/** Server-only AI administration and usage accounting. */
+export {
+  type AiUsageRun,
+  type AiUsageStats,
+  type AiUsageGroup,
+  type AiUsagePage,
+  AI_USAGE_RANGES,
+  type AiUsageBackgroundTask,
+  type AiUsageCapability,
+  type AiUsageFeedback,
+  type AiUsageLaunch,
+  type AiUsageModel,
+  type AiUsageOverview,
+  type AiUsagePoint,
+  type AiUsageRange,
+  type AiUsagePagination,
+  type AiUsageReportOptions,
+  type AiUsageReport,
+  type AiUsageUser,
+  aiUsage,
+} from "./usage";
+
+export { type AiModelAccessDraft, type AiModelAccessMap, type AiModelAccessState, aiModelAccess } from "./model-access";
+
+import { ENRICH_SYSTEM_PROMPT, ENRICH_OUTPUT_CONTRACT } from "./enrich";
+import {
+  MEMORY_LEARNING_PROMPT,
+  MEMORY_LEARNING_OUTPUT_CONTRACT,
+  WORKFLOW_PATTERN_PROMPT,
+  WORKFLOW_PATTERN_OUTPUT_CONTRACT,
+} from "./memory-learning";
+import { DEFAULT_COMPACTION_PROMPT, COMPACTION_OUTPUT_CONTRACT } from "./compaction";
+import { buildAiTaskPrompt } from "./task-prompt";
+
+/** Built-in task instructions for the admin viewer; excludes organization guidance and runtime input. */
+export const AI_BACKGROUND_TASK_PROMPTS = {
+  "ai.chat_enrichment_instructions": [
+    buildAiTaskPrompt({ baseInstructions: ENRICH_SYSTEM_PROMPT, outputContract: ENRICH_OUTPUT_CONTRACT }),
+  ],
+  "ai.memory_learning_instructions": [
+    buildAiTaskPrompt({ baseInstructions: MEMORY_LEARNING_PROMPT, outputContract: MEMORY_LEARNING_OUTPUT_CONTRACT }),
+    buildAiTaskPrompt({ baseInstructions: WORKFLOW_PATTERN_PROMPT, outputContract: WORKFLOW_PATTERN_OUTPUT_CONTRACT }),
+  ],
+  "ai.compaction_instructions": [
+    buildAiTaskPrompt({ baseInstructions: DEFAULT_COMPACTION_PROMPT, outputContract: COMPACTION_OUTPUT_CONTRACT }),
+  ],
+};

package/src/ai/approval-routes.ts

@@ -0,0 +1,130 @@
+import { Hono, type MiddlewareHandler } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { listCapabilities } from "../_internal/registry";
+import { ErrorResponseSchema } from "../contracts";
+import type { CapabilityRegistryEntry } from "../contracts/registry";
+import { type AuthContext, auth, expectUserBackedActor, jsonResponse, rateLimit, requiresAuth, v } from "../server";
+import { type AiToolApprovalPreference, listAiToolApprovalPreferences, revokeAiToolApprovalPreference } from "./approvals";
+import { buildAiCapabilityCatalog } from "./capabilities";
+
+export type AiApprovalPreferenceView = AiToolApprovalPreference & {
+  title: string;
+  app: {
+    id: string;
+    name: string;
+    icon: string;
+    accent?: string;
+  } | null;
+};
+
+const AiApprovalPreferenceSchema = z.object({
+  id: z.uuid(),
+  toolName: z.string(),
+  approvalScope: z.string(),
+  createdAt: z.iso.datetime(),
+  lastUsedAt: z.iso.datetime().nullable(),
+  expiresAt: z.iso.datetime().nullable(),
+  title: z.string(),
+  app: z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      icon: z.string(),
+      accent: z.string().optional(),
+    })
+    .nullable(),
+});
+
+const AiApprovalPreferenceListSchema = z.object({ approvals: z.array(AiApprovalPreferenceSchema) });
+const AiApprovalPreferenceParamSchema = z.object({ preferenceId: z.uuid() });
+const AiApprovalPreferenceDeleteSchema = z.object({ deleted: z.literal(true) });
+
+type AiApprovalRouteDependencies = {
+  limit?: MiddlewareHandler<AuthContext>;
+  authenticate?: MiddlewareHandler<AuthContext>;
+  listPreferences?: (actorUserId: string) => Promise<AiToolApprovalPreference[]>;
+  revokePreference?: (actorUserId: string, preferenceId: string) => Promise<boolean>;
+  listCapabilities?: () => Promise<CapabilityRegistryEntry[]>;
+};
+
+const fallbackTitle = (toolName: string): string => {
+  const label = toolName
+    .replaceAll("__", " ")
+    .replace(/[-_.]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return label ? `${label[0]!.toUpperCase()}${label.slice(1)}` : toolName;
+};
+
+export const createAiApprovalPreferenceRoutes = (dependencies: AiApprovalRouteDependencies = {}) => {
+  const listPreferences = dependencies.listPreferences ?? listAiToolApprovalPreferences;
+  const revokePreference = dependencies.revokePreference ?? revokeAiToolApprovalPreference;
+  const registry = dependencies.listCapabilities ?? listCapabilities;
+
+  return new Hono<AuthContext>()
+    .use(dependencies.limit ?? rateLimit())
+    .use("*", dependencies.authenticate ?? auth.requireRole("authenticated"))
+    .get(
+      "/",
+      describeRoute({
+        tags: ["AI"],
+        summary: "List remembered AI approvals",
+        description: "Lists AI tool approvals remembered for the current user.",
+        ...requiresAuth,
+        responses: {
+          200: jsonResponse(AiApprovalPreferenceListSchema, "Remembered approvals"),
+          401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+          403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
+        },
+      }),
+      async (c) => {
+        const user = expectUserBackedActor(c);
+        const [preferences, capabilities] = await Promise.all([
+          listPreferences(user.id),
+          registry().catch(() => [] as CapabilityRegistryEntry[]),
+        ]);
+        const catalogByName = new Map(buildAiCapabilityCatalog(capabilities).map((entry) => [entry.name, entry]));
+        const approvals: AiApprovalPreferenceView[] = preferences.map((preference) => {
+          const capability = catalogByName.get(preference.toolName);
+          return {
+            ...preference,
+            title: capability?.title ?? fallbackTitle(preference.toolName),
+            app: capability
+              ? {
+                  id: capability.appId,
+                  name: capability.appName,
+                  icon: capability.app.appIcon,
+                  ...(capability.app.appAccent ? { accent: capability.app.appAccent } : {}),
+                }
+              : null,
+          };
+        });
+        return c.json({ approvals });
+      },
+    )
+    .delete(
+      "/:preferenceId",
+      describeRoute({
+        tags: ["AI"],
+        summary: "Revoke a remembered AI approval",
+        description: "Revokes one remembered AI tool approval owned by the current user.",
+        ...requiresAuth,
+        responses: {
+          200: jsonResponse(AiApprovalPreferenceDeleteSchema, "Approval revoked"),
+          400: jsonResponse(ErrorResponseSchema, "Invalid approval id"),
+          401: jsonResponse(ErrorResponseSchema, "Authentication required"),
+          403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
+          404: jsonResponse(ErrorResponseSchema, "Approval not found"),
+        },
+      }),
+      v("param", AiApprovalPreferenceParamSchema),
+      async (c) => {
+        const user = expectUserBackedActor(c);
+        const deleted = await revokePreference(user.id, c.req.valid("param").preferenceId);
+        return deleted ? c.json({ deleted: true as const }) : c.json({ message: "Approval not found", code: "NOT_FOUND" }, 404);
+      },
+    );
+};
+
+export type AiApprovalPreferenceRoutes = ReturnType<typeof createAiApprovalPreferenceRoutes>;

package/src/ai/approvals.ts

@@ -0,0 +1,139 @@
+import { sql } from "bun";
+import type { AiToolApprovalPolicy, AiTurnRunConfig } from "./types";
+
+/** Background authority never inherits a user's interactive Always Allow preference. */
+export const aiTurnAllowsRememberedApprovals = (config: AiTurnRunConfig | null | undefined): boolean =>
+  config == null || config.kind === "compact" || config.mandate === undefined;
+
+export type AiToolApprovalContext = {
+  actorUserId: string;
+};
+
+export type AiToolApprovalPreference = {
+  id: string;
+  toolName: string;
+  approvalScope: string;
+  createdAt: string;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+};
+
+type AiToolApprovalPreferenceRow = {
+  id: string;
+  tool_name: string;
+  approval_scope: string;
+  created_at: Date | string;
+  last_used_at: Date | string | null;
+  expires_at: Date | string | null;
+};
+
+export const aiToolApprovalScope = (toolName: string, policy: AiToolApprovalPolicy | undefined): string => {
+  if (policy && typeof policy === "object") return policy.scope ?? toolName;
+  return toolName;
+};
+
+export const aiToolNeedsApproval = (policy: AiToolApprovalPolicy | undefined): boolean => policy !== "never";
+
+export const aiToolAllowsAlways = (policy: AiToolApprovalPolicy | undefined): boolean =>
+  policy === "always" || (typeof policy === "object" && policy.kind === "user-configurable");
+
+export const hasRememberedAiToolApproval = async (
+  context: AiToolApprovalContext,
+  input: { toolName: string; approvalScope: string },
+): Promise<boolean> => {
+  const rows = await sql<{ id: string }[]>`
+    SELECT id
+    FROM ai.tool_approval_preferences
+    WHERE actor_user_id = ${context.actorUserId}
+      AND tool_name = ${input.toolName}
+      AND approval_scope = ${input.approvalScope}
+      AND (expires_at IS NULL OR expires_at > now())
+    LIMIT 1
+  `;
+
+  const id = rows[0]?.id;
+  if (!id) return false;
+  await sql`UPDATE ai.tool_approval_preferences SET last_used_at = now() WHERE id = ${id}`;
+  return true;
+};
+
+export const rememberAiToolApproval = async (
+  context: AiToolApprovalContext,
+  input: { toolName: string; approvalScope: string; expiresAt?: Date | null },
+): Promise<void> => {
+  await sql.begin(async () => {
+    await sql`
+      DELETE FROM ai.tool_approval_preferences
+      WHERE actor_user_id = ${context.actorUserId}
+        AND tool_name = ${input.toolName}
+        AND approval_scope = ${input.approvalScope}
+    `;
+
+    await sql`
+      INSERT INTO ai.tool_approval_preferences (
+        actor_user_id,
+        tool_name,
+        approval_scope,
+        last_used_at,
+        expires_at
+      )
+      VALUES (
+        ${context.actorUserId},
+        ${input.toolName},
+        ${input.approvalScope},
+        now(),
+        ${input.expiresAt ?? null}
+      )
+    `;
+  });
+};
+
+export const forgetAiToolApproval = async (
+  context: AiToolApprovalContext,
+  input: { toolName: string; approvalScope: string },
+): Promise<void> => {
+  await sql`
+    DELETE FROM ai.tool_approval_preferences
+    WHERE actor_user_id = ${context.actorUserId}
+      AND tool_name = ${input.toolName}
+      AND approval_scope = ${input.approvalScope}
+  `;
+};
+
+const toIsoString = (value: Date | string): string => (value instanceof Date ? value : new Date(value)).toISOString();
+
+const approvalPreferenceFromRow = (row: AiToolApprovalPreferenceRow): AiToolApprovalPreference => ({
+  id: row.id,
+  toolName: row.tool_name,
+  approvalScope: row.approval_scope,
+  createdAt: toIsoString(row.created_at),
+  lastUsedAt: row.last_used_at ? toIsoString(row.last_used_at) : null,
+  expiresAt: row.expires_at ? toIsoString(row.expires_at) : null,
+});
+
+export const listAiToolApprovalPreferences = async (actorUserId: string): Promise<AiToolApprovalPreference[]> => {
+  const rows = await sql<AiToolApprovalPreferenceRow[]>`
+    SELECT
+      id,
+      tool_name,
+      approval_scope,
+      created_at,
+      last_used_at,
+      expires_at
+    FROM ai.tool_approval_preferences
+    WHERE actor_user_id = ${actorUserId}
+      AND (expires_at IS NULL OR expires_at > now())
+    ORDER BY last_used_at DESC NULLS LAST, created_at DESC, id
+  `;
+  return rows.map(approvalPreferenceFromRow);
+};
+
+export const revokeAiToolApprovalPreference = async (actorUserId: string, preferenceId: string): Promise<boolean> => {
+  const rows = await sql<{ id: string }[]>`
+    DELETE FROM ai.tool_approval_preferences
+    WHERE id = ${preferenceId}
+      AND actor_user_id = ${actorUserId}
+    RETURNING id
+  `;
+  return rows.length > 0;
+};

package/src/ai/assistant-models.ts

@@ -0,0 +1,61 @@
+import type { AccessSubject, RequestActor } from "../server";
+import { aiModelAccess } from "./model-access";
+import { personalAiModelPolicy } from "./personal-agent";
+import { listAiModels, toPublicAiSettingsState } from "./settings";
+import type { AiChatTurnRunConfig, AiModelPolicy, AiSettingsError } from "./types";
+
+export const aiChatAccessSubject = (actor: RequestActor | undefined): AccessSubject | null => {
+  if (!actor) return null;
+  if (actor.kind === "user") return { type: "user", userId: actor.user.id };
+  if (actor.delegatedUser) {
+    return { type: "user", userId: actor.delegatedUser.id, delegatedByServiceAccountId: actor.serviceAccount.id };
+  }
+  return { type: "service_account", serviceAccountId: actor.serviceAccount.id };
+};
+
+/** Background chat deliveries also use default tools; only the explicit HTTP marker identifies interactive turns. */
+export const isAssistantChatTurn = (config: AiChatTurnRunConfig): boolean => config.assistantChat === true && !config.mandate;
+
+export const listAssistantAiModels = async (subject: AccessSubject | null, policy: AiModelPolicy = personalAiModelPolicy) =>
+  aiModelAccess.filterModels(await listAiModels(policy), subject);
+
+export const assistantAiSettingsState = async (subject: AccessSubject | null) => {
+  const [status, models] = await Promise.all([
+    toPublicAiSettingsState(personalAiModelPolicy.allowedDataBoundaries),
+    listAssistantAiModels(subject),
+  ]);
+  return {
+    ...status,
+    models,
+    defaultModelId: models.some((model) => model.id === status.defaultModelId) ? status.defaultModelId : (models[0]?.id ?? ""),
+  };
+};
+
+/** Explicit and project selections never silently switch models. */
+export const selectAssistantAiModelId = async (
+  subject: AccessSubject | null,
+  requestedModelId?: string,
+  policy: AiModelPolicy = personalAiModelPolicy,
+): Promise<string> => {
+  if (policy.kind === "locked") {
+    await aiModelAccess.assertAllowed(policy.modelId, subject);
+    return policy.modelId;
+  }
+  if (policy.kind === "platform-default") {
+    const status = await toPublicAiSettingsState();
+    await aiModelAccess.assertAllowed(status.defaultModelId, subject);
+    return status.defaultModelId;
+  }
+  if (requestedModelId) {
+    await aiModelAccess.assertAllowed(requestedModelId, subject);
+    return requestedModelId;
+  }
+  const [status, models] = await Promise.all([toPublicAiSettingsState(), listAssistantAiModels(subject, policy)]);
+  const preferred = policy.defaultModelId;
+  const model = models.find((candidate) => candidate.id === (preferred ?? status.defaultModelId)) ?? models[0];
+  if (!model) {
+    const message = "No AI model is available for your Assistant access. Contact an administrator.";
+    throw Object.assign(new Error(message), { aiError: { code: "model_access_denied", message } satisfies AiSettingsError });
+  }
+  return model.id;
+};

package/src/ai/attachments.ts

@@ -0,0 +1,40 @@
+/**
+ * Attachments live in the conversation file store, not inline in the
+ * model context: the composer uploads the file, then sends an attachment
+ * input part which becomes a marker text part in the user message. The model
+ * reads the path with the conversation file tools; the chat UI parses
+ * the same marker back into a chip. Browser-safe module.
+ */
+
+export type AiAttachmentRef = { path: string; mediaType: string; size: number };
+
+const MARKER_RE = /<attachment path="([^"]+)" media-type="([^"]*)" size="(\d+)" \/>/g;
+
+export const aiAttachmentMarker = (ref: AiAttachmentRef): string =>
+  `<attachment path="${ref.path}" media-type="${ref.mediaType}" size="${ref.size}" />`;
+
+/** Replace client-supplied marker metadata with canonical file-store values. */
+export const canonicalizeAiAttachmentMarkers = (text: string, refs: ReadonlyMap<string, AiAttachmentRef>): string =>
+  text.replace(MARKER_RE, (marker, path: string) => {
+    const ref = refs.get(path);
+    return ref ? aiAttachmentMarker(ref) : marker;
+  });
+
+/** Split a text part into plain text and attachment chips for rendering. */
+export const parseAiAttachmentMarkers = (text: string): { text: string; attachments: AiAttachmentRef[] } => {
+  const attachments: AiAttachmentRef[] = [];
+  const stripped = text
+    .replace(MARKER_RE, (_all, path: string, mediaType: string, size: string) => {
+      attachments.push({ path, mediaType, size: Number(size) });
+      return "";
+    })
+    .trim();
+  return { text: stripped, attachments };
+};
+
+export const formatAiFileSize = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+};

package/src/ai/browser.ts

@@ -0,0 +1,92 @@
+import { AI_TURN_ATTACHMENT_MAX_ITEMS } from "./limits";
+import type { AiConversation, AiDraftContentPart } from "./types";
+
+export { parseAiSse } from "./client/transport";
+export {
+  CLOUD_AI_TEXT_EDITOR_MAX_CHARS,
+  CloudAiCardInputSchema,
+  CloudAiLocalBashInputSchema,
+  CloudAiSurveyInputSchema,
+  CloudAiTextEditorInputSchema,
+} from "./default-tool-contracts";
+export { guessAiMediaType } from "./file-media-type";
+export { AI_IMAGE_INPUT_MAX_BYTES, AI_TURN_ATTACHMENT_MAX_ITEMS, AI_TURN_IMAGE_MAX_TOTAL_BYTES } from "./limits";
+export {
+  AI_SKILL_REFERENCE_MAX_ITEMS,
+  AI_SKILL_REFERENCES_MAX_CHARS,
+  type AiSkillDocument,
+  type AiSkillReferenceInput,
+  parseAiSkillMarkdown,
+  serializeAiSkillMarkdown,
+  validateAiSkillReferences,
+} from "./skill-format";
+export { isAiImageMediaType } from "./types";
+
+export type LaunchAssistantInput = {
+  title?: string;
+  projectId?: string;
+  /** Stable application id when another Cloud application explicitly launches this chat. */
+  launchedByAppId?: string;
+  draft?: { content: Array<Extract<AiDraftContentPart, { type: "text" | "resource" }>> };
+  files?: File[];
+  preloadTools?: Array<{ name: string } | { appId: string; kind: "query" | "action"; id: string }>;
+  /** Optional immutable ceiling of built-in names and qualified capability IDs. */
+  allowedTools?: string[];
+  /** Exact enabled Skill names, resolved into ordinary removable resource attachments. */
+  skills?: string[];
+};
+
+export type AssistantLaunch = {
+  conversation: AiConversation;
+  href: string;
+};
+
+export const launchAssistant = async (input: LaunchAssistantInput): Promise<AssistantLaunch> => {
+  const { files = [], ...createInput } = input;
+  if (files.length > AI_TURN_ATTACHMENT_MAX_ITEMS) {
+    throw new Error(`Assistant drafts can attach at most ${AI_TURN_ATTACHMENT_MAX_ITEMS} files`);
+  }
+  if ((input.draft?.content.length ?? 0) + files.length > 20) {
+    throw new Error("Assistant drafts can contain at most 20 parts");
+  }
+  const response = await fetch("/api/ai/conversations", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(createInput),
+  });
+  if (!response.ok) {
+    const body = (await response.json().catch(() => null)) as { message?: string } | null;
+    throw new Error(body?.message ?? "Assistant chat could not be created");
+  }
+  let conversation = (await response.json()) as AiConversation;
+  try {
+    if (files.length > 0) {
+      const uploaded = await Promise.all(
+        files.map(async (file) => {
+          const form = new FormData();
+          form.set("file", file);
+          const upload = await fetch(`/api/ai/conversations/${encodeURIComponent(conversation.id)}/files`, { method: "POST", body: form });
+          if (!upload.ok) throw new Error(`Could not attach ${file.name}`);
+          return (await upload.json()) as { file: Omit<Extract<AiDraftContentPart, { type: "file" }>, "type"> };
+        }),
+      );
+      const draftResponse = await fetch(`/api/ai/conversations/${encodeURIComponent(conversation.id)}/draft`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          expectedRevision: conversation.draft.revision,
+          content: [...conversation.draft.content, ...uploaded.map((item) => ({ type: "file" as const, ...item.file }))],
+        }),
+      });
+      if (!draftResponse.ok) throw new Error("Assistant draft attachments could not be saved");
+      conversation = { ...conversation, draft: (await draftResponse.json()) as AiConversation["draft"] };
+    }
+  } catch (error) {
+    await fetch(`/api/ai/conversations/${encodeURIComponent(conversation.id)}/archive`, { method: "POST" }).catch(() => undefined);
+    throw error;
+  }
+  return {
+    conversation,
+    href: `/app/assistant?conversation=${encodeURIComponent(conversation.id)}`,
+  };
+};