@k2b/cloud 0.6.0 → 0.8.0

package/src/ai/capabilities.ts

@@ -1,13 +1,7 @@
 import { createHash } from "node:crypto";
 import type { Tool, ToolContext, ToolResolver } from "@k2b/nessi";
 import { z } from "zod";
-import {
-  createHelpCatalog,
-  HELP_READ_MAX_CHARS,
-  HELP_SEARCH_MAX_LIMIT,
-  readHelpCatalog,
-  searchHelpCatalog,
-} from "../_internal/help-catalog";
+import { HELP_READ_MAX_CHARS, HELP_SEARCH_MAX_LIMIT, readHelpArticle } from "../_internal/help-catalog";
 import {
   type CapabilityActionManifest,
   type CapabilityActionReview,
@@ -16,8 +10,12 @@ import {
   cloudResourceRefAppId,
   resolveCapabilityResourceReader,
 } from "../contracts/capabilities";
-import type { CapabilityRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import type { CapabilityRegistryEntry } from "../contracts/registry";
 import type { RequestActor } from "../server";
+import { createHelpReader, type HelpReaderFactory } from "../services/help";
+import { recordRejectedAiCapability } from "./capability-execution";
+import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
+import { createCodeSourceTool } from "./code-source-tools";
 import { CLOUD_AI_DEFERRED_BUILTIN_TOOL_NAMES } from "./default-tools";
 import { type AiToolPreparationContext, defineAiTool, type PreparedAiTools, prepareAiTools } from "./tools";
 import type { AiConversationService, AiRuntimeTool, AiToolPresentation } from "./types";
@@ -304,14 +302,14 @@ const AiHelpDocumentSchema = AiHelpCatalogItemSchema.extend({
   truncated: z.boolean(),
 }).strict();
 
-/** Search and read the live Help snapshot without loading one tool per article. */
-export const createAiHelpTools = (registry: readonly HelpRegistryEntry[], locale = "en"): AiRuntimeTool[] => {
-  const documents = createHelpCatalog(registry, locale);
+/** Search and read published Help without loading one tool per article. */
+export const createAiHelpTools = (help: HelpReaderFactory = createHelpReader, locale = "en"): AiRuntimeTool[] => {
+  const reader = help(locale);
 
   const search = defineAiTool({
     name: "search_help",
     description:
-      "Search installed Cloud app Help when product behavior, settings, workflows, permissions, or app errors are unclear. Use 1-3 concise English product terms and scope appId when known. Returns compact document ids for read_help; skip this tool for straightforward live-data requests.",
+      "Search installed Cloud app Help when product behavior, settings, workflows, permissions, or app errors are unclear. Use concise product terms in the request language and scope appId when known. Returns compact document ids for read_help; skip this tool for straightforward live-data requests.",
     inputSchema: z
       .object({
         query: z.string().trim().min(1).max(200).describe("Product task or concept to find."),
@@ -322,7 +320,7 @@ export const createAiHelpTools = (registry: readonly HelpRegistryEntry[], locale
     outputSchema: z.object({ documents: z.array(AiHelpCatalogItemSchema).max(HELP_SEARCH_MAX_LIMIT) }).strict(),
     approval: "never",
   }).server(async ({ query, appId, limit }) => ({
-    documents: searchHelpCatalog(documents, { query, appId, limit: boundedLimit(limit, DEFAULT_SEARCH_LIMIT, HELP_SEARCH_MAX_LIMIT) }),
+    documents: await reader.search({ query, appId, limit: boundedLimit(limit, DEFAULT_SEARCH_LIMIT, HELP_SEARCH_MAX_LIMIT) }),
   }));
 
   const read = defineAiTool({
@@ -338,25 +336,14 @@ export const createAiHelpTools = (registry: readonly HelpRegistryEntry[], locale
       .strict(),
     outputSchema: z.object({ document: AiHelpDocumentSchema.nullable() }).strict(),
     approval: "never",
-  }).server(async ({ appId, documentId, query }) => ({
-    document: readHelpCatalog(documents, { appId, documentId, query }),
-  }));
+  }).server(async ({ appId, documentId, query }) => {
+    const document = await reader.read({ appId, documentId });
+    return { document: document ? readHelpArticle(document, query) : null };
+  });
 
   return [search, read];
 };
 
-const resolveHelpRegistry = async (
-  listRegistry: () => Promise<HelpRegistryEntry[]>,
-  onError?: (error: unknown) => void,
-): Promise<HelpRegistryEntry[]> => {
-  try {
-    return await listRegistry();
-  } catch (error) {
-    onError?.(error);
-    return [];
-  }
-};
-
 const resolveCapabilityRegistry = async (
   listRegistry: () => Promise<CapabilityRegistryEntry[]>,
   onError?: (error: unknown) => void,
@@ -554,7 +541,9 @@ export const createAiToolMetaTools = (input: {
 export const createLoadedAiCapabilityTools = (input: {
   catalog: readonly AiCapabilityCatalogEntry[];
   loadedNames: readonly string[];
+  actor: RequestActor;
   review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReview | null>;
+  authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown) => Promise<void>;
   onReview?: (callId: string, review: CapabilityActionReview) => void;
   execute: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<unknown>;
 }): AiRuntimeTool[] => {
@@ -573,12 +562,18 @@ export const createLoadedAiCapabilityTools = (input: {
         // live review has resolved. The review may supply an app-owned scope.
         approval: "never",
       }).server(async (args, context) => {
-        if (entry.kind === "action") {
+        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.appName}: ${entry.title}\nReview the validated arguments below before running this Action.`;
-          if (!(await context.requestApproval(message))) throw new Error("Capability Action was rejected by the user.");
+          if (!(await context.requestApproval(message))) {
+            if (input.actor.kind === "user") {
+              await recordRejectedAiCapability({ entry, actor: input.actor, args }).catch(() => undefined);
+            }
+            throw new Error("Capability Action was rejected by the user.");
+          }
         }
         return input.execute(entry, args, context);
       }),
@@ -599,6 +594,11 @@ export const createAiResourceReaderTool = (input: {
     outputSchema: z.unknown(),
     approval: "never",
   }).server(async (ref, context) => {
+    if (ref.type === "assistant.artifact") {
+      const tool = createCodeSourceTool("code_read");
+      if (tool.location !== "server") throw new Error("Code reader must execute on the server.");
+      return tool.run(CODE_SOURCE_TOOLS.code_read.input.parse({ id: ref.id }), context);
+    }
     const appId = cloudResourceRefAppId(ref);
     const app = input.apps.find((candidate) => candidate.appId === appId);
     const reader = app ? resolveCapabilityResourceReader(app.manifest, ref) : null;
@@ -611,6 +611,24 @@ export const createAiResourceReaderTool = (input: {
   });
 
 /** Nessi resolver: one registry/load-state snapshot drives discovery, loading, schemas, and execution per model turn. */
+/** Background discovery belongs to one run, never the interactive conversation. */
+export const createRunToolStore = (initialNames: readonly string[]): Pick<AiConversationService, "getLoadedTools" | "loadTools"> => {
+  let current = [...new Set(initialNames)];
+  return {
+    getLoadedTools: async () => [...current],
+    loadTools: async ({ names, maxLoadedTools }) => {
+      const requested = [...new Set(names.map((name) => name.trim()).filter(Boolean))];
+      const alreadyLoaded = requested.filter((name) => current.includes(name));
+      const added = requested.filter((name) => !current.includes(name));
+      const combined = [...current, ...added];
+      const limit = Math.floor(maxLoadedTools ?? 0);
+      const evicted = limit > 0 ? combined.slice(0, Math.max(0, combined.length - limit)) : [];
+      current = combined.slice(evicted.length);
+      return { loaded: added.filter((name) => current.includes(name)), alreadyLoaded, evicted };
+    },
+  };
+};
+
 export const createAiToolResolver =
   (input: {
     conversationId: string;
@@ -621,12 +639,12 @@ export const createAiToolResolver =
     store: Pick<AiConversationService, "getLoadedTools" | "loadTools">;
     listRegistry?: () => Promise<CapabilityRegistryEntry[]>;
     onCapabilityRegistryError?: (error: unknown) => void;
-    listHelpRegistry?: () => Promise<HelpRegistryEntry[]>;
-    onHelpRegistryError?: (error: unknown) => void;
+    help?: HelpReaderFactory;
     locale?: string;
     maxLoadedTools?: number;
     execute?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<unknown>;
     review?: (entry: AiCapabilityCatalogEntry, args: unknown, context: ToolContext) => Promise<CapabilityActionReview | null>;
+    authorizeBackground?: (entry: AiCapabilityCatalogEntry, args: unknown) => Promise<void>;
     onReview?: (callId: string, review: CapabilityActionReview) => void;
     onPrepared?: (snapshot: {
       prepared: PreparedAiTools;
@@ -635,10 +653,9 @@ export const createAiToolResolver =
     }) => void;
   }): ToolResolver =>
   async (): Promise<Tool[]> => {
-    const [registry, persistedLoadedNames, helpRegistry] = await Promise.all([
+    const [registry, persistedLoadedNames] = await Promise.all([
       input.listRegistry ? resolveCapabilityRegistry(input.listRegistry, input.onCapabilityRegistryError) : [],
       input.store.getLoadedTools({ conversationId: input.conversationId }),
-      input.listHelpRegistry ? resolveHelpRegistry(input.listHelpRegistry, input.onHelpRegistryError) : [],
     ]);
     const configuredLimit = Math.floor(input.maxLoadedTools ?? 0);
     const loadedNames = configuredLimit > 0 ? persistedLoadedNames.slice(-configuredLimit) : persistedLoadedNames;
@@ -651,9 +668,9 @@ export const createAiToolResolver =
     }
     const allowed = input.allowedTools == null ? null : new Set(input.allowedTools);
     const capabilityCatalog = buildAiCapabilityCatalog(registry).filter((entry) => !allowed || allowed.has(entry.name));
-    const helpTools = input.listHelpRegistry ? createAiHelpTools(helpRegistry, input.locale) : [];
+    const helpTools = input.help ? createAiHelpTools(input.help, input.locale) : [];
     const resourceTool =
-      input.execute && capabilityCatalog.length > 0
+      input.execute && (capabilityCatalog.length > 0 || input.staticTools.some((tool) => tool.def.name === "code_read"))
         ? createAiResourceReaderTool({ apps: registry, catalog: capabilityCatalog, execute: input.execute })
         : null;
     const builtIns = [...input.staticTools, ...helpTools, ...(resourceTool ? [resourceTool] : [])].filter(
@@ -679,8 +696,10 @@ export const createAiToolResolver =
         ? createLoadedAiCapabilityTools({
             catalog: capabilityCatalog,
             loadedNames,
+            actor: input.actor,
             review: input.review,
             onReview: input.onReview,
+            authorizeBackground: input.authorizeBackground,
             execute: input.execute,
           })
         : []),

package/src/ai/capability-execution.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import type { ToolContext } from "@k2b/nessi";
 import { type CapabilityDispatchDependencies, dispatchCapability } from "../api/capabilities";
+import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
 import { type CapabilityActionManifest, type CapabilityActionReview, CapabilityActionReviewSchema } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import type { AccessSubject } from "../server/services/access";
@@ -98,18 +99,24 @@ const dispatchAiCapability = async (input: AiCapabilityCall, review: boolean): P
   const headers = new Headers();
   if (input.locale) headers.set(LOCALE_HEADER, input.locale);
   const action = input.entry.kind === "action" ? (input.entry.operation as CapabilityActionManifest) : null;
-  if (!review && action?.idempotency === "required" && input.context.callId) {
-    const key = idempotencyKey(input.conversationId, input.context.callId);
-    if (input.turnId) {
-      await aiToolAudit.noteCapabilityDispatch({
-        conversationId: input.conversationId,
-        turnId: input.turnId,
-        callId: input.context.callId,
-        toolName: input.entry.name,
-        idempotencyKey: key,
-      });
-    }
-    headers.set("idempotency-key", key);
+  // One request id per dispatch links the tool call, the platform execution
+  // record, and the target app's own audit rows.
+  const requestId = crypto.randomUUID();
+  headers.set("x-request-id", requestId);
+  const key =
+    !review && action?.idempotency === "required" && input.context.callId
+      ? idempotencyKey(input.conversationId, input.context.callId)
+      : null;
+  if (key) headers.set("idempotency-key", key);
+  if (!review && input.turnId && input.context.callId) {
+    await aiToolAudit.noteCapabilityDispatch({
+      conversationId: input.conversationId,
+      turnId: input.turnId,
+      callId: input.context.callId,
+      toolName: input.entry.name,
+      requestId,
+      idempotencyKey: key,
+    });
   }
   const request = new Request("http://cloud.internal/api/ai/capability", {
     method: "POST",
@@ -120,6 +127,7 @@ const dispatchAiCapability = async (input: AiCapabilityCall, review: boolean): P
     await dispatch({
       request,
       kind: input.entry.kind === "query" ? "queries" : "actions",
+      origin: "assistant",
       review,
       appId: input.entry.appId,
       capabilityId: input.entry.operation.localId,
@@ -149,3 +157,30 @@ export const reviewAiCapability = async (input: AiCapabilityCall): Promise<Capab
 };
 
 export const executeAiCapability = (input: AiCapabilityCall): Promise<unknown> => dispatchAiCapability(input, false);
+
+/**
+ * A rejected approval never reaches the dispatcher, so the assistant records
+ * the same execution row the dispatcher would have written for the attempt.
+ */
+export const recordRejectedAiCapability = async (input: {
+  entry: Pick<AiCapabilityCatalogEntry, "appId" | "kind" | "name" | "operation">;
+  actor: CapabilityActor;
+  args: unknown;
+}): Promise<void> => {
+  const at = new Date();
+  await recordCapabilityExecution({
+    requestId: crypto.randomUUID(),
+    origin: "assistant",
+    appId: input.entry.appId,
+    capability: input.entry.name,
+    kind: input.entry.kind,
+    destructive: "destructive" in input.entry.operation ? input.entry.operation.destructive : false,
+    actorKind: "user",
+    actorId: input.actor.user.id,
+    userId: input.actor.user.id,
+    status: "rejected",
+    inputMeta: capabilityValueMeta(input.args),
+    startedAt: at,
+    completedAt: at,
+  });
+};