@keemakr/agent-sdk 0.4.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 }
   },
 });
@@ -82,34 +82,106 @@ await kee.connections.get("hunter").call("email-finder", { ... }); // equivalent
 const { access_token } = await kee.connections.hunter.token();
 ```
 
+### Discover connectors + operations
+
+`@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';
+
+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**.
+
+**Refresh the manifest** after core ships new connectors/operations (it's a committed snapshot of `GET /api/connections/catalog`):
+
+```bash
+curl -s "$KEE_CORE_URL/api/connections/catalog" > src/connectors.snapshot.json
+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`.
 
-## Security model
+## Autonomous / scheduled runs
+
+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:
 
-- **Tenant always comes from the verified grant**, resolved server-side. Never pass a tenant id from tool input.
-- **On the proxy path, credentials never leave keemakr-core.** You send operation args; core runs the third-party request with the tenant's credential and returns only the result.
-- **The token path is opt-in and scope-gated** (`conn:<provider>:token`), declared per dependency in your `entry.json` (`"access": "token"`).
+```ts
+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');
+// claims.tenantId, claims.scopes, claims.aud, claims.exp
+```
+
+Inside an eve channel, `grantAuth()` already accepts machine grants (same token shape) — no extra work.
+
+## Credential & model contract
+
+- **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.
 - Every capability call re-verifies the grant and enforces scope on the server.
 
+Full contract: keemakr-core `docs/CONNECTOR-CONTRACT.md`.
+
 ## License
 
 MIT

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/connectors.d.ts

@@ -0,0 +1,8 @@
+export { connectors, type ConnectorName, type ConnectorInfo, type ConnectorOp, type ConnectorOps, } from './connectors.generated.js';
+import { type ConnectorName } from './connectors.generated.js';
+/** All provider slugs in the manifest. */
+export declare function providerNames(): ConnectorName[];
+/** The operation names a provider exposes (empty for a coming_soon stub). */
+export declare function opNames(provider: ConnectorName): string[];
+/** True when the provider's connect path is proven and its operations are callable. */
+export declare function isReady(provider: ConnectorName): boolean;

package/dist/connectors.generated.d.ts

@@ -0,0 +1,276 @@
+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";
+/** 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;
+    "facebook": never;
+    "fal": never;
+    "hubspot": never;
+    "hunter": "email-finder";
+    "instagram": never;
+    "instantly": never;
+    "mailchimp": never;
+    "meta": never;
+    "pagespeed": never;
+    "posthog": never;
+    "salesforce": never;
+    "sendgrid": never;
+    "slack": never;
+    "stripe": never;
+    "twilio": never;
+    "whatsapp": never;
+    "wordpress": never;
+}
+export interface ConnectorOp {
+    description: string | null;
+    /** JSON Schema (draft 2020-12) for the operation's arguments. */
+    inputSchema: unknown;
+}
+export interface ConnectorInfo {
+    displayName: string;
+    authKind: string;
+    category: string | null;
+    /** 'ready' → connectable + operations callable; 'coming_soon' → declared, ops not yet wired. */
+    maturity: string;
+    docUrl: string | null;
+    ops: Record<string, ConnectorOp>;
+}
+/**
+ * The connector catalog as of the last snapshot refresh. Metadata only — no
+ * credentials. Keyed by provider slug; each entry lists its callable operations
+ * and their JSON-Schema arg contracts.
+ */
+export declare const connectors: {
+    readonly "agent-sessions": {
+        readonly displayName: "Agent Session Feed";
+        readonly authKind: "api_key";
+        readonly category: "voice";
+        readonly maturity: "ready";
+        readonly docUrl: null;
+        readonly ops: {};
+    };
+    readonly apify: {
+        readonly displayName: "Apify";
+        readonly authKind: "api_key";
+        readonly category: "scraping";
+        readonly maturity: "ready";
+        readonly docUrl: "https://docs.apify.com/api/v2";
+        readonly ops: {};
+    };
+    readonly apollo: {
+        readonly displayName: "Apollo.io";
+        readonly authKind: "api_key";
+        readonly category: "sales-intelligence";
+        readonly maturity: "ready";
+        readonly docUrl: "https://docs.apollo.io/reference/introduction";
+        readonly ops: {};
+    };
+    readonly "cal-com": {
+        readonly displayName: "Cal.com";
+        readonly authKind: "api_key";
+        readonly category: "scheduling";
+        readonly maturity: "ready";
+        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";
+        readonly category: "sales-intelligence";
+        readonly maturity: "ready";
+        readonly docUrl: "https://dashboard.clearbit.com/docs";
+        readonly ops: {};
+    };
+    readonly drip: {
+        readonly displayName: "Drip";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.drip.com/";
+        readonly ops: {};
+    };
+    readonly elevenlabs: {
+        readonly displayName: "ElevenLabs";
+        readonly authKind: "api_key";
+        readonly category: "voice";
+        readonly maturity: "ready";
+        readonly docUrl: "https://elevenlabs.io/docs/api-reference";
+        readonly ops: {};
+    };
+    readonly facebook: {
+        readonly displayName: "Facebook";
+        readonly authKind: "oauth2";
+        readonly category: "channel";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.facebook.com/docs/pages-api";
+        readonly ops: {};
+    };
+    readonly fal: {
+        readonly displayName: "fal.ai";
+        readonly authKind: "api_key";
+        readonly category: "media";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://fal.ai/docs";
+        readonly ops: {};
+    };
+    readonly hubspot: {
+        readonly displayName: "HubSpot";
+        readonly authKind: "api_key";
+        readonly category: "crm";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.hubspot.com/docs/api/private-apps";
+        readonly ops: {};
+    };
+    readonly hunter: {
+        readonly displayName: "Hunter.io";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://hunter.io/api-documentation/v2";
+        readonly ops: {
+            readonly "email-finder": {
+                readonly description: "Find a person's email address at a company domain by their name. Returns the email, a confidence score, and verification status.";
+                readonly inputSchema: {
+                    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly domain: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "Company domain, e.g. \"stripe.com\".";
+                        };
+                        readonly first_name: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "The person first name.";
+                        };
+                        readonly last_name: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                            readonly description: "The person last name.";
+                        };
+                    };
+                    readonly required: readonly ["domain", "first_name", "last_name"];
+                };
+            };
+        };
+    };
+    readonly instagram: {
+        readonly displayName: "Instagram";
+        readonly authKind: "oauth2";
+        readonly category: "channel";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developers.facebook.com/docs/instagram-platform";
+        readonly ops: {};
+    };
+    readonly instantly: {
+        readonly displayName: "Instantly.ai";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.instantly.ai/";
+        readonly ops: {};
+    };
+    readonly mailchimp: {
+        readonly displayName: "Mailchimp";
+        readonly authKind: "api_key";
+        readonly category: "email";
+        readonly maturity: "ready";
+        readonly docUrl: "https://mailchimp.com/developer/marketing/api/";
+        readonly ops: {};
+    };
+    readonly meta: {
+        readonly displayName: "Meta Ads (Marketing API)";
+        readonly authKind: "api_key";
+        readonly category: "advertising";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developers.facebook.com/docs/marketing-apis";
+        readonly ops: {};
+    };
+    readonly pagespeed: {
+        readonly displayName: "PageSpeed Insights";
+        readonly authKind: "api_key";
+        readonly category: "analytics";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://developers.google.com/speed/docs/insights/v5/get-started";
+        readonly ops: {};
+    };
+    readonly posthog: {
+        readonly displayName: "PostHog";
+        readonly authKind: "api_key";
+        readonly category: "analytics";
+        readonly maturity: "ready";
+        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";
+        readonly category: "email";
+        readonly maturity: "ready";
+        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";
+        readonly category: "payments";
+        readonly maturity: "coming_soon";
+        readonly docUrl: "https://docs.stripe.com/connect/oauth-reference";
+        readonly ops: {};
+    };
+    readonly twilio: {
+        readonly displayName: "Twilio";
+        readonly authKind: "api_key";
+        readonly category: "sms";
+        readonly maturity: "ready";
+        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";
+        readonly category: "cms";
+        readonly maturity: "ready";
+        readonly docUrl: "https://developer.wordpress.com/docs/oauth2/";
+        readonly ops: {};
+    };
+};

package/dist/connectors.generated.js

@@ -0,0 +1,240 @@
+// AUTO-GENERATED by scripts/gen-connectors.mjs — DO NOT EDIT BY HAND.
+// Source: src/connectors.snapshot.json (a committed copy of keemakr-core's
+// GET /api/connections/catalog). Refresh: see scripts/gen-connectors.mjs header.
+/**
+ * The connector catalog as of the last snapshot refresh. Metadata only — no
+ * credentials. Keyed by provider slug; each entry lists its callable operations
+ * and their JSON-Schema arg contracts.
+ */
+export const connectors = {
+    "agent-sessions": {
+        "displayName": "Agent Session Feed",
+        "authKind": "api_key",
+        "category": "voice",
+        "maturity": "ready",
+        "docUrl": null,
+        "ops": {}
+    },
+    "apify": {
+        "displayName": "Apify",
+        "authKind": "api_key",
+        "category": "scraping",
+        "maturity": "ready",
+        "docUrl": "https://docs.apify.com/api/v2",
+        "ops": {}
+    },
+    "apollo": {
+        "displayName": "Apollo.io",
+        "authKind": "api_key",
+        "category": "sales-intelligence",
+        "maturity": "ready",
+        "docUrl": "https://docs.apollo.io/reference/introduction",
+        "ops": {}
+    },
+    "cal-com": {
+        "displayName": "Cal.com",
+        "authKind": "api_key",
+        "category": "scheduling",
+        "maturity": "ready",
+        "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",
+        "category": "sales-intelligence",
+        "maturity": "ready",
+        "docUrl": "https://dashboard.clearbit.com/docs",
+        "ops": {}
+    },
+    "drip": {
+        "displayName": "Drip",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://developer.drip.com/",
+        "ops": {}
+    },
+    "elevenlabs": {
+        "displayName": "ElevenLabs",
+        "authKind": "api_key",
+        "category": "voice",
+        "maturity": "ready",
+        "docUrl": "https://elevenlabs.io/docs/api-reference",
+        "ops": {}
+    },
+    "facebook": {
+        "displayName": "Facebook",
+        "authKind": "oauth2",
+        "category": "channel",
+        "maturity": "ready",
+        "docUrl": "https://developers.facebook.com/docs/pages-api",
+        "ops": {}
+    },
+    "fal": {
+        "displayName": "fal.ai",
+        "authKind": "api_key",
+        "category": "media",
+        "maturity": "coming_soon",
+        "docUrl": "https://fal.ai/docs",
+        "ops": {}
+    },
+    "hubspot": {
+        "displayName": "HubSpot",
+        "authKind": "api_key",
+        "category": "crm",
+        "maturity": "ready",
+        "docUrl": "https://developers.hubspot.com/docs/api/private-apps",
+        "ops": {}
+    },
+    "hunter": {
+        "displayName": "Hunter.io",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://hunter.io/api-documentation/v2",
+        "ops": {
+            "email-finder": {
+                "description": "Find a person's email address at a company domain by their name. Returns the email, a confidence score, and verification status.",
+                "inputSchema": {
+                    "$schema": "https://json-schema.org/draft/2020-12/schema",
+                    "type": "object",
+                    "properties": {
+                        "domain": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "Company domain, e.g. \"stripe.com\"."
+                        },
+                        "first_name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "The person first name."
+                        },
+                        "last_name": {
+                            "type": "string",
+                            "minLength": 1,
+                            "description": "The person last name."
+                        }
+                    },
+                    "required": [
+                        "domain",
+                        "first_name",
+                        "last_name"
+                    ]
+                }
+            }
+        }
+    },
+    "instagram": {
+        "displayName": "Instagram",
+        "authKind": "oauth2",
+        "category": "channel",
+        "maturity": "ready",
+        "docUrl": "https://developers.facebook.com/docs/instagram-platform",
+        "ops": {}
+    },
+    "instantly": {
+        "displayName": "Instantly.ai",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://developer.instantly.ai/",
+        "ops": {}
+    },
+    "mailchimp": {
+        "displayName": "Mailchimp",
+        "authKind": "api_key",
+        "category": "email",
+        "maturity": "ready",
+        "docUrl": "https://mailchimp.com/developer/marketing/api/",
+        "ops": {}
+    },
+    "meta": {
+        "displayName": "Meta Ads (Marketing API)",
+        "authKind": "api_key",
+        "category": "advertising",
+        "maturity": "coming_soon",
+        "docUrl": "https://developers.facebook.com/docs/marketing-apis",
+        "ops": {}
+    },
+    "pagespeed": {
+        "displayName": "PageSpeed Insights",
+        "authKind": "api_key",
+        "category": "analytics",
+        "maturity": "coming_soon",
+        "docUrl": "https://developers.google.com/speed/docs/insights/v5/get-started",
+        "ops": {}
+    },
+    "posthog": {
+        "displayName": "PostHog",
+        "authKind": "api_key",
+        "category": "analytics",
+        "maturity": "ready",
+        "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",
+        "category": "email",
+        "maturity": "ready",
+        "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",
+        "category": "payments",
+        "maturity": "coming_soon",
+        "docUrl": "https://docs.stripe.com/connect/oauth-reference",
+        "ops": {}
+    },
+    "twilio": {
+        "displayName": "Twilio",
+        "authKind": "api_key",
+        "category": "sms",
+        "maturity": "ready",
+        "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",
+        "category": "cms",
+        "maturity": "ready",
+        "docUrl": "https://developer.wordpress.com/docs/oauth2/",
+        "ops": {}
+    }
+};

