@ziggs-ai/api-client 0.1.26 → 0.1.29

package/dist/http/AgreementClient.d.ts

@@ -170,7 +170,6 @@ export declare function claimAgreement(agreementId: string, creds: Creds): Promi
     ok: boolean;
     agreement: Agreement;
 }>;
-export declare function getAgreementsByChat(chatId: string, creds: Creds): Promise<unknown[]>;
 export type ChatLinkType = 'origin' | 'mention' | 'delegation' | 'join';
 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[]>;
@@ -219,7 +218,6 @@ export declare class AgreementClient {
         ok: boolean;
         agreement: Agreement;
     }>;
-    listByChat(chatId: string): Promise<unknown[]>;
     linkToChat(id: string, chatId: string, linkType?: ChatLinkType): Promise<unknown>;
     listChats(id: string): Promise<unknown[]>;
     join(id: string): Promise<{

package/dist/http/AgreementClient.js

@@ -414,32 +414,6 @@ export async function claimAgreement(agreementId, creds) {
     }
     return data;
 }
-// ---------------------------------------------------------------------------
-// Chat links
-// ---------------------------------------------------------------------------
-export async function getAgreementsByChat(chatId, creds) {
-    if (!chatId)
-        return [];
-    assertCreds(creds, 'get agreements by chat');
-    try {
-        const res = await fetch(`${getAgreementBaseUrl()}/by-chat/${encodeURIComponent(chatId)}`, {
-            method: 'GET',
-            headers: buildHeaders(creds),
-        });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-            return [];
-        }
-        const data = await res.json().catch(() => null);
-        const links = data?.['links'] ?? data?.['agreements'];
-        return Array.isArray(links) ? links : [];
-    }
-    catch (e) {
-        runtimeLog.warn('AgreementClient', `⚠️ Get agreements by chat failed: ${e.message}`);
-        return [];
-    }
-}
 export async function linkAgreementToChat(agreementId, chatId, linkType = 'mention', creds) {
     if (!agreementId || !chatId)
         return null;
@@ -618,7 +592,6 @@ export class AgreementClient {
     revoke(id) { return revokeAgreement(id, this.creds); }
     fulfill(id) { return fulfillAgreement(id, this.creds); }
     claimAgreement(id) { return claimAgreement(id, this.creds); }
-    listByChat(chatId) { return getAgreementsByChat(chatId, this.creds); }
     linkToChat(id, chatId, linkType) { return linkAgreementToChat(id, chatId, linkType ?? 'mention', this.creds); }
     listChats(id) { return getChatsForAgreement(id, this.creds); }
     join(id) { return joinAgreement(id, this.creds); }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -1,16 +1,4 @@
 import 'dotenv/config';
-export interface ContextReachDescriptor {
-    grantId: string;
-    scope: {
-        kind: 'chat' | 'agreement' | 'org';
-        id: string;
-    };
-    temporal: 'from-now' | 'from-start';
-    watermarkAt: string;
-    expiresAt: string | null;
-    parentGrantId: string | null;
-    createdAt: string;
-}
 /** Labels-only pointer to context the agent could request access to (P4). */
 export interface DiscoverableItem {
     type: 'chat';
@@ -22,7 +10,9 @@ export interface DiscoverableItem {
     orgId: string;
 }
 /**
- * ZIG-412 discovery — scope descriptors only, no content.
+ * P4 discovery — labels-only pointers to context the agent could REQUEST but
+ * does not yet hold (`GET /context/discovery/available`). Grants the agent
+ * already holds are listed via the unified `GrantsClient` (GET /grants).
  */
 export declare class ContextDiscoveryClient {
     private readonly operatorKey;
@@ -33,7 +23,6 @@ export declare class ContextDiscoveryClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
-    discover(): Promise<ContextReachDescriptor[]>;
     /**
      * P4: what context EXISTS in the agent's engaged orgs that it does NOT hold
      * a grant for — so it can request access rather than fail blind. Labels only.

package/dist/http/ContextDiscoveryClient.js

@@ -2,7 +2,9 @@ import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 /**
- * ZIG-412 discovery — scope descriptors only, no content.
+ * P4 discovery — labels-only pointers to context the agent could REQUEST but
+ * does not yet hold (`GET /context/discovery/available`). Grants the agent
+ * already holds are listed via the unified `GrantsClient` (GET /grants).
  */
 export class ContextDiscoveryClient {
     operatorKey;
@@ -20,17 +22,6 @@ export class ContextDiscoveryClient {
         this.agentId = agentId;
         this.baseUrl = baseUrl || getBackendUrl();
     }
-    async discover() {
-        const res = await fetch(`${this.baseUrl}/context/discovery`, {
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
-        });
-        const body = await res.text().catch(() => '');
-        if (!res.ok) {
-            throw new Error(`ContextDiscoveryClient.discover ${res.status} ${body.slice(0, 200)}`);
-        }
-        const parsed = JSON.parse(body);
-        return parsed.reach ?? [];
-    }
     /**
      * P4: what context EXISTS in the agent's engaged orgs that it does NOT hold
      * a grant for — so it can request access rather than fail blind. Labels only.

package/dist/http/ContextReadClient.d.ts

@@ -20,6 +20,22 @@ export interface ContextReadEnvelope<T = unknown> {
     nextCursor: string | null;
     latestSequence?: string | null;
 }
+/** Aggregated chat snapshot from `GET /context/snapshot` (ZIG-775 follow-up). */
+export interface ContextSnapshotResult {
+    history: unknown[];
+    agreements: unknown[];
+    agents: Array<{
+        agentId: string;
+        role: string;
+        isYou: boolean;
+    }>;
+    users: Array<{
+        userId: string;
+        role: string;
+    }>;
+    latestSequence?: string | null;
+    chatMissing?: boolean;
+}
 /**
  * Protocol-first uniform context reads (ZIG-427).
  * Wraps `GET /context/read/:type` — one client, one envelope, four types.
@@ -34,4 +50,14 @@ export declare class ContextReadClient {
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     read<T = unknown>(type: ContextReadType, query: ContextReadQuery): Promise<ContextReadEnvelope<T>>;
+    /**
+     * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
+     * server composes history + agreements + roster through the same grant-fenced
+     * readers as {@link read}, so hosted agents pull one fenced view per wake.
+     * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
+     */
+    snapshot(chatId: string, opts?: {
+        maxMessages?: number;
+        contextGrantId?: string;
+    }): Promise<ContextSnapshotResult>;
 }

package/dist/http/ContextReadClient.js

@@ -53,4 +53,39 @@ export class ContextReadClient {
         }
         return JSON.parse(body);
     }
+    /**
+     * Aggregated chat snapshot — `GET /context/snapshot?via=chat:<id>`. The
+     * server composes history + agreements + roster through the same grant-fenced
+     * readers as {@link read}, so hosted agents pull one fenced view per wake.
+     * Rejects with an `Error & { status }` on non-OK so callers can branch (404).
+     */
+    async snapshot(chatId, opts = {}) {
+        if (!chatId?.trim()) {
+            throw new Error('ContextReadClient.snapshot: chatId is required');
+        }
+        const url = new URL(`${this.baseUrl}/context/snapshot`);
+        url.searchParams.set('via', `chat:${chatId}`);
+        if (opts.maxMessages != null) {
+            url.searchParams.set('maxMessages', String(opts.maxMessages));
+        }
+        if (opts.contextGrantId) {
+            url.searchParams.set('contextGrantId', opts.contextGrantId);
+        }
+        const headers = {
+            Authorization: `Bearer ${this.operatorKey}`,
+        };
+        if (this.agentId)
+            headers['X-Agent-Id'] = this.agentId;
+        if (opts.contextGrantId) {
+            headers['X-Context-Grant-Id'] = opts.contextGrantId;
+        }
+        const res = await fetch(url.toString(), { headers });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            const err = new Error(`ContextReadClient.snapshot ${res.status} ${body.slice(0, 200)}`);
+            err.status = res.status;
+            throw err;
+        }
+        return JSON.parse(body);
+    }
 }

package/dist/http/GrantsClient.d.ts

@@ -0,0 +1,45 @@
+import 'dotenv/config';
+import type { GrantView, GrantScopeKind, GrantHealth } from './grants.js';
+export interface ListGrantsQuery {
+    /**
+     * Filter to grants held by this agent. Admin-gated server-side when the caller
+     * is not impersonating that agent.
+     */
+    holderId?: string;
+    /**
+     * Rail/resource filter. One kind or several (the context rail spans three
+     * kinds: chat, agreement, org). Absent = every rail.
+     */
+    scopeKind?: GrantScopeKind | GrantScopeKind[];
+    /** Filter to grants of one health. */
+    health?: GrantHealth;
+    cursor?: string;
+    limit?: number;
+}
+export interface ListGrantsResult {
+    items: GrantView[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the
+ * canonical GrantView for each grant the caller holds (or, admin-gated, a named
+ * holder), filterable by scope kind and health, with cursor pagination. Replaces
+ * the old per-rail listers (context discovery, connection-grants,
+ * payment-grants).
+ */
+export declare class GrantsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    listGrants(query?: ListGrantsQuery): Promise<ListGrantsResult>;
+    /**
+     * Every grant matching `query`, following the cursor to completion. Use when a
+     * caller needs the whole set (reach tagging, catch-up, an owner listing) rather
+     * than a single page — `listGrants` returns only one page (server default 30),
+     * so a holder with more grants than a page would otherwise be silently
+     * truncated. `maxPages` bounds the loop as a runaway guard.
+     */
+    listAllGrants(query?: Omit<ListGrantsQuery, 'cursor'>, maxPages?: number): Promise<GrantView[]>;
+}

package/dist/http/GrantsClient.js

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the
+ * canonical GrantView for each grant the caller holds (or, admin-gated, a named
+ * holder), filterable by scope kind and health, with cursor pagination. Replaces
+ * the old per-rail listers (context discovery, connection-grants,
+ * payment-grants).
+ */
+export class GrantsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey)
+            throw new Error('GrantsClient: operatorKey is required');
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    async listGrants(query = {}) {
+        const url = new URL(`${this.baseUrl}/grants`);
+        if (query.holderId)
+            url.searchParams.set('holderId', query.holderId);
+        if (query.scopeKind) {
+            const kinds = Array.isArray(query.scopeKind)
+                ? query.scopeKind
+                : [query.scopeKind];
+            for (const k of kinds)
+                url.searchParams.append('scopeKind', k);
+        }
+        if (query.health)
+            url.searchParams.set('health', query.health);
+        if (query.cursor)
+            url.searchParams.set('cursor', query.cursor);
+        if (query.limit != null)
+            url.searchParams.set('limit', String(query.limit));
+        const res = await fetch(url.toString(), {
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`GrantsClient.listGrants ${res.status} ${body.slice(0, 200)}`);
+        }
+        const parsed = JSON.parse(body);
+        return {
+            items: parsed.items ?? [],
+            nextCursor: parsed.nextCursor ?? null,
+            hasMore: parsed.hasMore ?? false,
+        };
+    }
+    /**
+     * Every grant matching `query`, following the cursor to completion. Use when a
+     * caller needs the whole set (reach tagging, catch-up, an owner listing) rather
+     * than a single page — `listGrants` returns only one page (server default 30),
+     * so a holder with more grants than a page would otherwise be silently
+     * truncated. `maxPages` bounds the loop as a runaway guard.
+     */
+    async listAllGrants(query = {}, maxPages = 50) {
+        const all = [];
+        let cursor;
+        for (let page = 0; page < maxPages; page++) {
+            const res = await this.listGrants({ ...query, cursor });
+            all.push(...res.items);
+            if (!res.nextCursor)
+                return all;
+            cursor = res.nextCursor;
+        }
+        return all;
+    }
+}

