@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/ai/browser-code-contracts.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+export const CodeResourceId = z.string().regex(/^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz]{6}$/).describe("Public resource short ID returned by code_create or code_list.");
+const id = CodeResourceId;
+const runId = z.string().min(1).max(180).describe("Run ID returned by code_run in this conversation execution host.");
+export const CODE_RUNTIME_TOOL_NAMES = ["code_run", "code_action", "code_inspect", "code_interact", "code_stop", "code_open", "code_export", "code_present", "code_secret"] as const;
+export const CodeRunInput = z.object({
+  id: id.optional(),
+  resourceId: id.optional().describe("Optional data context for one-off code. Requires Manage; uses this resource database and shared files/KV without changing its source. Local storage stays temporary."),
+  version: z.number().int().positive().optional().describe("Published version to run; resource admins only. Omit for the current accessible source."),
+  code: z.string().min(1).max(1024 * 1024).optional().describe("One-off JavaScript/TypeScript entry exporting one function. Use code OR a saved resource id; no title or icon needed."),
+  inputPaths: z.array(z.string().min(1).max(500)).max(64).default([]).describe("Explicit current-chat input files. Scripts can read them; app test runs expose them only through the simulated picker. User apps never receive chat files."),
+}).strict().refine(input => Number(input.id !== undefined) + Number(input.code !== undefined) === 1, "Provide exactly one of id or code").refine(input => input.version === undefined || input.id !== undefined,"A published version requires a saved resource id").refine(input => input.resourceId === undefined || input.code !== undefined, "resourceId requires one-off code");
+export const CodeActionInput = z.object({
+  id,
+  action: z.string().regex(/^[a-z][a-zA-Z0-9_]*$/).max(80).describe("Exact name returned by code_actions."),
+  publishedVersion: z.number().int().positive().optional().describe("Exact publication returned by code_actions; a changed publication requires fresh discovery. Supply this OR draft revision."),
+  revision: z.number().int().positive().optional().describe("Exact draft revision returned by code_actions({draft:true}); Manage required. Supply this OR publishedVersion."),
+  input: z.json().describe("Action input matching the discovered inputSchema."),
+}).strict().refine(input => Number(input.publishedVersion !== undefined) + Number(input.revision !== undefined) === 1, "Supply publishedVersion OR draft revision");
+export const CodeInspectInput = z.object({ runId, waitMs: z.number().int().min(0).max(30000).default(0).describe("Wait up to this duration for background work to finish before returning its real state; never restarts work."), nodeId: z.string().min(1).max(80).optional(), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(100).default(20) }).strict();
+const CodeInteraction = z.object({
+  id: z.string().min(1).max(80).describe("Control ID or pending modal ID returned by the snapshot."),
+  event: z.discriminatedUnion("type", [
+    z.object({ type: z.literal("change"), value: z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(z.string()), z.object({ start: z.iso.date().nullable(), end: z.iso.date().nullable() }).strict()]) }).strict(),
+    z.object({ type: z.literal("select"), key: z.string().nullable() }).strict(),
+    z.object({ type: z.literal("view"), value: z.enum(["chart", "table"]) }).strict(),
+    z.object({ type: z.literal("refresh") }).strict(),
+    z.object({ type: z.literal("request"), request: z.record(z.string(), z.json()) }).strict(),
+  ]).optional().describe("An event object, never a JSON-encoded string. Omit to activate a button. Example: {type:'change',value:['Sued']} or {type:'view',value:'table'}."),
+  answer: z.json().optional().describe("Only for the pending modal ID: the modal answer, or null to cancel. Do not use for controls."),
+}).strict();
+const validInteraction = (input: z.infer<typeof CodeInteraction>) => input.event === undefined || input.answer === undefined;
+export const CodeInteractInput = CodeInteraction.partial({id:true}).extend({
+  runId,
+  // Three normal 15-second callback budgets share the existing 45-second call budget.
+  steps:z.array(CodeInteraction.refine(validInteraction,"Supply event OR answer")).min(1).max(3).optional()
+    .describe("Up to three sequential interactions in one call. Use steps OR the top-level id/event/answer. Stops on an error, pending modal or background work; returns completedSteps and nextStep."),
+}).strict().refine(input=>input.steps ? input.id===undefined && input.event===undefined && input.answer===undefined : input.id!==undefined && (input.event===undefined || input.answer===undefined),"Supply steps OR one id with event/answer.");
+export const CodeStopInput = z.object({ runId }).strict();
+export const CodeOpenInput = z.object({ id }).strict();
+export const CodePresentInput = z.object({ runId, title: z.string().trim().min(1).max(120) }).strict();
+export const CodeExportInput = z.object({ runId, name: z.string().min(1).max(180).describe("Captured output filename returned by the snapshot.") }).strict();
+
+export const CodeSecretInput = z.object({
+  resourceId:id.optional().describe("Scope to this app/script; omit to configure the current chat only."),
+  name:z.string().regex(/^[a-zA-Z][a-zA-Z0-9_-]{0,79}$/),
+  origin:z.string().url().max(2000).describe("Exact HTTPS origin allowed to receive the secret."),
+  header:z.string().min(1).max(80).default("authorization"),
+  prefix:z.string().max(160).default("Bearer "),
+}).strict();
+
+// Internal bridge envelope. Each model-facing tool receives only its own flat schema.
+export const CodeRuntimeInput = z.discriminatedUnion("operation", [
+  CodeRunInput.safeExtend({ operation: z.literal("run") }),
+  CodeActionInput.safeExtend({ operation: z.literal("action") }),
+  CodeInspectInput.extend({ operation: z.literal("inspect") }),
+  CodeInteractInput.safeExtend({ operation: z.literal("interact") }),
+  CodeStopInput.extend({ operation: z.literal("stop") }),
+  CodeOpenInput.extend({ operation: z.literal("open") }),
+  CodeSecretInput.extend({ operation: z.literal("secret") }),
+  CodePresentInput.extend({ operation: z.literal("present") }),
+  CodeExportInput.extend({ operation: z.literal("export") }),
+]);
+export type CodeRuntimeInput = z.infer<typeof CodeRuntimeInput>;
+export function parseCodeToolInput(name: string, args: unknown): CodeRuntimeInput {
+  switch (name) {
+    case "code_secret": return { operation: "secret", ...CodeSecretInput.parse(args) };
+    case "code_action": return { operation: "action", ...CodeActionInput.parse(args) };
+    case "code_run": return { operation: "run", ...CodeRunInput.parse(args) };
+    case "code_inspect": return { operation: "inspect", ...CodeInspectInput.parse(args) };
+    case "code_interact": return { operation: "interact", ...CodeInteractInput.parse(args) };
+    case "code_stop": return { operation: "stop", ...CodeStopInput.parse(args) };
+    case "code_open": return { operation: "open", ...CodeOpenInput.parse(args) };
+    case "code_present": return { operation: "present", ...CodePresentInput.parse(args) };
+    case "code_export": return { operation: "export", ...CodeExportInput.parse(args) };
+    default: throw new Error("Unknown code tool");
+  }
+}

package/src/ai/browser.ts

@@ -1,3 +1,5 @@
+export { parseAiTodoPlan, type AiTodoPlan } from "./todo-contracts";
+export { CodeResourceId, CodeActionInput, CODE_RUNTIME_TOOL_NAMES, CodeRuntimeInput, parseCodeToolInput } from "./browser-code-contracts";
 import { AI_TURN_ATTACHMENT_MAX_ITEMS } from "./limits";
 import type { AiConversation, AiDraftContentPart } from "./types";
 

package/src/ai/capabilities.ts

@@ -1,13 +1,10 @@
+import { createHelpReader, type HelpReaderFactory } from "../services/help";
+import { createCodeSourceTool } from "./code-source-tools";
+import { CODE_SOURCE_TOOLS } from "./code-source-contracts";
 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 +13,9 @@ 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 { recordRejectedAiCapability } from "./capability-execution";
 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,
+  });
+};