@ziggs-ai/api-client 0.10.3 → 0.11.0

package/dist/capabilities/proposeProviderId.d.ts

@@ -3,4 +3,4 @@
  * tools. Stated on the schema so a fresh agent does not burn a turn learning
  * the rule from the validation error.
  */
-export declare const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = "REQUIRED on a direct proposal: name who does the work \u2014 your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a quest (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.";
+export declare const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = "REQUIRED on a direct proposal: name who does the work \u2014 your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a request (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.";

package/dist/capabilities/proposeProviderId.js

@@ -3,4 +3,4 @@
  * tools. Stated on the schema so a fresh agent does not burn a turn learning
  * the rule from the validation error.
  */
-export const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = 'REQUIRED on a direct proposal: name who does the work — your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a quest (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.';
+export const AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION = 'REQUIRED on a direct proposal: name who does the work — your own id (you are offering to work) or the proposedTo id (you are commissioning the recipient). Do not omit it when proposedTo is a person/agent id. Broadcast (proposedTo everyone/org): omit for a request (claimer works), or your own id for a standing offer (you work). A third-party id brokers and needs a matching published offer. Payer is always the non-providing side.';

package/dist/http/AgreementClient.d.ts

@@ -1,7 +1,7 @@
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
- * For an open buyer-broadcast quest, set `proposedTo` to a broadcast sentinel —
+ * For an open buyer-broadcast request, set `proposedTo` to a broadcast sentinel —
  * `OPEN_AGREEMENT_TARGET` (`"everyone"`, fully public) or `ORG_AGREEMENT_TARGET`
  * (`"org"`, scoped to your org). Prefer `proposeBroadcast({ audience })` over
  * setting `proposedTo` by hand.
@@ -49,8 +49,9 @@ export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'> & {
  * A trust link's agreement, as every caller sees it.
  *
  * A link is reach, not commerce: it carries no money, no escrow, no execution
- * state and no approvals ledger. Handing the raw document over anyway put Mongo
- * bookkeeping in front of an LLM, which is what forbade.
+ * state and no approvals ledger. Handing the raw document over anyway puts
+ * storage bookkeeping in front of an LLM, which is what this summary exists to
+ * prevent.
  *
  * Lives here rather than in `capabilities/links.ts` because this is where the
  * rule is applied; that module re-exports it so the public name is