package/dist/connectors.js

@@ -0,0 +1,28 @@
+// @keemakr/agent-sdk/connectors — the generated connector manifest.
+//
+// A typed, metadata-only view of keemakr-core's connector catalog so an agent
+// author (and the port kit) can discover providers + operation names + their arg
+// schemas WITHOUT scanning a core checkout or hitting a running instance. Credential-
+// free by construction — this is the same data GET /api/connections/catalog serves,
+// committed as a snapshot (src/connectors.snapshot.json) and codegen'd into
+// connectors.generated.ts. Refresh: see scripts/gen-connectors.mjs.
+//
+// Usage:
+//   import { connectors, opNames } from '@keemakr/agent-sdk/connectors';
+//   connectors.hunter.ops['email-finder'].inputSchema; // JSON Schema for the args
+//   opNames('meta');                                    // string[] of meta's op names
+//   isReady('meta');                                    // false while coming_soon
+export { connectors, } from './connectors.generated.js';
+import { connectors } from './connectors.generated.js';
+/** All provider slugs in the manifest. */
+export function providerNames() {
+    return Object.keys(connectors);
+}
+/** The operation names a provider exposes (empty for a coming_soon stub). */
+export function opNames(provider) {
+    return Object.keys(connectors[provider]?.ops ?? {});
+}
+/** True when the provider's connect path is proven and its operations are callable. */
+export function isReady(provider) {
+    return connectors[provider]?.maturity === 'ready';
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { grantAuth } from './grant-auth.js';
-export { useKee, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeTools, type MemoryEntry, type MemorySearchHit, } from './client.js';
+export { verifyGrant, type VerifiedGrant } from './verify-grant.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

@@ -9,5 +9,6 @@
 //   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 { verifyGrant } from './verify-grant.js';
+export { useKee, MemoryConflictError, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';

package/dist/verify-grant.d.ts

@@ -0,0 +1,20 @@
+/** Trusted claims after verifyGrant() succeeds. */
+export interface VerifiedGrant {
+    tenantId: string;
+    installedAgent: string | null;
+    scopes: string[];
+    traceId: string | null;
+    aud: string | null;
+    exp: number | null;
+}
+/**
+ * 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.
+ */
+export declare function verifyGrant(token: string, opts?: {
+    jwksUrl?: string;
+    audience?: string;
+}): Promise<VerifiedGrant | null>;

package/dist/verify-grant.js

@@ -0,0 +1,52 @@
+// Standalone capability-grant verification — for a scheduled/headless remote.
+//
+// grantAuth() (grant-auth.ts) is the right entry point for an eve CHANNEL: it
+// returns an AuthFn. But an autonomous/machine turn may run OUTSIDE a channel (a
+// cron worker that received a machine grant from core's machine-grant endpoint
+// and wants to verify it before acting). verifyGrant() is that path: give it the
+// token, get back the trusted claims (or null), verifying signature + issuer +
+// audience against core's JWKS.
+//
+// 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';
+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.
+ */
+export async function verifyGrant(token, opts) {
+    const jwksUrl = opts?.jwksUrl ?? process.env.KEE_CORE_JWKS_URL;
+    if (!jwksUrl)
+        return null;
+    const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
+    try {
+        const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
+            issuer: GRANT_ISSUER,
+            ...(expectedAud ? { audience: expectedAud } : {}),
+        });
+        if (typeof payload.tenant_id !== 'string' || !Array.isArray(payload.scopes))
+            return null;
+        return {
+            tenantId: payload.tenant_id,
+            installedAgent: typeof payload.installed_agent === 'string' ? payload.installed_agent : null,
+            scopes: payload.scopes.map(String),
+            traceId: typeof payload.trace_id === 'string' ? payload.trace_id : null,
+            aud: typeof payload.aud === 'string' ? payload.aud : null,
+            exp: typeof payload.exp === 'number' ? payload.exp : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.4.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",
@@ -14,6 +14,10 @@
     "./tool-directory": {
       "types": "./dist/tool-directory.d.ts",
       "import": "./dist/tool-directory.js"
+    },
+    "./connectors": {
+      "types": "./dist/connectors.d.ts",
+      "import": "./dist/connectors.js"
     }
   },
   "files": [
@@ -25,11 +29,13 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fsztpartners/keemakr-agent-sdk.git"
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/agent-sdk"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc --noEmit",
+    "gen:connectors": "node scripts/gen-connectors.mjs",
+    "build": "npm run gen:connectors && tsc -p tsconfig.json",
+    "typecheck": "npm run gen:connectors && tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {