@theokit/agents 4.30.2 → 5.0.0

package/dist/{chunk-GGB5WXHS.js → chunk-JXR45RAW.js}

@@ -455,6 +455,59 @@ function generateAgentRoutes(ctx) {
 }
 __name(generateAgentRoutes, "generateAgentRoutes");
 
+// src/bridge/tool-hooks-plugin.ts
+function createToolHooksPlugin(hooks) {
+  return {
+    name: "theokit-tool-hooks",
+    version: "1.0.0",
+    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
+    // no hook fires (M10/M19 latent bug, proven via a real OpenRouter run).
+    kind: "general",
+    register(ctx) {
+      const { beforeToolCall, afterToolCall, beforeLLMCall, afterLLMCall, processInput } = hooks;
+      if (beforeToolCall) {
+        ctx.on("pre_tool_call", (c) => beforeToolCall({
+          name: c.name ?? "",
+          args: c.args ?? {}
+        }));
+      }
+      if (afterToolCall) {
+        ctx.on("post_tool_call", (c) => afterToolCall({
+          name: c.name ?? "",
+          result: c.result
+        }));
+      }
+      if (beforeLLMCall) {
+        ctx.on("pre_llm_call", (c) => beforeLLMCall({
+          agentId: c.agentId,
+          runId: c.runId,
+          iteration: c.iteration
+        }));
+      }
+      if (afterLLMCall) {
+        ctx.on("post_llm_call", (c) => afterLLMCall({
+          agentId: c.agentId,
+          runId: c.runId,
+          iteration: c.iteration
+        }));
+      }
+      if (processInput) {
+        ctx.on("pre_user_send", async (c) => {
+          const injected = await processInput({
+            prompt: c.prompt ?? "",
+            agentId: c.agentId,
+            runId: c.runId
+          });
+          return injected !== void 0 && injected.length > 0 ? {
+            recalledContext: injected
+          } : void 0;
+        });
+      }
+    }
+  };
+}
+__name(createToolHooksPlugin, "createToolHooksPlugin");
+
 // src/bridge/event-translator.ts
 function asString(value, fallback) {
   if (typeof value === "string") return value;
@@ -766,6 +819,116 @@ function debugLog(marker, data) {
 }
 __name(debugLog, "debugLog");
 
+// src/bridge/hitl-plugin.ts
+function createHitlPlugin(wiring) {
+  return {
+    name: "theokit-hitl",
+    version: "1.0.0",
+    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
+    // the HITL veto never fires (the run would proceed WITHOUT waiting for human approval).
+    kind: "general",
+    register(ctx) {
+      ctx.on("pre_tool_call", async (c) => {
+        const opts = wiring.gated.get(c.name);
+        if (!opts) return void 0;
+        const approvalId = crypto.randomUUID();
+        wiring.emit({
+          type: "approval_required",
+          callId: approvalId,
+          toolName: c.name,
+          question: opts.question,
+          input: c.args,
+          callbackUrl: `approve/${approvalId}`,
+          timeoutMs: opts.timeout ?? 3e5,
+          // M20 — carry the declared custom-payload schema so the UI knows what to collect.
+          ...opts.payloadSchema !== void 0 ? {
+            payloadSchema: opts.payloadSchema
+          } : {}
+        });
+        const raw = await wiring.awaitApproval(approvalId, opts, c.name);
+        const decision = typeof raw === "boolean" ? {
+          approved: raw
+        } : raw;
+        if (decision.approved) return void 0;
+        let message = `Tool '${c.name}' denied by human approver`;
+        if (decision.reason) message += `: ${decision.reason}`;
+        if (decision.payload !== void 0) {
+          message += ` (payload: ${JSON.stringify(decision.payload)})`;
+        }
+        return {
+          block: true,
+          message
+        };
+      });
+    }
+  };
+}
+__name(createHitlPlugin, "createHitlPlugin");
+
+// src/bridge/approval-posture.ts
+function razaoDe(postura) {
+  return postura.kind === "interactive" ? "human approver on this surface" : postura.reason;
+}
+__name(razaoDe, "razaoDe");
+function aplicarPostura(extra, m8, postura, gated) {
+  const daPostura = pluginsDaPostura(postura, gated);
+  if (daPostura.length === 0) return;
+  const atuais = extra.plugins ?? m8.plugins;
+  if (atuais !== void 0 && !Array.isArray(atuais)) {
+    throw new Error(`[@theokit/agents] approval posture "${postura.kind}" needs to install a plugin, but \`plugins\` was supplied in the legacy object form, which cannot carry both. Pass \`plugins\` as an array so the approval gate is not dropped.`);
+  }
+  extra.plugins = [
+    ...atuais ?? [],
+    ...daPostura
+  ];
+}
+__name(aplicarPostura, "aplicarPostura");
+function pluginsDaPostura(postura, gated) {
+  debugLog("[theokit] approval posture", {
+    kind: postura.kind,
+    reason: razaoDe(postura)
+  });
+  if (gated === void 0 || gated.size === 0) return [];
+  switch (postura.kind) {
+    case "interactive":
+      return [
+        createHitlPlugin({
+          gated,
+          emit: postura.emit,
+          awaitApproval: postura.awaitApproval
+        })
+      ];
+    case "auto-approve":
+      return [
+        createToolHooksPlugin({
+          beforeToolCall: /* @__PURE__ */ __name((ctx) => {
+            if (gated.has(ctx.name)) {
+              debugLog("[theokit] gated tool auto-approved", {
+                tool: ctx.name,
+                reason: postura.reason
+              });
+            }
+            return void 0;
+          }, "beforeToolCall")
+        })
+      ];
+    case "auto-reject":
+      return [
+        createToolHooksPlugin({
+          // Só as tools GATEADAS são recusadas: a postura descreve o gate, não um bloqueio universal.
+          // Recusar tudo quebraria todo agente que tem uma tool livre ao lado de uma gateada.
+          beforeToolCall: /* @__PURE__ */ __name((ctx) => gated.has(ctx.name) ? {
+            block: true,
+            message: `Tool '${ctx.name}' requires human approval, and this surface has no approver (approval posture: auto-reject \u2014 ${postura.reason}). Refused (fail-closed).`
+          } : void 0, "beforeToolCall")
+        })
+      ];
+    case "owned-by-surface":
+      return [];
+  }
+}
+__name(pluginsDaPostura, "pluginsDaPostura");
+
 // src/bridge/definicao-ou-thunk.ts
 function projetar(def, overrides) {
   const compiled = compileAgentDefinition(def);
@@ -1342,6 +1505,7 @@ function toAgentFactory(def, opts) {
       baseDir: overrides.baseDir
     };
     const extra = buildExtraCreateOptions(overrides, compiled);
+    aplicarPostura(extra, m8, opts.approvals, compiled.hitl);
     const agent = await rt.Agent.getOrCreate(sessionId, {
       apiKey: await resolverApiKey(opts.apiKey),
       model: buildModelSelection(model, reasoningEffort),
@@ -2098,52 +2262,6 @@ var AgentBuilder = {
   }
 };
 
-// src/bridge/hitl-plugin.ts
-function createHitlPlugin(wiring) {
-  return {
-    name: "theokit-hitl",
-    version: "1.0.0",
-    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
-    // the HITL veto never fires (the run would proceed WITHOUT waiting for human approval).
-    kind: "general",
-    register(ctx) {
-      ctx.on("pre_tool_call", async (c) => {
-        const opts = wiring.gated.get(c.name);
-        if (!opts) return void 0;
-        const approvalId = crypto.randomUUID();
-        wiring.emit({
-          type: "approval_required",
-          callId: approvalId,
-          toolName: c.name,
-          question: opts.question,
-          input: c.args,
-          callbackUrl: `approve/${approvalId}`,
-          timeoutMs: opts.timeout ?? 3e5,
-          // M20 — carry the declared custom-payload schema so the UI knows what to collect.
-          ...opts.payloadSchema !== void 0 ? {
-            payloadSchema: opts.payloadSchema
-          } : {}
-        });
-        const raw = await wiring.awaitApproval(approvalId, opts, c.name);
-        const decision = typeof raw === "boolean" ? {
-          approved: raw
-        } : raw;
-        if (decision.approved) return void 0;
-        let message = `Tool '${c.name}' denied by human approver`;
-        if (decision.reason) message += `: ${decision.reason}`;
-        if (decision.payload !== void 0) {
-          message += ` (payload: ${JSON.stringify(decision.payload)})`;
-        }
-        return {
-          block: true,
-          message
-        };
-      });
-    }
-  };
-}
-__name(createHitlPlugin, "createHitlPlugin");
-
 // src/bridge/agent-endpoint.ts
 var AgentDefinitionError = class extends Error {
   static {
@@ -3140,59 +3258,6 @@ async function delegate(spec, message, opts = {}) {
 }
 __name(delegate, "delegate");
 
-// src/bridge/tool-hooks-plugin.ts
-function createToolHooksPlugin(hooks) {
-  return {
-    name: "theokit-tool-hooks",
-    version: "1.0.0",
-    // `kind: 'general'` is load-bearing — without it the SDK's isCodePlugin() drops this plugin and
-    // no hook fires (M10/M19 latent bug, proven via a real OpenRouter run).
-    kind: "general",
-    register(ctx) {
-      const { beforeToolCall, afterToolCall, beforeLLMCall, afterLLMCall, processInput } = hooks;
-      if (beforeToolCall) {
-        ctx.on("pre_tool_call", (c) => beforeToolCall({
-          name: c.name ?? "",
-          args: c.args ?? {}
-        }));
-      }
-      if (afterToolCall) {
-        ctx.on("post_tool_call", (c) => afterToolCall({
-          name: c.name ?? "",
-          result: c.result
-        }));
-      }
-      if (beforeLLMCall) {
-        ctx.on("pre_llm_call", (c) => beforeLLMCall({
-          agentId: c.agentId,
-          runId: c.runId,
-          iteration: c.iteration
-        }));
-      }
-      if (afterLLMCall) {
-        ctx.on("post_llm_call", (c) => afterLLMCall({
-          agentId: c.agentId,
-          runId: c.runId,
-          iteration: c.iteration
-        }));
-      }
-      if (processInput) {
-        ctx.on("pre_user_send", async (c) => {
-          const injected = await processInput({
-            prompt: c.prompt ?? "",
-            agentId: c.agentId,
-            runId: c.runId
-          });
-          return injected !== void 0 && injected.length > 0 ? {
-            recalledContext: injected
-          } : void 0;
-        });
-      }
-    }
-  };
-}
-__name(createToolHooksPlugin, "createToolHooksPlugin");
-
 // src/bridge/api-error-handler.ts
 var DEFAULT_MAX_ATTEMPTS = 3;
 async function runWithApiErrorHandling(thunk, policy) {
@@ -3497,6 +3562,7 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
+  createToolHooksPlugin,
   translateSdkEvent,
   buildModelSelection,
   createThinkTagExtractor,
@@ -3538,7 +3604,6 @@ export {
   GoalRunner,
   JudgeCredentialError,
   delegate,
-  createToolHooksPlugin,
   runWithApiErrorHandling,
   createApiErrorHandler,
   delegateBackground,
@@ -3549,4 +3614,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-GGB5WXHS.js.map
+//# sourceMappingURL=chunk-JXR45RAW.js.map