@odingard/guardian-vercel-ai 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @odingard/guardian-vercel-ai
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vercel AI SDK adapter for Guardian — route every tool `execute` through a
+deterministic `ALLOW` / `ASK` / `DENY` authority decision before anything
+runs. The agent proposes; the human decides.
+
+## Install
+
+```bash
+npm install @odingard/guardian-vercel-ai @odingard/guardian-sdk ai
+```
+
+`ai` and `@odingard/guardian-sdk` are peer dependencies.
+
+## Two execution modes
+
+| Mode | When to use | What happens on `ALLOW` |
+| --- | --- | --- |
+| `remote` (default) | The tool name is a registered Guardian catalog entry — a bounded HTTP(S) endpoint Guardian calls itself | `client.execute` performs the call; the call resolves to `{ guardian: { decision: "ALLOW", requestId, receipt } }`. The local `execute` impl **never runs** |
+| `inProcess` (opt-in) | The local `execute` impl IS the tool — the common framework case | The impl runs (only after the capability is issued), then `client.execute` redeems + records the evidence; the call resolves to the impl's output |
+
+Set `mode` for every tool or `modes` per tool name:
+
+```ts
+withGuardian(tools, {
+  client,
+  connectionId: "con_…",
+  modes: { refund_order: "inProcess" }, // everything else remote
+});
+```
+
+`inProcess` needs a `transport: "record"` catalog entry on the connection so
+`execute` commits evidence instead of performing an HTTP call. The adapter
+auto-proposes `mcp.install` of that entry the first time each tool is called
+(it goes through the same ALLOW/ASK/DENY gate — a human may need to approve
+it once). **This requires the WO-021 control plane**; a client that can't
+form the proposal raises `GuardianRecordTransportRequired` before any
+network call. Pass `installRecordTransport: false` to opt out (entries must
+then be installed some other way).
+
+## Usage
+
+```ts
+import { tool } from "ai";
+import { z } from "zod";
+import { createGuardianClient } from "@odingard/guardian-sdk";
+import {
+  GuardianApprovalPending,
+  GuardianDenied,
+  withGuardian,
+} from "@odingard/guardian-vercel-ai";
+
+const guardian = createGuardianClient({
+  baseUrl: "https://guardian-api.odingard.com",
+  credential: process.env.GUARDIAN_AGENT_CREDENTIAL!,
+});
+
+const tools = withGuardian(
+  {
+    refund_order: tool({
+      description: "Refund an order",
+      inputSchema: z.object({ orderId: z.string(), amount: z.number() }),
+      execute: async ({ orderId, amount }) => refund(orderId, amount),
+    }),
+  },
+  {
+    client: guardian,
+    connectionId: "con_…",
+    agentName: "billing-agent",
+    mode: "inProcess",
+  },
+);
+
+try {
+  await generateText({ model, tools, prompt });
+} catch (err) {
+  if (err instanceof GuardianApprovalPending) {
+    // err.requestId — surface to a human approver, then:
+    const { output, receipt } = await err.resume();
+  } else if (err instanceof GuardianDenied) {
+    // err.reasonCode — refused before execution
+  }
+}
+```
+
+## What the triad means here
+
+- `ALLOW` — Guardian mints a single-use capability. Remote: `client.execute`
+  performs the catalog call and returns the receipt. In-process: the local
+  impl runs, then `client.execute` redeems + records it. A failed
+  redemption throws `GuardianExecutionFailed` — and in `inProcess` mode the
+  impl's own error propagates before the record call.
+- `ASK` — throws `GuardianApprovalPending` carrying `requestId`. After the
+  human approves in Guardian, `pending.resume()` claims the capability and
+  completes the call. With `onAsk: "result"` the tool instead returns a
+  serializable `{ guardian: { decision: "ASK", requestId, … } }` to the
+  model.
+- `DENY` — throws `GuardianDenied` carrying `reasonCode` (or returns
+  `{ guardian: { decision: "DENY", … } }` with `onDeny: "result"`).
+
+Nothing runs before a decision, and no tool ever runs without a capability
+issued for that exact request.
+
+Options: `client`, `connectionId`, `adapterId?`, `agentName?`, `mode?`,
+`modes?`, `installRecordTransport?`, `purpose?` (string or
+`(toolName, input) => string`), `onAsk?`, `onDeny?`, `onReceipt?` (called
+with `{ toolName, requestId, receipt }` after each `ALLOW`).
+
+## License
+
+Apache-2.0

