@ziggs-ai/api-client 0.20.0 → 0.22.0

package/dist/engagementGuide.js

@@ -0,0 +1,349 @@
+/**
+ * What to do with a piece of engagement, from records the caller already has.
+ *
+ * This is a receipt and a next-call pointer. It does not invent a worker
+ * protocol, a wake store, or a blocked task state. Waiting-on-person is a
+ * field on the receipt so a later human view can show waiting instead of
+ * active. A held graph is not work until deps release; failed or cancelled
+ * deps are not inputs. Withdraw is cancel on the root. A live hire does not
+ * take a second hire or an in-place amend.
+ */
+import { agreementBidCapability, agreementBuyCapability, agreementRequestCapability, agreementSubcontractCapability, } from './capabilities/agreementVerbs.js';
+import { nextCall } from './capabilities/nextCall.js';
+const TERMINAL_TASK = new Set(['completed', 'failed', 'cancelled']);
+function openTasksForAgreement(tasks, agreementId) {
+    return (tasks ?? []).filter((t) => t.agreementId === agreementId && !TERMINAL_TASK.has(t.state));
+}
+function assignedToMe(delivery, agentId) {
+    return Boolean(agentId) && delivery.assigneeId === agentId;
+}
+/** Same event twice, or a hire-room brief that already has an open task. */
+export function isEchoOrDuplicate(inbox, agentId) {
+    const mine = inbox.deliveries.filter((d) => assignedToMe(d, agentId));
+    const eventIds = mine.map((d) => d.eventId).filter(Boolean);
+    if (new Set(eventIds).size < eventIds.length)
+        return true;
+    for (const d of mine) {
+        if (d.kind === 'task-state' && d.taskId) {
+            const already = (inbox.tasksAwaitingMe ?? []).some((t) => t.taskId === d.taskId);
+            if (already)
+                return true;
+        }
+        if (d.kind === 'message' && d.agreementId) {
+            if (openTasksForAgreement(inbox.tasksAwaitingMe, d.agreementId).length > 0) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Assigned message under a live hire. Missing chat is not a skip — a fresh
+ * hire without a room still runs after access to that agreement is proven.
+ * An agrn- notification lane is not treated as a chat row.
+ */
+export function isHireWorkOrder(delivery, agentId, tasksAwaitingMe) {
+    if (!assignedToMe(delivery, agentId))
+        return false;
+    if (delivery.kind !== 'message')
+        return false;
+    if (!delivery.agreementId)
+        return false;
+    if (delivery.taskId)
+        return false;
+    if (openTasksForAgreement(tasksAwaitingMe, delivery.agreementId).length > 0) {
+        return false;
+    }
+    return true;
+}
+export function waitingOnFromTask(task) {
+    if (task.waitingOn?.id)
+        return task.waitingOn;
+    if (task.lastAct === 'question' && task.waitingOn?.id)
+        return task.waitingOn;
+    return task.waitingOn ?? null;
+}
+export function graphReleaseHonesty(task) {
+    const failedDepCount = (task.waitsOn ?? []).filter((id) => {
+        const state = task.depStates?.[id];
+        return state === 'failed' || state === 'cancelled';
+    }).length;
+    return {
+        ready: !task.heldByDeps,
+        heldByDeps: Boolean(task.heldByDeps),
+        failedDepsAreNotInputs: true,
+        failedDepCount,
+    };
+}
+export function liveHireChangedTerms(env) {
+    return {
+        kind: 'hire_terms',
+        outcome: 'unavailable',
+        summary: 'A live hire does not take a second hire or an in-place amend. Reuse the active agreement; changing terms is not on this surface.',
+        hireTerms: { secondHire: 'refused', amendLive: 'unavailable' },
+        next: nextCall(env, 'agreement_claim', undefined, 'a second hire on live terms is refused — reuse the active agreement', { outcome: 'unavailable' }),
+    };
+}
+/** Map a hire-formation 409 onto the refuse-second-hire receipt. */
+export function liveHireConflictFromStatus(env, status) {
+    if (status === 409)
+        return liveHireChangedTerms(env);
+    return null;
+}
+export function withdrawHeldGraph(env, rootTaskId) {
+    return {
+        kind: 'held',
+        outcome: 'pending',
+        taskId: rootTaskId,
+        summary: 'This graph is held. Withdraw is one act: cancel the root. Do not invent a blocked state.',
+        graph: {
+            ready: false,
+            heldByDeps: true,
+            failedDepsAreNotInputs: true,
+            failedDepCount: 0,
+        },
+        next: nextCall(env, 'task_cancel', { taskId: rootTaskId }, 'withdraw the held graph by cancelling the root'),
+    };
+}
+export function reminderHonesty(task, continuation) {
+    const limits = task.checkBack
+        ? `Remind at most ${task.checkBack.maxReminders} times, no sooner than every ${task.checkBack.everyMinutes} minutes.`
+        : 'This task has no reminder budget.';
+    const deadline = task.dueAt
+        ? ` At ${task.dueAt} post what you have and stop.`
+        : '';
+    if (continuation && !continuation.canScheduleWake) {
+        return {
+            kind: 'reminder',
+            outcome: 'unavailable',
+            taskId: task.taskId,
+            summary: `${limits}${deadline} This session cannot arm a wake — continue only by reading the inbox again. Do not infer a scheduler from the transport.`,
+        };
+    }
+    return {
+        kind: 'reminder',
+        outcome: 'ok',
+        taskId: task.taskId,
+        summary: `${limits}${deadline} Wake capability is whatever this host already reported — not the profile or the transport.`,
+    };
+}
+/**
+ * Formation receipt. Reuse a matching active agreement. Claim a listing
+ * and never counter it. Request when nothing listed fits. Direct only when
+ * they accept proposals. Subcontract under a parent you already hold.
+ * A second formation on a live hire is refused.
+ */
+export function formationGuide(env, input) {
+    const matchingId = input.matchingActive?.agreementId;
+    if (matchingId) {
+        return {
+            kind: 'reuse',
+            outcome: 'noop',
+            agreementId: matchingId,
+            summary: 'An active agreement already covers this work on matching terms. Reuse it. Do not form another, and do not counter a listing to replace it.',
+            next: nextCall(env, 'agreement_get', { agreementId: matchingId }, 'open the agreement you already hold'),
+        };
+    }
+    if (input.liveHire?.agreementId && input.wantsChangedTerms) {
+        return {
+            ...liveHireChangedTerms(env),
+            agreementId: input.liveHire.agreementId,
+        };
+    }
+    if (input.liveHire?.agreementId) {
+        return {
+            kind: 'reuse',
+            outcome: 'noop',
+            agreementId: input.liveHire.agreementId,
+            summary: 'You already hold a live hire with this party. Reuse it. Do not open a second formation.',
+            next: nextCall(env, 'agreement_get', { agreementId: input.liveHire.agreementId }, 'open the live hire you already hold'),
+        };
+    }
+    if (input.parentAgreementId) {
+        return {
+            kind: 'subcontract',
+            outcome: 'ok',
+            agreementId: input.parentAgreementId,
+            summary: 'Subcontracting under an active parent is its own rail. Name the worker and the slice. Do not open a second top-level hire.',
+            next: nextCall(env, 'agreement_subcontract', { parentAgreementId: input.parentAgreementId }, 'delegate this slice under the parent you hold', { definition: agreementSubcontractCapability }),
+        };
+    }
+    if (input.listing) {
+        const agreementId = input.listing === true ? undefined : input.listing.agreementId;
+        return {
+            kind: 'claim',
+            outcome: 'ok',
+            ...(agreementId ? { agreementId } : {}),
+            summary: 'Claim the posted listing. Listings are take-it-or-leave-it — never counter one. Do not buy past a listing that already fits.',
+            next: nextCall(env, 'agreement_claim', agreementId ? { agreementId } : undefined, 'claim this listing by agreementId — never counter it'),
+        };
+    }
+    if (input.counterparty && input.acceptsProposals === false) {
+        return {
+            kind: 'claim',
+            outcome: 'unavailable',
+            summary: 'This agent is claim-only and refuses a direct proposal. Find their listing and claim it. Do not buy, bid, or counter.',
+            next: nextCall(env, 'marketplace_view', undefined, 'find the listing this agent already posted'),
+        };
+    }
+    if (input.counterparty && input.acceptsProposals) {
+        const key = input.direction === 'bid' ? 'agreement_bid' : 'agreement_buy';
+        return {
+            kind: 'direct',
+            outcome: 'ok',
+            summary: 'No listing and they accept proposals. Go direct for these terms. Most published agents are claim-only — this path is the exception.',
+            next: nextCall(env, key, { counterparty: input.counterparty }, 'propose these terms to the named counterparty', { definition: key === 'agreement_bid' ? agreementBidCapability : agreementBuyCapability }),
+        };
+    }
+    return {
+        kind: 'request',
+        outcome: 'ok',
+        summary: 'Nothing listed fits. Post a request and let a claimer take it. Do not invent a duplicate formation or counter a listing that was not a fit.',
+        next: nextCall(env, 'agreement_request', undefined, 'post a request when nothing listed fits', { definition: agreementRequestCapability }),
+    };
+}
+/** Browse result: claim when rows exist, request when the board is empty. */
+export function marketplaceFormation(env, input) {
+    const ids = input.listingAgreementIds.filter(Boolean);
+    if (ids.length === 1) {
+        return formationGuide(env, { listing: { agreementId: ids[0] } });
+    }
+    if (ids.length > 1) {
+        return formationGuide(env, { listing: true });
+    }
+    return formationGuide(env, {});
+}
+/**
+ * Contact path. Same-org people are reachable under the scoped identity.
+ * An outside person needs an active link. A link is not a roster. An agent
+ * with a listing is claimed, not chatted into a hire.
+ */
+export function contactPath(env, input) {
+    const { partyKind, partyId, linked, listed, sameOrg } = input;
+    if (partyKind === 'person' && (linked || sameOrg)) {
+        return {
+            kind: 'contact',
+            outcome: 'ok',
+            summary: sameOrg && !linked
+                ? 'Same-org person: reach them under this scoped identity.'
+                : 'Linked person: open or continue the working room. A link does not reveal their org roster.',
+            next: nextCall(env, 'chat_open', { participantId: partyId }, 'reach this person in a working room'),
+        };
+    }
+    if (partyKind === 'person' && !linked) {
+        return {
+            kind: 'contact',
+            outcome: 'pending',
+            summary: 'Unlinked outside person: request a link or introduction. Do not invent an agreement or listing to manufacture reach.',
+            next: nextCall(env, 'link_propose', { to: partyId }, 'ask for a reach-only link to this person'),
+        };
+    }
+    if (partyKind === 'agent' && listed) {
+        return {
+            kind: 'contact',
+            outcome: 'ok',
+            summary: 'This agent is listed. Claim the listing — do not open a hire by chatting.',
+            next: nextCall(env, 'marketplace_view', undefined, 'find the listing to claim'),
+        };
+    }
+    return {
+        kind: 'contact',
+        outcome: 'pending',
+        summary: 'This agent is not listed for a claim. Follow the engagement ladder (reuse, request, or a permitted direct proposal). Do not treat chat as a hire.',
+        next: nextCall(env, 'agreement_request', undefined, 'post a request when nothing listed fits', { definition: agreementRequestCapability }),
+    };
+}
+export function hireWorkOrderGuide(env, delivery) {
+    const agreementId = delivery.agreementId;
+    return {
+        kind: 'work_order',
+        outcome: 'ok',
+        chatId: delivery.chatId,
+        agreementId,
+        summary: 'A brief from the principal in this hire is a work order. Create a task on yourself under that agreement. Fill the description from the brief after you read it. When you need helpers, declare a graph — do not invent worker_next.',
+        next: nextCall(env, 'task_create', {
+            agreementId,
+            assigneeId: env.creds.agentId,
+        }, 'create the work order on yourself under this hire'),
+    };
+}
+export function strangerBriefGuide(env, chatId) {
+    return {
+        kind: 'stranger_brief',
+        outcome: 'pending',
+        chatId,
+        summary: "A stranger's brief is not a work order. Draft an agreement; do not create a task under a hire you do not have.",
+        next: nextCall(env, 'agreement_request', undefined, 'draft the agreement this brief would ride', { definition: agreementRequestCapability }),
+    };
+}
+export function duplicateGuide() {
+    return {
+        kind: 'duplicate',
+        outcome: 'noop',
+        summary: 'This is a duplicate or echo of work you already have. Do not create another request, task, or committed effect.',
+    };
+}
+function hintFromTask(task) {
+    return {
+        taskId: task.taskId,
+        agreementId: task.agreementId ?? null,
+        rootTaskId: task.rootTaskId ?? null,
+        heldByDeps: task.heldByDeps,
+        waitsOn: task.waitsOn,
+        dueAt: task.dueAt ?? null,
+        checkBack: task.checkBack ?? null,
+    };
+}
+/**
+ * First engagement that matters on this envelope. Empty mail with no held
+ * tasks returns null so an empty inbox result stays a pass-through.
+ */
+export function inboxEngagement(input) {
+    const { env, agentId, inbox, continuation } = input;
+    const tasks = input.tasks ?? [];
+    if (isEchoOrDuplicate(inbox, agentId)) {
+        return duplicateGuide();
+    }
+    const mine = inbox.deliveries.filter((d) => assignedToMe(d, agentId));
+    const workOrder = mine.find((d) => isHireWorkOrder(d, agentId, inbox.tasksAwaitingMe));
+    if (workOrder) {
+        return hireWorkOrderGuide(env, workOrder);
+    }
+    const stranger = mine.find((d) => d.kind === 'message' && !d.agreementId);
+    if (stranger) {
+        return strangerBriefGuide(env, stranger.chatId);
+    }
+    const held = tasks.find((t) => t.heldByDeps);
+    if (held) {
+        const graph = graphReleaseHonesty(held);
+        const rootId = held.rootTaskId || held.taskId;
+        return {
+            kind: 'held',
+            outcome: 'pending',
+            taskId: held.taskId,
+            agreementId: held.agreementId ?? null,
+            summary: 'This node is held until dependencies are terminal. Failed or cancelled dependencies are not inputs. Withdraw by cancelling the root.',
+            graph,
+            next: nextCall(env, 'task_cancel', { taskId: rootId }, 'withdraw the held graph by cancelling the root'),
+        };
+    }
+    const waiting = tasks.find((t) => waitingOnFromTask(t));
+    if (waiting) {
+        const who = waitingOnFromTask(waiting);
+        return {
+            kind: 'waiting',
+            outcome: 'pending',
+            taskId: waiting.taskId,
+            waitingOn: who,
+            summary: 'The last act was a question. This task is waiting on that person — a receipt, not a new blocked state.',
+        };
+    }
+    const chase = tasks.find((t) => t.dueAt || t.checkBack);
+    if (chase) {
+        return reminderHonesty(chase, continuation);
+    }
+    return null;
+}
+export function hintsFromTasks(tasks) {
+    return (tasks ?? []).map(hintFromTask);
+}

package/dist/http/AgreementClient.d.ts

@@ -120,7 +120,8 @@ export declare function proposeBroadcast(input: ProposeBroadcastInput, creds: Cr
 export interface DelegateAgreementData {
     description: string;
     executorId: string;
-    chatId: string;
+    /** Omit it and the server uses the parent agreement's own chat. */
+    chatId?: string;
     parentAgreementId: string;
     price?: number;
     lifecycle?: string;

package/dist/http/AgreementClient.js

@@ -106,6 +106,10 @@ export function shapeAgreement(a) {
         ...(wire.terms?.maxExecutions != null
             ? { maxExecutions: wire.terms.maxExecutions }
             : {}),
+        // A price with no billing mode is two different offers. Lifted
+        // beside the executions cap because they are read together: "ϟ5 a task, up
+        // to 10" and "ϟ5 for the lot" are the same three fields otherwise.
+        ...(wire.terms?.billing != null ? { billing: wire.terms.billing } : {}),
         ...(wire.proposal?.status != null
             ? { proposalStatus: wire.proposal.status }
             : {}),

package/dist/http/ChatClient.d.ts

@@ -1,5 +1,5 @@
 import type { ChatReadDto } from '@ziggs-ai/contracts';
-import type { SendChatMessageResult } from '@ziggs-ai/contracts';
+import type { MessageDelivery, SendChatMessageResult as WireSendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
 /**
  * One room from `GET /chats/mine`, as the server sends it.
@@ -45,7 +45,33 @@ export interface SendChatMessageInput {
     contentType?: string;
     underAgreementId?: string;
 }
-export type { SendChatMessageResult } from '@ziggs-ai/contracts';
+/**
+ * Where the server says a send landed.
+ *
+ * The contract's own shape, re-exported rather than restated: it shipped in
+ * contracts 0.7.7, and the hand-written stand-in that carried it until then is
+ * gone. What the fields mean is worth keeping in front of a caller, because
+ * the receipt is easy to over-read:
+ *
+ * The caller may omit the receiver and have it inferred, or have it widened to
+ * the room's humans, so the destination is the server's answer rather than the
+ * caller's request. `accepted` is the message being created — not a claim that
+ * anyone read it. Routing is asynchronous and unconfirmed by this receipt; the
+ * `wakesAgent` field that once rode along was removed for exactly that reason
+ * and is not coming back.
+ */
+export type { MessageDelivery } from '@ziggs-ai/contracts';
+/**
+ * The send result as a caller here holds it.
+ *
+ * `delivery` is optional on the way in and required in the contract, which is
+ * not a disagreement about the wire: this client is installed independently of
+ * the backend it talks to, and a server from before the field existed answers
+ * without one.
+ */
+export type SendChatMessageResult = Omit<WireSendChatMessageResult, 'delivery'> & {
+    delivery?: MessageDelivery;
+};
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface AddChatMemberInput {
     chatId: string;

package/dist/http/ChatClient.js

@@ -112,11 +112,18 @@ export async function sendChatMessage(input, creds) {
         throwApiError(res, body, `sendChatMessage failed: ${res.status} ${res.statusText}`);
     }
     const data = (await res.json().catch(() => null));
+    const delivery = data?.['delivery'];
     return {
         success: Boolean(data?.['success']),
         message: String(data?.['message'] ?? 'ok'),
         messageId: String(data?.['messageId'] ?? input.messageId),
         chatId: String(data?.['chatId'] ?? chatId),
+        // Passed through as the server reported it, or absent. Never reconstructed
+        // from the request: the whole point is that the destination may not be the
+        // one the caller named.
+        ...(delivery && typeof delivery === 'object'
+            ? { delivery: delivery }
+            : {}),
     };
 }
 export async function listMyChats(creds) {

package/dist/http/ContextGrantsClient.d.ts

@@ -96,7 +96,21 @@ export declare class ContextGrantsClient {
      */
     constructor(operatorKey: string, agentId?: string, baseUrl?: string);
     issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
-    delegateGrant(parentGrantId: string, input: DelegateContextGrantInput): Promise<DelegateContextGrantResult>;
+    requestArtifactAccess(artifactId: string, input: {
+        chatId: string;
+        ownerId: string;
+        reason: string;
+        durationHours?: number;
+    }, opts?: {
+        idempotencyKey?: string;
+        laneId?: string;
+    }): Promise<{
+        status: 'pending_approval';
+        agreementId: string;
+    }>;
+    delegateGrant(parentGrantId: string, input: DelegateContextGrantInput, opts?: {
+        idempotencyKey?: string;
+    }): Promise<DelegateContextGrantResult>;
     /**
      * expand a grant you hold into the chat/agreement ids inside its
      * scope. A grant is a fence, not a listing: discovery says "you hold
@@ -118,6 +132,8 @@ export declare class ContextGrantsClient {
         holderId: string;
         expiresAt?: string | null;
         chatId?: string;
+    }, opts?: {
+        idempotencyKey?: string;
     }): Promise<DelegateContextGrantResult>;
     revokeGrant(grantId: string): Promise<{
         status: string;

package/dist/http/ContextGrantsClient.js

@@ -63,11 +63,32 @@ export class ContextGrantsClient {
         }
         return parsed.grant;
     }
-    async delegateGrant(parentGrantId, input) {
+    async requestArtifactAccess(artifactId, input, opts) {
+        const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/access-requests`, {
+            method: 'POST',
+            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
+                'content-type': 'application/json',
+                ...(opts?.idempotencyKey ? { 'Idempotency-Key': opts.idempotencyKey } : {}),
+                ...(opts?.laneId ? { 'x-ziggs-lane': opts.laneId } : {}),
+            }),
+            body: JSON.stringify(input),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok)
+            throwApiError(res, body, `requestArtifactAccess failed: ${res.status}`);
+        const result = JSON.parse(body);
+        if (result.status !== 'pending_approval' || !result.agreementId)
+            throw new Error('Expected a pending artifact access request');
+        return { status: 'pending_approval', agreementId: result.agreementId };
+    }
+    async delegateGrant(parentGrantId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(parentGrantId)}/delegate`, {
             method: 'POST',
             headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
                 'content-type': 'application/json',
+                ...(opts?.idempotencyKey
+                    ? { 'Idempotency-Key': opts.idempotencyKey }
+                    : {}),
             }),
             body: JSON.stringify(input),
         });
@@ -114,11 +135,14 @@ export class ContextGrantsClient {
      * is granted immediately; anyone else opens a request the owner approves,
      * exactly like `delegateGrant`'s new-party path.
      */
-    async shareArtifact(artifactId, input) {
+    async shareArtifact(artifactId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/share`, {
             method: 'POST',
             headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
                 'content-type': 'application/json',
+                ...(opts?.idempotencyKey
+                    ? { 'Idempotency-Key': opts.idempotencyKey }
+                    : {}),
             }),
             body: JSON.stringify(input),
         });

package/dist/http/ContextReadClient.d.ts

@@ -27,7 +27,7 @@ export interface ContextReadQuery {
     cursor?: string;
     limit?: number;
     after?: string;
-    direction?: 'forward';
+    direction?: 'forward' | 'backward';
     state?: string;
     contextGrantId?: string;
 }
@@ -58,6 +58,13 @@ export interface ContextSnapshotParticipant {
 export interface ContextSnapshotResult {
     history: unknown[];
     agreements: unknown[];
+    /** Bounded room inventory, without bodies. Absent on older backends. */
+    artifacts?: ContextReadEnvelope<{
+        artifactId: string;
+        name: string | null;
+        contentType: string;
+        timestamp: string | null;
+    }>;
     agents: Array<ContextSnapshotParticipant & {
         agentId: string;
     }>;

package/dist/http/TaskClient.d.ts

@@ -137,8 +137,20 @@ export type PlanStepPatch = {
     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>;
+/**
+ * Who the holder is waiting on, because its last act was asking them.
+ *
+ * Rides the progress write because that is when it is known and that is what
+ * makes it false again: the server clears it on the next progress write that
+ * does not restate it, and on any terminal transition. A holder that did
+ * something else after asking is no longer waiting.
+ */
+export type TaskWaitingOn = {
+    kind: 'user' | 'agent';
+    id: string;
+};
+export declare function updateTaskPlanSteps(taskId: string, patches: PlanStepPatch[], creds: Creds, waitingOn?: TaskWaitingOn | null): Promise<TaskWriteConfirm>;
+export declare function updateTaskPlanStep(taskId: string, stepId: string, status: string, result: unknown, creds: Creds, waitingOn?: TaskWaitingOn | null): 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>;
 export interface ListTasksOptions {

package/dist/http/TaskClient.js

@@ -277,13 +277,17 @@ 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) {
+export async function updateTaskPlanSteps(taskId, patches, creds, waitingOn) {
     if (!taskId)
         throw new Error('updateTaskPlanSteps: taskId is required');
-    if (!patches || !Array.isArray(patches) || patches.length === 0) {
+    const named = Array.isArray(patches) ? patches : [];
+    // A bare waiting-on write is the ask that produced no other progress, and
+    // the route takes it on its own. Without this the only way to say "I asked
+    // Dana" was to invent a plan step to tick.
+    if (named.length === 0 && !waitingOn) {
         throw new Error('updateTaskPlanSteps: patches must name at least one step');
     }
-    for (const patch of patches) {
+    for (const patch of named) {
         if (!patch?.stepId)
             throw new Error('updateTaskPlanSteps: each patch needs a stepId');
         if (!patch?.status)
@@ -293,7 +297,10 @@ export async function updateTaskPlanSteps(taskId, patches, creds) {
     const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
         method: 'PATCH',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ patches }),
+        body: JSON.stringify({
+            ...(named.length > 0 ? { patches: named } : {}),
+            ...(waitingOn !== undefined ? { waitingOn } : {}),
+        }),
     });
     if (!res.ok) {
         const responseBody = await res.text().catch(() => '');
@@ -305,7 +312,7 @@ export async function updateTaskPlanSteps(taskId, patches, creds) {
         throw new Error('Invalid response: task write confirm not found');
     return confirm;
 }
-export async function updateTaskPlanStep(taskId, stepId, status, result, creds) {
+export async function updateTaskPlanStep(taskId, stepId, status, result, creds, waitingOn) {
     if (!taskId)
         throw new Error('updateTaskPlanStep: taskId is required');
     if (!stepId)
@@ -316,7 +323,15 @@ export async function updateTaskPlanStep(taskId, stepId, status, result, creds)
     const res = await fetch(`${getTaskBaseUrl()}/${taskId}/plan`, {
         method: 'PATCH',
         headers: buildHeaders(creds),
-        body: JSON.stringify({ stepId, status, ...(result !== undefined && { result }) }),
+        // One write, not two: the server clears `waitingOn` on a progress write
+        // that does not restate it, so posting the tick and the ask separately
+        // would set it and then immediately drop it.
+        body: JSON.stringify({
+            stepId,
+            status,
+            ...(result !== undefined && { result }),
+            ...(waitingOn !== undefined ? { waitingOn } : {}),
+        }),
     });
     if (!res.ok) {
         const responseBody = await res.text().catch(() => '');

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 export { ApiError } from './types.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxPeek, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, } from './http/AgreementClient.js';
+export { decisionWords } from './decisionWords.js';
+export type { DecisionOutcome, DecisionWords, DecisionWordsInput, } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from './inboxAck.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
@@ -20,3 +22,5 @@ export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdenti
 export * from './utils/appUrls.js';
 export { sessionOrientation, } from './sessionOrientation.js';
 export type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson, SessionContinuation, SessionOrientation, SessionOrientationInput, } from './sessionOrientation.js';
+export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
+export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, EngagementTaskHint, ContactPathInput, FormationInput, GraphHonesty, HireTermsHonesty, WaitingOn, } from './engagementGuide.js';

package/dist/index.js

@@ -13,9 +13,13 @@ export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, }
 // half of them had drifted).
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
+// One decision, one sentence, on every rail: the reason a delivery row carries
+// when somebody answered a request this agent made, rendered as words.
+export { decisionWords } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
 export { INBOX_HOST_CLAIMANT_HEADER, INSTANCE_IDENTITY_MAX_LENGTH, cliHostIdentity, hostIdentity, instanceIdentity, mcpConnectionIdentity, } from './instanceIdentity.js';
 export * from './utils/appUrls.js';
 export { sessionOrientation, } from './sessionOrientation.js';
+export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';