@keemakr/agent-sdk 0.15.0 → 0.16.0-dev-20260925092950

package/dist/canvases.d.ts

@@ -0,0 +1,49 @@
+/** Any card. Open by construction: a client may render a `type` this SDK predates. */
+export type Canvas = {
+    type: string;
+} & Record<string, unknown>;
+/** A titled markdown document — a run summary, a written answer, a table of results. */
+export interface ReportCanvas {
+    type: 'report';
+    markdown: string;
+    title?: string;
+}
+/**
+ * A picture, shown inline in the chat.
+ *
+ * Prefer this over putting the URL in `reply`. Clients do preview a URL a reply merely names, but
+ * the card is the better copy on both sides of the wire: core validates the URL at ingestion, the
+ * card carries its own alt text and dimensions, and a client that shows the card suppresses the
+ * duplicate preview of the same URL in your prose.
+ */
+export interface ImageCanvas {
+    type: 'image';
+    url: string;
+    /** What the picture shows. This is the fallback text, so write it for someone who cannot see it. */
+    alt?: string;
+    /** The prompt that produced it, when it was generated. Shown as a caption. */
+    prompt?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Build an image card, refusing a URL that would not reach a reader.
+ *
+ * Two different things drop a URL on the way, and both are silent from here — the delegation
+ * succeeds, the card never appears, and nothing in your logs says why:
+ *
+ *  - Core's ingestion default-denies anything that is not http(s). A `data:`, `file:` or
+ *    `javascript:` URL is never persisted.
+ *  - The dashboards are served over https, so an `http:` image is mixed content the browser
+ *    refuses after upgrading the request. Core stores it happily; nobody ever sees it.
+ *
+ * So this is stricter than ingestion on purpose: https only. Throwing at construction turns a
+ * picture that quietly never arrives into an error where the mistake was made.
+ */
+export declare function imageCanvas(input: {
+    url: string;
+    alt?: string;
+    prompt?: string;
+    width?: number;
+    height?: number;
+}): ImageCanvas;

package/dist/canvases.js

@@ -0,0 +1,47 @@
+// Canvases — the inline cards an agent's reply can carry back to the Operator.
+//
+// A department returns `canvases` on its DelegationResult and core persists each one as a content
+// block the clients render. The wire is deliberately permissive (core validates a canvas is
+// `{ type, … }` and nothing more, so a client that knows a card can render it even if core has
+// never heard of it), which is right for the pipe and unhelpful when you are writing the agent:
+// nothing tells you a card exists, what it is called, or which fields it needs.
+//
+// So this is a floor, not a schema. The types name the cards clients render today, and the helper
+// refuses the one mistake that is silent end to end — a URL core will drop at ingestion, leaving
+// an agent that believes it delivered a picture and a user who sees nothing.
+/**
+ * Build an image card, refusing a URL that would not reach a reader.
+ *
+ * Two different things drop a URL on the way, and both are silent from here — the delegation
+ * succeeds, the card never appears, and nothing in your logs says why:
+ *
+ *  - Core's ingestion default-denies anything that is not http(s). A `data:`, `file:` or
+ *    `javascript:` URL is never persisted.
+ *  - The dashboards are served over https, so an `http:` image is mixed content the browser
+ *    refuses after upgrading the request. Core stores it happily; nobody ever sees it.
+ *
+ * So this is stricter than ingestion on purpose: https only. Throwing at construction turns a
+ * picture that quietly never arrives into an error where the mistake was made.
+ */
+export function imageCanvas(input) {
+    let parsed;
+    try {
+        parsed = new URL(input.url);
+    }
+    catch {
+        throw new TypeError(`imageCanvas: not a URL: ${input.url}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new TypeError(`imageCanvas: images must be https; "${parsed.protocol}" either never reaches the ` +
+            'transcript (core drops non-http(s) at ingestion) or is blocked as mixed content by the ' +
+            'browser that would show it');
+    }
+    return {
+        type: 'image',
+        url: input.url,
+        ...(input.alt === undefined ? {} : { alt: input.alt }),
+        ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+        ...(input.width === undefined ? {} : { width: input.width }),
+        ...(input.height === undefined ? {} : { height: input.height }),
+    };
+}

package/dist/channel-testkit.d.ts

@@ -0,0 +1,56 @@
+import type { ChannelAction } from './channel.js';
+export interface KbFixture {
+    chunkId: string;
+    title: string | null;
+    text: string;
+    score?: number;
+}
+export interface FakeCoreOptions {
+    /** What `ctx.kb.search()` returns. A function, so a fixture can vary by query. */
+    kb?: KbFixture[] | ((query: string) => KbFixture[]);
+    /** What `ctx.history()` returns. */
+    history?: Array<{
+        body: string;
+        authorKind: string;
+        position: number;
+    }>;
+    tenantId?: string;
+}
+export interface Delivered {
+    /** What the pack posted back, or null if it never did. */
+    action: (ChannelAction & Record<string, unknown>) | null;
+    /** The HTTP status the pack answered the delivery with. */
+    status: number;
+}
+export interface FakeCore {
+    /** Point the pack here: its `coreUrl`, and the issuer of every grant below. */
+    url: string;
+    /** And here: the audience every minted grant will name. */
+    audienceFor(packUrl: string): string;
+    /**
+     * Deliver a customer message to a pack and wait for its answer.
+     *
+     * Waits for the POST-BACK rather than for the 202, because the 202 means only that the
+     * pack accepted the work. A test that asserted on the acknowledgement would pass against
+     * a pack that never answers — which is the single commonest way a first pack is broken.
+     */
+    deliver(input: {
+        to: string;
+        text: string | string[];
+        conversationId?: string;
+        deliveryId?: string;
+        contact?: {
+            id: string;
+            handle: string | null;
+            name: string | null;
+        };
+        binding?: Record<string, unknown>;
+        language?: {
+            customer: string | null;
+        };
+        contract?: number;
+        timeoutMs?: number;
+    }): Promise<Delivered>;
+    close(): Promise<void>;
+}
+export declare function startFakeCore(options?: FakeCoreOptions): Promise<FakeCore>;

package/dist/channel-testkit.js

@@ -0,0 +1,136 @@
+// A core that is not running, for proving a pack before anything is deployed.
+//
+// WHAT THIS IS FOR. Today the shortest path to knowing whether a pack works is: deploy it,
+// publish an entry, install it on a tenant, bind it to a channel, send a real message, and
+// then read the database. Every one of those steps can fail for reasons that have nothing
+// to do with the pack, and the failure looks the same from the author's side — core's own
+// e2e script says so in its comments: "a dispatch that never reached it and an answer that
+// never came back look identical from here".
+//
+// So this mints grants with a real keypair, serves the three endpoints a pack actually
+// calls, receives the post-back, and hands it to you. A pack test becomes: deliver this,
+// assert that.
+//
+// IT REFUSES TO RUN IN PRODUCTION. It mints grants that its own JWKS validates, which is
+// the whole point in a test and a way to accept forged grants anywhere else.
+import { createServer } from 'node:http';
+import { exportJWK, generateKeyPair, SignJWT } from 'jose';
+const UUID_NS = '00000000-0000-4000-8000-0000000000';
+export async function startFakeCore(options = {}) {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error('[keemakr] startFakeCore mints grants its own JWKS validates. That is the point in a ' +
+            'test and a way to accept forged grants anywhere else — it refuses to run in production.');
+    }
+    const tenantId = options.tenantId ?? `${UUID_NS}01`;
+    const { publicKey, privateKey } = await generateKeyPair('RS256');
+    const jwk = { ...(await exportJWK(publicKey)), kid: 'testkit', alg: 'RS256', use: 'sig' };
+    /** Resolved when a pack posts its answer back for a given delivery. */
+    const waiting = new Map();
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const json = (status, body) => {
+            res.writeHead(status, { 'content-type': 'application/json' });
+            res.end(JSON.stringify(body));
+        };
+        if (url.pathname === '/.well-known/jwks.json')
+            return json(200, { keys: [jwk] });
+        if (url.pathname === '/api/capability/kb/retrieve') {
+            let raw = '';
+            req.on('data', (c) => (raw += c));
+            req.on('end', () => {
+                const query = JSON.parse(raw || '{}').query ?? '';
+                const hits = typeof options.kb === 'function' ? options.kb(query) : (options.kb ?? []);
+                json(200, {
+                    hits: hits.map((h) => ({
+                        chunk_id: h.chunkId,
+                        title: h.title,
+                        text: h.text,
+                        score: h.score ?? 0.5,
+                    })),
+                });
+            });
+            return;
+        }
+        if (url.pathname.endsWith('/actions')) {
+            let raw = '';
+            req.on('data', (c) => (raw += c));
+            req.on('end', () => {
+                const action = JSON.parse(raw || '{}');
+                const resolve = waiting.get(String(action.delivery_id));
+                if (resolve) {
+                    waiting.delete(String(action.delivery_id));
+                    resolve(action);
+                }
+                json(200, { ok: true });
+            });
+            return;
+        }
+        // Everything else is the history read.
+        return json(200, { messages: options.history ?? [] });
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const port = server.address().port;
+    const url = `http://127.0.0.1:${port}`;
+    async function mint(conversationId, audience) {
+        return new SignJWT({
+            tenant_id: tenantId,
+            channel_conversation_id: conversationId,
+            // The REAL ceiling, not a permissive one. A testkit that minted broader scopes than
+            // core does would let a pack pass its own tests while calling something production
+            // refuses — which is worse than no test, because it is a test that lies.
+            scopes: ['channel:history', 'channel:respond', 'kb:retrieve'],
+            external_kee: true,
+            trace_id: `testkit-${Date.now()}`,
+        })
+            .setProtectedHeader({ alg: 'RS256', kid: 'testkit' })
+            .setIssuer('keemakr')
+            .setAudience(audience)
+            .setExpirationTime('5m')
+            .sign(privateKey);
+    }
+    return {
+        url,
+        audienceFor(packUrl) {
+            return new URL(packUrl).origin;
+        },
+        async deliver(input) {
+            const conversationId = input.conversationId ?? `${UUID_NS}c1`;
+            const deliveryId = input.deliveryId ?? `${UUID_NS}d${Math.floor(Math.random() * 90 + 10)}`;
+            const bodies = Array.isArray(input.text) ? input.text : [input.text];
+            const token = await mint(conversationId, new URL(input.to).origin);
+            const answered = new Promise((resolve) => {
+                waiting.set(deliveryId, resolve);
+                setTimeout(() => {
+                    if (waiting.delete(deliveryId))
+                        resolve(null);
+                }, input.timeoutMs ?? 10_000).unref?.();
+            });
+            const res = await fetch(input.to, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${token}`,
+                    'content-type': 'application/json',
+                    'idempotency-key': deliveryId,
+                },
+                body: JSON.stringify({
+                    event: 'message.received',
+                    delivery_id: deliveryId,
+                    conversation: { id: conversationId },
+                    contact: input.contact ?? { id: `${UUID_NS}a1`, handle: 'v_test', name: null },
+                    unanswered_messages: bodies.map((body, i) => ({ body, position: i + 1 })),
+                    truncated_messages: 0,
+                    ...(input.contract !== undefined ? { contract: input.contract } : {}),
+                    ...(input.binding ? { binding: input.binding } : {}),
+                    ...(input.language ? { language: input.language } : {}),
+                }),
+            });
+            return {
+                status: res.status,
+                action: (await answered),
+            };
+        },
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/channel.d.ts

@@ -0,0 +1,159 @@
+/** The envelope core POSTs. Loose by rule — core adds fields without asking packs first. */
+export interface ChannelDelivery {
+    event: string;
+    delivery_id: string;
+    conversation: {
+        id: string;
+    };
+    contact: {
+        id: string;
+        handle: string | null;
+        name: string | null;
+    };
+    unanswered_messages: Array<{
+        body: string;
+        position: number;
+    }>;
+    truncated_messages: number;
+    contract?: number;
+    binding?: {
+        id: string;
+        autonomy: 'supervised' | 'assisted' | 'autonomous';
+        settings: Record<string, unknown>;
+        settings_version: number;
+    };
+    language?: {
+        customer: string | null;
+    };
+    [key: string]: unknown;
+}
+/** What a pack proposes. Core decides what happens to it. */
+export type ChannelAction = {
+    action: 'reply';
+    text: string;
+    confidence?: number;
+    grounded_on?: string[];
+    usage: Usage;
+} | {
+    action: 'handoff';
+    reason: HandoffReason;
+    usage: Usage;
+} | {
+    action: 'none';
+    usage: Usage;
+};
+export type HandoffReason = 'customer_requested' | 'no_answer' | 'agent_failed';
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface ChannelContext {
+    tenantId: string;
+    conversationId: string;
+    deliveryId: string;
+    /** THE WHOLE UNANSWERED RUN. A customer who split a question across three bubbles asked
+     *  one question, and a pack handed only the newest line answers the fragment. */
+    messages: Array<{
+        body: string;
+        position: number;
+    }>;
+    /** How many OLDER messages did not fit the tenant's budget. Said, not hidden. */
+    truncated: number;
+    contact: {
+        id: string;
+        handle: string | null;
+        name: string | null;
+    };
+    /** What this business wants its agent to be. Absent against a core that predates it. */
+    binding?: ChannelDelivery['binding'];
+    /** The customer's apparent language, or null when core looked and could not say. */
+    language?: {
+        customer: string | null;
+    };
+    /** Earlier turns in this conversation, under `channel:history`. */
+    history(limit?: number): Promise<Array<{
+        body: string;
+        authorKind: string;
+        position: number;
+    }>>;
+    /** This tenant's customer-safe knowledge, under `kb:retrieve`. */
+    kb: {
+        search(query: string, opts?: {
+            limit?: number;
+        }): Promise<Array<{
+            chunkId: string;
+            title: string | null;
+            text: string;
+            score: number;
+        }>>;
+    };
+    /** Pure builders. They construct an action; they do not send anything. */
+    reply(text: string, opts?: {
+        confidence?: number;
+        groundedOn?: string[];
+        usage?: Usage;
+    }): ChannelAction;
+    handoff(reason: HandoffReason, opts?: {
+        usage?: Usage;
+    }): ChannelAction;
+    none(opts?: {
+        usage?: Usage;
+    }): ChannelAction;
+}
+export interface ChannelAgentOptions {
+    /**
+     * The core this pack answers for.
+     *
+     * Everything trusted flows from here: the JWKS that proves a grant is real, and the API
+     * the answer is posted back to. A wrong value is not a broken pack — it is a pack that
+     * trusts somebody else's signatures, so it is validated at construction rather than at
+     * the first request.
+     */
+    coreUrl?: string;
+    /**
+     * The audience every grant must name, and it is REQUIRED here even though `verifyGrant`
+     * tolerates its absence.
+     *
+     * Without it a grant minted for any other deployment of any other pack verifies against
+     * this one. `verifyGrant` keeps the lenient behaviour because packs depend on it today;
+     * a helper being written for the first time has no such excuse.
+     */
+    audience: string;
+    /** The one function a pack author writes. */
+    answer: (ctx: ChannelContext) => Promise<ChannelAction> | ChannelAction;
+    /** The platform's keep-alive. On Vercel: `waitUntil` from `@vercel/functions`. */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /** Injected for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Refuse a core URL that cannot be trusted, at construction.
+ *
+ * The JWKS URL is derived from this with no scheme check anywhere below, so a pack pointed
+ * at `http://` fetches its trust anchor over a connection anybody on the path can rewrite —
+ * which means anybody on the path can mint grants it will accept. Loopback is exempted
+ * because local development is the reason the check is survivable at all, and loopback is
+ * then refused under NODE_ENV=production because "it worked on my machine" is precisely how
+ * that exemption reaches a deployment.
+ */
+export declare function assertTrustworthyCore(raw: string): URL;
+export interface ChannelAgent {
+    /** For a fetch-style platform (Vercel, Workers, Bun, Deno). */
+    fetchHandler(req: Request, ctx?: {
+        waitUntil?: (p: Promise<unknown>) => void;
+    }): Promise<Response>;
+    /**
+     * The same answer, computed INLINE and returned rather than posted back.
+     *
+     * WHY A SEPARATE HANDLER AND NOT A FLAG. The delivery path is asynchronous because a real
+     * customer's turn must survive the pack being slow; a preview is somebody staring at a
+     * settings drawer, where an answer that arrives on a later request is no answer at all.
+     * Same verification, same context, same `answer` — only the ending differs.
+     *
+     * It writes nothing. The grant core mints for this names a conversation that does not
+     * exist, so the post-back route would refuse it anyway; returning the proposal is the
+     * honest shape rather than a side effect somebody has to remember to suppress.
+     */
+    previewHandler(req: Request): Promise<Response>;
+}
+export declare function createChannelAgent(options: ChannelAgentOptions): ChannelAgent;

package/dist/channel.js

@@ -0,0 +1,359 @@
+// Answering a customer on a channel, without writing the security-critical half yourself.
+//
+// WHAT THIS REPLACES. The reference pack hand-rolled seventy-eight lines of grant
+// verification, because `verifyGrant` drops the one claim a channel turn depends on — the
+// conversation this grant is bound to — and it parsed an envelope that existed only as an
+// inline object literal inside core. Every pack after it would have copied that file, and a
+// copy of security-critical code is a copy that stops being reviewed.
+//
+// THE SHAPE OF THE CONTRACT, which is not obvious and is the thing most first packs get
+// wrong: core POSTs a delivery, the pack ACKNOWLEDGES within seconds, and the answer comes
+// back later on a SEPARATE request. Holding the connection open for the whole think is what
+// a first implementation does and what a serverless platform kills. So `answer` runs after
+// the response, inside the platform's `waitUntil`, and the helper posts the result back.
+//
+// `answer` RETURNS its action rather than calling something. That makes "exactly one
+// proposal per delivery" a property of the type rather than of everybody remembering, and
+// it makes `answer` a pure function that can be unit-tested with no core at all — fake or
+// otherwise.
+import { createRemoteJWKSet, customFetch, jwtVerify } from 'jose';
+import { jwksUrlFor, resolveJwksUrl } from './jwks.js';
+const GRANT_ISSUER = 'keemakr';
+/** The only delivery-envelope version this SDK speaks. */
+const SUPPORTED_CONTRACT = 1;
+/** How long a delivery id is remembered, so a core retry does not pay for a second think. */
+const SEEN_TTL_MS = 90_000;
+const SEEN_MAX = 500;
+/**
+ * Refuse a core URL that cannot be trusted, at construction.
+ *
+ * The JWKS URL is derived from this with no scheme check anywhere below, so a pack pointed
+ * at `http://` fetches its trust anchor over a connection anybody on the path can rewrite —
+ * which means anybody on the path can mint grants it will accept. Loopback is exempted
+ * because local development is the reason the check is survivable at all, and loopback is
+ * then refused under NODE_ENV=production because "it worked on my machine" is precisely how
+ * that exemption reaches a deployment.
+ */
+export function assertTrustworthyCore(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`[keemakr] KEE_CORE_URL is not a URL: ${raw}`);
+    }
+    const loopback = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+    if (url.protocol !== 'https:' && !loopback) {
+        throw new Error(`[keemakr] refusing to trust ${url.origin} over ${url.protocol} — the JWKS fetched ` +
+            'from it is what proves a grant is real, so anybody on the path could mint grants ' +
+            'this pack accepts. Use https, or localhost for development.');
+    }
+    if (loopback && process.env.NODE_ENV === 'production') {
+        throw new Error(`[keemakr] refusing to trust ${url.origin} in production — a deployed pack pointed at ` +
+            'loopback verifies nothing.');
+    }
+    return url;
+}
+/** Verify, keeping the claim `verifyGrant` drops. */
+async function verifyChannelGrant(token, keys, audience) {
+    try {
+        const { payload } = await jwtVerify(token, keys, {
+            issuer: GRANT_ISSUER,
+            audience,
+        });
+        if (typeof payload.tenant_id !== 'string' || !Array.isArray(payload.scopes))
+            return null;
+        return {
+            tenantId: payload.tenant_id,
+            // THE CLAIM THE WHOLE LANE RESTS ON, and the one `verifyGrant` throws away. Without
+            // it a live grant can post an answer into ANY conversation in the tenant for its
+            // whole life — Idempotency-Key is deduplication, not authorization.
+            conversationId: typeof payload.channel_conversation_id === 'string'
+                ? payload.channel_conversation_id
+                : null,
+            scopes: payload.scopes.map(String),
+            traceId: typeof payload.trace_id === 'string' ? payload.trace_id : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Remembered deliveries, so core's retry does not buy a second model call. */
+class SeenDeliveries {
+    seen = new Map();
+    /** True if this is new. Keyed on VERIFIED ids only — see the note at the call site. */
+    admit(key, now) {
+        for (const [k, at] of this.seen) {
+            if (now - at > SEEN_TTL_MS)
+                this.seen.delete(k);
+        }
+        if (this.seen.has(key))
+            return false;
+        if (this.seen.size >= SEEN_MAX) {
+            const oldest = this.seen.keys().next().value;
+            if (oldest !== undefined)
+                this.seen.delete(oldest);
+        }
+        this.seen.set(key, now);
+        return true;
+    }
+    forget(key) {
+        this.seen.delete(key);
+    }
+}
+export function createChannelAgent(options) {
+    if (!options.audience?.trim()) {
+        // AT CONSTRUCTION, not at the first delivery. A pack that boots and then refuses every
+        // customer looks like a broken product; a pack that refuses to boot looks like a
+        // missing environment variable, which is what it is.
+        throw new Error("[keemakr] createChannelAgent needs an `audience`: this deployment's exact origin, " +
+            "the same URL registered as the entry's runtime. Without it a grant minted for any " +
+            'other pack verifies here.');
+    }
+    const coreRaw = options.coreUrl ?? process.env.KEE_CORE_URL;
+    if (!coreRaw) {
+        throw new Error('[keemakr] createChannelAgent needs `coreUrl` or KEE_CORE_URL.');
+    }
+    const core = assertTrustworthyCore(coreRaw);
+    const jwksUrl = resolveJwksUrl() ?? jwksUrlFor(core.origin);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    // The keyset fetches through the SAME fetch as everything else. Its own cache is what
+    // makes this one round trip per key rotation rather than one per delivery, and routing it
+    // through the injected fetch is what lets a test — or a pack behind a proxy — serve it.
+    const keys = createRemoteJWKSet(new URL(jwksUrl), { [customFetch]: fetchImpl });
+    const seen = new SeenDeliveries();
+    // SAID AT BOOT, once. A pack pointed at the wrong core fails in a way that looks like a
+    // core outage from every angle except this line.
+    console.log(`[keemakr] channel agent trusting ${core.origin} (audience ${options.audience})`);
+    async function handle(req, waitUntil) {
+        const bearer = req.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ?? '';
+        if (!bearer)
+            return refuse(401, 'no_grant');
+        const claims = await verifyChannelGrant(bearer, keys, options.audience);
+        if (!claims)
+            return refuse(401, 'grant_invalid');
+        if (!claims.scopes.includes('channel:respond'))
+            return refuse(403, 'missing_channel_respond');
+        let body;
+        try {
+            body = (await req.json());
+        }
+        catch {
+            return refuse(400, 'invalid_json');
+        }
+        // THE GRANT NAMES ONE CONVERSATION, and this is where that is enforced. The reference
+        // pack parsed this claim and never compared it, which made the binding decorative.
+        if (!claims.conversationId || claims.conversationId !== body.conversation?.id) {
+            return refuse(403, 'conversation_mismatch');
+        }
+        // A CONTRACT THIS SDK DOES NOT SPEAK IS A REFUSAL, NOT A GUESS. Absent means a core
+        // that predates the field. Anything else means core has changed the envelope's SHAPE,
+        // and answering it with v1 assumptions is how a pack confidently misreads a customer.
+        if (body.contract !== undefined && body.contract !== SUPPORTED_CONTRACT) {
+            return refuse(400, 'contract_unsupported');
+        }
+        // DEDUPED AFTER VERIFICATION, on ids the signature vouches for. Keying on the raw
+        // Idempotency-Key header would let an unauthenticated caller suppress a real delivery
+        // by guessing one, which is a denial of service dressed as an optimisation.
+        const key = `${claims.tenantId}:${body.conversation.id}:${body.delivery_id}`;
+        if (!seen.admit(key, Date.now()))
+            return accept('duplicate');
+        const work = think(claims, body, bearer).catch((cause) => {
+            // The delivery is forgotten so core's retry can be answered. The alternative — a
+            // remembered id and a thrown think — is a conversation that is never answered again
+            // and no record anywhere of why.
+            seen.forget(key);
+            console.error('[keemakr] channel turn failed', cause?.message);
+        });
+        // THE WORK RUNS AFTER THE RESPONSE, which is the whole reason this helper exists. A
+        // bare `void think()` after returning is what a first pack writes and what a serverless
+        // platform freezes at response end — every delivery then times out at core's answer
+        // deadline, and the symptom is "the agent is slow" rather than "the agent was killed".
+        if (waitUntil)
+            waitUntil(work);
+        else
+            void work;
+        return accept('accepted');
+    }
+    async function think(claims, body, bearer) {
+        const ctx = buildContext(claims, body, bearer);
+        let action;
+        try {
+            action = await options.answer(ctx);
+        }
+        catch (cause) {
+            // A PACK THAT THREW STILL OWES CORE AN ANSWER. Silence costs the customer the full
+            // answer deadline — ninety seconds of a chat window doing nothing — and then raises
+            // `answer_timed_out`, which reads as "the pack is hanging" rather than "the pack
+            // crashed". A handoff puts a person on it now and says which.
+            console.error('[keemakr] answer() threw', cause?.message);
+            action = {
+                action: 'handoff',
+                reason: 'agent_failed',
+                usage: { input_tokens: 0, output_tokens: 0 },
+            };
+        }
+        await postBack(claims, body, bearer, action);
+    }
+    function buildContext(claims, body, bearer) {
+        const authed = (path, init = {}) => fetchImpl(new URL(path, core.origin).toString(), {
+            ...init,
+            headers: {
+                ...init.headers,
+                authorization: `Bearer ${bearer}`,
+                'content-type': 'application/json',
+            },
+        });
+        return {
+            tenantId: claims.tenantId,
+            conversationId: body.conversation.id,
+            deliveryId: body.delivery_id,
+            messages: body.unanswered_messages ?? [],
+            truncated: body.truncated_messages ?? 0,
+            contact: body.contact,
+            binding: body.binding,
+            language: body.language,
+            async history(limit = 20) {
+                const res = await authed(`/api/channels/conversations/${encodeURIComponent(body.conversation.id)}?limit=${limit}`);
+                if (!res.ok)
+                    return [];
+                const json = (await res.json());
+                return json.messages ?? [];
+            },
+            kb: {
+                async search(query, opts) {
+                    const res = await authed('/api/capability/kb/retrieve', {
+                        method: 'POST',
+                        body: JSON.stringify({ query, limit: opts?.limit ?? 3 }),
+                    });
+                    if (!res.ok)
+                        return [];
+                    const json = (await res.json());
+                    return (json.hits ?? []).map((h) => ({
+                        chunkId: String(h.chunk_id ?? ''),
+                        title: h.title ?? null,
+                        text: String(h.text ?? ''),
+                        score: Number(h.score ?? 0),
+                    }));
+                },
+            },
+            // PURE BUILDERS. They return an action and touch nothing — so a pack's `answer` can
+            // be tested by calling it and inspecting what came back, with no core, no fake and no
+            // network.
+            reply(text, opts) {
+                return {
+                    action: 'reply',
+                    text,
+                    ...(opts?.confidence !== undefined ? { confidence: opts.confidence } : {}),
+                    ...(opts?.groundedOn ? { grounded_on: opts.groundedOn } : {}),
+                    usage: opts?.usage ?? { input_tokens: 0, output_tokens: 0 },
+                };
+            },
+            handoff(reason, opts) {
+                return {
+                    action: 'handoff',
+                    reason,
+                    usage: opts?.usage ?? { input_tokens: 0, output_tokens: 0 },
+                };
+            },
+            none(opts) {
+                return { action: 'none', usage: opts?.usage ?? { input_tokens: 0, output_tokens: 0 } };
+            },
+        };
+    }
+    async function postBack(claims, body, bearer, action) {
+        const res = await fetchImpl(new URL(`/api/channels/conversations/${encodeURIComponent(body.conversation.id)}/actions`, core.origin).toString(), {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${bearer}`,
+                'content-type': 'application/json',
+                'idempotency-key': body.delivery_id,
+                ...(claims.traceId ? { 'x-keemakr-trace-id': claims.traceId } : {}),
+            },
+            body: JSON.stringify({
+                delivery_id: body.delivery_id,
+                ...action,
+                // ALWAYS, on every action including `none`. A pack that omits usage meters the
+                // whole lane at zero forever, and model tokens are most of what a conversation
+                // costs — so the one number that makes the bill visible is the one an author is
+                // most likely to forget.
+                usage: action.usage ?? { input_tokens: 0, output_tokens: 0 },
+            }),
+        });
+        if (!res.ok) {
+            console.error(`[keemakr] core refused the answer: ${res.status}`);
+        }
+    }
+    async function preview(req) {
+        const bearer = req.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ?? '';
+        if (!bearer)
+            return refuse(401, 'no_grant');
+        const claims = await verifyChannelGrant(bearer, keys, options.audience);
+        if (!claims)
+            return refuse(401, 'grant_invalid');
+        // THE SAME SCOPE AS ANSWERING, deliberately. A preview reads the tenant's knowledge and
+        // runs their model budget; a weaker gate here would be a way to do both without being
+        // allowed to answer anybody.
+        if (!claims.scopes.includes('channel:respond'))
+            return refuse(403, 'missing_channel_respond');
+        let body;
+        try {
+            body = (await req.json());
+        }
+        catch {
+            return refuse(400, 'invalid_json');
+        }
+        if (!claims.conversationId || claims.conversationId !== body.conversation?.id) {
+            return refuse(403, 'conversation_mismatch');
+        }
+        // AND THE SAME ENVELOPE CHECK AS A DELIVERY. This was in `handle` and not here, which
+        // is the one divergence that defeats the feature's purpose: a binding whose pack speaks
+        // a contract this SDK does not is correctly refused on the real path and silently
+        // ANSWERED on the preview path — so the owner is shown, under v1 assumptions, something
+        // no customer of theirs would ever receive. A preview that lies is worse than no
+        // preview, because it is trusted.
+        if (body.contract !== undefined && body.contract !== SUPPORTED_CONTRACT) {
+            return refuse(400, 'contract_unsupported');
+        }
+        const started = Date.now();
+        try {
+            const action = await options.answer(buildContext(claims, body, bearer));
+            return new Response(JSON.stringify({ action, latency_ms: Date.now() - started }), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        }
+        catch (cause) {
+            // SHOWN, not swallowed. The whole point of a preview is to find out why an agent is
+            // behaving oddly, and "it threw" is the most useful answer it can give.
+            return new Response(JSON.stringify({
+                action: {
+                    action: 'handoff',
+                    reason: 'agent_failed',
+                    usage: { input_tokens: 0, output_tokens: 0 },
+                },
+                error: cause?.message ?? 'unknown',
+                latency_ms: Date.now() - started,
+            }), { status: 200, headers: { 'content-type': 'application/json' } });
+        }
+    }
+    return {
+        fetchHandler(req, ctx) {
+            return handle(req, ctx?.waitUntil ?? options.waitUntil);
+        },
+        previewHandler: preview,
+    };
+}
+function refuse(status, code) {
+    return new Response(JSON.stringify({ error: code }), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+function accept(state) {
+    return new Response(JSON.stringify({ accepted: true, state }), {
+        status: 202,
+        headers: { 'content-type': 'application/json' },
+    });
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
 export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeRecords, type KeeKb, type KBHit, type KeeTools, type KeeConfig, type MemoryEntry, type MemorySearchHit, type RecordEntry, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';
+export { imageCanvas, type Canvas, type ImageCanvas, type ReportCanvas } from './canvases.js';
+export { createChannelAgent, assertTrustworthyCore, type ChannelAction, type ChannelAgent, type ChannelAgentOptions, type ChannelContext, type ChannelDelivery, type HandoffReason, type Usage, } from './channel.js';

package/dist/index.js

@@ -13,3 +13,5 @@ export { verifyGrant } from './verify-grant.js';
 export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';
+export { imageCanvas } from './canvases.js';
+export { createChannelAgent, assertTrustworthyCore, } from './channel.js';

package/dist/verify-grant.d.ts

@@ -7,15 +7,6 @@ export interface VerifiedGrant {
     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). `jwksUrl` falls back to KEE_CORE_JWKS_URL, then to
- * KEE_CORE_URL's origin — and to nothing after that, so a deployment that has not
- * named its platform refuses every grant rather than trusting a compiled-in
- * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and 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;

package/dist/verify-grant.js

@@ -22,6 +22,16 @@ const GRANT_ISSUER = 'keemakr';
  * default it did not choose. `audience` falls back to KEE_AGENT_AUDIENCE and is
  * strongly recommended: a grant is only valid for the remote it was minted for.
  */
+let audienceWarned = false;
+/** Said once per process. A per-request warning is noise, and noise is not a warning. */
+function warnAudienceUnset() {
+    if (audienceWarned)
+        return;
+    audienceWarned = true;
+    console.warn('[keemakr] KEE_AGENT_AUDIENCE is not set, so this grant is accepted whoever it was ' +
+        "minted for. Set it to this deployment's exact origin — the same URL registered as " +
+        "the entry's runtime — so a grant minted for another pack cannot be replayed here.");
+}
 export async function verifyGrant(token, opts) {
     const jwksUrl = resolveJwksUrl(opts?.jwksUrl);
     if (!jwksUrl) {
@@ -29,6 +39,19 @@ export async function verifyGrant(token, opts) {
         return null;
     }
     const expectedAud = opts?.audience ?? process.env.KEE_AGENT_AUDIENCE;
+    // AN UNSET AUDIENCE IS A REAL RISK, SAID OUT LOUD ONCE.
+    //
+    // `jwtVerify` is given no `audience` option when this is empty, which means the grant is
+    // accepted whoever it was minted FOR — any core-signed token for any deployment of any
+    // pack passes. The behaviour is kept, because changing it would break every pack running
+    // without the variable today and a silent tightening is worse than a loud gap. But it was
+    // completely silent, which made the unsafe configuration the easy one: nothing at build
+    // time, nothing at boot, nothing in the log, and the symptom only appears if somebody
+    // points a different deployment at this one.
+    //
+    // Once per process, not per request: a warning on every turn is a warning nobody reads.
+    if (!expectedAud)
+        warnAudienceUnset();
     try {
         const { payload } = await jwtVerify(token, jwksFor(jwksUrl), {
             issuer: GRANT_ISSUER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0-dev-20260925092950",
   "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",
@@ -18,6 +18,14 @@
     "./connectors": {
       "types": "./dist/connectors.d.ts",
       "import": "./dist/connectors.js"
+    },
+    "./channel": {
+      "types": "./dist/channel.d.ts",
+      "import": "./dist/channel.js"
+    },
+    "./channel/testkit": {
+      "types": "./dist/channel-testkit.d.ts",
+      "import": "./dist/channel-testkit.js"
     }
   },
   "files": [
@@ -43,6 +51,11 @@
     "eve": ">=0.40.0 <0.60",
     "jose": "^6.2.3"
   },
+  "peerDependenciesMeta": {
+    "eve": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^20.19.43",
     "eve": "0.40.0",