package/dist/index.js

@@ -0,0 +1,373 @@
+// src/core.ts
+var GuardianDenied = class extends Error {
+  decision = "DENY";
+  toolName;
+  reasonCode;
+  requestId;
+  constructor(args) {
+    super(
+      `Guardian denied "${args.toolName}" (reasonCode=${args.reasonCode})` + (args.requestId ? ` requestId=${args.requestId}` : "")
+    );
+    this.name = "GuardianDenied";
+    this.toolName = args.toolName;
+    this.reasonCode = args.reasonCode;
+    this.requestId = args.requestId;
+  }
+};
+var GuardianExecutionFailed = class extends Error {
+  toolName;
+  requestId;
+  reasonCode;
+  /**
+   * inProcess only: the local tool already ran before Guardian's final
+   * redemption refused it. The effect happened without a recorded receipt;
+   * treat it as an incident, never as a successful governed action.
+   */
+  localEffectRan;
+  constructor(args) {
+    super(
+      `Guardian execution of "${args.toolName}" failed (requestId=${args.requestId}, reasonCode=${args.reasonCode}${args.localEffectRan ? ", localEffectRan=true" : ""})`
+    );
+    this.name = "GuardianExecutionFailed";
+    this.toolName = args.toolName;
+    this.requestId = args.requestId;
+    this.reasonCode = args.reasonCode;
+    this.localEffectRan = args.localEffectRan ?? false;
+  }
+};
+var GuardianRecordTransportRequired = class extends Error {
+  toolName;
+  constructor(args) {
+    super(
+      `Guardian in-process mode for "${args.toolName}" requires a record-transport catalog entry (transport: "record"), which needs the updated Guardian control plane \u2014 auto-install was rejected by the client before it reached the network`
+    );
+    this.name = "GuardianRecordTransportRequired";
+    this.toolName = args.toolName;
+  }
+};
+var GuardianApprovalPending = class extends Error {
+  decision = "ASK";
+  requestId;
+  toolName;
+  input;
+  #resume;
+  constructor(args, resume) {
+    super(
+      `Guardian held "${args.toolName}" for human approval (requestId=${args.requestId})`
+    );
+    this.name = "GuardianApprovalPending";
+    this.requestId = args.requestId;
+    this.toolName = args.toolName;
+    this.input = args.input;
+    this.#resume = resume;
+  }
+  /** Claim + execute + finish after the human approves. */
+  resume() {
+    return this.#resume();
+  }
+};
+function createGuardianContext(options) {
+  return { options, ensured: /* @__PURE__ */ new Set() };
+}
+function toolModeFor(options, toolName) {
+  return options.modes?.[toolName] ?? options.mode ?? "remote";
+}
+function toArgumentsRecord(input) {
+  if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+    return input;
+  }
+  return input === void 0 ? {} : { input };
+}
+function resolvePurpose(options, toolName, input) {
+  if (typeof options.purpose === "function") {
+    return options.purpose(toolName, input);
+  }
+  if (typeof options.purpose === "string") {
+    return options.purpose;
+  }
+  const agent = options.agentName ?? "agent";
+  return `${agent} invoked ${toolName}`;
+}
+function deny(options, toolName, reasonCode, requestId) {
+  if (options.onDeny === "result") {
+    return {
+      guardian: {
+        decision: "DENY",
+        toolName,
+        reasonCode,
+        ...requestId ? { requestId } : {},
+        message: `Guardian denied ${toolName} (${reasonCode}). Do not retry the same call.`
+      }
+    };
+  }
+  throw new GuardianDenied({
+    toolName,
+    reasonCode,
+    ...requestId ? { requestId } : {}
+  });
+}
+function isLocalValidationError(err) {
+  return typeof err === "object" && err !== null && Array.isArray(err.issues);
+}
+async function ensureRecordTransport(ctx, toolName, input, runTool) {
+  const { options } = ctx;
+  if (options.installRecordTransport === false) {
+    return;
+  }
+  const key = `${options.connectionId}:${toolName}`;
+  if (ctx.ensured.has(key)) {
+    return;
+  }
+  let result;
+  try {
+    result = await options.client.request({
+      action: "mcp.install",
+      connectionId: options.connectionId,
+      tool: {
+        name: toolName,
+        description: `In-process tool "${toolName}" \u2014 evidence record only (registered by a Guardian framework adapter)`,
+        transport: "record"
+      },
+      ...options.adapterId ? { adapterId: options.adapterId } : {},
+      purpose: `Register in-process tool ${toolName} for evidence recording`
+    });
+  } catch (err) {
+    if (isLocalValidationError(err)) {
+      throw new GuardianRecordTransportRequired({ toolName });
+    }
+    throw err;
+  }
+  if (!result.ok) {
+    if (result.reasonCode === "TOOL_ALREADY_INSTALLED") {
+      ctx.ensured.add(key);
+      return;
+    }
+    return deny(options, toolName, result.reasonCode, void 0);
+  }
+  if (result.decision === "ALLOW" && result.capabilityToken) {
+    const executed = await options.client.execute({
+      requestId: result.requestId,
+      capabilityToken: result.capabilityToken
+    });
+    if (!executed.ok) {
+      throw new GuardianExecutionFailed({
+        toolName,
+        requestId: result.requestId,
+        reasonCode: executed.reasonCode
+      });
+    }
+    ctx.ensured.add(key);
+    return;
+  }
+  if (result.decision === "ASK") {
+    const requestId = result.requestId;
+    if (options.onAsk === "result") {
+      return {
+        guardian: {
+          decision: "ASK",
+          requestId,
+          toolName,
+          message: `Installing the record-transport catalog entry for ${toolName} needs human approval (requestId ${requestId}). Retry the tool call after approval.`
+        }
+      };
+    }
+    const resumeInstall = async () => {
+      const claimed = await options.client.claim(requestId);
+      if (claimed.ok && claimed.decision === "ALLOW" && claimed.capabilityToken) {
+        const executed = await options.client.execute({
+          requestId: claimed.requestId,
+          capabilityToken: claimed.capabilityToken
+        });
+        if (!executed.ok) {
+          throw new GuardianExecutionFailed({
+            toolName,
+            requestId: claimed.requestId,
+            reasonCode: executed.reasonCode
+          });
+        }
+        ctx.ensured.add(key);
+        const output = await runThroughGuardian(ctx, toolName, input, runTool);
+        return {
+          requestId: claimed.requestId,
+          receipt: executed.receipt,
+          output
+        };
+      }
+      if (claimed.ok && claimed.decision === "ASK") {
+        throw new GuardianApprovalPending(
+          { requestId: claimed.requestId, toolName, input },
+          resumeInstall
+        );
+      }
+      throw new GuardianDenied({
+        toolName,
+        reasonCode: claimed.ok ? claimed.reasonCode ?? "MISSING_CAPABILITY" : claimed.reasonCode,
+        ...claimed.ok ? { requestId: claimed.requestId } : {}
+      });
+    };
+    throw new GuardianApprovalPending(
+      { requestId, toolName, input },
+      resumeInstall
+    );
+  }
+  return deny(
+    options,
+    toolName,
+    result.reasonCode ?? "MISSING_CAPABILITY",
+    result.requestId
+  );
+}
+async function settle(ctx, toolName, input, result, runTool) {
+  const { options } = ctx;
+  const mode = toolModeFor(options, toolName);
+  if (!result.ok) {
+    const heldRequestId = result.requestId;
+    if (result.reasonCode === "APPROVAL_REQUIRED" && typeof heldRequestId === "string" && heldRequestId.length > 0) {
+      return settle(
+        ctx,
+        toolName,
+        input,
+        {
+          ok: true,
+          requestId: heldRequestId,
+          decision: "ASK",
+          reasonCode: result.reasonCode
+        },
+        runTool
+      );
+    }
+    return deny(options, toolName, result.reasonCode, void 0);
+  }
+  if (result.decision === "ALLOW" && result.capabilityToken) {
+    const requestId = result.requestId;
+    if (mode === "remote") {
+      const executed2 = await options.client.execute({
+        requestId,
+        capabilityToken: result.capabilityToken
+      });
+      if (!executed2.ok) {
+        throw new GuardianExecutionFailed({
+          toolName,
+          requestId,
+          reasonCode: executed2.reasonCode
+        });
+      }
+      await options.onReceipt?.({
+        toolName,
+        requestId,
+        receipt: executed2.receipt
+      });
+      return {
+        guardian: {
+          decision: "ALLOW",
+          requestId,
+          toolName,
+          receipt: executed2.receipt
+        }
+      };
+    }
+    const output = await runTool();
+    const executed = await options.client.execute({
+      requestId,
+      capabilityToken: result.capabilityToken
+    });
+    if (!executed.ok) {
+      throw new GuardianExecutionFailed({
+        toolName,
+        requestId,
+        reasonCode: executed.reasonCode,
+        localEffectRan: true
+      });
+    }
+    await options.onReceipt?.({ toolName, requestId, receipt: executed.receipt });
+    return output;
+  }
+  if (result.decision === "ASK") {
+    const resume = async () => {
+      const claimed = await options.client.claim(result.requestId);
+      let receipt;
+      const output = await settle(
+        {
+          ...ctx,
+          options: {
+            ...options,
+            onReceipt: async (event) => {
+              receipt = event.receipt;
+              await options.onReceipt?.(event);
+            }
+          }
+        },
+        toolName,
+        input,
+        claimed,
+        runTool
+      );
+      return { requestId: result.requestId, receipt, output };
+    };
+    if (options.onAsk === "result") {
+      return {
+        guardian: {
+          decision: "ASK",
+          requestId: result.requestId,
+          toolName,
+          message: `Held for human approval. After approval, claim requestId ${result.requestId} and re-run the tool.`
+        }
+      };
+    }
+    throw new GuardianApprovalPending(
+      { requestId: result.requestId, toolName, input },
+      resume
+    );
+  }
+  return deny(
+    options,
+    toolName,
+    result.reasonCode ?? "MISSING_CAPABILITY",
+    result.requestId
+  );
+}
+async function runThroughGuardian(ctx, toolName, input, runTool) {
+  const { options } = ctx;
+  if (toolModeFor(options, toolName) === "inProcess") {
+    const gate = await ensureRecordTransport(ctx, toolName, input, runTool);
+    if (gate !== void 0) {
+      return gate;
+    }
+  }
+  const result = await options.client.request({
+    action: "tool.invoke",
+    connectionId: options.connectionId,
+    toolName,
+    arguments: toArgumentsRecord(input),
+    ...options.adapterId ? { adapterId: options.adapterId } : {},
+    purpose: resolvePurpose(options, toolName, input)
+  });
+  return settle(ctx, toolName, input, result, runTool);
+}
+
+// src/index.ts
+function withGuardian(tools, options) {
+  const ctx = createGuardianContext(options);
+  const wrapped = {};
+  for (const [toolName, definition] of Object.entries(tools)) {
+    const execute = definition.execute;
+    wrapped[toolName] = typeof execute === "function" ? {
+      ...definition,
+      execute: (input, callOptions) => runThroughGuardian(
+        ctx,
+        toolName,
+        input,
+        () => execute(input, callOptions)
+      )
+    } : definition;
+  }
+  return wrapped;
+}
+export {
+  GuardianApprovalPending,
+  GuardianDenied,
+  GuardianExecutionFailed,
+  GuardianRecordTransportRequired,
+  toArgumentsRecord,
+  withGuardian
+};

package/dist-dts/core.d.ts

@@ -0,0 +1,177 @@
+import type { GuardianClient, GuardianRequestResult } from "@odingard/guardian-sdk";
+/**
+ * Shared triad semantics for the framework adapters — identical to
+ * mcp-server/src/dispatch.ts: a tool never runs unless Guardian issued a
+ * capability for this exact request.
+ *
+ * Two execution modes:
+ *
+ * - `remote` (default): the tool is a registered catalog entry — a bounded
+ *   HTTPS call Guardian executes itself. `client.execute` IS the execution;
+ *   the local `execute`/`func` implementation is never run.
+ * - `inProcess` (opt-in): the local implementation is the tool. After ALLOW
+ *   the impl runs first, then `client.execute` redeems the capability and
+ *   records the evidence — which requires a `transport: "record"` catalog
+ *   entry on the connection (auto-installed via `mcp.install`; needs the
+ *   WO-021 control plane).
+ */
+/** Thrown (or returned) when Guardian refuses an action before execution. */
+export declare class GuardianDenied extends Error {
+    readonly decision: "DENY";
+    readonly toolName: string;
+    readonly reasonCode: string;
+    readonly requestId: string | undefined;
+    constructor(args: {
+        toolName: string;
+        reasonCode: string;
+        requestId?: string;
+    });
+}
+/** ALLOW was decided but redeeming the capability failed. */
+export declare class GuardianExecutionFailed extends Error {
+    readonly toolName: string;
+    readonly requestId: string;
+    readonly reasonCode: string;
+    /**
+     * inProcess only: the local tool already ran before Guardian's final
+     * redemption refused it. The effect happened without a recorded receipt;
+     * treat it as an incident, never as a successful governed action.
+     */
+    readonly localEffectRan: boolean;
+    constructor(args: {
+        toolName: string;
+        requestId: string;
+        reasonCode: string;
+        localEffectRan?: boolean;
+    });
+}
+/**
+ * `inProcess` mode needs a record-transport catalog entry on the tool
+ * connection so `execute` commits evidence without an HTTP call. Thrown when
+ * the auto-install proposal could not even be formed — the SDK/control
+ * plane in use predates the `transport: "record"` tool kind (WO-021).
+ */
+export declare class GuardianRecordTransportRequired extends Error {
+    readonly toolName: string;
+    constructor(args: {
+        toolName: string;
+    });
+}
+export type GuardianResume<Output> = () => Promise<{
+    requestId: string;
+    receipt: unknown;
+    output: Output | GuardianDecisionResult;
+}>;
+/**
+ * Guardian held the action for human approval (`ASK`). Carries the requestId
+ * the app needs to surface to the approver; `resume()` claims the approved
+ * capability, executes it, and finishes the call — never before approval.
+ */
+export declare class GuardianApprovalPending<Output = unknown> extends Error {
+    #private;
+    readonly decision: "ASK";
+    readonly requestId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    constructor(args: {
+        requestId: string;
+        toolName: string;
+        input: unknown;
+    }, resume: GuardianResume<Output>);
+    /** Claim + execute + finish after the human approves. */
+    resume(): Promise<{
+        requestId: string;
+        receipt: unknown;
+        output: GuardianDecisionResult | Output;
+    }>;
+}
+/**
+ * Serializable decision handed back to the model: ASK/DENY when mode is
+ * "result", plus the ALLOW receipt a remote-mode call resolves to.
+ */
+export type GuardianDecisionResult = {
+    guardian: {
+        decision: "ALLOW";
+        requestId: string;
+        toolName: string;
+        receipt: unknown;
+    };
+} | {
+    guardian: {
+        decision: "ASK";
+        requestId: string;
+        toolName: string;
+        message: string;
+    };
+} | {
+    guardian: {
+        decision: "DENY";
+        toolName: string;
+        reasonCode: string;
+        requestId?: string;
+        message: string;
+    };
+};
+export type GuardianMode = "throw" | "result";
+/**
+ * `remote`: the tool name is a registered Guardian catalog entry and the
+ * server performs the bounded HTTPS call — the local impl never runs.
+ * `inProcess`: the local impl IS the tool; it runs only after the capability
+ * is issued and its evidence is recorded via execute afterwards.
+ */
+export type GuardianToolMode = "remote" | "inProcess";
+export type GuardianAdapterOptions = Readonly<{
+    client: GuardianClient;
+    /** Tool connection id the proposals are authorized against. */
+    connectionId: string;
+    /** Adapter audience for executes; defaults to the tool adapter. */
+    adapterId?: string;
+    /** Human label for the agent in audit + default purpose strings. */
+    agentName?: string;
+    /** Static purpose or per-call purpose shown to approvers. */
+    purpose?: string | ((toolName: string, input: unknown) => string);
+    /**
+     * Execution mode applied to every wrapped tool: "remote" (default) defers
+     * execution to the Guardian catalog entry; "inProcess" runs the local
+     * implementation and records the evidence. See `modes` for per-tool
+     * overrides.
+     */
+    mode?: GuardianToolMode;
+    /** Per-tool-name mode overrides, e.g. `{ refund_order: "remote" }`. */
+    modes?: Readonly<Record<string, GuardianToolMode>>;
+    /**
+     * inProcess only: auto-propose `mcp.install` of a `transport: "record"`
+     * catalog entry for each wrapped tool that lacks one. Default true;
+     * requires the WO-021 control plane — a pre-WO-021 SDK raises
+     * `GuardianRecordTransportRequired` before any network call.
+     */
+    installRecordTransport?: boolean;
+    /** What ASK does inside the wrapped call. Default "throw". */
+    onAsk?: GuardianMode;
+    /** What DENY does inside the wrapped call. Default "throw". */
+    onDeny?: GuardianMode;
+    /** Called with the execution receipt after every ALLOW. */
+    onReceipt?: (event: {
+        toolName: string;
+        requestId: string;
+        receipt: unknown;
+    }) => void | PromiseLike<void>;
+}>;
+/** Per-wrapper state: which record-transport entries were already ensured. */
+export type GuardianContext = {
+    options: GuardianAdapterOptions;
+    ensured: Set<string>;
+};
+export declare function createGuardianContext(options: GuardianAdapterOptions): GuardianContext;
+export declare function toolModeFor(options: GuardianAdapterOptions, toolName: string): GuardianToolMode;
+export declare function toArgumentsRecord(input: unknown): Record<string, unknown>;
+/**
+ * The triad applied to an already-answered request (request or claim).
+ * remote: ALLOW → execute (Guardian performs the call) → receipt is the
+ * output; the local impl never runs.
+ * inProcess: ALLOW → run the impl → execute redeems + records → impl output.
+ * ASK → pending handle; DENY → typed denial.
+ */
+export declare function settle<Output>(ctx: GuardianContext, toolName: string, input: unknown, result: GuardianRequestResult, runTool: () => Output | PromiseLike<Output>): Promise<Output | GuardianDecisionResult>;
+/** Ensure the record-transport entry (inProcess), propose, settle. */
+export declare function runThroughGuardian<Output>(ctx: GuardianContext, toolName: string, input: unknown, runTool: () => Output | PromiseLike<Output>): Promise<Output | GuardianDecisionResult>;

package/dist-dts/index.d.ts

@@ -0,0 +1,21 @@
+import type { ToolSet } from "ai";
+import { type GuardianAdapterOptions } from "./core.js";
+export { GuardianApprovalPending, GuardianDenied, GuardianExecutionFailed, GuardianRecordTransportRequired, toArgumentsRecord, type GuardianAdapterOptions, type GuardianDecisionResult, type GuardianMode, type GuardianToolMode, } from "./core.js";
+export type GuardianVercelAIOptions = GuardianAdapterOptions;
+/**
+ * Wrap a Vercel AI SDK tool set so every tool's `execute` routes through
+ * Guardian.
+ *
+ * - mode "remote" (default): the tool name is a registered Guardian catalog
+ *   entry — `client.execute` performs the bounded HTTPS call and the local
+ *   `execute` impl never runs; the call resolves to the ALLOW receipt.
+ * - mode "inProcess" (opt-in, `mode`/`modes` options): the local impl IS the
+ *   tool — it runs only once ALLOW issues the capability, and `execute`
+ *   redeems + records the evidence afterwards (auto-installs a
+ *   `transport: "record"` catalog entry via `mcp.install`; WO-021).
+ *
+ * ASK throws `GuardianApprovalPending` (or a result object with
+ * onAsk: "result"); DENY throws `GuardianDenied` (or a result object with
+ * onDeny: "result"). Tools without an `execute` pass through unchanged.
+ */
+export declare function withGuardian<T extends ToolSet>(tools: T, options: GuardianVercelAIOptions): T;

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@odingard/guardian-vercel-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Vercel AI SDK adapter — route an agent's tool calls through Guardian for a deterministic ALLOW/ASK/DENY decision before anything executes.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist-dts/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-dts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:ai --external:@odingard/guardian-sdk --outfile=dist/index.js && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "@odingard/guardian-sdk": "^0.2.0",
+    "ai": "^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@odingard/guardian-sdk": "^0.2.0",
+    "@types/node": "^22.20.5",
+    "ai": "^7.0.159",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "guardian",
+    "ai-agents",
+    "authorization",
+    "authority",
+    "vercel-ai-sdk",
+    "human-in-the-loop"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Odingard/guardian-sdk.git",
+    "directory": "packages/vercel-ai"
+  },
+  "homepage": "https://guardian.odingard.com"
+}