@cognipeer/agent-sdk 0.9.0 → 0.9.1

package/dist/index.d.cts

@@ -444,14 +444,38 @@ type ContentPart$1 = {
     type: string;
     [key: string]: any;
 };
+/**
+ * Decides, per call, whether this invocation needs human approval.
+ *
+ * Return `true` to pause. Returning a non-boolean is treated as `false` except
+ * for a thrown error, which is treated as `true` — see `needsApproval`.
+ */
+type ToolApprovalPredicate = (args: any) => boolean;
 interface ToolInterface<TInput = any, TOutput = any, TCallOptions = any> {
     name: string;
     description?: string;
     invoke?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     call?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     schema?: any;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * Whether a call must pause for a human before it runs.
+     *
+     * A boolean decides for the tool as a whole. A PREDICATE decides per call, with
+     * the parsed arguments in hand — which is the only way to express "ask before
+     * `rm`, but not before `ls`", because the interesting half of a dangerous tool
+     * is usually its arguments, not its name.
+     *
+     * The predicate runs inside the tools node, immediately before the call would
+     * execute, and it must not throw: a predicate that throws is treated as
+     * `true`, because a policy that cannot decide has not granted permission.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /**
+     * The text shown to whoever is asked. A function receives the same arguments
+     * the predicate saw, so the prompt can quote what is actually about to happen
+     * ("Delete 3 files under /src?") instead of describing the tool in general.
+     */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /**
@@ -1094,7 +1118,13 @@ type TraceToolDetails = {
     description?: string;
     inputSchema?: any;
     approval?: {
+        /** Set only when the tool answers statically. Absent when `conditional`. */
         required?: boolean;
+        /**
+         * The tool decides per call from its arguments, so no single answer can be
+         * recorded here. The actual verdict for each call is on its approval entry.
+         */
+        conditional?: boolean;
         prompt?: string;
         defaults?: any;
     };
@@ -1874,8 +1904,13 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     description?: string;
     schema: ZodSchema;
     func: SmartToolFn;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * `true` gates every call; a predicate gates the calls whose ARGUMENTS
+     * warrant it. See ToolApprovalPredicate.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /** A function form receives the call's arguments, so the prompt can quote them. */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /** When set, identical args within the same invoke short-circuit to the cached result. */

package/dist/index.d.ts

@@ -444,14 +444,38 @@ type ContentPart$1 = {
     type: string;
     [key: string]: any;
 };
+/**
+ * Decides, per call, whether this invocation needs human approval.
+ *
+ * Return `true` to pause. Returning a non-boolean is treated as `false` except
+ * for a thrown error, which is treated as `true` — see `needsApproval`.
+ */
+type ToolApprovalPredicate = (args: any) => boolean;
 interface ToolInterface<TInput = any, TOutput = any, TCallOptions = any> {
     name: string;
     description?: string;
     invoke?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     call?: (input: TInput, config?: TCallOptions) => Promise<TOutput> | TOutput;
     schema?: any;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * Whether a call must pause for a human before it runs.
+     *
+     * A boolean decides for the tool as a whole. A PREDICATE decides per call, with
+     * the parsed arguments in hand — which is the only way to express "ask before
+     * `rm`, but not before `ls`", because the interesting half of a dangerous tool
+     * is usually its arguments, not its name.
+     *
+     * The predicate runs inside the tools node, immediately before the call would
+     * execute, and it must not throw: a predicate that throws is treated as
+     * `true`, because a policy that cannot decide has not granted permission.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /**
+     * The text shown to whoever is asked. A function receives the same arguments
+     * the predicate saw, so the prompt can quote what is actually about to happen
+     * ("Delete 3 files under /src?") instead of describing the tool in general.
+     */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /**
@@ -1094,7 +1118,13 @@ type TraceToolDetails = {
     description?: string;
     inputSchema?: any;
     approval?: {
+        /** Set only when the tool answers statically. Absent when `conditional`. */
         required?: boolean;
+        /**
+         * The tool decides per call from its arguments, so no single answer can be
+         * recorded here. The actual verdict for each call is on its approval entry.
+         */
+        conditional?: boolean;
         prompt?: string;
         defaults?: any;
     };
@@ -1874,8 +1904,13 @@ declare function createTool({ name, description, schema, func, needsApproval, ap
     description?: string;
     schema: ZodSchema;
     func: SmartToolFn;
-    needsApproval?: boolean;
-    approvalPrompt?: string;
+    /**
+     * `true` gates every call; a predicate gates the calls whose ARGUMENTS
+     * warrant it. See ToolApprovalPredicate.
+     */
+    needsApproval?: boolean | ToolApprovalPredicate;
+    /** A function form receives the call's arguments, so the prompt can quote them. */
+    approvalPrompt?: string | ((args: any) => string | undefined);
     approvalDefaults?: any;
     maxExecutionsPerRun?: number | null;
     /** When set, identical args within the same invoke short-circuit to the cached result. */

package/dist/index.mjs

@@ -424,7 +424,7 @@ function createTool({
     run: execute,
     func: execute
   };
-  if (typeof needsApproval === "boolean") {
+  if (typeof needsApproval === "function" || typeof needsApproval === "boolean") {
     toolRecord.needsApproval = needsApproval;
   }
   if (approvalPrompt !== void 0) {
@@ -3473,6 +3473,29 @@ function selectPendingToolCalls(messages) {
 }
 
 // src/nodes/tools.ts
+function resolveNeedsApproval(tool, args) {
+  const spec = tool?.needsApproval;
+  if (typeof spec === "function") {
+    try {
+      return Boolean(spec(args));
+    } catch {
+      return true;
+    }
+  }
+  return Boolean(spec);
+}
+function resolveApprovalPrompt(tool, args) {
+  const prompt = tool?.approvalPrompt;
+  if (typeof prompt === "function") {
+    try {
+      const resolved = prompt(args);
+      return typeof resolved === "string" && resolved.length > 0 ? resolved : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return typeof prompt === "string" ? prompt : void 0;
+}
 function normalizeMaxExecutionsPerRun(value) {
   if (value === null || value === void 0 || value === "") return null;
   const parsed = Number(value);
@@ -3519,10 +3542,13 @@ function buildToolDetails(tool, toolName) {
   }
   const inputSchema = normalizeToolSchema(tool, toolName);
   if (inputSchema !== void 0) details.inputSchema = inputSchema;
-  const needsApproval = typeof tool.needsApproval === "boolean" ? tool.needsApproval : void 0;
-  if (needsApproval !== void 0 || tool.approvalPrompt !== void 0 || tool.approvalDefaults !== void 0) {
+  const approvalSpec = tool.needsApproval;
+  const needsApproval = typeof approvalSpec === "boolean" ? approvalSpec : void 0;
+  const conditionalApproval = typeof approvalSpec === "function" ? true : void 0;
+  if (needsApproval !== void 0 || conditionalApproval !== void 0 || tool.approvalPrompt !== void 0 || tool.approvalDefaults !== void 0) {
     details.approval = {
       required: needsApproval,
+      conditional: conditionalApproval,
       prompt: typeof tool.approvalPrompt === "string" ? tool.approvalPrompt : void 0,
       defaults: tool.approvalDefaults !== void 0 ? sanitizeTracePayload(tool.approvalDefaults) : void 0
     };
@@ -3747,7 +3773,7 @@ function createToolsNode(initialTools, opts) {
         }
       }
       let approvalEntry = pendingByCallId.get(toolCallId);
-      const needsApproval = Boolean(tool.needsApproval);
+      const needsApproval = resolveNeedsApproval(tool, args);
       if (needsApproval) {
         if (!approvalEntry) {
           approvalEntry = {
@@ -3757,7 +3783,7 @@ function createToolsNode(initialTools, opts) {
             args,
             status: "pending",
             requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            metadata: tool.approvalPrompt || tool.approvalDefaults ? { prompt: tool.approvalPrompt, defaults: tool.approvalDefaults } : void 0
+            metadata: resolveApprovalPrompt(tool, args) !== void 0 || tool.approvalDefaults !== void 0 ? { prompt: resolveApprovalPrompt(tool, args), defaults: tool.approvalDefaults } : void 0
           };
           pendingApprovals.push(approvalEntry);
           pendingByCallId.set(toolCallId, approvalEntry);