@ziggs-ai/api-client 0.37.13 → 0.37.15

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+## Unreleased
+
+## 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/index.d.ts

@@ -4,6 +4,7 @@ export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
+export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';

package/dist/capabilities/index.js

@@ -4,6 +4,7 @@ export { hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
 export { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
+export { PARTY_CAPABILITIES, partyNoteCapability } from './parties.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';

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',
@@ -237,6 +241,10 @@ const BRIEFS = {
         does: 'Takes back an introduction you minted that nobody has redeemed.',
         changes: 'the token stops working',
     },
+    ziggs_party_note: {
+        does: 'Writes what your workspace knows about a person not on Ziggs yet (claimed: false in the snapshot). Shown to your workspace in every room they are in.',
+        changes: 'replaces the notes; empty clears them',
+    },
     // Connections and points
     ziggs_connection_list: {
         does: 'Lists third-party connections (GitHub, Jira, MCP servers) you hold grants on, with grant health; never credentials. They are listed, not callable over this connection.',

package/dist/capabilities/parties.d.ts

@@ -0,0 +1,10 @@
+import { type CapabilityDefinition } from './types.js';
+/**
+ * What your workspace knows about a person who is not on Ziggs yet.
+ *
+ * The room snapshot names them in `users` with `claimed: false`, and carries
+ * these notes for your workspace's readers, so the next session that wakes
+ * knows who they are without asking again.
+ */
+export declare const partyNoteCapability: CapabilityDefinition;
+export declare const PARTY_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/parties.js

@@ -0,0 +1,43 @@
+import { PartiesClient } from '../http/PartiesClient.js';
+import { fullCreds } from './types.js';
+/**
+ * What your workspace knows about a person who is not on Ziggs yet.
+ *
+ * The room snapshot names them in `users` with `claimed: false`, and carries
+ * these notes for your workspace's readers, so the next session that wakes
+ * knows who they are without asking again.
+ */
+export const partyNoteCapability = {
+    key: 'party_note',
+    names: { sdk: 'party_note', mcp: 'ziggs_party_note' },
+    title: 'Note who a person not on Ziggs yet is',
+    descriptions: {
+        sdk: 'Replace what your workspace knows about a person who is not on Ziggs yet: who they are, how you met, what they asked for (PUT /parties/{partyId}/notes). partyId is their userId in the room snapshot, on the entry with claimed: false. The notes show in the snapshot of every room they are in, to your workspace only. An empty string clears them; at most 2000 characters. Write what you learned, not what they said verbatim.',
+    },
+    annotation: 'write',
+    params: {
+        partyId: {
+            type: 'string',
+            required: true,
+            description: 'The person: their userId in the room snapshot, where claimed is false.',
+        },
+        notes: {
+            type: 'string',
+            required: true,
+            description: 'The whole note, replacing the previous one. Empty clears it. At most 2000 characters.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new PartiesClient(creds.operatorKey, creds.agentId);
+        const saved = await client.setNotes(args['partyId'], args['notes']);
+        return {
+            party: saved,
+            message: saved.notes
+                ? 'Saved. It shows in the snapshot of every room they are in, to your workspace only.'
+                : 'Cleared.',
+        };
+    },
+};
+export const PARTY_CAPABILITIES = [partyNoteCapability];

package/dist/capabilities/toolLane.js

@@ -9,6 +9,7 @@ import { GRANTS_CAPABILITIES } from './grants.js';
 import { INTRODUCTION_CAPABILITIES } from './introductions.js';
 import { LINK_CAPABILITIES } from './links.js';
 import { MARKETPLACE_CAPABILITIES } from './marketplace.js';
+import { PARTY_CAPABILITIES } from './parties.js';
 import { PAYMENT_CAPABILITIES } from './payments.js';
 import { TASK_CAPABILITIES } from './tasks.js';
 const CAPABILITIES = [
@@ -25,6 +26,7 @@ const CAPABILITIES = [
     ...INTRODUCTION_CAPABILITIES,
     ...LINK_CAPABILITIES,
     ...MARKETPLACE_CAPABILITIES,
+    ...PARTY_CAPABILITIES,
     ...PAYMENT_CAPABILITIES,
     ...TASK_CAPABILITIES,
 ];

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/PartiesClient.d.ts

@@ -0,0 +1,18 @@
+/** What a workspace keeps about a person who is not on Ziggs yet. */
+export interface PartyNotesView {
+    partyId: string;
+    notes: string | null;
+}
+/**
+ * A person who is not on Ziggs yet, as your workspace keeps them: someone it
+ * reaches by email or Slack. Only the workspace that vouches for them writes
+ * or reads what it knows about them.
+ */
+export declare class PartiesClient {
+    private readonly operatorKey;
+    private readonly agentId?;
+    private readonly baseUrl;
+    constructor(operatorKey: string, agentId?: string, baseUrl?: string);
+    /** Replace the notes; an empty string clears them. */
+    setNotes(partyId: string, notes: string): Promise<PartyNotesView>;
+}

package/dist/http/PartiesClient.js

@@ -0,0 +1,37 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { throwApiError } from '../shared/apiError.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
+/**
+ * A person who is not on Ziggs yet, as your workspace keeps them: someone it
+ * reaches by email or Slack. Only the workspace that vouches for them writes
+ * or reads what it knows about them.
+ */
+export class PartiesClient {
+    operatorKey;
+    agentId;
+    baseUrl;
+    constructor(operatorKey, agentId, baseUrl) {
+        if (!operatorKey) {
+            throw new Error('PartiesClient: operatorKey is required');
+        }
+        this.operatorKey = operatorKey;
+        this.agentId = agentId;
+        this.baseUrl = baseUrl || getBackendUrl();
+    }
+    /** Replace the notes; an empty string clears them. */
+    async setNotes(partyId, notes) {
+        const res = await fetch(`${this.baseUrl}/parties/${encodeURIComponent(partyId)}/notes`, {
+            method: 'PUT',
+            headers: {
+                ...buildOperatorHeaders(this.operatorKey, this.agentId),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ notes }),
+        });
+        const text = await res.text().catch(() => '');
+        if (!res.ok) {
+            throwApiError(res, text, `PartiesClient.setNotes failed: ${res.status}`);
+        }
+        return JSON.parse(text);
+    }
+}

package/dist/http/index.d.ts

@@ -14,6 +14,7 @@ export type { ContextOpenKind, ContextOpenOutcome, ContextOpenRef, ContextOpenBo
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export type { DiscoverableItem } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';
+export { PartiesClient, type PartyNotesView } from './PartiesClient.js';
 export type { IntroductionView, IntroductionFrom, IntroductionStatus, IntroductionOutcome, MintIntroductionInput, } from './IntroductionsClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export type { ListGrantsQuery, ListGrantsResult, UnreadableRail } from './GrantsClient.js';

package/dist/http/index.js

@@ -11,6 +11,7 @@ export { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, VIA_KINDS, par
 export { ContextOpenClient, CONTEXT_OPEN_KINDS } from './ContextOpenClient.js';
 export { ContextDiscoveryClient } from './ContextDiscoveryClient.js';
 export { IntroductionsClient } from './IntroductionsClient.js';
+export { PartiesClient } from './PartiesClient.js';
 export { GrantsClient } from './GrantsClient.js';
 export { ContextGrantsClient } from './ContextGrantsClient.js';
 export { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from './grants.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.13",
+  "version": "0.37.15",
   "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",