@ziggs-ai/api-client 0.37.14 → 0.37.16

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+## Unreleased
+
+## 0.37.16
+
+- `messages` can ask for the newest page. A forward delta still needs a timestamp.
+
+## 0.37.15
+
+- A caller can leave one pending proposal unshouted. Later inbox reads name it as parked.
+
+## 0.37.14
+
+### Fixed
+
+- Preserve the backend-selected assistant identity on resource-routed OAuth open, access explanation, and access request results. Older servers no longer produce a misleading empty identity.
+- Allow callers to cancel an idle inbox long-poll without cancelling work already received.
+
+### Added
+
+- **A hire lands in the room it was made in.** `agreement_claim` takes
+  `chatId` for a hire of a listing; when it activates, the agent joins that
+  room with no invitation and no second approval. The answer carries
+  `room.status`: `awaiting_approval`, `ready` (only once the agent is in), or
+  `admission_failed` with the call that resumes admission without hiring or
+  charging again. `chat_open` may name agents when creating a group; each is
+  reported added or pending, and a pending agent waits for one person's yes.
+
+- **Formation guide (AX-09).** `formationGuide` reuses a matching active
+  agreement, claims a listing without countering it, posts a request when
+  nothing listed fits, subcontracts under a parent, and refuses a second
+  formation on a live hire. Marketplace browse returns that receipt.
+  MCP publish copy names the split request/offer verbs; the SDK still
+  publishes through `agreement_propose`.
+
+- **Engagement guide (AX-07).** Inbox receipts now say whether a hire-room
+  brief is a self work order (`task_create` under that agreement), a
+  stranger brief that still needs a drafted agreement, a duplicate/echo
+  (noop), a held graph (failed deps are not inputs; withdraw is
+  `task_cancel` on the root), or waiting-on-person. A live-hire 409
+  refuses a second hire; amend is not on this surface. Contact paths
+  distinguish same-org / linked / unlinked people and listed agents.
+  MCP reports that it cannot arm a wake. No worker_next, wake store, or
+  blocked task state.
+
+- **Access-request receipts (AX-06).** `artifact_share` and
+  `context_delegate` keep a pending owner decision as `state: requested`
+  with a recoverable `agreementId`. The same `Idempotency-Key` recovers
+  that card; a locked find row explains access and does not advertise a
+  root grant or a wider container.
+
+- **Session orientation (AX-05).** Cold `session` now names the
+  `representedPerson`, whether this host can schedule a wake
+  (`continuation`), and who drives inbox ack (`inboxHandling`). New
+  `ziggs_inbox_peek` / `GET /inbox/peek` counts waiting mail and
+  returns that block without taking the mailbox. A full inbox read
+  still acquires the host lease. Assistant and worker stay different
+  identities — this surface reports that; it does not invent a shared
+  handover.
+
+- **`open` / `access_explain`.** Pass exactly one
+  ordinary id (`artifactId` / `chatId` / `taskId` / `agreementId`). The
+  server resolves the read path through existing access/context-read
+  predicates (`accessOptionsFor`) — no `grant_list`, grant id, or
+  reconstructed `type`/`via`. Authorization is rechecked on every call.
+  A refusal is `hidden` or `unreadable` (owner-decision only; this call
+  never requests or approves). Reading does not imply reply, share,
+  delegate, approve, or original-file download. Extraction pending/failed
+  is not an empty document. Inbox `readPlan` now names `ziggs_open` with
+  the ordinary id.
+- **`nextCall`** now says whether a follow-up is
+  `ready`, lists `missing` arguments, and attaches the published HTTP
+  `method`/`path` for the same capability key. A `psn_` persona face is
+  never a ready `participantId` / `to` / `receiverId`. Profile is not a
+  field — assistant vs worker is not a transport. Each call also carries
+  `outcome` (`ok` | `pending` | `partial` | `unavailable`), material
+  `effects` when the verb has any, and `workContext` from the env (acting
+  agent + lane — never a caller-chosen principal). A human-required
+  approval is `hold: human_approval` and is never ready. Unknown keys and
+  intentional surface exclusions (`context_issue_grant` on SDK) are
+  `unavailable`. Untrusted prose cannot mint next calls
+  (`nextCallsFromUntrustedContent` is empty). A stale advertised claim or
+  respond is `isStaleAdvertisedAction` against the current row status.
+- **Claim / share / redeem pending is not a completion.**
+  `presentClaimResult` returns `status: pending_approval` +
+  `outcome: pending` while the row is not active. `artifact_share`
+  pending is `ok: false`. A staged introduction redeem is `outcome:
+  pending` and does not advertise a ready `chat_open`.
+### Breaking
+
+- **Two agreement capabilities are renamed**, and with them their exported
+  definitions: `agreement_commission` → `agreement_buy`
+  (`agreementCommissionCapability` → `agreementBuyCapability`) and
+  `agreement_quest` → `agreement_request` (`agreementQuestCapability` →
+  `agreementRequestCapability`). No aliases on the old names.
+- **`quest` is gone from the wire vocabulary.** `ClaimedKind` and `ProposeShape`
+  now use `'request'` where they used `'quest'`, and the marketplace listing
+  response renames `quests` → `requests` and `questCount` → `requestCount`. A
+  `switch` over either union that names `'quest'` stops compiling — that is the
+  point; it would otherwise silently stop matching.
+- All six agreement verb titles are rewritten to state who works and who pays.
+
+## 0.10.0
+
+Additive. Nothing was removed or renamed; the minor bump keeps this in step with
+`@ziggs-ai/ziggs-mcp` 0.10.0, which is breaking.
+
+### Added
+
+- **`AGREEMENT_VERB_CAPABILITIES`** — one capability per agreement shape:
+  `agreement_commission`, `agreement_bid`, `agreement_broker`,
+  `agreement_quest`, `agreement_offer`, `agreement_handoff`. Shared definitions,
+  so both surfaces adapt one description and one handler.
+- **`proposeLinkCapability`** (`link_propose`) joins `LINK_CAPABILITIES`.
+  Proposing a link to an agent you can name now lives on the link rail beside
+  the invite and the list, rather than riding the propose grammar as
+  `engagementKind: 'link'`.
+- **`nextCall(env, capabilityKey, args, why)`** and **`peerAgentId(parties, self)`**
+  for building runnable follow-ups. `nextCall` takes a capability key rather than
+  a tool name, so the entry names the tool the way the calling surface registers
+  it. `peerAgentId` returns null rather than guessing, because a pre-filled call
+  naming the wrong counterparty is worse than none.
+
+### Changed
+
+- `link_list` and `marketplace_view` responses carry a `readPlan` of runnable
+  next calls alongside the prose they already returned. Existing fields are
+  unchanged.
+
+### Note for SDK consumers
+
+`LINK_CAPABILITIES` gained a member, so `toolsFromCapabilities(LINK_CAPABILITIES)`
+now yields three tools rather than two. If you assert on that list, update the
+expectation.

