@ziggs-ai/api-client 0.14.3 → 0.16.0

package/dist/http/PaymentsClient.d.ts

@@ -87,27 +87,69 @@ export declare class PaymentsClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    private readonly laneId?;
+    /**
+     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
+     *   X-Ziggs-Lane. It tells the backend which hire this wake is in, and the
+     *   backend reads off it WHO the spend is for. An agent that serves several
+     *   hirers holds all of their grants at once and the holder is the same agent
+     *   in every one, so without a lane, spend authority one customer gave is
+     *   spendable while the agent works for another. ConnectionsClient and
+     *   ArtifactsClient send the same header for the same reason.
+     *
+     *   Omitting it cannot widen anything — a stated lane can only cause a
+     *   refusal — but it does leave the spend unfenced, so a caller that knows
+     *   its lane should pass it.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     balance(): Promise<WalletBalance>;
     resolve({ userId, agentId }?: {
         userId?: string;
         agentId?: string;
     }): Promise<WalletRef | null>;
-    transfer({ to, amount, idempotencyKey, description, paymentGrantId, }: {
+    transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
         to: string;
         amount: number;
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
+        /**
+         * The hire this spend belongs to. Used for attribution, and to prefer that
+         * hire's own grant over a standing one — a preference about which budget is
+         * billed, never about which grants may be spent. That answer is the
+         * server's, and it turns on who gave the grant.
+         */
+        agreementId?: string;
     }): Promise<TransferResult>;
-    hold({ amount, idempotencyKey, description, paymentGrantId, }: {
+    hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
         amount: number;
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
+        /**
+         * The hire this spend belongs to. Used for attribution, and to prefer that
+         * hire's own grant over a standing one — a preference about which budget is
+         * billed, never about which grants may be spent. That answer is the
+         * server's, and it turns on who gave the grant.
+         */
+        agreementId?: string;
     }): Promise<HoldResult>;
