agentkey-ai 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentKey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# AgentKey SDK
+
+AgentKey is an authorization and evidence layer for AI agents. Before an agent takes an action, the SDK asks the AgentKey API whether it is allowed, denied, or requires human approval. Both the decision and what the agent actually did are recorded as hash-chained evidence events you can inspect in a dashboard.
+
+## Installation
+
+Python (3.8+, zero dependencies):
+
+```bash
+pip install agentkey
+```
+
+JavaScript / TypeScript (Node 18+, zero dependencies, ESM):
+
+```bash
+npm install agentkey-ai
+```
+
+## Get an API key
+
+1. Sign up at the AgentKey dashboard: https://agentkey.base44.app
+2. Open the Connect wizard (or Agents, then create an agent).
+3. Generate an API key. It is shown once; store it as an environment variable and do not hard-code it.
+
+## First authorization (Python)
+
+```python
+from agentkey import AgentKeyClient
+
+ak = AgentKeyClient(api_key="agent_live_xxxxx")  # production API by default
+
+result = ak.check_permission(action="send_email", resource="gmail", arguments={"to": "x@company.com"})
+if result["allowed"]:
+    send_email(...)  # your code
+else:
+    print("Blocked:", result["reason"], "approval_required:", result.get("approval_required", False))
+```
+
+## First authorization (JavaScript / TypeScript)
+
+```js
+import { AgentKeyClient } from "agentkey-ai";
+
+const ak = new AgentKeyClient({ apiKey: "agent_live_xxxxx" }); // production API by default
+
+const result = await ak.checkPermission({
+  action: "send_email",
+  resource: "gmail",
+  arguments: { to: "x@company.com" },
+});
+if (result.allowed) {
+  await sendEmail(); // your code
+} else {
+  console.log("Blocked:", result.reason, "approval_required:", result.approval_required ?? false);
+}
+```
+
+## Decisions: allow, deny, ask
+
+`check_permission` / `checkPermission` evaluates the permissions you configured for the agent:
+
+- **allow**: `allowed: true`. Run the action, then record the execution (below).
+- **deny**: `allowed: false` with the server's reason. Do not run the action.
+- **ask** (human approval): `allowed: false`, `approval_required: true`. The request appears on the Approvals page in the dashboard, where a human approves or denies it. Do not run the action until it is approved.
+
+Fail-closed: if the service cannot return a valid decision within 5 seconds, the SDK returns:
+
+```json
+{ "allowed": false, "reason": "agentkey_unreachable", "fail_closed": true }
+```
+
+Treat `fail_closed: true` as an infrastructure failure and `allowed: false` without it as an authorization decision. Either way the agent must not proceed.
+
+## wrap(): authorize every tool call in one line
+
+```python
+agent = ak.wrap(my_agent)                   # observe (default): records, blocks nothing
+agent = ak.wrap(my_agent, mode="enforce")   # raises AgentKeyDenied on a denial
+```
+
+```js
+const agent = ak.wrap(myAgent);                    // observe (default)
+const agent = ak.wrap(myAgent, { mode: "enforce" }); // raises AgentKeyDenied on a denial
+```
+
+`wrap()` detects an MCP client (`callTool` / `call_tool`), a LangChain agent or tool list, a plain object or dict of functions, or a single function. Observe mode records every call and blocks nothing, so you can see what AgentKey would have caught before trusting it with enforcement. Enforce mode raises `AgentKeyDenied` and does not run the tool. If no session id is passed, a session is started automatically and ended best-effort at process exit.
+
+## Sessions
+
+Every decision and execution is recorded as an evidence event on the session's hash chain. Group a task into one session:
+
+```python
+s = ak.start_session()
+# ... checks and actions ...
+ak.end_session(s["session_id"])
+```
+
+```js
+const s = await ak.startSession();
+// ... checks and actions ...
+await ak.endSession({ sessionId: s.session_id });
+```
+
+## Recording what the agent actually did
+
+After an allowed action runs, record the execution, linked back to its decision by `authorization_id`:
+
+```python
+auth = ak.check_permission(action="send_email", resource="gmail", session_id=sid)
+if auth["allowed"]:
+    send_email(...)
+    ak.record_action(session_id=sid, authorization_id=auth["event_id"], tool="gmail",
+                     action="send_email", resource="gmail", result_status="success")
+```
+
+`record_action` never refuses to record, so evidence is not lost for billing reasons. Actions that run without any authorization decision are surfaced on the dashboard as findings (`executions_without_authorization`), because the SDK is self-reported: an agent that bypasses the wrapped functions produces no evidence.
+
+## guard(): authorize, run, record in one call
+
+```python
+out = ak.guard(sid, "gmail", "send_email", lambda: send_email(...), arguments={"to": "x@company.com"})
+```
+
+```js
+const out = await ak.guard({ sessionId: sid, resource: "gmail", action: "send_email" }, async () => sendEmail());
+```
+
+If authorize denies, `guard` returns the denial and does not run the function.
+
+## Delegated authorization
+
+A parent agent can delegate a scoped subset of its permissions to a child agent. Scopes are `resource:action` strings, must be a subset of the parent's own permissions, and chains are depth-limited. See `delegate()` in the source docstrings.
+
+## Production API
+
+Base URL: `https://agentkey.base44.app` (the SDK default). Override it with `base_url` (Python) or `baseUrl` (JavaScript) if you self-host.
+
+All endpoints are POST with a Bearer API key, under `/api/functions/`:
+
+- `authorize`
+- `record_action`
+- `start_session`
+- `end_session`
+- `delegate`
+- `validate_api_key` (GET)
+
+Raw HTTP:
+
+```bash
+curl -X POST https://agentkey.base44.app/api/functions/authorize \
+  -H "Authorization: Bearer agent_live_xxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{"action":"send_email","resource":"gmail","arguments":{"to":"x@company.com"}}'
+```
+
+## Dashboard
+
+Sessions, evidence events, approvals, findings and permission settings: https://agentkey.base44.app
+
+## Security limitations (current, accurate)
+
+- Evidence events are hash-chained per session, and session Merkle roots are attested with HMAC-SHA256 under a server-side key. This detects altered or missing events in stored evidence. It is not an asymmetric digital signature scheme, it does not make records forgery-proof against a compromised server, and it is not a non-repudiation guarantee.
+- SDK instrumentation is self-reported. `wrap()` and `record_action` record what the agent reports; an agent that calls tools outside the SDK produces no evidence. This is reported as an `executions_without_authorization` finding, but not prevented.
+- Checks fail closed on network errors and timeouts. In observe mode the SDK still lets the call run; only enforce mode blocks it.
+- No SOC 2 or other third-party compliance audit has been completed.
+
+License: MIT.

package/agentkey.d.ts

@@ -0,0 +1,118 @@
+// Type declarations for the AgentKey JavaScript / TypeScript SDK.
+
+export const DEFAULT_BASE_URL: string;
+
+export class AgentKeyDenied extends Error {
+  constructor(reason?: string, result?: unknown);
+  reason: string;
+  result: unknown;
+}
+
+export interface CheckResult {
+  allowed: boolean;
+  reason: string;
+  request_id: string;
+  session_id?: string;
+  event_id?: string;
+  attempt_id?: string;
+  approval_required?: boolean;
+  fail_closed?: boolean;
+  usage?: { used: number; limit: number };
+  plan?: string;
+  [key: string]: unknown;
+}
+
+export interface DelegateResult {
+  allowed?: boolean;
+  decision?: string;
+  delegation_id?: string;
+  scopes_granted?: string[];
+  depth?: number;
+  expires_at?: string;
+  [key: string]: unknown;
+}
+
+export interface SessionResult {
+  session_id?: string;
+  agent_id?: string;
+  started_at?: string;
+  preceding_scan_id?: string;
+  [key: string]: unknown;
+}
+
+export interface WrapOptions {
+  sessionId?: string;
+  mode?: "observe" | "enforce";
+  scanId?: string;
+}
+
+export interface ClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+export class AgentKeyClient {
+  constructor(options: ClientOptions);
+
+  checkPermission(args: {
+    action: string;
+    resource: string;
+    tool?: string;
+    metadata?: Record<string, unknown>;
+    arguments?: Record<string, unknown>;
+    sessionId?: string;
+    parentEventId?: string;
+    parentAgentId?: string;
+    source?: string;
+    scanId?: string;
+    delegationId?: string;
+  }): Promise<CheckResult>;
+
+  delegate(args: {
+    childAgentId: string;
+    scopes: string[];
+    ttlHours?: number;
+    sessionId?: string;
+    parentDelegationId?: string;
+  }): Promise<DelegateResult>;
+
+  validate(): Promise<{ valid: boolean; reason?: string; fail_closed?: boolean; [key: string]: unknown }>;
+
+  startSession(args?: { metadata?: Record<string, unknown>; scanId?: string }): Promise<SessionResult>;
+
+  endSession(args: { sessionId: string; status?: string }): Promise<Record<string, unknown>>;
+
+  recordAction(args: {
+    sessionId?: string;
+    authorizationId?: string;
+    attemptId?: string;
+    tool?: string;
+    action: string;
+    resource?: string;
+    arguments?: Record<string, unknown>;
+    resultStatus?: string;
+    resultHash?: string;
+    durationMs?: number;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+    scanId?: string;
+  }): Promise<Record<string, unknown>>;
+
+  guard(
+    args: {
+      sessionId?: string;
+      resource: string;
+      action: string;
+      tool?: string;
+      arguments?: Record<string, unknown>;
+      scanId?: string;
+    },
+    fn: () => Promise<unknown>
+  ): Promise<{ allowed: boolean; result?: unknown; authorization?: CheckResult; reason?: string }>;
+
+  wrap(target: unknown, options?: WrapOptions): unknown;
+
+  _hashResult(result: unknown): Promise<string>;
+}
+
+export default AgentKeyClient;

