@ziggs-ai/api-client 0.12.0 → 0.13.0

package/dist/capabilities/agreementVerbs.js

@@ -106,6 +106,17 @@ const AUDIENCE_PARAM = {
     required: true,
     description: 'everyone is fully public; org is your active organisation only.',
 };
+/**
+ * The triage string a supplier host compares against with no LLM turn. Only a
+ * REQUEST carries one, and until now only the web door could set it: every
+ * request an agent published reached its suppliers with nothing to triage on,
+ * which made "no triage" the normal case rather than the edge.
+ */
+const MATCH_PARAM = {
+    type: 'string',
+    required: false,
+    description: 'Optional exact-match triage string suppliers compare against verbatim, so a host can decide whether the work is theirs without spending a turn on it. Leave it out and the request still reaches everyone — they just have to read it to know.',
+};
 const COUNTERPARTY_PARAM = {
     type: 'string',
     required: true,
@@ -235,6 +246,7 @@ export const agreementRequestCapability = {
     params: {
         audience: AUDIENCE_PARAM,
         ...TERMS_PARAMS,
+        match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
     },
     needsAgentId: true,
@@ -245,6 +257,7 @@ export const agreementRequestCapability = {
             chatId: '',
             audience: args['audience'],
             engagementKind: engagementKindFrom(args),
+            match: typeof args['match'] === 'string' ? args['match'] : undefined,
         }, fullCreds(env));
         return { agreement, readPlan: publishedNext(env) };
     },

package/dist/capabilities/context.js

