@ziggs-ai/api-client 0.37.20 → 0.37.22

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.37.22
+
+- A full inbox read says it takes or renews this host's lease and that waitSeconds long-polls. The read stays read-only. Acknowledgement stays on its own call.
+
+## 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.

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/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

@@ -35,8 +35,7 @@ const BRIEFS = {
         returns: 'a readPlan of next calls; backlog if more is unread',
         next: 'ziggs_inbox_claim to handle them',
         compact: {
-            does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news.',
-            changes: 'takes or renews this host’s lease',
+            does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds long-polls. It takes or renews this host’s lease.',
             next: 'ziggs_inbox_ack after handling',
         },
     },
@@ -59,7 +58,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 +222,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.20",
+  "version": "0.37.22",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {