@keemakr/agent-sdk 0.10.0 → 0.12.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,
     };
 }