@keemakr/agent-sdk 0.18.0 → 1.0.0-v2-preview-20261007185032

package/README.md

@@ -13,19 +13,17 @@ The tenant identity and scopes come from a short-lived signed grant the operator
 npm install @keemakr/agent-sdk
 ```
 
-Peer dependencies: `eve` `>=0.40.0 <0.60` and `jose@^6.2.3`. Both ends of that eve range are
-compiled in CI — 0.40.0 and 0.59.1 — and nothing above 0.59.1 is claimed; see the CHANGELOG for
-why the ceiling stops there.
+Peer dependencies (match your eve agent): `eve@0.13.0`, `jose@^6.2.3`.
 
 ## Configure
 
 Set these in your deployed agent's environment:
 
-| Variable             | Purpose                                                                                                                                             |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `KEE_CORE_URL`       | **Required.** The keemakr platform you installed on, e.g. `https://dash.dev.keemakr.ai`. Used both to verify grants and to call the capability API. |
-| `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_JWKS_URL`  | Only when the JWKS is not at `<KEE_CORE_URL>/.well-known/jwks.json`. Takes precedence over `KEE_CORE_URL` for verification.                         |
+| Variable             | Purpose                                                                                                                                                                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `KEE_CORE_URL`       | **Required.** The keemakr platform you installed on, e.g. `https://dash.dev.keemakr.ai`. Used both to verify grants and to call the capability API.                                                                                              |
+| `KEE_AGENT_AUDIENCE` | This deployment's audience — your runtime URL's origin (`scheme://host[:port]`, no path, no trailing slash), e.g. `https://my-agent.example.com`. Must match the audience the operator mints exactly. Runtimes on one origin share one audience. |
+| `KEE_CORE_JWKS_URL`  | Only when the JWKS is not at `<KEE_CORE_URL>/.well-known/jwks.json`. Takes precedence over `KEE_CORE_URL` for verification.                                                                                                                      |
 
 **There is no default platform, deliberately.** `KEE_CORE_URL` names the keys your
 agent trusts and the host it sends the tenant's grant token to. A compiled-in
@@ -173,44 +171,6 @@ 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`.
 
-## Read the user's own words in a tool
-
-A delegation from Kee carries Kee's brief as the `message` and, beside it, the user's own latest message in that conversation, verbatim. eve gives that second text (`clientContext.keemakr_user_message`) to your model only. Core also signs it into the grant, so `grantAuth()` puts it on the session auth and `getUserMessage(ctx)` returns it to tool code:
-
-```ts title="agent/tools/request_discount.ts"
-import { defineTool } from 'eve/tools';
-import { z } from 'zod';
-import { getUserMessage } from '@keemakr/agent-sdk';
-
-export default defineTool({
-  description: 'Request a discount on a deal.',
-  inputSchema: z.object({ dealId: z.string(), percent: z.number() }),
-  // An approval policy gets the same ctx, in the turn the user wrote in. Refuse here and no
-  // approval card is raised for a request the user never made.
-  approval: (ctx) => {
-    const said = getUserMessage(ctx);
-    if (said && !said.truncated && !mentions(said.text, ctx.toolInput?.dealId)) {
-      return { type: 'denied', reason: `the user did not name deal ${ctx.toolInput?.dealId}` };
-    }
-    return 'user-approval';
-  },
-  async execute({ dealId, percent }, ctx) {
-    /* ... */
-  },
-});
-
-const mentions = (text: string, id: unknown) =>
-  typeof id === 'string' &&
-  text
-    .toUpperCase()
-    .replace(/[^A-Z0-9]/g, '')
-    .includes(id.toUpperCase().replace(/[^A-Z0-9]/g, ''));
-```
-
-`getUserMessage(ctx)` returns `{ text, inputMode, truncated }` or `null`. It is `null` when nobody wrote anything for this turn (a routine, a dispatch with no conversation turn), inside `execute()` after a human approved (core resumes the turn with a fresh grant that does not carry the words), and on any session that a grant did not authenticate. Decide what `null` means for each tool; most should go on as before rather than refuse. `truncated` is `true` when core cut the text (at 4 KiB in the grant), so do not refuse on the **absence** of something from a truncated message.
-
-Subagents see the same value: eve passes the parent's session auth to a declared subagent.
-
 ## Grant refresh (automatic since 0.8.0)
 
 Every `useKee` capability call keeps its grant alive by itself: when the active token has under two minutes left, the SDK exchanges it at core's `POST /api/capability/grant/refresh` (single-flight per delegation — concurrent tool calls share one refresh), and a `401 grant_expired` gets one refresh + one retry before surfacing. You write nothing; long runs simply stop dying at the TTL.
@@ -241,6 +201,60 @@ if (!claims) throw new Error('invalid or expired grant');
 
 Inside an eve channel, `grantAuth()` already accepts machine grants (same token shape) — no extra work.
 
+## Channel turns: answer the conversations Core routes to you
+
+A workspace binds each widget, WhatsApp number, email inbox and SMS number to one named handler in one Pack. When something happens in a conversation the handler owns, Core posts a delivery to `{runtime}/channels/v1/deliver` with a turn grant. Mount one route and name your handlers. The example passes the message to Eve with the route's `from`, which Eve has from 0.35; the SDK itself needs no newer Eve than the rest of this package:
+
+```ts
+// agent/channels/inbound.ts
+import { defineChannel, POST, type RouteHandlerArgs } from 'eve/channels';
+import {
+  CHANNEL_DELIVERY_PATH,
+  defineChannelHandler,
+  handleChannelDelivery,
+} from '@keemakr/agent-sdk';
+
+const salesInbound = defineChannelHandler<RouteHandlerArgs<undefined>>({
+  async message(turn, { from }) {
+    // The Core conversation is the Eve session address. A rollover opens a new
+    // conversation, and so a new session.
+    await from(turn.conversationId).send(turn.event.message.text, { auth: turn.sessionAuth() });
+  },
+  async verified(turn) {
+    // The person proved a number or address: move the lead's journey forward.
+  },
+});
+
+export default defineChannel({
+  routes: [
+    POST(CHANNEL_DELIVERY_PATH, (req, route) =>
+      handleChannelDelivery(req, { 'sales-inbound': salesInbound }, { route }),
+    ),
+  ],
+});
+```
+
+The methods are `message` (a customer message), `sent` (the agent's own reply went out; news only), `verified` (`contact.verified`) `ownerChanged` (a person gave the conversation back) and `staffAction` (a staff member clicked one of your buttons). A method you leave out is acknowledged and nothing happens. Declare the matching subscriptions on the inbound agent with `channelSubscriptions(['widget'])`. Declare staff buttons on the inbound agent as `staffActions: [{ key: 'send-booking-link', label: 'Send booking link', choices: [...] }]` and pass `{ staffActions: true }` to `channelSubscriptions`. When the staff member who clicked owns the conversation, `turn.actingUserId` names them and the turn's replies go out under their name.
+
+A turn acts through Core, which checks on every call that the turn still owns the conversation:
+
+| Action                                 | Call                                                                        |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| Reply                                  | `turn.reply(text)` (idempotent on the text by default)                      |
+| Stay silent                            | `turn.silent()`                                                             |
+| Hand over to a named person            | `turn.handoff(userId, { note })`                                            |
+| Ask the person to verify               | `turn.requestVerification({ kind: 'phone', value }, 'sms_code')`            |
+| Check a code                           | `turn.verifyCode(code)`                                                     |
+| Send an approved WhatsApp template     | `turn.sendTemplate({ name, language, variables })`                          |
+| Publish a Pack event, visible to staff | `turn.publish(contract, payload, { idempotencyKey, visible: { summary } })` |
+| Create a task                          | `turn.createTask(input)`                                                    |
+
+A workspace may hold agent replies for a person to approve: all of them, or those below its confidence threshold. Pass your own 0-1 rating as `turn.reply(text, { confidence })`; a reply without one counts as below the threshold. A held reply returns `heldForReview: true` (`outcome.status` is `held_for_review`): it is not lost and not refused, so do not send it again or apologise for a delay. Staff approve it (possibly edited) or discard it; an approved reply goes out as the agent's, and the handler hears `sent` as usual.
+
+`turn.can(action)` says what the binding allows. Publishing and tasks also need the binding's identity rule met. On WhatsApp, `turn.window` says whether the 24-hour window is open (`{ open, closesAt }`); once it closes only a template may go, and an agent may send only a UTILITY template its binding lists (`turn.can('send_template')`). A refusal throws `ChannelActionError` with Core's `code` (for example `superseded` after a staff takeover). Inside the agent's tools, `channelTurnFromContext(ctx)` gives the same actions, and `useKee(ctx)` reaches the Pack's tools with the scopes the binding allows.
+
+`advanceJourney(journey, turn)` and `journeyContext(journey)` keep the Pack's own journey record for each Contact (stage, last channel, open items, summary) and open each new session with it.
+
 ## 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.
@@ -250,17 +264,6 @@ Inside an eve channel, `grantAuth()` already accepts machine grants (same token
 
 Full contract: keemakr-core `docs/CONNECTOR-CONTRACT.md`.
 
-## Building the agent itself
-
-This SDK covers the grant and capability half. The delegation half — how the Operator talks to
-your root, what it expects back, and what it will not do for you — is in keemakr-core:
-
-- `docs/building-department-agents.md` — declared subagents and the isolation trap, parallel
-  fan-out as a barrier, the `DelegationResult` contract, the ONE-combined-message-per-department
-  obligation, the ~45s promotion budget, and voice.
-- `docs/authoring-manifest-descriptions.md` — the manifest description is the routing signal. An
-  empty one on the department surface stops intent routing for your department entirely.
-
 ## License
 
 MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,33 @@
+import { type VerifiedGrant } from './verify-grant.js';
+export interface CapabilityInvokeEnvelope {
+    operation_id: string;
+    capability_id: string;
+    version: number;
+    input: unknown;
+    context: {
+        tenant_id: string;
+        on_behalf_of: string | null;
+        trace_id: string | null;
+        task_id: string | null;
+        run_id: string | null;
+    };
+}
+export type CapabilityHandlerContext = CapabilityInvokeEnvelope['context'] & {
+    operation_id: string;
+    capability_id: string;
+    version: number;
+    grant: VerifiedGrant;
+    /** The bearer Core sent — hand it to your Kee client, never log it. */
+    token: string;
+};
+export type CapabilityHandler<I = unknown, O = unknown> = (input: I, ctx: CapabilityHandlerContext) => Promise<O>;
+/** A typed business failure the caller can act on (surfaces as failure.code). */
+export declare class CapabilityFailure extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+export declare function handleCapabilityInvoke(req: Request, key: string, handlers: Record<string, CapabilityHandler<never, unknown>>, opts?: {
+    jwksUrl?: string;
+    audience?: string;
+}): Promise<Response>;

package/dist/capabilities.js

@@ -0,0 +1,110 @@
+// handleCapabilityInvoke — the agent side of a Capability invocation.
+//
+// Core POSTs `{runtime}/capabilities/{key}/invoke` with a short-lived grant as
+// bearer. Mount this in a channel route and hand it your handlers:
+//
+//   import { defineChannel, POST } from 'eve/channels';
+//   import { handleCapabilityInvoke, CapabilityFailure } from '@keemakr/agent-sdk';
+//
+//   export default defineChannel({
+//     routes: [
+//       POST('/capabilities/:key/invoke', (req, { params }) =>
+//         handleCapabilityInvoke(req, params.key, {
+//           'lead.qualify': async (input, ctx) => { … return { qualified: 3 }; },
+//         })),
+//     ],
+//   });
+//
+// It verifies the grant against Core's JWKS (audience = this runtime), parses the
+// envelope, dispatches to the handler for `key`, and answers in the one shape
+// Core validates: `{ ok:true, output }` or `{ ok:false, failure:{code,message} }`.
+// Throw CapabilityFailure for a typed business failure; anything else becomes
+// `failure.code = 'unhandled'` with the message, never a stack.
+//
+// The handler receives the verified grant and the raw token: build your Kee
+// client from them (the grant-ctx pattern) to reach records/memory/connections.
+// It receives NO way to invoke another Capability — that boundary is Core's.
+import { bearer } from './http.js';
+import { verifyGrant } from './verify-grant.js';
+/** A typed business failure the caller can act on (surfaces as failure.code). */
+export class CapabilityFailure extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'CapabilityFailure';
+    }
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+export async function handleCapabilityInvoke(req, key, handlers, opts) {
+    const token = bearer(req);
+    if (!token)
+        return json(401, {
+            ok: false,
+            failure: { code: 'grant_missing', message: 'a capability grant is required' },
+        });
+    const grant = await verifyGrant(token, opts);
+    if (!grant) {
+        return json(401, {
+            ok: false,
+            failure: { code: 'grant_rejected', message: 'the capability grant did not verify' },
+        });
+    }
+    const handler = handlers[key];
+    if (!handler) {
+        return json(404, {
+            ok: false,
+            failure: { code: 'unknown_capability', message: `no handler for '${key}'` },
+        });
+    }
+    let envelope;
+    try {
+        envelope = (await req.json());
+        if (!envelope || typeof envelope.operation_id !== 'string')
+            throw new Error('bad envelope');
+    }
+    catch {
+        return json(400, {
+            ok: false,
+            failure: { code: 'bad_request', message: 'invalid invocation envelope' },
+        });
+    }
+    // The grant's tenant is the truth; an envelope naming another tenant is refused.
+    if (envelope.context?.tenant_id && envelope.context.tenant_id !== grant.tenantId) {
+        return json(403, {
+            ok: false,
+            failure: { code: 'tenant_mismatch', message: 'envelope tenant does not match the grant' },
+        });
+    }
+    try {
+        const output = await handler(envelope.input, {
+            ...envelope.context,
+            tenant_id: grant.tenantId,
+            operation_id: envelope.operation_id,
+            capability_id: envelope.capability_id,
+            version: envelope.version,
+            grant,
+            token,
+        });
+        return json(200, { ok: true, output: output ?? null });
+    }
+    catch (e) {
+        if (e instanceof CapabilityFailure) {
+            return json(200, {
+                ok: false,
+                failure: { code: e.code, message: e.message, details: e.details ?? null },
+            });
+        }
+        return json(200, {
+            ok: false,
+            failure: { code: 'unhandled', message: e instanceof Error ? e.message : String(e) },
+        });
+    }
+}

package/dist/channel-manifest.d.ts

@@ -0,0 +1,109 @@
+export type AgentExposure = 'general' | 'inbound';
+/** The customer-message Event each channel delivers. Owned by its channel family. */
+export declare const CORE_CHANNEL_EVENTS: {
+    readonly email: {
+        readonly owner: "email";
+        readonly key: "email.message.received";
+        readonly version: 1;
+    };
+    readonly whatsapp: {
+        readonly owner: "whatsapp";
+        readonly key: "whatsapp.message.received";
+        readonly version: 1;
+    };
+    readonly widget: {
+        readonly owner: "widget";
+        readonly key: "widget.message.received";
+        readonly version: 1;
+    };
+    readonly sms: {
+        readonly owner: "sms";
+        readonly key: "sms.message.received";
+        readonly version: 1;
+    };
+    readonly instagram: {
+        readonly owner: "instagram";
+        readonly key: "instagram.message.received";
+        readonly version: 1;
+    };
+    readonly messenger: {
+        readonly owner: "messenger";
+        readonly key: "messenger.message.received";
+        readonly version: 1;
+    };
+};
+export type CoreChannelEventKey = (typeof CORE_CHANNEL_EVENTS)[keyof typeof CORE_CHANNEL_EVENTS]['key'];
+/**
+ * A button the Pack offers staff in the inbox, for a conversation its inbound
+ * agent answers. A click reaches the handler as `conversation.action.requested`.
+ */
+export interface StaffActionDeclaration {
+    /** Lowercase letters, digits and dashes, starting with a letter; at most 40. */
+    key: string;
+    /** The button text, for example "Send booking link". At most 60 characters. */
+    label: string;
+    description?: string;
+    /** One option to pick at the click, for example the channel to send on. */
+    choices?: {
+        key: string;
+        label: string;
+    }[];
+}
+export declare const STAFF_ACTION_KEY: RegExp;
+export declare const STAFF_ACTION_EVENT = "conversation.action.requested";
+export interface InboundEventSubscription {
+    owner: string;
+    key: string;
+    version: number;
+    fingerprint?: string;
+}
+/**
+ * The subscriptions an inbound agent declares in its manifest: the customer
+ * message on each channel it answers, and the news it wants. The agent's own
+ * sent replies are opt-in; a verified Contact and the conversation coming back
+ * are on unless turned off. `staffActions` is needed when the agent declares
+ * staff buttons.
+ */
+export declare function channelSubscriptions(channels: readonly ('widget' | 'whatsapp' | 'email' | 'sms')[], news?: {
+    sent?: boolean;
+    verified?: boolean;
+    ownerChanged?: boolean;
+    staffActions?: boolean;
+}): InboundEventSubscription[];
+export interface AgentExposureManifest {
+    agents: Array<{
+        key: string;
+        exposure?: AgentExposure;
+        subscriptions?: InboundEventSubscription[];
+        permissions?: string[];
+        staffActions?: StaffActionDeclaration[];
+    }>;
+    teams?: Array<{
+        key: string;
+        exposure?: 'general';
+        lead?: string;
+        members?: string[];
+    }>;
+    capabilities?: Array<{
+        implementation?: {
+            kind?: string;
+            agent?: string;
+            team?: string;
+        };
+    }>;
+    schedules?: Array<{
+        agent?: string;
+    }>;
+    eventHandlers?: Array<{
+        authority?: {
+            agents?: string[];
+            teams?: string[];
+        };
+    }>;
+}
+/**
+ * Publication-time boundary: an inbound agent cannot also be named by a
+ * general dispatch declaration. Missing exposure remains general, preserving
+ * every existing manifest.
+ */
+export declare function validateAgentExposureManifest(manifest: AgentExposureManifest): string[];

package/dist/channel-manifest.js

@@ -0,0 +1,130 @@
+/** The customer-message Event each channel delivers. Owned by its channel family. */
+export const CORE_CHANNEL_EVENTS = {
+    email: { owner: 'email', key: 'email.message.received', version: 1 },
+    whatsapp: { owner: 'whatsapp', key: 'whatsapp.message.received', version: 1 },
+    widget: { owner: 'widget', key: 'widget.message.received', version: 1 },
+    sms: { owner: 'sms', key: 'sms.message.received', version: 1 },
+    instagram: { owner: 'instagram', key: 'instagram.message.received', version: 1 },
+    messenger: { owner: 'messenger', key: 'messenger.message.received', version: 1 },
+};
+export const STAFF_ACTION_KEY = /^[a-z][a-z0-9-]{0,39}$/;
+export const STAFF_ACTION_EVENT = 'conversation.action.requested';
+/**
+ * Every conversation Event Core delivers to an inbound agent: a received message,
+ * the agent's own sent reply, a verified Contact, and the conversation coming back
+ * to the agent. Each is owned by its family (`widget`, `contact`, ...); the older
+ * `core` owner still validates.
+ */
+const CORE_CHANNEL_EVENT_KEYS = new Set([
+    ...Object.values(CORE_CHANNEL_EVENTS).map((event) => event.key),
+    ...['widget', 'whatsapp', 'email', 'sms'].map((channel) => `${channel}.message.sent`),
+    'contact.verified',
+    'conversation.owner.changed',
+    'conversation.action.requested',
+]);
+function isCoreChannelSubscription(subscription) {
+    if (subscription.version !== 1 || !CORE_CHANNEL_EVENT_KEYS.has(subscription.key))
+        return false;
+    return subscription.owner === 'core' || subscription.key.startsWith(`${subscription.owner}.`);
+}
+/**
+ * The subscriptions an inbound agent declares in its manifest: the customer
+ * message on each channel it answers, and the news it wants. The agent's own
+ * sent replies are opt-in; a verified Contact and the conversation coming back
+ * are on unless turned off. `staffActions` is needed when the agent declares
+ * staff buttons.
+ */
+export function channelSubscriptions(channels, news = {}) {
+    const out = [];
+    for (const channel of channels) {
+        out.push({ owner: channel, key: `${channel}.message.received`, version: 1 });
+        if (news.sent)
+            out.push({ owner: channel, key: `${channel}.message.sent`, version: 1 });
+    }
+    if (news.verified !== false)
+        out.push({ owner: 'contact', key: 'contact.verified', version: 1 });
+    if (news.ownerChanged !== false) {
+        out.push({ owner: 'conversation', key: 'conversation.owner.changed', version: 1 });
+    }
+    if (news.staffActions) {
+        out.push({ owner: 'conversation', key: STAFF_ACTION_EVENT, version: 1 });
+    }
+    return out;
+}
+/**
+ * Publication-time boundary: an inbound agent cannot also be named by a
+ * general dispatch declaration. Missing exposure remains general, preserving
+ * every existing manifest.
+ */
+export function validateAgentExposureManifest(manifest) {
+    const inboundAgents = new Set(manifest.agents.filter((agent) => agent.exposure === 'inbound').map((agent) => agent.key));
+    const errors = [];
+    for (const agent of manifest.agents) {
+        if (agent.exposure === 'inbound' && !agent.subscriptions?.length) {
+            errors.push(`inbound agent '${agent.key}' must declare at least one Event subscription`);
+        }
+        if (agent.exposure !== 'inbound' &&
+            (agent.subscriptions?.length || agent.permissions?.length)) {
+            errors.push(`only an inbound agent may declare subscriptions or inbound permissions`);
+        }
+        const actions = agent.staffActions ?? [];
+        if (actions.length > 0) {
+            if (agent.exposure !== 'inbound') {
+                errors.push(`only an inbound agent may declare staff actions ('${agent.key}')`);
+            }
+            if (!agent.subscriptions?.some((s) => s.key === STAFF_ACTION_EVENT && s.version === 1)) {
+                errors.push(`inbound agent '${agent.key}' declares staff actions and must subscribe to ${STAFF_ACTION_EVENT}@1`);
+            }
+            if (actions.length > 10)
+                errors.push(`inbound agent '${agent.key}' may declare at most 10 staff actions`);
+            const seen = new Set();
+            for (const action of actions) {
+                const choices = action.choices ?? [];
+                if (!STAFF_ACTION_KEY.test(action.key) ||
+                    seen.has(action.key) ||
+                    typeof action.label !== 'string' ||
+                    action.label.trim().length === 0 ||
+                    action.label.length > 60 ||
+                    (action.description !== undefined &&
+                        (typeof action.description !== 'string' || action.description.length > 200)) ||
+                    choices.length > 5 ||
+                    new Set(choices.map((c) => c.key)).size !== choices.length ||
+                    choices.some((c) => !STAFF_ACTION_KEY.test(c.key) ||
+                        typeof c.label !== 'string' ||
+                        c.label.trim().length === 0 ||
+                        c.label.length > 60)) {
+                    errors.push(`inbound agent '${agent.key}' has an invalid staff action '${String(action.key)}': a unique key of lowercase letters, digits and dashes, a label of 1-60 characters, and at most 5 unique choices`);
+                }
+                seen.add(action.key);
+            }
+        }
+        for (const subscription of agent.subscriptions ?? []) {
+            if (!isCoreChannelSubscription(subscription)) {
+                errors.push(`inbound agent '${agent.key}' may subscribe only to Core channel Event contracts`);
+            }
+        }
+    }
+    for (const team of manifest.teams ?? []) {
+        if ((team.lead && inboundAgents.has(team.lead)) ||
+            team.members?.some((member) => inboundAgents.has(member))) {
+            errors.push('an inbound agent cannot be a Team lead or member');
+        }
+    }
+    for (const capability of manifest.capabilities ?? []) {
+        const target = capability.implementation;
+        if (target?.agent && inboundAgents.has(target.agent)) {
+            errors.push('an inbound agent cannot be a Capability target');
+        }
+    }
+    for (const schedule of manifest.schedules ?? []) {
+        if (schedule.agent && inboundAgents.has(schedule.agent)) {
+            errors.push('an inbound agent cannot be a schedule target');
+        }
+    }
+    for (const handler of manifest.eventHandlers ?? []) {
+        if (handler.authority?.agents?.some((agent) => inboundAgents.has(agent))) {
+            errors.push('an inbound agent cannot be a generic Event handler target');
+        }
+    }
+    return errors;
+}

package/dist/channel-turn.d.ts

@@ -0,0 +1,52 @@
+/** What a turn may ask Core's action door for, as the binding allows. */
+export type ChannelTurnAction = 'reply' | 'silent' | 'handoff' | 'request_verification' | 'verify_code' | 'publish_event'
+/** WhatsApp: present when the binding lists templates the agent may send. */
+ | 'send_template';
+export interface ChannelTurnGrant {
+    tenantId: string;
+    /** `{pack}/channels/{handler}` */
+    installedAgent: string;
+    /**
+     * Capability scopes for the Pack's own tools. Empty until the binding's
+     * identity rule is met, and on news the handler may not act on.
+     */
+    scopes: string[];
+    traceId: string | null;
+    audience: string;
+    exp: number | null;
+    turn: {
+        deliveryId: string;
+        conversationId: string;
+        ownerEpoch: number;
+        bindingId: string;
+        bindingRevisionId: string;
+        handlerKey: string;
+        agentKey: string;
+        consumerInstallId: string;
+        /** Empty on a delivery that is news only, such as the agent's own sent reply. */
+        permittedActions: ChannelTurnAction[];
+        /**
+         * The staff member this turn acts as, when their button click started it
+         * while they owned the conversation. Its replies go out under their name.
+         * Null for an agent turn.
+         */
+        actingUserId: string | null;
+    };
+}
+/** Pure: the verified claims as a turn grant, or null when they are not one. */
+export declare function parseChannelTurnGrantClaims(claims: Record<string, unknown>): ChannelTurnGrant | null;
+/**
+ * Verify a channel turn grant against Core's JWKS. The audience is required:
+ * a turn grant is valid only at the runtime Core woke. `audience` falls back to
+ * KEE_AGENT_AUDIENCE; with neither, every turn is refused.
+ */
+export declare function verifyChannelTurnGrant(token: string, opts?: {
+    jwksUrl?: string;
+    audience?: string;
+}): Promise<ChannelTurnGrant | null>;
+/**
+ * True for a turn grant, in its current or its first shape. The general
+ * verifiers refuse these: a turn grant acts for one delivery only, and must not
+ * open the Pack's own agent routes as a delegation.
+ */
+export declare function isChannelTurnClaims(claims: Record<string, unknown>): boolean;