@k2b/cloud 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -73,6 +73,7 @@
     "./ssr": "./src/ssr/index.ts",
     "./ssr/islands": "./src/ssr/islands/index.ts",
     "./ssr/WorkspaceNavigation.island": "./src/ssr/WorkspaceNavigation.island.tsx",
+    "./ssr/layout-runtime": "./src/ssr/layout-runtime.ts",
     "./ssr/*": "./src/ssr/*",
     "./config": "./src/config/index.ts",
     "./config/*": "./src/config/*",
@@ -104,7 +105,7 @@
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.17.0",
     "@k2b/ssr": "0.15.0",
-    "@k2b/ui": "0.21.0",
+    "@k2b/ui": "0.22.0",
     "@k2b/stdlib": "0.28.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/src/_internal/app-presentation.ts

@@ -1,4 +1,5 @@
-import type { AppMeta, AppPresentationCatalog, AppPresentationTranslation } from "../contracts/app";
+import type { AppMeta, AppPresentationCatalog, AppPresentationTranslation, AppWidgetTranslation } from "../contracts/app";
+import { WIDGET_DESCRIPTION_MAX_LENGTH, WIDGET_TITLE_MAX_LENGTH } from "../contracts/widgets";
 import { canonicalLocale } from "../shared/locale";
 
 export const APP_PRESENTATION_MAX_BYTES = 64 * 1024;
@@ -21,6 +22,24 @@ const labels = (values: Readonly<Record<string, string>> | undefined, allowed: S
   return normalized;
 };
 
+const widgetTexts = (
+  values: Readonly<Record<string, AppWidgetTranslation>>,
+  allowed: Set<string>,
+  label: string,
+): Record<string, AppWidgetTranslation> => {
+  const normalized: Record<string, AppWidgetTranslation> = {};
+  for (const [id, value] of Object.entries(values)) {
+    if (!allowed.has(id)) throw new Error(`${label} contains unknown key ${JSON.stringify(id)}`);
+    normalized[id] = {
+      ...(value.title !== undefined ? { title: text(value.title, `${label}.${id}.title`, WIDGET_TITLE_MAX_LENGTH) } : {}),
+      ...(value.description !== undefined
+        ? { description: text(value.description, `${label}.${id}.description`, WIDGET_DESCRIPTION_MAX_LENGTH) }
+        : {}),
+    };
+  }
+  return normalized;
+};
+
 /** Validate and canonicalize one static app-presentation catalog before it enters the registry. */
 export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCatalog | undefined): AppPresentationCatalog | undefined => {
   if (!catalog) return undefined;
@@ -36,6 +55,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
   const adminHrefs = new Set((app.adminNav ?? []).flatMap((group) => group.links.map((link) => link.href)));
   const searchHrefs = new Set((app.searchLinks ?? []).map((link) => link.href));
   const legalHrefs = new Set((app.legalLinks ?? []).map((link) => link.href));
+  const widgetIds = new Set((app.widgets ?? []).map((widget) => widget.id));
   const translations: Record<string, AppPresentationTranslation> = {};
 
   for (const [locale, translation] of Object.entries(catalog.translations)) {
@@ -62,6 +82,7 @@ export const compileAppPresentation = (app: AppMeta, catalog: AppPresentationCat
           }
         : {}),
       ...(translation.legalLinks ? { legalLinks: labels(translation.legalLinks, legalHrefs, `${canonical}.legalLinks`) } : {}),
+      ...(translation.widgets ? { widgets: widgetTexts(translation.widgets, widgetIds, `${canonical}.widgets`) } : {}),
     };
   }
 

package/src/_internal/capabilities.ts

@@ -1469,9 +1469,9 @@ export const reviewCompiledCapability = async (params: {
       return normalizeProviderError(reviewed.error, "Capability review returned an invalid error", params.onUnexpectedError);
     }
     const parsed = CapabilityActionReviewSchema.safeParse(reviewed.data);
+    // A rememberable Action may leave out its scope for arguments that should ask every time; any other Action has none.
     const approvalScopeIsValid =
-      parsed.success &&
-      (operation.manifest.approval === "rememberable" ? parsed.data.approvalScope !== undefined : parsed.data.approvalScope === undefined);
+      parsed.success && (operation.manifest.approval === "rememberable" || parsed.data.approvalScope === undefined);
     if (!parsed.success || !approvalScopeIsValid) {
       try {
         params.onUnexpectedError?.(

package/src/_internal/define-app.ts

@@ -54,6 +54,7 @@ import { matchedRouteTemplate, routeTemplate } from "../server/middleware/route-
 import { runtime as runtimeMiddleware } from "../server/middleware/runtime";
 import { preloadLayoutAnnouncements, settings as settingsMiddleware } from "../server/middleware/settings";
 import { validationErrorResponse } from "../server/middleware/validator";
+import { setWidgetRequest } from "../server/widget-request";
 import {
   capabilityInvocationOperation,
   searchInvocationOperation,
@@ -92,6 +93,7 @@ import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./r
 import { servePublicAsset } from "./static-assets";
 import { createStatusPreservingSsrHandler } from "./status-preserving-ssr";
 import { WEB_VITALS_ASSET_HREF } from "./web-vitals-asset";
+import { compileWidgetDeclarations } from "./widget-declarations";
 
 /** Cache-busting version stamp — changes on every server start / rebuild. */
 const v = Date.now();
@@ -515,7 +517,7 @@ export const defineApp = <
     legalLinks: opts.legalLinks ? [...opts.legalLinks] : undefined,
     searchLinks: opts.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
     pwa: pwaPart,
-    widgets: opts.widgets ? opts.widgets.map((w) => ({ ...w })) : undefined,
+    widgets: compileWidgetDeclarations(opts.id, opts.widgets),
     settingKeys: opts.settings ? Object.keys(opts.settings) : undefined,
     openapi: opts.openapi,
     cli: opts.cli,
@@ -614,7 +616,11 @@ export const defineApp = <
         pwa: meta.pwa
           ? { href: meta.pwa.href, requiresRoles: meta.pwa.requiresRoles ? [...meta.pwa.requiresRoles] : undefined }
           : undefined,
-        widgets: meta.widgets ? meta.widgets.map((w) => ({ ...w })) : undefined,
+        widgets: meta.widgets?.map((widget) => ({
+          ...widget,
+          sizes: widget.sizes ? [...widget.sizes] : undefined,
+          requiresRoles: widget.requiresRoles ? [...widget.requiresRoles] : undefined,
+        })),
         platformPermissions: meta.platformPermissions ? [...meta.platformPermissions] : undefined,
         settingKeys: meta.settingKeys ? [...meta.settingKeys] : undefined,
         openapi: advertiseOpenapi ? opts.openapi : undefined,
@@ -863,8 +869,12 @@ export const defineApp = <
           runtimeMiddleware(),
           settingsMiddleware(),
           async (c) => {
-            const handler = startOpts.widgets?.[c.req.param("widgetId") ?? ""];
-            return handler ? handler(c, async () => {}) : c.json({ message: "Widget not found" }, 404);
+            const widgetId = c.req.param("widgetId") ?? "";
+            const handler = startOpts.widgets?.[widgetId];
+            const declaration = meta.widgets?.find((widget) => widget.id === widgetId);
+            if (!handler || !declaration) return c.json({ message: "Widget not found" }, 404);
+            setWidgetRequest(c, declaration);
+            return handler(c, async () => {});
           },
         );
       }

package/src/_internal/registry.ts

@@ -3,7 +3,14 @@ import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
 import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
-import type { DashboardWidgetPresentation } from "../contracts/widgets";
+import { type Role, RoleSchema } from "../contracts/shared";
+import {
+  type DashboardWidgetPresentation,
+  type DashboardWidgetSize,
+  resolveWidgetSizes,
+  WIDGET_DESCRIPTION_MAX_LENGTH,
+  WIDGET_TITLE_MAX_LENGTH,
+} from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
 import { compileCapabilityPresentation, parseCapabilityManifest } from "./capabilities";
 import { lazySync } from "./process-sync";
@@ -332,7 +339,9 @@ export const listLegalLinks = async (locale?: string): Promise<Array<{ label: st
  * the dashboard app to build the widget grid and for Core to resolve the
  * exact target before proxying a widget request.
  *
- * Order = registration order across apps.
+ * Order = registration order across apps. Every optional declaration field is
+ * resolved here, so readers never see a registry record from an older app
+ * without `title`, `sizes`, or `defaultSize`, nor an unknown size or role.
  */
 export type DashboardWidget = {
   appId: string;
@@ -341,23 +350,58 @@ export type DashboardWidget = {
   widgetId: string;
   /** Fully-qualified URL — `<baseUrl>/<path>`. */
   url: string;
+  /** The declared title in the requested locale, or the app's name. */
+  title: string;
+  /** The declared description in the requested locale, or the app's description. */
+  description: string;
+  sizes: DashboardWidgetSize[];
+  defaultSize: DashboardWidgetSize;
+  suggest: boolean;
+  /** Visibility only, like `nav.requiresRoles`; empty means everyone. */
+  requiresRoles: Role[];
+  /**
+   * @deprecated The zone and width the app recommended before widgets had sizes. Only the dashboard reads it, to
+   * convert a board saved then into the board the person saw.
+   */
   presentation?: DashboardWidgetPresentation;
 };
 
-export const listWidgets = async (): Promise<DashboardWidget[]> => {
-  const apps = await listApps();
+const LEGACY_ZONES = ["focus", "overview", "context"] as const;
+const LEGACY_SPANS = ["standard", "wide"] as const;
+
+const legacyPresentation = (value: DashboardWidgetPresentation | undefined): DashboardWidgetPresentation | undefined => {
+  const defaultZone = LEGACY_ZONES.find((zone) => zone === value?.defaultZone);
+  const defaultSpan = LEGACY_SPANS.find((span) => span === value?.defaultSpan);
+  return defaultZone || defaultSpan ? { defaultZone, defaultSpan } : undefined;
+};
+
+const declaredText = (value: unknown, max: number): string | undefined =>
+  typeof value === "string" && value.trim() && value.trim().length <= max ? value.trim() : undefined;
+
+/** The widgets `apps` declare, resolved as `listWidgets()` returns them. */
+export const dashboardWidgetsOf = (apps: readonly AppRegistryEntry[], locale?: string): DashboardWidget[] => {
   const out: DashboardWidget[] = [];
-  for (const app of apps) {
+  for (const app of locale ? resolveAppPresentations(apps, locale) : apps) {
     for (const w of app.widgets ?? []) {
+      const { sizes, defaultSize } = resolveWidgetSizes(w);
       out.push({
         appId: app.id,
         appName: app.name,
         appIcon: app.icon,
         widgetId: w.id,
         url: `${app.baseUrl.replace(/\/$/, "")}${w.path.startsWith("/") ? w.path : `/${w.path}`}`,
-        presentation: w.presentation,
+        title: declaredText(w.title, WIDGET_TITLE_MAX_LENGTH) ?? app.name,
+        description: declaredText(w.description, WIDGET_DESCRIPTION_MAX_LENGTH) ?? app.description,
+        sizes,
+        defaultSize,
+        suggest: w.suggest === true,
+        requiresRoles: Array.isArray(w.requiresRoles) ? w.requiresRoles.filter((role) => RoleSchema.safeParse(role).success) : [],
+        presentation: legacyPresentation(w.presentation),
       });
     }
   }
   return out;
 };
+
+/** Every declared widget, with titles and descriptions in `locale` when given. */
+export const listWidgets = async (locale?: string): Promise<DashboardWidget[]> => dashboardWidgetsOf(await listApps(), locale);

package/src/_internal/widget-declarations.ts

@@ -0,0 +1,53 @@
+import type { WidgetEndpoint } from "../contracts/app";
+import { RoleSchema } from "../contracts/shared";
+import {
+  DASHBOARD_WIDGET_SIZES,
+  isDashboardWidgetSize,
+  WIDGET_DESCRIPTION_MAX_LENGTH,
+  WIDGET_TITLE_MAX_LENGTH,
+} from "../contracts/widgets";
+
+const text = (value: string | undefined, label: string, max: number): string | undefined => {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (!normalized || normalized.length > max) throw new Error(`${label} must contain 1 to ${max} characters`);
+  return normalized;
+};
+
+/**
+ * Validates and copies an app's widget declarations at `defineApp()`, so a typo fails at startup instead of a widget
+ * silently missing from the gallery: unique ids without `@`, which separates a widget's key from the size the
+ * dashboard asks for, bounded titles and descriptions, known sizes with the default among them, a boolean `suggest`,
+ * and known roles.
+ */
+export const compileWidgetDeclarations = (
+  appId: string,
+  widgets: ReadonlyArray<WidgetEndpoint> | undefined,
+): WidgetEndpoint[] | undefined => {
+  if (!widgets) return undefined;
+  const ids = new Set<string>();
+  return widgets.map((widget) => {
+    const label = `Widget ${JSON.stringify(widget.id)} of app ${JSON.stringify(appId)}`;
+    if (!widget.id.trim()) throw new Error(`Widgets of app ${JSON.stringify(appId)} need a non-empty id`);
+    if (widget.id.includes("@")) throw new Error(`${label} must not contain "@"`);
+    if (ids.has(widget.id)) throw new Error(`${label} is declared twice`);
+    ids.add(widget.id);
+    const sizes = widget.sizes ? [...widget.sizes] : undefined;
+    if (sizes && (sizes.length === 0 || sizes.some((size) => !isDashboardWidgetSize(size)) || new Set(sizes).size !== sizes.length)) {
+      throw new Error(`${label} must declare sizes as distinct values of ${DASHBOARD_WIDGET_SIZES.join(", ")}`);
+    }
+    if (widget.defaultSize !== undefined && !(sizes ?? ["large"]).includes(widget.defaultSize)) {
+      throw new Error(`${label} must declare a defaultSize it offers in sizes`);
+    }
+    if (widget.suggest !== undefined && typeof widget.suggest !== "boolean")
+      throw new Error(`${label} must declare suggest as true or false`);
+    if (widget.requiresRoles?.some((role) => !RoleSchema.safeParse(role).success)) throw new Error(`${label} requires an unknown role`);
+    return {
+      ...widget,
+      title: text(widget.title, `${label} title`, WIDGET_TITLE_MAX_LENGTH),
+      description: text(widget.description, `${label} description`, WIDGET_DESCRIPTION_MAX_LENGTH),
+      sizes: sizes ? DASHBOARD_WIDGET_SIZES.filter((size) => sizes.includes(size)) : undefined,
+      requiresRoles: widget.requiresRoles ? [...widget.requiresRoles] : undefined,
+    };
+  });
+};

package/src/ai/approval-routes.ts

@@ -5,8 +5,15 @@ import { listCapabilities } from "../_internal/registry";
 import { ErrorResponseSchema } from "../contracts";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
 import { type AuthContext, auth, expectUserBackedActor, getLocale, jsonResponse, rateLimit, requiresAuth, v } from "../server";
-import { type AiToolApprovalPreference, listAiToolApprovalPreferences, revokeAiToolApprovalPreference } from "./approvals";
+import {
+  AI_WEBSITE_APPROVAL_TOOL,
+  type AiToolApprovalPreference,
+  listAiToolApprovalPreferences,
+  parseAiWebsiteApprovalScope,
+  revokeAiToolApprovalPreference,
+} from "./approvals";
 import { buildAiCapabilityCatalog } from "./capabilities";
+import { aiConversations } from "./store";
 
 export type AiApprovalPreferenceView = AiToolApprovalPreference & {
   title: string;
@@ -16,6 +23,8 @@ export type AiApprovalPreferenceView = AiToolApprovalPreference & {
     icon: string;
     accent?: string;
   } | null;
+  /** For a website approval: the exact origin it lets code read, and the Studio app it is limited to, if any. */
+  website: { origin: string; resourceId: string | null } | null;
 };
 
 const AiApprovalPreferenceSchema = z.object({
@@ -24,6 +33,7 @@ const AiApprovalPreferenceSchema = z.object({
   approvalScope: z.string(),
   createdAt: z.iso.datetime(),
   lastUsedAt: z.iso.datetime().nullable(),
+  conversationId: z.uuid().nullable(),
   expiresAt: z.iso.datetime().nullable(),
   title: z.string(),
   app: z
@@ -34,20 +44,29 @@ const AiApprovalPreferenceSchema = z.object({
       accent: z.string().optional(),
     })
     .nullable(),
+  website: z.object({ origin: z.string(), resourceId: z.string().nullable() }).nullable(),
 });
 
 const AiApprovalPreferenceListSchema = z.object({ approvals: z.array(AiApprovalPreferenceSchema) });
 const AiApprovalPreferenceParamSchema = z.object({ preferenceId: z.uuid() });
+const AiApprovalPreferenceQuerySchema = z.object({ conversation: z.string().min(1).max(80).optional() });
 const AiApprovalPreferenceDeleteSchema = z.object({ deleted: z.literal(true) });
 
 type AiApprovalRouteDependencies = {
   limit?: MiddlewareHandler<AuthContext>;
   authenticate?: MiddlewareHandler<AuthContext>;
-  listPreferences?: (actorUserId: string) => Promise<AiToolApprovalPreference[]>;
+  listPreferences?: (actorUserId: string, options: { conversationId?: string }) => Promise<AiToolApprovalPreference[]>;
   revokePreference?: (actorUserId: string, preferenceId: string) => Promise<boolean>;
   listCapabilities?: () => Promise<CapabilityRegistryEntry[]>;
+  /** Resolves a chat the user owns by its ID or short ID. */
+  findConversation?: (ownerUserId: string, conversation: string) => Promise<{ id: string } | null>;
 };
 
+const findOwnConversation = async (ownerUserId: string, conversation: string) =>
+  z.uuid().safeParse(conversation).success
+    ? aiConversations.getConversation({ conversationId: conversation, ownerUserId })
+    : aiConversations.getConversationByShortId({ shortId: conversation, ownerUserId });
+
 const fallbackTitle = (toolName: string): string => {
   const label = toolName
     .replaceAll("__", " ")
@@ -61,6 +80,7 @@ export const createAiApprovalPreferenceRoutes = (dependencies: AiApprovalRouteDe
   const listPreferences = dependencies.listPreferences ?? listAiToolApprovalPreferences;
   const revokePreference = dependencies.revokePreference ?? revokeAiToolApprovalPreference;
   const registry = dependencies.listCapabilities ?? listCapabilities;
+  const findConversation = dependencies.findConversation ?? findOwnConversation;
 
   return new Hono<AuthContext>()
     .use(dependencies.limit ?? rateLimit())
@@ -70,25 +90,41 @@ export const createAiApprovalPreferenceRoutes = (dependencies: AiApprovalRouteDe
       describeRoute({
         tags: ["AI"],
         summary: "List remembered AI approvals",
-        description: "Lists AI tool approvals remembered for the current user, with titles in the request locale.",
+        description:
+          "Lists AI tool approvals remembered for the current user, with titles in the request locale. Without `conversation`, it lists the approvals that apply everywhere; with it, those limited to that chat.",
         ...requiresAuth,
         responses: {
           200: jsonResponse(AiApprovalPreferenceListSchema, "Remembered approvals"),
           401: jsonResponse(ErrorResponseSchema, "Authentication required"),
           403: jsonResponse(ErrorResponseSchema, "User-backed actor required"),
+          404: jsonResponse(ErrorResponseSchema, "Chat not found"),
         },
       }),
+      v("query", AiApprovalPreferenceQuerySchema),
       async (c) => {
         const user = expectUserBackedActor(c);
+        const requested = c.req.valid("query").conversation;
+        const conversation = requested ? await findConversation(user.id, requested) : null;
+        if (requested && !conversation) return c.json({ message: "Chat not found", code: "NOT_FOUND" }, 404);
         const [preferences, capabilities] = await Promise.all([
-          listPreferences(user.id),
+          listPreferences(user.id, conversation ? { conversationId: conversation.id } : {}),
           registry().catch(() => [] as CapabilityRegistryEntry[]),
         ]);
         const catalogByName = new Map(buildAiCapabilityCatalog(capabilities, getLocale(c)).map((entry) => [entry.name, entry]));
         const approvals: AiApprovalPreferenceView[] = preferences.map((preference) => {
+          if (preference.toolName === AI_WEBSITE_APPROVAL_TOOL) {
+            const website = parseAiWebsiteApprovalScope(preference.approvalScope);
+            return {
+              ...preference,
+              title: URL.canParse(website.origin) ? new URL(website.origin).host : website.origin,
+              app: null,
+              website,
+            };
+          }
           const capability = catalogByName.get(preference.toolName);
           return {
             ...preference,
+            website: null,
             title: capability?.display.title ?? fallbackTitle(preference.toolName),
             app: capability
               ? {

package/src/ai/approvals.ts

@@ -5,14 +5,41 @@ import type { AiToolApprovalPolicy, AiTurnRunConfig } from "./types";
 export const aiTurnAllowsRememberedApprovals = (config: AiTurnRunConfig | null | undefined): boolean =>
   config == null || config.kind === "compact" || config.mandate === undefined;
 
+/**
+ * Reserved remembered-approval name for reading one website in one chat or one managed app. No capability or tool can
+ * collide with it: tool names never contain a colon.
+ */
+export const AI_WEBSITE_APPROVAL_TOOL = "website:read";
+
+/** The remembered scope of a website approval: one exact origin, in a chat or for one managed Studio app. */
+export const aiWebsiteApprovalScope = (origin: string, resourceId?: string): string =>
+  resourceId ? `${origin} resource:${resourceId}` : origin;
+
+export const parseAiWebsiteApprovalScope = (scope: string): { origin: string; resourceId: string | null } => {
+  const [origin = scope, resource] = scope.split(" ");
+  return { origin, resourceId: resource?.startsWith("resource:") ? resource.slice("resource:".length) : null };
+};
+
+/**
+ * Website approvals apply only to a turn a person started in a signed-in browser session: never to a scheduled task,
+ * a mandate, `cld`, an API key, or another delegated credential.
+ */
+export const aiTurnAllowsWebsiteApprovals = (config: AiTurnRunConfig | null | undefined): boolean =>
+  config != null && config.kind !== "compact" && config.signedInSession === true && aiTurnAllowsRememberedApprovals(config);
+
 export type AiToolApprovalContext = {
   actorUserId: string;
 };
 
+/** Where a remembered approval applies: in one chat until it is deleted, or always. */
+export type AiToolApprovalRemember = "chat" | "always";
+
 export type AiToolApprovalPreference = {
   id: string;
   toolName: string;
   approvalScope: string;
+  /** The chat this approval is limited to; null for an approval that applies everywhere. */
+  conversationId: string | null;
   createdAt: string;
   lastUsedAt: string | null;
   expiresAt: string | null;
@@ -22,6 +49,7 @@ type AiToolApprovalPreferenceRow = {
   id: string;
   tool_name: string;
   approval_scope: string;
+  conversation_id: string | null;
   created_at: Date | string;
   last_used_at: Date | string | null;
   expires_at: Date | string | null;
@@ -37,36 +65,52 @@ export const aiToolNeedsApproval = (policy: AiToolApprovalPolicy | undefined): b
 export const aiToolAllowsAlways = (policy: AiToolApprovalPolicy | undefined): boolean =>
   policy === "always" || (typeof policy === "object" && policy.kind === "user-configurable");
 
-export const hasRememberedAiToolApproval = async (
+/**
+ * The remembered approval that covers this tool and scope: one that applies everywhere, or one limited to
+ * `conversationId`; with `chatOnly`, only the latter. Returns its ID and marks it used.
+ */
+export const findRememberedAiToolApproval = async (
   context: AiToolApprovalContext,
-  input: { toolName: string; approvalScope: string },
-): Promise<boolean> => {
+  input: { toolName: string; approvalScope: string; conversationId?: string | null; chatOnly?: boolean },
+): Promise<string | null> => {
+  const conversationId = input.conversationId ?? null;
+  if (input.chatOnly && !conversationId) return null;
   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 (conversation_id = ${conversationId}::uuid OR (conversation_id IS NULL AND NOT ${input.chatOnly === true}))
       AND (expires_at IS NULL OR expires_at > now())
+    ORDER BY conversation_id NULLS LAST
     LIMIT 1
   `;
 
   const id = rows[0]?.id;
-  if (!id) return false;
+  if (!id) return null;
   await sql`UPDATE ai.tool_approval_preferences SET last_used_at = now() WHERE id = ${id}`;
-  return true;
+  return id;
 };
 
+export const hasRememberedAiToolApproval = async (
+  context: AiToolApprovalContext,
+  input: { toolName: string; approvalScope: string; conversationId?: string | null },
+): Promise<boolean> => (await findRememberedAiToolApproval(context, input)) !== null;
+
+/** Remembers an approval everywhere, or in one chat when `conversationId` is set; a chat approval ends with its chat. */
 export const rememberAiToolApproval = async (
   context: AiToolApprovalContext,
-  input: { toolName: string; approvalScope: string; expiresAt?: Date | null },
+  input: { toolName: string; approvalScope: string; conversationId?: string | null; expiresAt?: Date | null },
 ): Promise<void> => {
+  const conversationId = input.conversationId ?? null;
   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}
+        AND conversation_id IS NOT DISTINCT FROM ${conversationId}::uuid
     `;
 
     await sql`
@@ -74,6 +118,7 @@ export const rememberAiToolApproval = async (
         actor_user_id,
         tool_name,
         approval_scope,
+        conversation_id,
         last_used_at,
         expires_at
       )
@@ -81,6 +126,7 @@ export const rememberAiToolApproval = async (
         ${context.actorUserId},
         ${input.toolName},
         ${input.approvalScope},
+        ${conversationId}::uuid,
         now(),
         ${input.expiresAt ?? null}
       )
@@ -88,16 +134,20 @@ export const rememberAiToolApproval = async (
   });
 };
 
+/** Forgets the approval with exactly this reach: everywhere, or in the one chat `conversationId` names. */
 export const forgetAiToolApproval = async (
   context: AiToolApprovalContext,
-  input: { toolName: string; approvalScope: string },
-): Promise<void> => {
-  await sql`
+  input: { toolName: string; approvalScope: string; conversationId?: string | null },
+): Promise<boolean> => {
+  const rows = await sql<{ id: string }[]>`
     DELETE FROM ai.tool_approval_preferences
     WHERE actor_user_id = ${context.actorUserId}
       AND tool_name = ${input.toolName}
       AND approval_scope = ${input.approvalScope}
+      AND conversation_id IS NOT DISTINCT FROM ${input.conversationId ?? null}::uuid
+    RETURNING id
   `;
+  return rows.length > 0;
 };
 
 const toIsoString = (value: Date | string): string => (value instanceof Date ? value : new Date(value)).toISOString();
@@ -106,22 +156,30 @@ const approvalPreferenceFromRow = (row: AiToolApprovalPreferenceRow): AiToolAppr
   id: row.id,
   toolName: row.tool_name,
   approvalScope: row.approval_scope,
+  conversationId: row.conversation_id,
   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[]> => {
+/** Lists the approvals that apply everywhere, or only those of one chat when `conversationId` is set. */
+export const listAiToolApprovalPreferences = async (
+  actorUserId: string,
+  options: { conversationId?: string } = {},
+): Promise<AiToolApprovalPreference[]> => {
+  const conversationId = options.conversationId ?? null;
   const rows = await sql<AiToolApprovalPreferenceRow[]>`
     SELECT
       id,
       tool_name,
       approval_scope,
+      conversation_id,
       created_at,
       last_used_at,
       expires_at
     FROM ai.tool_approval_preferences
     WHERE actor_user_id = ${actorUserId}
+      AND conversation_id IS NOT DISTINCT FROM ${conversationId}::uuid
       AND (expires_at IS NULL OR expires_at > now())
     ORDER BY last_used_at DESC NULLS LAST, created_at DESC, id
   `;