@ziggs-ai/api-client 0.14.3 → 0.16.0

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/AgreementClient.d.ts

@@ -34,7 +34,17 @@ export interface ProposeTerms {
 /** 1:1 proposal to a specific user or agent (`proposedTo` = their id). */
 export interface ProposeDirectInput extends ProposeTerms {
     proposedTo: string;
-    chatId: string;
+    /**
+     * The room the terms are discussed in, when there is one.
+     *
+     * Optional, matching the server, which has always accepted a proposal
+     * without one. Delivery does not depend on it: the create-time agreement
+     * event targets the party slots, so the counterparty is told either way; a
+     * room only gives them somewhere to talk about it. Required here was what
+     * forced a bookkeeping agreement between parties with no conversation to
+     * invent a chat id in order to exist.
+     */
+    chatId?: string;
 }
 /**
  * Open buyer-broadcast. `audience` selects who may see/claim it:
@@ -205,16 +215,29 @@ export interface CreateLinkBody {
     maxClaims?: number;
 }
 /**
- * The route's one answer, whatever was in `to`.
+ * The route's answer.
+ *
+ * `status` is constant — it went — and the two null-able fields are per-ARM,
+ * chosen by what the caller put in `to` and therefore known to it before the
+ * call. `shareUrl` is present exactly for an open invite.
+ *
+ * `agreementId` names the row for an agent id and for an open invite, and is
+ * null for an EMAIL. That split is what keeps the answer from becoming an
+ * existence oracle: the knock returns nothing for "no such person", "already
+ * linked", "already knocked" and "that is yourself" alike, so an id on some of
+ * those and not others would answer the one question the route refuses to
+ * answer. An agent id is different — the route resolves it through root
+ * authority and refuses a name that answers to nobody, so it already discloses
+ * that target's existence.
  *
- * Deliberately carries no agreement. Returning the row for an id target and a
- * bare "sent" for an address made one of the two an existence oracle over the
- * user table, so both say the same thing now: it went. `shareUrl` is null
- * exactly when `to` was named, which the caller already knows.
+ * Without it a caller could not reference what it had just created, check on it
+ * later, or tell a repeat from a first attempt.
  */
 export interface CreateLinkResult {
     ok: boolean;
     status: 'sent';
+    /** The link row, for a named agent id or an open invite. Null for an email. */
+    agreementId: string | null;
     shareUrl: string | null;
 }
 /**

package/dist/http/AgreementClient.js

@@ -444,9 +444,11 @@ export async function createLink(body, creds) {
         throw new Error('Invalid response: expected { ok, status: "sent", shareUrl } from POST /agreements/links');
     }
     const shareUrl = data['shareUrl'];
+    const agreementId = data['agreementId'];
     return {
         ok: data['ok'] === true,
         status: 'sent',
+        agreementId: typeof agreementId === 'string' ? agreementId : null,
         shareUrl: typeof shareUrl === 'string' ? shareUrl : null,
     };
 }

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

@@ -1,4 +1,4 @@
-import type { GrantView } from './grants.js';
+import type { GrantView } from "./grants.js";
 export declare function assertNoLeakedConnectionSecret(serialized: string): void;
 /** Thrown by ConnectionsClient with the HTTP status and raw body attached. */
 export interface ConnectionsError extends Error {
@@ -56,19 +56,30 @@ export declare class ConnectionsClient {
     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 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);
     /**
      * Present a ConnectionGrant to the broker and perform a provider action.
      * Returns the provider result — never the raw OAuth token. Requires an
      * impersonated agent (the grant holder).
      */
-    proxy({ connectionId, grantId, action, payload }: ConnectionProxyParams): Promise<unknown>;
+    proxy({ connectionId, grantId, action, payload, }: ConnectionProxyParams): Promise<unknown>;
     /**
      * List ConnectionGrants on a connection. When impersonating an agent the
      * server already scopes rows to that holder; the client-side filter is kept
      * as defense-in-depth (same behavior as the former ZiggsConnectClient).
      */
-    listGrants({ connectionId }: {
+    listGrants({ connectionId, }: {
         connectionId: string;
     }): Promise<ConnectionGrant[]>;
     /**

package/dist/http/ConnectionsClient.js

@@ -1,7 +1,7 @@
-import { getBackendUrl } from '../utils/urlUtils.js';
-import { throwApiError } from '../shared/apiError.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
-import { GrantsClient } from './GrantsClient.js';
+import { getBackendUrl } from "../utils/urlUtils.js";
+import { throwApiError } from "../shared/apiError.js";
+import { buildOperatorHeaders } from "./operatorHeaders.js";
+import { GrantsClient } from "./GrantsClient.js";
 // defense-in-depth mirror of the backend leak-guard
 // (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
 // vault token from the response; clients never see that token, so this layer
@@ -17,7 +17,7 @@ const LEAKED_SECRET_PATTERNS = [
 export function assertNoLeakedConnectionSecret(serialized) {
     for (const re of LEAKED_SECRET_PATTERNS) {
         if (re.test(serialized)) {
-            throw new Error('connection proxy response withheld: it appears to contain a credential (token-leak guard)');
+            throw new Error("connection proxy response withheld: it appears to contain a credential (token-leak guard)");
         }
     }
 }
@@ -34,29 +34,41 @@ export class ConnectionsClient {
     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 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) {
         if (!operatorKey)
-            throw new Error('ConnectionsClient: operatorKey is required');
+            throw new Error("ConnectionsClient: operatorKey is required");
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     /**
      * Present a ConnectionGrant to the broker and perform a provider action.
      * Returns the provider result — never the raw OAuth token. Requires an
      * impersonated agent (the grant holder).
      */
-    async proxy({ connectionId, grantId, action, payload }) {
+    async proxy({ connectionId, grantId, action, payload, }) {
         if (!connectionId)
-            throw new Error('proxy: connectionId is required');
+            throw new Error("proxy: connectionId is required");
         if (!grantId)
-            throw new Error('proxy: grantId is required');
+            throw new Error("proxy: grantId is required");
         if (!action)
-            throw new Error('proxy: action is required');
+            throw new Error("proxy: action is required");
         if (!this.agentId) {
-            throw new Error('proxy: agentId is required — connection broker calls must impersonate the grant holder agent');
+            throw new Error("proxy: agentId is required — connection broker calls must impersonate the grant holder agent");
         }
-        const text = await this._requestRaw('POST', `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
+        const text = await this._requestRaw("POST", `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
         assertNoLeakedConnectionSecret(text);
         let parsed = text;
         try {
@@ -65,7 +77,7 @@ export class ConnectionsClient {
         catch {
             parsed = text;
         }
-        const result = parsed?.['result'];
+        const result = parsed?.["result"];
         return result ?? parsed;
     }
     /**
@@ -73,15 +85,15 @@ export class ConnectionsClient {
      * server already scopes rows to that holder; the client-side filter is kept
      * as defense-in-depth (same behavior as the former ZiggsConnectClient).
      */
-    async listGrants({ connectionId }) {
+    async listGrants({ connectionId, }) {
         if (!connectionId)
-            throw new Error('listGrants: connectionId is required');
+            throw new Error("listGrants: connectionId is required");
         if (!this.agentId) {
-            throw new Error('listGrants: agentId is required — grants are scoped to the impersonated agent');
+            throw new Error("listGrants: agentId is required — grants are scoped to the impersonated agent");
         }
-        const res = (await this._request('GET', `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
-        const grants = res['grants'] || [];
-        return grants.filter((g) => g['holderId'] === this.agentId);
+        const res = (await this._request("GET", `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
+        const grants = res["grants"] || [];
+        return grants.filter((g) => g["holderId"] === this.agentId);
     }
     /**
      * cross-connection discovery over the unified GET /grants:
@@ -91,18 +103,18 @@ 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',
-            health: 'active',
+            scopeKind: "connection",
+            health: "active",
         });
         // An unreadable rail is not an empty one. Returning [] here made
         // every caller say "no connection grant" when the truth was "this key may not
         // look" — the needs gate refused work the agent could do, and the MCP tool
         // told the owner to issue a grant that already existed. Throwing puts the
         // missing scope in the message, where the person who can fix it will read it.
-        const railBlocked = unreadableRails.find((r) => r.rail === 'connection');
+        const railBlocked = unreadableRails.find((r) => r.rail === "connection");
         if (railBlocked && items.length === 0) {
             throw new Error(`Cannot read this agent's connection grants: the operator key is missing the ` +
                 `"${railBlocked.requiredScope}" scope, so the grant list came back empty whether or not ` +
@@ -125,10 +137,10 @@ export class ConnectionsClient {
     /** Issue a connection grant to an agent holder (connection owner side). */
     async issueGrant({ connectionId, holderId, caveats, }) {
         if (!connectionId)
-            throw new Error('issueGrant: connectionId is required');
+            throw new Error("issueGrant: connectionId is required");
         if (!holderId)
-            throw new Error('issueGrant: holderId is required');
-        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants`, {
+            throw new Error("issueGrant: holderId is required");
+        return this._request("POST", `/connections/${encodeURIComponent(connectionId)}/grants`, {
             holderId,
             caveats,
         });
@@ -141,20 +153,20 @@ export class ConnectionsClient {
      */
     async attenuateGrant({ connectionId, grantId, holderId, caveats, }) {
         if (!connectionId)
-            throw new Error('attenuateGrant: connectionId is required');
+            throw new Error("attenuateGrant: connectionId is required");
         if (!grantId)
-            throw new Error('attenuateGrant: grantId is required');
+            throw new Error("attenuateGrant: grantId is required");
         if (!holderId)
-            throw new Error('attenuateGrant: holderId is required');
-        return this._request('POST', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}/attenuate`, { holderId, caveats });
+            throw new Error("attenuateGrant: holderId is required");
+        return this._request("POST", `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}/attenuate`, { holderId, caveats });
     }
     /** Revoke a single connection grant. */
     async revokeGrant({ connectionId, grantId, }) {
         if (!connectionId)
-            throw new Error('revokeGrant: connectionId is required');
+            throw new Error("revokeGrant: connectionId is required");
         if (!grantId)
-            throw new Error('revokeGrant: grantId is required');
-        return this._request('DELETE', `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}`, undefined);
+            throw new Error("revokeGrant: grantId is required");
+        return this._request("DELETE", `/connections/${encodeURIComponent(connectionId)}/grants/${encodeURIComponent(grantId)}`, undefined);
     }
     /**
      * agent-initiated MCP connection request: ask the principal to
@@ -164,21 +176,23 @@ export class ConnectionsClient {
      */
     async requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }) {
         if (!serverUrl)
-            throw new Error('requestMcpConnection: serverUrl is required');
-        return (await this._request('POST', '/connections/mcp/requests', { serverUrl, tools, reason, chatId }, onBehalfOfUserId ? { 'X-On-Behalf-Of-User': onBehalfOfUserId } : undefined));
+            throw new Error("requestMcpConnection: serverUrl is required");
+        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, chatId }, onBehalfOfUserId
+            ? { "X-On-Behalf-Of-User": onBehalfOfUserId }
+            : undefined));
     }
     async _requestRaw(method, path, body, extraHeaders) {
         const init = {
             method,
             headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
-                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
                 ...extraHeaders,
-            }),
+            }, this.laneId),
         };
         if (body !== undefined)
             init.body = JSON.stringify(body);
         const response = await fetch(`${this.baseUrl}${path}`, init);
-        const text = await response.text().catch(() => '');
+        const text = await response.text().catch(() => "");
         if (!response.ok) {
             // ApiError (status/body/code); ConnectionsError remains the
             // documented duck type for callers that branch on `.status`.

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.d.ts

@@ -16,6 +16,13 @@ export interface PublishOfferPayload {
     /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
     audience?: BroadcastAudience;
     metadata?: Record<string, unknown>;
+    /**
+     * Replay handle, sent as the `Idempotency-Key` header — the same way
+     * `proposeAgreement` sends it. Re-publishing under the same key resolves to
+     * the listing already on the board; a NEW key republishes and retires the
+     * previous one. It used to ride in the body on this one route.
+     */
+    idempotencyKey?: string;
 }
 export declare function publishOffer(payload: PublishOfferPayload, creds: Creds): Promise<Agreement>;
 export interface PullOffersOptions {

package/dist/http/MarketplaceClient.js

@@ -21,17 +21,26 @@ function assertCreds(creds, op) {
 }
 export async function publishOffer(payload, creds) {
     assertCreds(creds, 'marketplace offer publish');
+    const { idempotencyKey, ...bodyData } = payload ?? {};
+    const headers = buildHeaders(creds);
+    if (idempotencyKey)
+        headers['Idempotency-Key'] = idempotencyKey;
     const res = await fetch(`${getMarketplaceBaseUrl()}/offers/publish`, {
         method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify(payload || {}),
+        headers,
+        body: JSON.stringify(bodyData),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
         throwApiError(res, body, `Marketplace offer publish failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
-    return shapeAgreement((data?.['offer'] ?? data));
+    // One key name across every agreement-creating route. This used to read
+    // `offer`, which was this route's own name for the same thing.
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { agreement } from POST /marketplace/offers/publish');
+    }
+    return shapeAgreement(data['agreement']);
 }
 export async function pullOffers(options, creds) {
     assertCreds(creds, 'marketplace offers pull');

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