@ziggs-ai/api-client 0.13.0 → 0.14.1

package/dist/http/IntroductionsClient.d.ts

@@ -0,0 +1,71 @@
+/** What became of one hello. `expired` is derived by the server, not stored. */
+export type IntroductionStatus = 'open' | 'redeemed' | 'declined' | 'revoked' | 'expired';
+export type IntroductionOutcome = 'link_pending' | 'already_teammates' | 'already_linked';
+export interface IntroductionFrom {
+    orgId: string;
+    agentId: string | null;
+    agentCreatedAt?: string | null;
+    claimedLabel?: {
+        text: string;
+        selfChosen: boolean;
+        verified: boolean;
+    };
+    /**
+     * Same text as claimedLabel.text. Not identity — anyone can pick it.
+     */
+    label: string;
+}
+export interface IntroductionView {
+    token: string;
+    status: IntroductionStatus;
+    outcome: IntroductionOutcome | null;
+    notice?: string;
+    from: IntroductionFrom;
+    venue: string | null;
+    venueRef: string | null;
+    note: string | null;
+    agreementId: string | null;
+    redeemedBy: {
+        agentId: string | null;
+        orgId: string | null;
+    } | null;
+    expiresAt: string;
+    /** The public page the string points at. This is what you hand over. */
+    url: string;
+    /**
+     * Returned to a redeemer only: the two ids the meeting is now worth, and what
+     * each is for. `agentId` is where messages go; `principal` is who can be a
+     * party to an agreement. Passing one where the other belongs is refused as if
+     * the agent did not exist, which is the wall this field exists to remove.
+     */
+    counterparty?: {
+        principal: string;
+        agentId: string | null;
+        label: string;
+        nextStep: string;
+    };
+}
+export interface MintIntroductionInput {
+    venue?: string;
+    venueRef?: string;
+    note?: string;
+}
+/**
+ * Introduction tokens — the one object to exchange when you meet an
+ * agent somewhere Ziggs does not own.
+ *
+ * The token carries no authority, which is why minting one is free: it widens
+ * nobody's reach. Redeeming one stages a link proposal the two humans sign.
+ */
+export declare class IntroductionsClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    mint(input?: MintIntroductionInput): Promise<IntroductionView>;
+    redeem(token: string): Promise<IntroductionView>;
+    decline(token: string): Promise<IntroductionView>;
+    revoke(token: string): Promise<IntroductionView>;
+    listMine(limit?: number): Promise<IntroductionView[]>;
+    private call;
+}

package/dist/http/IntroductionsClient.js

@@ -0,0 +1,54 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * Introduction tokens — the one object to exchange when you meet an
+ * agent somewhere Ziggs does not own.
+ *
+ * The token carries no authority, which is why minting one is free: it widens
+ * nobody's reach. Redeeming one stages a link proposal the two humans sign.
+ */
+export class IntroductionsClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey) {
+            throw new Error('IntroductionsClient: operatorKey is required');
+        }
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    async mint(input = {}) {
+        return this.call('POST', '/introductions', input, 'mint');
+    }
+    async redeem(token) {
+        return this.call('POST', `/introductions/${encodeURIComponent(token)}/redeem`, {}, 'redeem');
+    }
+    async decline(token) {
+        return this.call('POST', `/introductions/${encodeURIComponent(token)}/decline`, {}, 'decline');
+    }
+    async revoke(token) {
+        return this.call('DELETE', `/introductions/${encodeURIComponent(token)}`, undefined, 'revoke');
+    }
+    async listMine(limit) {
+        const query = limit != null ? `?limit=${encodeURIComponent(String(limit))}` : '';
+        return this.call('GET', `/introductions${query}`, undefined, 'listMine');
+    }
+    async call(method, path, body, label) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                ...buildOperatorHeaders(this.operatorKey, this.agentId),
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `IntroductionsClient.${label} failed: ${res.status}`);
+        }
+        return JSON.parse(text);
+    }
+}

package/dist/http/TaskClient.d.ts

@@ -13,6 +13,7 @@ export interface TaskWriteConfirm {
     structureChanged?: boolean;
     stepId?: string;
     stepStatus?: string;
+    patchedCount?: number;
     resultRecorded?: boolean;
     terminalState?: string;
     [key: string]: unknown;
@@ -23,6 +24,20 @@ export interface TaskWriteConfirm {
  * subcontract inputs rather than teaching those routes to keep one.
  */
 export type PlanReviewTiming = 'with_proposal' | 'before_execution';
+export interface CreateTaskGraphNodeData {
+    nodeId: string;
+    agreementId: string;
+    description: string;
+    title?: string;
+    assigneeId?: string;
+    waitsOn?: string[];
+    joinKind?: 'all' | 'any';
+}
+export interface CreateTaskGraphData {
+    nodes: CreateTaskGraphNodeData[];
+    inputArtifactIds?: string[];
+    review?: 'before_execution';
+}
 export interface CreateTaskData {
     description: string;
     /**
@@ -55,6 +70,8 @@ export interface CreateTaskData {
      * the shape in its own control flow where nothing else can see it.
      */
     waitsOn?: string[];
+    /** Atomically declare a native work graph beneath the returned root task. */
+    graph?: CreateTaskGraphData;
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;
@@ -91,6 +108,13 @@ export interface PlanReplaceStep {
     result?: unknown;
 }
 export declare function replaceTaskPlan(taskId: string, steps: PlanReplaceStep[], creds: Creds): Promise<TaskWriteConfirm>;
+/** Named-step progress — only the listed steps change. */
+export type PlanStepPatch = {
+    stepId: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'skipped';
+    result?: unknown;
+};
+export declare function updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[], creds: Creds): Promise<TaskWriteConfirm>;
 export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function reportTask(taskId: string, message: string | undefined, creds: Creds): Promise<TaskWriteConfirm>;
 export declare function setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative', creds: Creds): Promise<TaskWriteConfirm>;
@@ -135,6 +159,7 @@ export declare class TaskClient {
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     replaceTaskPlan(taskId: string, steps: PlanReplaceStep[]): Promise<TaskWriteConfirm>;
     updateTaskPlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<TaskWriteConfirm>;
+    updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[]): Promise<TaskWriteConfirm>;
     reportTask(taskId: string, message?: string): Promise<TaskWriteConfirm>;
     setTaskSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<TaskWriteConfirm>;
     listTasks(options?: ListTasksOptions): Promise<ListTasksResult>;

package/dist/http/TaskClient.js

@@ -55,6 +55,7 @@ function extractWriteConfirm(data) {
                 : {}),
             ...(typeof d['stepId'] === 'string' ? { stepId: d['stepId'] } : {}),
             ...(typeof d['stepStatus'] === 'string' ? { stepStatus: d['stepStatus'] } : {}),
+            ...(typeof d['patchedCount'] === 'number' ? { patchedCount: d['patchedCount'] } : {}),
             ...(d['resultRecorded'] === true ? { resultRecorded: true } : {}),
             ...(typeof d['terminalState'] === 'string'
                 ? { terminalState: d['terminalState'] }
@@ -152,10 +153,29 @@ export async function getActiveTasksForAgent(agentId, creds) {
     const data = await res.json().catch(() => null);
     const fromAgent = Array.isArray(data?.['tasks']) ? data['tasks'] : [];
     if (fromAgent.length > 0)
-        return fromAgent;
+        return workable(fromAgent);
     // Fallback when /agents/:id/tasks is empty but party-agreement tasks exist.
     return getActiveTasksForAgentViaPartyAgreements(agentId, creds);
 }
+/**
+ * Drop the tasks the platform created but deliberately did not deliver.
+ *
+ * `heldByDeps` is a DELIVERY condition, not a task state: a task waiting on its
+ * `waitsOn` edges is genuinely `active`, so `?state=active` returns it and the
+ * assignee's own work list hands over a task nobody woke it for. Every caller of
+ * this function is asking "what can I act on now", and for a withheld row the
+ * answer is nothing — `updateTaskState` refuses it with `dependencies_unmet`.
+ * Two of AgentHost's three callers do worse than waste a wake: the needs gate
+ * and the unmet-access sweep both FAIL the tasks they find, so a withheld node
+ * was one missing grant away from being failed before its turn came.
+ *
+ * Filtered here rather than at `/agents/:id/tasks`, which is also the route the
+ * UI lists an agent's work with — a person looking at the graph should see the
+ * withheld node sitting there waiting, which is the whole point of a join.
+ */
+function workable(tasks) {
+    return tasks.filter((t) => t.heldByDeps !== true);
+}
 async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
     const { listAgreements } = await import('./AgreementClient.js');
     const agreements = await listAgreements({ status: 'active' }, creds);
@@ -175,7 +195,7 @@ async function getActiveTasksForAgentViaPartyAgreements(agentId, creds) {
         return Array.isArray(data?.['tasks']) ? data['tasks'] : [];
     }));
     const merged = lists.flat();
-    return merged.filter((t) => !t.assigneeId || t.assigneeId === agentId);
+    return workable(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
@@ -263,6 +283,34 @@ export async function replaceTaskPlan(taskId, steps, creds) {
         throw new Error('Invalid response: task write confirm not found');
     return confirm;
 }
+export async function updateTaskPlanSteps(taskId, patches, creds) {
+    if (!taskId)
+        throw new Error('updateTaskPlanSteps: taskId is required');
+    if (!patches || !Array.isArray(patches) || patches.length === 0) {
+        throw new Error('updateTaskPlanSteps: patches must name at least one step');
+    }
+    for (const patch of patches) {
+        if (!patch?.stepId)
+            throw new Error('updateTaskPlanSteps: each patch needs a stepId');
+        if (!patch?.status)
+            throw new Error('updateTaskPlanSteps: each patch needs a status');
+    }
+    assertCreds(creds, 'plan step patch');
+    const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
+        method: 'PATCH',
+        headers: buildHeaders(creds),
+        body: JSON.stringify({ patches }),
+    });
+    if (!res.ok) {
+        const responseBody = await res.text().catch(() => '');
+        throwApiError(res, responseBody, `Plan step patch failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json().catch(() => null);
+    const confirm = extractWriteConfirm(data);
+    if (!confirm)
+        throw new Error('Invalid response: task write confirm not found');
+    return confirm;
+}
 export async function updateTaskPlanStep(taskId, stepId, status, result, creds) {
     if (!taskId)
         throw new Error('updateTaskPlanStep: taskId is required');
@@ -406,6 +454,7 @@ export class TaskClient {
     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); }
+    updateTaskPlanSteps(taskId, patches) { return updateTaskPlanSteps(taskId, patches, 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/index.d.ts

@@ -11,6 +11,8 @@ export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, par
 export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
+export { IntroductionsClient } from './IntroductionsClient.js';
+export type { IntroductionView, IntroductionFrom, IntroductionStatus, IntroductionOutcome, MintIntroductionInput, } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';

package/dist/http/index.js

@@ -9,6 +9,7 @@ export { ArtifactsClient,
 artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
+export { IntroductionsClient } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 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, partySideIds, partyActorIds, } from './types.js';
 export type { PrincipalPresentation } from './types.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 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, partySideIds, partyActorIds, } from './types.js';
 export { getBackendUrl } from './utils/urlUtils.js';

package/dist/types.d.ts

@@ -79,6 +79,16 @@ export interface Task {
      * from "nobody has picked it up" — this one is waiting on purpose.
      */
     heldByDeps?: boolean;
+    joinKind?: 'all' | 'any';
+    graph?: {
+        nodes: Array<{
+            nodeId: string;
+            taskId: string;
+        }>;
+        review?: 'before_execution';
+    } | null;
+    graphNodeId?: string | null;
+    heldByGraphReview?: boolean;
     plan?: {
         steps?: PlanStep[];
     };
@@ -148,6 +158,8 @@ export interface AgreementApprovalEntry {
     role?: string;
     status?: string;
     respondedAt?: string | null;
+    /** Why a pending slot is held (e.g. 'formation-gate', 'contact-basis'), when the server said. */
+    heldReason?: string | null;
 }
 export interface Agreement {
     agreementId: string;
@@ -163,6 +175,17 @@ export interface Agreement {
     money?: {
         price?: number | null;
         paymentStatus?: string;
+        transactionId?: string | null;
+        /**
+         * Ledger hold for this agreement, or null if paymentStatus says held but
+         * no hold row exists. Amount is cents. Never includes a wallet id.
+         */
+        held?: {
+            amount: number;
+            currency: string;
+            state: 'held' | 'released' | 'refunded';
+            agreementId: string;
+        } | null;
     };
     lifecycle?: string;
     expiresAt?: string;

package/package.json

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

package/dist/relay/provisionRelayWorkers.d.ts

@@ -1,119 +0,0 @@
-import type { Agreement, Creds } from '../types.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;
-    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';
-/**
- * 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[];
-}
-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;
-}
-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;
-/**
- * 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 {};