@keemakr/agent-sdk 0.6.0 → 0.8.0

package/README.md

@@ -19,11 +19,11 @@ Peer dependencies (match your eve agent): `eve@0.13.0`, `jose@^6.2.3`.
 
 Set these in your deployed agent's environment:
 
-| Variable | Purpose |
-|---|---|
-| `KEE_CORE_JWKS_URL` | keemakr-core's JWKS endpoint, e.g. `https://app.keemakr.com/.well-known/jwks.json`. Enables grant verification. |
+| Variable             | Purpose                                                                                                                                  |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `KEE_CORE_JWKS_URL`  | keemakr-core's JWKS endpoint, e.g. `https://app.keemakr.com/.well-known/jwks.json`. Enables grant verification.                          |
 | `KEE_AGENT_AUDIENCE` | This deployment's audience — your runtime URL's origin, e.g. `https://my-agent.example.com`. Must match the audience the operator mints. |
-| `KEE_CORE_URL` | keemakr-core's base URL for capability calls, e.g. `https://app.keemakr.com`. (Derived from `KEE_CORE_JWKS_URL` if unset.) |
+| `KEE_CORE_URL`       | keemakr-core's base URL for capability calls, e.g. `https://app.keemakr.com`. (Derived from `KEE_CORE_JWKS_URL` if unset.)               |
 
 If `KEE_CORE_JWKS_URL` is unset, `grantAuth()` skips entirely — useful during local development.
 
@@ -32,9 +32,9 @@ If `KEE_CORE_JWKS_URL` is unset, `grantAuth()` skips entirely — useful during
 `grantAuth()` returns an eve `AuthFn`. Put it ahead of any fallback:
 
 ```ts title="agent/channels/eve.ts"
-import { localDev, vercelOidc } from "eve/channels/auth";
-import { eveChannel } from "eve/channels/eve";
-import { grantAuth } from "@keemakr/agent-sdk";
+import { localDev, vercelOidc } from 'eve/channels/auth';
+import { eveChannel } from 'eve/channels/eve';
+import { grantAuth } from '@keemakr/agent-sdk';
 
 export default eveChannel({
   auth: [localDev(), vercelOidc(), grantAuth()],
@@ -46,9 +46,9 @@ On success the verified tenant id and scopes are attached to the session auth co
 ## 2. Reach tenant data from a tool
 
 ```ts title="agent/tools/find_email.ts"
-import { defineTool } from "eve/tools";
-import { z } from "zod";
-import { useKee } from "@keemakr/agent-sdk";
+import { defineTool } from 'eve/tools';
+import { z } from 'zod';
+import { useKee } from '@keemakr/agent-sdk';
 
 export default defineTool({
   description: "Find a lead's work email.",
@@ -60,7 +60,7 @@ export default defineTool({
   async execute(args, ctx) {
     const kee = useKee(ctx);
     // Proxy path: the credential stays in keemakr-core; you get the result.
-    const result = await kee.connections.hunter.call("email-finder", args);
+    const result = await kee.connections.hunter.call('email-finder', args);
     return result; // { email, score, status }
   },
 });
@@ -87,12 +87,12 @@ const { access_token } = await kee.connections.hunter.token();
 `@keemakr/agent-sdk/connectors` ships a generated, typed manifest of every connector keemakr-core exposes — provider slugs, `maturity`, and each operation's name + JSON-Schema arg contract. Use it to discover what's callable (and get autocomplete on provider + op names) **without** scanning a core checkout or hitting a running instance. It's **metadata only** — no credentials.
 
 ```ts
-import { connectors, opNames, isReady } from "@keemakr/agent-sdk/connectors";
+import { connectors, opNames, isReady } from '@keemakr/agent-sdk/connectors';
 
-opNames("hunter");                                  // → ["email-finder"]
-connectors.hunter.ops["email-finder"].inputSchema;  // JSON Schema for the args
-isReady("meta");                                     // false while a connector is coming_soon
-connectors.meta.maturity;                            // "coming_soon" | "ready"
+opNames('hunter'); // → ["email-finder"]
+connectors.hunter.ops['email-finder'].inputSchema; // JSON Schema for the args
+isReady('meta'); // false while a connector is coming_soon
+connectors.meta.maturity; // "coming_soon" | "ready"
 ```
 
 A `coming_soon` connector is declarable in your `entry.json` `dependencies` today; its operations start callable (and `isReady` flips to `true`) once core ships them — **no change to your agent**.
@@ -107,33 +107,83 @@ npm run gen:connectors    # or: npm run build (runs gen first)
 ### Memory (cross-session, tenant-shared)
 
 ```ts
-await kee.memory.set("prefs", "tone", { tone: "formal" });
-await kee.memory.get("prefs", "tone");          // → { tone: "formal" }
-await kee.memory.list("prefs");                  // → entries in the namespace
-await kee.memory.delete("prefs", "tone");
+await kee.memory.set('prefs', 'tone', { tone: 'formal' });
+await kee.memory.get('prefs', 'tone'); // → { tone: "formal" }
+await kee.memory.list('prefs'); // → entries in the namespace
+await kee.memory.delete('prefs', 'tone');
 // Semantic search by meaning (embeddings):
-const hits = await kee.memory.search("how should I speak to the user?", { limit: 5 });
+const hits = await kee.memory.search('how should I speak to the user?', { limit: 5 });
 // → [{ namespace, key, value, score, … }]  (score 0–1, nearest first)
 ```
 
+Memory is tenant-shared: any of the tenant's installed agents can read/write any
+namespace. Concurrent writers should take turns — every entry carries a
+monotonic `version`, and conditional writes lose gracefully instead of
+clobbering:
+
+```ts
+const entry = await kee.memory.getEntry('crm', 'lead:acme'); // { value, version, … }
+try {
+  await kee.memory.set('crm', 'lead:acme', next, { ifVersion: entry!.version });
+} catch (e) {
+  if (e instanceof MemoryConflictError) {
+    // someone wrote first — e.current is the winning entry; re-read, re-derive, retry
+  }
+}
+// Or merge one field with no read at all (object values only):
+await kee.memory.patch('crm', 'lead:acme', { status: 'contacted' });
+```
+
+Use memory for your agent's own continuity (preferences, cursors, entity
+state) — durable documents belong in the tenant knowledge base, which you read
+via `kee.kb`.
+
+### Knowledge base (read-only retrieval)
+
+```ts
+const hits = await kee.kb.search('what is our refund policy?', { k: 5 });
+// → [{ text, score, provenance: { title, source_uri, … } }]
+```
+
+Scoped server-side to the collections bound to your agent + the tenant's
+default corpus + the shared platform KB (`kb:retrieve` scope, granted to every
+install). Hybrid retrieval, reranked in core; `text` may be a wider parent
+context for clause-level documents.
+
 ### Platform tools
 
 ```ts
-await kee.tools.list();                 // tools this grant is entitled to
-await kee.tools.run("current-time");    // run one in keemakr-core
+await kee.tools.list(); // tools this grant is entitled to
+await kee.tools.run('current-time'); // run one in keemakr-core
 ```
 
 A call whose grant lacks the required scope returns a `KeeError` with `status: 403`; an expired/invalid grant returns `status: 401`.
 
+## Grant refresh (automatic since 0.8.0)
+
+Every `useKee` capability call keeps its grant alive by itself: when the active token has under two minutes left, the SDK exchanges it at core's `POST /api/capability/grant/refresh` (single-flight per delegation — concurrent tool calls share one refresh), and a `401 grant_expired` gets one refresh + one retry before surfacing. You write nothing; long runs simply stop dying at the TTL.
+
+The floor is core's, not the SDK's: an **expired** grant can never be refreshed, scopes are re-derived from the install at each exchange, and the whole chain dies at the renewal horizon (`CAPABILITY_GRANT_MAX_LIFETIME_SECONDS` on core, default 6h) with a relayable `grant_horizon_exceeded` error.
+
+Headless callers holding a raw grant can drive the exchange directly:
+
+```ts
+import { refreshGrant } from '@keemakr/agent-sdk';
+
+const { token, exp } = await refreshGrant(currentToken); // throws KeeError when core refuses
+```
+
+`refreshGrant` resolves core from `KEE_CORE_URL` / `KEE_CORE_JWKS_URL` (pass `{ coreUrl }` to override) and never verifies or signs anything locally — core is the only judge.
+
 ## Autonomous / scheduled runs
 
 A cron/scheduled turn has no operator session, so it gets no session grant. keemakr-core can mint a **machine grant** for it (gated on the tenant's per-install `unattended_consent`). If your remote runs **outside** an eve channel, verify that grant directly:
 
 ```ts
-import { verifyGrant } from "@keemakr/agent-sdk";
+import { verifyGrant } from '@keemakr/agent-sdk';
 
 const claims = await verifyGrant(grantToken, { audience: process.env.KEE_AGENT_AUDIENCE });
-if (!claims) throw new Error("invalid or expired grant");
+if (!claims) throw new Error('invalid or expired grant');
 // claims.tenantId, claims.scopes, claims.aud, claims.exp
 ```
 
@@ -143,7 +193,7 @@ Inside an eve channel, `grantAuth()` already accepts machine grants (same token
 
 - **Tenant/service credentials live in keemakr-core**, reached only via the proxy — the credential never crosses the wire. Tenant is always the verified grant, resolved server-side; never pass a tenant id from tool input.
 - **The token path is opt-in and scope-gated** (`conn:<provider>:token`), declared per dependency in `entry.json` (`"access": "token"`).
-- **You MAY hold your own model key.** There is no platform model gateway today, so an agent routing its own LLM calls (its own Anthropic/AI-Gateway key) is expected and fine — that is *not* a credential leak. A leak is a *tenant/service* credential read in agent code.
+- **You MAY hold your own model key.** There is no platform model gateway today, so an agent routing its own LLM calls (its own Anthropic/AI-Gateway key) is expected and fine — that is _not_ a credential leak. A leak is a _tenant/service_ credential read in agent code.
 - Every capability call re-verifies the grant and enforces scope on the server.
 
 Full contract: keemakr-core `docs/CONNECTOR-CONTRACT.md`.

package/dist/client.d.ts

@@ -1,5 +1,17 @@
 export interface KeeError extends Error {
     status?: number;
+    /** Parsed error-response body, when core sent one (e.g. the conflicting entry on 409). */
+    body?: unknown;
+}
+/**
+ * A conditional memory write (`ifVersion`) lost the race — another agent wrote
+ * the key first. `current` is the entry as it now stands (null when the key was
+ * deleted concurrently). Re-read, re-derive, retry.
+ */
+export declare class MemoryConflictError extends Error {
+    status: 409;
+    current: MemoryEntry | null;
+    constructor(current: MemoryEntry | null);
 }
 export interface KeeContext {
     session?: {
@@ -26,6 +38,8 @@ export interface MemoryEntry {
     key: string;
     value: unknown;
     written_by_agent: string | null;
+    /** Monotonic write counter — pass as `ifVersion` for compare-and-swap writes. */
+    version: number;
     created_at: string;
     updated_at: string;
 }
@@ -43,10 +57,25 @@ export interface MemorySearchHit extends MemoryEntry {
 export interface KeeMemory {
     /** Read a key's value, or null if absent. */
     get(namespace: string, key: string): Promise<unknown | null>;
-    /** Read the full entry (value + provenance + timestamps), or null. */
+    /** Read the full entry (value + provenance + version + timestamps), or null. */
     getEntry(namespace: string, key: string): Promise<MemoryEntry | null>;
-    /** Write a key. Returns the stored entry. */
-    set(namespace: string, key: string, value: unknown): Promise<MemoryEntry>;
+    /**
+     * Write a key. Returns the stored entry. Pass `ifVersion` (from a prior
+     * getEntry) to make it a compare-and-swap: throws MemoryConflictError when
+     * another agent wrote the key in between.
+     */
+    set(namespace: string, key: string, value: unknown, opts?: {
+        ifVersion?: number;
+    }): Promise<MemoryEntry>;
+    /**
+     * Shallow-merge `delta` into an existing object value without reading it
+     * first — safe under concurrency for the "add one field" case. Throws
+     * MemoryConflictError on an `ifVersion` mismatch; a KeeError with status 404
+     * when the key is absent, 422 when the stored value isn't an object.
+     */
+    patch(namespace: string, key: string, delta: Record<string, unknown>, opts?: {
+        ifVersion?: number;
+    }): Promise<MemoryEntry>;
     /** Delete a key. Returns whether it existed. */
     delete(namespace: string, key: string): Promise<boolean>;
     /** List every entry in a namespace (tenant-wide). */
@@ -57,6 +86,26 @@ export interface KeeMemory {
         limit?: number;
     }): Promise<MemorySearchHit[]>;
 }
+/** One KB retrieval hit. `text` is the chunk (or its parent context for
+ *  parent-child-chunked documents); `score` is the reranker's relevance when
+ *  reranking ran, else the RRF fusion score. */
+export interface KBHit {
+    text: string;
+    score: number;
+    provenance: Record<string, unknown>;
+}
+/**
+ * Tenant knowledge-base retrieval. The agent sees the collections bound to it
+ * plus the tenant's default corpus plus the shared platform KB — scoping is
+ * enforced server-side from the grant. Requires the `kb:retrieve` scope
+ * (granted to every install).
+ */
+export interface KeeKb {
+    /** Semantic + lexical + reranked search over the agent-visible knowledge. */
+    search(query: string, opts?: {
+        k?: number;
+    }): Promise<KBHit[]>;
+}
 /** Platform registry tools (Shape B) — defined in core, run server-side. */
 export interface KeeTools {
     /** List the registry tools this grant is entitled to. */
@@ -76,6 +125,7 @@ export interface Kee {
         get(provider: string): KeeConnection;
     };
     memory: KeeMemory;
+    kb: KeeKb;
     tools: KeeTools;
 }
 /**

package/dist/client.js

@@ -4,12 +4,33 @@
 // /api/capability/* endpoints, forwarding the grant. Core re-verifies the grant
 // and enforces scope on every call; the SDK never sees a raw credential on the
 // proxy path.
-function keeError(message, status) {
+//
+// Since 0.8.0 every capability call keeps its grant ALIVE transparently: the
+// token is refreshed shortly before expiry (see refresh.ts), and a 401
+// `grant_expired` gets one refresh + one retry before surfacing. Long runs stop
+// dying mid-flight; the ceiling is core's renewal horizon (default 6h).
+import { ensureFreshToken, tokenForRetry, coreBaseUrl } from './refresh.js';
+function keeError(message, status, body) {
     const e = new Error(message);
     e.name = 'KeeError';
     e.status = status;
+    e.body = body;
     return e;
 }
+/**
+ * A conditional memory write (`ifVersion`) lost the race — another agent wrote
+ * the key first. `current` is the entry as it now stands (null when the key was
+ * deleted concurrently). Re-read, re-derive, retry.
+ */
+export class MemoryConflictError extends Error {
+    status = 409;
+    current;
+    constructor(current) {
+        super('memory version conflict — the key changed since it was read');
+        this.name = 'MemoryConflictError';
+        this.current = current;
+    }
+}
 function readGrant(ctx) {
     const attrs = ctx?.session?.auth?.current?.attributes ?? {};
     const token = typeof attrs.grant_token === 'string' ? attrs.grant_token : undefined;
@@ -21,32 +42,69 @@ function readGrant(ctx) {
     }
     return { token, tenantId, scopes, traceId };
 }
-// Resolve core's base URL. Prefer KEE_CORE_URL; otherwise derive it from the
-// JWKS URL by stripping the well-known path.
-function coreBaseUrl() {
-    const explicit = process.env.KEE_CORE_URL;
-    if (explicit)
-        return explicit.replace(/\/$/, '');
-    const jwks = process.env.KEE_CORE_JWKS_URL;
-    if (jwks)
-        return jwks.replace(/\/\.well-known\/jwks\.json\/?$/, '');
-    throw keeError('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API');
+// A 401 from core surfaces INSIDE the remote agent's run as a failed tool, and
+// the only audience there is the remote's model — so the message must carry
+// remediation the model can relay verbatim instead of improvising around it.
+// Branches on core's typed `code` when present; the /expired/ text test remains
+// the fallback for older cores' undifferentiated 'invalid or expired grant'.
+function with401Guidance(base, code) {
+    if (code === 'grant_horizon_exceeded') {
+        return (`${base} — the delegation ran past the platform's renewal horizon ` +
+            `(CAPABILITY_GRANT_MAX_LIFETIME_SECONDS, default 6h). This is not an ` +
+            `agent-fixable error: split the work into shorter runs, or the platform ` +
+            `operator can raise the horizon deliberately.`);
+    }
+    if (code === 'grant_expired' || (!code && /expired/i.test(base))) {
+        return (`${base} — the capability grant expired mid-run and could not be refreshed ` +
+            `(the SDK refreshes automatically before expiry). This is not an agent-fixable ` +
+            `error: tell the operator to retry the delegation once; if it recurs, the ` +
+            `keemakr-core deployment may predate the grant-refresh endpoint — raise ` +
+            `CAPABILITY_GRANT_TTL_SECONDS there, or use a machine grant for long ` +
+            `unattended work.`);
+    }
+    return (`${base} — the capability grant was rejected. This is not an agent-fixable ` +
+        `error: the operator should re-issue the delegation.`);
+}
+/** An expired-grant denial: the typed `code` from current cores, with the
+ *  legacy error-text match as the fallback against pre-refresh cores. */
+function isExpiredDenial(status, body) {
+    if (status !== 401)
+        return false;
+    if (body.code)
+        return body.code === 'grant_expired';
+    return /expired/i.test(body.error ?? '');
 }
 async function capabilityFetch(grant, path, body, method = 'POST') {
     const url = `${coreBaseUrl()}/api/capability/${path}`;
     const hasBody = method !== 'GET' && method !== 'DELETE';
-    const res = await fetch(url, {
-        method,
-        headers: {
-            ...(hasBody ? { 'content-type': 'application/json' } : {}),
-            authorization: `Bearer ${grant.token}`,
-            ...(grant.traceId ? { 'x-keemakr-trace-id': grant.traceId } : {}),
-        },
-        ...(hasBody ? { body: JSON.stringify(body ?? {}) } : {}),
-    });
-    const json = (await res.json().catch(() => ({})));
+    const send = async (token) => {
+        const res = await fetch(url, {
+            method,
+            headers: {
+                ...(hasBody ? { 'content-type': 'application/json' } : {}),
+                authorization: `Bearer ${token}`,
+                ...(grant.traceId ? { 'x-keemakr-trace-id': grant.traceId } : {}),
+            },
+            ...(hasBody ? { body: JSON.stringify(body ?? {}) } : {}),
+        });
+        const json = (await res.json().catch(() => ({})));
+        return { res, json };
+    };
+    // Proactive: refresh the grant first when it's inside the expiry threshold
+    // (failure degrades to the current token — core is the judge).
+    const token = await ensureFreshToken(grant.token);
+    let { res, json } = await send(token);
+    // Reactive: one refresh + one retry when core says the grant expired in
+    // flight (or another call refreshed while this one was out on a stale
+    // token). At most one retry — never a loop.
+    if (isExpiredDenial(res.status, json)) {
+        const retryToken = await tokenForRetry(grant.token, token);
+        if (retryToken)
+            ({ res, json } = await send(retryToken));
+    }
     if (!res.ok) {
-        throw keeError(json.error ?? `capability request failed (${res.status})`, res.status);
+        const base = json.error ?? `capability request failed (${res.status})`;
+        throw keeError(res.status === 401 ? with401Guidance(base, json.code) : base, res.status, json);
     }
     return json;
 }
@@ -92,9 +150,31 @@ export function useKee(ctx) {
             const entry = await this.getEntry(namespace, key);
             return entry ? entry.value : null;
         },
-        async set(namespace, key, value) {
-            const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, { value }, 'PUT'));
-            return json.entry;
+        async set(namespace, key, value, opts) {
+            try {
+                const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, { value, expected_version: opts?.ifVersion }, 'PUT'));
+                return json.entry;
+            }
+            catch (e) {
+                if (e.status === 409) {
+                    const body = e.body;
+                    throw new MemoryConflictError(body?.entry ?? null);
+                }
+                throw e;
+            }
+        },
+        async patch(namespace, key, delta, opts) {
+            try {
+                const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, { delta, expected_version: opts?.ifVersion }, 'PATCH'));
+                return json.entry;
+            }
+            catch (e) {
+                if (e.status === 409) {
+                    const body = e.body;
+                    throw new MemoryConflictError(body?.entry ?? null);
+                }
+                throw e;
+            }
         },
         async delete(namespace, key) {
             const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, undefined, 'DELETE'));
