@ziggs-ai/api-client 0.17.1 → 0.18.0

package/dist/capabilities/chat.js

@@ -12,8 +12,8 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Open a chat',
     descriptions: {
-        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and the refusal names the levers. To list chats you can already read, use grant_list scopeKind=chat.',
-        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and names the levers.',
+        sdk: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat, so it is how you find the conversation you already have with someone — pass newChat only when this really is a separate subject. This is also how you reach the HUMAN who hired you when the work needs an answer only they have: pass their user id (context_snapshot lists it under users; on your agreement they are the payer/creator party), then chat_send in the chat it returns with no receiverId. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and the refusal names the levers. When the person you cannot reach is somebody YOUR OWN PERSON already knows — their teammate, their partner, their customer — none of those levers is the right one: ask the person you work for to open a room with them and add you, in plain words in your conversation with them, then stop until you are in it. Claiming a listing or sending an invite is for a stranger you are doing business with, and using it on somebody your person could introduce you to in two clicks costs them a negotiation instead. To list chats you can already read, use grant_list scopeKind=chat.',
+        mcp: 'Open or reuse a chat with a user or agent participant. Calling it again for the same participant returns the SAME chat; pass newChat only when this really is a separate subject. Opening a room is issuing the other side access to it, so it needs something that authorizes that: they publish a listing, you share an org, you hold a live agreement with them (a link counts, so ziggs_link_propose is how you get one with a peer in another org), or they claimed your invite. With none of those the call is refused and names the levers. When the person you cannot reach is somebody your own person already knows — their teammate, their partner, their customer — ask that person to open a room with them and add you, rather than reaching for a listing or an invite: those are for strangers you are doing business with.',
     },
     annotation: 'write',
     params: {

package/dist/http/AgreementClient.d.ts

@@ -88,6 +88,23 @@ export declare function linkSummary(a: Agreement): Record<string, unknown>;
  * Agreement field, so this narrows a document rather than returning a different
  * shape.
  */
+/**
+ * Lift the fields the wire nests, then summarise a link.
+ *
+ * `Agreement` offers `description`, `proposalStatus`, `lifecycle`,
+ * `expiresAt`, `maxExecutions` and `linkInvite` at the top level. The wire
+ * does not: it sends them under `terms` and `proposal`, and calls the seats
+ * `claimSeats`. This function is the only thing between the two and it used
+ * to map NONE of them, so every one of those reads answered `undefined` —
+ * silently, because the hand-written type promised they would be there.
+ *
+ * Filled here rather than by changing the type, because ~78 call sites across
+ * the SDK, ziggs-mcp and the agents read them at the top level. They keep
+ * reading them; they now get the value.
+ *
+ * The nested fields stay where the server put them. This adds a view, it does
+ * not move anything.
+ */
 export declare function shapeAgreement(a: Agreement): Agreement;
 /** @deprecated Alias for {@link ProposeDirectInput}. */
 export type ProposeAgreementData = ProposeDirectInput;

package/dist/http/AgreementClient.js

@@ -73,8 +73,56 @@ export function linkSummary(a) {
  * Agreement field, so this narrows a document rather than returning a different
  * shape.
  */
+/**
+ * Lift the fields the wire nests, then summarise a link.
+ *
+ * `Agreement` offers `description`, `proposalStatus`, `lifecycle`,
+ * `expiresAt`, `maxExecutions` and `linkInvite` at the top level. The wire
+ * does not: it sends them under `terms` and `proposal`, and calls the seats
+ * `claimSeats`. This function is the only thing between the two and it used
+ * to map NONE of them, so every one of those reads answered `undefined` —
+ * silently, because the hand-written type promised they would be there.
+ *
+ * Filled here rather than by changing the type, because ~78 call sites across
+ * the SDK, ziggs-mcp and the agents read them at the top level. They keep
+ * reading them; they now get the value.
+ *
+ * The nested fields stay where the server put them. This adds a view, it does
+ * not move anything.
+ */
 export function shapeAgreement(a) {
-    return a.engagementKind === 'link' ? linkSummary(a) : a;
+    const wire = a;
+    const lifted = {
+        ...a,
+        ...(wire.terms?.description != null
+            ? { description: wire.terms.description }
+            : {}),
+        ...(wire.terms?.lifecycle != null
+            ? { lifecycle: wire.terms.lifecycle }
+            : {}),
+        ...(wire.terms?.expiresAt != null
+            ? { expiresAt: wire.terms.expiresAt }
+            : {}),
+        ...(wire.terms?.maxExecutions != null
+            ? { maxExecutions: wire.terms.maxExecutions }
+            : {}),
+        ...(wire.proposal?.status != null
+            ? { proposalStatus: wire.proposal.status }
+            : {}),
+        ...(wire.claimSeats
+            ? {
+                linkInvite: {
+                    ...(wire.claimSeats.maxClaims != null
+                        ? { maxClaims: wire.claimSeats.maxClaims }
+                        : {}),
+                    claimsUsed: wire.claimSeats.claimsUsed,
+                },
+            }
+            : {}),
+    };
+    return lifted.engagementKind === 'link'
+        ? linkSummary(lifted)
+        : lifted;
 }
 export async function proposeAgreement(proposalData, creds) {
     if (!proposalData)

package/dist/http/ArtifactsClient.d.ts

@@ -1,3 +1,4 @@
+import type { ListReachableArtifactsResult } from '@ziggs-ai/contracts';
 /**
  * Inline `POST /artifacts` body cap (matches backend
  * `ARTIFACT_PUBLIC_TEXT_MAX_CHARS`). Over this → file rail or multi-part; the
@@ -22,10 +23,16 @@ export interface ListArtifactsQuery {
      */
     authoredBy?: 'me';
 }
-export interface ListArtifactsResult {
-    artifacts: unknown[];
-    latestSequence: string | null;
-}
+/**
+ * The reachable-artifact listing, as the server sends it.
+ *
+ * `truncated` was missing here, and it is the field that says the answer is
+ * incomplete — a caller typed against the old shape could not see that some
+ * sources were dropped, which is the same "short list read as a whole one"
+ * failure the grants rail names `unreadableRails` for. `artifacts` is also
+ * typed now, where it was `unknown[]`.
+ */
+export type ListArtifactsResult = ListReachableArtifactsResult;
 export interface WriteArtifactInput {
     text: string;
     /** Short list name. An upload defaults to filename when omitted. */

package/dist/http/ChatClient.d.ts

@@ -1,15 +1,18 @@
+import type { ChatReadDto } from '@ziggs-ai/contracts';
 import type { SendChatMessageResult } from '@ziggs-ai/contracts';
 import { type Creds } from '../types.js';
-/** Shape of GET /chats/mine items — the backend's ChatReadDto. */
-export interface ChatSummary {
-    chatId: string;
-    members: Array<{
-        principalId: string;
-        agentId: string | null;
-    }>;
-    orgId: string | null;
-    isOrgChat: boolean;
-}
+/**
+ * One room from `GET /chats/mine`, as the server sends it.
+ *
+ * The backend answers `toChatReadDto(...)`, so this is that type rather than
+ * a restatement of it. The restatement had drifted both ways: it declared
+ * `orgId` and `isOrgChat`, neither of which the wire carries — a caller
+ * branching on `isOrgChat` was branching on `undefined` — and it omitted
+ * seven fields the wire does send, including `name`, `updatedAt` and
+ * `lastMessage`, which are the ones this list exists to let an agent triage
+ * with without a second call.
+ */
+export type ChatSummary = ChatReadDto;
 export declare function openConversation(participantId: string, creds: Creds, { newChat, agreementId }?: {
     newChat?: boolean;
     agreementId?: string;
@@ -95,5 +98,5 @@ export declare class ChatClient {
     }>;
     addMember(input: AddChatMemberInput): Promise<AddChatMemberResult>;
     sendMessage(input: SendChatMessageInput): Promise<SendChatMessageResult>;
-    listMine(): Promise<ChatSummary[]>;
+    listMine(): Promise<ChatReadDto[]>;
 }

package/dist/http/GrantsClient.d.ts

@@ -31,20 +31,20 @@ export interface ListGrantsQuery {
  * presenting a short list as if it were complete). Replaces the client-side
  * mirror of the backend scope table + JWT decode (the retired grantRails.ts).
  */
-export interface UnreadableRail {
-    rail: 'context' | 'connection' | 'wallet';
-    requiredScope: string;
-}
-export interface ListGrantsResult {
-    items: GrantView[];
-    nextCursor: string | null;
-    hasMore: boolean;
-    /**
-     * Rails the caller can't read, per the backend. Absent when the backend
-     * predates or every requested rail was readable.
-     */
-    unreadableRails?: UnreadableRail[];
-}
+/**
+ * The wire's list, not this client's guess at it.
+ *
+ * This named three rails where the server has five, so a refusal on the
+ * `consent` or `inbox` rail did not typecheck as one — and the whole point of
+ * this field is that a short list must not read as an empty one.
+ */
+import type { UnreadableRail, ListGrantsResult } from '@ziggs-ai/contracts';
+export type { UnreadableRail };
+/**
+ * The unified grant listing. `unreadableRails` names the rails the caller
+ * could not read, so a short list is never mistaken for an empty one.
+ */
+export type { ListGrantsResult };
 /**
  * unified grant listing across every rail. `GET /grants` returns the
  * canonical GrantView for each grant the caller holds (or, admin-gated, a named

package/dist/http/InboxClient.d.ts

@@ -1,4 +1,4 @@
-import type { InboxAckResult, InboxEnvelope, InboxReadOptions } from '../types.js';
+import type { InboxAckResult, InboxEnvelope, InboxPeek, InboxReadOptions } from '../types.js';
 /**
  * The doorbell, not the door: references addressed to this agent
  * since its last ack — never content. Flow: inbox → read → act → ack
@@ -21,6 +21,11 @@ export declare class InboxClient {
     private headers;
     private inboxUrl;
     getInbox(opts?: InboxReadOptions): Promise<InboxEnvelope>;
+    /**
+     * Wait for assigned mail without taking the host lease.
+     * Still sends X-Ziggs-Instance; the server ignores it on this route.
+     */
+    peek(opts?: InboxReadOptions): Promise<InboxPeek>;
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
      * `resourceId` handled in `(priorAck, upTo]`. Monotonic

package/dist/http/InboxClient.js

@@ -56,6 +56,20 @@ export class InboxClient {
         }
         return JSON.parse(body);
     }
+    /**
+     * Wait for assigned mail without taking the host lease.
+     * Still sends X-Ziggs-Instance; the server ignores it on this route.
+     */
+    async peek(opts = {}) {
+        const res = await fetch(this.inboxUrl('/inbox/peek', opts), {
+            headers: this.headers(),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw pollSurfaceError('InboxClient.peek', res, body);
+        }
+        return JSON.parse(body);
+    }
     /**
      * Advance this agent's watermark — pass the envelope's `ackTo` plus every
      * `resourceId` handled in `(priorAck, upTo]`. Monotonic

package/dist/http/PaymentsClient.d.ts

@@ -14,14 +14,16 @@ export interface PaymentTransactionView {
     transactionId?: string;
     [key: string]: unknown;
 }
-/** A resolved wallet reference (GET /payments/wallets/resolve). */
-export interface WalletRef {
-    walletId?: string;
-    ownerId?: string;
-    currency?: string;
-    status?: string;
-    [key: string]: unknown;
-}
+/**
+ * A resolved wallet reference (GET /payments/wallets/resolve).
+ *
+ * The wire's shape, not a guess at it. This was all-optional with no `orgId`,
+ * so a caller could not tell a wallet that has no org from one whose org the
+ * client forgot to declare — and every field being optional meant TypeScript
+ * agreed with any misreading of the response.
+ */
+import type { WalletRef } from '@ziggs-ai/contracts';
+export type { WalletRef };
 export type TransferResult = {
     status: 'approval_required';
     approvalId: string | null;
@@ -43,10 +45,18 @@ export interface ReleaseResult {
     transaction?: PaymentTransactionView;
     [key: string]: unknown;
 }
+/**
+ * A payment grant as this rail answers it.
+ *
+ * `parentGrantId` is `string | null`, which is what the wire sends — it was
+ * `string | undefined` here, so a root grant's explicit `null` did not match
+ * the declared type and `parentGrantId === undefined` was a test for "is this
+ * a root grant" that never passed.
+ */
 export interface PaymentGrantView {
     grantId?: string;
     holderId?: string;
-    parentGrantId?: string;
+    parentGrantId?: string | null;
     caveats?: unknown[];
     expiresAt?: string | null;
     [key: string]: unknown;
@@ -75,6 +85,17 @@ export type WaitForApprovalResult = {
     status: 'rejected' | 'expired' | 'timeout';
     approval: PaymentApproval;
 };
+/**
+ * Who to pay on a transfer. Kind is declared by the caller — never inferred
+ * from id shape. A bare string is only a wallet id (`wal_…`).
+ */
+export type TransferPayee = string | {
+    walletId: string;
+} | {
+    agentId: string;
+} | {
+    userId: string;
+};
 /**
  * the one payments client for every surface (agent-sdk, ziggs-mcp,
  * scripts). Consolidates the former agent-sdk private ZiggsPayClient. Wallet
@@ -107,8 +128,13 @@ export declare class PaymentsClient {
         userId?: string;
         agentId?: string;
     }): Promise<WalletRef | null>;
+    /**
+     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
+     * user payees must name their kind.
+     */
+    private resolvePayeeWalletId;
     transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }: {
-        to: string;
+        to: TransferPayee;
         amount: number;
         idempotencyKey?: string;
         description?: string;

package/dist/http/PaymentsClient.js

@@ -61,20 +61,46 @@ export class PaymentsClient {
         const res = (await this._get(`/payments/wallets/resolve?${params}`));
         return res['wallet'] || null;
     }
+    /**
+     * Resolve `transfer.to` to a wallet id. String form is wallet-only; agent /
+     * user payees must name their kind.
+     */
+    async resolvePayeeWalletId(to) {
+        if (typeof to === 'string') {
+            const id = to.trim();
+            if (!id)
+                throw new Error('transfer: `to` is required');
+            if (id.startsWith('wal_'))
+                return id;
+            throw new Error('transfer: string `to` must be a wallet id (wal_…); pass { agentId } or { userId } for a principal');
+        }
+        if ('walletId' in to && typeof to.walletId === 'string' && to.walletId.trim()) {
+            return to.walletId.trim();
+        }
+        if ('agentId' in to && typeof to.agentId === 'string' && to.agentId.trim()) {
+            const w = await this.resolve({ agentId: to.agentId.trim() });
+            if (!w?.walletId) {
+                throw new Error(`transfer: could not resolve wallet for agent "${to.agentId}"`);
+            }
+            return w.walletId;
+        }
+        if ('userId' in to && typeof to.userId === 'string' && to.userId.trim()) {
+            const w = await this.resolve({ userId: to.userId.trim() });
+            if (!w?.walletId) {
+                throw new Error(`transfer: could not resolve wallet for user "${to.userId}"`);
+            }
+            return w.walletId;
+        }
+        throw new Error('transfer: `to` must be a wallet id (wal_…) or { walletId | agentId | userId }');
+    }
     async transfer({ to, amount, idempotencyKey, description, paymentGrantId, agreementId, }) {
-        if (!to)
+        if (to == null || to === '')
             throw new Error('transfer: `to` is required');
         if (!(Number.isInteger(amount) && amount > 0))
             throw new Error('transfer: `amount` must be a positive integer (cents)');
         // The recipient is resolved BEFORE choosing a grant: an `allowed_recipients`
         // caveat cannot be checked against a name the client has not resolved yet.
-        let toWalletId = to;
-        if (!to.startsWith('wal_')) {
-            const w = await this.resolve(to.startsWith('agent_') ? { agentId: to } : { userId: to });
-            if (!w?.walletId)
-                throw new Error(`transfer: could not resolve wallet for "${to}"`);
-            toWalletId = w.walletId;
-        }
+        const toWalletId = await this.resolvePayeeWalletId(to);
         // Choose the grant that covers this spend when the caller omitted one.
         // An explicit id still wins — a caller who names a grant means it.
         if (this.agentId && !paymentGrantId) {

package/dist/http/TaskClient.d.ts

@@ -72,6 +72,27 @@ export interface CreateTaskData {
     waitsOn?: string[];
     /** Atomically declare a native work graph beneath the returned root task. */
     graph?: CreateTaskGraphData;
+    /**
+     * When the answer stops being useful, ISO 8601. At the deadline
+     * the holder posts what it has and where it is stuck, and stops. A deadline
+     * already past is refused server-side.
+     */
+    dueAt?: string;
+    /**
+     * Reminder cadence and budget for work somebody has to be chased about
+     * Both halves are required together: a cadence with no budget is
+     * an open-ended wake loop, and one reminder is one wake, so the server
+     * refuses a half-filled rule rather than defaulting the missing half. Omit
+     * the whole object for a task nobody needs reminding about.
+     */
+    checkBack?: CreateTaskCheckBackData;
+}
+/** See {@link CreateTaskData.checkBack}. */
+export interface CreateTaskCheckBackData {
+    /** Minimum minutes between two reminders to the same person. */
+    everyMinutes: number;
+    /** Total reminders allowed per person asked, after the first ask. */
+    maxReminders: number;
 }
 export declare function createTask(taskData: CreateTaskData, creds: Creds): Promise<Task>;
 export declare function getTask(taskId: string, creds: Creds): Promise<Task>;

package/dist/http/grants.d.ts

@@ -46,45 +46,22 @@ export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "
  */
 export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "connection", "wallet", "consent", "inbox"];
 export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
-export interface GrantScopeView {
-    kind: GrantScopeKind;
-    id: string;
-    /**
-     * Human-readable name for the scoped resource, populated only by the unified
-     * list read (GET /grants / GrantsClient); the per-rail issue/delegate
-     * responses omit it. Optional so the one shape stays additive.
-     */
-    label?: string;
-}
-export interface GrantCaveatView {
-    type: string;
-    value: unknown;
-}
-export interface GrantView {
-    grantId: string;
-    issuerId: string;
-    holderId: string;
-    parentGrantId: string | null;
-    agreementId: string | null;
-    scope: GrantScopeView;
-    caveats: GrantCaveatView[];
-    revoked: boolean;
-    /** ISO-8601, or null for no expiry. */
-    expiresAt: string | null;
-    /** ISO-8601. */
-    createdAt: string;
-    health: GrantHealth;
-    /**
-     * 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;
-    };
-}
+/**
+ * The scope a grant is over, and one caveat on it — the wire's shapes.
+ *
+ * `label` is populated only by the unified list read; the per-rail
+ * issue/delegate responses omit it, which is why the contract has it optional.
+ */
+export type { GrantScopeView, GrantCaveatView };
+/**
+ * A grant row, exactly as the server sends it.
+ *
+ * Generated from the OpenAPI spec rather than restated here. Three copies of
+ * this shape lived in this package — this one, a looser one on
+ * `PaymentsClient`, and a third on `ConnectionsClient` — and each rail's
+ * client believed a different subset of the row.
+ */
+import type { GrantView, GrantScopeView, GrantCaveatView } from '@ziggs-ai/contracts';
+export type { GrantView };
 /** 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

@@ -20,7 +20,7 @@ export type { ContextGrantRecord, ContextGrantScope, ContextGrantScopeKind, Cont
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } 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 type { PaymentsError, WalletBalance, WalletRef, PaymentTransactionView, TransferPayee, TransferResult, HoldResult, ReleaseResult, PaymentGrantView, PaymentGrantEnvelope, RevokeGrantResult, PaymentApproval, WaitForApprovalResult, } from './PaymentsClient.js';
 export { ConnectionsClient, assertNoLeakedConnectionSecret, } from './ConnectionsClient.js';
 export type { ConnectionsError, ConnectionProxyParams, ConnectionGrant, ConnectionWithGrants, McpConnectionRequestParams, } from './ConnectionsClient.js';
 export { fetchMyOrgs, resolveOrgSelector, fetchDelegateAccess, fetchHostedAgentAccess, fetchSessionAccess, } from './OrgsClient.js';

package/dist/index.d.ts

@@ -10,7 +10,7 @@ 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, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxReadOptions, } 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 { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';

package/dist/shared/operatorKey.d.ts

@@ -1,3 +1,4 @@
+import { OPERATOR_KEY_ISSUED_VIA } from '@ziggs-ai/contracts';
 /** JWT payload fields we read client-side (signature not verified — identity hint only). */
 export interface OperatorKeyClaims {
     type?: string;
@@ -14,10 +15,20 @@ export interface OperatorKeyClaims {
 /** Decode operator JWT payload without verifying signature (boundAgentId). */
 export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
 export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export declare const ISSUED_VIA_MCP_OAUTH = "mcp_oauth";
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export declare const ISSUED_VIA_DEVICE_CODE = "device_code";
+/**
+ * The stamps the two consent rails put on the tokens they mint.
+ *
+ * Re-exported from the contract rather than restated here. This file used to
+ * declare the two strings it cared about while the server's list had six, so
+ * a rail added there was invisible here until somebody remembered — and the
+ * predicate below decides which tool surface a connected assistant gets, so
+ * forgetting would have served the whole catalogue to the new rail's
+ * credentials.
+ */
+export declare const ISSUED_VIA_MCP_OAUTH: "mcp_oauth";
+export declare const ISSUED_VIA_DEVICE_CODE: "device_code";
+export { OPERATOR_KEY_ISSUED_VIA };
+export type { OperatorKeyIssuedVia } from '@ziggs-ai/contracts';
 /**
  * Did a person board this credential through the connector directory?
  *

package/dist/shared/operatorKey.js

@@ -1,3 +1,4 @@
+import { OPERATOR_KEY_ISSUED_VIA, isDirectoryBoardedIssuedVia, } from '@ziggs-ai/contracts';
 /** Decode operator JWT payload without verifying signature (boundAgentId). */
 export function decodeOperatorKeyClaims(token) {
     const trimmed = token.trim();
@@ -26,10 +27,19 @@ export function isOperatorKeyExpired(claims) {
         return false;
     return claims.exp * 1000 <= Date.now();
 }
-/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
-export const ISSUED_VIA_MCP_OAUTH = 'mcp_oauth';
-/** The stamp the MCP OAuth device-code flow puts on its tokens. */
-export const ISSUED_VIA_DEVICE_CODE = 'device_code';
+/**
+ * The stamps the two consent rails put on the tokens they mint.
+ *
+ * Re-exported from the contract rather than restated here. This file used to
+ * declare the two strings it cared about while the server's list had six, so
+ * a rail added there was invisible here until somebody remembered — and the
+ * predicate below decides which tool surface a connected assistant gets, so
+ * forgetting would have served the whole catalogue to the new rail's
+ * credentials.
+ */
+export const ISSUED_VIA_MCP_OAUTH = OPERATOR_KEY_ISSUED_VIA.MCP_OAUTH;
+export const ISSUED_VIA_DEVICE_CODE = OPERATOR_KEY_ISSUED_VIA.DEVICE_CODE;
+export { OPERATOR_KEY_ISSUED_VIA };
 /**
  * Did a person board this credential through the connector directory?
  *
@@ -52,8 +62,9 @@ export const ISSUED_VIA_DEVICE_CODE = 'device_code';
  * is PERMITTED.
  */
 export function isDirectoryBoarded(claims) {
-    return (claims?.issuedVia === ISSUED_VIA_MCP_OAUTH ||
-        claims?.issuedVia === ISSUED_VIA_DEVICE_CODE);
+    // The set of boarding rails is the contract's, for the reason above: two
+    // copies of "which rails board an assistant" is how one of them goes stale.
+    return isDirectoryBoardedIssuedVia(claims?.issuedVia);
 }
 /** Routing hint only. Every request is still authenticated by the backend. */
 export function isMcpOAuthDelegateSession(creds) {

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementPartySide, AgreementParties, PrincipalPresentation, InboxDeliveryRef } from '@ziggs-ai/contracts';
 import type { InboxRequestChannel } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
@@ -102,6 +103,21 @@ export interface Task {
         steps?: PlanStep[];
     };
     planReview?: unknown;
+    /**
+     * When the answer stops being useful. At this point the holder
+     * posts what it has and where it is stuck, and stops. Absent or null on a
+     * task nobody has to chase.
+     */
+    dueAt?: string | null;
+    /**
+     * How often the holder may remind, and how many times at most.
+     * `everyMinutes` is a floor, not a schedule: remind later, never sooner.
+     * The budget is per person asked, after the first ask.
+     */
+    checkBack?: {
+        everyMinutes: number;
+        maxReminders: number;
+    } | null;
     history?: unknown[];
     creatorIsYou?: boolean;
     providerIsYou?: boolean;
@@ -119,30 +135,17 @@ export declare const AGREEMENT_ENGAGEMENT_KIND: {
 };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
 /**
- * One side of an agreement.
+ * One side of an agreement, as the wire carries it.
  *
- * An agent id occupies `actor` and nowhere else, so "is this agent on this
- * side?" is a structural read rather than a lookup against the Agent
- * collection. Asking `principal` about an agent id is always the wrong
- * question — it would match that agent's estate instead.
+ * `principal` is the accountable person or org — never an agent. On `payer`
+ * and `proposedTo` it may instead hold a broadcast sentinel
+ * ({@link isBroadcastTarget}), in which case nobody has taken the side up yet.
+ * `actor` is the agent that performed on this side, null when the principal
+ * acted itself.
  */
-export interface AgreementPartySide {
-    /**
-     * The accountable person or org — never an agent. On `payer` and `proposedTo`
-     * this may instead hold a broadcast sentinel ({@link isBroadcastTarget}), in
-     * which case nobody has taken the side up yet.
-     */
-    principal?: string | null;
-    /** The agent that performed on this side. Null when the principal acted itself. */
-    actor?: string | null;
-}
+export type { AgreementPartySide };
 /** The four sides of an agreement, each {@link AgreementPartySide}. */
-export interface AgreementParties {
-    payer?: AgreementPartySide;
-    provider?: AgreementPartySide;
-    proposedTo?: AgreementPartySide;
-    creator?: AgreementPartySide;
-}
+export type { AgreementParties };
 /** Both ids on one side, principal first, absent ones dropped. */
 export declare function partySideIds(side: AgreementPartySide | null | undefined): string[];
 /**
@@ -172,6 +175,8 @@ export interface AgreementApprovalEntry {
 }
 export interface Agreement {
     agreementId: string;
+    parentAgreementId?: string | null;
+    rootAgreementId?: string | null;
     description?: string;
     status?: AgreementStatus;
     engagementKind?: EngagementKind;
@@ -270,22 +275,7 @@ export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
 export declare function isBroadcastTarget(id: string | null | undefined): boolean;
 export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';
 /** Display + entitlement face for a principal on the message/roster wire. */
-export interface PrincipalPresentation {
-    /** Public, non-addressable reference (`psn_*` or `rpb_*`). */
-    ref?: string;
-    persona: {
-        id: string;
-        name: string;
-        image?: string | null;
-        revision?: number;
-    };
-    mode: 'persona' | 'chain';
-    /** Present only when the viewer is entitled to resolve the subject. */
-    subject?: {
-        id: string;
-        type: 'user' | 'agent';
-    };
-}
+export type { PrincipalPresentation };
 export interface MessageMetadata {
     chatId: string;
     /** Stable id for dedup across push + inbox catch-up. */
@@ -355,42 +345,8 @@ export interface InboxSourceRef {
     partyId: string;
     partyKind: InboxPartyKind;
 }
-/**
- * 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;
-    /** Who wrote it. Never this agent — you are not woken by your own writes. */
-    actorId: string | null;
-    ts: string;
-    /**
-     * lifecycle hint when the server includes one (e.g.
-     * `connection_request_fulfilled`). Absent on ordinary doorbells / older servers.
-     */
-    reason?: string | null;
-    /** MCP connection after a fulfilled first-hop request. */
-    connectionId?: string | null;
-    /** grant minted for this agent on fulfill. */
-    grantId?: string | null;
-}
+/** One delivery in a mailbox, as the wire carries it. */
+export type { InboxDeliveryRef };
 /** Message/artifact deliveries folded by chat, so you can open chats directly. */
 export interface InboxChatNews {
     chatId: string;
@@ -520,3 +476,8 @@ export interface InboxAckResult {
 export interface InboxReadOptions {
     waitSeconds?: number;
 }
+/** Count-only peek. Does not take the inbox host lease. */
+export interface InboxPeek {
+    asOf: string;
+    count: number;
+}

package/dist/types.js

@@ -47,6 +47,7 @@ export function partySideIds(side) {
  * so widening the match to `principal` would hit an unrelated estate.
  */
 export function partyActorIds(parties) {
+    // The wire always sends all four sides; a caller may still hand us nothing.
     const p = parties ?? {};
     return [
         ...new Set(AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => typeof id === 'string' && id.length > 0)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "socket.io-client": "^4.7.0",
-    "@ziggs-ai/contracts": "^0.6.0"
+    "@ziggs-ai/contracts": "^0.7.1"
   },
   "keywords": [
     "ziggs",