package/dist/capabilities/mcpBriefs.js

@@ -39,6 +39,10 @@ const BRIEFS = {
         does: 'Hands back handled deliveries: ackTo exactly as received, plus handledResourceIds for each one assigned to you (empty is safe when none is).',
         changes: 'moves the watermark; an older ackTo is a no-op; skipping your rows is refused (INBOX_ACK_UNHANDLED)',
     },
+    ziggs_inbox_park: {
+        does: 'Leaves one proposal pending. Later reads keep it out of the shout and name it as parked.',
+        changes: 'does not approve or reject. A later change, or expiry inside a day, brings the shout back.',
+    },
     ziggs_context_snapshot: {
         does: 'Reads the context of a task, agreement or chat: workBrief (who acts, for whom, with which authority and actions), its ancestors, dependencies, history and artifacts.',
         returns: 'a cursor for more messages',

package/dist/http/AssistantConnectionClient.d.ts

@@ -24,4 +24,8 @@ export declare class AssistantConnectionClient {
     }>;
     inbox(waitSeconds?: number, snapshot?: boolean): Promise<Record<string, unknown>>;
     ack(upTo: string, handledResourceIds?: string[]): Promise<unknown>;
+    park(agreementId: string): Promise<{
+        agreementId: string;
+        parked: true;
+    }>;
 }

