@ziggs-ai/api-client 0.15.1 → 0.16.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -9,6 +9,15 @@ export declare const agreementRequestCapability: CapabilityDefinition;
  * to be doing today, and the publish path says so at its own end
  * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
  * listing when the job ended.
+ *
+ * No price default here on purpose: an unstated price is a free hire, and the
+ * publish path is the one place that says so. Stating a price publishes a paid
+ * listing.
+ *
+ * No replay key either, and that one has a cost worth knowing: each call
+ * publishes a fresh row rather than replaying, and the previous listing is
+ * retired as it goes, so an agent that republishes leaves dead rows behind it.
+ * One listing per agent still holds; the churn does not.
  */
 export declare const agreementOfferCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -92,7 +92,7 @@ function engagementKindFrom(args) {
  */
 const MANDATE_PARAM = {
     type: 'string',
-    description: 'The active agreement whose work this is part of — the job you are doing. It becomes this engagement\'s parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job.',
+    description: "The active agreement whose work this is part of — the job you are doing. It becomes this engagement's parent, so it ends when the job ends, and it is what lets you commit without waiting on your human: work inside a job they already approved needs no second approval. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job. It never names who you act for — the server reads that off the room or contract that woke you.",
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
@@ -286,6 +286,15 @@ export const agreementRequestCapability = {
  * to be doing today, and the publish path says so at its own end
  * (`POST /marketplace/offers/publish`). Hanging one under a job would kill the
  * listing when the job ended.
+ *
+ * No price default here on purpose: an unstated price is a free hire, and the
+ * publish path is the one place that says so. Stating a price publishes a paid
+ * listing.
+ *
+ * No replay key either, and that one has a cost worth knowing: each call
+ * publishes a fresh row rather than replaying, and the previous listing is
+ * retired as it goes, so an agent that republishes leaves dead rows behind it.
+ * One listing per agent still holds; the churn does not.
  */
 export const agreementOfferCapability = {
     key: 'agreement_offer',

package/dist/capabilities/agreements.js

@@ -1,3 +1,4 @@
+import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
 import { fullCreds } from './types.js';
@@ -25,7 +26,7 @@ export function presentClaimResult(agreement, kind, env) {
     }
     if (agreement?.status !== 'active') {
         const held = (agreement?.approvals ?? []).find((a) => a.status === 'pending');
-        const approveUrl = `${webAppOrigin(env)}/app/agreements/${agreement.agreementId}`;
+        const approveUrl = agreementAppUrl(webAppOrigin(env), agreement.agreementId);
         const remedy = held?.heldReason === 'contact-basis'
             ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
             : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';

package/dist/capabilities/artifacts.js

@@ -1,6 +1,7 @@
 import { ArtifactsClient } from '../http/ArtifactsClient.js';
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 /**
  * teaching: name the result slot on the success path so an agent finds
  * the right move unaided — worded in each surface's task grammar (SDK
@@ -90,6 +91,7 @@ async function recordFileArtifact(args, env, visibility) {
     const byteSize = bytes.byteLength;
     const uploaded = await client.uploadUrl({
         filename,
+        name: args['name']?.trim() || undefined,
         mime,
         // The byte length of what will be PUT, not of the base64 envelope — the
         // presign signs this number and S3 rejects a mismatch.
@@ -134,9 +136,8 @@ export const recordArtifactCapability = {
             'taskId to bind it to the task. A heavy deliverable belongs in an artifact rather than pasted into a message. ' +
             ARTIFACT_RECORD_INLINE_CAP,
         mcp: 
-        // Canonical for ziggs-mcp (tools.ts must not override). Last paragraph is
-        // PROTOCOL.reporting copied verbatim — api-client cannot import ziggs-mcp;
-        // record-artifact-teaching.test.ts gates the live tool against both.
+        // Canonical for ziggs-mcp (tools.ts must not override). Shared protocol
+        // (where finished work goes) lives on connect instructions.
         'Write an artifact — text (text) or a file (filename + mime + contentBase64; presign, upload ' +
             'and completion all happen inside this one call, so there is no separate upload dance). ' +
             'Scope is optional — pass agreementId or chatId to record it into that ' +
@@ -144,8 +145,7 @@ export const recordArtifactCapability = {
             'free-standing artifact that is yours until you attach or share it. Never guess a scope: ' +
             'recording with none always succeeds. Set visibility explicitly. ' +
             'For a finished deliverable, set contentType=result and pass taskId to bind it to the task. ' +
-            ARTIFACT_RECORD_INLINE_CAP +
-            ' Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.',
+            ARTIFACT_RECORD_INLINE_CAP,
     },
     annotation: 'write',
     params: {
@@ -157,6 +157,10 @@ export const recordArtifactCapability = {
             type: 'string',
             description: 'Base64 file bytes for a file artifact — requires filename and mime. This call presigns, uploads and completes; you never compute a checksum. Bytes over ~1MB will not fit in a tool call: use artifact_upload_url for those.',
         },
+        name: {
+            type: 'string',
+            description: 'Short name shown in lists (room, agreement, artifacts page). Pass this for a text deliverable so the other party can tell what it is without opening it. A file defaults to filename when omitted.',
+        },
         filename: {
             type: 'string',
             description: 'Original filename — required with contentBase64',
@@ -232,6 +236,7 @@ export const recordArtifactCapability = {
         const creds = fullCreds(env);
         const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
             text,
+            name: args['name']?.trim() || undefined,
             visibility,
             chatId,
             agreementId,
@@ -275,14 +280,19 @@ export const listArtifactsCapability = {
             description: 'ISO timestamp — return only artifacts written strictly after this',
         },
         limit: { type: 'number', description: 'Page size (server default when omitted)' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
-        return new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
+        const listed = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
             after: args['after'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
+        const fields = parseListFields(args['fields']);
+        return fields
+            ? { ...listed, artifacts: pickListedRows(listed.artifacts, fields) }
+            : listed;
     },
 };
 /**

package/dist/capabilities/connections.js

@@ -1,11 +1,11 @@
 import { ConnectionsClient } from "../http/ConnectionsClient.js";
 import { rethrowWithContext, } from "./types.js";
 function client(env) {
-    // laneId, not just the key and the agent. The lane is which engagement this
-    // wake is in, and the broker needs it to tell one hirer's grant from
-    // another's: an agent that serves several hirers is the holder of every grant
-    // it has been given, so the holder check alone cannot separate them. Every
-    // other Creds-based client already carries it.
+    // laneId, not just the key and the agent. The lane is which hire this wake is
+    // in, and the broker reads off it who the agent is acting for — which is what
+    // tells one hirer's grant from another's: an agent that serves several hirers
+    // is the holder of every grant it has been given, so the holder check alone
+    // cannot separate them. Every other Creds-based client already carries it.
     const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error("operatorKey missing from tool context");

package/dist/capabilities/grants.js

@@ -1,6 +1,7 @@
 import { GrantsClient } from '../http/GrantsClient.js';
 import { GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 // BOTH the tool's param enum and its validator, so a missing kind makes the
 // filter the description advertises fail validation. Derived from the canonical
 // list next to the type rather than restated, because that is exactly how
@@ -67,6 +68,7 @@ export const listGrantsCapability = {
         },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         limit: { type: 'number', description: 'Page size (server default when omitted)' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -80,7 +82,10 @@ export const listGrantsCapability = {
         if (roleArg !== undefined && roleArg !== 'holder' && roleArg !== 'issuer') {
             throw new Error('role must be holder or issuer');
         }
-        const { items, nextCursor, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).listGrants({
+        const { items, nextCursor, unreadableRails } = await new GrantsClient(creds.operatorKey, creds.agentId, env.baseUrl, 
+        // The lane, so the server answers with the grants THIS wake may spend
+        // rather than everything the agent holds across every customer.
+        creds.laneId).listGrants({
             scopeKind,
             scopeId: typeof args['scopeId'] === 'string' ? args['scopeId'] : undefined,
             role: roleArg,
@@ -89,9 +94,10 @@ export const listGrantsCapability = {
             cursor: args['cursor'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
+        const fields = parseListFields(args['fields']);
         return {
             count: items.length,
-            grants: items,
+            grants: pickListedRows(items, fields),
             nextCursor,
             ...(unreadableRails?.length ? { unreadableRails } : {}),
         };

package/dist/capabilities/index.d.ts

@@ -5,6 +5,7 @@ export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
 export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/index.js

@@ -5,6 +5,7 @@ export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
+export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
 export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';

package/dist/capabilities/links.js

@@ -1,9 +1,9 @@
+import { resolveWebAppOrigin, connectInviteAppUrl } from '../utils/appUrls.js';
 import { createLink, listAgreements } from '../http/AgreementClient.js';
 import { nextCall } from './nextCall.js';
 import { fullCreds } from './types.js';
-const DEFAULT_WEB_URL = 'https://ziggsai.com';
 export function webAppOrigin(env) {
-    return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
+    return resolveWebAppOrigin(env.webUrl);
 }
 /**
  * The one thing an invite travels as: `/connect/<inviteId>`.
@@ -17,7 +17,7 @@ export function webAppOrigin(env) {
  * across two repos.
  */
 function inviteShareUrl(env, agreementId) {
-    return `${webAppOrigin(env)}/connect/${agreementId}`;
+    return connectInviteAppUrl(webAppOrigin(env), agreementId);
 }
 /**
  * A link is reach-only — the follow-up move differs by surface tool names.

package/dist/capabilities/listedFields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Opt-in row projection for list tools.
+ *
+ * List endpoints return the full row by default. Pass `fields` to keep only
+ * those keys — the same shape as Linear's `list_issues`. Envelope keys
+ * (count, nextCursor, hasMore) are never filtered.
+ */
+export declare const LIST_FIELDS_PARAM: {
+    type: "array";
+    items: {
+        type: "string";
+    };
+    description: string;
+};
+export declare function parseListFields(raw: unknown): string[] | undefined;
+export declare function pickListedRow(row: Record<string, unknown>, fields: string[] | undefined): Record<string, unknown>;
+export declare function pickListedRows(rows: unknown[], fields: string[] | undefined): unknown[];

package/dist/capabilities/listedFields.js

@@ -0,0 +1,45 @@
+/**
+ * Opt-in row projection for list tools.
+ *
+ * List endpoints return the full row by default. Pass `fields` to keep only
+ * those keys — the same shape as Linear's `list_issues`. Envelope keys
+ * (count, nextCursor, hasMore) are never filtered.
+ */
+export const LIST_FIELDS_PARAM = {
+    type: 'array',
+    items: { type: 'string' },
+    description: 'Return only these keys on each row. Omit for the full row. Keep the id you will use next (agreementId, taskId, artifactId, grantId).',
+};
+export function parseListFields(raw) {
+    if (raw == null)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error('fields must be a non-empty array of row key names');
+    }
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== 'string' || !item.trim()) {
+            throw new Error('fields entries must be non-empty strings');
+        }
+        if (!out.includes(item))
+            out.push(item);
+    }
+    return out;
+}
+export function pickListedRow(row, fields) {
+    if (!fields)
+        return row;
+    const picked = {};
+    for (const key of fields) {
+        if (key in row)
+            picked[key] = row[key];
+    }
+    return picked;
+}
+export function pickListedRows(rows, fields) {
+    if (!fields)
+        return rows;
+    return rows.map((row) => row && typeof row === 'object' && !Array.isArray(row)
+        ? pickListedRow(row, fields)
+        : row);
+}

package/dist/capabilities/marketplace.js

@@ -1,6 +1,7 @@
 import { pullOffers, pullRequests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
     const propose = env.surface === 'mcp' ? 'ziggs_agreement_request' : 'agreement_request';
@@ -77,6 +78,7 @@ export const marketplaceViewCapability = {
         },
         limit: { type: 'number', description: 'Max rows per kind (default 20)' },
         since: { type: 'string', description: 'ISO timestamp — only rows published after this' },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -93,12 +95,15 @@ export const marketplaceViewCapability = {
             kind === 'offers' ? Promise.resolve([]) : pullRequests(options, creds),
             kind === 'requests' ? Promise.resolve([]) : pullOffers(options, creds),
         ]);
+        const fields = parseListFields(args['fields']);
+        const requestRows = pickListedRows(requests.map((q) => toListingRow(q, 'request')), fields);
+        const offerRows = pickListedRows(offers.map((o) => toListingRow(o, 'offer')), fields);
         return {
             ...(kind !== 'offers'
-                ? { requests: requests.map((q) => toListingRow(q, 'request')), requestCount: requests.length }
+                ? { requests: requestRows, requestCount: requests.length }
                 : {}),
             ...(kind !== 'requests'
-                ? { offers: offers.map((o) => toListingRow(o, 'offer')), offerCount: offers.length }
+                ? { offers: offerRows, offerCount: offers.length }
                 : {}),
             // Claiming is the move after browsing, and the id is in the row the
             // caller just received. The prose hint stays for the publish side, which

package/dist/capabilities/payments.js

@@ -1,10 +1,15 @@
 import { PaymentsClient } from '../http/PaymentsClient.js';
 import { rethrowWithContext, } from './types.js';
 function client(env) {
-    const { operatorKey, agentId } = env.creds;
+    // laneId too, like every other Creds-based client. Only the balance read is
+    // on this surface today, and a read does not spend — but the lane is what
+    // fences a spend to the job it was authorised in, so it is wired here rather
+    // than left for whoever brings a spending verb back to remember. Omitting it
+    // can only leave a spend unfenced; it can never widen one.
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    return new PaymentsClient(operatorKey, agentId, env.baseUrl);
+    return new PaymentsClient(operatorKey, agentId, env.baseUrl, laneId);
 }
 /**
  * Reading the balance is the whole rail on an agent surface.

package/dist/capabilities/tasks.js

@@ -1,5 +1,6 @@
 import { listTasks } from '../http/TaskClient.js';
 import { fullCreds } from './types.js';
+import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 /**
  * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
  * same GET /tasks filters; assignedToMe vs assignedTo precedence then
@@ -11,8 +12,8 @@ export const listTasksCapability = {
     names: { sdk: 'task_list', mcp: 'ziggs_task_list' },
     title: 'List tasks',
     descriptions: {
-        sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
-        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else.',
+        sdk: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
+        mcp: 'List tasks reachable by the acting agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work, and createdByMe to list the work you handed to someone else. Pass fields to keep only those keys on each row.',
     },
     annotation: 'read-only',
     params: {
@@ -40,6 +41,7 @@ export const listTasksCapability = {
             type: 'boolean',
             description: "Shorthand for assignedTo=<this agent's id>. Takes precedence over assignedTo when both are set.",
         },
+        fields: LIST_FIELDS_PARAM,
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -48,13 +50,17 @@ export const listTasksCapability = {
             ? creds.agentId
             : args['assignedTo'];
         const createdBy = args['createdByMe'] ? creds.agentId : undefined;
-        return listTasks({
+        const listed = await listTasks({
             state: args['state'],
             cursor: args['cursor'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
             assignedTo,
             ...(createdBy ? { createdBy } : {}),
         }, creds);
+        const fields = parseListFields(args['fields']);
+        return fields
+            ? { ...listed, tasks: pickListedRows(listed.tasks, fields) }
+            : listed;
     },
 };
 export const TASK_CAPABILITIES = [listTasksCapability];

package/dist/http/ArtifactsClient.d.ts

@@ -28,6 +28,8 @@ export interface ListArtifactsResult {
 }
 export interface WriteArtifactInput {
     text: string;
+    /** Short list name. An upload defaults to filename when omitted. */
+    name?: string;
     contentType?: string;
     visibility?: ArtifactVisibility;
     /** When the artifact is associated with a chat. */
@@ -47,6 +49,8 @@ export interface WriteArtifactInput {
 }
 export type ArtifactFileFormat = 'pdf' | 'docx' | 'hwpx' | 'md' | 'txt' | 'html';
 export interface ArtifactUploadUrlInput {
+    /** Short list name. Defaults to filename on the server when omitted. */
+    name?: string;
     filename: string;
     mime: string;
     /** Exact UTF-8 / file byte length of the object that will be PUT. */
@@ -82,22 +86,7 @@ export type ArtifactFileView = Record<string, unknown> & {
     extractionError?: string | null;
     filename?: string | null;
 };
-/**
- * Replaces `ContextReader`'s artifact reads + `ContextWriter`'s breadcrumb
- * writes. `visibility: 'agent-private'` is the new home for agent thoughts —
- * they persist, are searchable, but are not visible to other chat parties.
- */
-/**
- * turn a runtime lane id into a scope the backend can accept.
- *
- * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
- * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
- * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
- * thought on an agreement lane come back 403 "not authorized for this scope" —
- * a fictional scope reading like an auth failure. The work is agreement-scoped,
- * so say so; same rule settled for deliverables.
- */
-export declare const AGREEMENT_LANE_PREFIX = "agrn-";
+export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
 export declare function artifactScopeForSession(sessionId: string): {
     chatId: string;
 } | {

package/dist/http/ArtifactsClient.js

@@ -33,17 +33,18 @@ function resolveUploadBytes(input) {
  * turn a runtime lane id into a scope the backend can accept.
  *
  * A task with no origin chat runs on the lane `agrn-<agreementId>` (see
- * AgentHost.laneSessionIdForTask). That is a routing key, not a chat: no such
+ * Agent.laneSessionIdForTask). That is a routing key, not a chat: no such
  * chat row exists, so passing it as `chatId` made every breadcrumb and recorded
  * thought on an agreement lane come back 403 "not authorized for this scope" —
  * a fictional scope reading like an auth failure. The work is agreement-scoped,
  * so say so; same rule settled for deliverables.
  */
-export const AGREEMENT_LANE_PREFIX = 'agrn-';
+import { agreementIdFromLane } from '@ziggs-ai/contracts';
+export { AGREEMENT_LANE_PREFIX } from '@ziggs-ai/contracts';
 export function artifactScopeForSession(sessionId) {
-    if (sessionId.startsWith(AGREEMENT_LANE_PREFIX)) {
-        return { agreementId: sessionId.slice(AGREEMENT_LANE_PREFIX.length) };
-    }
+    const agreementId = agreementIdFromLane(sessionId);
+    if (agreementId)
+        return { agreementId };
     return { chatId: sessionId };
 }
 export class ArtifactsClient {
@@ -145,6 +146,7 @@ export class ArtifactsClient {
             headers: this._headers(),
             body: JSON.stringify({
                 text,
+                ...(input.name?.trim() ? { name: input.name.trim() } : {}),
                 contentType: input.contentType ?? 'text',
                 visibility: input.visibility ?? 'chat',
                 chatId: input.chatId,
@@ -214,6 +216,7 @@ export class ArtifactsClient {
         }
         const parsed = await this._post('/artifacts/upload-url', {
             filename: input.filename.trim(),
+            ...(input.name?.trim() ? { name: input.name.trim() } : {}),
             mime: input.mime.trim(),
             byteSize: input.byteSize,
             format: input.format,

package/dist/http/ChatClient.d.ts

@@ -1,3 +1,4 @@
+import type { SendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
 /** Shape of GET /chats/mine items — the backend's ChatReadDto. */
 export interface ChatSummary {
@@ -41,12 +42,7 @@ export interface SendChatMessageInput {
     contentType?: string;
     underAgreementId?: string;
 }
-export interface SendChatMessageResult {
-    success: boolean;
-    message: string;
-    messageId: string;
-    chatId: string;
-}
+export type { SendChatMessageResult } from '@ziggs-ai/contracts';
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface AddChatMemberInput {
     chatId: string;

package/dist/http/ConnectionsClient.d.ts

@@ -59,10 +59,12 @@ export declare class ConnectionsClient {
     private readonly laneId?;
     /**
      * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
-     *   an agent that serves several hirers holds all of their grants at once, so
-     *   without a lane one hirer's grant is indistinguishable from another's, and
-     *   a grant issued for one job can be spent inside a different one.
+     *   X-Ziggs-Lane. It tells the broker which hire this wake is in, and the
+     *   broker reads off it WHO the agent is acting for: an agent that serves
+     *   several hirers holds all of their grants at once and is the holder of
+     *   every one, so without a lane one hirer's grant is indistinguishable from
+     *   another's, and a grant one customer gave can be spent while working for
+     *   somebody else.
      *   ArtifactsClient sends the same header for the same reason.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);

package/dist/http/ConnectionsClient.js

@@ -37,10 +37,12 @@ export class ConnectionsClient {
     laneId;
     /**
      * @param laneId the wake's lane (a chat id, or `agrn-<agreementId>`), sent as
-     *   X-Ziggs-Lane. It tells the broker which engagement is spending a grant:
-     *   an agent that serves several hirers holds all of their grants at once, so
-     *   without a lane one hirer's grant is indistinguishable from another's, and
-     *   a grant issued for one job can be spent inside a different one.
+     *   X-Ziggs-Lane. It tells the broker which hire this wake is in, and the
+     *   broker reads off it WHO the agent is acting for: an agent that serves
+     *   several hirers holds all of their grants at once and is the holder of
+     *   every one, so without a lane one hirer's grant is indistinguishable from
+     *   another's, and a grant one customer gave can be spent while working for
+     *   somebody else.
      *   ArtifactsClient sends the same header for the same reason.
      */
     constructor(operatorKey, agentId, baseUrl, laneId) {
@@ -101,7 +103,7 @@ export class ConnectionsClient {
      * defensively for leaked secrets, as `proxy` does.
      */
     async listForHolder() {
-        const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
+        const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl, this.laneId);
         // All pages of the agent's live connection grants (not just the first page).
         const { items, unreadableRails } = await grantsClient.listAllGrantsWithRails({
             scopeKind: "connection",

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/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

@@ -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/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

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

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { InboxRequestChannel } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
  *
@@ -259,19 +260,7 @@ export type BroadcastAudience = typeof OPEN_AGREEMENT_TARGET | typeof ORG_AGREEM
 export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
 /** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
 export declare function isBroadcastTarget(id: string | null | undefined): boolean;
-/**
- * Persona face id (`psn_*`). Non-addressable — never use for agent lookup,
- * wake, or payment parties.
- */
-export declare function isPersonaRef(id: string | null | undefined): boolean;
-/**
- * Room presentation binding id (`rpb_*`). Opaque to account lookup / wake /
- * pay. Chat sends may echo it as `receiverId` — the backend resolves it in-room
- *.
- */
-export declare function isRoomPresentationRef(id: string | null | undefined): boolean;
-/** Either opaque presentation ref (`psn_*` | `rpb_*`). */
-export declare function isOpaquePresentationRef(id: string | null | undefined): boolean;
+export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';
 /** Display + entitlement face for a principal on the message/roster wire. */
 export interface PrincipalPresentation {
     /** Public, non-addressable reference (`psn_*` or `rpb_*`). */
@@ -332,7 +321,7 @@ export interface MessageMetadata {
     agreementId?: string | null;
     /**
      * Message send time from the wire payload. The live-path inbox
-     * watermark ack (AgentHost, P4) needs it — without a timestamp the
+     * watermark ack (Agent, P4) needs it — without a timestamp the
      * ack never fires and catch-up re-delivers the chat's whole backlog after a
      * host eviction, re-running already-answered goals.
      */
@@ -472,14 +461,8 @@ export interface InboxTaskRef {
  * A marketplace request doorbell. Own channel so the host can
  * exact-match triage with zero LLM tokens before any wake.
  */
-export interface InboxRequestRef {
-    agreementId: string;
-    /** Exact-match string from the publisher — compare to the agent's tags. */
-    match: string;
-    title: string;
-    ts: string;
-}
-export interface InboxEnvelope {
+export type { InboxOpenRequestRef as InboxRequestRef } from '@ziggs-ai/contracts';
+export interface InboxEnvelope extends InboxRequestChannel {
     asOf: string;
     /**
      * The mailboxes this reader's view merges — its owner's, plus whatever
@@ -487,7 +470,7 @@ export interface InboxEnvelope {
      */
     sources?: InboxSourceRef[];
     /**
-     * Unacked rows across every source, newest first, copies of one event
+     * Unacked rows across every source, oldest first, copies of one event
      * collapsed. This IS the inbox — read straight out of the party delivery
      * logs, not derived from grants. Rows with `assigneeId === me` are mine to
      * act on; the rest are readable context.
@@ -509,9 +492,6 @@ export interface InboxEnvelope {
     /** Open tasks assigned to this agent — the work channel. */
     tasksAwaitingMe: InboxTaskRef[];
     truncatedTasks: number;
-    /** Unacked request deliveries — triaged before any LLM wake. */
-    requestsAwaitingMe?: InboxRequestRef[];
-    truncatedRequests?: number;
     proposalsAwaitingMe: InboxProposalRef[];
     truncatedProposals: number;
     connectionRequestsAwaitingMe: InboxConnectionRequestRef[];

package/dist/types.js

@@ -95,22 +95,4 @@ export const BROADCAST_TARGETS = [OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET];
 export function isBroadcastTarget(id) {
     return id === OPEN_AGREEMENT_TARGET || id === ORG_AGREEMENT_TARGET;
 }
-/**
- * Persona face id (`psn_*`). Non-addressable — never use for agent lookup,
- * wake, or payment parties.
- */
-export function isPersonaRef(id) {
-    return typeof id === 'string' && id.startsWith('psn_');
-}
-/**
- * Room presentation binding id (`rpb_*`). Opaque to account lookup / wake /
- * pay. Chat sends may echo it as `receiverId` — the backend resolves it in-room
- *.
- */
-export function isRoomPresentationRef(id) {
-    return typeof id === 'string' && id.startsWith('rpb_');
-}
-/** Either opaque presentation ref (`psn_*` | `rpb_*`). */
-export function isOpaquePresentationRef(id) {
-    return isPersonaRef(id) || isRoomPresentationRef(id);
-}
+export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';

package/dist/utils/appUrls.d.ts

@@ -0,0 +1,7 @@
+/** Resolve the app origin once for SDK, MCP, and capability links. */
+export declare function resolveWebAppOrigin(webUrl?: string | null, backendUrl?: string): string;
+export declare function agreementAppUrl(origin: string, id: string): string;
+export declare function agreementsListAppUrl(origin: string): string;
+export declare function connectInviteAppUrl(origin: string, id: string): string;
+export declare function connectionsSettingsAppUrl(origin: string, requestId?: string | null): string;
+export declare function walletAppUrl(origin: string): string;

package/dist/utils/appUrls.js

@@ -0,0 +1,38 @@
+/** Resolve the app origin once for SDK, MCP, and capability links. */
+export function resolveWebAppOrigin(webUrl, backendUrl) {
+    const explicit = webUrl
+        ?.split(';')
+        .map((value) => value.trim())
+        .find(Boolean);
+    if (explicit)
+        return explicit.replace(/\/+$/, '');
+    if (backendUrl) {
+        const backend = new URL(backendUrl);
+        if (backend.hostname === 'localhost' || backend.hostname === '127.0.0.1')
+            return 'http://localhost:1234';
+        backend.hostname = backend.hostname.replace(/^api\./, '');
+        return backend.origin;
+    }
+    return 'https://ziggsai.com';
+}
+function appUrl(origin, path) {
+    return new URL(path, `${resolveWebAppOrigin(origin)}/`).toString();
+}
+export function agreementAppUrl(origin, id) {
+    return appUrl(origin, `/app/agreements/${encodeURIComponent(id)}`);
+}
+export function agreementsListAppUrl(origin) {
+    return appUrl(origin, '/app/agreements');
+}
+export function connectInviteAppUrl(origin, id) {
+    return appUrl(origin, `/connect/${encodeURIComponent(id)}`);
+}
+export function connectionsSettingsAppUrl(origin, requestId) {
+    const url = new URL(appUrl(origin, '/app/access'));
+    if (requestId)
+        url.searchParams.set('request', requestId);
+    return url.toString();
+}
+export function walletAppUrl(origin) {
+    return appUrl(origin, '/app/settings/organization/billing');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,8 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "socket.io-client": "^4.7.0"
+    "socket.io-client": "^4.7.0",
+    "@ziggs-ai/contracts": "^0.6.0"
   },
   "keywords": [
     "ziggs",