@ziggs-ai/api-client 0.31.0 → 0.32.0

package/dist/capabilities/agreementVerbs.js

@@ -214,7 +214,7 @@ export const agreementBidCapability = {
             proposedTo: args['counterparty'],
             chatId: args['chatId'],
             // You provide, so the counterparty pays.
-            providerId: creds.agentId,
+            providerId: creds.agentId || undefined,
             engagementKind: engagementKindFrom(args),
         }, creds);
         return { agreement };

package/dist/capabilities/chat.js

@@ -138,7 +138,7 @@ export const openConversationCapability = {
         return {
             chatId,
             appUrl: chatAppUrl(webAppOrigin(env), chatId),
-            actingAgentId: agentId,
+            ...(agentId ? { actingAgentId: agentId } : {}),
             people,
             pending,
             ...(typeof reused === 'boolean' ? { reused } : {}),
@@ -158,7 +158,7 @@ function roomRoster(args, invited, agentId) {
     const pending = (invited ?? []).filter((row) => row.status === 'pending').map((row) => row.id);
     const waiting = new Set(pending);
     const here = (invited ?? []).filter((row) => row.status !== 'pending').map((row) => row.id);
-    const people = [...new Set([...named.filter((id) => !waiting.has(id)), ...here, agentId])];
+    const people = [...new Set([...named.filter((id) => !waiting.has(id)), ...here, ...(agentId ? [agentId] : [])])];
     return { people, pending };
 }
 /** Say what happened to each invited id, so the agent reports it truthfully. */

package/dist/capabilities/connections.js

@@ -72,13 +72,15 @@ export const connectionProxyCapability = {
 export const requestConnectionCapability = {
     key: "connection_request",
     names: { sdk: "connection_request", mcp: "ziggs_connection_request" },
-    title: "Ask your principal for a connection",
+    title: "Ask someone for a connection",
     descriptions: {
-        sdk: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
-            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement. " +
+        sdk: "Ask a person to connect a remote MCP server and grant you the listed tools. " +
+            "Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. " +
+            "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it — tell that person, not whoever happens to be in the room. " +
             "On approval the server is connected (browser OAuth if needed) and you are granted the tools; call them with mcp_tool_call / mcp_tools_list (not connection_proxy).",
-        mcp: "Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. " +
-            "Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). " +
+        mcp: "Ask a person to connect a remote MCP server and grant you the listed tools. " +
+            "Name who to ask in recipientId: the person you are helping (your own account) unless the server says otherwise; a pick it cannot use here is refused, and the refusal lists who you can ask. " +
+            "Opens a connection-consent card in the chat you pass; the answer says who got it and where they approve it (there is no MCP tool to approve it). " +
             "On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_connection_list for use with ziggs_mcp_tools_list / ziggs_mcp_tool_call.",
     },
     annotation: "write",
@@ -103,6 +105,11 @@ export const requestConnectionCapability = {
             type: "string",
             description: "Plain-language reason shown to the human deciding",
         },
+        recipientId: {
+            type: "string",
+            required: true,
+            description: "Who to ask: workBrief.actingFor.customer.id (the customer of this hire, for their own accounts) or workBrief.actingFor.operator.id (your operator, for tools you bring)",
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -114,20 +121,28 @@ export const requestConnectionCapability = {
         if (!Array.isArray(tools) || tools.length === 0) {
             throw new Error("tools must be a non-empty array of tool names");
         }
+        if (typeof args["recipientId"] !== "string" || !args["recipientId"].trim())
+            throw new Error("recipientId is required: who to ask, from your work brief");
         try {
             const result = await client(env).requestMcpConnection({
                 chatId: args["chatId"],
                 serverUrl: args["serverUrl"],
                 tools: tools,
                 reason: args["reason"],
+                recipientId: args["recipientId"].trim(),
             });
+            // Who got the card is the server's answer; say that, never "your
+            // principal" — the card often goes to someone else.
+            const sent = typeof result["message"] === "string"
+                ? result["message"]
+                : "A connection-consent card is open.";
             return {
                 ok: true,
                 ...result,
                 note: env.surface === "mcp"
-                    ? "A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. " +
+                    ? `${sent} Tell that person now (pull-only MCP has no push). ` +
                         "Once approved, the connection + grant appear in ziggs_connection_list for ziggs_mcp_tools_list / ziggs_mcp_tool_call."
-                    : "A connection-consent card is now in the chat awaiting your principal — they approve it right there. " +
+                    : `${sent} Tell that person; only they can approve it. ` +
                         "Once approved, the connection + grant appear in grant_list (scopeKind [\"connection\"]) / connection_list_grants for mcp_tools_list / mcp_tool_call.",
             };
         }

package/dist/capabilities/context.js

@@ -369,13 +369,13 @@ export const contextRequestCapability = {
     title: 'Ask an owner for artifact access',
     descriptions: {
         sdk: 'Ask a human owner for temporary read-only access to one artifact you were given a reference for. Use your existing chat with that owner. Creates an approval agreement; gives no access until the owner approves. You are the only recipient. After approval, open the original artifact. Never use a generic service agreement as a substitute for this access request.',
-        mcp: 'Request access to a restricted artifact directly from its human owner. Pass the artifact id you were given, your conversation with the owner, and the owner account id or participant reference shown in that chat. This creates a pending approval agreement, NOT a grant. No prior grant is needed. The human approves at the agreement link. After approval, ziggs_open the original artifact. Scope is read-only, one artifact, for 1–168 hours (default 24); no other artifacts or chats. Include the intended summary recipient in reason. Keep polling for the decision when asked to wait. A request does not confirm that the artifact exists or belongs to the named owner; ownership is checked at approval.',
+        mcp: 'Request access to a restricted artifact directly from its human owner. Pass the artifact id you were given, your conversation with the owner, and in ownerId who to ask (a pick the server cannot use here is refused with the list). This creates a pending approval agreement, NOT a grant. No prior grant is needed. The human approves at the agreement link. After approval, ziggs_open the original artifact. Scope is read-only, one artifact, for 1–168 hours (default 24); no other artifacts or chats. Include the intended summary recipient in reason. Keep polling for the decision when asked to wait. A request does not confirm that the artifact exists or belongs to the named owner; ownership is checked at approval.',
     },
     annotation: 'write', needsAgentId: true,
     params: {
         artifactId: { type: 'string', required: true },
         chatId: { type: 'string', required: true },
-        ownerId: { type: 'string', required: true, description: 'Human account id or room participant reference, not a persona face' },
+        ownerId: { type: 'string', required: true, description: 'Who to ask, from your work brief: workBrief.actingFor.customer.id or workBrief.actingFor.operator.id. Anyone else is refused, and the refusal lists who you can ask.' },
         reason: { type: 'string', required: true, description: 'Purpose, including whom you will summarize the artifact to' },
         durationHours: { type: 'number', description: 'Integer 1–168 hours after approval; default 24' },
         idempotencyKey: { type: 'string', description: 'Reuse for the same request; do not create duplicate approval cards' },
@@ -391,7 +391,7 @@ export const contextRequestCapability = {
         const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).requestArtifactAccess(args.artifactId, {
             chatId: args.chatId, ownerId: args.ownerId, reason: args.reason, durationHours,
         }, { idempotencyKey: args.idempotencyKey, laneId: creds.laneId });
-        return { ...result, outcome: 'pending', state: 'requested', appUrl: `${(env.webUrl ?? 'https://ziggsai.com').replace(/\/$/, '')}/app/agreements/${encodeURIComponent(result.agreementId)}`, note: 'Waiting for the artifact owner. No access granted yet; open the original artifact only after approval.' };
+        return { ...result, outcome: 'pending', state: 'requested', appUrl: `${(env.webUrl ?? 'https://ziggsai.com').replace(/\/$/, '')}/app/agreements/${encodeURIComponent(result.agreementId)}`, note: `${result.message ?? 'Waiting for the artifact owner.'} No access granted yet; open the original artifact only after approval.` };
     },
 };
 /** A suggested request still needs a purpose; it is never a grant or an approval. */
@@ -399,7 +399,7 @@ function requestAccessAction(args, env) {
     return {
         kind: 'request_access',
         tool: env.surface === 'mcp' ? 'ziggs_access_request' : 'access_request',
-        args, requiredInput: args.scopeKind === 'artifact' ? ['reason', 'chatId', 'ownerId'] : ['reason'], effect: 'request_only',
+        args, requiredInput: args.scopeKind === 'artifact' ? ['reason', 'chatId', 'recipientId'] : ['reason', 'recipientId'], effect: 'request_only',
         requiresApproval: true,
     };
 }
@@ -409,8 +409,8 @@ export const accessRequestCapability = {
     title: 'Request access for yourself',
     annotation: 'write', needsAgentId: true,
     descriptions: {
-        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Artifact requests need chatId and ownerId of the person authorized to share it. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
-        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Artifact requests require chatId and ownerId of the authorized person in that conversation. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
+        sdk: 'Request optional bounded access to one artifact, chat, agreement context or task. Creates only a pending approval; never grants access or approves. Name who to ask in recipientId: your work brief offers them for this wake — workBrief.actingFor.customer.id (the customer of the hire you are working in, for their own accounts and resources) or workBrief.actingFor.operator.id (your operator, for tools you bring). Anyone else is refused, and the refusal lists who you can ask. Artifact requests also need chatId, the conversation they approve in. Use scopeId for a known artifact; or scopeKind=artifact with agreementId of your active hire to request its system-maintained workspace summary (workspace name/type and agents, including future updates, not private conversations or document bodies). Send the returned appUrl, wait for human approval, then open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        mcp: 'Request access for this agent, never approve or grant it. Use scopeId for an artifact, chat, agreement or task; scopeKind=artifact with agreementId of your active hire resolves its system-maintained workspace summary artifact. Name who to ask in recipientId; a pick the server cannot use here is refused, and the refusal lists who you can ask. Artifact requests also require chatId. Explain the scope and lifetime; summary access includes future updates only to that artifact. Surface appUrl and wait for human approval; then open the returned scope. Pending grants no access.',
     },
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
@@ -421,11 +421,11 @@ export const accessRequestCapability = {
         temporal: { type: 'string', enum: ['from-now', 'from-start'], description: 'Chat history requested; default from-now. Earlier messages need from-start. Other resources use from-start.' },
         durationHours: { type: 'number', description: 'Integer 1–168 hours after approval; default 24' },
         chatId: { type: 'string', description: 'Artifact or workspace requests only: existing conversation with the owner' },
-        ownerId: { type: 'string', description: 'Artifact or workspace requests only: human account or participant reference in that conversation' },
+        recipientId: { type: 'string', required: true, description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator)' },
         idempotencyKey: { type: 'string', description: 'Reuse for the same logical request' },
     },
     handler: async (args, env) => {
-        for (const key of ['scopeKind', 'reason']) {
+        for (const key of ['scopeKind', 'reason', 'recipientId']) {
             if (typeof args[key] !== 'string' || !String(args[key]).trim())
                 throw new Error(`${key} is required`);
         }
@@ -448,14 +448,15 @@ export const accessRequestCapability = {
         const result = await new ContextGrantsClient(creds.operatorKey, creds.agentId, env.baseUrl).requestAccess({
             scopeKind, scopeId, agreementId, reason: String(args.reason).trim(),
             permission: permission, temporal: args.temporal,
-            durationHours, chatId: args.chatId, ownerId: args.ownerId,
+            durationHours, chatId: args.chatId,
+            recipientId: typeof args.recipientId === 'string' ? args.recipientId.trim() : undefined,
         }, { idempotencyKey: args.idempotencyKey, laneId: creds.laneId });
         return {
             ...result, outcome: 'pending', state: 'requested', actingAgentId: creds.agentId,
             scope: result.scope ?? { kind: scopeKind, id: scopeId },
             appUrl: `${(env.webUrl ?? 'https://ziggsai.com').replace(/\/$/, '')}/app/agreements/${encodeURIComponent(result.agreementId)}`,
             resumeAfterApproval: { tool: env.surface === 'mcp' ? 'ziggs_open' : 'open', args: result.scope ? { [`${result.scope.kind}Id`]: result.scope.id } : { [`${scopeKind}Id`]: scopeId } },
-            note: 'No access granted. The authorized person must approve; then open the original resource using the same agent identity.',
+            note: `${result.message ?? 'A request card is open.'} No access granted until they approve; then open the original resource using the same agent identity.`,
         };
     },
 };

package/dist/capabilities/tasks.js

@@ -48,9 +48,9 @@ export const listTasksCapability = {
     handler: async (args, env) => {
         const creds = fullCreds(env);
         const assignedTo = args['assignedToMe']
-            ? creds.agentId
+            ? 'self'
             : args['assignedTo'];
-        const createdBy = args['createdByMe'] ? creds.agentId : undefined;
+        const createdBy = args['createdByMe'] ? 'self' : undefined;
         const listed = await listTasks({
             state: args['state'],
             cursor: args['cursor'],

package/dist/capabilities/types.d.ts

@@ -1,19 +1,3 @@
-/**
- * one shared definition per SDK/MCP tool capability.
- *
- * The tool-surface-parity epic (→903) unified the HTTP layer here in
- * api-client but left ~25 shared capabilities hand-written twice: once in the
- * agent-sdk's defineTool DSL, once in ziggs-mcp zod. Each capability below is
- * the single source for the tool's schema, validation, response shaping, and
- * guidance; the two surfaces register it through thin adapters
- * (agent-sdk `toolFromCapability`, ziggs-mcp `registerCapability`).
- *
- * Params are a neutral JSON-schema-flavoured DSL rather than zod because the
- * two surfaces cannot share one zod: agent-sdk is on zod v4, ziggs-mcp on
- * zod v3 (pinned by the MCP SDK's ZodRawShape), and api-client deliberately
- * has no zod dependency. The SDK adapter feeds params straight into
- * defineTool's converter; the MCP adapter lowers them to zod v3.
- */
 import type { Creds } from '../types.js';
 export type CapabilitySurface = 'sdk' | 'mcp';
 /** read-only / write / destructive — lowered to MCP tool annotations. */

package/dist/capabilities/types.js

@@ -1,13 +1,30 @@
+/**
+ * one shared definition per SDK/MCP tool capability.
+ *
+ * The tool-surface-parity epic (→903) unified the HTTP layer here in
+ * api-client but left ~25 shared capabilities hand-written twice: once in the
+ * agent-sdk's defineTool DSL, once in ziggs-mcp zod. Each capability below is
+ * the single source for the tool's schema, validation, response shaping, and
+ * guidance; the two surfaces register it through thin adapters
+ * (agent-sdk `toolFromCapability`, ziggs-mcp `registerCapability`).
+ *
+ * Params are a neutral JSON-schema-flavoured DSL rather than zod because the
+ * two surfaces cannot share one zod: agent-sdk is on zod v4, ziggs-mcp on
+ * zod v3 (pinned by the MCP SDK's ZodRawShape), and api-client deliberately
+ * has no zod dependency. The SDK adapter feeds params straight into
+ * defineTool's converter; the MCP adapter lowers them to zod v3.
+ */
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 /** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
 export function fullCreds(env) {
     const { operatorKey, agentId, laneId } = env.creds;
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    if (!agentId)
+    if (!agentId && !decodeOperatorKeyClaims(operatorKey)?.connectionClientId)
         throw new Error('agentId missing from tool context');
     // the lane rides along so every Creds-based client sends
     // X-Ziggs-Lane without each capability having to remember to.
-    return { operatorKey, agentId, ...(laneId ? { laneId } : {}) };
+    return { operatorKey, agentId: agentId ?? '', ...(laneId ? { laneId } : {}) };
 }
 /**
  * Re-throw a client error with a capability-level prefix, preserving the HTTP

package/dist/decisionWords.d.ts

@@ -13,6 +13,16 @@
  * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
  * and an instant are all it carries.
  */
+/**
+ * The actor as it may appear in words, or null.
+ *
+ * A person's account id is `username:::email`. The server shows a reader
+ * outside that person's org their `psn_` face instead, but an older
+ * server, or a row written before that, still hands the raw id over, and the
+ * model repeats whatever it is told into the room. So an id shaped like a
+ * person's account is left out rather than said.
+ */
+export declare function speakableActor(actorId: string | null | undefined): string | null;
 export type DecisionOutcome = 'approved' | 'rejected' | 'fulfilled' | 'held';
 export interface DecisionWordsInput {
     /** The delivery row's `reason`. Anything that is not a decision maps to null. */

package/dist/decisionWords.js

@@ -13,6 +13,20 @@
  * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
  * and an instant are all it carries.
  */
+/**
+ * The actor as it may appear in words, or null.
+ *
+ * A person's account id is `username:::email`. The server shows a reader
+ * outside that person's org their `psn_` face instead, but an older
+ * server, or a row written before that, still hands the raw id over, and the
+ * model repeats whatever it is told into the room. So an id shaped like a
+ * person's account is left out rather than said.
+ */
+export function speakableActor(actorId) {
+    if (typeof actorId !== 'string' || !actorId)
+        return null;
+    return actorId.includes(':::') || actorId.includes('@') ? null : actorId;
+}
 const REFUSED_REASONS = new Set([
     'approval:rejected',
     'context_request_rejected',
@@ -38,7 +52,8 @@ export function decisionWords(input) {
     const on = input.agreementId
         ? `agreement ${input.agreementId}`
         : 'this agreement';
-    const by = input.actorId ? ` by ${input.actorId}` : '';
+    const actor = speakableActor(input.actorId);
+    const by = actor ? ` by ${actor}` : '';
     const at = input.ts ? ` at ${input.ts}` : '';
     const artifactId = input.scope?.kind === 'artifact' && input.scope.id ? input.scope.id : null;
     if (REFUSED_REASONS.has(reason)) {

package/dist/http/AgreementClient.js

@@ -1,3 +1,4 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partySideIds } from '../types.js';
@@ -14,7 +15,7 @@ const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
+    if (!creds?.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
         throw new Error(`agentId is required for ${op}`);
 }
 /**

package/dist/http/AssistantConnectionClient.d.ts

@@ -0,0 +1,27 @@
+import { type Creds } from '../types.js';
+export interface AssistantWorkspace {
+    orgId: string;
+    name: string;
+    agentId: string;
+}
+/**
+ * The reads a connection makes about itself: which workspaces it works in,
+ * and its one inbox across all of them. It never remembers a
+ * current workspace and never changes shared credentials; the per-call pick
+ * is the server's (see `routing.ts`).
+ */
+export declare class AssistantConnectionClient {
+    private readonly creds;
+    private readonly baseUrl;
+    constructor(creds: Creds, baseUrl?: string);
+    request<T>(path: string, body?: unknown): Promise<T>;
+    /** Live: a workspace joined since connecting shows up here with its assistant. */
+    workspaces(): Promise<AssistantWorkspace[]>;
+    /** Which of the connection's assistants is on an existing thing. */
+    resolve(kind: string, id: string): Promise<{
+        workspace: AssistantWorkspace | null;
+        choices: AssistantWorkspace[];
+    }>;
+    inbox(waitSeconds?: number): Promise<Record<string, unknown>>;
+    ack(upTo: string, handledResourceIds?: string[]): Promise<unknown>;
+}

package/dist/http/AssistantConnectionClient.js

@@ -0,0 +1,49 @@
+import { getBackendUrl } from '../utils/urlUtils.js';
+import { hostIdentity } from '../instanceIdentity.js';
+import { ApiError } from '../types.js';
+import { parseErrorCode, parseErrorMessage } from '../shared/apiError.js';
+/**
+ * The reads a connection makes about itself: which workspaces it works in,
+ * and its one inbox across all of them. It never remembers a
+ * current workspace and never changes shared credentials; the per-call pick
+ * is the server's (see `routing.ts`).
+ */
+export class AssistantConnectionClient {
+    creds;
+    baseUrl;
+    constructor(creds, baseUrl = getBackendUrl()) {
+        this.creds = creds;
+        this.baseUrl = baseUrl;
+    }
+    async request(path, body) {
+        const response = await fetch(`${this.baseUrl}/oauth/${path}`, {
+            method: body === undefined ? 'GET' : 'POST',
+            headers: {
+                Authorization: `Bearer ${this.creds.operatorKey}`,
+                'Content-Type': 'application/json',
+                'X-Ziggs-Instance': hostIdentity(this.creds.instanceId),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new ApiError(parseErrorMessage(text, `${path} failed: ${response.status}`), response.status, text, parseErrorCode(text));
+        }
+        return JSON.parse(text);
+    }
+    /** Live: a workspace joined since connecting shows up here with its assistant. */
+    async workspaces() {
+        return (await this.request('workspaces'))
+            .workspaces;
+    }
+    /** Which of the connection's assistants is on an existing thing. */
+    resolve(kind, id) {
+        return this.request(`resolve?${new URLSearchParams({ kind, id })}`);
+    }
+    inbox(waitSeconds = 0) {
+        return this.request(`inbox?wait=${waitSeconds}`);
+    }
+    ack(upTo, handledResourceIds = []) {
+        return this.request('inbox/ack', { upTo, handledResourceIds });
+    }
+}

package/dist/http/ChatClient.js

@@ -1,3 +1,4 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
@@ -7,7 +8,7 @@ const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
+    if (!creds?.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
         throw new Error(`agentId is required for ${op}`);
 }
 export async function openConversation(participant, creds, { newChat = false, agreementId, createIfMissing } = {}) {

package/dist/http/ConnectionsClient.d.ts

@@ -32,6 +32,12 @@ export interface McpConnectionRequestParams {
     serverUrl: string;
     tools: string[];
     reason?: string;
+    /**
+     * Who to ask, from the people the server offers this wake (the work brief's
+     * `actingFor.customer.id` / `.operator.id`). Required by the server; the
+     * per-user relay may send it as `onBehalfOfUserId` instead.
+     */
+    recipientId?: string;
     /**
      * Working chat the consent card is opened into. Required by the backend for
      * the agent-tool path; the per-user gateway trigger omits it.
@@ -119,7 +125,7 @@ export declare class ConnectionsClient {
      * connection-consent agreement in the working chat; on approval the
      * server is connected (if needed) and the agent is granted the tools.
      */
-    requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }: McpConnectionRequestParams): Promise<Record<string, unknown>>;
+    requestMcpConnection({ serverUrl, tools, reason, chatId, recipientId, onBehalfOfUserId, }: McpConnectionRequestParams): Promise<Record<string, unknown>>;
     private _requestRaw;
     private _request;
 }

package/dist/http/ConnectionsClient.js

@@ -1,3 +1,4 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { getBackendUrl } from "../utils/urlUtils.js";
 import { throwApiError } from "../shared/apiError.js";
 import { buildOperatorHeaders } from "./operatorHeaders.js";
@@ -65,7 +66,7 @@ export class ConnectionsClient {
             throw new Error("proxy: grantId is required");
         if (!action)
             throw new Error("proxy: action is required");
-        if (!this.agentId) {
+        if (!this.agentId && !decodeOperatorKeyClaims(this.operatorKey)?.connectionClientId) {
             throw new Error("proxy: agentId is required — connection broker calls must impersonate the grant holder agent");
         }
         const text = await this._requestRaw("POST", `/connections/${encodeURIComponent(connectionId)}/proxy`, { grantId, action, payload: payload ?? {} });
@@ -88,12 +89,12 @@ export class ConnectionsClient {
     async listGrants({ connectionId, }) {
         if (!connectionId)
             throw new Error("listGrants: connectionId is required");
-        if (!this.agentId) {
+        if (!this.agentId && !decodeOperatorKeyClaims(this.operatorKey)?.connectionClientId) {
             throw new Error("listGrants: agentId is required — grants are scoped to the impersonated agent");
         }
         const res = (await this._request("GET", `/connections/${encodeURIComponent(connectionId)}/grants`, undefined));
         const grants = res["grants"] || [];
-        return grants.filter((g) => g["holderId"] === this.agentId);
+        return this.agentId ? grants.filter((g) => g["holderId"] === this.agentId) : grants;
     }
     /**
      * cross-connection discovery over the unified GET /grants:
@@ -174,10 +175,10 @@ export class ConnectionsClient {
      * connection-consent agreement in the working chat; on approval the
      * server is connected (if needed) and the agent is granted the tools.
      */
-    async requestMcpConnection({ serverUrl, tools, reason, chatId, onBehalfOfUserId, }) {
+    async requestMcpConnection({ serverUrl, tools, reason, chatId, recipientId, onBehalfOfUserId, }) {
         if (!serverUrl)
             throw new Error("requestMcpConnection: serverUrl is required");
-        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, chatId }, onBehalfOfUserId
+        return (await this._request("POST", "/connections/mcp/requests", { serverUrl, tools, reason, chatId, ...(recipientId ? { recipientId } : {}) }, onBehalfOfUserId
             ? { "X-On-Behalf-Of-User": onBehalfOfUserId }
             : undefined));
     }

package/dist/http/ContextGrantsClient.d.ts

@@ -107,6 +107,8 @@ export declare class ContextGrantsClient {
         durationHours?: number;
         chatId?: string;
         ownerId?: string;
+        /** Who to ask, from the people the server offers this wake. */
+        recipientId?: string;
     }, opts?: {
         idempotencyKey?: string;
         laneId?: string;
@@ -118,7 +120,7 @@ export declare class ContextGrantsClient {
             kind: string;
             id: string;
         };
-    }>;
+    } & RequestSentTo>;
     requestArtifactAccess(artifactId: string, input: {
         chatId: string;
         ownerId: string;
@@ -130,7 +132,7 @@ export declare class ContextGrantsClient {
     }): Promise<{
         status: 'pending_approval';
         agreementId: string;
-    }>;
+    } & RequestSentTo>;
     delegateGrant(parentGrantId: string, input: DelegateContextGrantInput, opts?: {
         idempotencyKey?: string;
     }): Promise<DelegateContextGrantResult>;
@@ -163,3 +165,19 @@ export declare class ContextGrantsClient {
         revokedCount?: number;
     }>;
 }
+/** Who got a request card and where they answer it, as the server says. */
+export interface RequestSentTo {
+    sentTo?: {
+        id: string;
+        name: string | null;
+        role: 'customer' | 'operator';
+    };
+    approveIn?: {
+        kind: 'chat';
+        chatId: string;
+    } | {
+        kind: 'inbox';
+    };
+    /** e.g. "Sent to Ido. Ido approves it in this room." */
+    message?: string;
+}

package/dist/http/ContextGrantsClient.js

@@ -80,7 +80,7 @@ export class ContextGrantsClient {
         if (result.status !== 'pending_approval' || !result.agreementId || result.accessGranted !== false) {
             throw new Error('Expected a pending access request with accessGranted=false');
         }
-        return { status: 'pending_approval', agreementId: result.agreementId, accessGranted: false, ...(result.scope ? { scope: result.scope } : {}) };
+        return { status: 'pending_approval', agreementId: result.agreementId, accessGranted: false, ...(result.scope ? { scope: result.scope } : {}), ...sentToOf(result) };
     }
     async requestArtifactAccess(artifactId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/access-requests`, {
@@ -98,7 +98,7 @@ export class ContextGrantsClient {
         const result = JSON.parse(body);
         if (result.status !== 'pending_approval' || !result.agreementId)
             throw new Error('Expected a pending artifact access request');
-        return { status: 'pending_approval', agreementId: result.agreementId };
+        return { status: 'pending_approval', agreementId: result.agreementId, ...sentToOf(result) };
     }
     async delegateGrant(parentGrantId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(parentGrantId)}/delegate`, {
@@ -185,3 +185,10 @@ export class ContextGrantsClient {
         return JSON.parse(body);
     }
 }
+function sentToOf(result) {
+    return {
+        ...(result.sentTo && typeof result.sentTo === 'object' ? { sentTo: result.sentTo } : {}),
+        ...(result.approveIn && typeof result.approveIn === 'object' ? { approveIn: result.approveIn } : {}),
+        ...(typeof result.message === 'string' ? { message: result.message } : {}),
+    };
+}

package/dist/http/MarketplaceClient.js

@@ -1,3 +1,4 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 // one shaping rule for every agreement this package parses.
 import { shapeAgreement } from './AgreementClient.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
@@ -9,7 +10,7 @@ const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
+    if (!creds?.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
         throw new Error(`agentId is required for ${op}`);
 }
 export async function publishOffer(payload, creds) {

package/dist/http/MessagesClient.js

@@ -1,3 +1,5 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
+import { buildOperatorHeaders } from './operatorHeaders.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { throwApiError } from '../shared/apiError.js';
 /**
@@ -14,7 +16,7 @@ export class MessagesClient {
     constructor(operatorKey, agentId) {
         if (!operatorKey)
             throw new Error('MessagesClient: operatorKey is required');
-        if (!agentId)
+        if (!agentId && !decodeOperatorKeyClaims(operatorKey)?.connectionClientId)
             throw new Error('MessagesClient: agentId is required (operator-token impersonation)');
         this.operatorKey = operatorKey;
         this.agentId = agentId;
@@ -43,8 +45,7 @@ export class MessagesClient {
     _headers() {
         return {
             'content-type': 'application/json',
-            Authorization: `Bearer ${this.operatorKey}`,
-            'X-Agent-Id': this.agentId,
+            ...buildOperatorHeaders(this.operatorKey, this.agentId),
         };
     }
 }

package/dist/http/OrgsClient.js

@@ -102,7 +102,6 @@ export async function fetchHostedAgentAccess(creds, baseUrl) {
         orgId: activeOrgId,
         orgName,
         orgKind,
-        switchOrgHint: 'Hosted agent session — acting org is the agent home / key workspace, not MCP OAuth consent.',
     };
 }
 /**

package/dist/http/TaskClient.js

@@ -1,3 +1,4 @@
+import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { partyActorIds } from '../types.js';
 import { throwApiError } from '../shared/apiError.js';
@@ -8,7 +9,7 @@ const buildHeaders = buildCredsHeaders;
 function assertCreds(creds, op) {
     if (!creds?.operatorKey)
         throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId)
+    if (!creds?.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
         throw new Error(`agentId is required for ${op}`);
 }
 function extractTask(data) {

package/dist/http/operatorHeaders.d.ts

@@ -1,3 +1,10 @@
+type AssistantHints = {
+    orgId?: string;
+    resource?: string;
+};
+/** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
+export declare function withAssistantRequest<T>(hints: AssistantHints, run: () => T): Promise<Awaited<T>>;
+export declare function assistantRequestHeaders(): Record<string, string>;
 /**
  * Auth headers for operator-key HTTP clients.
  *
@@ -29,3 +36,4 @@ export declare function buildCredsHeaders(creds: {
     agentId: string;
     laneId?: string;
 }): Record<string, string>;
+export {};

package/dist/http/operatorHeaders.js

@@ -1,3 +1,17 @@
+let assistantRequest;
+let assistantContextLoading;
+/** Node-only, opt-in request context. Ordinary HTTP clients remain browser-safe. */
+export async function withAssistantRequest(hints, run) {
+    assistantContextLoading ??= import('node:async_hooks').then(({ AsyncLocalStorage }) => {
+        assistantRequest = new AsyncLocalStorage();
+        return assistantRequest;
+    });
+    return await (await assistantContextLoading).run(hints, run);
+}
+export function assistantRequestHeaders() {
+    const hints = assistantRequest?.getStore();
+    return { ...(hints?.orgId ? { 'X-Workspace-Id': hints.orgId } : {}), ...(hints?.resource ? { 'X-Ziggs-Resource': hints.resource } : {}) };
+}
 /**
  * Auth headers for operator-key HTTP clients.
  *
@@ -27,6 +41,7 @@ export function buildOperatorHeaders(operatorKey, agentId, extra,
 laneId) {
     return {
         Authorization: `Bearer ${operatorKey}`,
+        ...assistantRequestHeaders(),
         // `X-Agent-Id` is only sent when an agentId is present — agent-scoped keys
         // identify the agent themselves; fleet keys must pass one.
         ...(agentId ? { 'X-Agent-Id': agentId } : {}),

package/dist/inboxAck.d.ts

@@ -34,12 +34,13 @@ export interface PlanInboxAckOptions {
      * delivery counts (the MCP tool with no configured self id).
      */
     ownAgentId?: string;
+    ownAgentIds?: readonly string[];
     /** Failed handovers hold the watermark unless `forceAck`. */
     failures?: number;
     forceAck?: boolean;
 }
 /** Resource ids this envelope's ack must list. */
-export declare function inboxAckHandledIds(envelope: InboxAckEnvelope, ownAgentId?: string): string[];
+export declare function inboxAckHandledIds(envelope: InboxAckEnvelope, ownAgentId?: string, ownAgentIds?: readonly string[]): string[];
 /** Whether an ack is allowed for this envelope, given handover state. */
 export declare function inboxAckAllowed(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): boolean;
 export declare function planInboxAck(envelope: InboxAckEnvelope, opts?: PlanInboxAckOptions): InboxAckDecision;

package/dist/inboxAck.js

@@ -15,8 +15,8 @@ function isOutOfReach(note) {
         typeof n.remedy === 'string');
 }
 /** Resource ids this envelope's ack must list. */
-export function inboxAckHandledIds(envelope, ownAgentId) {
-    const mine = (assigneeId) => !ownAgentId || assigneeId === ownAgentId;
+export function inboxAckHandledIds(envelope, ownAgentId, ownAgentIds) {
+    const mine = (assigneeId) => ownAgentIds ? ownAgentIds.includes(assigneeId ?? '') : !ownAgentId || assigneeId === ownAgentId;
     return [
         ...new Set([
             ...(envelope.deliveries ?? [])
@@ -41,12 +41,12 @@ export function inboxAckAllowed(envelope, opts = {}) {
 export function planInboxAck(envelope, opts = {}) {
     return {
         allowed: inboxAckAllowed(envelope, opts),
-        handledResourceIds: inboxAckHandledIds(envelope, opts.ownAgentId),
+        handledResourceIds: inboxAckHandledIds(envelope, opts.ownAgentId, opts.ownAgentIds),
     };
 }
 /** Every row whose instant the server's bury-guard will ask about. */
-function gatingRows(envelope, ownAgentId) {
-    const mine = (assigneeId) => !ownAgentId || assigneeId === ownAgentId;
+function gatingRows(envelope, ownAgentId, ownAgentIds) {
+    const mine = (assigneeId) => ownAgentIds ? ownAgentIds.includes(assigneeId ?? '') : !ownAgentId || assigneeId === ownAgentId;
     return [
         ...(envelope.deliveries ?? [])
             .filter((d) => mine(d.assigneeId))
@@ -92,7 +92,7 @@ export function planPartialInboxAck(envelope, handled, opts = {}) {
     }
     if (tokenByInstant.size === 0)
         return null;
-    const gating = gatingRows(envelope, opts.ownAgentId);
+    const gating = gatingRows(envelope, opts.ownAgentId, opts.ownAgentIds);
     // ISO-8601 sorts lexicographically in time order, which is what every other
     // ts comparison on this rail already relies on.
     const instants = [...tokenByInstant.keys()].sort();

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 export { ApiError } from './types.js';
 export type { Creds, Task, TaskState, PlanStep, PlanStepStatus, Agreement, AgreementParties, AgreementPartySide, EngagementKind, BroadcastAudience, EntryType, ContentType, MessageMetadata, MessageHandler, InboxDeliveryKind, InboxDeliveryRef, InboxChatNews, InboxProposalRef, InboxTaskRef, InboxRequestRef, InboxConnectionRequestRef, InboxHumanAttention, InboxEnvelope, InboxAckResult, InboxPeek, InboxReadOptions, } from './types.js';
 export type { ProposeTerms, ProposeDirectInput, ProposeBroadcastInput, ProposeAgreementData, ClaimOptions, ClaimRoom, } from './http/AgreementClient.js';
-export { decisionWords } from './decisionWords.js';
+export { decisionWords, speakableActor } from './decisionWords.js';
 export type { DecisionOutcome, DecisionWords, DecisionWordsInput, } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export type { InboxAckDecision, InboxAckStep, InboxAckEnvelope, PlanInboxAckOptions, } from './inboxAck.js';
@@ -25,3 +25,5 @@ export type { ContinuationKind, InboxAckDriver, InboxHandling, RepresentedPerson
 export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
 export type { EngagementGuide, EngagementGuideKind, EngagementOutcome, EngagementTaskHint, ContactPathInput, FormationInput, GraphHonesty, HireTermsHonesty, WaitingOn, } from './engagementGuide.js';
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
+export { AssistantConnectionClient, type AssistantWorkspace, } from './http/AssistantConnectionClient.js';
+export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';

package/dist/index.js

@@ -15,7 +15,7 @@ export { parseErrorMessage, parseErrorCode, throwApiError, } from './shared/apiE
 export { ApiError } from './types.js';
 // One decision, one sentence, on every rail: the reason a delivery row carries
 // when somebody answered a request this agent made, rendered as words.
-export { decisionWords } from './decisionWords.js';
+export { decisionWords, speakableActor } from './decisionWords.js';
 export { planInboxAck, planPartialInboxAck, inboxAckAllowed, inboxAckHandledIds, } from './inboxAck.js';
 export { agreementLaneId, agreementIdFromLane, isAgreementLaneId, isAgreementId } from '@ziggs-ai/contracts';
 export * from './shared/operatorKey.js';
@@ -24,3 +24,5 @@ export * from './utils/appUrls.js';
 export { sessionOrientation, } from './sessionOrientation.js';
 export { inboxEngagement, isEchoOrDuplicate, isHireWorkOrder, contactPath, formationGuide, marketplaceFormation, liveHireChangedTerms, liveHireConflictFromStatus, withdrawHeldGraph, reminderHonesty, graphReleaseHonesty, hintsFromTasks, } from './engagementGuide.js';
 export { isContextAccessRequest } from './shared/contextAccessRequest.js';
+export { AssistantConnectionClient, } from './http/AssistantConnectionClient.js';
+export { withAssistantRequest, assistantRequestHeaders } from './http/operatorHeaders.js';

package/dist/shared/operatorKey.d.ts

@@ -5,6 +5,7 @@ export interface OperatorKeyClaims {
     keyId?: string;
     ownerId?: string;
     boundAgentId?: string | null;
+    connectionClientId?: string | null;
     /**
      * How the key was authorized. MCP consent uses `mcp_oauth` or `device_code`;
      * provisioning and other mint paths carry their own provenance.

package/dist/shared/operatorKey.js

@@ -14,6 +14,7 @@ export function decodeOperatorKeyClaims(token) {
             keyId: payload.keyId,
             ownerId: payload.ownerId,
             boundAgentId: typeof payload.boundAgentId === 'string' ? payload.boundAgentId : null,
+            connectionClientId: typeof payload.connectionClientId === 'string' ? payload.connectionClientId : null,
             issuedVia: typeof payload.issuedVia === 'string' ? payload.issuedVia : undefined,
             exp: payload.exp,
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",