-    /** Prefer a single active wallet grant the agent already holds. */
-    private resolveAgentPaymentGrantId;
+    /**
+     * Choose the grant that actually covers this spend.
+     *
+     * This used to be `grants[0]` — the first active grant, matched against
+     * nothing. An agent holding both its standing grant and an
+     * agreement-conferred one presented whichever came back first, the backend
+     * correctly refused it against wallet or amount, and the agent was refused a
+     * spend it was genuinely authorized to make.
+     *
+     * The source wallet is read rather than assumed: a grant on some other
+     * wallet cannot authorize money leaving this one, and the agent may hold
+     * grants on a counterparty's wallet from an engagement. A failure to read it
+     * is not fatal — selection then skips the wallet test and the server still
+     * validates, which is the same position we were in before.
+     */
+    private selectPaymentGrant;
     release({ holdId, action, toWalletId, idempotencyKey, }: {
         holdId: string;
         action?: string;

package/dist/http/PaymentsClient.js

@@ -1,6 +1,7 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { GrantsClient } from './GrantsClient.js';
+import { describeNoGrant, selectPaymentGrant, } from './paymentGrantSelection.js';
 import { throwApiError } from '../shared/apiError.js';
 function randomIdempotencyKey(prefix = 'op') {
     return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
@@ -17,12 +18,27 @@ export class PaymentsClient {
     operatorKey;
     agentId;
     baseUrl;
-    constructor(operatorKey, agentId, baseUrl) {
+    laneId;
+    /**
+     * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
+     *   X-Ziggs-Lane. It tells the backend which hire this wake is in, and the
+     *   backend reads off it WHO the spend is for. An agent that serves several
+     *   hirers holds all of their grants at once and the holder is the same agent
+     *   in every one, so without a lane, spend authority one customer gave is
+     *   spendable while the agent works for another. ConnectionsClient and
+     *   ArtifactsClient send the same header for the same reason.
+     *
+     *   Omitting it cannot widen anything — a stated lane can only cause a
+     *   refusal — but it does leave the spend unfenced, so a caller that knows
+     *   its lane should pass it.
+     */
+    constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)
             throw new Error('PaymentsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     async balance() {
         const w = (await this._get('/payments/wallet'));
@@ -45,18 +61,13 @@ export class PaymentsClient {
         const res = (await this._get(`/payments/wallets/resolve?${params}`));
         return res['wallet'] || null;
     }
-    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, }) {
+    async transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
         if (!to)
             throw new Error('transfer: `to` is required');
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('transfer: `amount` must be a positive integer (cents)');
-        // resolve a standing/active grant when the caller omitted one
-        // (Claude/MCP ensureForUser mints it). Explicit id still wins.
-        if (this.agentId && !paymentGrantId) {
-            paymentGrantId = (await this.resolveAgentPaymentGrantId()) ?? undefined;
-        }
-        if (this.agentId && !paymentGrantId)
-            throw new Error('transfer: paymentGrantId is required for agent-impersonated transfers. The wallet owner must have issued a payment grant to this agentId.');
+        // The recipient is resolved BEFORE choosing a grant: an `allowed_recipients`
+        // caveat cannot be checked against a name the client has not resolved yet.
         let toWalletId = to;
         if (!to.startsWith('wal_')) {
             const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
@@ -64,6 +75,15 @@ export class PaymentsClient {
                 throw new Error(`transfer: could not resolve wallet for "${to}"`);
             toWalletId = w.walletId;
         }
+        // Choose the grant that covers this spend when the caller omitted one.
+        // An explicit id still wins — a caller who names a grant means it.
+        if (this.agentId && !paymentGrantId) {
+            const picked = await this.selectPaymentGrant({ amount, toWalletId, agreementId });
+            if (!picked.grant) {
+                throw new Error(describeNoGrant('transfer', { amount, toWalletId, agreementId }, picked.rejected));
+            }
+            paymentGrantId = picked.grant.grantId;
+        }
         const result = (await this._post('/payments/transfer', {
             toWalletId,
             amount,
@@ -90,15 +110,18 @@ export class PaymentsClient {
             amount,
         };
     }
-    async hold({ amount, idempotencyKey, description, paymentGrantId, }) {
+    async hold({ amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('hold: `amount` must be a positive integer (cents)');
-        // agent holds reserve the owner's wallet; require a grant.
+        // A hold reserves the owner's money, so it needs a grant like a transfer.
+        // It has no counterparty, so no recipient is offered to the caveats.
         if (this.agentId && !paymentGrantId) {
-            paymentGrantId = (await this.resolveAgentPaymentGrantId()) ?? undefined;
+            const picked = await this.selectPaymentGrant({ amount, agreementId });
+            if (!picked.grant) {
+                throw new Error(describeNoGrant('hold', { amount, agreementId }, picked.rejected));
+            }
+            paymentGrantId = picked.grant.grantId;
         }
-        if (this.agentId && !paymentGrantId)
-            throw new Error('hold: paymentGrantId is required for agent-impersonated holds. The wallet owner must have issued a payment grant to this agentId.');
         return (await this._post('/payments/hold', {
             amount,
             idempotencyKey: idempotencyKey || randomIdempotencyKey('hold'),
@@ -106,16 +129,37 @@ export class PaymentsClient {
             paymentGrantId,
         }));
     }
-    /** Prefer a single active wallet grant the agent already holds. */
-    async resolveAgentPaymentGrantId() {
+    /**
+     * Choose the grant that actually covers this spend.
+     *
+     * This used to be `grants[0]` — the first active grant, matched against
+     * nothing. An agent holding both its standing grant and an
+     * agreement-conferred one presented whichever came back first, the backend
+     * correctly refused it against wallet or amount, and the agent was refused a
+     * spend it was genuinely authorized to make.
+     *
+     * The source wallet is read rather than assumed: a grant on some other
+     * wallet cannot authorize money leaving this one, and the agent may hold
+     * grants on a counterparty's wallet from an engagement. A failure to read it
+     * is not fatal — selection then skips the wallet test and the server still
+     * validates, which is the same position we were in before.
+     */
+    async selectPaymentGrant(spend) {
+        let grants = [];
+        try {
+            grants = await this.listGrants();
+        }
+        catch {
+            return { grant: null, rejected: [] };
+        }
+        let fromWalletId = null;
         try {
-            const grants = await this.listGrants();
-            const id = grants[0]?.grantId;
-            return typeof id === 'string' && id.length > 0 ? id : null;
+            fromWalletId = (await this.balance()).walletId;
         }
         catch {
-            return null;
+            fromWalletId = null;
         }
+        return selectPaymentGrant(grants, { ...spend, fromWalletId });
     }
     async release({ holdId, action = 'complete', toWalletId, idempotencyKey, }) {
         return (await this._post(`/payments/release/${holdId}`, {
@@ -151,7 +195,7 @@ export class PaymentsClient {
      * (retired GET /payments/grants), following the cursor to completion.
      */
     async listGrants() {
-        const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
+        const grants = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl, this.laneId);
         return grants.listAllGrants({ scopeKind: 'wallet', health: 'active' });
     }
     async createTopUpIntent({ amount, description, currency, } = {}) {
@@ -232,7 +276,7 @@ export class PaymentsClient {
     async _request(method, path, body) {
         const init = {
             method,
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId, body !== undefined ? { 'content-type': 'application/json' } : {}),
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, body !== undefined ? { 'content-type': 'application/json' } : {}, this.laneId),
         };
         if (body !== undefined)
             init.body = JSON.stringify(body);

package/dist/http/TaskClient.js

@@ -165,7 +165,7 @@ export async function getActiveTasksForAgent(agentId, creds) {
  * assignee's own work list hands over a task nobody woke it for. Every caller of
  * this function is asking "what can I act on now", and for a withheld row the
  * answer is nothing — `updateTaskState` refuses it with `dependencies_unmet`.
- * Two of AgentHost's three callers do worse than waste a wake: the needs gate
+ * Two of Agent's three callers do worse than waste a wake: the needs gate
  * and the unmet-access sweep both FAIL the tasks they find, so a withheld node
  * was one missing grant away from being failed before its turn came.
  *

package/dist/http/agreementFlows.js

@@ -38,12 +38,18 @@ export async function proposeUnified(input, creds) {
         }, creds);
         return { agreement, shape: 'request' };
     }
-    if (!chatId)
-        throw new Error('chatId is required on a direct proposal');
+    // No room is a shape, not an error. The server has always accepted a direct
+    // proposal without one, and this throw was the only thing that made the answer
+    // depend on which client you used: an agreement between parties who have no
+    // conversation had to invent a chat id to be created. Delivery does not go
+    // through the room — the create-time event targets the party slots — so the
+    // counterparty is told either way.
     const agreement = await proposeDirectTo({
         ...terms,
         proposedTo,
-        chatId,
+        // Omitted rather than sent empty: an absent field says "no room", and an
+        // empty string is one more fiction for the server to interpret.
+        ...(chatId ? { chatId } : {}),
         providerId: providerId?.trim() || proposedTo,
         engagementKind: engagementKind ?? 'service',
     }, creds);

package/dist/http/index.d.ts

@@ -23,7 +23,7 @@ export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
-export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, isMcpOAuthDelegateAgentId, MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX, } from './OrgsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, } from './OrgsClient.js';
 export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';

package/dist/http/index.js

@@ -15,7 +15,7 @@ export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
-export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, isMcpOAuthDelegateAgentId, MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX, } from './OrgsClient.js';
+export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/http/paymentGrantSelection.d.ts

@@ -0,0 +1,58 @@
+import { type GrantView } from './grants.js';
+/**
+ * Which grant to present for a spend, and — when none fits — why each candidate
+ * did not.
+ *
+ * The client used to take `grants[0]` from the active list. It matched nothing
+ * else: not the source wallet, not the amount, not the agreement the spend
+ * belongs to. An agent holding both its standing grant and an agreement-conferred
+ * one presented whichever came back first, the backend correctly refused it
+ * against wallet or amount, and the agent was refused a spend it was genuinely
+ * authorized to make.
+ *
+ * Selection is a pure function of the grants and the spend so it can be tested
+ * without a server, and so the refusal can name what it considered.
+ */
+export interface SpendShape {
+    /** The wallet the money leaves. A grant on another wallet cannot authorize it. */
+    fromWalletId?: string | null;
+    /** Cents. Checked against `max_amount`. */
+    amount: number;
+    /** The wallet receiving it, when known. Checked against `allowed_recipients`. */
+    toWalletId?: string | null;
+    /** The engagement this spend belongs to, when the caller names one. */
+    agreementId?: string | null;
+}
+export interface RejectedGrant {
+    grantId: string;
+    reason: string;
+}
+export interface GrantSelection {
+    grant: GrantView | null;
+    /** Every grant that was looked at and did not fit, with the reason. */
+    rejected: RejectedGrant[];
+}
+/**
+ * Pick the grant to present, preferring the one that belongs to the engagement.
+ *
+ * Order among grants that all fit: the agreement's own grant first when the
+ * spend names one, then the standing grant. A standing grant is the buyer
+ * bootstrap and the right default; reaching for it while an agreement grant
+ * covers the same spend would bill the wrong budget.
+ *
+ * This is a preference, never a fence. Every grant here is already one the
+ * server said this wake may spend, so picking a different one cannot reach
+ * another party's authority — it would only bill the wrong budget of the same
+ * party. That is why the mismatch is no longer a rejection above.
+ */
+export declare function selectPaymentGrant(grants: readonly GrantView[], spend: SpendShape): GrantSelection;
+/**
+ * The sentence an agent gets when nothing fits.
+ *
+ * It names every grant considered and why each was not it, because "no payment
+ * grant" is a condition and an agent cannot act on a condition — it retries,
+ * and every retry is a full model call. Which ceiling was in the way is the
+ * thing that tells the agent whether to ask for a bigger grant, name the
+ * agreement, or stop.
+ */
+export declare function describeNoGrant(verb: string, spend: SpendShape, rejected: readonly RejectedGrant[]): string;

package/dist/http/paymentGrantSelection.js

@@ -0,0 +1,121 @@
+import { grantCaveat } from './grants.js';
+/**
+ * A caveat off a grant that may not carry the array at all.
+ *
+ * `grantCaveat` assumes `caveats` is populated, which the unified list read
+ * does. A caller handing us a partial view should get "no such caveat", not a
+ * crash — this runs on the spend path, where throwing would turn a missing
+ * field into a refused payment.
+ */
+function caveatValue(grant, type) {
+    const caveats = grant.caveats;
+    if (!Array.isArray(caveats))
+        return undefined;
+    return grantCaveat(grant, type);
+}
+function numericCaveat(grant, type) {
+    const raw = caveatValue(grant, type);
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+}
+function recipientCaveat(grant) {
+    const raw = caveatValue(grant, 'allowed_recipients');
+    if (!Array.isArray(raw))
+        return null;
+    const ids = raw.filter((r) => typeof r === 'string');
+    return ids.length ? ids : null;
+}
+/**
+ * Why this grant cannot authorize this spend, or null if it can.
+ *
+ * `daily_budget` is deliberately not checked. It is a ceiling on spend already
+ * made, which only the server can see — guessing here would refuse a grant that
+ * would have worked. The server validates it inside the same transaction as the
+ * ledger write, which is the only place the answer is not already stale.
+ */
+function whyNot(grant, spend) {
+    // A stated kind that is not `wallet` is disqualifying. An ABSENT one is not:
+    // `listGrants` asks the server for `scopeKind: 'wallet'`, so the rail has
+    // already answered, and treating a field the response did not populate as a
+    // wrong answer would refuse every grant. Same reading as an unread source
+    // wallet below — absence means unknown, never no.
+    if (grant.scope?.kind && grant.scope.kind !== 'wallet') {
+        return `is a ${grant.scope.kind} grant, not a wallet grant`;
+    }
+    if (spend.fromWalletId && grant.scope?.id && grant.scope.id !== spend.fromWalletId) {
+        return `is on wallet ${grant.scope.id}, and this spend leaves ${spend.fromWalletId}`;
+    }
+    const maxAmount = numericCaveat(grant, 'max_amount');
+    if (maxAmount !== null && spend.amount > maxAmount) {
+        return `caps a single spend at ${maxAmount}, and this one is ${spend.amount}`;
+    }
+    const allowed = recipientCaveat(grant);
+    if (allowed && spend.toWalletId && !allowed.includes(spend.toWalletId)) {
+        return `may only pay ${allowed.join(', ')}, and this one pays ${spend.toWalletId}`;
+    }
+    // A grant's agreement is NOT checked here, deliberately.
+    //
+    // It used to be refused when it did not match the spend's agreement, which
+    // made a customer's own grant unusable inside their second hire of the same
+    // agent, and made a standing grant unusable on any spend that named a deal.
+    // Whether a grant may be spent at all is the server's answer, and it turns on
+    // who GAVE the grant against who the agent is acting for — not on which of
+    // that party's deals is running. A list the server answered for this wake
+    // holds only grants it may spend, so there is nothing left to refuse here.
+    //
+    // The agreement still decides the ORDER below, which is a budget preference
+    // rather than a question of authority.
+    return null;
+}
+/**
+ * Pick the grant to present, preferring the one that belongs to the engagement.
+ *
+ * Order among grants that all fit: the agreement's own grant first when the
+ * spend names one, then the standing grant. A standing grant is the buyer
+ * bootstrap and the right default; reaching for it while an agreement grant
+ * covers the same spend would bill the wrong budget.
+ *
+ * This is a preference, never a fence. Every grant here is already one the
+ * server said this wake may spend, so picking a different one cannot reach
+ * another party's authority — it would only bill the wrong budget of the same
+ * party. That is why the mismatch is no longer a rejection above.
+ */
+export function selectPaymentGrant(grants, spend) {
+    const rejected = [];
+    const fitting = [];
+    for (const grant of grants) {
+        const reason = whyNot(grant, spend);
+        if (reason)
+            rejected.push({ grantId: grant.grantId, reason });
+        else
+            fitting.push(grant);
+    }
+    if (fitting.length === 0)
+        return { grant: null, rejected };
+    // Explicit both ways, because the deal is no longer a fence: until it was
+    // removed, a deal-bound grant simply never reached this list on a spend that
+    // named nothing, so "prefer the standing grant" happened by accident of the
+    // rejection. Now it has to be said.
+    const standing = fitting.find((g) => !g.agreementId);
+    const preferred = spend.agreementId
+        ? (fitting.find((g) => g.agreementId === spend.agreementId) ?? standing)
+        : standing;
+    return { grant: preferred ?? fitting[0], rejected };
+}
+/**
+ * The sentence an agent gets when nothing fits.
+ *
+ * It names every grant considered and why each was not it, because "no payment
+ * grant" is a condition and an agent cannot act on a condition — it retries,
+ * and every retry is a full model call. Which ceiling was in the way is the
+ * thing that tells the agent whether to ask for a bigger grant, name the
+ * agreement, or stop.
+ */
+export function describeNoGrant(verb, spend, rejected) {
+    if (rejected.length === 0) {
+        return (`${verb}: you hold no active payment grant, so this spend cannot be ` +
+            `authorized. The wallet owner issues one; nothing you can do from here.`);
+    }
+    const lines = rejected.map((r) => `  - ${r.grantId} ${r.reason}`).join('\n');
+    return (`${verb}: none of your ${rejected.length} active payment grant(s) covers ` +
+        `this spend of ${spend.amount}.\n${lines}`);
+}

package/dist/index.d.ts

@@ -12,3 +12,6 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 export { ApiError } from './types.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
+export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
+export * from './shared/operatorKey.js';
+export * from './utils/appUrls.js';

package/dist/index.js

@@ -13,3 +13,6 @@ export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, }
 // half of them had drifted).
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
+export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
+export * from './shared/operatorKey.js';
+export * from './utils/appUrls.js';

package/dist/shared/operatorKey.d.ts

@@ -0,0 +1,47 @@
+/** JWT payload fields we read client-side (signature not verified — identity hint only). */
+export interface OperatorKeyClaims {
+    type?: string;
+    keyId?: string;
+    ownerId?: string;
+    boundAgentId?: string | null;
+    /**
+     * How the key was authorized. MCP consent uses `mcp_oauth` or `device_code`;
+     * provisioning and other mint paths carry their own provenance.
+     */
+    issuedVia?: string;
+    exp?: number;
+}
+/** Decode operator JWT payload without verifying signature (boundAgentId). */
+export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
+export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
+/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
+export declare const ISSUED_VIA_MCP_OAUTH = "mcp_oauth";
+/** The stamp the MCP OAuth device-code flow puts on its tokens. */
+export declare const ISSUED_VIA_DEVICE_CODE = "device_code";
+/**
+ * Did a person board this credential through the connector directory?
+ *
+ * That is the question the tool surface turns on: a connected assistant
+ * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
+ * anyone who configured this server themselves with an operator key gets the
+ * whole thing.
+ *
+ * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
+ * board an assistant through that door — the authorization-code flow and the
+ * device-code flow — and both want the same narrowed surface, but the server
+ * records them as the different acts they are. An equality test against one
+ * value serves the whole catalogue to every credential from the other one.
+ *
+ * Read off the unverified payload. On the remote endpoint the backend verified
+ * the signature before this ran; on stdio the key is the caller's own. Either
+ * way the payload is the one the backend signed. And what hangs on the answer
+ * is which tools are registered, not what a call may do: every call is still
+ * authorized by the backend. Provenance may decide what is OFFERED, never what
+ * is PERMITTED.
+ */
+export declare function isDirectoryBoarded(claims: OperatorKeyClaims | null): boolean;
+/** Routing hint only. Every request is still authenticated by the backend. */
+export declare function isMcpOAuthDelegateSession(creds: {
+    operatorKey: string;
+    agentId: string;
+}): boolean;

package/dist/shared/operatorKey.js

@@ -0,0 +1,64 @@
+/** Decode operator JWT payload without verifying signature (boundAgentId). */
+export function decodeOperatorKeyClaims(token) {
+    const trimmed = token.trim();
+    const parts = trimmed.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const encoded = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = new TextDecoder().decode(Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0)));
+        const payload = JSON.parse(json);
+        return {
+            type: payload.type,
+            keyId: payload.keyId,
+            ownerId: payload.ownerId,
+            boundAgentId: typeof payload.boundAgentId === 'string' ? payload.boundAgentId : null,
+            issuedVia: typeof payload.issuedVia === 'string' ? payload.issuedVia : undefined,
+            exp: payload.exp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isOperatorKeyExpired(claims) {
+    if (!claims?.exp)
+        return false;
+    return claims.exp * 1000 <= Date.now();
+}
+/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
+export const ISSUED_VIA_MCP_OAUTH = 'mcp_oauth';
+/** The stamp the MCP OAuth device-code flow puts on its tokens. */
+export const ISSUED_VIA_DEVICE_CODE = 'device_code';
+/**
+ * Did a person board this credential through the connector directory?
+ *
+ * That is the question the tool surface turns on: a connected assistant
+ * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
+ * anyone who configured this server themselves with an operator key gets the
+ * whole thing.
+ *
+ * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
+ * board an assistant through that door — the authorization-code flow and the
+ * device-code flow — and both want the same narrowed surface, but the server
+ * records them as the different acts they are. An equality test against one
+ * value serves the whole catalogue to every credential from the other one.
+ *
+ * Read off the unverified payload. On the remote endpoint the backend verified
+ * the signature before this ran; on stdio the key is the caller's own. Either
+ * way the payload is the one the backend signed. And what hangs on the answer
+ * is which tools are registered, not what a call may do: every call is still
+ * authorized by the backend. Provenance may decide what is OFFERED, never what
+ * is PERMITTED.
+ */
+export function isDirectoryBoarded(claims) {
+    return (claims?.issuedVia === ISSUED_VIA_MCP_OAUTH ||
+        claims?.issuedVia === ISSUED_VIA_DEVICE_CODE);
+}
+/** Routing hint only. Every request is still authenticated by the backend. */
+export function isMcpOAuthDelegateSession(creds) {
+    const claims = decodeOperatorKeyClaims(creds.operatorKey);
+    return (!!creds.agentId &&
+        claims?.boundAgentId === creds.agentId &&
+        isDirectoryBoarded(claims));
+}