package/agentkey.js

@@ -0,0 +1,372 @@
+// AgentKey — minimal JavaScript / TypeScript SDK.
+// Zero dependencies. Works in Node 18+ and modern browsers (global fetch).
+//
+// One-line install: wrap an existing agent and AgentKey records every tool call
+// as paired authorization + execution evidence — no call-site changes.
+//
+//   import { AgentKeyClient } from "./agentkey.js";
+//   const ak = new AgentKeyClient({ apiKey: "agent_live_xxxxx" });   // baseUrl defaults to the production API
+//   const agent = ak.wrap(myAgent);            // observe mode (default): records, blocks nothing
+//   // ak.wrap(myAgent, { mode: "enforce" });   // enforce mode: raises AgentKeyDenied on a denial
+//
+// Fail-closed: if the AgentKey service cannot return a valid decision within
+// 5 seconds (network error, timeout, non-JSON body, or a response missing the
+// `allowed` field), every check returns { allowed: false, reason:
+// "agentkey_unreachable", fail_closed: true } so an agent never proceeds on a
+// missing or ambiguous decision.
+
+const FAIL_CLOSED = { allowed: false, reason: "agentkey_unreachable", fail_closed: true };
+const TIMEOUT_MS = 5000;
+
+// Production API. Override with baseUrl only if you self-host.
+export const DEFAULT_BASE_URL = "https://agentkey.base44.app";
+const USER_AGENT = "agentkey-js-sdk/1.0.0";
+
+// Process-wide flag so the first-run info block prints once per process.
+let _wrapFirstRunPrinted = false;
+
+export class AgentKeyDenied extends Error {
+  constructor(reason, result) {
+    super(reason || "denied by AgentKey policy");
+    this.name = "AgentKeyDenied";
+    this.result = result || null;
+  }
+}
+
+export class AgentKeyClient {
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
+    if (!apiKey) throw new Error("AgentKey: apiKey is required");
+    this.apiKey = apiKey;
+    this.baseUrl = String(baseUrl).replace(/\/$/, "");
+  }
+
+  async _post(path, body, extraHeaders = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT, ...extraHeaders },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      const data = await res.json().catch(() => null);
+      if (!data || typeof data.allowed !== "boolean") return { ...FAIL_CLOSED };
+      return data;
+    } catch (e) {
+      return { ...FAIL_CLOSED };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async _postJson(path, body, extraHeaders = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT, ...extraHeaders },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      const data = await res.json().catch(() => null);
+      return data || { error: "agentkey_unreachable" };
+    } catch (e) {
+      return { error: "agentkey_unreachable" };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /** Evaluate a permission. Returns { allowed, reason, request_id, session_id,
+   *  event_id, usage, plan }. Pass sessionId/parentEventId/parentAgentId to
+   *  thread the decision into an evidence session and record it on the agent's
+   *  hash chain. Fails closed (allowed: false) on any error or timeout. */
+  async checkPermission({ action, resource, tool, metadata = {}, arguments: args, sessionId, parentEventId, parentAgentId, source, scanId, delegationId }) {
+    if (!action || !resource) throw new Error("AgentKey: action and resource are required");
+    return this._post(
+      "/api/functions/authorize",
+      { action, resource, tool, metadata, arguments: args, session_id: sessionId, parent_event_id: parentEventId, parent_agent_id: parentAgentId, source, input_scan_id: scanId, delegation_id: delegationId },
+      { Authorization: `Bearer ${this.apiKey}` }
+    );
+  }
+
+  /** Delegated authorization: delegate a scoped subset of THIS agent's
+   *  authority (the caller of this method is the PARENT agent) to a child
+   *  agent. Scopes are "resource:action" strings and must be a subset of the
+   *  parent's own permissions — anything broader is blocked server-side
+   *  (scope escalation prevention). Returns
+   *  { allowed, decision, delegation_id, scopes_granted, depth, expires_at }.
+   *  The delegation_id is runtime-minted: the caller can neither choose nor
+   *  reset it. The child then presents delegationId to checkPermission() to
+   *  act under the delegation. Fail-closed. */
+  async delegate({ childAgentId, scopes, ttlHours, sessionId, parentDelegationId }) {
+    if (!childAgentId || !Array.isArray(scopes) || scopes.length === 0) {
+      throw new Error("AgentKey: childAgentId and a non-empty scopes array are required");
+    }
+    return this._postJson(
+      "/api/functions/delegate",
+      {
+        child_agent_id: childAgentId,
+        scopes,
+        ttl_hours: ttlHours,
+        session_id: sessionId,
+        parent_delegation_id: parentDelegationId,
+      },
+      { Authorization: `Bearer ${this.apiKey}` }
+    );
+  }
+
+  /** Validate the key is active. Returns { valid, message, agent_id, agent_name }. */
+  async validate() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const res = await fetch(`${this.baseUrl}/api/functions/validate_api_key`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal,
+      });
+      const data = await res.json().catch(() => null);
+      if (!data || typeof data.valid !== "boolean") {
+        return { valid: false, reason: "agentkey_unreachable", fail_closed: true };
+      }
+      return data;
+    } catch (e) {
+      return { valid: false, reason: "agentkey_unreachable", fail_closed: true };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /** Start an evidence session rooted at this agent's key.
+   *  Returns { session_id, agent_id, started_at }. */
+  /** Start an evidence session rooted at this agent's key. Pass scanId to
+   *  attach an input scan once at the start of a task; it is inherited by every
+   *  decision in the session unless overridden per call. Returns { session_id,
+   *  agent_id, started_at, preceding_scan_id }. */
+  async startSession({ metadata, scanId } = {}) {
+    return this._postJson("/api/functions/start_session", { metadata, scan_id: scanId }, { Authorization: `Bearer ${this.apiKey}` });
+  }
+
+  /** End an evidence session. Returns { session_id, status, event_count }.
+   *  Pass status: "failed" to mark a failed session. */
+  async endSession({ sessionId, status } = {}) {
+    return this._postJson("/api/functions/end_session", { session_id: sessionId, status }, { Authorization: `Bearer ${this.apiKey}` });
+  }
+
+  /** Record what an agent ACTUALLY did, as an execution event on the same hash
+   *  chain as the decision that permitted it. Pass the `event_id` returned by
+   *  checkPermission as authorizationId to link the execution to its decision.
+   *  Self-reported: an agent that does not call it produces no execution
+   *  evidence — which is exactly why executions_without_authorization is
+   *  reported. `metadata` is sanitized to primitives before storage (used by
+   *  wrap() to mark would_block in observe mode). */
+  async recordAction({ sessionId, authorizationId, attemptId, tool, action, resource, arguments: args, resultStatus, resultHash, durationMs, errorMessage, metadata, scanId }) {
+    return this._postJson("/api/functions/record_action", {
+      session_id: sessionId, authorization_id: authorizationId, attempt_id: attemptId, tool, action, resource, arguments: args,
+      result_status: resultStatus, result_hash: resultHash, duration_ms: durationMs, error_message: errorMessage,
+      metadata, input_scan_id: scanId,
+    }, { Authorization: `Bearer ${this.apiKey}` });
+  }
+
+  async _sha256(text) {
+    try {
+      const data = new TextEncoder().encode(String(text));
+      const buf = await crypto.subtle.digest("SHA-256", data);
+      return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+    } catch (e) { return ""; }
+  }
+
+  async _hashResult(result) {
+    try { return await this._sha256(JSON.stringify(result)); } catch (e) { return ""; }
+  }
+
+  /** Convenience wrapper: authorize, run `fn` if allowed, then record the
+   *  execution linked to that decision and hashed against the result. */
+  async guard({ sessionId, resource, action, tool, arguments: args, scanId }, fn) {
+    const auth = await this.checkPermission({ action, resource, tool, arguments: args, sessionId, scanId });
+    if (!auth || !auth.allowed) return auth;
+    const t0 = Date.now();
+    try {
+      const result = await fn();
+      const durationMs = Date.now() - t0;
+      try {
+        const resultHash = await this._hashResult(result);
+        await this.recordAction({ sessionId, authorizationId: auth.event_id, attemptId: auth.attempt_id, tool, action, resource, arguments: args, resultStatus: "success", resultHash, durationMs, scanId });
+      } catch (e) {}
+      return { allowed: true, result, authorization: auth };
+    } catch (e) {
+      const durationMs = Date.now() - t0;
+      try {
+        await this.recordAction({ sessionId, authorizationId: auth.event_id, attemptId: auth.attempt_id, tool, action, resource, arguments: args, resultStatus: "error", errorMessage: String(e && e.message ? e.message : e).slice(0, 200), durationMs, scanId });
+      } catch (recErr) {}
+      throw e;
+    }
+  }
+
+  /** One-line auto-instrumentation. Wraps an existing agent — an MCP client
+   *  (callTool), a LangChain agent or tool list (tools[].invoke/run/_call), a
+   *  plain object of functions, or a single function — so every tool call is
+   *  authorized and recorded without changing any call site.
+   *
+   *  mode: "observe" (default) records everything and blocks nothing; a denial
+   *  is logged ("AgentKey would have blocked this: <reason>") and the call still
+   *  runs, recorded with would_block: true. mode: "enforce" raises
+   *  AgentKeyDenied on a denial and does NOT run the tool.
+   *
+   *  If no sessionId is given, a session is started automatically and ended
+   *  best-effort on process exit (never throws on shutdown). Wrapped functions
+   *  preserve the original name and return value — a wrapped agent behaves
+   *  identically when everything is allowed.
+   *
+   *  wrap() is still self-reported: an agent that bypasses the wrapped
+   *  functions produces no evidence, which is exactly why
+   *  executions_without_authorization is reported. */
+  /** One-line auto-instrumentation (see above). Pass scanId to attach an input
+   *  scan to the auto-started session so every wrapped tool call inherits it. */
+  wrap(target, { sessionId, mode = "observe", scanId } = {}) {
+    return _wrapTarget(this, target, { sessionId, mode, scanId });
+  }
+}
+
+// --- wrap() internals ---------------------------------------------------------
+
+function _deriveName(t, fallback) {
+  if (t && typeof t.name === "string" && t.name) return t.name;
+  return fallback;
+}
+
+function _getInvoke(tool) {
+  if (typeof tool.invoke === "function") return { fn: tool.invoke.bind(tool), key: "invoke" };
+  if (typeof tool.run === "function") return { fn: tool.run.bind(tool), key: "run" };
+  if (typeof tool._call === "function") return { fn: tool._call.bind(tool), key: "_call" };
+  if (typeof tool === "function") return { fn: tool, key: null };
+  return null;
+}
+
+function _discover(target) {
+  if (target && typeof target.callTool === "function") {
+    return [{ name: "call_tool", host: target, inv: { fn: target.callTool.bind(target), key: "callTool" }, kind: "mcp" }];
+  }
+  if (Array.isArray(target)) {
+    return target.map((t, i) => ({ name: _deriveName(t, `tool_${i}`), host: t, inv: _getInvoke(t), kind: "list" }));
+  }
+  if (target && Array.isArray(target.tools)) {
+    return target.tools.map((t, i) => ({ name: _deriveName(t, `tool_${i}`), host: t, inv: _getInvoke(t), kind: "langchain" }));
+  }
+  if (target && typeof target === "object") {
+    return Object.entries(target)
+      .filter(([, v]) => typeof v === "function")
+      .map(([name, fn]) => ({ name, host: target, inv: { fn: fn.bind(target), key: null }, kind: "dict" }));
+  }
+  if (typeof target === "function") {
+    return [{ name: _deriveName(target, "anonymous"), host: target, inv: { fn: target, key: null }, kind: "fn" }];
+  }
+  return [];
+}
+
+function _argsToObject(args) {
+  const a = args[0];
+  return a && typeof a === "object" && !Array.isArray(a) && a !== null ? a : {};
+}
+
+function _wrapTarget(client, target, { sessionId, mode = "observe", scanId } = {}) {
+  const enforce = mode === "enforce";
+  const tools = _discover(target);
+  const auto = !sessionId;
+  const state = { sessionId: sessionId || null, booted: false, ended: false };
+
+  function _printFirstRun() {
+    if (_wrapFirstRunPrinted) return;
+    _wrapFirstRunPrinted = true;
+    const url = `${client.baseUrl}/sessions/${state.sessionId || ""}`;
+    try {
+      console.error(`AgentKey: session=${state.sessionId || "?"} tools=${tools.length} mode=${enforce ? "enforce" : "observe"} dashboard=${url}`);
+    } catch (e) {}
+  }
+
+  async function boot() {
+    if (state.booted) return;
+    state.booted = true;
+    if (!state.sessionId) {
+      try { const s = await client.startSession({ scanId }); state.sessionId = (s && s.session_id) || null; } catch (e) { state.sessionId = null; }
+    }
+    _printFirstRun();
+    if (auto && typeof process !== "undefined" && process && typeof process.on === "function") {
+      try {
+        process.on("beforeExit", async () => {
+          if (state.ended || !state.sessionId) return;
+          state.ended = true;
+          try { await client.endSession({ sessionId: state.sessionId }); } catch (e) {}
+        });
+      } catch (e) {}
+    }
+  }
+
+  function makeWrapped(name, originalFn) {
+    const wrapped = async function (...args) {
+      await boot();
+      const sid = state.sessionId;
+      const argumentsObj = _argsToObject(args);
+      let auth;
+      try {
+        auth = await client.checkPermission({ action: "invoke", resource: name, arguments: argumentsObj, sessionId: sid });
+      } catch (e) {
+        auth = { allowed: false, reason: "agentkey_unreachable", fail_closed: true };
+      }
+      const allowed = !!auth && auth.allowed === true;
+      if (!allowed && enforce) {
+        throw new AgentKeyDenied(auth && auth.reason ? auth.reason : "denied", auth);
+      }
+      if (!allowed && !enforce) {
+        try { console.error(`AgentKey would have blocked this: ${auth && auth.reason ? auth.reason : "denied"}`); } catch (e) {}
+      }
+      const t0 = Date.now();
+      const meta = !allowed ? { would_block: true } : undefined;
+      try {
+        const result = await originalFn.apply(this, args);
+        try {
+          const resultHash = await client._hashResult(result);
+          await client.recordAction({
+            sessionId: sid, authorizationId: auth && auth.event_id, attemptId: auth && auth.attempt_id, tool: name, action: "invoke", resource: name,
+            arguments: argumentsObj, resultStatus: "success", resultHash, durationMs: Date.now() - t0, metadata: meta,
+          });
+        } catch (e) {}
+        return result;
+      } catch (e) {
+        try {
+          await client.recordAction({
+            sessionId: sid, authorizationId: auth && auth.event_id, attemptId: auth && auth.attempt_id, tool: name, action: "invoke", resource: name,
+            arguments: argumentsObj, resultStatus: "error", errorMessage: String(e && e.message ? e.message : e).slice(0, 200),
+            durationMs: Date.now() - t0, metadata: meta,
+          });
+        } catch (recErr) {}
+        throw e;
+      }
+    };
+    try { Object.defineProperty(wrapped, "name", { value: (originalFn && originalFn.name) || name, configurable: true }); } catch (e) {}
+    return wrapped;
+  }
+
+  // Build the wrapped target, preserving the original shape.
+  if (tools.length === 0) return target;
+
+  const kinds = new Set(tools.map((t) => t.kind));
+  if (kinds.has("dict") || kinds.has("fn")) {
+    if (tools[0].kind === "fn") return makeWrapped(tools[0].name, tools[0].inv.fn);
+    const out = {};
+    for (const t of tools) out[t.name] = makeWrapped(t.name, t.inv.fn);
+    return out;
+  }
+  // list / langchain / mcp: mutate each tool's method in place so an agent that
+  // calls its own tools internally still routes through the wrapper.
+  for (const t of tools) {
+    if (!t.inv) continue;
+    const w = makeWrapped(t.name, t.inv.fn);
+    try { t.host[t.inv.key] = w; } catch (e) {}
+  }
+  return target;
+}
+
+export default AgentKeyClient;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "agentkey-ai",
+  "version": "1.0.0",
+  "description": "Authorization and evidence SDK for AI agents: check permissions before every action, record what agents actually did.",
+  "type": "module",
+  "main": "./agentkey.js",
+  "types": "./agentkey.d.ts",
+  "exports": {
+    ".": {
+      "types": "./agentkey.d.ts",
+      "default": "./agentkey.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "agentkey.js",
+    "agentkey.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "authorization",
+    "permissions",
+    "audit",
+    "mcp",
+    "security",
+    "llm"
+  ],
+  "license": "MIT",
+  "homepage": "https://agentkey.base44.app"
+}