@ziggs-ai/api-client 0.10.3 → 0.11.0

package/dist/http/TaskClient.d.ts

@@ -1,6 +1,6 @@
 import { type Creds, type Task, type TaskState } from '../types.js';
 /**
- * ZIG-1321 — thin confirmation from task write verbs. Full object stays on
+ * Thin confirmation from task write verbs. Full object stays on
  * getTask / ziggs_task_get.
  */
 export interface TaskWriteConfirm {
@@ -25,6 +25,12 @@ export interface TaskWriteConfirm {
 export type PlanReviewTiming = 'with_proposal' | 'before_execution';
 export interface CreateTaskData {
     description: string;
+    /**
+     * Short label for list rows, around 60 characters, 80 max.
+     * Optional: a task without one lists under a trimmed description, which is a
+     * wall of prose at a glance. Set it whenever the task is one row among many.
+     */
+    title?: string;
     agreementId: string;
     parentTaskId?: string;
     plan?: unknown;
@@ -62,7 +68,7 @@ export interface PlanReplaceStep {
     /** Omit to use the array index. */
     order?: number;
     /**
-     * ZIG-1313: step progress. Omit for `pending`. Send `completed` /
+     * Step progress. Omit for `pending`. Send `completed` /
      * `in_progress` when replacing the plan so a later task completion does not
      * rewrite finished steps as skipped.
      */
@@ -80,6 +86,11 @@ export interface ListTasksOptions {
     limit?: number;
     /** Filter to tasks assigned to this id. */
     assignedTo?: string;
+    /**
+     * Filter to tasks CREATED by this id — what the caller handed out, as
+     * opposed to what was handed to it.
+     */
+    createdBy?: string;
 }
 export interface ListTasksResult {
     tasks: Task[];

package/dist/http/TaskClient.js

@@ -24,8 +24,8 @@ function extractTask(data) {
     if (d['task'] && typeof d['task'] === 'object' && d['task']['taskId']) {
         return d['task'];
     }
-    // Top-level task document (GET / create). Do not treat ZIG-1321 thin write
-    // confirms (`ok: true`, no description) as a Task.
+    // Top-level task document (GET / create). Do not treat thin write confirms
+    // (`ok: true`, no description) as a Task.
     if (typeof d['taskId'] === 'string' && d['ok'] !== true) {
         return d;
     }
@@ -345,6 +345,8 @@ export async function listTasks(options = {}, creds) {
         url.searchParams.set('limit', String(options.limit));
     if (options.assignedTo)
         url.searchParams.set('assignedTo', options.assignedTo);
+    if (options.createdBy)
+        url.searchParams.set('createdBy', options.createdBy);
     const res = await fetch(url.toString(), {
         method: 'GET',
         headers: buildHeaders(creds),

package/dist/http/agreementFlows.d.ts

@@ -1,14 +1,14 @@
 import { type ClaimedKind, type ProposeTerms } from './AgreementClient.js';
 import { type Agreement, type Creds, type EngagementKind } from '../types.js';
 /**
- * one propose grammar. Direct, broadcast (quest and standing
+ * one propose grammar. Direct, broadcast (request and standing
  * offer), and link proposals all flow through here; the surfaces expose a
  * single propose tool instead of dedicated publish/request tools.
  *
  * Routing:
  * - engagementKind 'link'                    → POST /agreements (link proposal / open invite)
  * - proposedTo 'everyone' | 'org', providerId = self  → seller-broadcast standing offer
- * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast quest
+ * - proposedTo 'everyone' | 'org', no providerId      → buyer-broadcast request
  * - anything else                            → direct proposal
  */
 export interface UnifiedProposeInput extends ProposeTerms {
@@ -17,13 +17,13 @@ export interface UnifiedProposeInput extends ProposeTerms {
     chatId?: string;
     engagementKind?: EngagementKind;
 }
-export type ProposeShape = 'direct' | 'quest' | 'offer' | 'link';
+export type ProposeShape = 'direct' | 'request' | 'offer' | 'link';
 export declare function proposeUnified(input: UnifiedProposeInput, creds: Creds): Promise<{
     agreement: Agreement;
     shape: ProposeShape;
 }>;
 /**
- * one claim verb for any open broadcast: link invite, quest,
+ * one claim verb for any open broadcast: link invite, request,
  * hand-off, or standing offer.
  *
  * One request. This used to read the agreement first to decide which endpoint to

package/dist/http/agreementFlows.js

@@ -1,4 +1,4 @@
-import { createAgreement, claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
+import { createLink, claimAgreement, proposeBroadcast, proposeDirectTo, } from './AgreementClient.js';
 import { publishOffer } from './MarketplaceClient.js';
 import { isBroadcastTarget, } from '../types.js';
 export async function proposeUnified(input, creds) {
@@ -9,9 +9,8 @@ export async function proposeUnified(input, creds) {
         // A link is an agreement, proposed to one agent (providerId) or opened as
         // an invite (proposedTo 'everyone'); no chat, no money.
         const target = isBroadcastTarget(proposedTo) ? undefined : proposedTo;
-        const { agreement } = await createAgreement({
-            engagementKind: 'link',
-            ...(target ? { providerId: target } : {}),
+        const { agreement } = await createLink({
+            ...(target ? { targetAgentId: target } : {}),
             ...(terms.description ? { description: terms.description } : {}),
         }, creds);
         return { agreement, shape: 'link' };
@@ -33,16 +32,16 @@ export async function proposeUnified(input, creds) {
             return { agreement, shape: 'offer' };
         }
         if (providerId) {
-            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a quest: the claimer works, you pay). A third-party providerId is not broadcastable.');
+            throw new Error('On a broadcast, providerId must be your own agent id (a standing offer: you work, the claimer pays) or omitted (a request: the claimer works, you pay). A third-party providerId is not broadcastable.');
         }
-        // Buyer-broadcast: the claimer works, your side pays — an open quest.
+        // Buyer-broadcast: the claimer works, your side pays — an open request.
         const agreement = await proposeBroadcast({
             ...terms,
             chatId: chatId ?? '',
             engagementKind: engagementKind ?? 'service',
             audience,
         }, creds);
-        return { agreement, shape: 'quest' };
+        return { agreement, shape: 'request' };
     }
     if (!chatId)
         throw new Error('chatId is required on a direct proposal');
@@ -56,7 +55,7 @@ export async function proposeUnified(input, creds) {
     return { agreement, shape: 'direct' };
 }
 /**
- * one claim verb for any open broadcast: link invite, quest,
+ * one claim verb for any open broadcast: link invite, request,
  * hand-off, or standing offer.
  *
  * One request. This used to read the agreement first to decide which endpoint to
@@ -74,6 +73,6 @@ export async function claimOpenAgreement(agreementId, creds) {
         throw new Error('agreementId is required');
     const { agreement, kind } = await claimAgreement(agreementId, creds);
     // A server that has not shipped the `kind` field yet still claims correctly;
-    // 'quest' is the shape the route has always handled.
-    return { agreement, kind: kind ?? 'quest' };
+    // 'request' is the shape the route has always handled.
+    return { agreement, kind: kind ?? 'request' };
 }

package/dist/http/grants.d.ts

@@ -11,6 +11,23 @@
  * watermark are presented as `temporal` / `watermark_at` caveats.
  */
 export type GrantHealth = 'active' | 'expired' | 'revoked';
+/**
+ * Who holds a grant. Declared at issuance and carried on the row — nothing
+ * about an id says what it names. An `org` holder is how one grant covers every
+ * member of that organization.
+ */
+export type GrantHolderKind = 'user' | 'org' | 'agent';
+/**
+ * What a grant lets its holder do. `write` implies `read`, `admit` implies
+ * both: `read` sees the scope, `write` takes part in it, `admit` brings others
+ * in as well.
+ */
+export type GrantAccessKind = 'read' | 'write' | 'admit';
+/**
+ * The kind of principal-authored consent object a grant rests on. Every grant
+ * is minted by one of these, or delegated from a parent grant that was.
+ */
+export type GrantBasisKind = 'creation' | 'publication' | 'membership' | 'acceptance' | 'agreement';
 /**
  * The context rail's scope kinds, as VALUES — the type below is derived from
  * them, so widening the rail is one edit rather than a type change plus however
@@ -51,6 +68,17 @@ export interface GrantView {
     /** ISO-8601. */
     createdAt: string;
     health: GrantHealth;
+    /**
+     * What the holder is, what the grant lets them do, and which consent object
+     * authorized it. Present on rails that record them (context grants do);
+     * absent means the rail does not say, not that there is nothing.
+     */
+    holderKind?: GrantHolderKind;
+    access?: GrantAccessKind;
+    basis?: {
+        kind: GrantBasisKind;
+        id: string | null;
+    };
 }
 /** 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/index.d.ts

@@ -8,7 +8,7 @@ export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.j
 export { ArtifactsClient, artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';
 export type { ArtifactVisibility, ListArtifactsOptions, ListArtifactsQuery, ListArtifactsResult, WriteArtifactInput, } from './ArtifactsClient.js';
 export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, parseVia, viaHint, } from './ContextReadClient.js';
-export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ViaKind, } from './ContextReadClient.js';
+export type { ContextReadType, ContextReadQuery, ContextReadEnvelope, ContextSnapshotResult, ContextSnapshotParticipant, ViaKind, } from './ContextReadClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { GrantsClient } from './GrantsClient.js';
@@ -16,7 +16,7 @@ export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './Grants
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, ContextTemporal, IssueContextGrantInput, DelegateContextGrantInput, DelegateContextGrantResult, ReachEntry, GrantReachResult, } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.js';
-export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, } from './grants.js';
+export type { GrantView, GrantScopeKind, GrantScopeView, GrantCaveatView, GrantHealth, GrantHolderKind, GrantAccessKind, GrantBasisKind, } from './grants.js';
 export { PaymentsClient } from './PaymentsClient.js';
 export type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
 export { RateLimitedError, isRateLimited, parseRetryAfterMs, pollSurfaceError, } from './shared/rateLimit.js';
 export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiError.js';
 export { ApiError } from './types.js';
-export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxQuestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
+export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, } from './http/AgreementClient.js';

package/dist/types.d.ts

@@ -27,7 +27,8 @@ export interface Creds {
      *
      * The operator key says WHO is calling; this says ON WHOSE BEHALF, RIGHT NOW.
      * Without it an agent serving several customers carries its full authority
-     * into every call, and one tool call reaches another customer's work.
+     * into every call, so a read spans every engagement it holds rather than
+     * staying inside the one being worked.
      *
      * Optional, and omitting it can only narrow what comes back (the backend
      * falls back to the agent's own org) — never widen it. Nothing here is
@@ -46,6 +47,13 @@ export interface PlanStep {
 export interface Task {
     taskId: string;
     description: string;
+    /**
+     * Short row label. The backend always resolves it — falling back
+     * to a trimmed description for tasks that never set one — so render it
+     * unconditionally instead of re-deriving the fallback. Optional here only
+     * because a server predating the field omits it.
+     */
+    title?: string;
     agentId?: string;
     executorId?: string;
     payerId?: string;
@@ -75,7 +83,7 @@ export interface Task {
 }
 export type AgreementStatus = 'pending' | 'active' | 'fulfilled' | 'cancelled' | 'rejected' | (string & {});
 export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'countered' | 'expired' | (string & {});
-/** ⚠️ SYNC: backend src/agreements/agreements.constants.ts AGREEMENT_ENGAGEMENT_KIND */
+/** ⚠️ Mirrors the server's engagement-kind constant; the server is authoritative. */
 export declare const AGREEMENT_ENGAGEMENT_KIND: {
     readonly HIRE: "hire";
     readonly SERVICE: "service";
@@ -152,7 +160,7 @@ export interface Agreement {
     createdAt?: string;
     updatedAt?: string;
 }
-/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts ENTRY_TYPE */
+/** ⚠️ Mirrors the server's entry-type constant; the server is authoritative. */
 export declare const EntryTypes: {
     readonly MESSAGE: "message";
     readonly NOTIFICATION: "notification";
@@ -162,7 +170,7 @@ export declare const EntryTypes: {
     readonly TASK_HISTORY: "task_history";
 };
 export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
-/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts CONTENT_TYPE */
+/** ⚠️ Mirrors the server's content-type constant; the server is authoritative. */
 export declare const ContentTypes: {
     readonly TEXT: "text";
     readonly OPERATION: "operation";
@@ -176,11 +184,11 @@ export declare const ContentTypes: {
     readonly TASK_UPDATE: "task_update";
 };
 export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
-/** ⚠️ SYNC: Mirrors backend src/chat/chat.types.ts isValidContentType */
+/** ⚠️ Mirrors the server's entry/content-type validation; the server is authoritative. */
 export declare function isValidContentType(contentType: string, entryType: string): boolean;
-/** ⚠️ SYNC: Keep in sync with backend agreements.constants.ts. Fully-public broadcast sentinel. */
+/** ⚠️ Mirrors the server's sentinel. Fully-public broadcast target. */
 export declare const OPEN_AGREEMENT_TARGET: "everyone";
-/** ⚠️ SYNC: backend ORG_AGREEMENT_TARGET. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
+/** ⚠️ Mirrors the server's sentinel. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
 export declare const ORG_AGREEMENT_TARGET: "org";
 /** Audience for a broadcast proposal: fully public ('everyone') or org-scoped ('org'). */
 export type BroadcastAudience = typeof OPEN_AGREEMENT_TARGET | typeof ORG_AGREEMENT_TARGET;
@@ -279,14 +287,34 @@ export type MessageHandler = (text: string, metadata: MessageMetadata) => Promis
  * on this side validates a delivery kind at runtime (the server does that on the
  * way in), and exhaustiveness checking is purely type-level.
  */
-export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'quest';
+export type InboxDeliveryKind = 'message' | 'artifact' | 'task-state' | 'agreement' | 'request';
+/** The two mailbox owners. Agents own no mailbox — they read through grants. */
+export type InboxPartyKind = 'human' | 'org';
+/** One mailbox this reader's merged view includes. */
+export interface InboxSourceRef {
+    partyId: string;
+    partyKind: InboxPartyKind;
+}
 /**
- * One thing addressed to this agent. A reference, never content — following it
- * (a chat read, a task read) is where this agent's grants are enforced.
+ * One row in this reader's merged view. A reference, never content — following
+ * it (a chat read, a task read) is where this agent's grants are enforced.
+ *
+ * "Mine to act on" is `assigneeId === my agent id`, nothing else. A row
+ * without my stamp is context I may read, never a wake and never mine to ack
+ * as handled.
  */
 export interface InboxDeliveryRef {
     kind: InboxDeliveryKind;
     resourceId: string;
+    /** One emit, one id — copies of the same event collapse on this. */
+    eventId: string;
+    /** The mailbox this copy lives in. */
+    partyId: string;
+    partyKind: InboxPartyKind;
+    /** The ONE agent stamped to act; null when nothing has to. */
+    assigneeId: string | null;
+    /** The owner's human should see this. */
+    needsHuman: boolean;
     chatId: string | null;
     agreementId: string | null;
     taskId: string | null;
@@ -369,10 +397,10 @@ export interface InboxTaskRef {
     updatedAt: string | null;
 }
 /**
- * A marketplace quest doorbell. Own channel so the host can
+ * A marketplace request doorbell. Own channel so the host can
  * exact-match triage with zero LLM tokens before any wake.
  */
-export interface InboxQuestRef {
+export interface InboxRequestRef {
     agreementId: string;
     /** Exact-match string from the publisher — compare to the agent's tags. */
     match: string;
@@ -382,27 +410,36 @@ export interface InboxQuestRef {
 export interface InboxEnvelope {
     asOf: string;
     /**
-     * Unacked deliveries addressed to this agent, newest first. This IS the
-     * inbox — read straight out of the delivery log, not derived from grants.
+     * The mailboxes this reader's view merges — its owner's, plus whatever
+     * inbox grants add. Absent on older servers.
+     */
+    sources?: InboxSourceRef[];
+    /**
+     * Unacked rows across every source, newest first, copies of one event
+     * collapsed. This IS the inbox — read straight out of the party delivery
+     * logs, not derived from grants. Rows with `assigneeId === me` are mine to
+     * act on; the rest are readable context.
      */
     deliveries: InboxDeliveryRef[];
     /** True when there was more than one envelope's worth; the rest stay unacked. */
     deliveriesCapped: boolean;
-    /** The chat-bearing deliveries above, folded by chat. */
+    /** This agent's ASSIGNED chat mail, folded by chat. */
     chats: InboxChatNews[];
     /**
-     * Pass to `ack(upTo, { handledResourceIds })` after acting (ZIG-1305).
-     * Null when there is nothing to ack. Ack after acting, not after reading:
-     * a crash in between redelivers. Listing every handled resourceId is what
-     * stops a partial triage from burying other chats.
+     * Opaque watermark bundle. Pass to `ack(upTo, { handledResourceIds })`
+     * VERBATIM after acting — never construct or parse one; the per-mailbox
+     * positions live inside the value. Null when there is nothing to ack. Ack
+     * after acting, not after reading: a crash in between redelivers. Listing
+     * every ASSIGNED resourceId is what stops a partial triage from burying
+     * work.
      */
     ackTo: string | null;
     /** Open tasks assigned to this agent — the work channel. */
     tasksAwaitingMe: InboxTaskRef[];
     truncatedTasks: number;
-    /** Unacked quest deliveries — triaged before any LLM wake. */
-    questsAwaitingMe?: InboxQuestRef[];
-    truncatedQuests?: number;
+    /** Unacked request deliveries — triaged before any LLM wake. */
+    requestsAwaitingMe?: InboxRequestRef[];
+    truncatedRequests?: number;
     proposalsAwaitingMe: InboxProposalRef[];
     truncatedProposals: number;
     connectionRequestsAwaitingMe: InboxConnectionRequestRef[];

package/dist/types.js

@@ -27,14 +27,14 @@ export class RateLimitedError extends ApiError {
         this.retryAfterMs = retryAfterMs;
     }
 }
-/** ⚠️ SYNC: backend src/agreements/agreements.constants.ts AGREEMENT_ENGAGEMENT_KIND */
+/** ⚠️ Mirrors the server's engagement-kind constant; the server is authoritative. */
 export const AGREEMENT_ENGAGEMENT_KIND = {
     HIRE: 'hire',
     SERVICE: 'service',
     /** a bilateral reach link between two agents (no money, no work). */
     LINK: 'link',
 };
-/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts ENTRY_TYPE */
+/** ⚠️ Mirrors the server's entry-type constant; the server is authoritative. */
 export const EntryTypes = {
     MESSAGE: 'message',
     NOTIFICATION: 'notification',
@@ -43,7 +43,7 @@ export const EntryTypes = {
     /** @deprecated legacy alias for AGREEMENT_HISTORY */
     TASK_HISTORY: 'task_history',
 };
-/** ⚠️ SYNC: Keep in sync with backend src/chat/chat.types.ts CONTENT_TYPE */
+/** ⚠️ Mirrors the server's content-type constant; the server is authoritative. */
 export const ContentTypes = {
     TEXT: 'text',
     OPERATION: 'operation',
@@ -63,13 +63,13 @@ const VALID_CONTENT_TYPES = {
     [EntryTypes.AGREEMENT_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
     [EntryTypes.TASK_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
 };
-/** ⚠️ SYNC: Mirrors backend src/chat/chat.types.ts isValidContentType */
+/** ⚠️ Mirrors the server's entry/content-type validation; the server is authoritative. */
 export function isValidContentType(contentType, entryType) {
     return VALID_CONTENT_TYPES[entryType]?.includes(contentType) ?? false;
 }
-/** ⚠️ SYNC: Keep in sync with backend agreements.constants.ts. Fully-public broadcast sentinel. */
+/** ⚠️ Mirrors the server's sentinel. Fully-public broadcast target. */
 export const OPEN_AGREEMENT_TARGET = 'everyone';
-/** ⚠️ SYNC: backend ORG_AGREEMENT_TARGET. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
+/** ⚠️ Mirrors the server's sentinel. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
 export const ORG_AGREEMENT_TARGET = 'org';
 /** Both broadcast sentinels — values that occupy a party slot but are NOT real principal ids. */
 export const BROADCAST_TARGETS = [OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET];

package/package.json

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