@oked/ai-sdk 0.0.0-stage → 0.6.21

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 the 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 the 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 any 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,186 @@
-# Temporary Holding Version
+# @oked/ai-sdk
 
-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.
+[![npm version](https://img.shields.io/npm/v/@oked/ai-sdk.svg)](https://www.npmjs.com/package/@oked/ai-sdk)
+[![License: Apache-2.0](https://img.shields.io/npm/l/@oked/ai-sdk.svg)](./LICENSE)
+
+OKed for the [Vercel AI SDK](https://ai-sdk.dev) (`ai`). Risky tool calls wait for a person, in Telegram or on the [web dashboard](https://oked.ai/dashboard), before `execute` runs. The iPhone app is coming soon. Questions: [contact@oked.ai](mailto:contact@oked.ai).
+
+AI SDK 7 decides this on the call, through `toolApproval`. `okedToolApproval()` waits on `approve()` from [`@oked/sdk`](../sdk) and answers in that same call. A denial or a timeout comes back as `{ type: "denied", reason }`. The AI SDK does not run the tool, and the reason is the `execution-denied` result the model reads.
+
+This package does not return `user-approval`. That status ends the generation and leaves the tool runnable until some later request answers it. Forgetting that second step, or answering it in code, would run the tool with no OKed decision.
+
+`withOked()` and `okedTools()` wrap `execute` instead. Use them when the gate has to live on the tool object, or on AI SDK 5 and 6 (those versions have `needsApproval`, which is the same two-step pause). Do not set `toolApproval` on a tool you already wrapped. The person would be asked twice.
+
+## Install
+
+```sh
+npm install @oked/ai-sdk
+```
+
+`ai` is an optional peer dependency (`>=5.0.0`). You already have it if you are calling `generateText`, `streamText`, or `ToolLoopAgent`. `okedToolApproval()` needs AI SDK 7. The `execute` wrappers also work on AI SDK 5 and 6. Node.js 18 or newer.
+
+This package has no pairing command. Provide a key in either place:
+
+- `OKED_API_KEY` in the environment, or
+- `~/.oked/config.json` (`{ "apiKey": "ok_..." }`)
+
+Create a key from the [dashboard](https://oked.ai/dashboard) after you [sign up](https://oked.ai/signup), or run `oked init --key-only` from [`@oked/claude-code`](../claude-code).
+
+Each request sends `source: "ai-sdk"` and `client: "@oked/ai-sdk@<version>"`. Both are part of the receipt subject.
+
+## Quick start
+
+Pass `okedToolApproval()` as `toolApproval`. Every tool on that call is classified. `safe` and `warning` run immediately. `review` and `high_stakes` wait. The default wait is 630 seconds, so the backend's 10 minute window is the one that answers. A timeout denies.
+
+```ts
+import { generateText, isStepCount, tool } from "ai";
+import { okedToolApproval } from "@oked/ai-sdk";
+import { z } from "zod";
+
+const runCommand = tool({
+  description: "Run a shell command",
+  inputSchema: z.object({
+    command: z.string(),
+  }),
+  execute: async ({ command }) => {
+    // Runs only after OKed has approved a sensitive command.
+    return { command, exitCode: 0 };
+  },
+});
+
+const result = await generateText({
+  model, // your AI SDK model
+  tools: { runCommand },
+  toolApproval: okedToolApproval(),
+  stopWhen: isStepCount(5),
+  instructions: "When OKed denies a tool, do not retry that action. Ask the user how to proceed.",
+  prompt: "Delete the old export in /var/data",
+});
+```
+
+`streamText` takes the same `toolApproval` option. The stream stays open while a person decides, then continues.
+
+## Agent
+
+```ts
+import { ToolLoopAgent, isStepCount } from "ai";
+import { okedToolApproval } from "@oked/ai-sdk";
+
+const agent = new ToolLoopAgent({
+  model,
+  instructions: "When OKed denies a tool, do not retry that action. Ask the user how to proceed.",
+  tools: { runCommand },
+  toolApproval: okedToolApproval(),
+  stopWhen: isStepCount(10),
+});
+
+const result = await agent.generate({
+  prompt: "Remove /var/data/old-export",
+});
+```
+
+`agent.stream()` uses the same constructor option.
+
+## One tool, or a tools object
+
+`okedToolApprovalFor(name)` is the per-tool form. A tool you leave off the map is not gated, so prefer the function above unless you mean to opt out.
+
+```ts
+toolApproval: {
+  runCommand: okedToolApprovalFor("runCommand"),
+  readFile: "not-applicable",
+}
+```
+
+Wrap `execute` when you want the gate on the tool itself:
+
+```ts
+import { withOked, okedTools } from "@oked/ai-sdk";
+
+const runCommand = withOked(
+  tool({
+    description: "Run a shell command",
+    inputSchema: z.object({ command: z.string() }),
+    execute: async ({ command }) => ({ command, exitCode: 0 }),
+  }),
+  { name: "runCommand" },
+);
+
+const tools = okedTools({ runCommand, readFile });
+```
+
+`name` is the key you put on the tools object. `withOked` returns a new tool and does not change the original. On approve, `execute` is called with the same input and the same options object, including `toolCallId` and `abortSignal`. On deny, timeout, or error, `execute` is not called.
+
+The wrapper returns this object, which the model sees as the tool result:
+
+```ts
+{
+  oked: "denied",
+  decision: "denied" | "timeout" | "error",
+  approvalId: string | null,
+  tier: "safe" | "warning" | "review" | "high_stakes",
+  reason: string
+}
+```
+
+`isOkedDenial(value)` checks that shape. If the tool defines `outputSchema`, the wrapper throws `OkedDeniedError` instead, with the same reason as `message`, so schema validation cannot replace the reason with a validation error.
+
+A tool with no `execute` (a provider-executed tool, or a client-side tool) cannot be stopped from this package. `okedTools` copies it through and logs that it is not gated. `withOked` throws at setup time. The AI SDK's own `toolApproval` has the same limit: it only covers tools the SDK executes locally.
+
+## Configuration
+
+Same ideas as the other integrations. Omit these to use the defaults.
+
+| Option | Default | What it does |
+|---|---|---|
+| `apiKey` | `OKED_API_KEY`, then `~/.oked/config.json` | Used when you do not pass `client`. |
+| `timeoutMs` | `630000` | How long to wait. A timeout denies. Used when you do not pass `client`. |
+| `minTier` | `"review"` (`OKED_MIN_TIER`) | Lowest tier that waits. `high_stakes` asks only for that tier. |
+| `alwaysApprove` | none | Tool names that always wait, including names the classifier calls safe. |
+| `alwaysAllow` | none | Tool names that always run. Wins over `alwaysApprove`. Exact, case-sensitive. |
+| `strictFailClosed` | `false` (`OKED_STRICT_FAIL_CLOSED=1`) | When true, an unreachable backend denies every sensitive tool. When false, it denies `high_stakes` only. |
+| `cwd` | `process.cwd()` | Recorded on the approval. |
+| `sessionId` | the AI SDK tool call id | Receipt session. Set it to group a whole conversation. |
+| `client` | a new `OKedClient` | Pass an existing client, or a test double. |
+| `log` | stderr, prefixed with `[OKed]` | Receives the message with no prefix. |
+
+`safe` and `warning` do not wait, even if `minTier` is lower, unless `alwaysApprove` lists the tool or a saved rule matches. A matching rule sends the call to `approve()` so the rule is applied on the server and the receipt records it. If the rules lookup fails, `safe` and `warning` still run. `review` and `high_stakes` do not depend on that lookup.
+
+```ts
+toolApproval: okedToolApproval({
+  minTier: "high_stakes",
+  alwaysApprove: ["sendEmail"],
+  alwaysAllow: ["readFile"],
+  cwd: process.cwd(),
+})
+```
+
+## Behavior
+
+| Situation | What the model gets | Does `execute` run? |
+|---|---|---|
+| `safe`, or `warning` with no matching rule | nothing extra (`toolApproval` returns `undefined`) | yes |
+| Person approves | the tool's own result. The transcript also records `{ type: "approved" }`. | yes |
+| Person denies | `{ type: "denied", reason }` and an `execution-denied` tool result | no |
+| Approval window expires (`timeout`) | the same denial shape. The reason says nobody responded. | no |
+| No API key, invalid key, bad receipt, HTTP error, unexpected error | a denial that tells the model not to retry | no |
+| Backend unreachable, `high_stakes` or `strictFailClosed` | a denial | no |
+| Backend unreachable, lower sensitive tier, strict mode off | the tool runs. Stderr says it was allowed degraded. | yes |
+
+An explicit denial is final. A timeout is a denial. Nothing in those paths fails open.
+
+Add a line to your instructions: "When OKed denies a tool, do not retry that action." The reason already says not to retry. Models still retry a bare tool error more often than a sentence that tells them to stop.
+
+## Timeouts
+
+The client waits 630 seconds (`DEFAULT_APPROVAL_TIMEOUT_MS`). That is 30 seconds past the 10 minute window, so the backend's `timeout` answer is the one that comes back, and the tool is denied.
+
+Set the server's max duration, and any AI SDK `timeout` or `timeout.stepMs`, above that wait. Those budgets include the tool step. A platform that kills the process during the wait cannot deliver the denial, because the process is gone. `timeoutMs` on this package shortens the OKed wait itself. That shorter wait still denies. It does not let the tool run.
+
+## Receipts
+
+`approve()` checks the signed receipt before an approval counts. A receipt that does not verify denies the tool. An approval with no receipt denies too, which is the default since 0.6.0. A deny or a timeout that arrives without a receipt stays a deny. See [docs/receipts.md](../../docs/receipts.md).
+
+## License
+
+[Apache-2.0](./LICENSE)

package/dist/gate.d.ts

@@ -0,0 +1,14 @@
+import type { OkedAiOptions, OkedGateResult } from "./types.js";
+export { unexpectedMessage } from "./messages.js";
+export interface GateCall {
+    toolName: string;
+    input: unknown;
+    toolCallId?: string;
+}
+/**
+ * Classify one call and, when the tier needs a person, wait on `approve()`.
+ * Safe and warning calls return a local allow unless a rule matches or
+ * `alwaysApprove` lists the tool. The returned denial is final: callers must
+ * not run the tool.
+ */
+export declare function createGate(options?: OkedAiOptions): (call: GateCall) => Promise<OkedGateResult>;

package/dist/gate.js

@@ -0,0 +1,219 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { OKedClient, OKedAuthError, OKedBackendUnreachableError, OKedHttpError, OKedReceiptError, OKedTooManyPendingError, TIER_ORDER, applyRules, classify, degradedDecision, describe, describeFields, lookupPrTitle, } from "@oked/sdk";
+import { approvedMessage, authMessage, classifierMessage, deniedMessage, httpMessage, malformedMessage, missingNameMessage, noKeyMessage, pendingMessage, receiptMessage, timeoutMessage, unexpectedMessage, unreachableMessage, } from "./messages.js";
+export { unexpectedMessage } from "./messages.js";
+const APPROVAL_TIERS = new Set(["review", "high_stakes"]);
+const CLIENT_ID = (() => {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        return `@oked/ai-sdk@${JSON.parse(readFileSync(pkgPath, "utf-8")).version}`;
+    }
+    catch {
+        return "@oked/ai-sdk";
+    }
+})();
+function defaultLog(message) {
+    process.stderr.write(`[OKed] ${message}\n`);
+}
+function asToolInput(input) {
+    if (input !== null && typeof input === "object" && !Array.isArray(input)) {
+        return input;
+    }
+    if (input === undefined)
+        return {};
+    return { value: input };
+}
+function resolveMinTier(options) {
+    if (options.minTier && options.minTier in TIER_ORDER)
+        return options.minTier;
+    const env = process.env.OKED_MIN_TIER;
+    if (env && env in TIER_ORDER)
+        return env;
+    return "review";
+}
+function isStrict(options, client) {
+    if (typeof options.strictFailClosed === "boolean")
+        return options.strictFailClosed;
+    return client.strictFailClosed === true;
+}
+function resolveClient(options) {
+    if (options.client)
+        return options.client;
+    const timeout = typeof options.timeoutMs === "number" &&
+        Number.isFinite(options.timeoutMs) &&
+        options.timeoutMs > 0
+        ? options.timeoutMs
+        : undefined;
+    return new OKedClient({
+        ...(options.apiKey ? { apiKey: options.apiKey } : {}),
+        ...(timeout !== undefined ? { timeout } : {}),
+        ...(typeof options.strictFailClosed === "boolean"
+            ? { strictFailClosed: options.strictFailClosed }
+            : {}),
+        client: CLIENT_ID,
+        source: options.source ?? "ai-sdk",
+    });
+}
+function deny(decision, approvalId, reason, tier) {
+    return { action: "deny", decision, approvalId, reason, tier };
+}
+function localAllow() {
+    return { action: "allow", recorded: false };
+}
+function approvalIdOf(result) {
+    return typeof result.approval_id === "string" ? result.approval_id : null;
+}
+function mapApproval(result, tier) {
+    if (!result || typeof result.approved !== "boolean") {
+        return deny("error", null, malformedMessage(), tier);
+    }
+    const approvalId = approvalIdOf(result);
+    if (result.approved) {
+        return { action: "allow", recorded: true, reason: approvedMessage(approvalId) };
+    }
+    if (result.decision === "timeout") {
+        return deny("timeout", approvalId, timeoutMessage(approvalId), tier);
+    }
+    return deny("denied", approvalId, deniedMessage(approvalId), tier);
+}
+function mapError(err, tier, strict) {
+    if (err instanceof OKedReceiptError) {
+        return deny("error", null, receiptMessage(err.problems), tier);
+    }
+    if (err instanceof OKedAuthError) {
+        return deny("error", null, authMessage(), tier);
+    }
+    if (err instanceof OKedTooManyPendingError) {
+        return deny("error", null, pendingMessage(err.message), tier);
+    }
+    if (err instanceof OKedHttpError) {
+        return deny("error", null, httpMessage(err.status, err.detail), tier);
+    }
+    if (err instanceof OKedBackendUnreachableError) {
+        const decision = degradedDecision(tier, { strictFailClosed: strict });
+        if (decision === "allow")
+            return localAllow();
+        const why = strict ? "strict fail-closed" : "high-stakes";
+        return deny("error", null, unreachableMessage(tier, why), tier);
+    }
+    return deny("error", null, unexpectedMessage(err), tier);
+}
+async function rulesWantBackend(client, tier, toolName, toolInput, cwd) {
+    if (!client.apiKey || !client.getRules)
+        return false;
+    try {
+        const rules = await client.getRules();
+        if (!Array.isArray(rules) || rules.length === 0)
+            return false;
+        const fields = describeFields(toolName, toolInput, { cwd }) ?? {};
+        return Boolean(applyRules({ tier, fields }, rules, { cwd }).appliedRuleId);
+    }
+    catch {
+        // A failed rules lookup must not block a safe or warning call.
+        return false;
+    }
+}
+function summaryOf(toolName, toolInput) {
+    const raw = toolInput.command ?? toolInput.cmd ?? toolInput.file_path ?? toolInput.path ?? toolName;
+    return typeof raw === "string" && raw ? raw : toolName;
+}
+/**
+ * Classify one call and, when the tier needs a person, wait on `approve()`.
+ * Safe and warning calls return a local allow unless a rule matches or
+ * `alwaysApprove` lists the tool. The returned denial is final: callers must
+ * not run the tool.
+ */
+export function createGate(options = {}) {
+    const client = resolveClient(options);
+    const log = options.log ?? defaultLog;
+    const cwd = options.cwd ?? process.cwd();
+    return async (call) => {
+        const toolName = typeof call.toolName === "string" ? call.toolName.trim() : "";
+        if (!toolName) {
+            return deny("error", null, missingNameMessage(), "review");
+        }
+        if (client.apiKey && client.heartbeat) {
+            try {
+                await client.heartbeat();
+            }
+            catch {
+                // Presence only. A failure must not change the decision.
+            }
+        }
+        const toolInput = asToolInput(call.input);
+        const sessionId = options.sessionId || call.toolCallId || undefined;
+        if (options.alwaysAllow?.includes(toolName)) {
+            return localAllow();
+        }
+        let tier;
+        try {
+            tier = classify(toolName, toolInput);
+        }
+        catch (err) {
+            log(`Classifier error on ${toolName}: ${err instanceof Error ? err.message : String(err)}`);
+            return deny("error", null, classifierMessage(), "review");
+        }
+        let forceAsk = false;
+        if (options.alwaysApprove?.includes(toolName)) {
+            if (TIER_ORDER[tier] < TIER_ORDER.review)
+                tier = "review";
+            forceAsk = true;
+        }
+        if (!forceAsk && (tier === "safe" || tier === "warning")) {
+            const matched = await rulesWantBackend(client, tier, toolName, toolInput, cwd);
+            if (!matched) {
+                if (tier === "warning") {
+                    log(`WARNING ${toolName} ${summaryOf(toolName, toolInput)} allowed (inside project)`);
+                }
+                return localAllow();
+            }
+            forceAsk = true;
+        }
+        const minTier = resolveMinTier(options);
+        if (!forceAsk && (TIER_ORDER[tier] < TIER_ORDER[minTier] || !APPROVAL_TIERS.has(tier))) {
+            return localAllow();
+        }
+        if (!client.apiKey) {
+            log(`No API key. Denying ${toolName}.`);
+            return deny("error", null, noKeyMessage(), tier);
+        }
+        let fields = describeFields(toolName, toolInput, { cwd }) ?? undefined;
+        const prTitle = await lookupPrTitle(fields);
+        if (prTitle)
+            fields = describeFields(toolName, toolInput, { cwd, prTitle }) ?? undefined;
+        const description = describe(toolName, toolInput, prTitle ? { cwd, prTitle } : { cwd });
+        log(`Requesting approval for ${toolName} (${tier}). Check Telegram or the dashboard.`);
+        const strict = isStrict(options, client);
+        let outcome;
+        try {
+            const result = await client.approve({
+                action: toolName,
+                description,
+                tier,
+                fields,
+                tool_input: toolInput,
+                ...(sessionId ? { session_id: sessionId } : {}),
+                cwd,
+            });
+            outcome = mapApproval(result, tier);
+        }
+        catch (err) {
+            if (err instanceof OKedBackendUnreachableError) {
+                const decision = degradedDecision(tier, { strictFailClosed: strict });
+                if (decision === "allow") {
+                    log(`Backend unreachable. ${toolName} (${tier}) allowed (degraded, non-high-stakes).`);
+                }
+            }
+            outcome = mapError(err, tier, strict);
+        }
+        if (outcome.action === "allow" && outcome.recorded) {
+            log(`${outcome.reason} for ${toolName}`);
+        }
+        else if (outcome.action === "deny") {
+            log(`Blocking ${toolName}: ${outcome.reason}`);
+        }
+        return outcome;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import type { OkedAiOptions, OkedDenial, OkedSingleToolApproval, OkedToolApprovalFunction, ToolExecute } from "./types.js";
+import type { RiskTier } from "@oked/sdk";
+export type { OkedAiOptions, OkedDenial, OkedGateClient, OkedGateResult, OkedSingleToolApproval, OkedToolApprovalArgs, OkedToolApprovalFunction, OkedToolApprovalResult, OkedToolCall, } from "./types.js";
+export type { RiskTier } from "@oked/sdk";
+/**
+ * Thrown when a wrapped tool has an `outputSchema` and the call is denied.
+ * The AI SDK turns the error into a tool error, so the schema does not
+ * replace the reason with a validation failure. `message` is the reason
+ * the model should read.
+ */
+export declare class OkedDeniedError extends Error {
+    readonly oked: "denied";
+    readonly decision: OkedDenial["decision"];
+    readonly approvalId: string | null;
+    readonly reason: string;
+    readonly tier: RiskTier;
+    constructor(denial: OkedDenial);
+}
+export declare function isOkedDenial(value: unknown): value is OkedDenial;
+/**
+ * `toolApproval` callback for every tool on a `generateText`, `streamText`,
+ * or `ToolLoopAgent` call.
+ *
+ * ```ts
+ * await generateText({
+ *   model,
+ *   tools,
+ *   toolApproval: okedToolApproval(),
+ *   prompt,
+ * });
+ * ```
+ *
+ * A sensitive call waits for a person. Approve returns `{ type: "approved" }`
+ * and the AI SDK runs `execute`. Deny or timeout returns `{ type: "denied", reason }`
+ * and `execute` does not run. `safe` and `warning` return `undefined` so the
+ * tool runs with no approval metadata, unless a rule or `alwaysApprove` says
+ * otherwise.
+ */
+export declare function okedToolApproval(options?: OkedAiOptions): OkedToolApprovalFunction;
+/**
+ * Per-tool `toolApproval` entry. Tools you leave off the map are not gated.
+ * Prefer {@link okedToolApproval} so every tool is classified.
+ *
+ * ```ts
+ * toolApproval: { runCommand: okedToolApprovalFor("runCommand") }
+ * ```
+ */
+export declare function okedToolApprovalFor(toolName: string, options?: OkedAiOptions): OkedSingleToolApproval;
+/**
+ * Wrap one tool's `execute`. The original tool is not modified.
+ * `name` is the tool name the model uses (the key in your tools object).
+ *
+ * On approve, `execute` is called with the same input and the same options
+ * object. On deny, timeout, or error, `execute` is not called. The return
+ * value is an {@link OkedDenial} unless the tool defines `outputSchema`, in
+ * which case {@link OkedDeniedError} is thrown so schema validation cannot
+ * hide the reason.
+ */
+export declare function withOked<T extends {
+    execute?: ToolExecute;
+}>(toolDef: T, options: OkedAiOptions & {
+    name: string;
+}): T;
+/**
+ * Wrap every tool in a tools object that has `execute`. Tools without
+ * `execute` are copied through and a log line says they are not gated.
+ * One client is shared across the set.
+ */
+export declare function okedTools<T extends Record<string, {
+    execute?: ToolExecute;
+} | undefined>>(tools: T, options?: OkedAiOptions): T;

package/dist/index.js

@@ -0,0 +1,212 @@
+/**
+ * @oked/ai-sdk. OKed for the Vercel AI SDK.
+ *
+ * AI SDK 7 asks for approval through `toolApproval` on `generateText`,
+ * `streamText`, and `ToolLoopAgent`. `okedToolApproval()` awaits
+ * `OKedClient.approve()` and returns `approved` or `denied` in that same
+ * call. A denial or a timeout is `{ type: "denied", reason }`. The AI SDK
+ * then skips `execute` and shows the reason to the model.
+ *
+ * `user-approval` is intentionally unused. That status ends the generation
+ * and leaves the tool runnable until some later call answers it.
+ *
+ * `withOked` and `okedTools` wrap `execute` for one tool or a tools object.
+ * Use those when the gate has to travel with the tool, or on AI SDK 5 and 6,
+ * which have no `toolApproval`. Do not also set `toolApproval` on a wrapped
+ * tool: the person would be asked twice.
+ *
+ * Denied, timed out, and failed approvals do not run the tool.
+ */
+import { createGate, unexpectedMessage } from "./gate.js";
+const TIERS = new Set(["safe", "warning", "review", "high_stakes"]);
+/**
+ * Thrown when a wrapped tool has an `outputSchema` and the call is denied.
+ * The AI SDK turns the error into a tool error, so the schema does not
+ * replace the reason with a validation failure. `message` is the reason
+ * the model should read.
+ */
+export class OkedDeniedError extends Error {
+    oked = "denied";
+    decision;
+    approvalId;
+    reason;
+    tier;
+    constructor(denial) {
+        super(denial.reason);
+        this.name = "OkedDeniedError";
+        this.decision = denial.decision;
+        this.approvalId = denial.approvalId;
+        this.reason = denial.reason;
+        this.tier = denial.tier;
+    }
+}
+export function isOkedDenial(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return (v.oked === "denied" &&
+        (v.decision === "denied" || v.decision === "timeout" || v.decision === "error") &&
+        typeof v.reason === "string" &&
+        (typeof v.approvalId === "string" || v.approvalId === null) &&
+        typeof v.tier === "string" &&
+        TIERS.has(v.tier));
+}
+function toDenial(result) {
+    return {
+        oked: "denied",
+        decision: result.decision,
+        approvalId: result.approvalId,
+        reason: result.reason,
+        tier: result.tier,
+    };
+}
+/** Map a gate result onto an AI SDK 7 `toolApproval` status. */
+function toToolApprovalStatus(result) {
+    if (result.action === "deny")
+        return { type: "denied", reason: result.reason };
+    if (result.recorded)
+        return { type: "approved", reason: result.reason };
+    return undefined;
+}
+function readInput(toolCall) {
+    if (toolCall.input !== undefined)
+        return toolCall.input;
+    return toolCall.args;
+}
+async function gated(gate, call) {
+    try {
+        return await gate(call);
+    }
+    catch (err) {
+        return {
+            action: "deny",
+            decision: "error",
+            approvalId: null,
+            reason: unexpectedMessage(err),
+            tier: "review",
+        };
+    }
+}
+/**
+ * `toolApproval` callback for every tool on a `generateText`, `streamText`,
+ * or `ToolLoopAgent` call.
+ *
+ * ```ts
+ * await generateText({
+ *   model,
+ *   tools,
+ *   toolApproval: okedToolApproval(),
+ *   prompt,
+ * });
+ * ```
+ *
+ * A sensitive call waits for a person. Approve returns `{ type: "approved" }`
+ * and the AI SDK runs `execute`. Deny or timeout returns `{ type: "denied", reason }`
+ * and `execute` does not run. `safe` and `warning` return `undefined` so the
+ * tool runs with no approval metadata, unless a rule or `alwaysApprove` says
+ * otherwise.
+ */
+export function okedToolApproval(options = {}) {
+    const gate = createGate(options);
+    return async (args = {}) => {
+        const toolCall = args.toolCall;
+        const result = await gated(gate, {
+            toolName: typeof toolCall?.toolName === "string" ? toolCall.toolName : "",
+            input: toolCall ? readInput(toolCall) : undefined,
+            toolCallId: typeof toolCall?.toolCallId === "string" ? toolCall.toolCallId : undefined,
+        });
+        return toToolApprovalStatus(result);
+    };
+}
+/**
+ * Per-tool `toolApproval` entry. Tools you leave off the map are not gated.
+ * Prefer {@link okedToolApproval} so every tool is classified.
+ *
+ * ```ts
+ * toolApproval: { runCommand: okedToolApprovalFor("runCommand") }
+ * ```
+ */
+export function okedToolApprovalFor(toolName, options = {}) {
+    const name = toolName.trim();
+    const gate = createGate(options);
+    return async (input, execOptions) => {
+        const result = await gated(gate, {
+            toolName: name,
+            input,
+            toolCallId: typeof execOptions?.toolCallId === "string" ? execOptions.toolCallId : undefined,
+        });
+        return toToolApprovalStatus(result);
+    };
+}
+function hasOutputSchema(toolDef) {
+    return "outputSchema" in toolDef && toolDef.outputSchema != null;
+}
+function wrapExecute(toolDef, name, gate) {
+    const execute = toolDef.execute;
+    if (typeof execute !== "function") {
+        throw new Error(`OKed: tool "${name}" has no execute function, so a wrapper cannot stop it. ` +
+            "Provider-executed tools are not gated. Use okedToolApproval() for tools the AI SDK executes locally.");
+    }
+    const validateOutput = hasOutputSchema(toolDef);
+    const copy = { ...toolDef };
+    delete copy.needsApproval;
+    copy.execute = async (input, execOptions) => {
+        const toolCallId = execOptions && typeof execOptions === "object"
+            ? execOptions.toolCallId
+            : undefined;
+        const result = await gated(gate, {
+            toolName: name,
+            input,
+            toolCallId: typeof toolCallId === "string" ? toolCallId : undefined,
+        });
+        if (result.action === "allow") {
+            return await execute.call(toolDef, input, execOptions);
+        }
+        const denial = toDenial(result);
+        if (validateOutput)
+            throw new OkedDeniedError(denial);
+        return denial;
+    };
+    return copy;
+}
+/**
+ * Wrap one tool's `execute`. The original tool is not modified.
+ * `name` is the tool name the model uses (the key in your tools object).
+ *
+ * On approve, `execute` is called with the same input and the same options
+ * object. On deny, timeout, or error, `execute` is not called. The return
+ * value is an {@link OkedDenial} unless the tool defines `outputSchema`, in
+ * which case {@link OkedDeniedError} is thrown so schema validation cannot
+ * hide the reason.
+ */
+export function withOked(toolDef, options) {
+    const name = options.name?.trim() ?? "";
+    if (!name)
+        throw new Error("OKed: withOked requires a tool name.");
+    if (!toolDef || typeof toolDef.execute !== "function") {
+        throw new Error(`OKed: tool "${name}" has no execute function, so a wrapper cannot stop it. ` +
+            "Provider-executed tools are not gated. Use okedToolApproval() for tools the AI SDK executes locally.");
+    }
+    return wrapExecute(toolDef, name, createGate(options));
+}
+/**
+ * Wrap every tool in a tools object that has `execute`. Tools without
+ * `execute` are copied through and a log line says they are not gated.
+ * One client is shared across the set.
+ */
+export function okedTools(tools, options = {}) {
+    const gate = createGate(options);
+    const log = options.log ?? ((message) => process.stderr.write(`[OKed] ${message}\n`));
+    const out = {};
+    for (const name of Object.keys(tools)) {
+        const toolDef = tools[name];
+        if (!toolDef || typeof toolDef !== "object" || typeof toolDef.execute !== "function") {
+            log(`tool "${name}" has no execute function, so it is not gated. ` +
+                "Provider-executed tools run on the provider and OKed cannot stop them.");
+            out[name] = toolDef;
+            continue;
+        }
+        out[name] = wrapExecute(toolDef, name, gate);
+    }
+    return out;
+}

package/dist/messages.d.ts

@@ -0,0 +1,14 @@
+export declare function idSuffix(id: string | null | undefined): string;
+export declare function deniedMessage(id: string | null): string;
+export declare function timeoutMessage(id: string | null): string;
+export declare function noKeyMessage(): string;
+export declare function authMessage(): string;
+export declare function receiptMessage(problems: readonly string[]): string;
+export declare function pendingMessage(detail: string): string;
+export declare function httpMessage(status: number, detail: string): string;
+export declare function unreachableMessage(tier: string, why: string): string;
+export declare function unexpectedMessage(err: unknown): string;
+export declare function malformedMessage(): string;
+export declare function classifierMessage(): string;
+export declare function missingNameMessage(): string;
+export declare function approvedMessage(id: string | null): string;

package/dist/messages.js

@@ -0,0 +1,53 @@
+const STOP = "Do NOT retry the same action. Stop and ask the user what to do instead.";
+export function idSuffix(id) {
+    return id ? ` (approval ${id})` : "";
+}
+export function deniedMessage(id) {
+    return `USER DENIED this action via OKed${idSuffix(id)}. This is a final human decision. ${STOP}`;
+}
+export function timeoutMessage(id) {
+    return (`USER did not respond to this action via OKed${idSuffix(id)}. ` +
+        `The approval window expired, so the action was not run. ${STOP}`);
+}
+export function noKeyMessage() {
+    return ("OKed: no API key is configured, so this action was not run. " +
+        "Set OKED_API_KEY, or save an apiKey in ~/.oked/config.json. " +
+        "Create a key from the dashboard at https://oked.ai/dashboard, " +
+        "or run `oked init --key-only` from @oked/claude-code. " +
+        STOP);
+}
+export function authMessage() {
+    return ("OKed: invalid API key (configuration error, not a transient failure). " +
+        STOP);
+}
+export function receiptMessage(problems) {
+    const detail = problems.length > 0 ? problems.join(", ") : "invalid";
+    return (`OKed: the approval receipt did not verify (${detail}), so this action was not run. ` +
+        STOP);
+}
+export function pendingMessage(detail) {
+    return `${detail} ${STOP}`;
+}
+export function httpMessage(status, detail) {
+    const extra = detail ? `: ${detail}` : "";
+    return `OKed: backend error HTTP ${status}${extra} (fail-safe deny). ${STOP}`;
+}
+export function unreachableMessage(tier, why) {
+    return (`OKed backend unreachable. This ${tier} action was not run (${why}, fail-safe). ${STOP}`);
+}
+export function unexpectedMessage(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `OKed: unexpected error (fail-safe deny): ${msg}. ${STOP}`;
+}
+export function malformedMessage() {
+    return `OKed: the approval response was malformed, so this action was not run. ${STOP}`;
+}
+export function classifierMessage() {
+    return `OKed: the classifier failed, so this action was not run (fail-safe deny). ${STOP}`;
+}
+export function missingNameMessage() {
+    return `OKed: the tool call had no name, so it was not run. ${STOP}`;
+}
+export function approvedMessage(id) {
+    return `Approved via OKed${idSuffix(id)}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+import type { ApprovalRequest, ApprovalResponse, RiskTier, Rule } from "@oked/sdk";
+/**
+ * Enough of `OKedClient` for the gate. Pass `new OKedClient()` or a test double.
+ * `apiKey` and `timeoutMs` on {@link OkedAiOptions} apply only when `client` is omitted.
+ */
+export interface OkedGateClient {
+    readonly apiKey: string;
+    readonly strictFailClosed?: boolean;
+    approve(request: ApprovalRequest): Promise<ApprovalResponse>;
+    getRules?(): Promise<Rule[]>;
+    heartbeat?(): Promise<void>;
+}
+export interface OkedAiOptions {
+    /**
+     * Client to call. When omitted, a new `OKedClient` is created from
+     * `OKED_API_KEY` or `~/.oked/config.json`.
+     */
+    client?: OkedGateClient;
+    /** Used only when `client` is omitted. */
+    apiKey?: string;
+    /**
+     * How long to wait for a person, in milliseconds. Used only when `client`
+     * is omitted. Default is the SDK wait, 630 seconds. A timeout denies.
+     */
+    timeoutMs?: number;
+    /**
+     * When true, an unreachable backend denies every sensitive tool. When false,
+     * it denies `high_stakes` only. Overrides `client.strictFailClosed` when set.
+     * Env: `OKED_STRICT_FAIL_CLOSED=1`.
+     */
+    strictFailClosed?: boolean;
+    /**
+     * Lowest tier that waits for a person. Default `review` (env `OKED_MIN_TIER`).
+     * `safe` and `warning` still run locally unless `alwaysApprove` lists the
+     * tool or a saved rule matches.
+     */
+    minTier?: RiskTier;
+    /** Tool names that always wait for a person, whatever the classifier says. */
+    alwaysApprove?: readonly string[];
+    /** Tool names that always run, with no approval request. Wins over `alwaysApprove`. */
+    alwaysAllow?: readonly string[];
+    /** Working directory recorded on the approval. Default `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Receipt session id. When omitted, the AI SDK tool call id is used so
+     * each call can be told apart.
+     */
+    sessionId?: string;
+    /**
+     * Receipt subject source. Default `ai-sdk`. Used only when `client` is omitted.
+     */
+    source?: string;
+    /** Line logger. Default writes `[OKed] ...` to stderr. The message has no prefix. */
+    log?: (message: string) => void;
+}
+/** What the gate decided. Local allows are not recorded as approvals. */
+export type OkedGateResult = {
+    action: "allow";
+    recorded: false;
+} | {
+    action: "allow";
+    recorded: true;
+    reason: string;
+} | {
+    action: "deny";
+    decision: "denied" | "timeout" | "error";
+    approvalId: string | null;
+    reason: string;
+    tier: RiskTier;
+};
+/**
+ * Value returned from a wrapped `execute` when the tool did not run.
+ * `reason` is the text to show the model.
+ */
+export interface OkedDenial {
+    oked: "denied";
+    decision: "denied" | "timeout" | "error";
+    approvalId: string | null;
+    reason: string;
+    tier: RiskTier;
+}
+/**
+ * Subset of an AI SDK tool call. AI SDK 7 uses `input`. `args` is accepted
+ * when `input` is missing.
+ */
+export interface OkedToolCall {
+    toolName: string;
+    input?: unknown;
+    args?: unknown;
+    toolCallId?: string;
+    dynamic?: boolean;
+}
+/**
+ * Arguments of an AI SDK 7 `GenericToolApprovalFunction`. Extra fields the
+ * SDK passes (`tools`, `messages`, `runtimeContext`) are ignored.
+ */
+export interface OkedToolApprovalArgs {
+    toolCall?: OkedToolCall;
+}
+/**
+ * Status object AI SDK 7 accepts from `toolApproval`. This package never
+ * returns `user-approval`: that ends the generation and leaves the tool
+ * runnable on the next call.
+ */
+export type OkedToolApprovalResult = undefined | {
+    type: "approved";
+    reason?: string;
+} | {
+    type: "denied";
+    reason: string;
+};
+export type OkedToolApprovalFunction = (args: OkedToolApprovalArgs) => Promise<OkedToolApprovalResult>;
+/** Per-tool `toolApproval` callback. The tool name is bound by the caller. */
+export type OkedSingleToolApproval = (input: unknown, options?: {
+    toolCallId?: string;
+}) => Promise<OkedToolApprovalResult>;
+export type ToolExecute = (input: unknown, options?: unknown) => unknown;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@oked/ai-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.21",
+  "description": "OKed for the Vercel AI SDK. Risky tool calls wait for a person in Telegram or on the web dashboard before they run.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run build --workspace=@oked/sdk",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test src/gate.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "ai": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@oked/sdk": "0.6.21"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "oked",
+    "ai-agent",
+    "approval",
+    "human-in-the-loop",
+    "hooks",
+    "ai-sdk",
+    "vercel",
+    "tool-calling"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oked-ai/oked-sdk.git",
+    "directory": "packages/ai-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/oked-ai/oked-sdk/issues"
+  },
+  "homepage": "https://oked.ai",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}