@ziggs-ai/api-client 0.37.19 → 0.37.21

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.37.21
+
+- A room lane can name the agreement the wake works under: `laneUnderAgreement(chatId, agreementId)` builds it, and the lane header sends it as `X-Ziggs-Agreement` beside `X-Ziggs-Lane`. The backend takes it only for an agreement the agent has mail under in that room.
+- A search row names an active hire of that agent: it says already hired and carries the agreement id and the workspace the payer bought it in. An agent with no such hire has no such field.
+
+## 0.37.20
+
+- Shorter parameter text on the agreement verbs and the artifact record capability. Every rule stays.
+
 ## 0.37.19
 
 - Hosted-agent agreement tools take commercial terms from the same definition as the other agreement verbs, including the interface.

package/dist/capabilities/activeHire.d.ts

@@ -0,0 +1,19 @@
+import { type Agreement } from '../types.js';
+/** One live hire of an agent, as a search row names it. */
+export interface ActiveHire {
+    agreementId: string;
+    /** The workspace the payer bought it in. Null when the row records none. */
+    workspace: string | null;
+}
+type HireRow = Agreement & {
+    payerLane?: string | null;
+};
+/**
+ * Active hires whose provider is this agent.
+ *
+ * A listing is not a hire: its payer is still a broadcast. A link and a
+ * membership are not hires either. `service` stays, because older hires
+ * were written as services with a named payer.
+ */
+export declare function activeHiresForAgent(agentId: string, agreements: readonly HireRow[]): ActiveHire[];
+export {};

package/dist/capabilities/activeHire.js

@@ -0,0 +1,31 @@
+import { AGREEMENT_ENGAGEMENT_KIND, isBroadcastTarget, } from '../types.js';
+/**
+ * Active hires whose provider is this agent.
+ *
+ * A listing is not a hire: its payer is still a broadcast. A link and a
+ * membership are not hires either. `service` stays, because older hires
+ * were written as services with a named payer.
+ */
+export function activeHiresForAgent(agentId, agreements) {
+    if (!agentId)
+        return [];
+    const hires = [];
+    for (const row of agreements) {
+        if (row.status !== 'active')
+            continue;
+        if (row.engagementKind !== AGREEMENT_ENGAGEMENT_KIND.HIRE &&
+            row.engagementKind !== AGREEMENT_ENGAGEMENT_KIND.SERVICE) {
+            continue;
+        }
+        if (row.parties?.provider?.actor !== agentId)
+            continue;
+        const payer = row.parties?.payer?.principal;
+        if (typeof payer === 'string' && isBroadcastTarget(payer))
+            continue;
+        hires.push({
+            agreementId: row.agreementId,
+            workspace: row.payerLane ?? null,
+        });
+    }
+    return hires;
+}

package/dist/capabilities/agreementVerbs.js

@@ -33,12 +33,12 @@ export const AGREEMENT_TERMS_PARAMS = {
     },
     price: {
         type: 'number',
-        description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Recording a price here does not itself move any. Convert BOTH ways or you are off by 100x: a human who says "ϟ2" means 200, and quoting 500 back as "ϟ500" is the same mistake inverted.',
+        description: 'Points in hundredths: 500 is ϟ5.00, and a person\'s "ϟ2" is 200. Convert both ways. Recording a price moves no points.',
     },
     billing: {
         type: 'string',
         enum: ['total', 'per_task'],
-        description: 'How price reads. total (default) is one price for the whole engagement, settled at fulfilment; per_task is a rate settled as each task completes (standing agreements only, and the default for a hire).',
+        description: 'total (default): one price, settled at fulfilment. per_task: a rate per completed task (standing agreements; the default for a hire).',
     },
     engagementKind: {
         type: 'string',
@@ -48,14 +48,14 @@ export const AGREEMENT_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.',
+        description: 'open (default): no expiry, unlimited tasks. Set it only when this should end on its own.',
     },
     expiresAt: {
         type: 'string',
         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.' },
-    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.' },
+    conversationAllowance: { type: 'number', description: 'Incoming messages allowed across covered rooms, shared with any helper hired under this job. Omit for unlimited; on a counter, omit to keep the current limit.' },
     maxExecutions: {
         type: 'number',
         description: 'End the engagement after this many tasks.',
@@ -90,7 +90,7 @@ function engagementKindFrom(args) {
 /** The declared job governs the work; hiring consent uses grants or agreement approval. */
 const MANDATE_PARAM = {
     type: 'string',
-    description: "The active agreement whose work this is part of — the job you are doing. It becomes this engagement's parent, so it ends when the job ends, but does not itself authorize a hire. Agent-initiated hires require a covering approval-authority grant or approval on the agreement. Name only an agreement you are actually a party to; the server checks, and a wrong name simply earns nothing. Leave it out for work that belongs to no job. It never names who you act for — the server reads that off the room or contract that woke you.",
+    description: 'The job you are doing, if this work is part of it: an active agreement you are a party to. This work ends when that job ends. It does not authorize the hire by itself, and never says who you act for.',
 };
 /** Pull the declared mandate off a validated arg bag, as the wire field. */
 function mandateFrom(args) {
@@ -140,7 +140,7 @@ const COUNTERPARTY_PARAM = {
 const CHAT_PARAM = {
     type: 'string',
     required: false,
-    description: 'The room this is proposed in, when there is one — the counterparty can read and discuss the terms there. Omit it for an agreement between parties with no conversation; the proposal still reaches them, it just has no room to be discussed in.',
+    description: 'The room to discuss the terms in, if any. Without one the proposal still reaches them.',
 };
 /** Marketplace follow-up: a published listing is claimed, never countered. */
 function publishedNext(env) {
@@ -162,7 +162,7 @@ export const agreementBuyCapability = {
         chatId: CHAT_PARAM,
         ...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.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -193,7 +193,7 @@ export const agreementBidCapability = {
         chatId: CHAT_PARAM,
         ...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.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -232,7 +232,7 @@ export const agreementBrokerCapability = {
         chatId: CHAT_PARAM,
         ...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.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -262,7 +262,7 @@ export const agreementRequestCapability = {
         ...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.' },
+        parentAgreementId: { type: 'string', description: 'The job this work is part of; ending it ends this work. Not a link, and no spending consent.' },
     },
     needsAgentId: true,
     handler: async (args, env) => {

package/dist/capabilities/artifacts.js

@@ -210,8 +210,7 @@ export const recordArtifactCapability = {
         },
         idempotencyKey: {
             type: 'string',
-            description: 'Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it. ' +
-                'A task-bound result artifact is one deliverable per task: recordReport keys it `task-result:<taskId>`, so a retry after a partial failure reuses that row. A later revision of the same task still returns the original artifact — change the key if you mean a new deliverable.',
+            description: 'Dedup key: the same key returns the original artifact instead of a new one. Derive it from the event and step, never at random. A new revision needs a new key.',
         },
         externalRef: {
             type: 'object',

package/dist/capabilities/discovery.js

@@ -1,4 +1,6 @@
 import { AgentSearchClient } from '../http/AgentSearchClient.js';
+import { getMyAgreements } from '../http/AgreementClient.js';
+import { activeHiresForAgent } from './activeHire.js';
 import { RESOURCE_HIDDEN_MESSAGE } from './context.js';
 import { fullCreds } from './types.js';
 export const agentSearchCapability = {
@@ -6,7 +8,7 @@ export const agentSearchCapability = {
     names: { sdk: 'agent_search', mcp: 'ziggs_agent_search' },
     title: 'Search for agents',
     descriptions: {
-        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store, your org\'s own agents and your own agents, and it matches your teammates by name: a teammate comes back under `people` as a person to message (chat_open with their userId), never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids.',
+        sdk: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. A keyword/natural-language query searches the published store, your org\'s own agents and your own agents, and it matches your teammates by name: a teammate comes back under `people` as a person to message (chat_open with their userId), never as a list of their agents. Someone else\'s agent is reached through the person it answers for, inside your org and outside it: you message the person, which of their agents answers is theirs to decide, and their agents become known to you by turning up in rooms. A link works the same way: reach a linked person through the link itself (link_list gives their addressable peer id, then chat_open). Passing an EXACT agent id resolves that one agent when you can reach it. Each row carries `doors` — its engagement doors: doors.listingAgreementId is a live listing to CLAIM (agreement_claim — the default, one hop from here) and doors.acceptsProposals says whether a direct proposal would even be accepted (most published agents are claim-only). Use returned agentId in grant/issue tools — do not guess ids. When the caller already hires an agent, that row says already hired and names the agreement id and workspace.',
     },
     annotation: 'read-only',
     params: {
@@ -42,7 +44,9 @@ export const agentSearchCapability = {
                 peopleNote: `These are teammates whose name matched. Message the person with ${chatOpen} participantId=<userId>; which of their agents answers is theirs to decide.`,
             }
             : {};
-        if (!result.agents?.length) {
+        const hired = await hireNotes(result.agents ?? [], env);
+        const agents = (result.agents ?? []).map((agent) => withHire(agent, hired));
+        if (!agents.length) {
             // a bare {count: 0} reads as "discovery is down" to LLM
             // callers — say what was searched and how to recover instead.
             return {
@@ -67,7 +71,12 @@ export const agentSearchCapability = {
                     `not their agents. Take their peer id from ${linkList} and open a chat with the person instead.`,
             };
         }
-        return { count: result.agents.length, agents: result.agents, ...messageThem };
+        return {
+            count: agents.length,
+            agents,
+            ...(hired.checked ? {} : { hireCheck: 'unavailable' }),
+            ...messageThem,
+        };
     },
     sdkOptions: { isGenericFallback: true },
 };
@@ -106,3 +115,27 @@ export const DISCOVERY_CAPABILITIES = [
     agentSearchCapability,
     agentGetCapability,
 ];
+function withHire(agent, hired) {
+    const hires = hired.byAgent.get(agent.agentId);
+    if (!hires?.length)
+        return agent;
+    return { ...agent, alreadyHired: 'already hired', hires };
+}
+/** One reachable-agreement read for the whole result. A failure is said, so a row with no hire field was checked. */
+async function hireNotes(agents, env) {
+    const byAgent = new Map();
+    if (agents.length === 0)
+        return { checked: true, byAgent };
+    try {
+        const agreements = await getMyAgreements({}, fullCreds(env));
+        for (const agent of agents) {
+            const hires = activeHiresForAgent(agent.agentId, agreements);
+            if (hires.length)
+                byAgent.set(agent.agentId, hires);
+        }
+        return { checked: true, byAgent };
+    }
+    catch {
+        return { checked: false, byAgent };
+    }
+}

package/dist/capabilities/mcpBriefs.js

@@ -59,7 +59,7 @@ const BRIEFS = {
     },
     // Agreements
     ziggs_agreement_list: {
-        does: 'Lists agreements you are a party to. scope reachable adds every agreement your grants can read.',
+        does: 'Lists the agreements you can reach, including hires. scope mine keeps only agreements you are a party to.',
     },
     ziggs_agreement_get: {
         does: 'Reads one agreement: parties, terms, status, and approvalAction (who may decide a pending slot).',
@@ -223,7 +223,7 @@ 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 says whether to claim a listing or propose.',
+        does: 'Finds agents in the store, your workspaces and your own; teammates come back as people. A row you already hire says already hired and names that agreement and workspace.',
     },
     ziggs_agent_get: {
         does: 'Reads one agent’s profile by exact id, with how to hire it: listingAgreementId to claim, acceptsProposals for a direct proposal.',

package/dist/http/index.d.ts

@@ -33,5 +33,5 @@ export { TelemetryClient } from './TelemetryClient.js';
 export { InboxClient } from './InboxClient.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from '../inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from '../inboxAck.js';
-export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { WAKE_LANE_HEADER, WAKE_AGREEMENT_HEADER, laneHeader, laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick, type ToolPickOption, type ToolPickAnswer, type PickTool } from './ToolPickClient.js';

package/dist/http/index.js

@@ -25,5 +25,5 @@ export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds,
 // The lane header, built in one place — see operatorHeaders.ts. Exported
 // because the MCP transports in agent-sdk and ziggs-mcp send it too, and a
 // copy of a header nobody notices missing goes stale unseen.
-export { WAKE_LANE_HEADER, laneHeader, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
+export { WAKE_LANE_HEADER, WAKE_AGREEMENT_HEADER, laneHeader, laneUnderAgreement, buildOperatorHeaders, buildCredsHeaders, } from './operatorHeaders.js';
 export { backendToolPick } from './ToolPickClient.js';

package/dist/http/operatorHeaders.d.ts

@@ -24,8 +24,22 @@ export declare function assistantRequestHeaders(): Record<string, string>;
 /** The header the backend's wake fence reads (`access/wake-fence.ts`). */
 export declare const WAKE_LANE_HEADER = "X-Ziggs-Lane";
 /**
- * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
- * for a task with no origin chat.
+ * The header naming the agreement a room wake works under. The backend takes
+ * it only for an agreement the agent has mail under in that room, and reads
+ * it off that mail when it is absent.
+ */
+export declare const WAKE_AGREEMENT_HEADER = "X-Ziggs-Agreement";
+/**
+ * A room lane that also names the agreement the wake works under:
+ * `<chatId>@<agreementId>`. Every client already carries the lane to
+ * {@link laneHeader}, so the agreement travels with it without a second
+ * parameter on each of them. An `agrn-` lane already is its agreement.
+ */
+export declare function laneUnderAgreement(laneId: string, agreementId?: string | null): string;
+/**
+ * The lane headers, or nothing. `laneId` is a chat id, `agrn-<agreementId>`
+ * for a task with no origin chat, or a chat id with the agreement the wake
+ * works under (`<chatId>@<agreementId>`, see {@link laneUnderAgreement}).
  */
 export declare function laneHeader(laneId?: string): Record<string, string>;
 export declare function buildOperatorHeaders(operatorKey: string, agentId?: string, extra?: Record<string, string>, 

package/dist/http/operatorHeaders.js

@@ -37,11 +37,37 @@ export function assistantRequestHeaders() {
 /** The header the backend's wake fence reads (`access/wake-fence.ts`). */
 export const WAKE_LANE_HEADER = 'X-Ziggs-Lane';
 /**
- * The lane header, or nothing. `laneId` is a chat id, or `agrn-<agreementId>`
- * for a task with no origin chat.
+ * The header naming the agreement a room wake works under. The backend takes
+ * it only for an agreement the agent has mail under in that room, and reads
+ * it off that mail when it is absent.
+ */
+export const WAKE_AGREEMENT_HEADER = 'X-Ziggs-Agreement';
+/**
+ * A room lane that also names the agreement the wake works under:
+ * `<chatId>@<agreementId>`. Every client already carries the lane to
+ * {@link laneHeader}, so the agreement travels with it without a second
+ * parameter on each of them. An `agrn-` lane already is its agreement.
+ */
+export function laneUnderAgreement(laneId, agreementId) {
+    if (!agreementId || laneId.startsWith('agrn-') || laneId.includes('@'))
+        return laneId;
+    return `${laneId}@${agreementId}`;
+}
+/**
+ * The lane headers, or nothing. `laneId` is a chat id, `agrn-<agreementId>`
+ * for a task with no origin chat, or a chat id with the agreement the wake
+ * works under (`<chatId>@<agreementId>`, see {@link laneUnderAgreement}).
  */
 export function laneHeader(laneId) {
-    return laneId ? { [WAKE_LANE_HEADER]: laneId } : {};
+    if (!laneId)
+        return {};
+    const at = laneId.indexOf('@');
+    if (at <= 0)
+        return { [WAKE_LANE_HEADER]: laneId };
+    return {
+        [WAKE_LANE_HEADER]: laneId.slice(0, at),
+        [WAKE_AGREEMENT_HEADER]: laneId.slice(at + 1),
+    };
 }
 export function buildOperatorHeaders(operatorKey, agentId, extra, 
 /**

package/package.json

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