@ziggs-ai/api-client 0.1.24 → 0.1.26

package/dist/http/AgreementClient.d.ts

@@ -17,7 +17,12 @@ export interface ProposeTerms {
     agreementDescription?: string;
     parentAgreementId?: string;
     parentTaskId?: string;
-    payerId?: string;
+    /**
+     * Who does the work. Required on direct proposals (your own id = you offer;
+     * the proposedTo id = you commission the recipient); forbidden on
+     * broadcasts. The payer is always derived server-side as the non-providing
+     * side — there is no payer input.
+     */
     providerId?: string;
     plan?: unknown;
     planReviewTiming?: PlanReviewTiming;
@@ -146,6 +151,12 @@ export declare function revokeAgreement(agreementId: string, creds: Creds): Prom
     ok: boolean;
     agreement: Agreement;
 }>;
+/** ZIG-832: mark an agreement fulfilled (complete). A provider closing its own
+ * delivered work — party-gated server-side. */
+export declare function fulfillAgreement(agreementId: string, creds: Creds): Promise<{
+    ok: boolean;
+    agreement: Agreement;
+}>;
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
  * - open link invite (`engagementKind: link`, proposedTo everyone)
@@ -200,6 +211,10 @@ export declare class AgreementClient {
         ok: boolean;
         agreement: Agreement;
     }>;
+    fulfill(id: string): Promise<{
+        ok: boolean;
+        agreement: Agreement;
+    }>;
     claimAgreement(id: string): Promise<{
         ok: boolean;
         agreement: Agreement;

package/dist/http/AgreementClient.js

@@ -370,6 +370,26 @@ export async function revokeAgreement(agreementId, creds) {
     }
     return data;
 }