@@ -113,6 +193,15 @@ export function useKee(ctx) {
             return json.hits ?? [];
         },
     };
+    const kb = {
+        async search(query, opts) {
+            const json = (await capabilityFetch(grant, 'kb/retrieve', {
+                query,
+                k: opts?.k,
+            }));
+            return json.hits ?? [];
+        },
+    };
     const tools = {
         async list() {
             const json = (await capabilityFetch(grant, 'tools', undefined, 'GET'));
@@ -125,5 +214,5 @@ export function useKee(ctx) {
             return json.result;
         },
     };
-    return { tenantId: grant.tenantId, scopes: grant.scopes, connections, memory, tools };
+    return { tenantId: grant.tenantId, scopes: grant.scopes, connections, memory, kb, tools };
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { grantAuth } from './grant-auth.js';
 export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
-export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
+export { useKee, MemoryConflictError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeKb, type KBHit, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
+export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';

package/dist/index.js

@@ -10,5 +10,6 @@
 //   const r = await kee.connections.hunter.call('email-finder', { domain, first_name, last_name });
 export { grantAuth } from './grant-auth.js';
 export { verifyGrant } from './verify-grant.js';
-export { useKee, } from './client.js';
+export { useKee, MemoryConflictError, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
+export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';

package/dist/refresh.d.ts

@@ -0,0 +1,31 @@
+/** Refresh when the active token has less than this long left to live. */
+export declare const REFRESH_THRESHOLD_SECONDS = 120;
+/** Resolve core's base URL: KEE_CORE_URL, else derived from KEE_CORE_JWKS_URL. */
+export declare function coreBaseUrl(): string;
+/** The freshest token known for a delegation (the exchanged one, else the original). */
+export declare function activeGrantToken(originalToken: string): string;
+/**
+ * Exchange a still-valid grant for a fresh one. The one public low-level hook,
+ * for headless/advanced callers — `useKee` calls it for you. Throws a KeeError-
+ * shaped error when core refuses (expired grant, horizon exceeded, …); the
+ * error's `body.code` carries core's machine-readable reason.
+ */
+export declare function refreshGrant(token: string, opts?: {
+    coreUrl?: string;
+}): Promise<{
+    token: string;
+    exp: number;
+}>;
+/**
+ * The proactive path, called before every capability request: returns the token
+ * the request should carry, refreshing first when the active one is inside the
+ * expiry threshold. A failed refresh degrades to the current token.
+ */
+export declare function ensureFreshToken(originalToken: string): Promise<string>;
+/**
+ * The reactive path, called once after a 401 `grant_expired`: if another call
+ * already refreshed (the request went out on a stale token), hand back the
+ * newer one; otherwise attempt one shared refresh. Returns the token to retry
+ * with, or null — the caller retries AT MOST once and never loops.
+ */
+export declare function tokenForRetry(originalToken: string, usedToken: string): Promise<string | null>;

package/dist/refresh.js

@@ -0,0 +1,112 @@
+// Grant refresh — keeps a delegation's capability grant alive for the whole
+// run by exchanging a STILL-VALID grant for a fresh one at core's
+// POST /api/capability/grant/refresh (sliding renewal; the chain is bounded
+// server-side by root_iat, default 6h).
+//
+// The cache is MODULE state keyed by the ORIGINAL grant token from the session
+// auth attributes — deliberately not closure state: eve step replay
+// reconstructs closures, and a closure-held fresh token would silently vanish
+// on replay. Module state survives within a process; across processes the
+// worst case is one redundant refresh, which core guarantees is harmless
+// (refreshing the same grant twice just yields two valid tokens).
+//
+// The SDK never verifies signatures and never sees the signing key —
+// decodeJwt() here reads `exp` locally only; core re-verifies everything.
+import { decodeJwt } from 'jose';
+/** Refresh when the active token has less than this long left to live. */
+export const REFRESH_THRESHOLD_SECONDS = 120;
+// original grant token → freshest exchanged token. Module-level on purpose (R2).
+const refreshed = new Map();
+// original grant token → in-flight refresh, so N concurrent tool calls share one POST.
+const inflight = new Map();
+/** Resolve core's base URL: KEE_CORE_URL, else derived from KEE_CORE_JWKS_URL. */
+export function coreBaseUrl() {
+    const explicit = process.env.KEE_CORE_URL;
+    if (explicit)
+        return explicit.replace(/\/$/, '');
+    const jwks = process.env.KEE_CORE_JWKS_URL;
+    if (jwks)
+        return jwks.replace(/\/\.well-known\/jwks\.json\/?$/, '');
+    const e = new Error('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API');
+    e.name = 'KeeError';
+    throw e;
+}
+function expOf(token) {
+    try {
+        const { exp } = decodeJwt(token);
+        return typeof exp === 'number' ? exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The freshest token known for a delegation (the exchanged one, else the original). */
+export function activeGrantToken(originalToken) {
+    return refreshed.get(originalToken)?.token ?? originalToken;
+}
+/**
+ * Exchange a still-valid grant for a fresh one. The one public low-level hook,
+ * for headless/advanced callers — `useKee` calls it for you. Throws a KeeError-
+ * shaped error when core refuses (expired grant, horizon exceeded, …); the
+ * error's `body.code` carries core's machine-readable reason.
+ */
+export async function refreshGrant(token, opts) {
+    const base = opts?.coreUrl?.replace(/\/$/, '') ?? coreBaseUrl();
+    const res = await fetch(`${base}/api/capability/grant/refresh`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}` },
+    });
+    const json = (await res.json().catch(() => ({})));
+    if (!res.ok || typeof json.token !== 'string' || typeof json.exp !== 'number') {
+        const e = new Error(`grant refresh failed (${res.status})${json.error ? `: ${json.error}` : ''}`);
+        e.name = 'KeeError';
+        e.status = res.status;
+        e.body = json;
+        throw e;
+    }
+    return { token: json.token, exp: json.exp };
+}
+/** Single-flight refresh of a delegation's ACTIVE token; null on any failure. */
+function refreshShared(originalToken) {
+    const running = inflight.get(originalToken);
+    if (running)
+        return running;
+    const attempt = refreshGrant(activeGrantToken(originalToken))
+        .then((fresh) => {
+        refreshed.set(originalToken, fresh);
+        return fresh;
+    })
+        .catch(() => null) // non-fatal: proceed on the current token, core decides
+        .finally(() => {
+        inflight.delete(originalToken);
+    });
+    inflight.set(originalToken, attempt);
+    return attempt;
+}
+/**
+ * The proactive path, called before every capability request: returns the token
+ * the request should carry, refreshing first when the active one is inside the
+ * expiry threshold. A failed refresh degrades to the current token.
+ */
+export async function ensureFreshToken(originalToken) {
+    const active = activeGrantToken(originalToken);
+    const exp = expOf(active);
+    const now = Math.floor(Date.now() / 1000);
+    if (exp !== null && exp - now >= REFRESH_THRESHOLD_SECONDS)
+        return active;
+    const fresh = await refreshShared(originalToken);
+    return fresh?.token ?? active;
+}
+/**
+ * The reactive path, called once after a 401 `grant_expired`: if another call
+ * already refreshed (the request went out on a stale token), hand back the
+ * newer one; otherwise attempt one shared refresh. Returns the token to retry
+ * with, or null — the caller retries AT MOST once and never loops.
+ */
+export async function tokenForRetry(originalToken, usedToken) {
+    const active = activeGrantToken(originalToken);
+    if (active !== usedToken)
+        return active;
+    const fresh = await refreshShared(originalToken);
+    return fresh && fresh.token !== usedToken ? fresh.token : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections, memory, and shared platform tools through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
   "license": "MIT",
   "type": "module",