@keemakr/agent-sdk 0.2.0 → 0.4.0

package/README.md

@@ -82,6 +82,25 @@ await kee.connections.get("hunter").call("email-finder", { ... }); // equivalent
 const { access_token } = await kee.connections.hunter.token();
 ```
 
+### 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");
+// Semantic search by meaning (embeddings):
+const hits = await kee.memory.search("how should I speak to the user?", { limit: 5 });
+// → [{ namespace, key, value, score, … }]  (score 0–1, nearest first)
+```
+
+### Platform tools
+
+```ts
+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`.
 
 ## Security model

package/dist/client.d.ts

@@ -35,6 +35,11 @@ export interface MemoryEntry {
  * memory use eve's defineState instead — this is for state that must outlive the
  * session. Requires the `memory:rw` scope.
  */
+/** A semantic-search hit — a memory entry with its similarity score. */
+export interface MemorySearchHit extends MemoryEntry {
+    /** Cosine similarity in [0,1] (1 = identical). */
+    score: number;
+}
 export interface KeeMemory {
     /** Read a key's value, or null if absent. */
     get(namespace: string, key: string): Promise<unknown | null>;
@@ -46,6 +51,22 @@ export interface KeeMemory {
     delete(namespace: string, key: string): Promise<boolean>;
     /** List every entry in a namespace (tenant-wide). */
     list(namespace: string): Promise<MemoryEntry[]>;
+    /** Semantic search by meaning. Optionally scope to a namespace. */
+    search(query: string, opts?: {
+        namespace?: string;
+        limit?: number;
+    }): Promise<MemorySearchHit[]>;
+}
+/** Platform registry tools (Shape B) — defined in core, run server-side. */
+export interface KeeTools {
+    /** List the registry tools this grant is entitled to. */
+    list(): Promise<Array<{
+        name: string;
+        description: string;
+        requiredScope?: string;
+    }>>;
+    /** Run a registry tool by name and return its result. Requires `tools:run`. */
+    run(name: string, args?: Record<string, unknown>): Promise<unknown>;
 }
 export interface Kee {
     tenantId: string;
@@ -55,6 +76,7 @@ export interface Kee {
         get(provider: string): KeeConnection;
     };
     memory: KeeMemory;
+    tools: KeeTools;
 }
 /**
  * Build a tenant-scoped capability client from a tool's context. Call inside a

package/dist/client.js

@@ -104,6 +104,26 @@ export function useKee(ctx) {
             const json = (await capabilityFetch(grant, `memory/${enc(namespace)}`, undefined, 'GET'));
             return json.entries ?? [];
         },
+        async search(query, opts) {
+            const json = (await capabilityFetch(grant, 'memory/search', {
+                query,
+                namespace: opts?.namespace,
+                limit: opts?.limit,
+            }));
+            return json.hits ?? [];
+        },
+    };
+    const tools = {
+        async list() {
+            const json = (await capabilityFetch(grant, 'tools', undefined, 'GET'));
+            return json.tools ?? [];
+        },
+        async run(name, args) {
+            const json = (await capabilityFetch(grant, `tools/${encodeURIComponent(name)}`, {
+                args: args ?? {},
+            }));
+            return json.result;
+        },
     };
-    return { tenantId: grant.tenantId, scopes: grant.scopes, connections, memory };
+    return { tenantId: grant.tenantId, scopes: grant.scopes, connections, memory, tools };
 }

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { grantAuth } from './grant-auth.js';
-export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type MemoryEntry, } from './client.js';
+export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
+export { keemakrToolDirectory } from './tool-directory.js';

package/dist/index.js

@@ -10,3 +10,4 @@
 //   const r = await kee.connections.hunter.call('email-finder', { domain, first_name, last_name });
 export { grantAuth } from './grant-auth.js';
 export { useKee, } from './client.js';
+export { keemakrToolDirectory } from './tool-directory.js';

package/dist/tool-directory.d.ts

@@ -0,0 +1 @@
+export declare const keemakrToolDirectory: import("eve/tools").DynamicSentinel;

package/dist/tool-directory.js

@@ -0,0 +1,61 @@
+// keemakrToolDirectory — a defineDynamic file that surfaces the platform's
+// registry tools (Shape B) to an agent at session start, with NO redeploy.
+//
+// Drop it into your agent in one line:
+//   // agent/tools/keemakr-directory.ts
+//   export { keemakrToolDirectory as default } from '@keemakr/agent-sdk/tool-directory';
+//
+// On session.started it reads the verified grant off the session, asks
+// keemakr-core which registry tools this install is entitled to, and synthesizes
+// one delegation tool per entry. Each synthesized tool's execute calls
+// useKee(ctx).tools.run(name, args) — so the tool runs IN CORE, governed
+// centrally: a fix or a new tool in core's registry reaches every agent next
+// session, no redeploy here. Mirrors keemakr-core's marketplace-dispatch.ts.
+import { defineDynamic, defineTool } from 'eve/tools';
+import { z } from 'zod';
+import { useKee } from './client.js';
+export const keemakrToolDirectory = defineDynamic({
+    events: {
+        'session.started': async (_event, ctx) => {
+            // No grant on the session (e.g. local dev without grantAuth) → no tools.
+            let kee;
+            try {
+                kee = useKee(ctx);
+            }
+            catch {
+                return null;
+            }
+            let entries;
+            try {
+                entries = await kee.tools.list();
+            }
+            catch {
+                return null;
+            }
+            if (!entries.length)
+                return null;
+            // One delegation tool per entitled registry tool. The args are passed
+            // through as a generic object; core validates them against the tool's real
+            // schema and returns a typed error if they don't fit. (Names are namespaced
+            // `kee__<name>` to avoid colliding with the agent's own tools.)
+            const pairs = entries.map((t) => {
+                const name = t.name;
+                const tool = defineTool({
+                    description: `${t.description} (keemakr platform tool, runs server-side)`,
+                    inputSchema: z.object({
+                        args: z
+                            .record(z.string(), z.unknown())
+                            .optional()
+                            .describe('Arguments for the tool, per its description.'),
+                    }),
+                    execute: async ({ args }) => {
+                        const result = await useKee(ctx).tools.run(name, args ?? {});
+                        return { ok: true, tool: name, result };
+                    },
+                });
+                return [`kee__${name.replace(/[^a-z0-9]+/gi, '_')}`, tool];
+            });
+            return Object.fromEntries(pairs);
+        },
+    },
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.2.0",
-  "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections (and, soon, memory and shared tools) through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
+  "version": "0.4.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",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./tool-directory": {
+      "types": "./dist/tool-directory.d.ts",
+      "import": "./dist/tool-directory.js"
     }
   },
   "files": [