@keemakr/agent-sdk 0.6.0 → 0.7.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,20 +107,54 @@ 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`.
@@ -130,10 +164,10 @@ A call whose grant lacks the required scope returns a `KeeError` with `status: 4
 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 +177,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,27 @@
 // /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) {
+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;
@@ -46,7 +61,7 @@ async function capabilityFetch(grant, path, body, method = 'POST') {
     });
     const json = (await res.json().catch(() => ({})));
     if (!res.ok) {
-        throw keeError(json.error ?? `capability request failed (${res.status})`, res.status);
+        throw keeError(json.error ?? `capability request failed (${res.status})`, res.status, json);
     }
     return json;
 }
@@ -92,9 +107,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 +150,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 +171,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,4 @@
 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';

package/dist/index.js

@@ -10,5 +10,5 @@
 //   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';

package/package.json

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