+/** ZIG-832: mark an agreement fulfilled (complete). A provider closing its own
+ * delivered work — party-gated server-side. */
+export async function fulfillAgreement(agreementId, creds) {
+    if (!agreementId)
+        throw new Error('agreementId is required to fulfill');
+    assertCreds(creds, 'agreement fulfillment');
+    const res = await fetch(`${getAgreementBaseUrl()}/${encodeURIComponent(agreementId)}/fulfill`, {
+        method: 'POST',
+        headers: buildHeaders(creds),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throwApiError(res, body, `Agreement fulfillment failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    if (!data?.['agreement']) {
+        throw new Error('Invalid response: expected { ok, agreement } from POST /agreements/:id/fulfill');
+    }
+    return data;
+}
 /**
  * Claim an open agreement (ZIG-524 phase 2 / ZIG-525):
  * - open link invite (`engagementKind: link`, proposedTo everyone)
@@ -596,6 +616,7 @@ export class AgreementClient {
     get(id) { return getAgreement(id, this.creds); }
     create(data) { return createAgreement(data, this.creds); }
     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); }

package/dist/http/ContextDiscoveryClient.d.ts

@@ -11,6 +11,16 @@ export interface ContextReachDescriptor {
     parentGrantId: string | null;
     createdAt: string;
 }
+/** Labels-only pointer to context the agent could request access to (P4). */
+export interface DiscoverableItem {
+    type: 'chat';
+    label: string;
+    scopeRef: {
+        kind: 'chat' | 'agreement' | 'org';
+        id: string;
+    };
+    orgId: string;
+}
 /**
  * ZIG-412 discovery — scope descriptors only, no content.
  */
@@ -24,4 +34,11 @@ export declare class ContextDiscoveryClient {
      */
     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.
+     * Defensively re-shapes each row to the whitelist (type/label/scopeRef/orgId)
+     * so an over-broad server response can never leak content/tokens through here.
+     */
+    discoverGrantable(): Promise<DiscoverableItem[]>;
 }

package/dist/http/ContextDiscoveryClient.js

@@ -31,4 +31,26 @@ export class ContextDiscoveryClient {
         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.
+     * Defensively re-shapes each row to the whitelist (type/label/scopeRef/orgId)
+     * so an over-broad server response can never leak content/tokens through here.
+     */
+    async discoverGrantable() {
+        const res = await fetch(`${this.baseUrl}/context/discovery/available`, {
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw new Error(`ContextDiscoveryClient.discoverGrantable ${res.status} ${body.slice(0, 200)}`);
+        }
+        const parsed = JSON.parse(body);
+        return (parsed.items ?? []).map((i) => ({
+            type: i.type,
+            label: i.label,
+            scopeRef: { kind: i.scopeRef.kind, id: i.scopeRef.id },
+            orgId: i.orgId,
+        }));
+    }
 }

package/dist/http/ContextGrantsClient.d.ts

@@ -1,23 +1,20 @@
 import 'dotenv/config';
+import type { GrantView } from './grants.js';
 export type ContextGrantScopeKind = 'chat' | 'agreement' | 'org';
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface ContextGrantScope {
     kind: ContextGrantScopeKind;
     id: string;
 }
-export interface ContextGrantRecord {
-    grantId: string;
-    issuerId: string;
-    holderId: string;
-    scopeKind: ContextGrantScopeKind;
-    scopeId: string;
-    temporal: ContextTemporal;
-    watermarkAt: string;
-    parentGrantId: string | null;
-    expiresAt: string | null;
-    revoked: boolean;
-    createdAt: string;
-}
+/**
+ * @deprecated ZIG-646 — context grants now serialise to the canonical
+ * {@link GrantView} like every other rail. This alias previously declared a
+ * flat `scopeKind`/`scopeId` + `revoked` shape that the backend never actually
+ * emitted (it sends nested `scope: { kind, id }` and folds temporal/watermark
+ * into `caveats`), so reads like `record.scopeKind` were always `undefined`.
+ * Use `GrantView`; this remains only so existing name-imports keep resolving.
+ */
+export type ContextGrantRecord = GrantView;
 export interface IssueContextGrantInput {
     holderId: string;
     scope: ContextGrantScope;
@@ -31,6 +28,17 @@ export interface DelegateContextGrantInput {
     expiresAt?: string | null;
     watermarkAt?: string;
 }
+/** Delegating your own principal's grant mints immediately; passing a grant
+ *  whose original owner is a different party opens a request that owner
+ *  approves — no grant is minted until then. */
+export type DelegateContextGrantResult = {
+    status: 'granted';
+    grant: GrantView;
+} | {
+    status: 'pending_approval';
+    agreementId: string;
+    ownerId?: string;
+};
 /**
  * ZIG-411 context grant management — list / issue / delegate / revoke.
  */
@@ -43,8 +51,8 @@ export declare class ContextGrantsClient {
      * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
-    issueGrant(input: IssueContextGrantInput): Promise<ContextGrantRecord>;
-    delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<ContextGrantRecord>;
+    issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
+    delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<DelegateContextGrantResult>;
     revokeGrant(grantId: string): Promise<{
         status: string;
         revokedCount?: number;

package/dist/http/ContextGrantsClient.js

@@ -74,10 +74,19 @@ export class ContextGrantsClient {
             throwApiError(res, body, `delegateGrant failed: ${res.status} ${res.statusText}`);
         }
         const parsed = JSON.parse(body);
+        // Re-granting a grant whose original owner is a different party does not
+        // mint — it opens a request that owner must approve.
+        if (parsed.status === 'pending_approval' && parsed.agreementId) {
+            return {
+                status: 'pending_approval',
+                agreementId: parsed.agreementId,
+                ownerId: parsed.ownerId,
+            };
+        }
         if (!parsed.grant?.grantId) {
-            throw new Error('Invalid response: expected { grant } from POST /context/grants/:id/delegate');
+            throw new Error('Invalid response: expected { grant } or { status: "pending_approval" } from POST /context/grants/:id/delegate');
         }
-        return parsed.grant;
+        return { status: 'granted', grant: parsed.grant };
     }
     async revokeGrant(grantId) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(grantId)}`, {

package/dist/http/MessagesClient.js

@@ -35,7 +35,11 @@ export class MessagesClient {
         const res = await fetch(url.toString(), { headers: this._headers() });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
-            throw new Error(`MessagesClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+            const err = new Error(`MessagesClient.list ${res.status} ${res.statusText} ${body.slice(0, 200)}`);
+            // Callers branch on the HTTP status (404 = chat deleted/not visible)
+            // without parsing the message string.
+            err.status = res.status;
+            throw err;
         }
         return (await res.json());
     }

package/dist/http/TaskClient.d.ts

@@ -8,6 +8,8 @@ export interface CreateTaskData {
     idempotencyKey?: string;
     /** Explicit delegation target (ZIG-586) — must be a party to the agreement; validated server-side. */
     assigneeId?: string;
+    /** ZIG-734: prior-step artifact handles consumed as structured input links. */
+    inputArtifactIds?: string[];
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
@@ -26,6 +28,7 @@ export interface PlanReplaceStep {
     order: number;
 }
 export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<Task>;
+export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<Task>;
 export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<Task>;
 export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<Task>;
 export interface ListTasksOptions {
@@ -63,6 +66,7 @@ export declare class TaskClient {
     cancelTask(taskId: string): Promise<Task>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<Task>;
+    updateTaskPlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
     reportTask(taskId: string, message?: string): Promise<Task>;
     setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task>;
     listTasks(options?: ListTasksOptions): Promise<ListTasksResult>;

package/dist/http/TaskClient.js

@@ -117,7 +117,38 @@ export async function getActiveTasksForAgent(agentId, creds) {
         throwApiError(res, body, `Get active tasks for agent failed: ${res.status} ${res.statusText}`);
     }
     const data = await res.json().catch(() => null);
-    return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+    const fromAgent = Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+    if (fromAgent.length > 0)
+        return fromAgent;
+    // Fallback when /agents/:id/tasks is empty but party-agreement tasks exist (ZIG-802).
+    return getActiveTasksForAgentViaPartyAgreements(agentId, creds);
+}
+async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
+    const { listAgreements } = await import('./AgreementClient.js');
+    const agreements = await listAgreements({ status: 'active' }, creds);
+    const partyIds = agreements
+        .filter((a) => {
+        const p = a.parties ?? {};
+        return (p.provider === agentId ||
+            p.providerAgent === agentId ||
+            p.creator === agentId ||
+            p.payer === agentId);
+    })
+        .map((a) => a.agreementId)
+        .filter(Boolean);
+    if (partyIds.length === 0)
+        return [];
+    const lists = await Promise.all(partyIds.map(async (aid) => {
+        const url = new URL(`${getBackendUrl()}/agreements/${encodeURIComponent(aid)}/tasks`);
+        url.searchParams.set('state', 'active');
+        const res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });
+        if (!res.ok)
+            return [];
+        const data = await res.json().catch(() => null);
+        return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
+    }));
+    const merged = lists.flat();
+    return merged.filter((t) => !t.assigneeId || t.assigneeId === agentId);
 }
 // Backend deliberately has no `/chats/:id/tasks` route — it's composable
 // from links → per-agreement tasks. We do the composition here so callers
@@ -205,6 +236,29 @@ export async function replaceTaskPlan(taskId, steps, creds) {
         throw new Error('Invalid response: task data not found');
     return task;
 }
+export async function updateTaskPlanStep(taskId, stepId, status, result, creds) {
+    if (!taskId)
+        throw new Error('updateTaskPlanStep: taskId is required');
+    if (!stepId)
+        throw new Error('updateTaskPlanStep: stepId is required');
+    if (!status)
+        throw new Error('updateTaskPlanStep: status is required');
+    assertCreds(creds, 'plan step update');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ stepId, status, ...(result !== undefined && { result }) }),
+    });
+    if (!res.ok) {
+        const responseBody = await res.text().catch(() => '');
+        throwApiError(res, responseBody, `Plan step update failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const task = extractTask(data);
+    if (!task)
+        throw new Error('Invalid response: task data not found');
+    return task;
+}
 // ---------------------------------------------------------------------------
 // Reporting & satisfaction
 // ---------------------------------------------------------------------------
@@ -322,6 +376,7 @@ export class TaskClient {
     cancelTask(taskId) { return cancelTask(taskId, this.creds); }
     getSubtasks(parentTaskId) { return getSubtasks(parentTaskId, this.creds); }
     replaceTaskPlan(taskId, steps) { return replaceTaskPlan(taskId, steps, this.creds); }
+    updateTaskPlanStep(taskId, stepId, status, result) { return updateTaskPlanStep(taskId, stepId, status, result, this.creds); }
     reportTask(taskId, message) { return reportTask(taskId, message, this.creds); }
     setTaskSatisfaction(taskId, satisfaction) { return setTaskSatisfaction(taskId, satisfaction, this.creds); }
     listTasks(options) { return listTasks(options ?? {}, this.creds); }

package/dist/http/grants.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ZIG-646: the one grant shape the backend presents on the wire, mirrored for
+ * SDK consumers. Context, connection, and payment grants all serialise to this
+ * exact object (see backend `src/grants/grant-view.ts`), so a caller reads one
+ * shape to answer "what grants exist, and are they live?" regardless of rail.
+ *
+ * `scope.kind` names the rail's resource: context grants keep chat/agreement/org;
+ * a connection grant is `connection` + connectionId; a payment grant is
+ * `wallet` + the root wallet id. A grant's bounds are its `caveats` — for
+ * context grants (which have no caveat column) the temporal mode and read
+ * watermark are presented as `temporal` / `watermark_at` caveats.
+ */
+export type GrantHealth = 'active' | 'expired' | 'revoked';
+export type GrantScopeKind = 'chat' | 'agreement' | 'org' | 'connection' | 'wallet';
+export interface GrantScopeView {
+    kind: GrantScopeKind;
+    id: string;
+}
+export interface GrantCaveatView {
+    type: string;
+    value: unknown;
+}
+export interface GrantView {
+    grantId: string;
+    issuerId: string;
+    holderId: string;
+    parentGrantId: string | null;
+    agreementId: string | null;
+    scope: GrantScopeView;
+    caveats: GrantCaveatView[];
+    revoked: boolean;
+    /** ISO-8601, or null for no expiry. */
+    expiresAt: string | null;
+    /** ISO-8601. */
+    createdAt: string;
+    health: GrantHealth;
+}
+/** Value of the first caveat of `type` on a grant, or undefined. */
+export declare function grantCaveat(grant: GrantView, type: string): unknown | undefined;

package/dist/http/grants.js

@@ -0,0 +1,4 @@
+/** Value of the first caveat of `type` on a grant, or undefined. */
+export function grantCaveat(grant, type) {
+    return grant.caveats.find((c) => c.type === type)?.value;
+}

package/dist/http/index.d.ts

@@ -14,6 +14,8 @@ export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { ContextReachDescriptor } from './ContextDiscoveryClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, } from './ContextGrantsClient.js';
+export { grantCaveat } from './grants.js';
+export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/http/index.js

@@ -8,6 +8,7 @@ export { ScopeClient } from './ScopeClient.js';
 export { ContextReadClient } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
+export { grantCaveat } from './grants.js';
 export { AgentSearchClient } from './AgentSearchClient.js';
 export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';

package/dist/websocket/WebSocketClient.d.ts

@@ -27,6 +27,12 @@ export interface ResourceEvent {
     taskId?: string;
     change?: 'created' | 'updated' | 'state-changed';
     reason?: string;
+    /**
+     * Principal whose action produced the event, when the backend knows it.
+     * Hosts drop events the receiving agent itself caused — its own writes
+     * aren't news to it.
+     */
+    actorId?: string;
 }
 export type ResourceEventHandler = (event: ResourceEvent) => void | Promise<void>;
 export interface SendOptions {

package/package.json

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