@keemakr/agent-sdk 0.10.0 → 0.11.0

package/README.md

@@ -19,13 +19,21 @@ 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.                          |
-| `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.)               |
-
-If `KEE_CORE_JWKS_URL` is unset, `grantAuth()` skips entirely — useful during local development.
+| Variable             | Purpose                                                                                                                                             |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KEE_CORE_URL`       | **Required.** The keemakr platform you installed on, e.g. `https://dash.dev.keemakr.ai`. Used both to verify grants and to call the capability API. |
+| `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_JWKS_URL`  | Only when the JWKS is not at `<KEE_CORE_URL>/.well-known/jwks.json`. Takes precedence over `KEE_CORE_URL` for verification.                         |
+
+**There is no default platform, deliberately.** `KEE_CORE_URL` names the keys your
+agent trusts and the host it sends the tenant's grant token to. A compiled-in
+default would mean this package picking your trust anchor for you — and since the
+same published SDK is installed against dev, staging and production, whichever
+origin it named would be wrong for the others. Set one variable per deployment.
+
+With neither set, `grantAuth()` refuses every grant and logs once explaining why,
+and `coreBaseUrl()` throws rather than posting a live credential somewhere you did
+not choose. Both name the variables in their message.
 
 ## 1. Verify the grant in your channel
 
@@ -142,13 +150,17 @@ via `kee.kb`.
 
 ```ts
 const hits = await kee.kb.search('what is our refund policy?', { k: 5 });
-// → [{ text, score, provenance: { title, source_uri, … } }]
+// → [{ text, score, artifact_id, version_id, chunk_id, title,
+//      audience, visibility, provenance }]
 ```
 
-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.
+Core derives the retrieval actor from the verified grant. A Kee acting for a
+user can retrieve that user's Personal Knowledge plus Organization and Platform
+Knowledge. A System Kee can retrieve Organization and Platform Knowledge but
+never Personal Knowledge. External Kees are additionally restricted to External
+Safe knowledge. Collections organize artifacts but never grant access
+(`kb:retrieve` scope, granted to every install). Retrieval is hybrid and may be
+reranked in Core; `text` may be a wider parent context.
 
 ### Platform tools
 

package/dist/client.d.ts