@@ -78,7 +79,7 @@ export declare function proposeAgreement(proposalData: ProposeDirectInput, creds
 /** Propose a contract to one party (user or agent). Server defaults `engagementKind` to `service`. */
 export declare function proposeDirectTo(input: ProposeDirectInput, creds: Creds): Promise<Agreement>;
 /**
- * Propose an open quest. `audience` ('everyone' default | 'org') picks the
+ * Propose an open request. `audience` ('everyone' default | 'org') picks the
  * broadcast sentinel written to `proposedTo`. Server defaults `engagementKind`
  * to `service`.
  */
@@ -145,7 +146,7 @@ export declare function resolveMyPendingApprovalPartyId(agreement: Agreement, op
  *
  * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
  * principal when approving as human, delegate agent id when impersonating.
- * Canonical for hire, service, link, and quest proposals.
+ * Canonical for hire, service, link, and request proposals.
  */
 export declare function approveAgreementAsParty(agreementId: string, partyId: string, status: 'approved' | 'rejected', creds: Creds): Promise<Agreement>;
 export interface CounterAgreementData {
@@ -180,21 +181,26 @@ export interface GetMyAgreementsFilters {
 export declare function getMyAgreements(filters: GetMyAgreementsFilters | undefined, creds: Creds): Promise<Agreement[]>;
 /** One agreement, shaped: a link comes back as its summary. */
 export declare function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null>;
-export interface CreateAgreementBody {
-    proposedToId?: string;
-    providerId?: string;
-    agentId?: string;
-    price?: number;
-    lifecycle?: string;
-    expiresAt?: string;
-    maxExecutions?: number;
+export interface CreateLinkBody {
+    /** Target agent for a direct link. Omit for an open, claimable invite. */
+    targetAgentId?: string;
+    /** Message shown to whoever is asked to approve or claim it. */
     description?: string;
-    engagementKind?: EngagementKind;
-    /** Link invites only: how many people may claim this one link. Default 1. */
+    /** Open invites only: how many people may claim this one link. Default 1. */
     maxClaims?: number;
-    metadata?: Record<string, unknown>;
+    /** Which of the caller's own agents stands on their side of the link. */
+    asAgentId?: string;
 }
-export declare function createAgreement(body: CreateAgreementBody, creds: Creds): Promise<{
+/**
+ * Create a trust link — a direct proposal to one agent, or an open invite.
+ *
+ * This posts to `POST /agreements/links`. It used to post to `POST /agreements`,
+ * which also created work agreements inline and skipped the gates the proposal
+ * and marketplace paths run. Work agreements go through `proposeAgreement`
+ * (`POST /agreements/proposals`) and the marketplace claim routes; this rail
+ * carries links and nothing else.
+ */
+export declare function createLink(body: CreateLinkBody, creds: Creds): Promise<{
     ok: boolean;
     agreement: Agreement;
 }>;
@@ -208,13 +214,13 @@ export declare function fulfillAgreement(agreementId: string, creds: Creds): Pro
     ok: boolean;
     agreement: Agreement;
 }>;
-/** What an open-broadcast claim turned out to be. ⚠️ SYNC: backend AgreementOpenService. */
-export type ClaimedKind = 'link' | 'offer' | 'quest' | 'hand-off';
+/** What an open-broadcast claim resolved to. ⚠️ Mirrors the server; it is authoritative. */
+export type ClaimedKind = 'link' | 'offer' | 'request' | 'hand-off';
 /**
  * Claim an open agreement. Three shapes are claimable:
  * - open link invite (`engagementKind: link`, proposedTo everyone)
- * - open broadcast quest (proposedTo 'everyone', status open)
- * - org-scoped broadcast quest (proposedTo 'org') — the server rejects the
+ * - open broadcast request (proposedTo 'everyone', status open)
+ * - org-scoped broadcast request (proposedTo 'org') — the server rejects the
  *   claim with 403 if the caller is not a member of the agreement's orgId
  *
  * POST /agreements/:id/claim — canonical; no partyId in body.
@@ -261,7 +267,7 @@ export declare class AgreementClient {
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
     listMine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(id: string): Promise<Agreement | null>;
-    create(data: CreateAgreementBody): Promise<{
+    createLink(data: CreateLinkBody): Promise<{
         ok: boolean;
         agreement: Agreement;
     }>;

package/dist/http/AgreementClient.js

@@ -28,8 +28,9 @@ function assertCreds(creds, op) {
  * A trust link's agreement, as every caller sees it.
  *
  * A link is reach, not commerce: it carries no money, no escrow, no execution
- * state and no approvals ledger. Handing the raw document over anyway put Mongo
- * bookkeeping in front of an LLM, which is what forbade.
+ * state and no approvals ledger. Handing the raw document over anyway puts
+ * storage bookkeeping in front of an LLM, which is what this summary exists to
+ * prevent.
  *
  * Lives here rather than in `capabilities/links.ts` because this is where the
  * rule is applied; that module re-exports it so the public name is
@@ -102,7 +103,7 @@ export async function proposeDirectTo(input, creds) {
     return proposeAgreement(input, creds);
 }
 /**
- * Propose an open quest. `audience` ('everyone' default | 'org') picks the
+ * Propose an open request. `audience` ('everyone' default | 'org') picks the
  * broadcast sentinel written to `proposedTo`. Server defaults `engagementKind`
  * to `service`.
  */
@@ -171,7 +172,7 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     const proposedTo = agreement.parties?.proposedTo;
     if (isBroadcastTarget(proposedTo) || isBroadcastTarget(agreement.parties?.payer)) {
         // respond is approve/reject on DIRECT proposals only. An open
-        // broadcast (quest, standing offer, link invite) has no per-recipient
+        // broadcast (request, standing offer, link invite) has no per-recipient
         // approval slot — a BYSTANDER can neither approve nor reject it
         //; their move is to claim it, which has its own verb.
         //
@@ -188,7 +189,7 @@ export async function respondToAgreement(agreementId, action, creds, opts = {})
     else if (!partyId) {
         throw new Error(`No pending approval entry for this operator on agreement ${agreementId}`);
     }
-    // ZIG-1087 / ZIG-1316 — if the slot is the principal's, the server accepts
+    // If the slot is the principal's, the server accepts
     // only under a live approval-authority grant (else 403). Do not pre-refuse
     // here; the PUT is the source of truth.
     return approveAgreementAsParty(agreementId, partyId, action === 'approve' ? 'approved' : 'rejected', creds);
@@ -231,7 +232,7 @@ export function resolveMyPendingApprovalPartyId(agreement, opts) {
  *
  * `partyId` MUST match the authenticated actor (`actor.id === partyId`): owner
  * principal when approving as human, delegate agent id when impersonating.
- * Canonical for hire, service, link, and quest proposals.
+ * Canonical for hire, service, link, and request proposals.
  */
 export async function approveAgreementAsParty(agreementId, partyId, status, creds) {
     if (!agreementId)
@@ -405,23 +406,31 @@ export async function getAgreement(agreementId, creds) {
     const agreement = await getAgreementDocument(agreementId, creds);
     return agreement ? shapeAgreement(agreement) : null;
 }
-export async function createAgreement(body, creds) {
+/**
+ * Create a trust link — a direct proposal to one agent, or an open invite.
+ *
+ * This posts to `POST /agreements/links`. It used to post to `POST /agreements`,
+ * which also created work agreements inline and skipped the gates the proposal
+ * and marketplace paths run. Work agreements go through `proposeAgreement`
+ * (`POST /agreements/proposals`) and the marketplace claim routes; this rail
+ * carries links and nothing else.
+ */
+export async function createLink(body, creds) {
     if (!body)
-        throw new Error('Body is required for agreement creation');
-    assertCreds(creds, 'agreement creation');
-    // Canonical REST create: POST /agreements.
-    const res = await fetch(getAgreementBaseUrl(), {
+        throw new Error('Body is required for link creation');
+    assertCreds(creds, 'link creation');
+    const res = await fetch(`${getAgreementBaseUrl()}/links`, {
         method: 'POST',
         headers: buildHeaders(creds),
         body: JSON.stringify(body),
     });
     if (!res.ok) {
         const responseBody = await res.text().catch(() => '');
-        throwApiError(res, responseBody, `Agreement creation failed: ${res.status} ${res.statusText}`);
+        throwApiError(res, responseBody, `Link creation failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement']) {
-        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements');
+        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/links');
     }
     const envelope = data;
     return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
@@ -471,8 +480,8 @@ export async function fulfillAgreement(agreementId, creds) {
 /**
  * Claim an open agreement. Three shapes are claimable:
  * - open link invite (`engagementKind: link`, proposedTo everyone)
- * - open broadcast quest (proposedTo 'everyone', status open)
- * - org-scoped broadcast quest (proposedTo 'org') — the server rejects the
+ * - open broadcast request (proposedTo 'everyone', status open)
+ * - org-scoped broadcast request (proposedTo 'org') — the server rejects the
  *   claim with 403 if the caller is not a member of the agreement's orgId
  *
  * POST /agreements/:id/claim — canonical; no partyId in body.
@@ -492,7 +501,7 @@ export async function claimAgreement(agreementId, creds) {
     }
     // the route reports which kind of broadcast this turned out to be.
     // A caller cannot work it out from the row — post-claim no sentinel is left,
-    // and a quest (you do the work) reads the same shape as a standing offer (you
+    // and a request (you do the work) reads the same shape as a standing offer (you
     // pay for it) unless you know which slot you landed in.
     const envelope = data;
     return { ...envelope, agreement: shapeAgreement(envelope.agreement) };
@@ -682,7 +691,7 @@ export class AgreementClient {
     list(filters) { return listAgreements(filters, this.creds); }
     listMine(filters) { return getMyAgreements(filters, this.creds); }
     get(id) { return getAgreement(id, this.creds); }
-    create(data) { return createAgreement(data, this.creds); }
+    createLink(data) { return createLink(data, this.creds); }
     revoke(id) { return revokeAgreement(id, this.creds); }
     fulfill(id) { return fulfillAgreement(id, this.creds); }
     claimAgreement(id) { return claimAgreement(id, this.creds); }

package/dist/http/ArtifactsClient.d.ts

@@ -1,10 +1,10 @@
 /**
  * Inline `POST /artifacts` body cap (matches backend
  * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
- * server does not auto-split (ZIG-1320).
+ * server does not auto-split.
  */
 export declare const ARTIFACT_INLINE_TEXT_MAX_CHARS = 50000;
-/** ZIG-1320 — named escape hatch for agents that hit the inline cap. */
+/** Named escape hatch for agents that hit the inline cap. */
 export declare const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT: string;
 export type ArtifactVisibility = 'chat' | 'agent-private';
 export interface ListArtifactsOptions {
@@ -112,7 +112,7 @@ export declare class ArtifactsClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      * @param laneId the wake's lane (chat id, or `agrn-<agreementId>`),
      *   sent as X-Ziggs-Lane so `authoredBy=me` is fenced to this engagement
-     *   instead of returning every customer's deliverables in one call.
+     *   rather than spanning every engagement the agent has authored in.
      */
     constructor(operatorKey: string, agentId?: string, laneId?: string);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;

package/dist/http/ArtifactsClient.js

@@ -5,10 +5,10 @@ import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
  * Inline `POST /artifacts` body cap (matches backend
  * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
- * server does not auto-split (ZIG-1320).
+ * server does not auto-split.
  */
 export const ARTIFACT_INLINE_TEXT_MAX_CHARS = 50_000;
-/** ZIG-1320 — named escape hatch for agents that hit the inline cap. */
+/** Named escape hatch for agents that hit the inline cap. */
 export const ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT = `text exceeds ${ARTIFACT_INLINE_TEXT_MAX_CHARS} characters. ` +
     'For larger content use ziggs_artifact_upload_url (file rail), or split into ' +
     'an index artifact plus part artifacts and list the part ids in the index. ' +
@@ -55,7 +55,7 @@ export class ArtifactsClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      * @param laneId the wake's lane (chat id, or `agrn-<agreementId>`),
      *   sent as X-Ziggs-Lane so `authoredBy=me` is fenced to this engagement
-     *   instead of returning every customer's deliverables in one call.
+     *   rather than spanning every engagement the agent has authored in.
      */
     constructor(operatorKey, agentId, laneId) {
         if (!operatorKey)
@@ -134,7 +134,7 @@ export class ArtifactsClient {
         }
         this._assertScopeXor(input);
         const text = input.text.trim();
-        // ZIG-1320: refuse before the wire so MCP/SDK get a named escape hatch
+        // Refuse before the wire so MCP/SDK get a named escape hatch
         // instead of a bare class-validator string.
         if (text.length > ARTIFACT_INLINE_TEXT_MAX_CHARS) {
             throw new Error(`ArtifactsClient.writeStrict: ${ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT}`);
@@ -309,10 +309,8 @@ export class ArtifactsClient {
         if (input.chatId && input.agreementId) {
             // the refusal names the recovery, because this is the one gate
             // for every caller — the exposed tool surfaces inherit it rather than each
-            // wording their own, and a caller that used to have chatId silently
-            // dropped here now learns what to do instead. Wording matters: a bare
-            // "pick one" at the last step of a finished task is what the drop was
-            // added to avoid (dogfood).
+            // wording their own. Wording matters: this fires at the last step of a
+            // finished task, where a bare "pick one" leaves the deliverable unfiled.
             throw new Error('pass at most one of chatId or agreementId — a deliverable under an ' +
                 'agreement wants agreementId alone (its parties see it); use chatId ' +
                 'only for a chat-scoped note. To put it in both places, record it ' +

package/dist/http/ChatClient.d.ts

@@ -21,6 +21,7 @@ export interface SendChatMessageInput {
      * Recipient id. Optional: when omitted, the backend infers the
      * receiver if the chat has exactly one other member (one agent, or one
      * other human). Provide it explicitly in chats with multiple members.
+     * Sent on the wire as `{ id }`; the SDK still takes a string.
      */
     receiverId?: string;
     text: string;

package/dist/http/ChatClient.js

@@ -93,7 +93,10 @@ export async function sendChatMessage(input, creds) {
             text: input.text,
             entryType,
             contentType,
-            receiver: input.receiverId,
+            // Canonical wire shape is `{ id, type? }`; bare strings are still
+            // accepted by the backend after edge normalize, but first-party
+            // clients send the object.
+            receiver: input.receiverId ? { id: input.receiverId } : undefined,
             underAgreementId: input.underAgreementId,
         }),
     });

package/dist/http/ConnectionsClient.js

@@ -93,10 +93,21 @@ export class ConnectionsClient {
     async listForHolder() {
         const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
         // All pages of the agent's live connection grants (not just the first page).
-        const items = await grantsClient.listAllGrants({
+        const { items, unreadableRails } = await grantsClient.listAllGrantsWithRails({
             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');
+        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 ` +
+                'a grant exists. Re-mint the key with that scope (the "launcher-mcp-broker" preset includes it).');
+        }
         const byConnection = new Map();
         for (const g of items) {
             const connectionId = g.scope.id;

package/dist/http/ContextGrantsClient.d.ts

@@ -1,4 +1,4 @@
-import type { GrantView } from './grants.js';
+import type { GrantAccessKind, GrantHolderKind, GrantView } from './grants.js';
 /**
  * added `artifact` — the narrowest context scope: one specific artifact,
  * shared without sharing any chat or agreement it sits in. Still the context
@@ -21,12 +21,26 @@ export interface ContextGrantScope {
 export type ContextGrantRecord = GrantView;
 export interface IssueContextGrantInput {
     holderId: string;
+    /**
+     * What kind of principal the holder is: a person, an organization, or an
+     * agent. Always stated, because an id says nothing about what it names — and
+     * an organization holder is how one grant covers a whole team.
+     */
+    holderKind: GrantHolderKind;
+    /**
+     * What the holder may do: `read` to see the scope, `write` to take part in
+     * it, `admit` to bring others in as well. Defaults to `write`.
+     */
+    kind?: GrantAccessKind;
     scope: ContextGrantScope;
     temporal?: ContextTemporal;
     expiresAt?: string | null;
 }
 export interface DelegateContextGrantInput {
     holderId: string;
+    holderKind: GrantHolderKind;
+    /** Never stronger than the grant it comes from; defaults to the same. */
+    kind?: GrantAccessKind;
     scope: ContextGrantScope;
     temporal: ContextTemporal;
     expiresAt?: string | null;

package/dist/http/ContextGrantsClient.js

@@ -28,6 +28,8 @@ export class ContextGrantsClient {
             }),
             body: JSON.stringify({
                 holderId: input.holderId,
+                holderKind: input.holderKind,
+                kind: input.kind,
                 scope: input.scope,
                 temporal: input.temporal,
                 expiresAt: input.expiresAt,

package/dist/http/ContextReadClient.d.ts

@@ -43,17 +43,26 @@ export interface ContextReadEnvelope<T = unknown> {
     latestSequence?: string | null;
 }
 /** Aggregated chat snapshot from `GET /context/snapshot` (follow-up). */
+/**
+ * One participant on the snapshot roster. `kind` is the declared holder kind the
+ * server stamped on the row, so a reader takes what a participant IS from the
+ * row rather than from which array it arrived in. Optional so a backend that
+ * predates it still parses.
+ */
+export interface ContextSnapshotParticipant {
+    role: string;
+    kind?: string;
+    isYou?: boolean;
+    [key: string]: unknown;
+}
 export interface ContextSnapshotResult {
     history: unknown[];
     agreements: unknown[];
-    agents: Array<{
+    agents: Array<ContextSnapshotParticipant & {
         agentId: string;
-        role: string;
-        isYou: boolean;
     }>;
-    users: Array<{
+    users: Array<ContextSnapshotParticipant & {
         userId: string;
-        role: string;
     }>;
     latestSequence?: string | null;
     chatMissing?: boolean;
@@ -70,9 +79,10 @@ export declare class ContextReadClient {
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
-     * @param laneId the wake's lane, sent as X-Ziggs-Lane. This is the
-     *   path the dogfood leak ran through: `via=artifact:<other customer's spec>`
-     *   was authorised purely because the same agent had authored it.
+     * @param laneId the wake's lane, sent as X-Ziggs-Lane. The server fences a
+     *   read to the lane's parties; without it, reach falls back to a wider
+     *   test and a read can be authorised on a weaker basis than the caller
+     *   intended. Send it on every read made while acting on a wake.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;

package/dist/http/ContextReadClient.js

@@ -60,9 +60,10 @@ export class ContextReadClient {
     /**
      * @param operatorKey Agent-scoped or fleet operator key.
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
-     * @param laneId the wake's lane, sent as X-Ziggs-Lane. This is the
-     *   path the dogfood leak ran through: `via=artifact:<other customer's spec>`
-     *   was authorised purely because the same agent had authored it.
+     * @param laneId the wake's lane, sent as X-Ziggs-Lane. The server fences a
+     *   read to the lane's parties; without it, reach falls back to a wider
+     *   test and a read can be authorised on a weaker basis than the caller
+     *   intended. Send it on every read made while acting on a wake.
      */
     constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)

package/dist/http/GrantsClient.d.ts

@@ -66,4 +66,18 @@ export declare class GrantsClient {
      * truncated. `maxPages` bounds the loop as a runaway guard.
      */
     listAllGrants(query?: Omit<ListGrantsQuery, 'cursor'>, maxPages?: number): Promise<GrantView[]>;
+    /**
+     * The same sweep, keeping the part `listAllGrants` throws away: which rails the
+     * caller was not allowed to read.
+     *
+     * The distinction is not cosmetic. An empty page from an unreadable rail looks
+     * exactly like "you hold no grants", and a caller that cannot tell them apart
+     * reports the wrong one: a brokered connector agent with a live grant refused
+     * its task and told the buyer to ask for the grant they had just issued, because
+     * its key lacked `connections:read` and this method answered "none".
+     */
+    listAllGrantsWithRails(query?: Omit<ListGrantsQuery, 'cursor'>, maxPages?: number): Promise<{
+        items: GrantView[];
+        unreadableRails: UnreadableRail[];
+    }>;
 }

package/dist/http/GrantsClient.js

@@ -65,15 +65,31 @@ export class GrantsClient {
      * truncated. `maxPages` bounds the loop as a runaway guard.
      */
     async listAllGrants(query = {}, maxPages = 50) {
+        return (await this.listAllGrantsWithRails(query, maxPages)).items;
+    }
+    /**
+     * The same sweep, keeping the part `listAllGrants` throws away: which rails the
+     * caller was not allowed to read.
+     *
+     * The distinction is not cosmetic. An empty page from an unreadable rail looks
+     * exactly like "you hold no grants", and a caller that cannot tell them apart
+     * reports the wrong one: a brokered connector agent with a live grant refused
+     * its task and told the buyer to ask for the grant they had just issued, because
+     * its key lacked `connections:read` and this method answered "none".
+     */
+    async listAllGrantsWithRails(query = {}, maxPages = 50) {
         const all = [];
+        const rails = new Map();
         let cursor;
         for (let page = 0; page < maxPages; page++) {
             const res = await this.listGrants({ ...query, cursor });
             all.push(...res.items);
+            for (const rail of res.unreadableRails ?? [])
+                rails.set(rail.rail, rail);
             if (!res.nextCursor)
-                return all;
+                break;
             cursor = res.nextCursor;
         }
-        return all;
+        return { items: all, unreadableRails: [...rails.values()] };
     }
 }

package/dist/http/InboxClient.d.ts

@@ -18,7 +18,7 @@ export declare class InboxClient {
     getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
-     * `resourceId` handled in `(priorAck, upTo]` (ZIG-1305). Monotonic
+     * `resourceId` handled in `(priorAck, upTo]`. Monotonic
      * server-side: an older value is a no-op, so a replayed ack can never
      * redeliver handled work. An ack that would bury unlisted deliveries is
      * refused.

package/dist/http/InboxClient.js

@@ -48,7 +48,7 @@ export class InboxClient {
     }
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
-     * `resourceId` handled in `(priorAck, upTo]` (ZIG-1305). Monotonic
+     * `resourceId` handled in `(priorAck, upTo]`. Monotonic
      * server-side: an older value is a no-op, so a replayed ack can never
      * redeliver handled work. An ack that would bury unlisted deliveries is
      * refused.

package/dist/http/MarketplaceClient.d.ts

@@ -24,7 +24,7 @@ export interface PullOffersOptions {
 }
 export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare function claimOffer(agreementId: string, creds: Creds): Promise<Agreement>;
-export interface PublishQuestPayload {
+export interface PublishRequestPayload {
     /** See PublishOfferPayload.billing. */
     billing?: 'total' | 'per_task';
     description: string;
@@ -38,12 +38,12 @@ export interface PublishQuestPayload {
     /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
     audience?: BroadcastAudience;
 }
-export declare function publishQuest(payload: PublishQuestPayload, creds: Creds): Promise<Agreement>;
-export interface PullQuestsOptions {
+export declare function publishRequest(payload: PublishRequestPayload, creds: Creds): Promise<Agreement>;
+export interface PullRequestsOptions {
     limit?: number;
     since?: string;
 }
-export declare function pullQuests(options: PullQuestsOptions | undefined, creds: Creds): Promise<Agreement[]>;
+export declare function pullRequests(options: PullRequestsOptions | undefined, creds: Creds): Promise<Agreement[]>;
 export declare class MarketplaceClient {
     private creds;
     /**
@@ -54,6 +54,6 @@ export declare class MarketplaceClient {
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
     claimOffer(agreementId: string): Promise<Agreement>;
-    publishQuest(payload: PublishQuestPayload): Promise<Agreement>;
-    pullQuests(options?: PullQuestsOptions): Promise<Agreement[]>;
+    publishRequest(payload: PublishRequestPayload): Promise<Agreement>;
+    pullRequests(options?: PullRequestsOptions): Promise<Agreement[]>;
 }

package/dist/http/MarketplaceClient.js

@@ -70,37 +70,37 @@ export async function claimOffer(agreementId, creds) {
         throw new Error(data?.['error'] || 'Claim failed');
     return shapeAgreement(data['offer']);
 }
-export async function publishQuest(payload, creds) {
-    assertCreds(creds, 'quest publish');
-    const res = await fetch(`${getMarketplaceBaseUrl()}/quests/publish`, {
+export async function publishRequest(payload, creds) {
+    assertCreds(creds, 'request publish');
+    const res = await fetch(`${getMarketplaceBaseUrl()}/requests/publish`, {
         method: 'POST',
         headers: buildHeaders(creds),
         body: JSON.stringify(payload || {}),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
-        throwApiError(res, body, `Quest publish failed: ${res.status}`);
+        throwApiError(res, body, `Request publish failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
     if (!data?.['agreement'])
-        throw new Error('Quest publish returned no agreement');
+        throw new Error('Request publish returned no agreement');
     return shapeAgreement(data['agreement']);
 }
-export async function pullQuests(options, creds) {
-    assertCreds(creds, 'quest pull');
+export async function pullRequests(options, creds) {
+    assertCreds(creds, 'request pull');
     const params = new URLSearchParams();
     if (options?.limit != null)
         params.set('limit', String(options.limit));
     if (options?.since)
         params.set('since', options.since);
     const qs = params.toString();
-    const res = await fetch(`${getMarketplaceBaseUrl()}/quests${qs ? `?${qs}` : ''}`, {
+    const res = await fetch(`${getMarketplaceBaseUrl()}/requests${qs ? `?${qs}` : ''}`, {
         method: 'GET',
         headers: buildHeaders(creds),
     });
     if (!res.ok) {
         const body = await res.text().catch(() => '');
-        throwApiError(res, body, `Quest pull failed: ${res.status}`);
+        throwApiError(res, body, `Request pull failed: ${res.status}`);
     }
     const data = await res.json().catch(() => null);
     return data?.['agreements'] ?? [];
@@ -121,6 +121,6 @@ export class MarketplaceClient {
     publishOffer(payload) { return publishOffer(payload, this.creds); }
     pullOffers(options) { return pullOffers(options, this.creds); }
     claimOffer(agreementId) { return claimOffer(agreementId, this.creds); }
-    publishQuest(payload) { return publishQuest(payload, this.creds); }
-    pullQuests(options) { return pullQuests(options, this.creds); }
+    publishRequest(payload) { return publishRequest(payload, this.creds); }
+    pullRequests(options) { return pullRequests(options, this.creds); }
 }