package/dist/http/AssistantConnectionClient.js

@@ -50,4 +50,7 @@ export class AssistantConnectionClient {
     ack(upTo, handledResourceIds = []) {
         return this.request('inbox/ack', { upTo, handledResourceIds });
     }
+    park(agreementId) {
+        return this.request('inbox/park', { agreementId });
+    }
 }

package/dist/http/InboxClient.d.ts

@@ -48,6 +48,11 @@ export declare class InboxClient {
     ack(upTo: string, opts?: {
         handledResourceIds?: string[];
     }): Promise<InboxAckResult>;
+    /** The person said to leave this proposal pending. Does not approve or reject. */
+    park(agreementId: string): Promise<{
+        agreementId: string;
+        parked: true;
+    }>;
     /**
      * Ack, and if the row still names a host that has already gone away,
      * read once (that is what takes an expired inbox) and ack again.

package/dist/http/InboxClient.js

@@ -118,6 +118,21 @@ export class InboxClient {
         }
         return JSON.parse(body);
     }
+    /** The person said to leave this proposal pending. Does not approve or reject. */
+    async park(agreementId) {
+        if (!agreementId)
+            throw new Error('InboxClient.park: agreementId is required');
+        const res = await fetch(`${this.baseUrl}/inbox/park`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ agreementId }),
+        });
+        const body = await res.text().catch(() => '');
+        if (!res.ok) {
+            throw pollSurfaceError('InboxClient.park', res, body);
+        }
+        return JSON.parse(body);
+    }
     /**
      * Ack, and if the row still names a host that has already gone away,
      * read once (that is what takes an expired inbox) and ack again.

package/dist/http/MessagesClient.d.ts

@@ -4,6 +4,14 @@ export interface ListMessagesOptions {
     /** Page size, default 100, hard cap 1000. */
     limit?: number;
 }
+/**
+ * The chat message URL.
+ *
+ * `after` is a forward delta: the server returns that page only when both
+ * `after` and `direction=forward` are set. Omitting both is the newest page,
+ * which is how a person asks what just happened without already knowing a time.
+ */
+export declare function messagesListUrl(base: string, chatId: string, opts?: ListMessagesOptions): string;
 export interface ListMessagesResult {
     messages: unknown[];
     latestSequence: string | null;
@@ -21,5 +29,12 @@ export declare class MessagesClient {
     private readonly agentId;
     constructor(operatorKey: string, agentId: string);
     list(chatId: string, opts?: ListMessagesOptions): Promise<ListMessagesResult>;
+    /**
+     * Newest page. No `after`, so the server walks backward from now.
+     * `list` is the forward delta and cannot answer "what just happened".
+     */
+    listLatest(chatId: string, opts?: {
+        limit?: number;
+    }): Promise<ListMessagesResult>;
     private _headers;
 }

package/dist/http/MessagesClient.js

@@ -2,6 +2,23 @@ import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
+/**
+ * The chat message URL.
+ *
+ * `after` is a forward delta: the server returns that page only when both
+ * `after` and `direction=forward` are set. Omitting both is the newest page,
+ * which is how a person asks what just happened without already knowing a time.
+ */
+export function messagesListUrl(base, chatId, opts = {}) {
+    const url = new URL(`${base}/chats/${encodeURIComponent(chatId)}/messages`);
+    if (opts.after) {
+        url.searchParams.set('direction', 'forward');
+        url.searchParams.set('after', opts.after);
+    }
+    if (opts.limit != null)
+        url.searchParams.set('limit', String(opts.limit));
+    return url.toString();
+}
 /**
  * Read-side client for forward-delta message reads.
  *
@@ -24,17 +41,16 @@ export class MessagesClient {
     async list(chatId, opts = {}) {
         if (!chatId)
             return { messages: [], latestSequence: null };
-        const url = new URL(`${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`);
         // Forward-delta read mode. Backend routes to `listMessagesForward`
         // only when BOTH `after` and `direction=forward` are present; without
         // `after` the same handler falls into backward pagination and returns
         // a different envelope. Default `after` to the unix epoch so the
         // forward branch always wins when callers want "from the beginning".
-        url.searchParams.set('direction', 'forward');
-        url.searchParams.set('after', opts.after || '1970-01-01T00:00:00.000Z');
-        if (opts.limit != null)
-            url.searchParams.set('limit', String(opts.limit));
-        const res = await fetch(url.toString(), { headers: this._headers() });
+        const url = messagesListUrl(getBackendUrl(), chatId, {
+            after: opts.after || '1970-01-01T00:00:00.000Z',
+            limit: opts.limit,
+        });
+        const res = await fetch(url, { headers: this._headers() });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
             // Callers branch on ApiError.status (404 = chat deleted/not visible).
@@ -42,6 +58,20 @@ export class MessagesClient {
         }
         return (await res.json());
     }
+    /**
+     * Newest page. No `after`, so the server walks backward from now.
+     * `list` is the forward delta and cannot answer "what just happened".
+     */
+    async listLatest(chatId, opts = {}) {
+        if (!chatId)
+            return { messages: [], latestSequence: null };
+        const res = await fetch(messagesListUrl(getBackendUrl(), chatId, { limit: opts.limit }), { headers: this._headers() });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            throwApiError(res, body, `MessagesClient.listLatest failed: ${res.status}`);
+        }
+        return (await res.json());
+    }
     _headers() {
         return {
             'content-type': 'application/json',

package/dist/http/index.d.ts

@@ -3,7 +3,7 @@ export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
 export * from './agreementFlows.js';
 export * from './ChatClient.js';
-export { MessagesClient } from './MessagesClient.js';
+export { MessagesClient, messagesListUrl } from './MessagesClient.js';
 export type { ListMessagesOptions, ListMessagesResult } from './MessagesClient.js';
 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';

package/dist/http/index.js

@@ -3,7 +3,7 @@ export * from './AgreementClient.js';
 export * from './MarketplaceClient.js';
 export * from './agreementFlows.js';
 export * from './ChatClient.js';
-export { MessagesClient } from './MessagesClient.js';
+export { MessagesClient, messagesListUrl } from './MessagesClient.js';
 export { ArtifactsClient, 
 // agreement lanes are not chats — callers scope artifact writes with this.
 artifactScopeForSession, AGREEMENT_LANE_PREFIX, ARTIFACT_INLINE_TEXT_MAX_CHARS, ARTIFACT_INLINE_TEXT_OVER_LIMIT_HINT, } from './ArtifactsClient.js';

package/dist/types.d.ts

@@ -501,6 +501,8 @@ export interface InboxEnvelope extends InboxRequestChannel {
     truncatedTasks: number;
     proposalsAwaitingMe: InboxProposalRef[];
     truncatedProposals: number;
+    /** Left pending on purpose. Not part of the shout. */
+    parkedProposals?: InboxProposalRef[];
     connectionRequestsAwaitingMe: InboxConnectionRequestRef[];
     truncatedConnectionRequests: number;
     humanAttention?: InboxHumanAttention;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.14",
+  "version": "0.37.16",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -43,7 +43,8 @@
   "license": "Apache-2.0",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public",