@odingard/guardian-openai-agents 0.1.0 → 0.1.2

package/README.md

@@ -108,7 +108,7 @@ the agent.
   instead.
 - Guardian error, network failure, timeout or a cancelled call — your
   `execute` never runs, and a late answer from Guardian is ignored. The model
-  is told `Guardian could not check refund_order, so it did not run.`, and
+  is told `Guardian could not check refund_order, so it did not run. Try again later.`, and
   `onGuardianError` is called. `decisionTimeoutMs` (default 30000) bounds the
   wait for Guardian's decision; the Agents SDK's own `timeoutMs` and run
   cancellation stop the wait too, but only while Guardian is still deciding.
@@ -137,13 +137,22 @@ even with `onAsk: "result"`.
 In-process mode is decision-gated: `execute` runs after `ALLOW` and before
 the capability is redeemed, so a revocation at redemption lands after the
 effect. Use `mode: "remote"` where Guardian itself must hold the effect.
+In remote mode, a call Guardian performed whose receipt status is not
+`sent-verified` (for example the upstream answered with an error) is a
+`GuardianExecutionFailed`, and the model is told it did not complete; it is
+never reported as an `ALLOW` result.
 `modes` sets the mode per tool name. The Agents SDK renames tools: every
 character that is not a letter or a digit becomes `_` (`refund-order`
 becomes `refund_order`), and Guardian sees the new name. A `modes` entry
 under the name you wrote is applied to the new name; two entries for the
-same tool that disagree are refused when the tool is built. `installRecordTransport: true` makes the
-adapter propose the record-only entry itself on first use (this needs a
-grant that allows it; production usually does not).
+same tool that disagree are refused when the tool is built. `installRecordTransport`
+is off by default. `true` makes the adapter propose the record-only entry
+itself on first use (this needs a grant that allows it; production usually
+does not), and it only works for a tool that has no entry yet: an "already
+registered" answer is refused (`RECORD_TRANSPORT_UNVERIFIED`) and nothing
+runs, including after a restart for an entry the adapter created itself,
+because which entries it registered is kept in memory only. Once the entry
+exists, use it with the option off.
 
 Setting the Agents SDK's own `needsApproval` on a tool adds a local approval
 step before Guardian is asked. It never replaces Guardian's decision.

package/dist/index.js

@@ -35,7 +35,7 @@ var CallGate = class {
   #signal;
   #onAbort;
   #rejecters = /* @__PURE__ */ new Set();
-  #installIds = /* @__PURE__ */ new Set();
+  #setupIds = /* @__PURE__ */ new Set();
   constructor(args) {
     const { client, toolName, timeoutMs, signal } = args;
     this.#timer = setTimeout(
@@ -71,29 +71,31 @@ var CallGate = class {
         );
       });
     };
