@keemakr/agent-sdk 0.7.0 → 0.8.0

package/README.md

@@ -159,6 +159,22 @@ 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:

package/dist/client.js

@@ -4,6 +4,12 @@
 // /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.
+//
+// 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';
@@ -36,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, json);
+        const base = json.error ?? `capability request failed (${res.status})`;
+        throw keeError(res.status === 401 ? with401Guidance(base, json.code) : base, res.status, json);
     }
     return json;
 }

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export { grantAuth } from './grant-auth.js';
 export { verifyGrant, type VerifiedGrant } from './verify-grant.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

@@ -12,3 +12,4 @@ export { grantAuth } from './grant-auth.js';
 export { verifyGrant } from './verify-grant.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.7.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",