@k2b/cloud 0.29.1 → 0.31.0

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
   `;

package/src/ai/browser.ts

@@ -13,13 +13,23 @@ export { type AiTodoPlan, parseAiTodoPlan } from "./todo-contracts";
 import { AI_TURN_ATTACHMENT_MAX_ITEMS } from "./limits";
 import type { AiConversation, AiDraftContentPart } from "./types";
 
+export {
+  type CloudAiChartColumn,
+  type CloudAiChartRow,
+  type CloudAiChartTable,
+  cloudAiChartTable,
+} from "./chart-block";
 export { parseAiSse } from "./client/transport";
 export {
+  CLOUD_AI_CHART_MAX_SERIES,
+  CLOUD_AI_CHART_MAX_VALUES,
   CLOUD_AI_TEXT_EDITOR_MAX_CHARS,
   CloudAiCardInputSchema,
+  CloudAiChartInputSchema,
   CloudAiLocalBashInputSchema,
   CloudAiSurveyInputSchema,
   CloudAiTextEditorInputSchema,
+  parseCloudAiChartInput,
 } 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";

package/src/ai/capabilities.ts

@@ -1,7 +1,15 @@
 import { createHash } from "node:crypto";
 import type { Tool, ToolContext, ToolResolver } from "@k2b/nessi";
 import { z } from "zod";
-import { resolveCapabilityOperationTitle } from "../_internal/capabilities";
+import { resolveCapabilityActionWording, resolveCapabilityOperationTitle } from "../_internal/capabilities";
+import {
+  CAPABILITY_APPROVAL_REASON_FIELD,
+  CAPABILITY_APPROVAL_REASON_MAX_CHARS,
+  type CapabilityActionWording,
+  capabilityActionSubject,
+  capabilityApprovalReason,
+  capabilityApprovalText,
+} from "../_internal/capability-sentences";
 import { HELP_READ_MAX_CHARS, HELP_SEARCH_MAX_LIMIT, readHelpArticle } from "../_internal/help-catalog";
 import {
   type CapabilityActionManifest,
@@ -13,9 +21,10 @@ import {
 } from "../contracts/capabilities";
 import type { CapabilityRegistryEntry } from "../contracts/registry";
 import type { RequestActor } from "../server";
-import { createHelpReader, type HelpReaderFactory } from "../services/help";
+import type { HelpReader, HelpReaderFactory } from "../services/help";
 import { type MandatePolicyV1, mandatePolicyCanPermitCapability } from "../services/mandates/policy";
 import { resolveAppIdentityPresentation } from "../shared/app-presentation";
+import { DEFAULT_LOCALE } from "../shared/locale";
 import { recordRejectedAiCapability } from "./capability-execution";
 import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 import { createCodeSourceTool } from "./code-source-tools";
@@ -337,9 +346,7 @@ const AiHelpDocumentSchema = AiHelpCatalogItemSchema.extend({
 }).strict();
 
 /** Search and read published Help without loading one tool per article. */
-export const createAiHelpTools = (help: HelpReaderFactory = createHelpReader, locale = "en"): AiRuntimeTool[] => {
-  const reader = help(locale);
-
+export const createAiHelpTools = (reader: HelpReader): AiRuntimeTool[] => {
   const search = defineAiTool({
     name: "search_help",
     description:
@@ -453,6 +460,39 @@ export const reduceAiCapabilityInputSchema = (schema: Record<string, unknown>):
 export const aiCapabilityInputSchema = (schema: Record<string, unknown>): z.ZodType =>
   z.fromJSONSchema(reduceAiCapabilityInputSchema(schema));
 
+/** How people read calls of one loaded Action in the turn's locale; derived from the live catalog only. */
+export const aiCapabilityActionWording = (entry: AiCapabilityCatalogEntry, locale: string | undefined): CapabilityActionWording =>
+  resolveCapabilityActionWording(entry.operation as CapabilityActionManifest, entry.app.presentation, locale ?? DEFAULT_LOCALE);
+
+/**
+ * An Action that waits for approval lets the model say why it wants it. The field exists only for the model:
+ * Cloud removes it before review, authorization, and execution. An app field of the same name wins.
+ */
+const offersApprovalReason = (entry: AiCapabilityCatalogEntry): boolean => {
+  if (entry.kind !== "action" || (entry.operation as CapabilityActionManifest).approval === "none") return false;
+  const properties = entry.operation.inputSchema.properties;
+  return Boolean(properties && typeof properties === "object" && !Object.hasOwn(properties, CAPABILITY_APPROVAL_REASON_FIELD));
+};
+
+const withApprovalReason = (schema: Record<string, unknown>): Record<string, unknown> => ({
+  ...schema,
+  properties: {
+    ...(schema.properties as Record<string, unknown>),
+    [CAPABILITY_APPROVAL_REASON_FIELD]: {
+      type: "string",
+      maxLength: CAPABILITY_APPROVAL_REASON_MAX_CHARS,
+      description:
+        "Optional: one short sentence in the user's language on why this call is needed now. Shown as your reason beside the approval; never put Action input here.",
+    },
+  },
+});
+
+const withoutApprovalReason = (entry: AiCapabilityCatalogEntry, args: unknown): unknown => {
+  if (!offersApprovalReason(entry) || !args || typeof args !== "object" || Array.isArray(args)) return args;
+  const { [CAPABILITY_APPROVAL_REASON_FIELD]: _reason, ...appArgs } = args as Record<string, unknown>;
+  return appArgs;
+};
+
 const ToolCatalogItemSchema = z
   .object({
     name: z.string(),
@@ -600,6 +640,8 @@ export const createLoadedAiCapabilityTools = (input: {
   catalog: readonly AiCapabilityCatalogEntry[];
   loadedNames: readonly string[];
   actor: RequestActor;
+  /** Locale of the turn; the approval text a person reads is worded in it. */
+  locale?: string;
   review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReview | null>;
   authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown) => Promise<void>;
   onReview?: (callId: string, review: CapabilityActionReview) => void;
@@ -614,17 +656,28 @@ export const createLoadedAiCapabilityTools = (input: {
         name: entry.providerName,
         canonicalName: entry.name,
         description: `${entry.title}. ${entry.description} Never retry ACTION_OUTCOME_UNKNOWN. Do not retry unchanged after INTERNAL or INVALID_APP_RESPONSE; report the provider error.`,
-        inputSchema: aiCapabilityInputSchema(entry.operation.inputSchema),
+        inputSchema: aiCapabilityInputSchema(
+          offersApprovalReason(entry) ? withApprovalReason(entry.operation.inputSchema) : entry.operation.inputSchema,
+        ),
         outputSchema: z.unknown(),
         // Capability Actions request a custom approval after their optional
         // live review has resolved. The review may supply an app-owned scope.
         approval: "never",
-      }).server(async (args, context) => {
+      }).server(async (modelArgs, context) => {
+        const args = withoutApprovalReason(entry, modelArgs);
         await input.authorizeBackground?.(entry, args);
         if (!input.authorizeBackground && entry.kind === "action" && (entry.operation as CapabilityActionManifest).approval !== "none") {
           const review = (await input.review?.(entry, args, context)) ?? null;
           if (review && context.callId) input.onReview?.(context.callId, review);
-          const message = review?.message ?? `${entry.display.appName}: ${entry.display.title}`;
+          // Text-only readers such as the CLI read what the card shows: the app's sentence, its review, and the model's reason.
+          const locale = input.locale ?? DEFAULT_LOCALE;
+          const message = capabilityApprovalText({
+            appName: entry.display.appName,
+            subject: capabilityActionSubject(aiCapabilityActionWording(entry, locale), args, { locale, timeZone: context.timeZone }),
+            review: review?.message,
+            reason: offersApprovalReason(entry) ? capabilityApprovalReason(modelArgs) : null,
+            locale,
+          });
           if (!(await context.requestApproval(message))) {
             if (input.actor.kind === "user") {
               await recordRejectedAiCapability({ entry, actor: input.actor, args }).catch(() => undefined);
@@ -743,7 +796,8 @@ export const createAiToolResolver =
       fullCapabilityCatalog.filter((entry) => !mandateAllows(entry)).flatMap((entry) => [entry.name, entry.providerName]),
     );
     const capabilityCatalog = fullCapabilityCatalog.filter((entry) => (!allowed || allowed.has(entry.name)) && mandateAllows(entry));
-    const helpTools = input.help ? createAiHelpTools(input.help, input.locale) : [];
+    // The turn's actor decides which apps' Help exists for the model, like every other Help surface.
+    const helpTools = input.help ? createAiHelpTools(input.help(input.locale ?? "en", input.actor)) : [];
     const resourceTool =
       input.execute && (capabilityCatalog.length > 0 || input.staticTools.some((tool) => tool.def.name === "code_read"))
         ? createAiResourceReaderTool({ apps: registry, catalog: capabilityCatalog, execute: input.execute })
@@ -805,6 +859,7 @@ export const createAiToolResolver =
             catalog: capabilityCatalog,
             loadedNames,
             actor: input.actor,
+            locale: input.locale,
             review: input.review,
             onReview: input.onReview,
             authorizeBackground: input.authorizeBackground,
@@ -824,6 +879,7 @@ export const createAiToolResolver =
     for (const name of loadedNames) {
       const entry = catalogByName.get(name);
       if (!entry) continue;
+      const wording = entry.kind === "action" ? aiCapabilityActionWording(entry, input.locale) : null;
       presentations.set(entry.providerName, {
         kind: "capability",
         appId: entry.appId,
@@ -832,6 +888,9 @@ export const createAiToolResolver =
         appAccent: entry.app.appAccent,
         title: entry.display.title,
         capabilityKind: entry.kind,
+        ...(wording?.sentences ? { sentences: wording.sentences } : {}),
+        ...(wording?.fields?.length ? { fields: [...wording.fields] } : {}),
+        ...(offersApprovalReason(entry) ? { approvalReason: true as const } : {}),
       });
       // Rememberable scopes are resolved by the owning app for each concrete
       // call and attached when its live review completes.