@k2b/cloud 0.30.0 → 0.32.0

package/src/ai/timeline.ts

@@ -125,7 +125,9 @@ export const buildAiMessageTimeline = (messages: AiStoredMessage[]): AiMessageTi
 
     const blocks = [
       ...steerBlocks,
-      ...buildBlocksFromMessages(entries.map((stored) => ({ seq: stored.seq, message: stored.message, meta: stored.meta }))),
+      ...buildBlocksFromMessages(
+        entries.map((stored) => ({ seq: stored.seq, message: stored.message, meta: stored.meta, createdAt: stored.createdAt })),
+      ),
     ];
     items.push({
       type: "assistant",

package/src/ai/tool-audit.ts

@@ -1,4 +1,5 @@
 import { sql } from "bun";
+import type { ApprovalDecisionChannel } from "../services/approvals";
 
 /**
  * AI-specific tool-call state only: approval, turn linkage, and the request id
@@ -8,7 +9,14 @@ import { sql } from "bun";
  */
 export type AiToolCallLocation = "server" | "client" | "client_view" | "client_interaction";
 
-export type AiToolApprovalState = "not_required" | "waiting" | "approved_once" | "approved_always" | "approved_by_preference" | "rejected";
+export type AiToolApprovalState =
+  | "not_required"
+  | "waiting"
+  | "approved_once"
+  | "approved_for_chat"
+  | "approved_always"
+  | "approved_by_preference"
+  | "rejected";
 
 export const aiToolAudit = {
   /** Resolve the current server-recorded invocation, never a model-supplied chat id. */
@@ -140,12 +148,14 @@ export const aiToolAudit = {
     turnId: string;
     callId: string;
     approvalState: Exclude<AiToolApprovalState, "not_required" | "waiting">;
+    decidedVia?: ApprovalDecisionChannel;
   }): Promise<void> => {
     const approved = input.approvalState !== "rejected";
     await sql`
       UPDATE ai.tool_calls
       SET
         approval_state = ${input.approvalState},
+        approval_decided_via = ${input.decidedVia ?? null},
         status = CASE WHEN ${approved} THEN status ELSE 'rejected' END,
         approved_at = CASE WHEN ${approved} THEN now() ELSE approved_at END,
         rejected_at = CASE WHEN ${approved} THEN rejected_at ELSE now() END

package/src/ai/tools.ts

@@ -4,6 +4,7 @@ import type { z } from "zod";
 import type { RequestActor } from "../server";
 import { aiToolNeedsApproval } from "./approvals";
 import type {
+  AiApprovalTarget,
   AiDataBoundary,
   AiFrontendToolMode,
   AiProjectFileToolSource,
@@ -13,6 +14,7 @@ import type {
   AiToolApprovalPolicy,
   AiToolDefinition,
   AiToolRuntime,
+  AiWebsiteReceipt,
 } from "./types";
 
 export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType>(config: {
@@ -52,6 +54,7 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           conversationId?: string;
           turnId?: string;
           attachedFilePaths?: ReadonlySet<string>;
+          localToolsEnabled?: boolean;
           allowedDataBoundaries?: AiDataBoundary[];
           projectFiles?: AiProjectFileToolSource;
           skillFiles?: AiSkillFileToolSource;
@@ -60,6 +63,12 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ) => Promise<z.infer<TOutput>>,
     ): AiToolRuntime<TInput, TOutput> {
@@ -99,6 +108,7 @@ export type AiToolPreparationContext = {
   conversationId?: string;
   turnId?: string;
   attachedFilePaths?: ReadonlySet<string>;
+  localToolsEnabled?: boolean;
   allowedDataBoundaries?: AiDataBoundary[];
   projectFiles?: AiProjectFileToolSource;
   skillFiles?: AiSkillFileToolSource;
@@ -106,15 +116,93 @@ export type AiToolPreparationContext = {
   locale?: string;
   timeZone?: string;
   reportToolProgress?: (callId: string, message: string) => Promise<void>;
+  /** Uses the approved snapshot immediately before the tool executes its effect. */
+  consumeApproval?: (approvalCallId: string, input: unknown) => Promise<AiApprovalUse>;
+  /** Links a relayed decision to the record the effect owner will consume. */
+  linkApproval?: (approvalCallId: string, approvalId: string) => void;
+  /** Hears what a nested approval asks for before the approval is requested. */
+  describeApproval?: (approvalCallId: string, target: AiApprovalTarget) => void;
+  reportWebsiteReceipts?: (callId: string, receipts: AiWebsiteReceipt[]) => Promise<void>;
 };
 
+/**
+ * What using an approval found: `approved` lets the effect run, `changed` means the approved snapshot no longer
+ * matches and asks again, and `used` means an earlier run of the call already used it, so the call must not run again.
+ */
+export type AiApprovalUse = "approved" | "changed" | "used";
+
+const approvalCallIdPattern = /^(.*)-approval-(\d+)$/;
+
+/**
+ * Whether `askedCallIds` holds a question of the same tool call that Nessi asked after `approvalCallId`, the call's
+ * own approval or one of its numbered questions. A turn that continues after such a question runs the tool from its
+ * start again, so the approvals before it are used again by the same call.
+ */
+export const aiApprovalAskedLater = (approvalCallId: string, askedCallIds: Iterable<string>): boolean => {
+  const own = approvalCallIdPattern.exec(approvalCallId);
+  const callId = own ? own[1] : approvalCallId,
+    index = own ? Number(own[2]) : -1;
+  for (const asked of askedCallIds) {
+    const later = approvalCallIdPattern.exec(asked);
+    if (later && later[1] === callId && Number(later[2]) > index) return true;
+  }
+  return false;
+};
+
+const approvalUsedError = () =>
+  new Error("This approval was already used, so Cloud does not run the call again. Check its outcome before you call again.");
+
 export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRuntimeTool[] }): PreparedAiTools => {
   const canonicalNames = new Map<string, string>();
   const approvalPolicies = new Map<string, AiToolApprovalPolicy>();
   const frontendModes = new Map<string, AiFrontendToolMode>();
 
+  const approvalContext = async (toolInput: unknown, ctx: ToolContext, needsApproval: boolean) => {
+    const callId = ctx.callId;
+    const use = (approvalCallId: string): Promise<AiApprovalUse> =>
+      input.consumeApproval ? input.consumeApproval(approvalCallId, toolInput) : Promise.resolve("approved");
+    if (needsApproval && input.consumeApproval) {
+      const used = callId ? await use(callId) : "changed";
+      if (used === "used") throw approvalUsedError();
+      if (used === "changed") throw new Error("This approval no longer matches the call. Ask again.");
+    }
+    // Nessi numbers the approvals of one execution in request order; count them to name each one's call ID.
+    let approvals = 0;
+    const requestApproval = async (message: string, target?: AiApprovalTarget): Promise<boolean> => {
+      while (true) {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (target) input.describeApproval?.(approvalCallId, target);
+        if (!(await ctx.requestApproval(message))) return false;
+        const used = await use(approvalCallId);
+        if (used === "approved") return true;
+        if (used === "used") throw approvalUsedError();
+        // A changed snapshot requires a new human decision under the next Nessi action ID.
+      }
+    };
+    return {
+      ...ctx,
+      requestApproval,
+      requestApprovalFor: (message: string, target: AiApprovalTarget) => requestApproval(message, target),
+      requestRelayedApproval: async (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (options.approvalId) input.linkApproval?.(approvalCallId, options.approvalId);
+        if (options.target) input.describeApproval?.(approvalCallId, options.target);
+        if (!(await ctx.requestApproval(message))) return false;
+        // The effect's own record is used where it runs. Without one, as for a website request from code, the relay
+        // that hands over the decision uses the chat's record; a decision it cannot use is not handed over as approval.
+        return options.approvalId !== undefined || (await use(approvalCallId)) === "approved";
+      },
+    };
+  };
+
   const tools = (input.tools ?? []).map((tool): Tool => {
-    if (!isCloudAiTool(tool)) return tool;
+    if (!isCloudAiTool(tool)) {
+      if (tool.kind !== "server") return tool;
+      return {
+        ...tool,
+        execute: async (toolInput, ctx) => tool.execute(toolInput, await approvalContext(toolInput, ctx, tool.def.needsApproval === true)),
+      };
+    }
 
     canonicalNames.set(tool.def.name, tool.def.canonicalName ?? tool.def.name);
     approvalPolicies.set(tool.def.name, tool.def.approval);
@@ -130,16 +218,17 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
     });
 
     if (tool.location === "server") {
-      return nessiTool.server((toolInput, ctx) => {
+      return nessiTool.server(async (toolInput, ctx) => {
         if (!input.actor) throw new Error(`AI server tool "${tool.def.name}" requires a request actor.`);
         const report = input.reportToolProgress;
         const callId = ctx.callId;
         return tool.run(toolInput, {
-          ...ctx,
+          ...(await approvalContext(toolInput, ctx, aiToolNeedsApproval(tool.def.approval))),
           actor: input.actor,
           conversationId: input.conversationId,
           turnId: input.turnId,
           attachedFilePaths: input.attachedFilePaths,
+          localToolsEnabled: input.localToolsEnabled,
           allowedDataBoundaries: input.allowedDataBoundaries,
           projectFiles: input.projectFiles,
           skillFiles: input.skillFiles,
@@ -147,6 +236,8 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
           locale: input.locale,
           timeZone: input.timeZone,
           reportProgress: callId && report ? (message) => report(callId, message) : undefined,
+          reportWebsiteReceipts:
+            callId && input.reportWebsiteReceipts ? (receipts) => input.reportWebsiteReceipts!(callId, receipts) : undefined,
         });
       });
     }

package/src/ai/types.ts

@@ -15,6 +15,7 @@ import type { z } from "zod";
 import type { CapabilitySentenceField } from "../_internal/capability-sentences";
 import type { CapabilityActionReview, CapabilityActionSentences, CloudResourceRef } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
+import type { AiLocalClient, AiLocalContext, AiLocalToolName } from "./local-tool-contracts";
 import type { AiTurnBlock } from "./protocol";
 
 export const AI_MODEL_CAPABILITIES = ["streaming", "tools", "vision", "transcription"] as const;
@@ -84,6 +85,7 @@ export type AiSettingsState =
       defaultModelId: string;
       visionModelId?: string;
       globalInstructions: string;
+      localClientInstructions: string;
       compactionInstructions: string;
       maxToolResultChars: number;
       firecrawlConfigured: boolean;
@@ -95,6 +97,7 @@ export type AiSettingsState =
       defaultModelId: string;
       visionModelId?: string;
       globalInstructions: string;
+      localClientInstructions: string;
       compactionInstructions: string;
       maxToolResultChars: number;
       firecrawlConfigured: boolean;
@@ -303,6 +306,8 @@ export type AiStoredMessage = {
     toolPresentations?: Record<string, AiToolPresentation>;
     /** How the person decided an approval; `expired` when the turn ended while it still waited. */
     toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
+    /** Requests a website approval let through, by tool call and then by `AiWebsiteReceipt.index`. */
+    websiteReceipts?: Record<string, Record<string, { method: string; url: string }>>;
     /** Why the turn failed, on the last message of its loop. The chat words it in the reader's language. */
     turnError?: AiTurnError;
   } | null;
@@ -420,6 +425,10 @@ export type AiPendingTurnAction =
       message?: string;
       review?: CapabilityActionReview;
       allowAlways: boolean;
+      /** Whether the approval can be remembered for this chat. */
+      allowChat: boolean;
+      /** The website origin a chat approval would allow, for an HTTP request a code run makes. */
+      website?: string;
     }
   | {
       type: "frontend_tool";
@@ -441,6 +450,7 @@ export type AiTurnAbortRequest =
     };
 
 export type AiPendingTurnActionRecord = {
+  approvalId?: string;
   turnId: string;
   conversationId: string;
   callId: string;
@@ -452,6 +462,10 @@ export type AiPendingTurnActionRecord = {
   review?: CapabilityActionReview;
   approvalScope: string;
   allowAlways: boolean;
+  /** Whether the approval can be remembered for this chat; defaults to `allowAlways`. */
+  allowChat?: boolean;
+  /** Remembered-approval name when it differs from `name`: the website or Action a code run asks for. */
+  rememberToolName?: string;
   frontendMode?: AiFrontendToolMode;
   resolvedEvent: InboundEvent | null;
 };
@@ -460,6 +474,7 @@ export type AiTurnToolSource = { kind: "none" } | { kind: "default"; appTools?:
 
 export type AiClientToolId =
   | "local_bash"
+  | AiLocalToolName
   | "code_run"
   | "code_action"
   | "code_inspect"
@@ -607,6 +622,11 @@ export type AiChatTurnRunConfig = {
   selectedSkillIds?: string[];
   /** Server-owned marker: model grants apply only to interactive Assistant chat. */
   assistantChat?: true;
+  /**
+   * Server-owned marker: a person started this turn in a signed-in browser session, not through `cld`, an API key,
+   * a delegated account, or a schedule. Only such a turn uses website approvals.
+   */
+  signedInSession?: true;
   kind?: "chat";
   input: Input;
   /** Stable public ID exposed as runtime context, not instructions. */
@@ -626,6 +646,8 @@ export type AiChatTurnRunConfig = {
   /** Whether this turn's materialized tools can inspect referenced images. */
   canInspectAttachedImages?: boolean;
   clientToolIds?: AiClientToolId[];
+  client?: AiLocalClient;
+  localContext?: AiLocalContext;
   toolSource?: AiTurnToolSource;
   toolApprovalContext?: {
     actorUserId: string;
@@ -971,6 +993,7 @@ export type AiConversationService = {
   savePendingTurnAction(input: AiPendingTurnActionRecord): Promise<void>;
   listPendingTurnActions(input: { conversationId: string; turnId: string }): Promise<AiPendingTurnAction[]>;
   getPendingTurnAction(input: { conversationId: string; turnId: string; callId: string }): Promise<AiPendingTurnActionRecord | null>;
+  findPendingTurnActionByApproval(input: { approvalId: string; ownerUserId: string }): Promise<AiPendingTurnActionRecord | null>;
   listPendingActionRecords(input: { conversationId: string; turnId: string }): Promise<AiPendingTurnActionRecord[]>;
   listResolvedPendingActions(input: { conversationId: string; turnId: string }): Promise<AiPendingTurnActionRecord[]>;
   resolvePendingTurnAction(input: {
@@ -979,6 +1002,7 @@ export type AiConversationService = {
     callId: string;
     event: InboundEvent;
   }): Promise<AiPendingTurnActionRecord | null>;
+  markPendingTurnActionConsumedInline(input: { conversationId: string; turnId: string; callId: string }): Promise<void>;
   clearPendingTurnActions(input: { conversationId: string; turnId: string }): Promise<void>;
   enqueueTurnSteer(input: {
     conversationId: string;
@@ -1016,6 +1040,23 @@ export type AiAccessResult<TAccess = unknown> = {
 
 export type AiToolApprovalPolicy = "never" | "once" | "always" | { kind: "user-configurable"; default: "once" | "always"; scope?: string };
 
+/**
+ * What a server tool asks a person to approve when the approval can be remembered: a website or an Action, not the
+ * tool itself. A target can always be remembered for its chat.
+ */
+export type AiApprovalTarget = {
+  toolName: string;
+  approvalScope: string;
+  /** Whether the person may also remember it everywhere. */
+  always: boolean;
+};
+
+/**
+ * A request a remembered website approval let through without asking. The chat shows it with its full URL and a revoke
+ * action; `index` orders the receipts of one tool call, and a receipt reported again with the same index replaces it.
+ */
+export type AiWebsiteReceipt = { index: number; method: string; url: string };
+
 export type AiFrontendToolMode = "client" | "client_view" | "client_interaction";
 
 export type AiCapabilityToolPresentation = {
@@ -1063,6 +1104,7 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           conversationId?: string;
           turnId?: string;
           attachedFilePaths?: ReadonlySet<string>;
+          localToolsEnabled?: boolean;
           allowedDataBoundaries?: AiDataBoundary[];
           projectFiles?: AiProjectFileToolSource;
           skillFiles?: AiSkillFileToolSource;
@@ -1071,6 +1113,12 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ): Promise<z.infer<TOutput>>;
     }