@@ -112,13 +112,17 @@ export interface KeeMemory {
 export interface KBHit {
     text: string;
     score: number;
+    artifact_id: string;
+    version_id: string;
+    chunk_id: string;
+    title: string;
+    audience: 'personal' | 'organization' | 'platform';
+    visibility: 'internal_only' | 'external_safe';
     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).
+ * Governed Company Brain retrieval. Core derives User, System, or External Kee access from the
+ * verified grant and returns source identities suitable for citations. Requires `kb:retrieve`.
  */
 export interface KeeKb {
     /** Semantic + lexical + reranked search over the agent-visible knowledge. */
@@ -182,6 +186,31 @@ export interface KeeTools {
     /** Run a registry tool by name and return its result. Requires `tools:run`. */
     run(name: string, args?: Record<string, unknown>): Promise<unknown>;
 }
+/**
+ * The entry's STAFF-SET platform settings — one value per `kind:'env'`
+ * dependency it declares. Requires the `config:read` scope, which that same
+ * declaration mints.
+ *
+ * These are operator settings (a destination address, a shared endpoint), not
+ * tenant data and not secrets the agent may change: the surface is read-only by
+ * design. An operator sets them once in the platform console and they apply to
+ * every install of the entry.
+ */
+export interface KeeConfig {
+    /** One setting, or null when staff have not set it yet. */
+    get(key: string): Promise<string | null>;
+    /**
+     * Every declared setting at once — `{ config, declared }`. `declared` lists
+     * the keys this entry asks for, so "staff haven't set it" (declared, missing
+     * from config) stays distinguishable from "this entry has no such setting"
+     * (absent from declared). Collapsing those two is what makes a configuration
+     * gap look like a runtime bug.
+     */
+    all(): Promise<{
+        config: Record<string, string>;
+        declared: string[];
+    }>;
+}
 export interface Kee {
     tenantId: string;
     scopes: string[];
@@ -193,6 +222,7 @@ export interface Kee {
     records: KeeRecords;
     kb: KeeKb;
     tools: KeeTools;
+    config: KeeConfig;
 }
 /**
  * Build a tenant-scoped capability client from a tool's context. Call inside a

package/dist/client.js

@@ -278,7 +278,7 @@ export function useKee(ctx) {
         async search(query, opts) {
             const json = (await capabilityFetch(grant, 'kb/retrieve', {
                 query,
-                k: opts?.k,
+                limit: opts?.k,
             }));
             return json.hits ?? [];
         },
@@ -295,6 +295,30 @@ export function useKee(ctx) {
             return json.result;
         },
     };
+    // One fetch serves both accessors, and the result is cached for the life of
+    // this client: settings change at operator pace, not per tool call, and a
+    // `get()` per setting inside one tool would re-fetch the same map N times.
+    let configOnce = null;
+    const config = {
+        async all() {
+            configOnce ??= (async () => {
+                const json = (await capabilityFetch(grant, 'config', undefined, 'GET'));
+                return { config: json.config ?? {}, declared: json.declared ?? [] };
+            })();
+            try {
+                return await configOnce;
+            }
+            catch (e) {
+                // Don't cache a failure — a transient error must not poison every later
+                // read for the rest of the session.
+                configOnce = null;
+                throw e;
+            }
+        },
+        async get(key) {
+            return (await this.all()).config[key] ?? null;
+        },
+    };
     return {
         tenantId: grant.tenantId,
         scopes: grant.scopes,
@@ -303,5 +327,6 @@ export function useKee(ctx) {
         records,
         kb,
         tools,
+        config,
     };
 }

package/dist/connectors.generated.d.ts

@@ -1,11 +1,10 @@
-export type ConnectorName = "agent-sessions" | "apify" | "apollo" | "cal-com" | "calendly" | "clearbit" | "drip" | "elevenlabs" | "facebook" | "fal" | "hubspot" | "hunter" | "instagram" | "instantly" | "mailchimp" | "meta" | "pagespeed" | "posthog" | "salesforce" | "sendgrid" | "slack" | "stripe" | "twilio" | "whatsapp" | "wordpress";
+export type ConnectorName = "agent-sessions" | "apify" | "apollo" | "cal-com" | "clearbit" | "drip" | "elevenlabs" | "facebook" | "fal" | "hubspot" | "hunter" | "instagram" | "instantly" | "mailchimp" | "meta" | "pagespeed" | "posthog" | "sendgrid" | "stripe" | "twilio" | "wordpress";
 /** Per-provider operation names (autocomplete for `.call(op)`). */
 export interface ConnectorOps {
     "agent-sessions": never;
     "apify": never;
     "apollo": never;
     "cal-com": never;
-    "calendly": never;
     "clearbit": never;
     "drip": never;
     "elevenlabs": never;
@@ -19,12 +18,9 @@ export interface ConnectorOps {
     "meta": never;
     "pagespeed": never;
     "posthog": never;
-    "salesforce": never;
     "sendgrid": never;
-    "slack": never;
     "stripe": never;
     "twilio": never;
-    "whatsapp": never;
     "wordpress": never;
 }
 export interface ConnectorOp {
@@ -79,14 +75,6 @@ export declare const connectors: {
         readonly docUrl: "https://cal.com/docs/api-reference";
         readonly ops: {};
     };
-    readonly calendly: {
-        readonly displayName: "Calendly";
-        readonly authKind: "api_key";
-        readonly category: "scheduling";
-        readonly maturity: "coming_soon";
-        readonly docUrl: "https://developer.calendly.com/api-docs";
-        readonly ops: {};
-    };
     readonly clearbit: {
         readonly displayName: "Clearbit";
         readonly authKind: "api_key";
@@ -217,14 +205,6 @@ export declare const connectors: {
         readonly docUrl: "https://posthog.com/docs/api";
         readonly ops: {};
     };
-    readonly salesforce: {
-        readonly displayName: "Salesforce";
-        readonly authKind: "api_key";
-        readonly category: "crm";
-        readonly maturity: "coming_soon";
-        readonly docUrl: "https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/";
-        readonly ops: {};
-    };
     readonly sendgrid: {
         readonly displayName: "SendGrid";
         readonly authKind: "api_key";
@@ -233,14 +213,6 @@ export declare const connectors: {
         readonly docUrl: "https://docs.sendgrid.com/api-reference";
         readonly ops: {};
     };
-    readonly slack: {
-        readonly displayName: "Slack";
-        readonly authKind: "api_key";
-        readonly category: "messaging";
-        readonly maturity: "coming_soon";
-        readonly docUrl: "https://api.slack.com/methods/chat.postMessage";
-        readonly ops: {};
-    };
     readonly stripe: {
         readonly displayName: "Stripe";
         readonly authKind: "oauth2";
@@ -257,14 +229,6 @@ export declare const connectors: {
         readonly docUrl: "https://www.twilio.com/docs/usage/api";
         readonly ops: {};
     };
-    readonly whatsapp: {
-        readonly displayName: "WhatsApp";
-        readonly authKind: "oauth2";
-        readonly category: "channel";
-        readonly maturity: "coming_soon";
-        readonly docUrl: "https://developers.facebook.com/docs/whatsapp";
-        readonly ops: {};
-    };
     readonly wordpress: {
         readonly displayName: "WordPress";
         readonly authKind: "oauth2";

package/dist/connectors.generated.js

@@ -39,14 +39,6 @@ export const connectors = {
         "docUrl": "https://cal.com/docs/api-reference",
         "ops": {}
     },
-    "calendly": {
-        "displayName": "Calendly",
-        "authKind": "api_key",
-        "category": "scheduling",
-        "maturity": "coming_soon",
-        "docUrl": "https://developer.calendly.com/api-docs",
-        "ops": {}
-    },
     "clearbit": {
         "displayName": "Clearbit",
         "authKind": "api_key",
@@ -181,14 +173,6 @@ export const connectors = {
         "docUrl": "https://posthog.com/docs/api",
         "ops": {}
     },
-    "salesforce": {
-        "displayName": "Salesforce",
-        "authKind": "api_key",
-        "category": "crm",
-        "maturity": "coming_soon",
-        "docUrl": "https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/",
-        "ops": {}
-    },
     "sendgrid": {
         "displayName": "SendGrid",
         "authKind": "api_key",
@@ -197,14 +181,6 @@ export const connectors = {
         "docUrl": "https://docs.sendgrid.com/api-reference",
         "ops": {}
     },
-    "slack": {
-        "displayName": "Slack",
-        "authKind": "api_key",
-        "category": "messaging",
-        "maturity": "coming_soon",
-        "docUrl": "https://api.slack.com/methods/chat.postMessage",
-        "ops": {}
-    },
     "stripe": {
         "displayName": "Stripe",
         "authKind": "oauth2",
@@ -221,14 +197,6 @@ export const connectors = {
         "docUrl": "https://www.twilio.com/docs/usage/api",
         "ops": {}
     },
-    "whatsapp": {
-        "displayName": "WhatsApp",
-        "authKind": "oauth2",
-        "category": "channel",
-        "maturity": "coming_soon",
-        "docUrl": "https://developers.facebook.com/docs/whatsapp",
-        "ops": {}
-    },
     "wordpress": {
         "displayName": "WordPress",
         "authKind": "oauth2",

package/dist/grant-auth.d.ts

@@ -6,12 +6,22 @@ import { type AuthFn } from 'eve/channels/auth';
  * fallback).
  *
  * Environment:
- *   KEE_CORE_JWKS_URL   keemakr-core's JWKS endpoint
- *                       (e.g. https://app.keemakr.com/.well-known/jwks.json).
- *                       If unset, this AuthFn skips entirely (grant path off).
+ *   KEE_CORE_URL        core's origin, e.g. https://dash.<env>.keemakr.ai — the
+ *                       platform this agent was installed on. REQUIRED (unless
+ *                       KEE_CORE_JWKS_URL or `opts.jwksUrl` says the same thing):
+ *                       it names the keys this agent trusts, and there is no
+ *                       default, because a default would mean trusting whichever
+ *                       platform the SDK author picked. Without it, every grant is
+ *                       refused and the reason is logged once.
+ *   KEE_CORE_JWKS_URL   the JWKS endpoint directly, when it is not
+ *                       `<KEE_CORE_URL>/.well-known/jwks.json`.
  *   KEE_AGENT_AUDIENCE  this deployment's audience — the runtime URL's origin —
  *                       matching the `aud` the operator mints. If unset, the
  *                       audience check is skipped (dev convenience only).
+ *
+ * A missing configuration no longer switches grant verification off SILENTLY,
+ * which was the real defect: it used to return the same bare null as a bad token,
+ * so every capability call 401'd with nothing in the log to say why.
  */
 export declare function grantAuth(opts?: {
     jwksUrl?: string;

package/dist/grant-auth.js

@@ -8,16 +8,11 @@
 // grantAuth() returns an eve AuthFn that verifies the grant against core's JWKS
 // and surfaces the tenant + scopes (and the raw grant, for useKee to forward) on
 // the session auth context. Use it as the PRIMARY inbound auth in your channel.
-import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { jwtVerify } from 'jose';
 import { extractBearerToken } from 'eve/channels/auth';
+import { jwksFor, resolveJwksUrl, warnCoreUnconfigured, warnGrantVerifyFailed } from './jwks.js';
 // The issuer keemakr-core mints grants with.
 const GRANT_ISSUER = 'keemakr';
-let jwks = null;
-function jwksFor(url) {
-    if (!jwks)
-        jwks = createRemoteJWKSet(new URL(url));
-    return jwks;
-}
 /**
  * An eve AuthFn that accepts a keemakr capability grant. Returns a principal
  * carrying `tenant_id`, `scopes`, and the raw `grant_token` in attributes on
@@ -25,21 +20,35 @@ function jwksFor(url) {
  * fallback).
  *
  * Environment:
- *   KEE_CORE_JWKS_URL   keemakr-core's JWKS endpoint
- *                       (e.g. https://app.keemakr.com/.well-known/jwks.json).
- *                       If unset, this AuthFn skips entirely (grant path off).
+ *   KEE_CORE_URL        core's origin, e.g. https://dash.<env>.keemakr.ai — the
+ *                       platform this agent was installed on. REQUIRED (unless
+ *                       KEE_CORE_JWKS_URL or `opts.jwksUrl` says the same thing):
+ *                       it names the keys this agent trusts, and there is no
+ *                       default, because a default would mean trusting whichever
+ *                       platform the SDK author picked. Without it, every grant is
+ *                       refused and the reason is logged once.
+ *   KEE_CORE_JWKS_URL   the JWKS endpoint directly, when it is not
+ *                       `<KEE_CORE_URL>/.well-known/jwks.json`.
  *   KEE_AGENT_AUDIENCE  this deployment's audience — the runtime URL's origin —
  *                       matching the `aud` the operator mints. If unset, the
  *                       audience check is skipped (dev convenience only).
+ *
+ * A missing configuration no longer switches grant verification off SILENTLY,
+ * which was the real defect: it used to return the same bare null as a bad token,
+ * so every capability call 401'd with nothing in the log to say why.
  */
 export function grantAuth(opts) {
     return async (request) => {
-        const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
-        if (!jwksUrl)
-            return null;
+        // Token first: an unconfigured deployment should complain about requests that
+        // actually carry a grant, not about every anonymous hit on the channel.
         const token = extractBearerToken(request.headers.get('authorization'));
         if (!token)
             return null;
+        const jwksUrl = resolveJwksUrl(opts?.jwksUrl);
+        if (!jwksUrl) {
+            warnCoreUnconfigured('verify the capability grant on this request');
+            return null;
+        }
         const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
         try {
             const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
@@ -67,7 +76,11 @@ export function grantAuth(opts) {
                 },
             };
         }
-        catch {
+        catch (error) {
+            // Still returns null — an unverifiable token must not authenticate — but no
+            // longer silently. A wrong JWKS URL and a genuinely bad token produced the
+            // same nothing before, which is what made the redirect trap so expensive.
+            warnGrantVerifyFailed(jwksUrl, error);
             return null;
         }
     };

package/dist/index.d.ts

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

package/dist/jwks.d.ts

@@ -0,0 +1,42 @@
+/**
+ * There is deliberately NO compiled-in default origin.
+ *
+ * This value is a TRUST ANCHOR: whatever it names gets to decide, for every
+ * tenant this agent serves, which grants are genuine. It cannot come from the
+ * token (a forged grant would name its own JWKS and verify against it), and it
+ * must not come from a constant baked into a published package either — this SDK
+ * ships to npm and is installed by agents on dev, staging and production alike,
+ * so ANY single origin compiled in here is the wrong one for at least two of
+ * them. A default pointing at a non-production platform is the worst case of all:
+ * an unconfigured production agent would accept grants signed by a platform
+ * anyone can get an account on.
+ *
+ * So an unconfigured deployment gets `null` and verifies nothing — but LOUDLY,
+ * via warnCoreUnconfigured(). That was the actual defect behind "every capability
+ * call 401s with nothing in the log": not the absence of a default, but the
+ * silence. One warning naming the two variables fixes that without inventing a
+ * trust anchor on the operator's behalf.
+ */
+/** `<origin>/.well-known/jwks.json`, tolerating a trailing slash. */
+export declare function jwksUrlFor(origin: string): string;
+/**
+ * Resolve core's JWKS endpoint, most specific first, or `null` when the
+ * deployment has said nothing about which platform it belongs to.
+ *
+ * `KEE_CORE_URL` counts as a source in its own right: the SDK already derives
+ * that base URL FROM the JWKS URL, and supporting only that direction meant an
+ * agent could be configured to reach the capability API yet unable to verify the
+ * grant authorizing it — two variables for one fact, with a silent 401 as the
+ * penalty for setting the wrong one.
+ */
+export declare function resolveJwksUrl(explicit?: string): string | null;
+export declare function jwksFor(url: string): {
+    (protectedHeader?: import("jose").JWSHeaderParameters, token?: import("jose").FlattenedJWSInput): Promise<import("jose").CryptoKey>;
+    coolingDown: boolean;
+    fresh: boolean;
+    reloading: boolean;
+    reload: () => Promise<void>;
+    jwks: () => import("jose").JSONWebKeySet | undefined;
+};
+export declare function warnGrantVerifyFailed(jwksUrl: string, error: unknown): void;
+export declare function warnCoreUnconfigured(attempting: string): void;

package/dist/jwks.js

@@ -0,0 +1,97 @@
+// Where a keemakr agent looks for core's signing keys, and the one cache of them.
+//
+// Shared by both verification paths — the inbound channel auth (grant-auth) and
+// the standalone machine-grant check (verify-grant) — because a deployment that
+// can verify one and not the other is a configuration bug waiting to be
+// diagnosed twice.
+import { createRemoteJWKSet } from 'jose';
+/**
+ * There is deliberately NO compiled-in default origin.
+ *
+ * This value is a TRUST ANCHOR: whatever it names gets to decide, for every
+ * tenant this agent serves, which grants are genuine. It cannot come from the
+ * token (a forged grant would name its own JWKS and verify against it), and it
+ * must not come from a constant baked into a published package either — this SDK
+ * ships to npm and is installed by agents on dev, staging and production alike,
+ * so ANY single origin compiled in here is the wrong one for at least two of
+ * them. A default pointing at a non-production platform is the worst case of all:
+ * an unconfigured production agent would accept grants signed by a platform
+ * anyone can get an account on.
+ *
+ * So an unconfigured deployment gets `null` and verifies nothing — but LOUDLY,
+ * via warnCoreUnconfigured(). That was the actual defect behind "every capability
+ * call 401s with nothing in the log": not the absence of a default, but the
+ * silence. One warning naming the two variables fixes that without inventing a
+ * trust anchor on the operator's behalf.
+ */
+/** `<origin>/.well-known/jwks.json`, tolerating a trailing slash. */
+export function jwksUrlFor(origin) {
+    return `${origin.replace(/\/$/, '')}/.well-known/jwks.json`;
+}
+/**
+ * Resolve core's JWKS endpoint, most specific first, or `null` when the
+ * deployment has said nothing about which platform it belongs to.
+ *
+ * `KEE_CORE_URL` counts as a source in its own right: the SDK already derives
+ * that base URL FROM the JWKS URL, and supporting only that direction meant an
+ * agent could be configured to reach the capability API yet unable to verify the
+ * grant authorizing it — two variables for one fact, with a silent 401 as the
+ * penalty for setting the wrong one.
+ */
+export function resolveJwksUrl(explicit) {
+    if (explicit)
+        return explicit;
+    if (process.env.KEE_CORE_JWKS_URL)
+        return process.env.KEE_CORE_JWKS_URL;
+    if (process.env.KEE_CORE_URL)
+        return jwksUrlFor(process.env.KEE_CORE_URL);
+    return null;
+}
+// Keyed by URL. The previous single-slot cache handed back the FIRST keyset it
+// ever built for every later call, so a process verifying against two cores used
+// the wrong keys for one of them and reported nothing.
+const jwksCache = new Map();
+export function jwksFor(url) {
+    let set = jwksCache.get(url);
+    if (!set) {
+        set = createRemoteJWKSet(new URL(url));
+        jwksCache.set(url, set);
+    }
+    return set;
+}
+// A misconfigured JWKS URL was indistinguishable from an unauthorized caller: the
+// verify threw, the caller returned null, and every capability call 401'd with
+// nothing said about why. The classic cause is an origin that REDIRECTS (e.g.
+// app.dev.keemakr.ai → dash.dev.keemakr.ai), where `jose` fetches HTML and finds
+// no keys. Warn once per URL: enough to diagnose, not enough to flood a hot path.
+const warned = new Set();
+export function warnGrantVerifyFailed(jwksUrl, error) {
+    if (warned.has(jwksUrl))
+        return;
+    warned.add(jwksUrl);
+    const reason = error instanceof Error ? error.message : String(error);
+    console.warn(`[keemakr] could not verify a capability grant against ${jwksUrl}: ${reason}. ` +
+        'If that URL redirects or serves no keys, set KEE_CORE_JWKS_URL (or KEE_CORE_URL) ' +
+        'to the origin serving /.well-known/jwks.json for the platform you installed on.');
+}
+/**
+ * The other half of the same diagnosis problem: a deployment that named no
+ * platform at all. It still refuses the token — an agent that does not know whose
+ * keys to trust must not decide that a grant is genuine — but it now says so
+ * instead of returning the same silent null a genuinely bad token gets.
+ *
+ * Warned once per process (not per request): this fires on a hot path, and after
+ * the first line the operator has everything they need.
+ */
+let warnedUnconfigured = false;
+export function warnCoreUnconfigured(attempting) {
+    if (warnedUnconfigured)
+        return;
+    warnedUnconfigured = true;
+    console.warn(`[keemakr] cannot ${attempting}: this deployment has not been told which keemakr ` +
+        'platform it belongs to, so there are no signing keys to trust and no capability ' +
+        'API to call. Set KEE_CORE_URL to the origin you installed on (e.g. ' +
+        'https://dash.<env>.keemakr.ai), or KEE_CORE_JWKS_URL to its ' +
+        '/.well-known/jwks.json directly. There is no default on purpose — guessing ' +
+        'would mean trusting a platform you did not choose.');
+}

package/dist/refresh.d.ts

@@ -1,6 +1,16 @@
 /** 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. */
+/**
+ * Resolve core's base URL: KEE_CORE_URL, else the origin of KEE_CORE_JWKS_URL.
+ *
+ * Throws when neither is set, and that is the safe answer rather than the
+ * unhelpful one. This URL is where the SDK POSTs the tenant's grant token, so a
+ * guessed default is not a convenience — it is a live credential sent to a host
+ * nobody chose, which on an unconfigured production agent would mean handing a
+ * production grant to whatever environment the constant happened to name. Failing
+ * at the first capability call, with both variable names in the message, costs one
+ * deploy; the other failure mode costs a credential.
+ */
 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;

package/dist/refresh.js

@@ -19,7 +19,17 @@ export const REFRESH_THRESHOLD_SECONDS = 120;
 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. */
+/**
+ * Resolve core's base URL: KEE_CORE_URL, else the origin of KEE_CORE_JWKS_URL.
+ *
+ * Throws when neither is set, and that is the safe answer rather than the
+ * unhelpful one. This URL is where the SDK POSTs the tenant's grant token, so a
+ * guessed default is not a convenience — it is a live credential sent to a host
+ * nobody chose, which on an unconfigured production agent would mean handing a
+ * production grant to whatever environment the constant happened to name. Failing
+ * at the first capability call, with both variable names in the message, costs one
+ * deploy; the other failure mode costs a credential.
+ */
 export function coreBaseUrl() {
     const explicit = process.env.KEE_CORE_URL;
     if (explicit)
@@ -27,7 +37,10 @@ export function coreBaseUrl() {
     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');
+    const e = new Error('KEE_CORE_URL (or KEE_CORE_JWKS_URL) must be set to reach the Capability API — ' +
+        'it names the keemakr platform this agent was installed on, e.g. ' +
+        'https://dash.<env>.keemakr.ai. There is no default: the grant token is sent ' +
+        'to this URL, so guessing would leak it to a platform you did not choose.');
     e.name = 'KeeError';
     throw e;
 }

package/dist/verify-grant.d.ts

@@ -10,9 +10,11 @@ export interface VerifiedGrant {
 /**
  * Verify a capability grant (session OR machine) against keemakr-core's JWKS.
  * Returns the trusted claims, or `null` on any failure (bad signature, wrong
- * issuer/audience, expired). Both `jwksUrl` and `audience` fall back to
- * KEE_CORE_JWKS_URL / KEE_AGENT_AUDIENCE. `audience` is strongly recommended: a
- * grant is only valid for the remote it was minted for.
+ * issuer/audience, expired). `jwksUrl` falls back to KEE_CORE_JWKS_URL, then to
+ * KEE_CORE_URL's origin — and to nothing after that, so a deployment that has not
+ * named its platform refuses every grant rather than trusting a compiled-in
+ * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and is
+ * strongly recommended: a grant is only valid for the remote it was minted for.
  */
 export declare function verifyGrant(token: string, opts?: {
     jwksUrl?: string;

package/dist/verify-grant.js

@@ -10,25 +10,24 @@
 // A machine grant is the SAME token shape as a session grant (same issuer, aud,
 // tenant_id, scopes) — only the TTL and the mint path differ — so this one
 // verifier covers both.
-import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { jwtVerify } from 'jose';
+import { jwksFor, resolveJwksUrl, warnCoreUnconfigured, warnGrantVerifyFailed } from './jwks.js';
 const GRANT_ISSUER = 'keemakr';
-let jwks = null;
-function jwksFor(url) {
-    if (!jwks)
-        jwks = createRemoteJWKSet(new URL(url));
-    return jwks;
-}
 /**
  * Verify a capability grant (session OR machine) against keemakr-core's JWKS.
  * Returns the trusted claims, or `null` on any failure (bad signature, wrong
- * issuer/audience, expired). Both `jwksUrl` and `audience` fall back to
- * KEE_CORE_JWKS_URL / KEE_AGENT_AUDIENCE. `audience` is strongly recommended: a
- * grant is only valid for the remote it was minted for.
+ * issuer/audience, expired). `jwksUrl` falls back to KEE_CORE_JWKS_URL, then to
+ * KEE_CORE_URL's origin — and to nothing after that, so a deployment that has not
+ * named its platform refuses every grant rather than trusting a compiled-in
+ * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and is
+ * strongly recommended: a grant is only valid for the remote it was minted for.
  */
 export async function verifyGrant(token, opts) {
-    const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
-    if (!jwksUrl)
+    const jwksUrl = resolveJwksUrl(opts?.jwksUrl);
+    if (!jwksUrl) {
+        warnCoreUnconfigured('verify this capability grant');
         return null;
+    }
     const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
     try {
         const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
@@ -46,7 +45,10 @@ export async function verifyGrant(token, opts) {
             exp: typeof payload.exp === 'number' ? payload.exp : null,
         };
     }
-    catch {
+    catch (error) {
+        // Null either way — an unverifiable grant must not pass — but say why once, so
+        // a misconfigured JWKS URL is distinguishable from a genuinely bad token.
+        warnGrantVerifyFailed(jwksUrl, error);
         return null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.10.0",
+  "version": "0.11.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",