@ziggs-ai/api-client 0.15.1 → 0.17.0

package/dist/http/GrantsClient.d.ts

@@ -56,7 +56,16 @@ export declare class GrantsClient {
     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. The server reads off it who the agent is acting for, and
+     *   answers the spendable rails with only the grants this wake may spend —
+     *   so an agent serving several customers is never handed a list it has to
+     *   choose between. Without it the list is everything the agent holds, and
+     *   the grant it picks may then be refused with nothing saying why.
+     */
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     listGrants(query?: ListGrantsQuery): Promise<ListGrantsResult>;
     /**
      * Every grant matching `query`, following the cursor to completion. Use when a

package/dist/http/GrantsClient.js

@@ -12,12 +12,22 @@ export class GrantsClient {
     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. The server reads off it who the agent is acting for, and
+     *   answers the spendable rails with only the grants this wake may spend —
+     *   so an agent serving several customers is never handed a list it has to
+     *   choose between. Without it the list is everything the agent holds, and
+     *   the grant it picks may then be refused with nothing saying why.
+     */
+    constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)
             throw new Error('GrantsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     async listGrants(query = {}) {
         const url = new URL(`${this.baseUrl}/grants`);
@@ -41,7 +51,7 @@ export class GrantsClient {
         if (query.limit != null)
             url.searchParams.set('limit', String(query.limit));
         const res = await fetch(url.toString(), {
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, undefined, this.laneId),
         });
         const body = await res.text().catch(() => '');
         if (!res.ok) {

package/dist/http/IntroductionsClient.d.ts

@@ -5,15 +5,16 @@ export interface IntroductionFrom {
     orgId: string;
     agentId: string | null;
     agentCreatedAt?: string | null;
-    claimedLabel?: {
+    claimedLabel: {
         text: string;
         selfChosen: boolean;
         verified: boolean;
     };
     /**
-     * Same text as claimedLabel.text. Not identity — anyone can pick it.
+     * Same text as claimedLabel.text. Not identity. Remove after 2026-10-07;
+     * readers must use claimedLabel.
      */
-    label: string;
+    label?: string;
 }
 export interface IntroductionView {
     token: string;
@@ -41,7 +42,13 @@ export interface IntroductionView {
     counterparty?: {
         principal: string;
         agentId: string | null;
-        label: string;
+        claimedLabel: {
+            text: string;
+            selfChosen: boolean;
+            verified: boolean;
+        };
+        /** Same text as claimedLabel.text. Remove after 2026-10-07. */
+        label?: string;
         nextStep: string;
     };
 }

package/dist/http/MarketplaceClient.js

@@ -2,17 +2,10 @@
 import { shapeAgreement } from './AgreementClient.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 function getMarketplaceBaseUrl() { return `${getBackendUrl()}/marketplace`; }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);

package/dist/http/OrgsClient.d.ts

@@ -27,20 +27,6 @@ export type OrgResolution = {
  * match. Ambiguous names return the candidates rather than guessing.
  */
 export declare function resolveOrgSelector(orgs: MyOrg[], selector: string): OrgResolution;
-/**
- * MCP OAuth auto-provisioned delegate id prefix.
- *
- * The backend stopped classifying delegates by their id and now reads a stamp
- * on the agent row, which is what freed the prefix to drop the vendor name. A
- * client holds credentials, not rows, so this is still a shape test — but it is
- * a shape test against a NAME, and the only thing it decides is which access
- * endpoint to read. It said `delegate--` until the ids were renamed;
- * left alone, every delegate session would have fallen through to the hosted
- * reader and reported the wrong org and connection state.
- */
-export declare const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = "delegate--";
-/** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
-export declare function isMcpOAuthDelegateAgentId(agentId: string): boolean;
 /**
  * runtime acting org from the server (self-hire / agent
  * row): GET /agents/delegate/access. Moved here from ziggs-mcp's inline

package/dist/http/OrgsClient.js

@@ -1,3 +1,4 @@
+import { isMcpOAuthDelegateSession } from '../shared/operatorKey.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
@@ -42,22 +43,6 @@ export function resolveOrgSelector(orgs, selector) {
         return { status: 'ambiguous', matches: byName };
     return { status: 'not-found' };
 }
-/**
- * MCP OAuth auto-provisioned delegate id prefix.
- *
- * The backend stopped classifying delegates by their id and now reads a stamp
- * on the agent row, which is what freed the prefix to drop the vendor name. A
- * client holds credentials, not rows, so this is still a shape test — but it is
- * a shape test against a NAME, and the only thing it decides is which access
- * endpoint to read. It said `delegate--` until the ids were renamed;
- * left alone, every delegate session would have fallen through to the hosted
- * reader and reported the wrong org and connection state.
- */
-export const MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX = 'delegate--';
-/** True when `agentId` is an inbound MCP OAuth auto-provisioned delegate. */
-export function isMcpOAuthDelegateAgentId(agentId) {
-    return !!agentId && agentId.startsWith(MCP_OAUTH_DELEGATE_AGENT_ID_PREFIX);
-}
 /**
  * runtime acting org from the server (self-hire / agent
  * row): GET /agents/delegate/access. Moved here from ziggs-mcp's inline
@@ -125,7 +110,7 @@ export async function fetchHostedAgentAccess(creds, baseUrl) {
  * Claude OAuth delegates → self-hire status; everything else → hosted path.
  */
 export async function fetchSessionAccess(creds, baseUrl) {
-    if (isMcpOAuthDelegateAgentId(creds.agentId)) {
+    if (isMcpOAuthDelegateSession(creds)) {
         return fetchDelegateAccess(creds, baseUrl);
     }
     return fetchHostedAgentAccess(creds, baseUrl);

package/dist/http/PaymentsClient.d.ts

@@ -87,7 +87,21 @@ 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;
@@ -99,7 +113,12 @@ export declare class PaymentsClient {
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
-        /** The engagement this spend belongs to, so its own grant is preferred. */
+        /**
+         * 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, agreementId, }: {
@@ -107,7 +126,12 @@ export declare class PaymentsClient {
         idempotencyKey?: string;
         description?: string;
         paymentGrantId?: string;
-        /** The engagement this spend belongs to, so its own grant is preferred. */
+        /**
+         * 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>;
     /**

package/dist/http/PaymentsClient.js

@@ -18,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'));
@@ -180,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, } = {}) {
@@ -261,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

@@ -1,17 +1,10 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { partyActorIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
+import { buildCredsHeaders } from './operatorHeaders.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
-function buildHeaders(creds) {
-    return {
-        'content-type': 'application/json',
-        Authorization: `Bearer ${creds.operatorKey}`,
-        'X-Agent-Id': creds.agentId,
-        // the wake's lane, so the backend can fence this call to the
-        // engagement it belongs to rather than the agent's whole authority.
-        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
-    };
-}
+// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
+const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);
@@ -165,7 +158,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/index.d.ts

@@ -23,8 +23,9 @@ 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';
 export { InboxClient } from './InboxClient.js';
+export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';

package/dist/http/index.js

@@ -15,7 +15,11 @@ 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';
+// The lane header, built in one place — see operatorHeaders.ts. Exported
+// because the MCP transports in agent-sdk and ziggs-mcp send it too, and a
+// copy of a header nobody notices missing goes stale unseen.
+export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';

package/dist/http/operatorHeaders.d.ts

@@ -1,8 +1,21 @@
 /**
- * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
- * an agentId is present — agent-scoped keys identify the agent themselves;
- * fleet keys must pass one.
+ * Auth headers for operator-key HTTP clients.
+ *
+ * ONE place builds them, because the lane is the header a caller cannot be
+ * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
+ * the wake to the agent's own org instead, so a door that forgets it answers
+ * short lists and refuses grants the agent's customer gave it — silently, and
+ * only for the agents that serve someone other than their owner. A header
+ * whose absence is indistinguishable from a legitimate answer has to be built
+ * in one place, not copied into each caller.
  */
+/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
+export declare const WAKE_LANE_HEADER = "X-Ziggs-Lane";
+/**
+ * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
+ * for a task with no origin chat.
+ */
+export declare function laneHeader(laneId?: string): Record<string, string>;
 export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 
 /**
  * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
@@ -10,3 +23,9 @@ export declare function buildOperatorHeaders(operatorKey: string, agentId?: stri
  * narrows to the agent's own org, so it can never widen reach.
  */
 laneId?: string): Record<string, string>;
+/** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
+export declare function buildCredsHeaders(creds: {
+    operatorKey: string;
+    agentId: string;
+    laneId?: string;
+}): Record<string, string>;

package/dist/http/operatorHeaders.js

@@ -1,8 +1,23 @@
 /**
- * Auth headers for operator-key HTTP clients. `X-Agent-Id` is only sent when
- * an agentId is present — agent-scoped keys identify the agent themselves;
- * fleet keys must pass one.
+ * Auth headers for operator-key HTTP clients.
+ *
+ * ONE place builds them, because the lane is the header a caller cannot be
+ * trusted to remember. Omitting `X-Ziggs-Lane` never fails: the server fences
+ * the wake to the agent's own org instead, so a door that forgets it answers
+ * short lists and refuses grants the agent's customer gave it — silently, and
+ * only for the agents that serve someone other than their owner. A header
+ * whose absence is indistinguishable from a legitimate answer has to be built
+ * in one place, not copied into each caller.
  */
+/** The header the backend's wake fence reads (`access/wake-fence.ts`). */
+export const WAKE_LANE_HEADER = 'X-Ziggs-Lane';
+/**
+ * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
+ * for a task with no origin chat.
+ */
+export function laneHeader(laneId) {
+    return laneId ? { [WAKE_LANE_HEADER]: laneId } : {};
+}
 export function buildOperatorHeaders(operatorKey, agentId, extra, 
 /**
  * the lane this call belongs to, sent as `X-Ziggs-Lane`. The
@@ -12,8 +27,17 @@ export function buildOperatorHeaders(operatorKey, agentId, extra,
 laneId) {
     return {
         Authorization: `Bearer ${operatorKey}`,
+        // `X-Agent-Id` is only sent when an agentId is present — agent-scoped keys
+        // identify the agent themselves; fleet keys must pass one.
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),
-        ...(laneId ? { 'X-Ziggs-Lane': laneId } : {}),
+        ...laneHeader(laneId),
         ...extra,
     };
 }
+/** What a `Creds`-shaped client sends on a JSON call: auth, agent, lane. */
+export function buildCredsHeaders(creds) {
+    return {
+        'content-type': 'application/json',
+        ...buildOperatorHeaders(creds.operatorKey, creds.agentId, undefined, creds.laneId),
+    };
+}

package/dist/http/paymentGrantSelection.d.ts

@@ -39,6 +39,11 @@ export interface GrantSelection {
  * 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;
 /**

package/dist/http/paymentGrantSelection.js

@@ -52,18 +52,18 @@ function whyNot(grant, spend) {
     if (allowed && spend.toWalletId && !allowed.includes(spend.toWalletId)) {
         return `may only pay ${allowed.join(', ')}, and this one pays ${spend.toWalletId}`;
     }
-    // An agreement-conferred grant is FOR that agreement's work. Spending it on
-    // something else would pass every caveat above and still be the wrong money:
-    // the ceiling was agreed for one engagement, and nothing on the wire would
-    // show it had been used for another.
-    if (grant.agreementId) {
-        if (!spend.agreementId) {
-            return `belongs to agreement ${grant.agreementId}, and this spend names no agreement`;
-        }
-        if (grant.agreementId !== spend.agreementId) {
-            return `belongs to agreement ${grant.agreementId}, not ${spend.agreementId}`;
-        }
-    }
+    // 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;
 }
 /**
@@ -73,6 +73,11 @@ function whyNot(grant, spend) {
  * 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 = [];
@@ -86,10 +91,15 @@ export function selectPaymentGrant(grants, spend) {
     }
     if (fitting.length === 0)
         return { grant: null, rejected };
-    const forAgreement = spend.agreementId
-        ? fitting.find((g) => g.agreementId === spend.agreementId)
-        : undefined;
-    return { grant: forAgreement ?? fitting[0], 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.

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));
+}