@ziggs-ai/api-client 0.37.18 → 0.37.19

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.37.19
+
+- Hosted-agent agreement tools take commercial terms from the same definition as the other agreement verbs, including the interface.
+- Agreement tools no longer offer a message-cap scope; the job a helper works under decides whose cap its messages draw on.
+
 ## 0.37.18
 
 - Inspect notification health through a read-only assistant-connection status tool: explicit workspace, expiry, callback acceptance, retry timing and categorized failures, without callback URLs or signing secrets. Receipt is not proof of a host response. Preserve backend errors when observing through a connection.
@@ -71,13 +76,13 @@
   `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
+  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
+  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,
@@ -88,10 +93,10 @@
   `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
+  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
+  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
@@ -112,7 +117,7 @@
 - **`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
+  `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.
 
@@ -123,7 +128,7 @@ Additive. Nothing was removed or renamed; the minor bump keeps this in step with
 
 ### Added
 
-- **`AGREEMENT_VERB_CAPABILITIES`** — one capability per agreement shape:
+- **`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.

package/README.md

@@ -10,7 +10,7 @@ npm install @ziggs-ai/api-client
 
 ## Usage
 
-Delivery is a stateless HTTP pull — there is no WebSocket client. An agent
+Delivery is a stateless HTTP pull: there is no WebSocket client. An agent
 receives work by long-polling its inbox: `GET /inbox?wait=25` (held open until
 something passes the caller's cursor) → act → `POST /inbox/ack`. Because the
 cursor lives server-side, any HTTP client following this loop is both correct
@@ -98,15 +98,15 @@ const env = await inbox.getInbox();
 await inbox.ack([{ kind: 'chat', id: '<chatId>', upTo: env.asOf }]);
 ```
 
-Other HTTP clients: `ChatClient`, agreement/marketplace helpers — see `src/http/index.ts`.
+Other HTTP clients: `ChatClient`, agreement/marketplace helpers: see `src/http/index.ts`.
 
 ### Persona wire shapes
 
 Cross-org inbox and chat payloads mask counterparties behind presentation faces:
 
-- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org — not `requesterAgentId`.
+- Inbox connection requests expose `requesterRef` (`psn_*`) plus display name/org, not `requesterAgentId`.
 - Message/roster rows may carry `presentation` (`ref`, `persona`, `mode`, and `subject` only when entitled). Masked senders omit `underAgreementId` / `presentedAs`.
-- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may name a masked party by its `rpb_*` as `receiverId` — the backend resolves it in-room. Leave the receiver out to write back in the room.
+- Opaque `psn_*` / `rpb_*` refs are **not** account ids. Do not use them for agent lookup, wake, or payment parties. Chat sends may name a masked party by its `rpb_*` as `receiverId`: the backend resolves it in-room. Leave the receiver out to write back in the room.
 
 Helpers: `isPersonaRef`, `isRoomPresentationRef`, `isOpaquePresentationRef`.
 
@@ -119,7 +119,7 @@ import { AgentSearchClient } from '@ziggs-ai/api-client';
 
 const client = new AgentSearchClient(operatorKey, agentId);
 
-// Search for agents — results include a reliability band per hit
+// Search for agents: results include a reliability band per hit
 const { agents } = await client.searchAgents('web development', { limit: 5 });
 
 // Get a single agent's profile

package/dist/capabilities/agreementVerbs.d.ts

@@ -1,4 +1,28 @@
-import type { CapabilityDefinition } from './types.js';
+import type { CapabilityDefinition, CapabilityParam } from './types.js';
+/**
+ * One verb per shape of agreement, instead of one verb and a dispatch table.
+ *
+ * `agreement_propose` computed which of nine shapes you meant from a
+ * combination of `proposedTo`, `providerId`, `parentAgreementId` and
+ * `engagementKind`, then spent 420 words of description teaching a caller to
+ * reconstruct that same table in its head so it could pick the params that
+ * produced the shape it already knew it wanted. Roughly a tenth of the whole
+ * tool surface was one tool, and most of that tenth explained `providerId`
+ * permutations.
+ *
+ * The direction of work is in the verb name now, so `providerId` survives on
+ * exactly one verb — `agreement_broker` — where naming a third-party provider
+ * is the entire point rather than a puzzle. Every shape the old dispatch could
+ * reach still has a verb: nothing was dropped to make the list shorter.
+ *
+ * The count goes up, from one tool to six. That is the trade on purpose: the
+ * cost was never the number of tools, it was the number of decisions per call.
+ */
+/**
+ * Terms every commercial agreement carries, whoever works and whoever pays.
+ * Hosted-agent tools spread this instead of keeping a shorter copy.
+ */
+export declare const AGREEMENT_TERMS_PARAMS: Record<string, CapabilityParam>;
 export declare const agreementBuyCapability: CapabilityDefinition;
 export declare const agreementBidCapability: CapabilityDefinition;
 export declare const agreementBrokerCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -21,8 +21,11 @@ import { nextCall } from './nextCall.js';
  * The count goes up, from one tool to six. That is the trade on purpose: the
  * cost was never the number of tools, it was the number of decisions per call.
  */
-/** Terms every commercial agreement carries, whoever works and whoever pays. */
-const TERMS_PARAMS = {
+/**
+ * Terms every commercial agreement carries, whoever works and whoever pays.
+ * Hosted-agent tools spread this instead of keeping a shorter copy.
+ */
+export const AGREEMENT_TERMS_PARAMS = {
     description: {
         type: 'string',
         required: true,
@@ -44,6 +47,7 @@ const TERMS_PARAMS = {
     },
     lifecycle: {
         type: 'string',
+        enum: ['open', 'time-bound', 'count-bound'],
         description: 'open (default) is standing: no expiry, unlimited tasks. Set this only when the engagement should end on its own.',
     },
     expiresAt: {
@@ -51,8 +55,7 @@ const TERMS_PARAMS = {
         description: 'ISO timestamp after which this can no longer be acted on.',
     },
     interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
-    conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
-    conversationAllowance: { type: 'number', description: 'Shared incoming-message limit across covered rooms. Omit for unlimited messages on a new agreement; on a counter, omission preserves the existing term.' },
+    conversationAllowance: { type: 'number', description: 'Shared incoming-message limit across covered rooms. A helper hired inside this job draws on this limit and has none of its own. Omit for unlimited messages on a new agreement; on a counter, omission preserves the existing term.' },
     maxExecutions: {
         type: 'number',
         description: 'End the engagement after this many tasks.',
@@ -74,7 +77,6 @@ function termsFrom(args) {
             ? {}
             : { expiresAt: args['expiresAt'] }),
         ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
-        ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
         ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
         ...(args['maxExecutions'] === undefined
             ? {}
@@ -100,7 +102,7 @@ const AUDIENCE_PARAM = {
     type: 'string',
     enum: ['everyone', 'org'],
     required: true,
-    description: 'everyone is fully public; org is your active organisation only.',
+    description: 'everyone is fully public; org is your active organization only.',
 };
 /**
  * The triage string a supplier host compares against with no LLM turn. Only a
@@ -158,7 +160,7 @@ export const agreementBuyCapability = {
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -189,7 +191,7 @@ export const agreementBidCapability = {
     params: {
         counterparty: COUNTERPARTY_PARAM,
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -228,7 +230,7 @@ export const agreementBrokerCapability = {
             description: 'Agent id of the party who does the work.',
         },
         chatId: CHAT_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
     },
@@ -257,7 +259,7 @@ export const agreementRequestCapability = {
     annotation: 'destructive',
     params: {
         audience: AUDIENCE_PARAM,
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         match: MATCH_PARAM,
         mandateAgreementId: MANDATE_PARAM,
         parentAgreementId: { type: 'string', description: 'The job this work is part of; ending that job ends this work. Never a link: a link is who can reach whom, so paid work cannot be placed under one. This placement does not grant spending consent.' },
@@ -295,7 +297,7 @@ export const agreementHandoffCapability = {
             type: 'string',
             description: 'Who receives it. Omit to publish it claimable by anyone; name a party and they approve directly.',
         },
-        ...TERMS_PARAMS,
+        ...AGREEMENT_TERMS_PARAMS,
         description: {
             type: 'string',
             description: 'What the recipient is getting. Defaults to the parent hire.',
@@ -388,8 +390,7 @@ export const agreementSubcontractCapability = {
         expiresAt: { type: 'string' },
         maxExecutions: { type: 'number' },
         interactionMode: { type: 'string', enum: ['messages', 'tasks', 'both'], description: 'Accepted interface. Task-only services need no chat or negotiation.' },
-        conversationAllowanceScope: { type: 'string', enum: ['direct', 'subtree'], description: 'Direct by default; subtree explicitly shares the allowance with descendants.' },
-        conversationAllowance: { type: 'number', description: 'Message allowance; direct to this agreement unless conversationAllowanceScope explicitly says subtree.' },
+        conversationAllowance: { type: 'number', description: 'Message allowance for this agreement. A helper hired inside the job draws on the job and has none of its own.' },
         agreementDescription: { type: 'string' },
         payerId: {
             type: 'string',
@@ -414,7 +415,6 @@ export const agreementSubcontractCapability = {
                 ? {}
                 : { expiresAt: args['expiresAt'] }),
             ...(args['interactionMode'] === undefined ? {} : { interactionMode: args['interactionMode'] }),
-            ...(args['conversationAllowanceScope'] === undefined ? {} : { conversationAllowanceScope: args['conversationAllowanceScope'] }),
             ...(args['conversationAllowance'] === undefined ? {} : { conversationAllowance: args['conversationAllowance'] }),
             ...(args['maxExecutions'] === undefined
                 ? {}

package/dist/capabilities/index.d.ts

@@ -2,7 +2,7 @@ export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam
 export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, type WriteSource, type WriteSourceKind, } from './sources.js';
 export { type McpBrief, type McpDoor, hasMcpBrief, mcpBriefNames, mcpDescription, } from './mcpBriefs.js';
 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 { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, AGREEMENT_TERMS_PARAMS, } 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';

package/dist/capabilities/index.js

@@ -2,7 +2,7 @@ export { fullCreds, rethrowWithContext, } from './types.js';
 export { WRITE_SOURCE_KINDS, SOURCES_DESCRIPTION, SOURCES_PARAM, sourcesArg, } from './sources.js';
 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 { AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementHandoffCapability, agreementSubcontractCapability, AGREEMENT_TERMS_PARAMS, } 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';

package/dist/capabilities/links.js

@@ -121,7 +121,7 @@ export const proposeLinkCapability = {
     names: { sdk: 'link_propose', mcp: 'ziggs_link_propose' },
     title: 'Connect with someone',
     descriptions: {
-        sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organisation is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
+        sdk: "Connect with a person: pass their email, or the id of an agent that answers to them, and Ziggs delivers the invitation. The link is with the PERSON either way — an agent id is only a way to find its owner, and an agent that answers to an organization is refused, because a link connects two people. Leave `to` out to get a share link you hand over yourself. A link is reach and nothing else: no chat, no money, no work. The answer is the same every time, so it never tells you whether that address has an account.",
     },
     annotation: 'destructive',
     params: {

package/dist/capabilities/mcpBriefs.js

@@ -26,6 +26,10 @@ const BRIEFS = {
             does: 'Says whether mail arrived since your last ack (count is 1 or 0, not a total) and names who you represent. Does not take the inbox lease, return deliveries or ack.',
         },
     },
+    ziggs_inbox_show: {
+        does: 'Shows your person what waits on them and their work in hand, as a card where the host draws one. No claim or ack.',
+        when: 'your person asks what is waiting in Ziggs',
+    },
     ziggs_inbox: {
         does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news. Observes only: no claim or ack.',
         returns: 'a readPlan of next calls; backlog if more is unread',
@@ -219,10 +223,10 @@ const BRIEFS = {
     },
     // Agents, links and introductions
     ziggs_agent_search: {
-        does: 'Finds agents in the store, your workspaces and your own; matching teammates come back as people. Each row’s doors say whether to claim a listing or propose.',
+        does: 'Finds agents in the store, your workspaces and your own; matching teammates come back as people. Each row says whether to claim a listing or propose.',
     },
     ziggs_agent_get: {
-        does: 'Reads one agent’s profile by exact id, with its doors: listingAgreementId to claim, acceptsProposals for a direct proposal.',
+        does: 'Reads one agent’s profile by exact id, with how to hire it: listingAgreementId to claim, acceptsProposals for a direct proposal.',
     },
     ziggs_link_propose: {
         does: 'Proposes a link with a person, by email or an agent of theirs. Without to, returns a shareUrl invite.',

package/dist/http/AgreementClient.d.ts

@@ -17,7 +17,6 @@ export interface ProposeTerms {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     /**
      * How `price` reads. `total` (default) escrows one price for the whole
@@ -140,7 +139,6 @@ export interface DelegateAgreementData {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     agreementDescription?: string;
     payerId?: string;
@@ -210,7 +208,6 @@ export interface CounterAgreementData {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     description?: string;
     /** What this text drew on. See {@link WriteSource}. */

package/dist/http/MarketplaceClient.d.ts

@@ -10,7 +10,6 @@ export interface PublishOfferPayload {
     maxExecutions?: number;
     /** Shared incoming-message allowance; null means unlimited. */
     conversationAllowance?: number | null;
-    conversationAllowanceScope?: 'direct' | 'subtree';
     interactionMode?: 'messages' | 'tasks' | 'both';
     /** `hire` = claimer becomes the provider's principal on claim. Defaults to `service` server-side. */
     engagementKind?: 'hire' | 'service';

package/dist/http/agreementFlows.js

@@ -21,7 +21,6 @@ export async function proposeUnified(input, creds) {
                 expiresAt: terms.expiresAt,
                 maxExecutions: terms.maxExecutions,
                 conversationAllowance: terms.conversationAllowance,
-                conversationAllowanceScope: terms.conversationAllowanceScope,
                 interactionMode: terms.interactionMode,
                 engagementKind: engagementKind,
                 billing: terms.billing,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.18",
+  "version": "0.37.19",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {