@ziggs-ai/api-client 0.21.0 → 0.22.0

package/dist/capabilities/chat.js

@@ -86,7 +86,7 @@ export const openConversationCapability = {
                 : {}),
         });
         const lister = env.surface === 'mcp' ? 'ziggs_grant_list' : 'grant_list';
-        const grantNote = `Opening the room issued you a grant on it, so the chat also appears in ${lister} scopeKind=chat for context reads.`;
+        const grantNote = `Use ${lister} scopeKind=chat to inspect your room grants. Opening a conversation does not send a message or confirm that anyone has read it.`;
         // word the note from the outcome instead of covering both cases.
         // "Open (or reused)" told the agent the distinction existed and then
         // withheld it — worse than silence, because the agent cannot even tell

package/dist/capabilities/context.js

@@ -83,8 +83,8 @@ export const contextReadCapability = {
         after: { type: 'string', description: 'ISO timestamp for forward-delta (messages/artifacts)' },
         direction: {
             type: 'string',
-            enum: ['forward'],
-            description: 'Use "forward" with after for a message forward-delta',
+            enum: ['forward', 'backward'],
+            description: 'Use "forward" with after for a message forward-delta; "backward" starts a newest-first artifact inventory',
         },
         limit: { type: 'number', description: 'Page size (server default when omitted)' },
         state: { type: 'string', description: 'Task state filter (tasks only)' },
@@ -114,8 +114,8 @@ export const contextReadCapability = {
             throw new Error(`${type} reads accept via=${viaHint(type)} — not ${parsed.kind}:<id>`);
         }
         const direction = args['direction'];
-        if (direction !== undefined && direction !== 'forward') {
-            throw new Error('direction must be "forward"');
+        if (direction !== undefined && direction !== 'forward' && direction !== 'backward') {
+            throw new Error('direction must be "forward" or "backward"');
         }
         return new ContextReadClient(creds.operatorKey, creds.agentId, undefined, creds.laneId).read(type, {
             via,

package/dist/capabilities/discovery.js

@@ -6,7 +6,7 @@ export const agentSearchCapability = {
     title: 'Search for agents',
     descriptions: {
         sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store AND your own org-mates. A link does NOT make the other person\'s agents findable — how they staff their side is theirs, and it changes without telling anyone; reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
-        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND your own org-mates — so you can find a teammate\'s delegate by name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you. A link does NOT make the other person\'s agents findable: a link makes the PERSON addressable, never their staffing list. To reach someone you are linked with, take their peer id from ziggs_link_list and ziggs_chat_open with that; their agents become known to you by turning up in rooms. Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and a linked person\'s unpublished agent is one of those. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `managed`, or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
+        mcp: 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND your own org-mates — so you can find a teammate\'s assistant by the teammate\'s name or by its own name and ziggs_chat_open with it directly, even if it is unpublished/offline and has never been in a chat with you; a same-org hit carries `person` (the teammate\'s userId and name), and ziggs_chat_open with that userId reaches the person themselves. A link does NOT make the other person\'s agents findable: a link makes the PERSON addressable, never their staffing list. To reach someone you are linked with, take their peer id from ziggs_link_list and ziggs_chat_open with that; their agents become known to you by turning up in rooms. Passing an EXACT agent id resolves that one agent even if unpublished/private, when you can reach it — an id you cannot reach comes back `reachability: "restricted"` with no name/profile, and a linked person\'s unpublished agent is one of those. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (ziggs_agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `managed`, or `engaged`; it is not a blanket "published" label. Use returned agentId in grant/issue tools — do not guess ids.',
     },
     annotation: 'read-only',
     params: {
@@ -37,9 +37,15 @@ export const agentSearchCapability = {
             return {
                 count: 0,
                 agents: [],
-                searched: ['published store', 'your org-mates'],
-                hint: 'Zero hits means no agent profile matched these terms — discovery itself is up. ' +
-                    'Matching is lexical against agent name/description/tags, so try shorter or different keywords. ' +
+                searched: [
+                    'published store: agents by name, description and tags',
+                    'your org: agents by name, description and tags',
+                    'your org: people by name (returns their agents, with person.userId)',
+                ],
+                hint: 'Zero hits means nothing matched these terms; discovery itself is up. ' +
+                    'People are not agents: a teammate\'s assistant is found by the teammate\'s name or by its own name, and a hit carries person.userId. ' +
+                    'To reach the person themselves, open a chat with that user id (chat_open participantId). ' +
+                    'Matching is lexical, so try shorter or different keywords. ' +
                     'If you already know the agent, pass its exact agent id as the query to resolve it directly. ' +
                     'Searching for someone you are LINKED with will always miss: a link makes the person addressable, ' +
                     'not their agents. Take their peer id from link_list and open a chat with the person instead.',

package/dist/decisionWords.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One decision, one sentence, on every rail.
+ *
+ * When somebody answers a request an agent made (an access request on an
+ * artifact, a connection request, its own proposal), the agent hears about it
+ * as an agreement row whose `reason` names the decision. Rendered generically
+ * ("open the agreement <id>") that row says nothing about what was decided,
+ * and the agent learned it was approved or refused only if it happened to list
+ * its agreements. The hosted brain already had words for these reasons; the
+ * MCP rail did not. Both now call this function, so they say the same thing.
+ *
+ * The sentence is server state only. It never interpolates anything a
+ * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
+ * and an instant are all it carries.
+ */
+export type DecisionOutcome = 'approved' | 'rejected' | 'fulfilled' | 'held';
+export interface DecisionWordsInput {
+    /** The delivery row's `reason`. Anything that is not a decision maps to null. */
+    reason: string | null | undefined;
+    /** Who answered (the row's `actorId`). Absent on some emits. */
+    actorId?: string | null;
+    /** When it was answered (the row's `ts`), as an ISO instant. */
+    ts?: string | null;
+    /** The request agreement. */
+    agreementId?: string | null;
+    /**
+     * What the request was about, when the caller knows it. Named only when
+     * `kind` is `artifact`; today's delivery row does not carry it, so the
+     * sentence sends the reader to the agreement to find the artifact instead.
+     */
+    scope?: {
+        kind: string;
+        id: string;
+    } | null;
+    /**
+     * Which surface's tool names to use. MCP registers `ziggs_open` and
+     * `ziggs_context_read`; the hosted SDK registers `open` and `context_read`.
+     */
+    surface?: 'mcp' | 'sdk';
+}
+export interface DecisionWords {
+    outcome: DecisionOutcome;
+    /** Plain, model-facing, server state only. */
+    sentence: string;
+}
+/**
+ * Map a delivery row's decision reason to words. Returns null when the reason
+ * is not a decision (an ordinary doorbell, a store claim, a withheld contact),
+ * so a caller can use it as the test for "does this row need explaining".
+ */
+export declare function decisionWords(input: DecisionWordsInput): DecisionWords | null;

package/dist/decisionWords.js

@@ -0,0 +1,86 @@
+/**
+ * One decision, one sentence, on every rail.
+ *
+ * When somebody answers a request an agent made (an access request on an
+ * artifact, a connection request, its own proposal), the agent hears about it
+ * as an agreement row whose `reason` names the decision. Rendered generically
+ * ("open the agreement <id>") that row says nothing about what was decided,
+ * and the agent learned it was approved or refused only if it happened to list
+ * its agreements. The hosted brain already had words for these reasons; the
+ * MCP rail did not. Both now call this function, so they say the same thing.
+ *
+ * The sentence is server state only. It never interpolates anything a
+ * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
+ * and an instant are all it carries.
+ */
+const REFUSED_REASONS = new Set([
+    'approval:rejected',
+    'context_request_rejected',
+    'connection_request_rejected',
+]);
+function requestNoun(reason) {
+    if (reason.startsWith('context_request_'))
+        return 'access request';
+    if (reason.startsWith('connection_request_'))
+        return 'connection request';
+    return 'request';
+}
+/**
+ * Map a delivery row's decision reason to words. Returns null when the reason
+ * is not a decision (an ordinary doorbell, a store claim, a withheld contact),
+ * so a caller can use it as the test for "does this row need explaining".
+ */
+export function decisionWords(input) {
+    const reason = typeof input.reason === 'string' ? input.reason : '';
+    if (!reason)
+        return null;
+    const tool = (key) => input.surface === 'sdk' ? key : `ziggs_${key}`;
+    const on = input.agreementId
+        ? `agreement ${input.agreementId}`
+        : 'this agreement';
+    const by = input.actorId ? ` by ${input.actorId}` : '';
+    const at = input.ts ? ` at ${input.ts}` : '';
+    const artifactId = input.scope?.kind === 'artifact' && input.scope.id ? input.scope.id : null;
+    if (REFUSED_REASONS.has(reason)) {
+        return {
+            outcome: 'rejected',
+            sentence: `Your ${requestNoun(reason)} on ${on} was refused${by}${at}. ` +
+                'Report the unresolved dependency where you asked, and ask what to change.',
+        };
+    }
+    if (reason === 'context_request_fulfilled') {
+        const open = artifactId
+            ? `Open the artifact ${artifactId} with ${tool('context_read')} or ${tool('open')}; `
+            : `Open the agreement with ${tool('open')} to find the artifact, then open the artifact with ${tool('context_read')} or ${tool('open')}; `;
+        return {
+            outcome: 'fulfilled',
+            sentence: `Your access request on ${on} was approved${by}${at}. ` +
+                open +
+                'the grant is bounded, check its expiry on the agreement.',
+        };
+    }
+    if (reason === 'connection_request_fulfilled') {
+        return {
+            outcome: 'fulfilled',
+            sentence: `Your connection request on ${on} was fulfilled${by}${at}. ` +
+                `The connection is ready to use; open the agreement with ${tool('open')} for its connection and grant ids and the bound on the grant.`,
+        };
+    }
+    if (reason === 'approval:approved') {
+        return {
+            outcome: 'approved',
+            sentence: `An approval on ${on} was given${by}${at}. ` +
+                'If it answers a request you made, carry out the next step you promised where you asked; ' +
+                `open the agreement with ${tool('open')} to see which slot was answered. ` +
+                'Approval of your own request is not a new hire and needs no introduction.',
+        };
+    }
+    if (reason === 'formation_held') {
+        return {
+            outcome: 'held',
+            sentence: `${on.charAt(0).toUpperCase()}${on.slice(1)} is held${at}: a consent it needs has not been given yet, so nothing is granted. ` +
+                `Open the agreement with ${tool('open')} to see whose decision it waits on.`,
+        };
+    }
+    return null;
+}

package/dist/http/ChatClient.d.ts

@@ -1,5 +1,5 @@
 import type { ChatReadDto } from '@ziggs-ai/contracts';
-import type { SendChatMessageResult as WireSendChatMessageResult } 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.
@@ -48,29 +48,29 @@ export interface SendChatMessageInput {
 /**
  * Where the server says a send landed.
  *
- * Named apart from the server's own `MessageDelivery` on purpose: the contracts
- * package is generated from the running server's spec and has not shipped this
- * shape yet, and a hand-written type under the contract's name would be a
- * second opinion about the wire. When the generated type lands, this alias is
- * replaced by importing it rather than kept beside it.
+ * 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.
- * Legacy servers inferred wakesAgent from recipient type; that field is not
- * evidence of assignment or execution, including when it is false.
+ * 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 interface SendDeliveryReport {
-    accepted: boolean;
-    to: {
-        id: string;
-        type: string;
-    };
-    broadcast: boolean;
-}
 export type SendChatMessageResult = Omit<WireSendChatMessageResult, 'delivery'> & {
-    delivery?: SendDeliveryReport;
+    delivery?: MessageDelivery;
 };
 export type ContextTemporal = 'from-now' | 'from-start';
 export interface AddChatMemberInput {

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';

package/dist/index.js

@@ -13,6 +13,9 @@ 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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,8 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "socket.io-client": "^4.7.0",
-    "@ziggs-ai/contracts": "^0.9.0"
+    "@ziggs-ai/contracts": "^0.9.0",
+    "socket.io-client": "^4.7.0"
   },
   "keywords": [
     "ziggs",