package/dist/http/TaskClient.js

@@ -20,7 +20,13 @@ function parseErrorMessage(responseBody, defaultMessage) {
         return defaultMessage;
     try {
         const d = JSON.parse(responseBody);
-        return d['details'] || d['error'] || d['message'] || defaultMessage;
+        // NestJS ValidationPipe returns { message: string[] | string, error: 'Bad
+        // Request', statusCode }. Prefer the detailed `message` over the generic
+        // `error` so the real cause (which field failed validation) is surfaced
+        // instead of a bare "Bad Request". (ZIG-832)
+        const msg = d['message'];
+        const detailed = Array.isArray(msg) ? msg.join('; ') : (typeof msg === 'string' ? msg : undefined);
+        return d['details'] || detailed || d['error'] || defaultMessage;
     }
     catch {
         return responseBody || defaultMessage;

package/dist/http/grants.d.ts

@@ -15,6 +15,12 @@ export type GrantScopeKind = 'chat' | 'agreement' | 'org' | 'connection' | 'wall
 export interface GrantScopeView {
     kind: GrantScopeKind;
     id: string;
+    /**
+     * Human-readable name for the scoped resource, populated only by the unified
+     * list read (GET /grants / GrantsClient); the per-rail issue/delegate
+     * responses omit it. Optional so the one shape stays additive.
+     */
+    label?: string;
 }
 export interface GrantCaveatView {
     type: string;

package/dist/http/index.d.ts

@@ -6,12 +6,12 @@ export { MessagesClient } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
 export { ArtifactsClient } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
-export { ScopeClient } from './ScopeClient.js';
-export type { ScopeKind, ScopeResult, PartyRef } from './ScopeClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
-export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
-export type { ContextReachDescriptor } from './ContextDiscoveryClient.js';
+export type { DiscoverableItem } from './ContextDiscoveryClient.js';
+export { GrantsClient } from './GrantsClient.js';
+export type { ListGrantsQuery, ListGrantsResult } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, } from './ContextGrantsClient.js';
 export { grantCaveat } from './grants.js';

package/dist/http/index.js

@@ -4,9 +4,9 @@ export * from './MarketplaceClient.js';
 export * from './ChatClient.js';
 export { MessagesClient } from './MessagesClient.js';
 export { ArtifactsClient } from './ArtifactsClient.js';
-export { ScopeClient } from './ScopeClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
+export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat } from './grants.js';
 export { AgentSearchClient } from './AgentSearchClient.js';

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './http/index.js';
+export * from './relay/provisionRelayWorkers.js';
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './http/index.js';
+export * from './relay/provisionRelayWorkers.js';
 export { WebSocketClient } from './websocket/index.js';
 export { createControlSocket } from './websocket/ControlSocket.js';
 export { ConnectionManager } from './ConnectionManager.js';

package/dist/relay/provisionRelayWorkers.d.ts

@@ -0,0 +1,53 @@
+import type { Agreement, Creds } from '../types.js';
+import { claimOffer, 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;
+    order: number;
+    assigneeId: string;
+    description: string;
+    /** Standing offer agreementId to claim for this worker (optional). */
+    offerAgreementId?: string;
+}
+export interface RelayPayloadShape {
+    inputArtifactIds?: string[];
+    steps: Array<{
+        stepId: string;
+        order: number;
+        agreementId: string;
+        assigneeId: string;
+        description: string;
+    }>;
+}
+export type ProvisionMethod = 'existing' | 'claim' | 'delegate';
+export type StepProvisionStatus = 'active' | 'pending_approval';
+export type ProvisionedRelayStep = RelayPayloadShape['steps'][number] & {
+    provisionMethod: ProvisionMethod;
+    status: StepProvisionStatus;
+};
+export interface RelayProvisionDeps {
+    getMyAgreements: typeof getMyAgreements;
+    pullOffers: typeof pullOffers;
+    claimOffer: typeof claimOffer;
+    delegateAgreement: typeof delegateAgreement;
+}
+export interface ProvisionRelayWorkersInput {
+    creds: Creds;
+    hireAgreementId: string;
+    chatId?: string;
+    steps: RelayStepInput[];
+    inputArtifactIds?: string[];
+}
+export interface ProvisionRelayWorkersResult {
+    payload: RelayPayloadShape;
+    steps: ProvisionedRelayStep[];
+    pendingApprovals: string[];
+    readyForKickoff: boolean;
+}
+type AgreementWithParent = Agreement & {
+    parentAgreementId?: string;
+};
+export declare function findExistingWorkerDelegation(hireAgreementId: string, assigneeId: string, agreements: AgreementWithParent[]): AgreementWithParent | null;
+export declare function findOpenOfferForAgent(assigneeId: string, offers: Agreement[]): Agreement | null;
+export declare function provisionRelayWorkers(input: ProvisionRelayWorkersInput, deps?: RelayProvisionDeps): Promise<ProvisionRelayWorkersResult>;
+export {};

package/dist/relay/provisionRelayWorkers.js

@@ -0,0 +1,147 @@
+import { claimOffer, delegateAgreement, getMyAgreements, pullOffers, } from '../http/index.js';
+function providerAgentId(agreement) {
+    return agreement.parties?.providerAgent ?? agreement.parties?.provider ?? null;
+}
+function isActiveAgreement(agreement) {
+    return agreement.status === 'active';
+}
+export function findExistingWorkerDelegation(hireAgreementId, assigneeId, agreements) {
+    const matches = agreements.filter((a) => {
+        if (a.parentAgreementId !== hireAgreementId)
+            return false;
+        if (!isActiveAgreement(a))
+            return false;
+        return providerAgentId(a) === assigneeId;
+    });
+    matches.sort((a, b) => {
+        const ta = a.updatedAt ?? a.createdAt ?? '';
+        const tb = b.updatedAt ?? b.createdAt ?? '';
+        return tb.localeCompare(ta);
+    });
+    return matches[0] ?? null;
+}
+export function findOpenOfferForAgent(assigneeId, offers) {
+    return (offers.find((o) => {
+        if (o.status !== 'open' && o.status !== 'active')
+            return false;
+        return providerAgentId(o) === assigneeId;
+    }) ?? null);
+}
+export async function provisionRelayWorkers(input, deps = {
+    getMyAgreements,
+    pullOffers,
+    claimOffer,
+    delegateAgreement,
+}) {
+    const { creds, hireAgreementId, chatId, steps, inputArtifactIds } = input;
+    if (!steps.length)
+        throw new Error('steps must not be empty');
+    const myAgreements = (await deps.getMyAgreements({}, creds));
+    let offersCache = null;
+    const provisioned = [];
+    const pendingApprovals = [];
+    for (const step of steps) {
+        const existing = findExistingWorkerDelegation(hireAgreementId, step.assigneeId, myAgreements);
+        if (existing?.agreementId) {
+            provisioned.push({
+                stepId: step.stepId,
+                order: step.order,
+                agreementId: existing.agreementId,
+                assigneeId: step.assigneeId,
+                description: step.description,
+                provisionMethod: 'existing',
+                status: 'active',
+            });
+            continue;
+        }
+        if (step.offerAgreementId) {
+            const claimed = await deps.claimOffer(step.offerAgreementId, creds);
+            const agreementId = claimed.agreementId;
+            const status = isActiveAgreement(claimed)
+                ? 'active'
+                : 'pending_approval';
+            if (status === 'pending_approval')
+                pendingApprovals.push(agreementId);
+            provisioned.push({
+                stepId: step.stepId,
+                order: step.order,
+                agreementId,
+                assigneeId: step.assigneeId,
+                description: step.description,
+                provisionMethod: 'claim',
+                status,
+            });
+            continue;
+        }
+        if (!offersCache) {
+            offersCache = await deps.pullOffers({ limit: 100 }, creds);
+        }
+        const openOffer = findOpenOfferForAgent(step.assigneeId, offersCache);
+        if (openOffer?.agreementId) {
+            const claimed = await deps.claimOffer(openOffer.agreementId, creds);
+            const agreementId = claimed.agreementId;
+            const status = isActiveAgreement(claimed)
+                ? 'active'
+                : 'pending_approval';
+            if (status === 'pending_approval')
+                pendingApprovals.push(agreementId);
+            provisioned.push({
+                stepId: step.stepId,
+                order: step.order,
+                agreementId,
+                assigneeId: step.assigneeId,
+                description: step.description,
+                provisionMethod: 'claim',
+                status,
+            });
+            continue;
+        }
+        if (!chatId?.trim()) {
+            throw new Error(`No standing offer found for ${step.assigneeId} and chatId is required to propose a delegation under the hire`);
+        }
+        const delegated = await deps.delegateAgreement({
+            description: step.description,
+            executorId: step.assigneeId,
+            chatId: chatId.trim(),
+            parentAgreementId: hireAgreementId,
+            agreementDescription: `Relay step ${step.stepId}: ${step.description}`,
+            lifecycle: 'count-bound',
+            maxExecutions: 50,
+            price: 0,
+        }, creds);
+        const agreementId = delegated.agreementId;
+        const status = isActiveAgreement(delegated)
+            ? 'active'
+            : 'pending_approval';
+        if (status === 'pending_approval')
+            pendingApprovals.push(agreementId);
+        provisioned.push({
+            stepId: step.stepId,
+            order: step.order,
+            agreementId,
+            assigneeId: step.assigneeId,
+            description: step.description,
+            provisionMethod: 'delegate',
+            status,
+        });
+    }
+    provisioned.sort((a, b) => a.order - b.order);
+    const payload = {
+        inputArtifactIds,
+        steps: provisioned.map(({ stepId, order, agreementId, assigneeId, description }) => ({
+            stepId,
+            order,
+            agreementId,
+            assigneeId,
+            description,
+        })),
+    };
+    const readyForKickoff = pendingApprovals.length === 0 &&
+        provisioned.every((s) => s.status === 'active');
+    return {
+        payload,
+        steps: provisioned,
+        pendingApprovals,
+        readyForKickoff,
+    };
+}

package/dist/types.d.ts

@@ -173,5 +173,13 @@ export interface MessageMetadata {
     agreement?: Record<string, unknown> | null;
     operation?: string | null;
     agreementId?: string | null;
+    /**
+     * Message send time from the wire payload (ZIG-860). The live-path inbox
+     * watermark ack (AgentHost, ZIG-832 P4) needs it — without a timestamp the
+     * ack never fires and catch-up re-delivers the chat's whole backlog after a
+     * host eviction, re-running already-answered goals.
+     */
+    timestamp?: string;
+    sentTimestamp?: string;
 }
 export type MessageHandler = (text: string, metadata: MessageMetadata) => Promise<void>;

package/dist/websocket/WebSocketClient.js

@@ -109,6 +109,15 @@ export class WebSocketClient {
         this.socket.on('error', (error) => {
             runtimeLog.error(this.label, `Socket.IO error: ${String(error)}`);
         });
+        // ZIG-860: the send path is fire-and-forget (no ack callback), so the
+        // backend's structured rejection is the ONLY failure signal. Not listening
+        // made every rejected send silent — an agent's message just vanished (the
+        // a2a schema bug hid behind exactly this). Log loudly; delivery recovery
+        // stays with the inbox/catch-up machinery.
+        this.socket.on('chat:error', (payload) => {
+            const p = (payload ?? {});
+            runtimeLog.error(this.label, `chat:error [${p['code'] ?? 'UNKNOWN'}] chatId=${p['chatId'] ?? '-'} messageId=${p['messageId'] ?? '-'}: ${p['message'] ?? ''}`);
+        });
     }
     connectAsync(timeout = 10_000) {
         if (this.socket?.connected)
@@ -191,7 +200,7 @@ export class WebSocketClient {
         const agreement = p['agreement'] ?? null;
         const operation = p['operation'] ?? null;
         const agreementId = p['agreementId'] ?? null;
-        runtimeLog.info(this.label, `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`);
+        runtimeLog.info(this.label, `[wire-debug] incoming chatId=${chatId} sender=${senderId} content_type=${p['content_type'] ?? p['contentType'] ?? '<none>'} entryType=${p['entryType'] ?? '<none>'} ts=${typeof p['timestamp']}/${typeof p['sentTimestamp']} keys=${Object.keys(p).join(',')} task?=${task ? `taskId=${task['taskId']} state=${task['state']}` : 'no'} agreement?=${agreement ? `agreementId=${agreement['agreementId']} status=${agreement['status']}` : 'no'} operation?=${operation ?? 'no'}`);
         const metadata = {
             chatId,
             messageId: typeof p['messageId'] === 'string' ? p['messageId'] : undefined,
@@ -208,6 +217,11 @@ export class WebSocketClient {
             agreement,
             operation,
             agreementId,
+            // ZIG-860: carry the send time through — the live-path watermark ack
+            // (AgentHost, ZIG-832 P4) reads it, and dropping it here meant the ack
+            // never fired for any live message.
+            timestamp: typeof p['timestamp'] === 'string' ? p['timestamp'] : undefined,
+            sentTimestamp: typeof p['sentTimestamp'] === 'string' ? p['sentTimestamp'] : undefined,
         };
         await this.messageHandler(p['text'], metadata);
     }

package/package.json

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

package/dist/http/ScopeClient.d.ts

@@ -1,37 +0,0 @@
-import 'dotenv/config';
-export type ScopeKind = 'chat' | 'agreement' | 'task' | 'counterparty';
-export interface PartyRef {
-    id: string;
-    role: 'payer' | 'provider' | 'creator' | 'proposedTo' | 'providerPrincipal';
-}
-export interface ScopeResult {
-    via: {
-        kind: ScopeKind;
-        id: string;
-    };
-    agent: string;
-    accessible: {
-        chats: string[];
-        agreements: string[];
-        tasks: string[];
-        counterparties: PartyRef[];
-    };
-    permissions: string[];
-}
-/**
- * Client for `GET /scope?via=<kind>:<id>`. Returns the access graph reachable
- * from an entry point for the impersonated agent. Used by `runTurn` to
- * bootstrap "what does my current session-key resolve to" before fanning out
- * to primitive reads.
- */
-export declare class ScopeClient {
-    private readonly operatorKey;
-    private readonly agentId?;
-    /**
-     * @param operatorKey Agent-scoped or fleet operator key.
-     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
-     */
-    constructor(operatorKey: string, agentId?: string);
-    get(kind: ScopeKind, id: string): Promise<ScopeResult>;
-    private _headers;
-}

package/dist/http/ScopeClient.js

@@ -1,40 +0,0 @@
-import 'dotenv/config';
-import { getBackendUrl } from '../utils/urlUtils.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
-/**
- * Client for `GET /scope?via=<kind>:<id>`. Returns the access graph reachable
- * from an entry point for the impersonated agent. Used by `runTurn` to
- * bootstrap "what does my current session-key resolve to" before fanning out
- * to primitive reads.
- */
-export class ScopeClient {
-    operatorKey;
-    agentId;
-    /**
-     * @param operatorKey Agent-scoped or fleet operator key.
-     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
-     */
-    constructor(operatorKey, agentId) {
-        if (!operatorKey)
-            throw new Error('ScopeClient: operatorKey is required');
-        this.operatorKey = operatorKey;
-        this.agentId = agentId;
-    }
-    async get(kind, id) {
-        if (!id)
-            throw new Error('ScopeClient.get: id is required');
-        const url = new URL(`${getBackendUrl()}/scope`);
-        url.searchParams.set('via', `${kind}:${id}`);
-        const res = await fetch(url.toString(), { headers: this._headers() });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            throw new Error(`ScopeClient.get ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
-        }
-        return (await res.json());
-    }
-    _headers() {
-        return buildOperatorHeaders(this.operatorKey, this.agentId, {
-            'content-type': 'application/json',
-        });
-    }
-}