@ziggs-ai/api-client 0.10.4 → 0.12.0

package/dist/http/TaskClient.js

@@ -1,4 +1,5 @@
 import { getBackendUrl } from '../utils/urlUtils.js';
+import { partyActorIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
 function getTaskBaseUrl() { return `${getBackendUrl()}/tasks`; }
 function buildHeaders(creds) {
@@ -159,13 +160,7 @@ async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
     const { listAgreements } = await import('./AgreementClient.js');
     const agreements = await listAgreements({ status: 'active' }, creds);
     const partyIds = agreements
-        .filter((a) => {
-        const p = a.parties ?? {};
-        return (p.provider === agentId ||
-            p.providerAgent === agentId ||
-            p.creator === agentId ||
-            p.payer === agentId);
-    })
+        .filter((a) => partyActorIds(a.parties).includes(agentId))
         .map((a) => a.agreementId)
         .filter(Boolean);
     if (partyIds.length === 0)
@@ -345,6 +340,8 @@ export async function listTasks(options = {}, creds) {
         url.searchParams.set('limit', String(options.limit));
     if (options.assignedTo)
         url.searchParams.set('assignedTo', options.assignedTo);
+    if (options.createdBy)
+        url.searchParams.set('createdBy', options.createdBy);
     const res = await fetch(url.toString(), {
         method: 'GET',
         headers: buildHeaders(creds),

package/dist/http/agreementFlows.d.ts

@@ -1,14 +1,13 @@
-import { type ClaimedKind, type ProposeTerms } from './AgreementClient.js';
+import { type ClaimedKind, type ClaimOptions, type ProposeTerms } from './AgreementClient.js';
 import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 /**
- * one propose grammar. Direct, broadcast (quest and standing
+ * one propose grammar. Direct, broadcast (request and standing
  * offer), and link proposals all flow through here; the surfaces expose a
  * single propose tool instead of dedicated publish/request tools.
  *
  * Routing:
- * - engagementKind 'link'                    → POST /agreements (link proposal / open invite)
  * - proposedTo 'everyone' | 'org', providerId = self  → seller-broadcast standing offer
- * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast quest
+ * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast request
  * - anything else                            → direct proposal
  */
 export interface UnifiedProposeInput extends ProposeTerms {
@@ -17,13 +16,13 @@ export interface UnifiedProposeInput extends ProposeTerms {
     chatId?: string;
     engagementKind?: EngagementKind;
 }
-export type ProposeShape = 'direct' | 'quest' | 'offer' | 'link';
+export type ProposeShape = 'direct' | 'request' | 'offer';
 export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds): Promise<{
     agreement: Agreement;
     shape: ProposeShape;
 }>;
 /**
- * one claim verb for any open broadcast: link invite, quest,
+ * one claim verb for any open broadcast: link invite, request,
  * hand-off, or standing offer.
  *
  * One request. This used to read the agreement first to decide which endpoint to
@@ -36,7 +35,7 @@ export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds)
  * `kind` arrives on the claim response — the route that did the routing reports
  * which broadcast kind this turned out to be.
  */
-export declare function claimOpenAgreement(agreementId: string, creds: Creds): Promise<{
+export declare function claimOpenAgreement(agreementId: string, creds: Creds, opts?: ClaimOptions): Promise<{
     agreement: Agreement;
     kind: ClaimedKind;
 }>;

package/dist/http/agreementFlows.js

@@ -1,21 +1,15 @@
-import { createAgreement, claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
 import { publishOffer } from './MarketplaceClient.js';
 import { isBroadcastTarget, } from '../types.js';
 export async function proposeUnified(input, creds) {
     const { proposedTo, chatId, engagementKind, providerId, ...terms } = input;
     if (!proposedTo)
         throw new Error('proposedTo is required (a user/agent id, or "everyone"/"org" to broadcast)');
-    if (engagementKind === 'link') {
-        // A link is an agreement, proposed to one agent (providerId) or opened as
-        // an invite (proposedTo 'everyone'); no chat, no money.
-        const target = isBroadcastTarget(proposedTo) ? undefined : proposedTo;
-        const { agreement } = await createAgreement({
-            engagementKind: 'link',
-            ...(target ? { providerId: target } : {}),
-            ...(terms.description ? { description: terms.description } : {}),
-        }, creds);
-        return { agreement, shape: 'link' };
-    }
+    // The 'link' arm is gone. A link is not a proposal shape: it has no
+    // price, no chat and no work, and it is formed by `link_propose`, which takes
+    // an email or an agent id and answers the same either way. Keeping a second
+    // door here would have meant a caller reaching a link through the propose
+    // grammar, where the constant answer and the org-root refusal do not apply.
     if (isBroadcastTarget(proposedTo)) {
         const audience = proposedTo;
         if (providerId && creds.agentId && providerId === creds.agentId) {
@@ -33,16 +27,16 @@ export async function proposeUnified(input, creds) {
             return { agreement, shape: 'offer' };
         }
         if (providerId) {
-            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a quest: the claimer works, you pay). A third-party providerId is not broadcastable.');
+            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a request: the claimer works, you pay). A third-party providerId is not broadcastable.');
         }
-        // Buyer-broadcast: the claimer works, your side pays — an open quest.
+        // Buyer-broadcast: the claimer works, your side pays — an open request.
         const agreement = await proposeBroadcast({
             ...terms,
             chatId: chatId ?? '',
             engagementKind: engagementKind ?? 'service',
             audience,
         }, creds);
-        return { agreement, shape: 'quest' };
+        return { agreement, shape: 'request' };
     }
     if (!chatId)
         throw new Error('chatId is required on a direct proposal');
@@ -56,7 +50,7 @@ export async function proposeUnified(input, creds) {
     return { agreement, shape: 'direct' };
 }
 /**
- * one claim verb for any open broadcast: link invite, quest,
+ * one claim verb for any open broadcast: link invite, request,
  * hand-off, or standing offer.
  *
  * One request. This used to read the agreement first to decide which endpoint to
@@ -69,11 +63,11 @@ export async function proposeUnified(input, creds) {
  * `kind` arrives on the claim response — the route that did the routing reports
  * which broadcast kind this turned out to be.
  */
-export async function claimOpenAgreement(agreementId, creds) {
+export async function claimOpenAgreement(agreementId, creds, opts = {}) {
     if (!agreementId)
         throw new Error('agreementId is required');
-    const { agreement, kind } = await claimAgreement(agreementId, creds);
+    const { agreement, kind } = await claimAgreement(agreementId, creds, opts);
     // A server that has not shipped the `kind` field yet still claims correctly;
-    // 'quest' is the shape the route has always handled.
-    return { agreement, kind: kind ?? 'quest' };
+    // 'request' is the shape the route has always handled.
+    return { agreement, kind: kind ?? 'request' };
 }

package/dist/http/grants.d.ts

@@ -11,6 +11,23 @@
  * watermark are presented as `temporal` / `watermark_at` caveats.
  */
 export type GrantHealth = 'active' | 'expired' | 'revoked';
+/**
+ * Who holds a grant. Declared at issuance and carried on the row — nothing
+ * about an id says what it names. An `org` holder is how one grant covers every
+ * member of that organization.
+ */
+export type GrantHolderKind = 'user' | 'org' | 'agent';
+/**
+ * What a grant lets its holder do. `write` implies `read`, `admit` implies
+ * both: `read` sees the scope, `write` takes part in it, `admit` brings others
+ * in as well.
+ */
+export type GrantAccessKind = 'read' | 'write' | 'admit';
+/**
+ * The kind of principal-authored consent object a grant rests on. Every grant
+ * is minted by one of these, or delegated from a parent grant that was.
+ */
+export type GrantBasisKind = 'creation' | 'publication' | 'membership' | 'acceptance' | 'agreement';
 /**
  * The context rail's scope kinds, as VALUES — the type below is derived from
  * them, so widening the rail is one edit rather than a type change plus however
@@ -51,6 +68,17 @@ export interface GrantView {
     /** ISO-8601. */
     createdAt: string;
     health: GrantHealth;
+    /**
+     * What the holder is, what the grant lets them do, and which consent object
+     * authorized it. Present on rails that record them (context grants do);
+     * absent means the rail does not say, not that there is nothing.
+     */
+    holderKind?: GrantHolderKind;
+    access?: GrantAccessKind;
+    basis?: {
+        kind: GrantBasisKind;
+        id: string | null;
+    };
 }
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export declare function grantCaveat(grant: GrantView, type: string): unknown | undefined;

package/dist/http/index.d.ts

@@ -8,7 +8,7 @@ export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.j
 export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.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 type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
@@ -16,7 +16,7 @@ export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './Grants
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
-export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
+export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, GrantHolderKind, GrantAccessKind, GrantBasisKind, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';

package/dist/index.d.ts

@@ -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, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, 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, partySideIds, partyActorIds, } from './types.js';
 export type { PrincipalPresentation } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';
 export { configureApiClient, apiClientConfig } from './config.js';
@@ -11,5 +11,5 @@ export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxQuestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
-export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
+export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';

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, isPersonaRef, isRoomPresentationRef, isOpaquePresentationRef, 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, partySideIds, partyActorIds, } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';
 // the host injects the environment; this package never reads it.
 export { configureApiClient, apiClientConfig } from './config.js';

package/dist/instanceIdentity.d.ts

@@ -0,0 +1,4 @@
+export declare const INBOX_HOST_CLAIMANT_HEADER = "X-Ziggs-Instance";
+export declare function instanceIdentity(): string;
+/** Test seam: forget the memoized value so a case can set different env. */
+export declare function resetInstanceIdentityForTests(): void;

package/dist/instanceIdentity.js

@@ -0,0 +1,44 @@
+import { hostname } from 'node:os';
+/**
+ * Which process is calling GET /inbox.
+ *
+ * The exclusive-read claimant must be the *host* (this fleet task, a
+ * laptop fleet, an MCP process), not the API process. Two fleets share
+ * one backend task, so stamping the API's identity would let both wake.
+ *
+ * `ecs:<id>` on Fargate, `local:<host>:<pid>` otherwise. Env-derived
+ * and memoized.
+ */
+let cached = null;
+const MAX_LENGTH = 64;
+export const INBOX_HOST_CLAIMANT_HEADER = 'X-Ziggs-Instance';
+export function instanceIdentity() {
+    if (cached)
+        return cached;
+    cached = resolve().slice(0, MAX_LENGTH);
+    return cached;
+}
+/** Test seam: forget the memoized value so a case can set different env. */
+export function resetInstanceIdentityForTests() {
+    cached = null;
+}
+function resolve() {
+    const metadataUri = process.env.ECS_CONTAINER_METADATA_URI_V4 ??
+        process.env.ECS_CONTAINER_METADATA_URI;
+    if (metadataUri) {
+        const id = metadataUri.split('/').filter(Boolean).pop() ?? '';
+        const short = id.replace(/[^A-Za-z0-9]/g, '').slice(0, 12);
+        if (short.length >= 8)
+            return `ecs:${short}`;
+    }
+    const host = process.env.HOSTNAME || safeHostname();
+    return `local:${host}:${process.pid}`;
+}
+function safeHostname() {
+    try {
+        return hostname() || 'unknown-host';
+    }
+    catch {
+        return 'unknown-host';
+    }
+}

package/dist/relay/provisionRelayWorkers.d.ts

@@ -1,5 +1,5 @@
 import type { Agreement, Creds } from '../types.js';
-import { claimOffer, delegateAgreement, getMyAgreements, pullOffers } from '../http/index.js';
+import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers } from '../http/index.js';
 /** Minimal relay step shape — keep field names aligned with agents/coordinators/relayTypes.ts */
 export interface RelayStepInput {
     stepId: string;
@@ -28,7 +28,7 @@ export type ProvisionedRelayStep = RelayPayloadShape['steps'][number] & {
 export interface RelayProvisionDeps {
     getMyAgreements: typeof getMyAgreements;
     pullOffers: typeof pullOffers;
-    claimOffer: typeof claimOffer;
+    claimOpenAgreement: typeof claimOpenAgreement;
     delegateAgreement: typeof delegateAgreement;
 }
 export interface ProvisionRelayWorkersInput {

package/dist/relay/provisionRelayWorkers.js

@@ -1,6 +1,6 @@
-import { claimOffer, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
+import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
 function providerAgentId(agreement) {
-    return agreement.parties?.providerAgent ?? agreement.parties?.provider ?? null;
+    return agreement.parties?.provider?.actor ?? null;
 }
 function isActiveAgreement(agreement) {
     return agreement.status === 'active';
@@ -30,7 +30,7 @@ export function findOpenOfferForAgent(assigneeId, offers) {
 export async function provisionRelayWorkers(input, deps = {
     getMyAgreements,
     pullOffers,
-    claimOffer,
+    claimOpenAgreement,
     delegateAgreement,
 }) {
     const { creds, hireAgreementId, chatId, steps, inputArtifactIds } = input;
@@ -55,7 +55,7 @@ export async function provisionRelayWorkers(input, deps = {
             continue;
         }
         if (step.offerAgreementId) {
-            const claimed = await deps.claimOffer(step.offerAgreementId, creds);
+            const { agreement: claimed } = await deps.claimOpenAgreement(step.offerAgreementId, creds);
             const agreementId = claimed.agreementId;
             const status = isActiveAgreement(claimed)
                 ? 'active'
@@ -78,7 +78,7 @@ export async function provisionRelayWorkers(input, deps = {
         }
         const openOffer = findOpenOfferForAgent(step.assigneeId, offersCache);
         if (openOffer?.agreementId) {
-            const claimed = await deps.claimOffer(openOffer.agreementId, creds);
+            const { agreement: claimed } = await deps.claimOpenAgreement(openOffer.agreementId, creds);
             const agreementId = claimed.agreementId;
             const status = isActiveAgreement(claimed)
                 ? 'active'

package/dist/types.d.ts

@@ -91,19 +91,46 @@ export declare const AGREEMENT_ENGAGEMENT_KIND: {
     readonly LINK: "link";
 };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
+/**
+ * One side of an agreement.
+ *
+ * An agent id occupies `actor` and nowhere else, so "is this agent on this
+ * side?" is a structural read rather than a lookup against the Agent
+ * collection. Asking `principal` about an agent id is always the wrong
+ * question — it would match that agent's estate instead.
+ */
+export interface AgreementPartySide {
+    /**
+     * The accountable person or org — never an agent. On `payer` and `proposedTo`
+     * this may instead hold a broadcast sentinel ({@link isBroadcastTarget}), in
+     * which case nobody has taken the side up yet.
+     */
+    principal?: string | null;
+    /** The agent that performed on this side. Null when the principal acted itself. */
+    actor?: string | null;
+}
+/** The four sides of an agreement, each {@link AgreementPartySide}. */
+export interface AgreementParties {
+    payer?: AgreementPartySide;
+    provider?: AgreementPartySide;
+    proposedTo?: AgreementPartySide;
+    creator?: AgreementPartySide;
+}
+/** Both ids on one side, principal first, absent ones dropped. */
+export declare function partySideIds(side: AgreementPartySide | null | undefined): string[];
+/**
+ * Every agent that acted on this agreement, deduped.
+ *
+ * The read for "is this agent a party?" — an agent id lives in `actor` alone,
+ * so widening the match to `principal` would hit an unrelated estate.
+ */
+export declare function partyActorIds(parties: AgreementParties | null | undefined): string[];
 /** Compact agreement reference carried by task reads. */
 export interface AgreementSummary {
     agreementId: string;
     description: string;
     status: AgreementStatus;
-    parties?: {
-        proposedTo?: string | null;
-        provider?: string | null;
-        payer?: string | null;
-        creator?: string | null;
-        creatorAgent?: string | null;
-        providerAgent?: string | null;
-    };
+    parties?: AgreementParties;
     /** The opposite party relative to the requesting agent; null for observers,
      * broadcast sentinels, and self-agreements. */
     counterparty: string | null;
@@ -120,14 +147,7 @@ export interface Agreement {
     status?: AgreementStatus;
     engagementKind?: EngagementKind;
     proposalStatus?: ProposalStatus;
-    parties?: {
-        proposedTo?: string;
-        provider?: string;
-        payer?: string;
-        creator?: string;
-        creatorAgent?: string;
-        providerAgent?: string;
-    };
+    parties?: AgreementParties;
     approvals?: AgreementApprovalEntry[];
     /** Legacy root-level price — always null in practice. Use money.price instead. */
     price?: number | null;
@@ -287,14 +307,34 @@ export type MessageHandler = (text: string, metadata: MessageMetadata) => Promis
  * 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' | 'quest';
+export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'request';
+/** The two mailbox owners. Agents own no mailbox — they read through grants. */
+export type InboxPartyKind = 'human' | 'org';
+/** One mailbox this reader's merged view includes. */
+export interface InboxSourceRef {
+    partyId: string;
+    partyKind: InboxPartyKind;
+}
 /**
- * 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.
+ * One row in this reader's merged view. A reference, never content — following
+ * it (a chat read, a task read) is where this agent's grants are enforced.
+ *
+ * "Mine to act on" is `assigneeId === my agent id`, nothing else. A row
+ * without my stamp is context I may read, never a wake and never mine to ack
+ * as handled.
  */
 export interface InboxDeliveryRef {
     kind: InboxDeliveryKind;
     resourceId: string;
+    /** One emit, one id — copies of the same event collapse on this. */
+    eventId: string;
+    /** The mailbox this copy lives in. */
+    partyId: string;
+    partyKind: InboxPartyKind;
+    /** The ONE agent stamped to act; null when nothing has to. */
+    assigneeId: string | null;
+    /** The owner's human should see this. */
+    needsHuman: boolean;
     chatId: string | null;
     agreementId: string | null;
     taskId: string | null;
@@ -377,10 +417,10 @@ export interface InboxTaskRef {
     updatedAt: string | null;
 }
 /**
- * A marketplace quest doorbell. Own channel so the host can
+ * A marketplace request doorbell. Own channel so the host can
  * exact-match triage with zero LLM tokens before any wake.
  */
-export interface InboxQuestRef {
+export interface InboxRequestRef {
     agreementId: string;
     /** Exact-match string from the publisher — compare to the agent's tags. */
     match: string;
@@ -390,27 +430,36 @@ export interface InboxQuestRef {
 export interface InboxEnvelope {
     asOf: string;
     /**
-     * Unacked deliveries addressed to this agent, newest first. This IS the
-     * inbox — read straight out of the delivery log, not derived from grants.
+     * The mailboxes this reader's view merges — its owner's, plus whatever
+     * inbox grants add. Absent on older servers.
+     */
+    sources?: InboxSourceRef[];
+    /**
+     * Unacked rows across every source, newest first, copies of one event
+     * collapsed. This IS the inbox — read straight out of the party delivery
+     * logs, not derived from grants. Rows with `assigneeId === me` are mine to
+     * act on; the rest are readable context.
      */
     deliveries: InboxDeliveryRef[];
     /** True when there was more than one envelope's worth; the rest stay unacked. */
     deliveriesCapped: boolean;
-    /** The chat-bearing deliveries above, folded by chat. */
+    /** This agent's ASSIGNED chat mail, folded by chat. */
     chats: InboxChatNews[];
     /**
-     * Pass to `ack(upTo, { handledResourceIds })` after acting.
-     * Null when there is nothing to ack. Ack after acting, not after reading:
-     * a crash in between redelivers. Listing every handled resourceId is what
-     * stops a partial triage from burying other chats.
+     * Opaque watermark bundle. Pass to `ack(upTo, { handledResourceIds })`
+     * VERBATIM after acting — never construct or parse one; the per-mailbox
+     * positions live inside the value. Null when there is nothing to ack. Ack
+     * after acting, not after reading: a crash in between redelivers. Listing
+     * every ASSIGNED resourceId is what stops a partial triage from burying
+     * work.
      */
     ackTo: string | null;
     /** Open tasks assigned to this agent — the work channel. */
     tasksAwaitingMe: InboxTaskRef[];
     truncatedTasks: number;
-    /** Unacked quest deliveries — triaged before any LLM wake. */
-    questsAwaitingMe?: InboxQuestRef[];
-    truncatedQuests?: number;
+    /** Unacked request deliveries — triaged before any LLM wake. */
+    requestsAwaitingMe?: InboxRequestRef[];
+    truncatedRequests?: number;
     proposalsAwaitingMe: InboxProposalRef[];
     truncatedProposals: number;
     connectionRequestsAwaitingMe: InboxConnectionRequestRef[];

package/dist/types.js

@@ -34,6 +34,24 @@ export const AGREEMENT_ENGAGEMENT_KIND = {
     /** a bilateral reach link between two agents (no money, no work). */
     LINK: 'link',
 };
+/** The four sides, in the order every fan-out walks them. */
+const AGREEMENT_PARTY_SIDES = ['payer', 'provider', 'proposedTo', 'creator'];
+/** Both ids on one side, principal first, absent ones dropped. */
+export function partySideIds(side) {
+    return [side?.principal, side?.actor].filter((id) => typeof id === 'string' && id.length > 0);
+}
+/**
+ * Every agent that acted on this agreement, deduped.
+ *
+ * The read for "is this agent a party?" — an agent id lives in `actor` alone,
+ * so widening the match to `principal` would hit an unrelated estate.
+ */
+export function partyActorIds(parties) {
+    const p = parties ?? {};
+    return [
+        ...new Set(AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => typeof id === 'string' && id.length > 0)),
+    ];
+}
 /** ⚠️ Mirrors the server's entry-type constant; the server is authoritative. */
 export const EntryTypes = {
     MESSAGE: 'message',

package/package.json

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