@ziggs-ai/api-client 0.37.1 → 0.37.5

package/dist/capabilities/chat.js

@@ -63,7 +63,7 @@ export const openConversationCapability = {
     names: { sdk: 'chat_open', mcp: 'ziggs_chat_open' },
     title: 'Start or reuse a conversation',
     descriptions: {
-        sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses the acting agent’s pair conversation with one person or agent; newChat opens a separate subject. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
+        sdk: 'Open a conversation or explicitly invite people to a room. participantId opens/reuses your person’s conversation with one person or agent, the same room each of their agents finds; newChat opens a separate subject, which can take a name. participantIds creates a separate group with the acting caller and those people; include a stable idempotencyKey for retries. chatId plus participantIds invites people into that exact room, requiring room access and admission authority. Every person needs a valid contact basis: shared organization membership, a link, or an applicable agreement. Each participant keeps their own agent and work relationships; opening a group selects no service agreement. Group creation never expands an existing private DM. Invited teammates read from admission onward. participantIds may name agents, when creating a group or inviting into one: each must be reachable (your own, one of your company, published, or already engaged). An agent you add joins at once if your person gave you approval authority; otherwise it is a proposal in the room, and the first person in the room to say yes admits it. The result lists each id as added, already-here or pending. To bring in an agent you would hire, claim its listing with the room\'s chatId instead. Your own missing seat is asked for with access_request. Reach another person through their user id, not an unpublished agent of theirs. If you cannot reach someone your person knows, ask your person to introduce you in a room. Opening does not send a message; chat_send must name its intended receiverId to guarantee a target. To list accessible rooms, use grant_list with scopeKind ["chat"].',
     },
     annotation: 'write',
     params: {
@@ -74,8 +74,8 @@ export const openConversationCapability = {
         participantIds: { type: 'array', items: { type: 'string' }, description: '1–20 known ids. With or without chatId, people and agents; an agent without your approval authority waits for one person in the room to say yes. Use instead of participantId. Each invitation is authorized separately.' },
         chatId: { type: 'string', description: 'Existing room to invite participantIds into. Never creates another room. Omit creation options and agreementId.' },
         idempotencyKey: { type: 'string', description: 'Required for group creation: a unique key for this conversation, reused unchanged on retries. A different participant set needs a new key.' },
-        name: { type: 'string', description: 'Name for a new group, 1–80 characters. Pair rooms and team channels take no name. A retry of the same idempotencyKey keeps the first name. Rename later is PATCH /chats/:chatId by someone who can admit people.' },
-        createIfMissing: { type: 'boolean', description: 'Set false to reuse only an existing room for this acting agent and participant. A missing room is refused without creating a replacement.' },
+        name: { type: 'string', description: 'Name for a new group or a newChat room, 1–80 characters. Pair rooms and team channels take no name. A retry of the same idempotencyKey keeps the first name. Rename later is PATCH /chats/:chatId by someone who can admit people.' },
+        createIfMissing: { type: 'boolean', description: 'Set false to reuse only an existing room with this participant. A missing room is refused without creating a replacement.' },
         newChat: {
             type: 'boolean',
             description: 'Open a separate chat even though one is already open with the named participants. ' +
@@ -108,8 +108,8 @@ export const openConversationCapability = {
         else if (args.chatId || args.idempotencyKey) {
             throw new Error('chatId and idempotencyKey require participantIds');
         }
-        if (typeof args.name === 'string' && args.name.trim() && !Array.isArray(args.participantIds)) {
-            throw new Error('A name is for a new group. Pair rooms take no name; the person is the name.');
+        if (typeof args.name === 'string' && args.name.trim() && !Array.isArray(args.participantIds) && args.newChat !== true) {
+            throw new Error('A name is for a new group or a newChat room. Pair rooms take no name; the person is the name.');
         }
         const { chatId, reused, invited, name } = await openConversation({
             ...(typeof args.participantId === 'string' ? { participantId: args.participantId } : {}),

package/dist/capabilities/context.d.ts

@@ -50,6 +50,5 @@ export declare const RESOURCE_UNREADABLE_MESSAGE = "This exists and you cannot r
 export declare function explainRefusedRead(kind: 'agreement' | 'task' | 'chat' | 'artifact', id: string, env: CapabilityEnv): Promise<RefusedRead | null>;
 export declare const openCapability: CapabilityDefinition;
 export declare const accessExplainCapability: CapabilityDefinition;
-export declare const contextRequestCapability: CapabilityDefinition;
 export declare const accessRequestCapability: CapabilityDefinition;
 export declare const CONTEXT_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/context.js

@@ -391,36 +391,6 @@ export const accessExplainCapability = {
         return presentOpenResult(result, env);
     },
 };
-export const contextRequestCapability = {
-    key: 'context_request',
-    names: { sdk: 'context_request', mcp: 'ziggs_context_request' },
-    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.',
-    },
-    annotation: 'destructive', needsAgentId: true,
-    params: {
-        artifactId: { type: 'string', required: true },
-        chatId: { type: 'string', required: true },
-        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' },
-    },
-    handler: async (args, env) => {
-        for (const key of ['artifactId', 'chatId', 'ownerId', 'reason'])
-            if (typeof args[key] !== 'string' || !String(args[key]).trim())
-                throw new Error(`${key} is required`);
-        const durationHours = args.durationHours === undefined ? 24 : Number(args.durationHours);
-        if (!Number.isInteger(durationHours) || durationHours < 1 || durationHours > 168)
-            throw new Error('durationHours must be an integer between 1 and 168');
-        const creds = fullCreds(env);
-        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: `${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. */
 function requestAccessAction(args, env) {
     return {
@@ -430,13 +400,32 @@ function requestAccessAction(args, env) {
         requiresApproval: true,
     };
 }
+/** The readers an access request names: kinds stated, ids distinct, at most 20. */
+function readersOf(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 20)
+        throw new Error('holders must list 1 to 20 readers');
+    const seen = new Set();
+    return value.map((entry, i) => {
+        const kind = entry?.kind;
+        const id = entry?.id;
+        if (kind !== 'agent' && kind !== 'user' && kind !== 'org')
+            throw new Error(`holders[${i}].kind must be agent, user or org`);
+        if (typeof id !== 'string' || !id.trim())
+            throw new Error(`holders[${i}].id is required`);
+        const key = `${kind}:${id.trim()}`;
+        if (seen.has(key))
+            throw new Error(`holders names the same reader twice (holders[${i}])`);
+        seen.add(key);
+        return { kind, id: id.trim() };
+    });
+}
 export const accessRequestCapability = {
     key: 'access_request',
     names: { sdk: 'access_request', mcp: 'ziggs_access_request' },
-    title: 'Request access for yourself',
+    title: 'Request access for yourself or named readers',
     annotation: 'destructive', 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. 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. 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 open the returned scope. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
+        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. 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 open the returned scope. To arrange reading of one artifact for others, name them in holders (agents by id, people or workspaces by id or the participant reference this room shows you); 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. Hiring alone grants no source access. Revocation and expiry are checked by the system.',
     },
     params: {
         scopeKind: { type: 'string', required: true, enum: ['artifact', 'chat', 'agreement', 'task'] },
@@ -451,6 +440,18 @@ export const accessRequestCapability = {
         // comes back refused with the people this agent may ask. Required in the
         // schema, a host refused the call before that list could arrive.
         recipientId: { type: 'string', description: 'Who to ask: workBrief.actingFor.customer.id (the customer of this hire) or workBrief.actingFor.operator.id (your operator). Without it, the refusal lists who you can ask.' },
+        holders: {
+            type: 'array',
+            description: 'Artifact only, read only: up to 20 readers, each { kind: "agent" | "user" | "org", id }. Leave yourself out to arrange it for others. Omit to ask for yourself.',
+            items: {
+                type: 'object',
+                properties: {
+                    kind: { type: 'string', enum: ['agent', 'user', 'org'] },
+                    id: { type: 'string' },
+                },
+                required: ['kind', 'id'],
+            },
+        },
         idempotencyKey: { type: 'string', description: 'Reuse for the same logical request' },
     },
     handler: async (args, env) => {
@@ -477,14 +478,26 @@ export const accessRequestCapability = {
         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'))
+            throw new Error('holders is for one artifact named by scopeId, to read');
         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,
             durationHours, chatId: args.chatId,
             recipientId: typeof args.recipientId === 'string' ? args.recipientId.trim() : undefined,
+            ...(holders ? { holders } : {}),
         }, { idempotencyKey: args.idempotencyKey, laneId: creds.laneId });
         const actingAgentId = result.actingAgentId ?? (creds.agentId || undefined);
+        if (result.status === 'already_readable') {
+            return {
+                ...result, outcome: 'already_readable', state: 'not_requested',
+                ...(actingAgentId ? { actingAgentId } : {}),
+                scope: result.scope ?? { kind: scopeKind, id: scopeId },
+                note: result.message ?? 'Every reader you named can already read it. Nothing was asked.',
+            };
+        }
         return {
             ...result, outcome: 'pending', state: 'requested',
             ...(actingAgentId ? { actingAgentId } : {}),
@@ -500,7 +513,6 @@ export const CONTEXT_CAPABILITIES = [
     openCapability,
     accessExplainCapability,
     accessRequestCapability,
-    contextRequestCapability,
     contextDelegateCapability,
     contextExpandReachCapability,
     contextDiscoverGrantableCapability,

package/dist/capabilities/index.d.ts

@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
-export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, type RefusedRead, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, type RefusedRead, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/index.js

@@ -12,7 +12,7 @@ export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTa
 export { AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION } from './proposeProviderId.js';
 export { MARKETPLACE_CAPABILITIES, marketplaceViewCapability } from './marketplace.js';
 export { GRANTS_CAPABILITIES, listGrantsCapability } from './grants.js';
-export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, accessRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, explainRefusedRead, RESOURCE_HIDDEN_MESSAGE, RESOURCE_UNREADABLE_MESSAGE, } from './context.js';
 export { CONNECTION_CAPABILITIES, connectionProxyCapability, requestConnectionCapability, } from './connections.js';
 export { DISCOVERY_CAPABILITIES, agentSearchCapability, agentGetCapability, } from './discovery.js';
 export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';

package/dist/capabilities/links.d.ts

@@ -5,10 +5,9 @@ export declare function webAppOrigin(env: CapabilityEnv): string;
  *
  * Opening a chat is itself the admission: the backend issues a standing from-now
  * write grant to each side as it creates the room, so both delegates can
- * read and post immediately. Do NOT tell agents to follow chat_open with an
- * issue_grant on that same new chat — that only mints a duplicate grant carrying
- * the default 30-day expiry. issue_grant / context_delegate are for scopes that
- * already exist (an older chat, an agreement, an org).
+ * read and post immediately. Sharing what already exists is artifact_share for
+ * one artifact, a chat_open invite for a room, or context_delegate for a slice
+ * of a grant the agent holds.
  */
 export declare function linkIsReachOnly(env: CapabilityEnv): string;
 export declare const listLinksCapability: CapabilityDefinition;

package/dist/capabilities/links.js

@@ -10,14 +10,13 @@ export function webAppOrigin(env) {
  *
  * Opening a chat is itself the admission: the backend issues a standing from-now
  * write grant to each side as it creates the room, so both delegates can
- * read and post immediately. Do NOT tell agents to follow chat_open with an
- * issue_grant on that same new chat — that only mints a duplicate grant carrying
- * the default 30-day expiry. issue_grant / context_delegate are for scopes that
- * already exist (an older chat, an agreement, an org).
+ * read and post immediately. Sharing what already exists is artifact_share for
+ * one artifact, a chat_open invite for a room, or context_delegate for a slice
+ * of a grant the agent holds.
  */
 export function linkIsReachOnly(env) {
     return env.surface === 'mcp'
-        ? 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side (ziggs_chat_open, participantId = that link\'s `peer.id`): delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Use `peer.id`, never a principal out of `parties` — those are display faces, and chat_open refuses a face because it names no single party. Opening the room admits both sides to read and post from then on. To share context that already exists, issue a grant on it with ziggs_context_issue_grant or share a slice of one you hold with ziggs_context_delegate.'
+        ? 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side (ziggs_chat_open, participantId = that link\'s `peer.id`): delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Use `peer.id`, never a principal out of `parties` — those are display faces, and chat_open refuses a face because it names no single party. Opening the room admits both sides to read and post from then on. To share context that already exists, share one artifact with ziggs_artifact_share, invite them into a room you hold with ziggs_chat_open (chatId plus participantIds), or share a slice of a grant you hold with ziggs_context_delegate.'
         : 'A link is reach-only — it shares no context on its own. Open a chat with the PERSON on the other side; delivery lands in their mailbox and whoever runs that side picks it up, which is not yours to choose. Opening the room admits both sides to it from then on. To share context that already exists, share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one.';
 }
 const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
@@ -84,7 +83,7 @@ export const listLinksCapability = {
             readPlan.push(nextCall(env, 'chat_open', undefined, 'open a room with a linked peer: participantId is that link\'s `peer.id`. Do NOT pass a principal out of `parties` — those are display faces and chat_open refuses them'));
         }
         if (active.length) {
-            readPlan.push(nextCall(env, 'context_issue_grant', undefined, 'share context that already exists: a link does not share any on its own'));
+            readPlan.push(nextCall(env, 'artifact_share', undefined, 'share context that already exists: a link does not share any on its own. One artifact with artifact_share; a room you hold by inviting them with chat_open (chatId plus participantIds)'));
         }
         return {
             count: links.length,

package/dist/capabilities/mcpBriefs.js

@@ -21,11 +21,11 @@ const BRIEFS = {
         },
     },
     ziggs_inbox: {
-        does: 'Reads your inbox: deliveries oldest first, tasks, decisions, sessionChatCard; waitSeconds holds for news. Observes only: no claim or ack.',
+        does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news. Observes only: no claim or ack.',
         returns: 'a readPlan of next calls; backlog if more is unread',
         next: 'ziggs_inbox_claim to handle them',
         compact: {
-            does: 'Reads your inbox: deliveries oldest first, tasks, decisions, sessionChatCard; waitSeconds holds for news.',
+            does: 'Reads your inbox: deliveries by recipient, tasks, decisions, sessionChatCard; waitSeconds holds for news.',
             changes: 'takes or renews this host’s lease',
             next: 'ziggs_inbox_ack after handling',
         },
@@ -137,14 +137,6 @@ const BRIEFS = {
         does: 'Asks for access to an artifact, chat, agreement or task for this agent. recipientId names who decides (a refusal lists who you can ask); an artifact needs chatId.',
         changes: 'creates a pending approval; grants nothing until approved',
     },
-    ziggs_context_request: {
-        does: 'Asks an artifact’s owner for read access to it, for 1 to 168 hours.',
-        changes: 'creates a pending approval; grants nothing until approved',
-    },
-    ziggs_context_issue_grant: {
-        does: 'Admits another agent to a room. Agreement, org, artifact and task grants need your person’s authority.',
-        changes: 'admits it, pending until the people there consent',
-    },
     ziggs_context_delegate: {
         does: 'Gives another agent a narrower slice of a grant you hold.',
         changes: 'grants it, or opens a request its owner approves (pending_approval)',
@@ -204,7 +196,7 @@ const BRIEFS = {
         changes: 'the old steps are replaced',
     },
     ziggs_task_set_result: {
-        does: 'Closes a task as completed, failed or cancelled; the result is for the next agent, a person reads it in your conversation. The agreement stays active.',
+        does: 'Closes a task as completed or failed; the result is for the next agent, a person reads it in your conversation. The agreement stays active.',
         changes: 'closes the task, proving nobody read or paid; the same idempotencyKey is a no-op',
     },
     ziggs_task_cancel: {

package/dist/capabilities/nextCall.js

@@ -28,7 +28,6 @@ const REQUIRED_ARGS = {
     agreement_subcontract: ['parentAgreementId', 'executorId', 'description'],
     agreement_respond: ['agreementId'],
     introduction_redeem: ['token'],
-    context_issue_grant: ['holderId', 'scopeKind', 'scopeId'],
     artifact_share: ['artifactId', 'holderId'],
     context_delegate: ['parentGrantId', 'holderId', 'scopeKind', 'scopeId', 'temporal'],
     task_create: ['agreementId', 'description'],
@@ -59,7 +58,6 @@ const HTTP_BINDINGS = {
         path: '/agreements/:agreementId/approvals/:partyId',
     },
     marketplace_view: { method: 'GET', path: '/marketplace/offers' },
-    context_issue_grant: { method: 'POST', path: '/context/grants' },
     artifact_share: { method: 'POST', path: '/context/artifacts/:artifactId/share' },
     context_delegate: { method: 'POST', path: '/context/grants/:parentGrantId/delegate' },
     open: { method: 'POST', path: '/context/open' },
@@ -74,11 +72,9 @@ const HTTP_BINDINGS = {
 };
 /**
  * Intentional surface exclusions. A ready next call has to exist as a tool
- * on the calling surface — SDK context exposes delegate, not a top-level
- * issue grant (tool-surface-parity).
+ * on the calling surface (tool-surface-parity).
  */
 const SURFACE_EXPOSURE = {
-    context_issue_grant: ['mcp'],
     // The hosted SDK surface enumerates its own work with task_list and reads a
     // task from the wake it arrived on; ziggs_task_get is the MCP delegate's
     // one-task read. Naming it to an SDK agent would offer a tool it cannot call.
@@ -98,9 +94,6 @@ const MATERIAL_EFFECTS = {
     introduction_redeem: {
         relationship: 'a stranger redeem stages a link both humans must approve — it is not a live connection yet',
     },
-    context_issue_grant: {
-        disclosure: 'issues a grant that widens who can read that scope',
-    },
     link_propose: {
         relationship: 'proposes a reach-only link; nothing is shared until they accept',
     },

package/dist/http/ContextGrantsClient.d.ts

@@ -109,31 +109,12 @@ export declare class ContextGrantsClient {
         ownerId?: string;
         /** Who to ask, from the people the server offers this wake. */
         recipientId?: string;
+        /** Artifact only: who should read it, if not only the caller. One grant each. */
+        holders?: AccessReader[];
     }, opts?: {
         idempotencyKey?: string;
         laneId?: string;
-    }): Promise<{
-        status: 'pending_approval';
-        agreementId: string;
-        accessGranted: false;
-        actingAgentId?: string;
-        scope?: {
-            kind: string;
-            id: string;
-        };
-    } & RequestSentTo>;
-    requestArtifactAccess(artifactId: string, input: {
-        chatId: string;
-        ownerId: string;
-        reason: string;
-        durationHours?: number;
-    }, opts?: {
-        idempotencyKey?: string;
-        laneId?: string;
-    }): Promise<{
-        status: 'pending_approval';
-        agreementId: string;
-    } & RequestSentTo>;
+    }): Promise<AccessRequestResult>;
     delegateGrant(parentGrantId: string, input: DelegateContextGrantInput, opts?: {
         idempotencyKey?: string;
     }): Promise<DelegateContextGrantResult>;
@@ -167,6 +148,31 @@ export declare class ContextGrantsClient {
     }>;
 }
 /** Who got a request card and where they answer it, as the server says. */
+/** One reader an artifact access request asks for, named with its kind. */
+export interface AccessReader {
+    kind: 'agent' | 'user' | 'org';
+    id: string;
+}
+/** What a request did for one named reader. */
+export interface AccessReaderOutcome extends AccessReader {
+    outcome: 'already_readable' | 'awaiting_approval';
+}
+export type AccessRequestResult = {
+    accessGranted: false;
+    actingAgentId?: string;
+    scope?: {
+        kind: string;
+        id: string;
+    };
+    /** Per named reader, when the request named readers. */
+    readers?: AccessReaderOutcome[];
+} & RequestSentTo & ({
+    status: 'pending_approval';
+    agreementId: string;
+} | {
+    status: 'already_readable';
+    agreementId: null;
+});
 export interface RequestSentTo {
     sentTo?: {
         id: string;

package/dist/http/ContextGrantsClient.js

@@ -77,28 +77,22 @@ export class ContextGrantsClient {
         if (!res.ok)
             throwApiError(res, body, `requestAccess failed: ${res.status}`);
         const result = JSON.parse(body);
+        const readers = Array.isArray(result.readers) ? { readers: result.readers } : {};
+        const common = {
+            accessGranted: false,
+            ...(typeof result.actingAgentId === 'string' && result.actingAgentId ? { actingAgentId: result.actingAgentId } : {}),
+            ...(result.scope ? { scope: result.scope } : {}),
+            ...readers,
+            ...sentToOf(result),
+        };
+        // Every named reader already reads it: nothing was asked.
+        if (result.status === 'already_readable' && result.accessGranted === false) {
+            return { status: 'already_readable', agreementId: null, ...common };
+        }
         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, ...(typeof result.actingAgentId === 'string' && result.actingAgentId ? { actingAgentId: result.actingAgentId } : {}), ...(result.scope ? { scope: result.scope } : {}), ...sentToOf(result) };
-    }
-    async requestArtifactAccess(artifactId, input, opts) {
-        const res = await fetch(`${this.baseUrl}/context/artifacts/${encodeURIComponent(artifactId)}/access-requests`, {
-            method: 'POST',
-            headers: buildOperatorHeaders(this.operatorKey, this.agentId, {
-                'content-type': 'application/json',
-                ...(opts?.idempotencyKey ? { 'Idempotency-Key': opts.idempotencyKey } : {}),
-                ...(opts?.laneId ? { 'x-ziggs-lane': opts.laneId } : {}),
-            }),
-            body: JSON.stringify(input),
-        });
-        const body = await res.text().catch(() => '');
-        if (!res.ok)
-            throwApiError(res, body, `requestArtifactAccess failed: ${res.status}`);
-        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, ...sentToOf(result) };
+        return { status: 'pending_approval', agreementId: result.agreementId, ...common };
     }
     async delegateGrant(parentGrantId, input, opts) {
         const res = await fetch(`${this.baseUrl}/context/grants/${encodeURIComponent(parentGrantId)}/delegate`, {

package/dist/http/TaskClient.d.ts

@@ -48,6 +48,8 @@ export interface CreateTaskGraphNodeData {
     assigneeId?: string;
     waitsOn?: string[];
     joinKind?: 'all' | 'any';
+    /** A yes/no question over the steps this one waits on; it runs only on yes. */
+    runIf?: string;
 }
 export interface CreateTaskGraphData {
     nodes: CreateTaskGraphNodeData[];

package/dist/http/grants.d.ts

@@ -36,16 +36,8 @@ export type GrantBasisKind = 'creation' | 'publication' | 'membership' | 'accept
  * stopped showing a whole scope kind after `artifact` was added; anything that
  * means "every context scope" should read this.
  */
-export declare const CONTEXT_GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task"];
-/**
- * Every scope kind across every rail: context + connection + payment + consent
- * + carrier. Mirrors the server's `GRANT_SCOPE_KINDS` (grants/grant-view.ts),
- * which is the list `GET /grants?scopeKind=` validates against — a kind missing
- * here cannot be asked for at all, which is the failure the comment above
- * describes.
- */
-export declare const GRANT_SCOPE_KINDS: readonly ["chat", "agreement", "org", "artifact", "task", "connection", "wallet", "consent", "inbox"];
-export type GrantScopeKind = (typeof GRANT_SCOPE_KINDS)[number];
+import { CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, type ContextGrantScopeKind, type GrantScopeKind } from '@ziggs-ai/contracts';
+export { CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, type ContextGrantScopeKind, type GrantScopeKind, };
 /**
  * The scope a grant is over, and one caveat on it — the wire's shapes.
  *

package/dist/http/grants.js

@@ -6,32 +6,8 @@
  * stopped showing a whole scope kind after `artifact` was added; anything that
  * means "every context scope" should read this.
  */
-export const CONTEXT_GRANT_SCOPE_KINDS = [
-    'chat',
-    'agreement',
-    'org',
-    // narrowest context scope
-    'artifact',
-    // a branch of a work graph: the named task and everything under it, now and
-    // in future. Holding one is what being in a job means.
-    'task',
-];
-/**
- * Every scope kind across every rail: context + connection + payment + consent
- * + carrier. Mirrors the server's `GRANT_SCOPE_KINDS` (grants/grant-view.ts),
- * which is the list `GET /grants?scopeKind=` validates against — a kind missing
- * here cannot be asked for at all, which is the failure the comment above
- * describes.
- */
-export const GRANT_SCOPE_KINDS = [
-    ...CONTEXT_GRANT_SCOPE_KINDS,
-    'connection',
-    'wallet',
-    // approval authority — who may answer a slot
-    'consent',
-    // carrier grants — who reads whose mailbox
-    'inbox',
-];
+import { CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, } from '@ziggs-ai/contracts';
+export { CONTEXT_GRANT_SCOPE_KINDS, GRANT_SCOPE_KINDS, };
 /** Value of the first caveat of `type` on a grant, or undefined. */
 export function grantCaveat(grant, type) {
     return grant.caveats.find((c) => c.type === type)?.value;

package/dist/inboxAck.d.ts

@@ -8,7 +8,6 @@
  */
 export interface InboxAckEnvelope {
     ackTo?: string | null;
-    truncatedRequests?: number | null;
     deliveries?: ReadonlyArray<{
         resourceId?: string | null;
         assigneeId?: string | null;

package/dist/inboxAck.js

@@ -31,8 +31,6 @@ export function inboxAckHandledIds(envelope, ownAgentId, ownAgentIds) {
 export function inboxAckAllowed(envelope, opts = {}) {
     if (!envelope.ackTo)
         return false;
-    if ((envelope.truncatedRequests ?? 0) !== 0)
-        return false;
     const failures = opts.failures ?? 0;
     if (failures > 0 && !opts.forceAck)
         return false;
@@ -80,8 +78,6 @@ function gatingRows(envelope, ownAgentId, ownAgentIds) {
  * backend is handled: the caller keeps its single end-of-pass ack.
  */
 export function planPartialInboxAck(envelope, handled, opts = {}) {
-    if ((envelope.truncatedRequests ?? 0) !== 0)
-        return null;
     const failures = opts.failures ?? 0;
     if (failures > 0 && !opts.forceAck)
         return null;

package/dist/types.d.ts

@@ -1,6 +1,4 @@
-import type { AgreementPartySide, AgreementParties, PrincipalPresentation, InboxDeliveryRef } from '@ziggs-ai/contracts';
-import type { InboxRequestChannel } from '@ziggs-ai/contracts';
-import type { InboxPartyKind } from '@ziggs-ai/contracts';
+import { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, type AgreementPartySide, type AgreementParties, type AgreementStatusValue, type BroadcastAudience, type InboxDeliveryRef, type InboxPartyKind, type InboxRequestChannel, type PrincipalPresentation, type TaskStateValue } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
  *
@@ -60,7 +58,7 @@ export interface Creds {
     /** Person-readable window name, sent as `X-Ziggs-Session-Name`. */
     sessionName?: string;
 }
-export type TaskState = 'active' | 'proposal' | 'completed' | 'failed' | 'cancelled' | 'ledger_open';
+export type TaskState = TaskStateValue;
 export type PlanStepStatus = 'pending' | 'in_progress' | 'completed' | 'skipped';
 export interface PlanStep {
     stepId: string;
@@ -114,6 +112,20 @@ export interface Task {
     } | null;
     graphNodeId?: string | null;
     heldByGraphReview?: boolean;
+    /**
+     * A graph step that runs only if a yes/no question holds over the steps it
+     * waits on. Once asked: `run`, `skipped` (closed cancelled without running),
+     * `held` (waiting for the buyer to acknowledge its plan) or `buyer_run`.
+     */
+    runIf?: {
+        question: string;
+        outcome?: 'run' | 'skipped' | 'held' | 'buyer_run';
+        answer?: 'yes' | 'no' | null;
+        confidence?: number | null;
+        reason?: string;
+        decidedAt?: string;
+        decidedBy?: string | null;
+    } | null;
     plan?: {
         steps?: PlanStep[];
     };
@@ -139,15 +151,9 @@ export interface Task {
     payerIsYou?: boolean;
     proposedToIsYou?: boolean;
 }
-export type AgreementStatus = 'pending' | 'active' | 'fulfilled' | 'cancelled' | 'rejected' | (string & {});
+export type AgreementStatus = AgreementStatusValue;
 export type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'countered' | 'expired' | (string & {});
-/** ⚠️ Mirrors the server's engagement-kind constant; the server is authoritative. */
-export declare const AGREEMENT_ENGAGEMENT_KIND: {
-    readonly HIRE: "hire";
-    readonly SERVICE: "service";
-    /** a bilateral reach link between two agents (no money, no work). */
-    readonly LINK: "link";
-};
+export { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, type BroadcastAudience, };
 export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGREEMENT_ENGAGEMENT_KIND];
 /**
  * One side of an agreement, as the wire carries it.
@@ -161,15 +167,6 @@ export type EngagementKind = (typeof AGREEMENT_ENGAGEMENT_KIND)[keyof typeof AGR
 export type { AgreementPartySide };
 /** The four sides of an agreement, each {@link AgreementPartySide}. */
 export type { AgreementParties };
-/** Both ids on one side, principal first, absent ones dropped. */
-export declare function partySideIds(side: AgreementPartySide | null | undefined): string[];
-/**
- * Every agent that acted on this agreement, deduped.
- *
- * The read for "is this agent a party?" — an agent id lives in `actor` alone,
- * so widening the match to `principal` would hit an unrelated estate.
- */
-export declare function partyActorIds(parties: AgreementParties | null | undefined): string[];
 /** Compact agreement reference carried by task reads. */
 export interface AgreementSummary {
     agreementId: string;
@@ -289,7 +286,6 @@ export declare const EntryTypes: {
     readonly TASK_HISTORY: "task_history";
 };
 export type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
-/** ⚠️ Mirrors the server's content-type constant; the server is authoritative. */
 export declare const ContentTypes: {
     readonly TEXT: "text";
     readonly OPERATION: "operation";
@@ -297,24 +293,13 @@ export declare const ContentTypes: {
     readonly RESULT: "result";
     readonly AGREEMENT_UPDATE: "agreement_update";
     readonly TASK: "task";
-    readonly PROPOSAL: "proposal";
+    readonly TASK_PLAN_STEP: "task_plan_step";
     readonly THOUGHT: "thought";
-    /** @deprecated legacy alias for AGREEMENT_UPDATE */
-    readonly TASK_UPDATE: "task_update";
+    readonly PROPOSAL: "proposal";
 };
 export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
 /** ⚠️ Mirrors the server's entry/content-type validation; the server is authoritative. */
 export declare function isValidContentType(contentType: string, entryType: string): boolean;
-/** ⚠️ Mirrors the server's sentinel. Fully-public broadcast target. */
-export declare const OPEN_AGREEMENT_TARGET: "everyone";
-/** ⚠️ Mirrors the server's sentinel. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
-export declare const ORG_AGREEMENT_TARGET: "org";
-/** Audience for a broadcast proposal: fully public ('everyone') or org-scoped ('org'). */
-export type BroadcastAudience = typeof OPEN_AGREEMENT_TARGET | typeof ORG_AGREEMENT_TARGET;
-/** Both broadcast sentinels — values that occupy a party slot but are NOT real principal ids. */
-export declare const BROADCAST_TARGETS: readonly ["everyone", "org"];
-/** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
-export declare function isBroadcastTarget(id: string | null | undefined): boolean;
 export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';
 /** Display + entitlement face for a principal on the message/roster wire. */
 export type { PrincipalPresentation };

package/dist/types.js

@@ -1,3 +1,4 @@
+import { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, MESSAGE_CONTENT_TYPE, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, } from '@ziggs-ai/contracts';
 /**
  * One failure shape for every HTTP client path.
  *
@@ -27,32 +28,7 @@ export class RateLimitedError extends ApiError {
         this.retryAfterMs = retryAfterMs;
     }
 }
-/** ⚠️ Mirrors the server's engagement-kind constant; the server is authoritative. */
-export const AGREEMENT_ENGAGEMENT_KIND = {
-    HIRE: 'hire',
-    SERVICE: 'service',
-    /** a bilateral reach link between two agents (no money, no work). */
-    LINK: 'link',
-};
-/** The four sides, in the order every fan-out walks them. */
-const AGREEMENT_PARTY_SIDES = ['payer', 'provider', 'proposedTo', 'creator'];
-/** Both ids on one side, principal first, absent ones dropped. */
-export function partySideIds(side) {
-    return [side?.principal, side?.actor].filter((id) => typeof id === 'string' && id.length > 0);
-}
-/**
- * Every agent that acted on this agreement, deduped.
- *
- * The read for "is this agent a party?" — an agent id lives in `actor` alone,
- * so widening the match to `principal` would hit an unrelated estate.
- */
-export function partyActorIds(parties) {
-    // The wire always sends all four sides; a caller may still hand us nothing.
-    const p = parties ?? {};
-    return [
-        ...new Set(AGREEMENT_PARTY_SIDES.map((name) => p[name]?.actor).filter((id) => typeof id === 'string' && id.length > 0)),
-    ];
-}
+export { AGREEMENT_ENGAGEMENT_KIND, BROADCAST_TARGETS, OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET, isBroadcastTarget, partyActorIds, partySideIds, };
 /** ⚠️ Mirrors the server's entry-type constant; the server is authoritative. */
 export const EntryTypes = {
     MESSAGE: 'message',
@@ -62,38 +38,28 @@ export const EntryTypes = {
     /** @deprecated legacy alias for AGREEMENT_HISTORY */
     TASK_HISTORY: 'task_history',
 };
-/** ⚠️ Mirrors the server's content-type constant; the server is authoritative. */
-export const ContentTypes = {
-    TEXT: 'text',
-    OPERATION: 'operation',
-    CONTEXT: 'context',
-    RESULT: 'result',
-    AGREEMENT_UPDATE: 'agreement_update',
-    TASK: 'task',
-    PROPOSAL: 'proposal',
-    THOUGHT: 'thought',
-    /** @deprecated legacy alias for AGREEMENT_UPDATE */
-    TASK_UPDATE: 'task_update',
-};
+export const ContentTypes = MESSAGE_CONTENT_TYPE;
 const VALID_CONTENT_TYPES = {
     [EntryTypes.MESSAGE]: [ContentTypes.TEXT],
-    [EntryTypes.NOTIFICATION]: [ContentTypes.TEXT, ContentTypes.TASK, ContentTypes.PROPOSAL],
-    [EntryTypes.ARTIFACT]: [ContentTypes.OPERATION, ContentTypes.CONTEXT, ContentTypes.RESULT, ContentTypes.TEXT, ContentTypes.THOUGHT],
-    [EntryTypes.AGREEMENT_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
-    [EntryTypes.TASK_HISTORY]: [ContentTypes.AGREEMENT_UPDATE, ContentTypes.TASK_UPDATE],
+    [EntryTypes.NOTIFICATION]: [
+        ContentTypes.TEXT,
+        ContentTypes.TASK,
+        ContentTypes.TASK_PLAN_STEP,
+        ContentTypes.PROPOSAL,
+        ContentTypes.AGREEMENT_UPDATE,
+    ],
+    [EntryTypes.ARTIFACT]: [
+        ContentTypes.OPERATION,
+        ContentTypes.CONTEXT,
+        ContentTypes.RESULT,
+        ContentTypes.TEXT,
+        ContentTypes.THOUGHT,
+    ],
+    [EntryTypes.AGREEMENT_HISTORY]: [ContentTypes.AGREEMENT_UPDATE],
+    [EntryTypes.TASK_HISTORY]: [ContentTypes.AGREEMENT_UPDATE],
 };
 /** ⚠️ Mirrors the server's entry/content-type validation; the server is authoritative. */
 export function isValidContentType(contentType, entryType) {
     return VALID_CONTENT_TYPES[entryType]?.includes(contentType) ?? false;
 }
-/** ⚠️ Mirrors the server's sentinel. Fully-public broadcast target. */
-export const OPEN_AGREEMENT_TARGET = 'everyone';
-/** ⚠️ Mirrors the server's sentinel. Org-scoped broadcast: visible/claimable only by members of the agreement's orgId. */
-export const ORG_AGREEMENT_TARGET = 'org';
-/** Both broadcast sentinels — values that occupy a party slot but are NOT real principal ids. */
-export const BROADCAST_TARGETS = [OPEN_AGREEMENT_TARGET, ORG_AGREEMENT_TARGET];
-/** True when `id` is a broadcast sentinel ('everyone' | 'org') rather than a concrete principal id. */
-export function isBroadcastTarget(id) {
-    return id === OPEN_AGREEMENT_TARGET || id === ORG_AGREEMENT_TARGET;
-}
 export { isPersonaFaceRef as isPersonaRef, isRoomBindingRef as isRoomPresentationRef, isPresentationRef as isOpaquePresentationRef, } from '@ziggs-ai/contracts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/api-client",
-  "version": "0.37.1",
+  "version": "0.37.5",
   "description": "HTTP and WebSocket client for the Ziggs backend API",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "test:watch": "node --import tsx/esm --test --watch test/*.test.ts"
   },
   "dependencies": {
-    "@ziggs-ai/contracts": "^0.21.0",
+    "@ziggs-ai/contracts": "^0.23.3",
     "socket.io-client": "^4.7.0"
   },
   "keywords": [