@ziggs-ai/api-client 0.39.3 → 0.39.5

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.39.5
+
+- `message_send` explains its "Nothing authorizes giving … access to this message" refusal: the reader has no contact basis, so ask its owner with `access_request` `scopeKind: "contact"`, then send once they approve.
+
+## 0.39.4
+
+- `access_request` accepts `scopeKind: "contact"`: ask whoever answers for a person, an agent or a workspace inbox to let you send messages to it. It is one-way: it carries no permission, names at most one holder (yourself or your own owner), reads nothing and gives no reply path. After approval the resume action is a `message_send` to that destination. A send grant is never delegated, so `context_delegate` does not offer the scope.
+
 ## 0.39.3
 
 - Message queries accept `conversationOf` to page messages connected by readable reply relationships. Readers never identify history, and every message still requires current access.

package/dist/capabilities/context.js

@@ -10,7 +10,8 @@ import { fullCreds } from './types.js';
 // `artifact` joined the context rail. Delegating an artifact grant
 // onward works (same kind, same id — an exact re-grant); narrowing a container
 // grant DOWN to an artifact inside it is deliberately not supported yet.
-const GRANT_SCOPE_KINDS = CONTEXT_GRANT_SCOPE_KINDS.filter(kind => kind !== 'address' && kind !== 'person');
+// A send grant (`contact`) is never passed on, so it is not a delegation scope.
+const GRANT_SCOPE_KINDS = CONTEXT_GRANT_SCOPE_KINDS.filter(kind => kind !== 'address' && kind !== 'person' && kind !== 'contact');
 const CONTEXT_TEMPORALS = ['from-now', 'from-start'];
 /**
  * Human/LLM-readable bounds for a context grant. folded a context
@@ -267,6 +268,9 @@ const OPEN_REF_PARAMS = {
         }])),
 };
 function resumeResource(kind, id, env) {
+    // After a send grant is approved there is nothing to read: send to the destination.
+    if (kind === 'contact')
+        return { tool: env.surface === 'mcp' ? 'ziggs_message_send' : 'message_send', args: { command: { audience: { kind: 'explicit', principalIds: [id] }, deliveries: { kind: 'explicit', principalIds: [id] }, effect: { kind: 'none' } } } };
     const tool = kind === 'message' ? 'message_read' : 'open';
     return {
         tool: env.surface === 'mcp' ? `ziggs_${tool}` : tool,
@@ -405,10 +409,10 @@ export const accessRequestCapability = {
     title: 'Request access for yourself or named readers',
     annotation: 'destructive', needsAgentId: true,
     descriptions: {
-        sdk: 'Request optional bounded access to one message, artifact, agreement context or task. Creates only a pending approval; never grants access or approves. Choose recipientId when several approvers are offered; with one, it is selected automatically: 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 go to the selected approver inbox; no conversation is needed. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. 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 follow the returned resume action. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by their authorized principal IDs); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. For releaseSource, explicitly name its authority in recipientId; approval releases only the exact output. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        sdk: 'Request optional bounded access to one message, artifact, agreement context or task, or ask to send messages to a destination (scopeKind=contact). Creates only a pending approval; never grants access or approves. Choose recipientId when several approvers are offered; with one, it is selected automatically: 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 go to the selected approver inbox; no conversation is needed. To create work under an agreement you can read but not work on (a task create refused with WORK_ACCESS_REQUIRED), request permission=work on it; only someone who can work on it may approve, and it lasts until the agreement ends. 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 follow the returned resume action. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by their authorized principal IDs); include yourself only if you need to read it too. The owner approves that exact list once and each reader gets its own grant; readers who can already read it come back as already_readable. For releaseSource, explicitly name its authority in recipientId; approval releases only the exact output. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
     },
     params: {
-        scopeKind: { type: 'string', required: true, enum: ['message', 'artifact', 'agreement', 'task'] },
+        scopeKind: { type: 'string', required: true, enum: ['message', 'artifact', 'agreement', 'task', 'contact'], description: 'contact: ask to send messages to scopeId (a person, an agent or a workspace inbox). One-way; it reads nothing and gives no reply path.' },
         scopeId: { type: 'string', description: 'Original resource id. Omit when using a hire agreementId to request its workspace summary.' },
         agreementId: { type: 'string', description: 'Artifact scope only: current hire id, used instead of scopeId to request the system-maintained workspace summary.' },
         reason: { type: 'string', required: true, description: 'Why access is needed and who will receive the reply or summary' },
@@ -447,8 +451,9 @@ export const accessRequestCapability = {
                 throw new Error(`${key} is required`);
         }
         const scopeKind = args.scopeKind;
-        if (!['message', 'artifact', 'agreement', 'task'].includes(scopeKind))
+        if (!['message', 'artifact', 'agreement', 'task', 'contact'].includes(scopeKind))
             throw new Error('Unsupported scopeKind');
+        const contact = scopeKind === 'contact';
         const agreementId = typeof args.agreementId === 'string' ? args.agreementId.trim() : undefined;
         const scopeId = typeof args.scopeId === 'string' ? args.scopeId.trim() : undefined;
         if (Boolean(agreementId) === Boolean(scopeId) || (agreementId && scopeKind !== 'artifact'))
@@ -458,13 +463,17 @@ export const accessRequestCapability = {
             throw new Error('permission must be read or work');
         if (permission === 'work' && scopeKind !== 'agreement')
             throw new Error('Only agreement access may request work permission');
+        if (contact && args.permission !== undefined && permission !== 'read')
+            throw new Error('A contact request asks to send only; omit permission');
         if (args.temporal !== undefined && args.temporal !== 'from-start')
             throw new Error('Retained resources use from-start access');
         const durationHours = args.durationHours ?? 24;
         if (typeof durationHours !== 'number' || !Number.isInteger(durationHours) || durationHours < 1 || durationHours > 168)
             throw new Error('durationHours must be an integer between 1 and 168');
         const holders = args.holders === undefined ? undefined : readersOf(args.holders);
-        if (holders && (scopeKind !== 'artifact' || agreementId || permission !== 'read'))
+        if (holders && contact && holders.length !== 1)
+            throw new Error('A contact request names one holder: yourself or your own owner');
+        if (holders && !contact && (scopeKind !== 'artifact' || agreementId || permission !== 'read'))
             throw new Error('holders is for one artifact named by scopeId, to read');
         let contributionTo;
         if (args.contributionTo !== undefined) {
@@ -483,7 +492,8 @@ export const accessRequestCapability = {
         const creds = fullCreds(env);
         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,
+            // A contact request carries no permission: the server makes it send-only.
+            ...(contact ? {} : { permission: permission }), temporal: args.temporal,
             durationHours,
             recipientId: typeof args.recipientId === 'string' ? args.recipientId.trim() : undefined,
             ...(holders ? { holders } : {}),

package/dist/capabilities/messaging.js

@@ -2,7 +2,7 @@ import { MessageRecordsClient } from '../http/MessageRecordsClient.js';
 import { fullCreds } from './types.js';
 const client = (env) => { const creds = fullCreds(env); return new MessageRecordsClient(creds.operatorKey, creds.agentId, env.baseUrl); };
 export const readMessageCapability = { key: 'message_read', names: { sdk: 'message_read', mcp: 'ziggs_message_read' }, title: 'Read exact message', descriptions: { sdk: 'Read one authorized message. Returns content, independent readers/recipients, requested-answer action slots and authorized relationships. Does not acknowledge delivery.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true } }, handler: (args, env) => client(env).get(String(args.messageId)) };
-export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; effect:{kind:"none"} or request-answers:{requests:[{requestId,responsiblePrincipalId}]} or answer:{action:{kind:"message",id,slot:"answer",requestId},artifacts:[]} or provide-input:{action}. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. Reuse operationId unchanged on retry. A causal reply alone never resolves an answer. No room required.' }, annotation: 'destructive', needsAgentId: true, params: { command: { type: 'object', required: true, description: 'MessageCommand with explicit independent audience, deliveries, action effect and optional mandate.' } }, handler: (args, env) => client(env).send(args.command) };
+export const sendMessageCapability = { key: 'message_send', names: { sdk: 'message_send', mcp: 'ziggs_message_send' }, title: 'Send message', descriptions: { sdk: 'Send the canonical command: operationId; content:{text}; audience:{kind:"explicit",principalIds:[...]}; deliveries:{kind:"explicit",principalIds:[...]}; effect:{kind:"none"} or request-answers:{requests:[{requestId,responsiblePrincipalId}]} or answer:{action:{kind:"message",id,slot:"answer",requestId},artifacts:[]} or provide-input:{action}. Optional mandate:{agreementId,taskId}, relationships:{replyToMessageId,taskIds,artifacts}, exact sources. Reuse operationId unchanged on retry. A causal reply alone never resolves an answer. No room required. Refused with "Nothing authorizes giving … access to this message" means you have no contact basis for that reader (membership, a link, an agreement or a listing): ask its owner with access_request scopeKind=contact and scopeId=that reader, then send once they approve.' }, annotation: 'destructive', needsAgentId: true, params: { command: { type: 'object', required: true, description: 'MessageCommand with explicit independent audience, deliveries, action effect and optional mandate.' } }, handler: (args, env) => client(env).send(args.command) };
 export const readRepliesCapability = { key: 'message_replies', names: { sdk: 'message_replies', mcp: 'ziggs_message_replies' }, title: 'Read replies', descriptions: { sdk: 'Read currently authorized causal replies; links never grant access. Continue using nextCursor as before.' }, annotation: 'read-only', needsAgentId: true, params: { messageId: { type: 'string', required: true }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).replies(String(args.messageId), { before: args.before, limit: args.limit }) };
 export const queryMessagesCapability = { key: 'message_list', names: { sdk: 'message_list', mcp: 'ziggs_message_list' }, title: 'Query messages', descriptions: { sdk: 'Query authorized messages. Use conversationOf with an exact message id to browse messages connected by readable reply relationships; use nextCursor as before for earlier turns. Select conversationOf independently of agreementId, taskId or participantIds. History never selects authority.' }, annotation: 'read-only', needsAgentId: true, params: { conversationOf: { type: 'string', description: 'Authorized anchor message; follows readable causal links, never a reader roster. Each result still requires read access and any execution input authorization.' }, q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string' }, taskId: { type: 'string' }, participantIds: { type: 'array', items: { type: 'string' } }, before: { type: 'string' }, limit: { type: 'number' } }, handler: (args, env) => client(env).list(args) };
 export const messageControlsCapability = { key: 'message_controls', names: { sdk: 'message_controls', mcp: 'ziggs_message_controls' }, title: 'Inspect message mandate', descriptions: { sdk: 'Discover recipients and current authority under an explicitly selected agreement/task without reading message history.' }, annotation: 'read-only', needsAgentId: true, params: { q: { type: 'string' }, senderId: { type: 'string' }, recipientIds: { type: 'array', items: { type: 'string' } }, agreementId: { type: 'string', required: true }, taskId: { type: 'string' } }, handler: (args, env) => client(env).controls(String(args.agreementId), args.taskId) };

package/dist/http/ContextGrantsClient.d.ts

@@ -96,7 +96,7 @@ export declare class ContextGrantsClient {
     issueGrant(input: IssueContextGrantInput): Promise<GrantView>;
     /** Request-only endpoint: a successful call must still have granted no access. */
     requestAccess(input: {
-        scopeKind: 'message' | 'artifact' | 'address' | 'agreement' | 'task' | 'person';
+        scopeKind: 'message' | 'artifact' | 'address' | 'agreement' | 'task' | 'person' | 'contact';
         scopeId?: string;
         agreementId?: string;
         reason: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.39.3",
+  "version": "0.39.5",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -31,7 +31,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "0.44.0",
+    "@ziggs-ai/contracts": "0.45.0",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [