@ziggs-ai/api-client 0.11.0 → 0.13.0

package/dist/http/agreementFlows.js

@@ -1,20 +1,15 @@
-import { createLink, 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 createLink({
-            ...(target ? { targetAgentId: 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) {
@@ -68,10 +63,10 @@ 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;
     // 'request' is the shape the route has always handled.
     return { agreement, kind: kind ?? 'request' };

package/dist/http/grants.d.ts

@@ -36,9 +36,15 @@ export type GrantBasisKind = 'creation' | 'publication' | 'membership' | 'accept
  * stopped showing a whole scope kind after `artifact` was added; anything that
  * means "every context scope" should read this.
  */
-export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact"];
-/** Every scope kind across every rail: context + connection + payment. */
-export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "connection", "wallet"];
+export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task"];
+/**
+ * Every scope kind across every rail: context + connection + payment + consent
+ * + carrier. Mirrors the server's `GRANT_SCOPE_KINDS` (grants/grant-view.ts),
+ * which is the list `GET /grants?scopeKind=` validates against — a kind missing
+ * here cannot be asked for at all, which is the failure the comment above
+ * describes.
+ */
+export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "connection", "wallet", "consent", "inbox"];
 export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
 export interface GrantScopeView {
     kind: GrantScopeKind;

package/dist/http/grants.js

@@ -12,12 +12,25 @@ export const CONTEXT_GRANT_SCOPE_KINDS = [
     'org',
     // narrowest context scope
     'artifact',
+    // a branch of a work graph: the named task and everything under it, now and
+    // in future. Holding one is what being in a job means.
+    'task',
 ];
-/** Every scope kind across every rail: context + connection + payment. */
+/**
+ * Every scope kind across every rail: context + connection + payment + consent
+ * + carrier. Mirrors the server's `GRANT_SCOPE_KINDS` (grants/grant-view.ts),
+ * which is the list `GET /grants?scopeKind=` validates against — a kind missing
+ * here cannot be asked for at all, which is the failure the comment above
+ * describes.
+ */
 export const GRANT_SCOPE_KINDS = [
     ...CONTEXT_GRANT_SCOPE_KINDS,
     'connection',
     'wallet',
+    // approval authority — who may answer a slot
+    'consent',
+    // carrier grants — who reads whose mailbox
+    'inbox',
 ];
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export function grantCaveat(grant, type) {

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, InboxRequestRef, 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, type DelegateContextGrantResult, type GrantView } from '../http/index.js';
 /** Minimal relay step shape — keep field names aligned with agents/coordinators/relayTypes.ts */
 export interface RelayStepInput {
     stepId: string;
@@ -21,19 +21,72 @@ export interface RelayPayloadShape {
 }
 export type ProvisionMethod = 'existing' | 'claim' | 'delegate';
 export type StepProvisionStatus = 'active' | 'pending_approval';
+/**
+ * What happened to the coordinator's pass on this worker contract.
+ *
+ *  - `granted`  — the coordinator may create work citing this contract.
+ *  - `reused`   — it already held one; nothing was minted.
+ *  - `pending_approval` — the pass needs a person. An agent cannot MINT a root
+ *    agreement grant at all: `POST /context/grants` requires the `context:grant`
+ *    operator scope, which a delegate never holds ("no re-mint or grant will
+ *    satisfy this"). So an initiator agent's only route is delegating the
+ *    participation grant it holds — and handing a slice to a third party in
+ *    another org opens a card that owner must approve.
+ *  - `deferred` — the contract itself is not active yet, so there is no
+ *    participation grant to delegate from. Provision again after it activates.
+ *  - `failed`   — named so the caller stops rather than kicking off a run whose
+ *    branches will each be refused one at a time.
+ */
+export type GrantProvisionStatus = 'granted' | 'reused' | 'pending_approval' | 'deferred' | 'failed';
+export interface StepGrantProvision {
+    status: GrantProvisionStatus;
+    grantId?: string;
+    /** The approval card's agreement id, when a person has to say yes. */
+    approvalAgreementId?: string;
+    error?: string;
+}
 export type ProvisionedRelayStep = RelayPayloadShape['steps'][number] & {
     provisionMethod: ProvisionMethod;
     status: StepProvisionStatus;
+    /**
+     * The coordinator's pass on this step's contract. Handing over an agreement
+     * id is not enough: membership in work is a grant, and the coordinator is not
+     * a party to this contract, so nothing about it reaches the coordinator
+     * otherwise.
+     */
+    grant: StepGrantProvision;
 };
 export interface RelayProvisionDeps {
     getMyAgreements: typeof getMyAgreements;
     pullOffers: typeof pullOffers;
-    claimOffer: typeof claimOffer;
+    claimOpenAgreement: typeof claimOpenAgreement;
     delegateAgreement: typeof delegateAgreement;
+    /**
+     * Grants on one agreement scope. `role` picks which side: `holder` is what
+     * this initiator holds (the participation grant to delegate FROM), `issuer` is
+     * what it has already caused (so a re-provision reuses rather than re-mints).
+     */
+    listAgreementGrants: (args: {
+        agreementId: string;
+        role: 'holder' | 'issuer';
+    }, creds: Creds) => Promise<GrantView[]>;
+    delegateAgreementGrant: (args: {
+        parentGrantId: string;
+        holderId: string;
+        agreementId: string;
+    }, creds: Creds) => Promise<DelegateContextGrantResult>;
 }
 export interface ProvisionRelayWorkersInput {
     creds: Creds;
     hireAgreementId: string;
+    /**
+     * The coordinator that will create the work. Required, because provisioning a
+     * worker FOR a coordinator is two acts and this names who the second one is
+     * for: without an `agreement`-scope grant on each worker contract, the
+     * coordinator's very first `task_create` is refused with "holds no grant on
+     * agreement …" and every branch of the run fails the same way.
+     */
+    coordinatorId: string;
     chatId?: string;
     steps: RelayStepInput[];
     inputArtifactIds?: string[];
@@ -41,6 +94,11 @@ export interface ProvisionRelayWorkersInput {
 export interface ProvisionRelayWorkersResult {
     payload: RelayPayloadShape;
     steps: ProvisionedRelayStep[];
+    /**
+     * Everything a person still has to approve before kickoff — agreement
+     * activations AND grant hand-overs, in one list. They gate the run
+     * identically, so splitting them would just make a caller check two.
+     */
     pendingApprovals: string[];
     readyForKickoff: boolean;
 }
@@ -49,5 +107,13 @@ type AgreementWithParent = Agreement & {
 };
 export declare function findExistingWorkerDelegation(hireAgreementId: string, assigneeId: string, agreements: AgreementWithParent[]): AgreementWithParent | null;
 export declare function findOpenOfferForAgent(assigneeId: string, offers: Agreement[]): Agreement | null;
+/**
+ * The default grant plumbing, built on the two clients that own these routes.
+ *
+ * A thin function seam rather than the clients themselves, so a test can drive
+ * provisioning without a backend — the same reason the agreement calls are
+ * injected.
+ */
+export declare function defaultRelayProvisionDeps(): RelayProvisionDeps;
 export declare function provisionRelayWorkers(input: ProvisionRelayWorkersInput, deps?: RelayProvisionDeps): Promise<ProvisionRelayWorkersResult>;
 export {};

package/dist/relay/provisionRelayWorkers.js

@@ -1,6 +1,6 @@
-import { claimOffer, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
+import { ContextGrantsClient, GrantsClient, 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';
@@ -27,23 +27,123 @@ export function findOpenOfferForAgent(assigneeId, offers) {
         return providerAgentId(o) === assigneeId;
     }) ?? null);
 }
-export async function provisionRelayWorkers(input, deps = {
-    getMyAgreements,
-    pullOffers,
-    claimOffer,
-    delegateAgreement,
-}) {
-    const { creds, hireAgreementId, chatId, steps, inputArtifactIds } = input;
+/**
+ * The default grant plumbing, built on the two clients that own these routes.
+ *
+ * A thin function seam rather than the clients themselves, so a test can drive
+ * provisioning without a backend — the same reason the agreement calls are
+ * injected.
+ */
+export function defaultRelayProvisionDeps() {
+    return {
+        getMyAgreements,
+        pullOffers,
+        claimOpenAgreement,
+        delegateAgreement,
+        listAgreementGrants: async ({ agreementId, role }, creds) => {
+            const client = new GrantsClient(creds.operatorKey, creds.agentId);
+            return client.listAllGrants({
+                scopeKind: 'agreement',
+                scopeId: agreementId,
+                role,
+                health: 'active',
+            });
+        },
+        delegateAgreementGrant: async ({ parentGrantId, holderId, agreementId }, creds) => {
+            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
+            return client.delegateGrant(parentGrantId, {
+                holderId,
+                holderKind: 'agent',
+                // `write` is exactly what `canActUnderAgreement` tests. Deliberately not
+                // `admit`: that would let a coordinator widen its own crew.
+                kind: 'write',
+                scope: { kind: 'agreement', id: agreementId },
+                // from-start, not from-now: the contract predates the grant, so a
+                // from-now watermark would exclude the very row the grant is about.
+                temporal: 'from-start',
+            });
+        },
+    };
+}
+/**
+ * Hand the coordinator a pass on one worker contract.
+ *
+ * Membership in work is a grant, which is what lets a coordinator create work
+ * under a contract it is not a party to. Issuing that grant is the half that has
+ * to happen here: without it the recipe fails at the coordinator's first
+ * `task_create` with "Caller <coordinator> holds no grant on agreement <worker>,
+ * so it cannot create work citing it."
+ *
+ * Reused before minted, because provisioning is re-run: a second call after an
+ * agreement activates should not stack a second pass on a contract that already
+ * has one.
+ */
+async function grantCoordinatorAccess(args, deps) {
+    const { agreementId, coordinatorId, status, creds } = args;
+    // Participation grants are minted at ACTIVATION, so a contract still waiting
+    // on a signature has nothing to delegate from yet. Say so rather than
+    // reporting a failure the caller cannot act on.
+    if (status !== 'active') {
+        return {
+            status: 'deferred',
+            error: `${agreementId} is not active yet, so there is no participation grant to ` +
+                'delegate from — provision again once it activates',
+        };
+    }
+    try {
+        const alreadyIssued = await deps.listAgreementGrants({ agreementId, role: 'issuer' }, creds);
+        const existing = alreadyIssued.find((g) => g.holderId === coordinatorId);
+        if (existing?.grantId)
+            return { status: 'reused', grantId: existing.grantId };
+        const held = await deps.listAgreementGrants({ agreementId, role: 'holder' }, creds);
+        // Only a `write` or `admit` parent can beget the `write` child the act rule
+        // tests; a `read` participation grant cannot be widened by delegating it.
+        // `access` is optional on GrantView because some rails do not record it —
+        // context grants always do, so an absent value here is a malformed row and
+        // must not be treated as strong enough.
+        const parent = held.find((g) => g.access === 'write' || g.access === 'admit');
+        if (!parent?.grantId) {
+            return {
+                status: 'failed',
+                error: `no write-or-stronger grant on ${agreementId} to delegate from (found ` +
+                    `${held.length ? held.map((g) => g.access ?? 'unstated').join(', ') : 'none'}) — ` +
+                    'the initiator must be a party to the worker contract it is provisioning',
+            };
+        }
+        const result = await deps.delegateAgreementGrant({ parentGrantId: parent.grantId, holderId: coordinatorId, agreementId }, creds);
+        if (result.status === 'pending_approval') {
+            return { status: 'pending_approval', approvalAgreementId: result.agreementId };
+        }
+        return { status: 'granted', grantId: result.grant.grantId };
+    }
+    catch (err) {
+        return {
+            status: 'failed',
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function provisionRelayWorkers(input, deps = defaultRelayProvisionDeps()) {
+    const { creds, hireAgreementId, coordinatorId, chatId, steps, inputArtifactIds } = input;
     if (!steps.length)
         throw new Error('steps must not be empty');
+    if (!coordinatorId?.trim()) {
+        throw new Error('coordinatorId is required: provisioning a worker for a coordinator means both ' +
+            'the contract and an agreement-scope grant to that coordinator on it, and ' +
+            'without the grant every branch of the run is refused');
+    }
     const myAgreements = (await deps.getMyAgreements({}, creds));
     let offersCache = null;
-    const provisioned = [];
+    // The contracts first, then the passes. Two passes rather than one because a
+    // grant can only be delegated from a participation grant, which exists only
+    // once the contract is active — so the grant decision needs the settled
+    // status of the row, not the intent that created it.
+    const contracted = [];
     const pendingApprovals = [];
     for (const step of steps) {
         const existing = findExistingWorkerDelegation(hireAgreementId, step.assigneeId, myAgreements);
         if (existing?.agreementId) {
-            provisioned.push({
+            contracted.push({
                 stepId: step.stepId,
                 order: step.order,
                 agreementId: existing.agreementId,
@@ -55,14 +155,14 @@ 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'
                 : 'pending_approval';
             if (status === 'pending_approval')
                 pendingApprovals.push(agreementId);
-            provisioned.push({
+            contracted.push({
                 stepId: step.stepId,
                 order: step.order,
                 agreementId,
@@ -78,14 +178,14 @@ 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'
                 : 'pending_approval';
             if (status === 'pending_approval')
                 pendingApprovals.push(agreementId);
-            provisioned.push({
+            contracted.push({
                 stepId: step.stepId,
                 order: step.order,
                 agreementId,
@@ -115,7 +215,7 @@ export async function provisionRelayWorkers(input, deps = {
             : 'pending_approval';
         if (status === 'pending_approval')
             pendingApprovals.push(agreementId);
-        provisioned.push({
+        contracted.push({
             stepId: step.stepId,
             order: step.order,
             agreementId,
@@ -125,7 +225,21 @@ export async function provisionRelayWorkers(input, deps = {
             status,
         });
     }
-    provisioned.sort((a, b) => a.order - b.order);
+    contracted.sort((a, b) => a.order - b.order);
+    // ── the second act of provisioning: the coordinator's passes ─────────────
+    const provisioned = [];
+    for (const step of contracted) {
+        const grant = await grantCoordinatorAccess({
+            agreementId: step.agreementId,
+            coordinatorId,
+            status: step.status,
+            creds,
+        }, deps);
+        if (grant.status === 'pending_approval' && grant.approvalAgreementId) {
+            pendingApprovals.push(grant.approvalAgreementId);
+        }
+        provisioned.push({ ...step, grant });
+    }
     const payload = {
         inputArtifactIds,
         steps: provisioned.map(({ stepId, order, agreementId, assigneeId, description }) => ({
@@ -136,8 +250,14 @@ export async function provisionRelayWorkers(input, deps = {
             description,
         })),
     };
+    /**
+     * Ready means BOTH acts are done for every step. A run whose contracts are all
+     * active but whose coordinator holds no passes looks provisioned and has every
+     * branch refused, so the grant has to count here or this flag goes on lying.
+     */
     const readyForKickoff = pendingApprovals.length === 0 &&
-        provisioned.every((s) => s.status === 'active');
+        provisioned.every((s) => s.status === 'active' &&
+            (s.grant.status === 'granted' || s.grant.status === 'reused'));
     return {
         payload,
         steps: provisioned,

package/dist/types.d.ts

@@ -71,6 +71,14 @@ export interface Task {
     updatedAt?: string;
     parentTaskId?: string;
     rootTaskId?: string;
+    /** Tasks this one waits for before it may start. */
+    waitsOn?: string[];
+    /**
+     * True while {@link waitsOn} is unmet: the task exists but has not been
+     * delivered, and its assignee cannot take the processing lock yet. Distinct
+     * from "nobody has picked it up" — this one is waiting on purpose.
+     */
+    heldByDeps?: boolean;
     plan?: {
         steps?: PlanStep[];
     };
@@ -91,19 +99,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 +155,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;
@@ -341,6 +369,15 @@ export interface InboxProposalRef {
     agreementId: string;
     title: string;
     proposedAt: string | null;
+    /**
+     * The agent designated to wake for this proposal, or null when it is
+     * ambient/human work in this reader's merged inbox.
+     *
+     * Optional for rolling deploys. When an older server omits it, clients must
+     * only use an explicit agent-keyed approval/responder slot as a safe fallback;
+     * org visibility alone is never assignment.
+     */
+    assignedAgentId?: string | null;
     /**
      * party ids still owing a decision, and the named responder slot.
      * The inbox lists proposals awaiting the agent OR its human, and only the

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.11.0",
+  "version": "0.13.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",