-    const installIds = this.#installIds;
-    const noteInstall = (result) => {
+    const setupIds = this.#setupIds;
+    const noteSetup = (result) => {
       const id = result?.requestId;
-      if (typeof id === "string" && id.length > 0) installIds.add(id);
+      if (typeof id === "string" && id.length > 0) setupIds.add(id);
     };
     const request = decide(
       async (i) => {
         const result = await client.request(i);
-        if (i.action === "mcp.install") noteInstall(result);
+        if (i.action === "mcp.install" || i.action === "mcp.enable") {
+          noteSetup(result);
+        }
         return result;
       }
     );
     const claim = decide(async (id) => {
       const result = await client.claim(id);
-      if (installIds.has(id)) noteInstall(result);
+      if (setupIds.has(id)) noteSetup(result);
       return result;
     });
-    const executeInstall = decide(
+    const executeSetup = decide(
       (input) => client.execute(input)
     );
     const execute = (input) => {
-      if (installIds.has(input.requestId)) {
-        return executeInstall(input);
+      if (setupIds.has(input.requestId)) {
+        return executeSetup(input);
       }
       this.assertOpen();
       this.commit();
@@ -171,12 +173,15 @@ function denyMessage(err) {
   return `Guardian denied ${err.toolName} (${err.reasonCode}). It did not run. Do not retry the same call.`;
 }
 function unavailableMessage(toolName) {
-  return `Guardian could not check ${toolName}, so it did not run.`;
+  return `Guardian could not check ${toolName}, so it did not run. Try again later.`;
 }
 function executionFailedMessage(err) {
   if (err.localEffectRan) {
     return `${err.toolName} ran, but Guardian could not record it (${err.reasonCode}). Do not call it again; tell the user it ran without a receipt.`;
   }
+  if (err.outcomeUnknown) {
+    return `Guardian could not confirm that ${err.toolName} completed (${err.reasonCode}, requestId ${err.requestId}). It may have run. Do not call it again; tell the user so they can check.`;
+  }
   return `Guardian could not complete ${err.toolName} (${err.reasonCode}). Do not call it again; tell the user so they can check.`;
 }
 function remapModes(modes, writtenName, builtName) {
@@ -220,13 +225,20 @@ function buildTool(shared, toolOptions) {
     });
     const ctx = {
       options: { ...coreOptions, client: gate.client },
-      ensured: shared.ensured
+      ensured: shared.ensured,
+      installed: shared.installed,
+      heldSetup: shared.heldSetup
     };
     try {
-      const output = await runThroughGuardian(ctx, toolName, input, () => {
-        gate.commit();
-        return userExecute(input, runContext, details);
-      });
+      const output = await runThroughGuardian(
+        ctx,
+        toolName,
+        input,
+        (approved) => {
+          gate.commit();
+          return userExecute(approved, runContext, details);
+        }
+      );
       gate.settle();
       return output;
     } catch (err) {
@@ -242,7 +254,8 @@ function buildTool(shared, toolOptions) {
         }
         throw err;
       }
-      if (err instanceof GuardianDenied) {
+      const guardianDidNotAnswer = err instanceof GuardianDenied && err.reasonCode === "SERVICE_UNAVAILABLE" && !startedBeforeError;
+      if (err instanceof GuardianDenied && !guardianDidNotAnswer) {
         if (onDeny === "result" && !hasOutputSchema) {
           return denyMessage(err);
         }
@@ -299,12 +312,22 @@ function buildTool(shared, toolOptions) {
 }
 function guardianTool(toolOptions, options) {
   return buildTool(
-    { options, ensured: /* @__PURE__ */ new Set() },
+    {
+      options,
+      ensured: /* @__PURE__ */ new Set(),
+      installed: /* @__PURE__ */ new Set(),
+      heldSetup: /* @__PURE__ */ new Map()
+    },
     toolOptions
   );
 }
 function createGuardianTool(options) {
-  const shared = { options, ensured: /* @__PURE__ */ new Set() };
+  const shared = {
+    options,
+    ensured: /* @__PURE__ */ new Set(),
+    installed: /* @__PURE__ */ new Set(),
+    heldSetup: /* @__PURE__ */ new Map()
+  };
   return (toolOptions) => buildTool(shared, toolOptions);
 }
 function findApprovalPending(err) {

package/dist-dts/gate.d.ts

@@ -21,8 +21,9 @@ export declare class GuardianUnavailable extends Error {
  *
  * Once the tool starts (or Guardian is asked to execute the tool call) the
  * gate is committed and stops interfering, so a started action is always
- * recorded. Executing a record-transport install does not commit the gate:
- * the deadline and the abort signal still apply to the tool call after it.
+ * recorded. Executing a record-transport setup step (mcp.install or
+ * mcp.enable) does not commit the gate: the deadline and the abort signal
+ * still apply to the tool call after it.
  * Once the call has settled (for example an ASK handed back to the app),
  * the gate opens so `resume()` can claim the approval later.
  */

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@odingard/guardian-openai-agents",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenAI Agents SDK adapter — route an agent's tool calls through Guardian for a deterministic ALLOW/ASK/DENY decision before anything executes.",
   "license": "Apache-2.0",
+  "author": "Odingard Security LLC",
   "type": "module",
   "exports": {
     ".": {
@@ -26,11 +27,11 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "peerDependencies": {
-    "@odingard/guardian-sdk": "^0.3.8",
+    "@odingard/guardian-sdk": "^0.3.9",
     "@openai/agents": ">=0.21.0 <0.22.0"
   },
   "devDependencies": {
-    "@odingard/guardian-sdk": "^0.3.8",
+    "@odingard/guardian-sdk": "^0.3.9",
     "@openai/agents": "0.21.0",
     "@types/node": "^22.20.5",
     "esbuild": "^0.28.2",