@keemakr/agent-sdk 0.1.0 → 0.3.0

package/dist/client.d.ts

@@ -20,6 +20,44 @@ export interface KeeConnection {
         account_label: string | null;
     }>;
 }
+/** One stored memory entry. */
+export interface MemoryEntry {
+    namespace: string;
+    key: string;
+    value: unknown;
+    written_by_agent: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Cross-session, tenant-owned key-value memory. TENANT-SHARED: any of the
+ * tenant's installed agents can read/write any namespace. For per-session working
+ * memory use eve's defineState instead — this is for state that must outlive the
+ * session. Requires the `memory:rw` scope.
+ */
+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. */
+    getEntry(namespace: string, key: string): Promise<MemoryEntry | null>;
+    /** Write a key. Returns the stored entry. */
+    set(namespace: string, key: string, value: unknown): Promise<MemoryEntry>;
+    /** Delete a key. Returns whether it existed. */
+    delete(namespace: string, key: string): Promise<boolean>;
+    /** List every entry in a namespace (tenant-wide). */
+    list(namespace: string): Promise<MemoryEntry[]>;
+}
+/** 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;
     scopes: string[];
@@ -27,6 +65,8 @@ export interface Kee {
         /** Explicit accessor (equivalent to kee.connections[provider]). */
         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

@@ -32,16 +32,17 @@ function coreBaseUrl() {
         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');
 }
-async function capabilityFetch(grant, path, body) {
+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: 'POST',
+        method,
         headers: {
-            'content-type': 'application/json',
+            ...(hasBody ? { 'content-type': 'application/json' } : {}),
             authorization: `Bearer ${grant.token}`,
             ...(grant.traceId ? { 'x-keemakr-trace-id': grant.traceId } : {}),
         },
-        body: JSON.stringify(body ?? {}),
+        ...(hasBody ? { body: JSON.stringify(body ?? {}) } : {}),
     });
     const json = (await res.json().catch(() => ({})));
     if (!res.ok) {
@@ -74,5 +75,47 @@ export function useKee(ctx) {
             return connectionFor(prop);
         },
     });
-    return { tenantId: grant.tenantId, scopes: grant.scopes, connections };
+    const enc = encodeURIComponent;
+    const memory = {
+        async getEntry(namespace, key) {
+            try {
+                const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, undefined, 'GET'));
+                return json.entry ?? null;
+            }
+            catch (e) {
+                if (e.status === 404)
+                    return null;
+                throw e;
+            }
+        },
+        async get(namespace, key) {
+            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 delete(namespace, key) {
+            const json = (await capabilityFetch(grant, `memory/${enc(namespace)}/${enc(key)}`, undefined, 'DELETE'));
+            return !!json.deleted;
+        },
+        async list(namespace) {
+            const json = (await capabilityFetch(grant, `memory/${enc(namespace)}`, undefined, 'GET'));
+            return json.entries ?? [];
+        },
+    };
+    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, 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 } from './client.js';
+export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeTools, type MemoryEntry, } from './client.js';
+export { keemakrToolDirectory } from './tool-directory.js';

package/dist/index.js

@@ -9,4 +9,5 @@
 //   const kee = useKee(ctx);
 //   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 { 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.1.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.3.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": [