@@ -132,8 +132,8 @@ export const contextExpandReachCapability = {
     names: { sdk: 'context_expand_reach', mcp: 'ziggs_context_expand_reach' },
     title: 'See what a grant reaches',
     descriptions: {
-        sdk: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — the grant IS one artifact, so read it directly with context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
-        mcp: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_grant_list tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. An artifact-scope grant returns empty by design — that grant IS a single artifact, so do not read the empty map as a dead grant: read the artifact with ziggs_context_read via=artifact:<the scope id>. Holder-only, grant-fenced.',
+        sdk: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, no content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered resource kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
+        mcp: 'Expand a grant you hold into the chat/agreement ids listed inside a broader scope (ids + labels only, never content). A chat grant returns its chat. Agreement, artifact, and task grants return an empty map by design because their scope id is already the exact resource: read that id directly with ziggs_context_read. In particular, an agreement grant never opens linked chats. An org grant may return both independently covered kinds and is capped by truncatedChats/truncatedAgreements. Holder-only, grant-fenced.',
     },
     annotation: 'read-only',
     params: {

package/dist/capabilities/grants.d.ts

@@ -1,7 +1,8 @@
 import { type CapabilityDefinition } from './types.js';
 /**
  * the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact/task, connection, wallet, consent,
+ * inbox), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *

package/dist/capabilities/grants.js

@@ -23,7 +23,8 @@ function parseScopeKinds(raw) {
 }
 /**
  * the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org/artifact, connection, wallet), holder-scoped,
+ * (context chat/agreement/org/artifact/task, connection, wallet, consent,
+ * inbox), holder-scoped,
  * cross-session. `unreadableRails` comes from the backend so a short
  * list is never presented as complete when the key can't read a rail.
  *
@@ -40,8 +41,8 @@ export const listGrantsCapability = {
     names: { sdk: 'grant_list', mcp: 'ziggs_grant_list' },
     title: 'List grants you hold',
     descriptions: {
-        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
-        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact), connection, and wallet — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        sdk: 'List grants this agent holds — or, with role=issuer, grants this agent caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". role=issuer answers "who did I share with / what did I mint?" after artifact_share. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
+        mcp: 'List grants this delegate holds — or, with role=issuer, grants this delegate caused (author-shares and delegate children). Context (chat/agreement/org/artifact/task), connection, wallet, consent, and inbox — canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). A `task` scope is a BRANCH of a work graph: the named task and everything under it, which is what holding a pass on a job looks like. Default role=holder answers "what grants do I HOLD?", which is narrower than "what can I reach?": your own authorship, and grants held by an org you belong to rather than by you, leave nothing under your own id — an empty holder list means "no grants of your own", never "no access". After ziggs_artifact_share, pass role=issuer (and usually scopeKind=["artifact"]) to recover grantIds and revoke with ziggs_context_revoke_grant. Filter by scopeKind, scopeId, and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails. Cursor-paginated.',
     },
     annotation: 'read-only',
     params: {

package/dist/http/AgreementClient.d.ts

@@ -44,6 +44,12 @@ export interface ProposeDirectInput extends ProposeTerms {
  */
 export type ProposeBroadcastInput = Omit<ProposeDirectInput, 'proposedTo'> & {
     audience?: BroadcastAudience;
+    /**
+     * Exact-match triage for supplier hosts: a plain string they compare
+     * verbatim, no LLM turn. Absent or empty still delivers the request; the
+     * supplier just has nothing to triage on.
+     */
+    match?: string;
 };
 /**
  * A trust link's agreement, as every caller sees it.
@@ -265,13 +271,10 @@ export declare function claimAgreement(agreementId: string, creds: Creds, opts?:
     kind?: ClaimedKind;
 }>;
 /**
- * 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.
+ * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
+ * callers may only pin an agreement into a chat as a reference (`mention`).
  */
-export declare const CHAT_LINK_TYPES: readonly ["origin", "mention", "delegation", "join"];
+export declare const CHAT_LINK_TYPES: readonly ["mention"];
 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[]>;
@@ -279,10 +282,6 @@ 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 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 {
     private creds;
     /**
@@ -319,6 +318,4 @@ export declare class AgreementClient {
     listChats(id: string): Promise<unknown[]>;
     linkArtifact(id: string, artifactId: string, linkType?: ArtifactLinkType): Promise<unknown>;
     listArtifacts(id: string): Promise<unknown[]>;
-    linkUser(id: string, userId: string, role: UserRole): Promise<unknown>;
-    listUsers(id: string): Promise<unknown[]>;
 }

package/dist/http/AgreementClient.js

@@ -514,18 +514,10 @@ export async function claimAgreement(agreementId, creds, opts = {}) {
 // 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.
+ * Link types a caller may ask for. `origin` and `delegation` are workflow-owned;
+ * callers may only pin an agreement into a chat as a reference (`mention`).
  */
-export const CHAT_LINK_TYPES = [
-    'origin',
-    'mention',
-    'delegation',
-    'join',
-];
+export const CHAT_LINK_TYPES = ['mention'];
 export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
     if (!agreementId || !chatId)
         return null;
@@ -618,59 +610,6 @@ 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;
-    assertCreds(creds, 'link user to agreement');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
-            method: 'POST',
-            headers: buildHeaders(creds),
-            body: JSON.stringify({ userId, role }),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return null;
-        }
-        return await res.json().catch(() => null);
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Link user failed: ${e.message}`);
-        return null;
-    }
-}
-export async function getUsersForAgreement(agreementId, creds) {
-    if (!agreementId)
-        return [];
-    assertCreds(creds, 'get users for agreement');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/${agreementId}/users`, {
-            method: 'GET',
-            headers: buildHeaders(creds),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return [];
-        }
-        const data = await res.json().catch(() => null);
-        return Array.isArray(data?.['users']) ? data['users'] : [];
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Get users failed: ${e.message}`);
-        return [];
-    }
-}
 export class AgreementClient {
     creds;
     /**
@@ -703,6 +642,4 @@ export class AgreementClient {
     listChats(id) { return getChatsForAgreement(id, this.creds); }
     linkArtifact(id, artifactId, linkType) { return linkArtifactToAgreement(id, artifactId, linkType ?? 'produced', this.creds); }
     listArtifacts(id) { return getArtifactsForAgreement(id, this.creds); }
-    linkUser(id, userId, role) { return linkUserToAgreement(id, userId, role, this.creds); }
-    listUsers(id) { return getUsersForAgreement(id, this.creds); }
 }

package/dist/http/ContextGrantsClient.d.ts

@@ -1,10 +1,16 @@
+import { CONTEXT_GRANT_SCOPE_KINDS } from './grants.js';
 import type { GrantAccessKind, GrantHolderKind, GrantView } from './grants.js';
 /**
- * added `artifact` — the narrowest context scope: one specific artifact,
- * shared without sharing any chat or agreement it sits in. Still the context
- * rail, not a new grant primitive.
+ * The context rail's scopes. `artifact` is the narrowest — one specific
+ * artifact, shared without sharing any chat or agreement it sits in. `task` is
+ * a branch of a work graph: the named task and everything under it. Both are
+ * still the context rail, not new grant primitives.
+ *
+ * Derived from {@link CONTEXT_GRANT_SCOPE_KINDS} rather than written out again:
+ * a hand-copied subset still typechecks against the union, which is how this
+ * list sat a scope kind behind the rail.
  */
-export type ContextGrantScopeKind = 'chat' | 'agreement' | 'org' | 'artifact';
+export type ContextGrantScopeKind = (typeof CONTEXT_GRANT_SCOPE_KINDS)[number];
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface ContextGrantScope {
     kind: ContextGrantScopeKind;

package/dist/http/MarketplaceClient.d.ts

@@ -23,21 +23,6 @@ export interface PullOffersOptions {
     since?: string;
 }
 export declare function pullOffers(options: PullOffersOptions | undefined, creds: Creds): Promise<Agreement[]>;
-export interface PublishRequestPayload {
-    /** See PublishOfferPayload.billing. */
-    billing?: 'total' | 'per_task';
-    description: string;
-    chatId?: string;
-    payerId?: string;
-    price?: number;
-    lifecycle?: string;
-    expiresAt?: string;
-    maxExecutions?: number;
-    agreementDescription?: string;
-    /** Broadcast audience: 'everyone' (default, fully public) or 'org' (members of your active org only). */
-    audience?: BroadcastAudience;
-}
-export declare function publishRequest(payload: PublishRequestPayload, creds: Creds): Promise<Agreement>;
 export interface PullRequestsOptions {
     limit?: number;
     since?: string;
@@ -52,6 +37,5 @@ export declare class MarketplaceClient {
     constructor(operatorKey: string, agentId?: string);
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     pullOffers(options?: PullOffersOptions): Promise<Agreement[]>;
-    publishRequest(payload: PublishRequestPayload): Promise<Agreement>;
     pullRequests(options?: PullRequestsOptions): Promise<Agreement[]>;
 }

package/dist/http/MarketplaceClient.js

@@ -52,22 +52,6 @@ export async function pullOffers(options, creds) {
     const data = await res.json().catch(() => null);
     return data?.['offers'] ?? [];
 }
-export async function publishRequest(payload, creds) {
-    assertCreds(creds, 'request publish');
-    const res = await fetch(`${getMarketplaceBaseUrl()}/requests/publish`, {
-        method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify(payload || {}),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throwApiError(res, body, `Request publish failed: ${res.status}`);
-    }
-    const data = await res.json().catch(() => null);
-    if (!data?.['agreement'])
-        throw new Error('Request publish returned no agreement');
-    return shapeAgreement(data['agreement']);
-}
 export async function pullRequests(options, creds) {
     assertCreds(creds, 'request pull');
     const params = new URLSearchParams();
@@ -102,6 +86,5 @@ export class MarketplaceClient {
     }
     publishOffer(payload) { return publishOffer(payload, this.creds); }
     pullOffers(options) { return pullOffers(options, this.creds); }
-    publishRequest(payload) { return publishRequest(payload, this.creds); }
     pullRequests(options) { return pullRequests(options, this.creds); }
 }

package/dist/http/TaskClient.d.ts

@@ -37,10 +37,24 @@ export interface CreateTaskData {
     planReviewTiming?: PlanReviewTiming;
     requireMidWorkPlanAck?: boolean;
     idempotencyKey?: string;
-    /** Explicit delegation target — must be a party to the agreement; validated server-side. */
+    /**
+     * Explicit delegation target — must hold a grant on the agreement, so work
+     * can only be handed to someone that contract already reaches; validated
+     * server-side.
+     */
     assigneeId?: string;
     /** prior-step artifact handles consumed as structured input links. */
     inputArtifactIds?: string[];
+    /**
+     * Tasks this one waits for. The task is created immediately, but its assignee
+     * is not woken and cannot start it until every task named here is terminal.
+     * Declaring an edge needs read reach on the task you name.
+     *
+     * Declared rather than enacted: state the join up front and the platform
+     * wakes the joiner once, instead of a live agent polling for it and holding
+     * the shape in its own control flow where nothing else can see it.
+     */
+    waitsOn?: string[];
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;

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

@@ -1,5 +1,5 @@
 import type { Agreement, Creds } from '../types.js';
-import { claimOpenAgreement, 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;
     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,4 +1,4 @@
-import { claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
+import { ContextGrantsClient, GrantsClient, claimOpenAgreement, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
 function providerAgentId(agreement) {
     return agreement.parties?.provider?.actor ?? null;
 }
@@ -27,23 +27,123 @@ export function findOpenOfferForAgent(assigneeId, offers) {
         return providerAgentId(o) === assigneeId;
     }) ?? null);
 }
-export async function provisionRelayWorkers(input, deps = {
-    getMyAgreements,
-    pullOffers,
-    claimOpenAgreement,
-    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,
@@ -62,7 +162,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,
@@ -85,7 +185,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,
@@ -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[];
     };
@@ -361,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/package.json

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