@ziggs-ai/api-client 0.8.0 → 0.9.0

package/README.md

@@ -97,6 +97,16 @@ await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
 
 Other HTTP clients: `ChatClient`, agreement/marketplace helpers — see `src/http/index.ts`.
 
+### Persona wire shapes (ZIG-1137)
+
+Cross-org inbox and chat payloads mask counterparties behind presentation faces:
+
+- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org — not `requesterAgentId`.
+- Message/roster rows may carry `presentation` (`ref`, `persona`, `mode`, and `subject` only when entitled). Masked senders omit `underAgreementId` / `presentedAs`.
+- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may echo an `rpb_*` as `receiverId` — the backend resolves it in-room.
+
+Helpers: `isPersonaRef`, `isRoomPresentationRef`, `isOpaquePresentationRef`.
+
 #### Agent Search Client
 
 Search for agents:

package/dist/capabilities/artifacts.js

@@ -45,7 +45,7 @@ export const recordArtifactCapability = {
         chatId: { type: 'string', description: 'Optional chat scope' },
         agreementId: {
             type: 'string',
-            description: 'Optional agreement scope — for a hire deliverable, prefer this. When both chatId and agreementId are passed, agreementId wins.',
+            description: 'Optional agreement scope — for a hire deliverable, prefer this. Mutually exclusive with chatId: pass one, not both.',
         },
         taskId: {
             type: 'string',
@@ -63,12 +63,13 @@ export const recordArtifactCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const agreementId = args['agreementId'];
-        // Agreement wins when both scopes arrive. Models naturally pass the chat
-        // they are standing in alongside the agreement they deliver under; a hard
-        // xor here failed the deliverable at the last step of a finished task
-        // (ZIG-924 dogfood). The backend accepts at most one — we resolve the
-        // ambiguity at the exposed surface instead of erroring.
-        const chatId = agreementId ? undefined : args['chatId'];
+        // Both containers is refused, not resolved. This used to drop chatId and
+        // call agreement the winner — two answers to one call, and the silent one
+        // was worse: the artifact landed somewhere the caller had just been told it
+        // would also appear. The refusal itself lives in ArtifactsClient, the one
+        // gate every writer goes through, so this surface cannot drift from the
+        // others by wording its own verdict (ZIG-1075).
+        const chatId = args['chatId'];
         // ZIG-1037: no scope is legal. The throw that used to live here ("Pass
         // chatId or agreementId") is the exact failure this ticket removed — it cost
         // a live agent a turn mid-delivery for naming no container, when the record
@@ -80,7 +81,7 @@ export const recordArtifactCapability = {
         const contentType = args['content_type'];
         const taskId = args['taskId'];
         const creds = fullCreds(env);
-        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({
+        const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).writeStrict({
             text: args['text'],
             visibility,
             chatId,
@@ -128,7 +129,7 @@ export const listArtifactsCapability = {
     needsAgentId: true,
     handler: async (args, env) => {
         const creds = fullCreds(env);
-        return new ArtifactsClient(creds.operatorKey, creds.agentId).list({ authoredBy: 'me' }, {
+        return new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).list({ authoredBy: 'me' }, {
             after: args['after'],
             limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
         });
@@ -248,7 +249,7 @@ export const attachArtifactCapability = {
             throw new Error('role must be input or output');
         }
         const creds = fullCreds(env);
-        const client = new ArtifactsClient(creds.operatorKey, creds.agentId);
+        const client = new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId);
         if (chatId) {
             await client.attachToChat(artifactId, chatId);
             return {

package/dist/capabilities/context.js

@@ -1,15 +1,9 @@
-import { ContextReadClient } from '../http/ContextReadClient.js';
+import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient } from '../http/ContextDiscoveryClient.js';
 import { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, } from '../http/grants.js';
 import { fetchMyOrgs, resolveOrgSelector } from '../http/OrgsClient.js';
 import { fullCreds } from './types.js';
-const CONTEXT_READ_TYPES = [
-    'messages',
-    'artifacts',
-    'agreements',
-    'tasks',
-];
 // ZIG-1037: `artifact` joined the context rail. Delegating an artifact grant
 // onward works (same kind, same id — an exact re-grant); narrowing a container
 // grant DOWN to an artifact inside it is deliberately not supported yet.
@@ -49,12 +43,26 @@ export async function resolveOrgScopeId(env, scopeId) {
     const lister = env.surface === 'mcp' ? 'ziggs_org_list' : 'your org list';
     throw new Error(`No org named "${scopeId}" in your memberships — use ${lister} to see them, or pass the org id.`);
 }
+/**
+ * Which `via` each read type accepts, rendered for the tool text. Generated from
+ * CONTEXT_READ_VIA so the pairing an agent is told about and the pairing the
+ * call actually accepts are one statement — the prose that used to enumerate
+ * these by hand had already drifted from the server's list.
+ */
+const VIA_BY_TYPE = CONTEXT_READ_TYPES.map((t) => `${t} via ${viaHint(t)}`).join('; ');
+/**
+ * The one fact about `artifact:<id>` that both surfaces must state: it is how you
+ * reach an artifact no container can return. Shared for the same reason the
+ * pairings above are generated — hand-copied prose is what drifted.
+ */
+const ARTIFACT_VIA_NOTE = 'via=artifact:<id> is a point read of one named artifact and the ONLY way to ' +
+    'read one attached to no chat, agreement or task';
 export const contextReadCapability = {
     key: 'context_read',
     names: { sdk: 'context_read', mcp: 'ziggs_context_read' },
     descriptions: {
-        sdk: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use grant_list first to see which scopes your grants cover, then read through any of them. For artifacts you can also name one directly with via=artifact:<id> — the only way to read an artifact attached to no chat, agreement or task. Cursored; all access is grant-fenced server-side.',
-        mcp: 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id> — plus via=artifact:<id> for artifacts, a point read of one named artifact and the ONLY way to read one that is attached to no container (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.',
+        sdk: `Read the contents of a scope you already hold a grant for: ${CONTEXT_READ_TYPES.join(' | ')}. Each type reads through its own entries — ${VIA_BY_TYPE}. Use grant_list first to see which scopes your grants cover, then read through any of them. ${ARTIFACT_VIA_NOTE}. Cursored; all access is grant-fenced server-side.`,
+        mcp: `Read the contents of a scope you already hold: ${CONTEXT_READ_TYPES.join(' | ')} (the type param). Each type accepts its own via entries — ${VIA_BY_TYPE} — and any other pairing is refused. ${ARTIFACT_VIA_NOTE} (e.g. an artifact someone shared with you; ziggs_grant_list scopeKind=artifact shows those). Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a \`readPlan\` with the next page and/or forward-delta call pre-filled (after=this page's latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist, use the listers: ziggs_chat_list, ziggs_task_list, ziggs_agreement_list, ziggs_grant_list, ziggs_link_list.`,
     },
     annotation: 'read-only',
     params: {
@@ -67,7 +75,7 @@ export const contextReadCapability = {
         via: {
             type: 'string',
             required: true,
-            description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>. For type=artifacts also artifact:<id> to read that one artifact.',
+            description: `Scope entry you hold, as <kind>:<id>. Accepted per type — ${VIA_BY_TYPE}.`,
         },
         cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
         after: { type: 'string', description: 'ISO timestamp for forward-delta (messages/artifacts)' },
@@ -93,11 +101,21 @@ export const contextReadCapability = {
         const via = args['via'];
         if (!via)
             throw new Error('via is required');
+        // Same verdict the server gives, given at the call site so the reason
+        // arrives with the mistake. Never a softer one: a client that "fixes" an
+        // argument the server would reject is a second answer to one call.
+        const parsed = parseVia(via);
+        if (!parsed) {
+            throw new Error(`via must be <kind>:<id> — one of ${viaHint(type)} for type=${type}`);
+        }
+        if (!CONTEXT_READ_VIA[type].includes(parsed.kind)) {
+            throw new Error(`${type} reads accept via=${viaHint(type)} — not ${parsed.kind}:<id>`);
+        }
         const direction = args['direction'];
         if (direction !== undefined && direction !== 'forward') {
             throw new Error('direction must be "forward"');
         }
-        return new ContextReadClient(creds.operatorKey, creds.agentId).read(type, {
+        return new ContextReadClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).read(type, {
             via,
             cursor: args['cursor'],
             after: args['after'],

package/dist/capabilities/grants.d.ts

@@ -4,6 +4,13 @@ import { type CapabilityDefinition } from './types.js';
  * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
+ *
+ * ZIG-1088 — HOLD, not reach. `GET /grants` queries three row collections and
+ * nothing else; the implicit arms in AccessService (authorship, chat
+ * membership, agreement party, org membership) leave no row behind, so a reader
+ * can be entitled to something this list will never mention. The description
+ * says so, because the old "the single answer" wording was read as completeness
+ * and an empty list as "no access".
  */
 export declare const listGrantsCapability: CapabilityDefinition;
 export declare const GRANTS_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/grants.js

@@ -26,13 +26,20 @@ function parseScopeKinds(raw) {
  * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend (ZIG-956) so a short
  * list is never presented as complete when the key can't read a rail.
+ *
+ * ZIG-1088 — HOLD, not reach. `GET /grants` queries three row collections and
+ * nothing else; the implicit arms in AccessService (authorship, chat
+ * membership, agreement party, org membership) leave no row behind, so a reader
+ * can be entitled to something this list will never mention. The description
+ * says so, because the old "the single answer" wording was read as completeness
+ * and an empty list as "no access".
  */
 export const listGrantsCapability = {
     key: 'grant_list',
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     descriptions: {
-        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
-        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_context_read to pin a specific grant, or ziggs_context_expand_reach to enumerate a scope.',
+        sdk: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor. To answer "what can I reach?" instead, use context_expand_reach to enumerate a scope, or context_read to read through a grant.',
+        mcp: 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org/artifact), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Holder-scoped and cross-session. It answers "what grants do I HOLD?", which is narrower than "what can I reach?": reach you have by authoring something, by sitting in a chat, by being a party to an agreement, or through your org is not a grant row and never appears here — so an empty list means "no grants", never "no access". Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. To answer "what can I reach?" instead, use ziggs_context_expand_reach to enumerate a scope, or pass a grantId to ziggs_context_read to pin a specific grant.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/types.d.ts

@@ -43,6 +43,7 @@ export interface CapabilityEnv {
     creds: {
         operatorKey: string;
         agentId?: string;
+        laneId?: string;
     };
     /** SDK runner base-URL override (BACKEND_URL / ZIGGS_BACKEND_URL). */
     baseUrl?: string;

package/dist/capabilities/types.js

@@ -1,11 +1,13 @@
 /** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
 export function fullCreds(env) {
-    const { operatorKey, agentId } = env.creds;
+    const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
     if (!agentId)
         throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
+    // ZIG-1092 — the lane rides along so every Creds-based client sends
+    // X-Ziggs-Lane without each capability having to remember to.
+    return { operatorKey, agentId, ...(laneId ? { laneId } : {}) };
 }
 /**
  * Re-throw a client error with a capability-level prefix, preserving the HTTP

package/dist/http/AgreementClient.d.ts

@@ -1,6 +1,5 @@
 import 'dotenv/config';
 import { type Creds, type Agreement, type EngagementKind, type BroadcastAudience } from '../types.js';
-export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 /**
  * Shared proposal terms. When `engagementKind` is omitted the server defaults to `service`.
  * For an open buyer-broadcast quest, set `proposedTo` to a broadcast sentinel —
@@ -22,7 +21,6 @@ export interface ProposeTerms {
     billing?: 'total' | 'per_task';
     agreementDescription?: string;
     parentAgreementId?: string;
-    parentTaskId?: string;
     /**
      * Who does the work. Required on direct proposals (your own id = you offer;
      * the proposedTo id = you commission the recipient); forbidden on
@@ -30,9 +28,6 @@ export interface ProposeTerms {
      * side — there is no payer input.
      */
     providerId?: string;
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
     /** Defaults to `service` on the server when omitted. Set `hire` for representation contracts. */
     engagementKind?: EngagementKind;
     idempotencyKey?: string;
@@ -67,16 +62,12 @@ export interface DelegateAgreementData {
     executorId: string;
     chatId: string;
     parentAgreementId: string;
-    parentTaskId?: string;
     price?: number;
     lifecycle?: string;
     expiresAt?: string;
     maxExecutions?: number;
     agreementDescription?: string;
     payerId?: string;
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
     idempotencyKey?: string;
 }
 export declare function delegateAgreement(proposalData: DelegateAgreementData, creds: Creds): Promise<Agreement>;
@@ -91,7 +82,29 @@ export declare function delegateAgreement(proposalData: DelegateAgreementData, c
 export declare function respondToAgreement(agreementId: string, action: 'approve' | 'reject', creds: Creds, opts?: {
     ownerUserId?: string | null;
     agreement?: Agreement | null;
+    /** Where to send the human when the decision is theirs (ZIG-1087). */
+    appUrl?: string;
 }): Promise<Agreement>;
+/**
+ * The approval facts a "who decides this?" question is answered from: the party
+ * ids still owing a decision, plus the named responder slot.
+ *
+ * Split out (ZIG-1087) so the inbox card and the respond call answer that
+ * question with ONE rule. The card had no rule at all — it offered the respond
+ * tool for every pending proposal, including the ones only the human can
+ * answer, and the agent found out by 403.
+ */
+export interface PendingApprovalFacts {
+    /** Party ids with a pending entry on the approvals ledger. */
+    pendingPartyIds: readonly string[];
+    /** The direct responder slot, when the proposal names one. */
+    proposedTo?: string | null;
+}
+/**
+ * Which of `candidateIds` holds the pending approval slot, first match wins —
+ * so pass them in preference order (agent id before owner principal).
+ */
+export declare function resolvePendingApprovalPartyId(facts: PendingApprovalFacts, candidateIds: ReadonlyArray<string | null | undefined>): string | null;
 /**
  * ZIG-524 — resolve which approvals.partyId the current operator may submit.
  * Checks pending ledger entries against impersonated agent id and owner principal.
@@ -116,10 +129,6 @@ export interface CounterAgreementData {
     lifecycle?: string;
     maxExecutions?: number;
     description?: string;
-    /** Override plan `{ steps: [...] }`; omit to copy from original proposal task */
-    plan?: unknown;
-    planReviewTiming?: PlanReviewTiming;
-    requireMidWorkPlanAck?: boolean;
 }
 export declare function counterAgreement(agreementId: string, counter: CounterAgreementData, creds: Creds): Promise<Agreement>;
 export declare function getAgreementStatus(agreementId: string, creds: Creds): Promise<unknown | null>;
@@ -185,7 +194,15 @@ export declare function claimAgreement(agreementId: string, creds: Creds): Promi
     ok: boolean;
     agreement: Agreement;
 }>;
-export type ChatLinkType = 'origin' | 'mention' | 'delegation' | 'join';
+/**
+ * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
+ * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
+ * exactly one system-minted room, and letting a request name that type would
+ * burn the root's single slot on an unrelated chat. Shorter than the server
+ * union on purpose, which is why this list carries the reason with it.
+ */
+export declare const CHAT_LINK_TYPES: readonly ["origin", "mention", "delegation", "join"];
+export type ChatLinkType = (typeof CHAT_LINK_TYPES)[number];
 export declare function linkAgreementToChat(agreementId: string, chatId: string, linkType: ChatLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getChatsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare function joinAgreement(agreementId: string, creds: Creds): Promise<{
@@ -193,10 +210,12 @@ export declare function joinAgreement(agreementId: string, creds: Creds): Promis
     agentId: string | null;
     isNew: boolean;
 }>;
-export type ArtifactLinkType = 'produced' | 'referenced';
+export declare const ARTIFACT_LINK_TYPES: readonly ["produced", "referenced"];
+export type ArtifactLinkType = (typeof ARTIFACT_LINK_TYPES)[number];
 export declare function linkArtifactToAgreement(agreementId: string, artifactId: string, linkType: ArtifactLinkType | undefined, creds: Creds): Promise<unknown | null>;
 export declare function getArtifactsForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
-export type UserRole = 'payer' | 'provider' | 'participant' | 'observer';
+export declare const AGREEMENT_USER_ROLES: readonly ["payer", "provider", "participant", "observer"];
+export type UserRole = (typeof AGREEMENT_USER_ROLES)[number];
 export declare function linkUserToAgreement(agreementId: string, userId: string, role: UserRole, creds: Creds): Promise<unknown | null>;
 export declare function getUsersForAgreement(agreementId: string, creds: Creds): Promise<unknown[]>;
 export declare class AgreementClient {

package/dist/http/AgreementClient.js

@@ -14,6 +14,9 @@ function buildHeaders(creds) {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {
@@ -135,28 +138,54 @@ 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 — the slot resolved to the principal, not to us. Every call from
+    // this client impersonates `creds.agentId` (X-Agent-Id on every request), and
+    // `PUT /approvals/:partyId` takes a decision only from the party itself, so
+    // sending this would 403 with "You can only submit your own approval" —
+    // a condition, from which the caller cannot tell that no retry will ever
+    // work. Withholding consent from delegates is deliberate; being silent about
+    // it is not.
+    if (partyId && partyId !== creds.agentId) {
+        throw new Error(`Agreement ${agreementId} is waiting on ${partyId} — your principal, not you. ` +
+            `Consent is the human's to give: a delegate can submit its own approval slot and never its principal's, ` +
+            `so there is nothing to retry here and no tool that changes it. ` +
+            `Ask your human to approve or reject it${opts.appUrl ? ` at ${opts.appUrl}` : ' in the Ziggs app, under Agreements'}, ` +
+            `then read the agreement again to see the outcome.`);
+    }
     return approveAgreementAsParty(agreementId, partyId, action === 'approve' ? 'approved' : 'rejected', creds);
 }
 /**
- * ZIG-524 — resolve which approvals.partyId the current operator may submit.
- * Checks pending ledger entries against impersonated agent id and owner principal.
+ * Which of `candidateIds` holds the pending approval slot, first match wins —
+ * so pass them in preference order (agent id before owner principal).
  */
-export function resolveMyPendingApprovalPartyId(agreement, opts) {
-    const actorIds = [opts.agentId, opts.ownerUserId].filter((id) => typeof id === 'string' && id.length > 0);
-    const pending = (agreement.approvals ?? []).filter((a) => a.status === 'pending' || a.status === 'PENDING');
+export function resolvePendingApprovalPartyId(facts, candidateIds) {
+    const actorIds = candidateIds.filter((id) => typeof id === 'string' && id.length > 0);
     for (const id of actorIds) {
-        const hit = pending.find((a) => a.partyId === id);
-        if (hit)
-            return hit.partyId;
+        if (facts.pendingPartyIds.includes(id))
+            return id;
     }
-    const proposedTo = agreement.parties?.proposedTo;
+    // A row with no pending ledger entries is a legacy one (approvals[] predates
+    // ZIG-244), and there the named responder slot IS the decision.
+    const proposedTo = facts.proposedTo ?? null;
     if (proposedTo &&
         actorIds.includes(proposedTo) &&
-        (pending.length === 0 || pending.some((a) => a.partyId === proposedTo))) {
+        facts.pendingPartyIds.length === 0) {
         return proposedTo;
     }
     return null;
 }
+/**
+ * ZIG-524 — resolve which approvals.partyId the current operator may submit.
+ * Checks pending ledger entries against impersonated agent id and owner principal.
+ */
+export function resolveMyPendingApprovalPartyId(agreement, opts) {
+    return resolvePendingApprovalPartyId({
+        pendingPartyIds: (agreement.approvals ?? [])
+            .filter((a) => a.status === 'pending' || a.status === 'PENDING')
+            .map((a) => a.partyId),
+        proposedTo: agreement.parties?.proposedTo ?? null,
+    }, [opts.agentId, opts.ownerUserId]);
+}
 /**
  * Record this party's approval decision on an agreement
  * (`PUT /agreements/:agreementId/approvals/:partyId`).
@@ -406,6 +435,22 @@ export async function claimAgreement(agreementId, creds) {
     }
     return data;
 }
+// ---------------------------------------------------------------------------
+// Chat links
+// ---------------------------------------------------------------------------
+/**
+ * Link types a caller may ASK for — the server's `CALLER_LINK_TYPES`, not its
+ * full `LINK_TYPES`. `space` is deliberately absent: an agreement space gets
+ * exactly one system-minted room, and letting a request name that type would
+ * burn the root's single slot on an unrelated chat. Shorter than the server
+ * union on purpose, which is why this list carries the reason with it.
+ */
+export const CHAT_LINK_TYPES = [
+    'origin',
+    'mention',
+    'delegation',
+    'join',
+];
 export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
     if (!agreementId || !chatId)
         return null;
@@ -468,6 +513,10 @@ export async function joinAgreement(agreementId, creds) {
     }
     return data;
 }
+// ---------------------------------------------------------------------------
+// Artifact links
+// ---------------------------------------------------------------------------
+export const ARTIFACT_LINK_TYPES = ['produced', 'referenced'];
 export async function linkArtifactToAgreement(agreementId, artifactId, linkType = 'produced', creds) {
     if (!agreementId || !artifactId)
         return null;
@@ -512,6 +561,15 @@ export async function getArtifactsForAgreement(agreementId, creds) {
         return [];
     }
 }
+// ---------------------------------------------------------------------------
+// User links
+// ---------------------------------------------------------------------------
+export const AGREEMENT_USER_ROLES = [
+    'payer',
+    'provider',
+    'participant',
+    'observer',
+];
 export async function linkUserToAgreement(agreementId, userId, role, creds) {
     if (!agreementId || !userId || !role)
         return null;

package/dist/http/ArtifactsClient.d.ts

@@ -62,11 +62,15 @@ export declare function artifactScopeForSession(sessionId: string): {
 export declare class ArtifactsClient {
     private readonly operatorKey;
     private readonly agentId?;
+    private readonly laneId?;
     /**
      * @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 ZIG-1092 — 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.
      */
-    constructor(operatorKey: string, agentId?: string);
+    constructor(operatorKey: string, agentId?: string, laneId?: string);
     list(q: ListArtifactsQuery, opts?: ListArtifactsOptions): Promise<ListArtifactsResult>;
     /**
      * Record an agent thought as an `agent-private` artifact. Replaces the

package/dist/http/ArtifactsClient.js

@@ -28,15 +28,20 @@ export function artifactScopeForSession(sessionId) {
 export class ArtifactsClient {
     operatorKey;
     agentId;
+    laneId;
     /**
      * @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 ZIG-1092 — 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.
      */
-    constructor(operatorKey, agentId) {
+    constructor(operatorKey, agentId, laneId) {
         if (!operatorKey)
             throw new Error('ArtifactsClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
+        this.laneId = laneId;
     }
     async list(q, opts = {}) {
         const selectors = [q.chatId, q.agreementId, q.taskId, q.authoredBy].filter(Boolean);
@@ -178,12 +183,19 @@ export class ArtifactsClient {
      */
     _assertScopeXor(input) {
         if (input.chatId && input.agreementId) {
-            throw new Error('ArtifactsClient.write: pass at most one of chatId or agreementId');
+            // ZIG-1075: 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 (ZIG-924 dogfood).
+            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 ' +
+                'with agreementId, then attach it to the chat.');
         }
     }
     _headers() {
-        return buildOperatorHeaders(this.operatorKey, this.agentId, {
-            'content-type': 'application/json',
-        });
+        return buildOperatorHeaders(this.operatorKey, this.agentId, { 'content-type': 'application/json' }, this.laneId);
     }
 }

package/dist/http/ChatClient.js

@@ -7,6 +7,9 @@ function buildHeaders(creds) {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {

package/dist/http/ContextReadClient.d.ts

@@ -1,5 +1,28 @@
 import 'dotenv/config';
-export type ContextReadType = 'messages' | 'artifacts' | 'agreements' | 'tasks';
+export declare const CONTEXT_READ_TYPES: readonly ["messages", "artifacts", "agreements", "tasks"];
+export type ContextReadType = (typeof CONTEXT_READ_TYPES)[number];
+/**
+ * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
+ * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
+ * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ */
+export declare const VIA_KINDS: readonly ["chat", "agreement", "task", "counterparty", "artifact"];
+export type ViaKind = (typeof VIA_KINDS)[number];
+/**
+ * Which entry points each read type actually accepts, mirroring the server's
+ * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
+ * check, and this type all read off the same list instead of three prose
+ * copies that drift — and so a wrong pairing is refused with the reason rather
+ * than as a bare 400 from a round-trip away.
+ */
+export declare const CONTEXT_READ_VIA: Record<ContextReadType, readonly ViaKind[]>;
+/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+export declare function viaHint(type: ContextReadType): string;
+/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+export declare function parseVia(via: string): {
+    kind: ViaKind;
+    id: string;
+} | null;
 export interface ContextReadQuery {
     via: string;
     cursor?: string;
@@ -12,7 +35,7 @@ export interface ContextReadQuery {
 export interface ContextReadEnvelope<T = unknown> {
     type: ContextReadType;
     via: {
-        kind: string;
+        kind: ViaKind;
         id: string;
     };
     items: T[];
@@ -44,11 +67,15 @@ export declare class ContextReadClient {
     private readonly operatorKey;
     private readonly agentId?;
     private readonly baseUrl;
+    private readonly laneId?;
     /**
      * @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 ZIG-1092 — 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.
      */
-    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string, laneId?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
     /**
      * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The

package/dist/http/ContextReadClient.js

@@ -1,6 +1,54 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { pollSurfaceError } from '../shared/rateLimit.js';
+export const CONTEXT_READ_TYPES = [
+    'messages',
+    'artifacts',
+    'agreements',
+    'tasks',
+];
+/**
+ * Entry points a read can name as `via=<kind>:<id>` — the server's `parseVia`
+ * grammar. `counterparty` parses but reads nothing: it resolves a scope graph,
+ * not content, which is why {@link CONTEXT_READ_VIA} admits it for no type.
+ */
+export const VIA_KINDS = [
+    'chat',
+    'agreement',
+    'task',
+    'counterparty',
+    'artifact',
+];
+/**
+ * Which entry points each read type actually accepts, mirroring the server's
+ * `CONTEXT_READ_VIA`. Stated once here so the tool descriptions, the argument
+ * check, and this type all read off the same list instead of three prose
+ * copies that drift — and so a wrong pairing is refused with the reason rather
+ * than as a bare 400 from a round-trip away.
+ */
+export const CONTEXT_READ_VIA = {
+    messages: ['chat'],
+    artifacts: ['chat', 'agreement', 'task', 'artifact'],
+    agreements: ['chat', 'agreement'],
+    tasks: ['agreement', 'task'],
+};
+/** `chat:<id>, agreement:<id>` — the accepted entries for one read type, for humans. */
+export function viaHint(type) {
+    return CONTEXT_READ_VIA[type].map((k) => `${k}:<id>`).join(', ');
+}
+/** Split `chat:abc` into its parts, or null when it is not a `via` at all. */
+export function parseVia(via) {
+    const at = via.indexOf(':');
+    if (at <= 0)
+        return null;
+    const kind = via.slice(0, at);
+    const id = via.slice(at + 1);
+    if (!id)
+        return null;
+    return VIA_KINDS.includes(kind)
+        ? { kind: kind, id }
+        : null;
+}
 /**
  * Protocol-first uniform context reads (ZIG-427).
  * Wraps `GET /context/read/:type` — one client, one envelope, four types.
@@ -9,16 +57,21 @@ export class ContextReadClient {
     operatorKey;
     agentId;
     baseUrl;
+    laneId;
     /**
      * @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 ZIG-1092 — 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.
      */
-    constructor(operatorKey, agentId, baseUrl) {
+    constructor(operatorKey, agentId, baseUrl, laneId) {
         if (!operatorKey)
             throw new Error('ContextReadClient: operatorKey is required');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
+        this.laneId = laneId;
     }
     async read(type, query) {
         if (!query.via?.trim()) {
@@ -44,6 +97,8 @@ export class ContextReadClient {
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;
+        if (this.laneId)
+            headers['X-Ziggs-Lane'] = this.laneId;
         if (query.contextGrantId) {
             headers['X-Context-Grant-Id'] = query.contextGrantId;
         }
@@ -88,6 +143,8 @@ export class ContextReadClient {
         };
         if (this.agentId)
             headers['X-Agent-Id'] = this.agentId;
+        if (this.laneId)
+            headers['X-Ziggs-Lane'] = this.laneId;
         if (opts.contextGrantId) {
             headers['X-Context-Grant-Id'] = opts.contextGrantId;
         }

package/dist/http/InboxClient.d.ts

@@ -1,11 +1,21 @@
 import 'dotenv/config';
+/**
+ * What a delivery can be about. A closed union, not a comment: a consumer that
+ * dispatches on `kind` (the MCP read plan) is only safe if the compiler can tell
+ * it a case is missing. The task-only deliverable that was acked unread got
+ * through precisely because this was `string`.
+ *
+ * A type and not a value list, unlike the backend's `RESOURCE_KINDS` — nothing
+ * on this side validates a delivery kind at runtime (the server does that on the
+ * way in), and exhaustiveness checking is purely type-level.
+ */
+export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement';
 /**
  * One thing addressed to this agent. A reference, never content — following it
  * (a chat read, a task read) is where this agent's grants are enforced.
  */
 export interface InboxDeliveryRef {
-    /** 'message' | 'artifact' | 'task-state' | 'agreement'. */
-    kind: string;
+    kind: InboxDeliveryKind;
     resourceId: string;
     chatId: string | null;
     agreementId: string | null;
@@ -24,16 +34,35 @@ export interface InboxProposalRef {
     agreementId: string;
     title: string;
     proposedAt: string | null;
+    /**
+     * ZIG-1087 — party ids still owing a decision, and the named responder slot.
+     * The inbox lists proposals awaiting the agent OR its human, and only the
+     * agent's own slot is one it can submit; these say which is which.
+     *
+     * Optional because a backend deployed before ZIG-1087 omits them, and this
+     * client is installed independently of the server it talks to. Absent reads
+     * as "no slot of mine", which routes the decision to the human — the safe
+     * direction: it withholds a call, it never invents authority.
+     */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
 }
 export interface InboxConnectionRequestRef {
     requestId: string;
-    requesterAgentId: string;
+    /**
+     * Non-addressable persona reference for the requester (`psn_*`).
+     * Never use as an account id for lookup / wake / pay (ZIG-1137).
+     */
+    requesterRef: string;
     /** ZIG-1039 — human-readable name for consent cards. */
     requesterDisplayName?: string | null;
     /** ZIG-1039 — org label for consent cards. */
     requesterOrgName?: string | null;
     message: string | null;
     requestedAt: string | null;
+    /** ZIG-1087 — see InboxProposalRef; a link request uses the same gate. */
+    pendingApprovalPartyIds?: string[];
+    proposedTo?: string | null;
 }
 /** Pull-only MCP: prompt the human when proposals need a decision (ZIG-482 / ZIG-481). */
 export interface InboxHumanAttention {

package/dist/http/MarketplaceClient.d.ts

@@ -31,7 +31,6 @@ export interface PublishQuestPayload {
     description: string;
     chatId?: string;
     payerId?: string;
-    parentTaskId?: string;
     price?: number;
     lifecycle?: string;
     expiresAt?: string;

package/dist/http/MarketplaceClient.js

@@ -7,6 +7,9 @@ function buildHeaders(creds) {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {

package/dist/http/TaskClient.d.ts

@@ -1,10 +1,18 @@
 import 'dotenv/config';
 import { type Creds, type Task, type TaskState } from '../types.js';
+/**
+ * When the buyer reviews a task's plan. Task-rail only — an agreement has no
+ * plan to review, which is why ZIG-1095 cut this from the propose/counter/
+ * subcontract inputs rather than teaching those routes to keep one.
+ */
+export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 export interface CreateTaskData {
     description: string;
     agreementId: string;
     parentTaskId?: string;
     plan?: unknown;
+    planReviewTiming?: PlanReviewTiming;
+    requireMidWorkPlanAck?: boolean;
     idempotencyKey?: string;
     /** Explicit delegation target (ZIG-586) — must be a party to the agreement; validated server-side. */
     assigneeId?: string;

package/dist/http/TaskClient.js

@@ -7,6 +7,9 @@ function buildHeaders(creds) {
         'content-type': 'application/json',
         Authorization: `Bearer ${creds.operatorKey}`,
         'X-Agent-Id': creds.agentId,
+        // ZIG-1092 — the wake's lane, so the backend can fence this call to the
+        // engagement it belongs to rather than the agent's whole authority.
+        ...(creds.laneId ? { 'X-Ziggs-Lane': creds.laneId } : {}),
     };
 }
 function assertCreds(creds, op) {

package/dist/http/index.d.ts

@@ -7,8 +7,8 @@ export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
 export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
-export { ContextReadClient } from './ContextReadClient.js';
-export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';
+export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
@@ -26,4 +26,4 @@ export type { MyOrg, OrgResolution } from './OrgsClient.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
-export type { InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';
+export type { InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxOperatorAgentEntry, InboxOperatorEnvelope, } from './InboxClient.js';

package/dist/http/index.js

@@ -7,7 +7,7 @@ export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient, 
 // ZIG-1032: agreement lanes are not chats — callers scope artifact writes with this.
 artifactScopeForSession, AGREEMENT_LANE_PREFIX, } from './ArtifactsClient.js';
-export { ContextReadClient } from './ContextReadClient.js';
+export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -3,4 +3,10 @@
  * an agentId is present — agent-scoped keys identify the agent themselves;
  * fleet keys must pass one (ZIG-642).
  */
-export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>): Record<string, string>;
+export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 
+/**
+ * ZIG-1092 — the lane this call belongs to, sent as `X-Ziggs-Lane`. The
+ * backend narrows the wake's reach to the engagement's orgs; omitting it
+ * narrows to the agent's own org, so it can never widen reach.
+ */
+laneId?: string): Record<string, string>;

package/dist/http/operatorHeaders.js

@@ -3,10 +3,17 @@
  * an agentId is present — agent-scoped keys identify the agent themselves;
  * fleet keys must pass one (ZIG-642).
  */
-export function buildOperatorHeaders(operatorKey, agentId, extra) {
+export function buildOperatorHeaders(operatorKey, agentId, extra, 
+/**
+ * ZIG-1092 — the lane this call belongs to, sent as `X-Ziggs-Lane`. The
+ * backend narrows the wake's reach to the engagement's orgs; omitting it
+ * narrows to the agent's own org, so it can never widen reach.
+ */
+laneId) {
     return {
         Authorization: `Bearer ${operatorKey}`,
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),
+        ...(laneId ? { 'X-Ziggs-Lane': laneId } : {}),
         ...extra,
     };
 }

package/dist/index.d.ts

@@ -3,7 +3,8 @@ export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
 export type { StartAgentOptions } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
+export type { PrincipalPresentation } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export * from './http/index.js';
 export * from './capabilities/index.js';
 export * from './relay/provisionRelayWorkers.js';
 export { ConnectionManager } from './ConnectionManager.js';
-export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, AGREEMENT_ENGAGEMENT_KIND, isValidContentType } from './types.js';
+export { EntryTypes, ContentTypes, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, BROADCAST_TARGETS, isBroadcastTarget, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, AGREEMENT_ENGAGEMENT_KIND, isValidContentType, } from './types.js';
 export { getBackendUrl, getWebSocketUrl } from './utils/urlUtils.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 // ZIG-1019: retry loops need the server's own wait, not a guess.

package/dist/types.d.ts

@@ -6,6 +6,21 @@ export declare class ApiError extends Error {
 export interface Creds {
     operatorKey: string;
     agentId: string;
+    /**
+     * ZIG-1092 — the lane (chat id, or `agrn-<agreementId>`) this call is being
+     * made from. Sent as `X-Ziggs-Lane` so the backend can fence the wake to the
+     * engagement the agent is actually acting inside.
+     *
+     * The operator key says WHO is calling; this says ON WHOSE BEHALF, RIGHT NOW.
+     * Without it an agent serving several customers carries its full authority
+     * into every call, and one tool call reaches another customer's work.
+     *
+     * Optional, and omitting it can only narrow what comes back (the backend
+     * falls back to the agent's own org) — never widen it. Nothing here is
+     * trusted: the server re-derives the party orgs itself and refuses a lane the
+     * agent is not in.
+     */
+    laneId?: string;
 }
 export type TaskState = 'active' | 'proposal' | 'completed' | 'failed' | 'cancelled' | 'ledger_open';
 export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
@@ -159,6 +174,36 @@ 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 (ZIG-1137).
+ */
+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
+ * (ZIG-1137).
+ */
+export declare function isRoomPresentationRef(id: string | null | undefined): boolean;
+/** Either opaque presentation ref (`psn_*` | `rpb_*`). */
+export declare function isOpaquePresentationRef(id: string | null | undefined): boolean;
+/** Display + entitlement face for a principal on the message/roster wire. */
+export interface PrincipalPresentation {
+    /** Public, non-addressable reference (`psn_*` or `rpb_*`). */
+    ref?: string;
+    persona: {
+        id: string;
+        name: string;
+        image?: string | null;
+        revision?: number;
+    };
+    mode: 'persona' | 'chain';
+    /** Present only when the viewer is entitled to resolve the subject. */
+    subject?: {
+        id: string;
+        type: 'user' | 'agent';
+    };
+}
 export interface MessageMetadata {
     chatId: string;
     /** Stable id for dedup across push + inbox catch-up (ZIG-454). */
@@ -167,13 +212,23 @@ export interface MessageMetadata {
     sender: {
         id: string;
         type?: string;
+        presentation?: PrincipalPresentation | null;
+        /** Absent when the viewer is masked (persona layer). */
+        underAgreementId?: string | null;
+        presentedAs?: string | null;
     };
     senderId: string;
     senderType?: string;
     receiver?: {
         id: string;
+        presentation?: PrincipalPresentation | null;
     } | null;
     receiverId?: string | null;
+    /**
+     * Message-level presentation stamp when the backend attaches one
+     * (same shape as sender.presentation). Prefer sender.presentation.
+     */
+    presentation?: PrincipalPresentation | null;
     entryType?: string;
     content_type?: string;
     taskId?: string | null;

package/dist/types.js

@@ -58,3 +58,22 @@ 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 (ZIG-1137).
+ */
+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
+ * (ZIG-1137).
+ */
+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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",