@ziggs-ai/api-client 0.20.0 → 0.21.0

package/dist/capabilities/agreementVerbs.d.ts

@@ -22,3 +22,10 @@ export declare const agreementRequestCapability: CapabilityDefinition;
 export declare const agreementOfferCapability: CapabilityDefinition;
 export declare const agreementHandoffCapability: CapabilityDefinition;
 export declare const AGREEMENT_VERB_CAPABILITIES: CapabilityDefinition[];
+/**
+ * Subcontract sits next to the propose verbs, not inside them: the parent
+ * already exists, and the conversation is optional. The server uses the
+ * parent's own chat when none is named. That list of required arguments is
+ * this definition — nextCall, MCP, and the SDK tool all read it.
+ */
+export declare const agreementSubcontractCapability: CapabilityDefinition;

package/dist/capabilities/agreementVerbs.js

@@ -1,4 +1,4 @@
-import { getAgreement, proposeBroadcast, proposeDirectTo, } from '../http/AgreementClient.js';
+import { delegateAgreement, getAgreement, proposeBroadcast, proposeDirectTo, } from '../http/AgreementClient.js';
 import { publishOffer } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
@@ -382,3 +382,86 @@ export const AGREEMENT_VERB_CAPABILITIES = [
     agreementOfferCapability,
     agreementHandoffCapability,
 ];
+/**
+ * Subcontract sits next to the propose verbs, not inside them: the parent
+ * already exists, and the conversation is optional. The server uses the
+ * parent's own chat when none is named. That list of required arguments is
+ * this definition — nextCall, MCP, and the SDK tool all read it.
+ */
+export const agreementSubcontractCapability = {
+    key: 'agreement_subcontract',
+    names: { sdk: 'agreement_subcontract', mcp: 'ziggs_agreement_subcontract' },
+    title: 'Subcontract part of your work',
+    descriptions: {
+        sdk: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room.',
+        mcp: 'Delegate a slice of an active parent agreement to another agent. Name the parent, the worker, and the slice. The worker must approve — never impersonated. A chat is optional: omit it and the slice lands in the parent agreement\'s own room. Spawn tasks for the worker under the sub-agreement once it is active.',
+    },
+    annotation: 'write',
+    params: {
+        parentAgreementId: {
+            type: 'string',
+            required: true,
+            description: 'The active agreement you are delegating under',
+        },
+        executorId: {
+            type: 'string',
+            required: true,
+            description: 'Agent doing the delegated work',
+        },
+        description: {
+            type: 'string',
+            required: true,
+            description: 'What the sub-agreement covers',
+        },
+        chatId: {
+            type: 'string',
+            description: "Chat the subcontract is coordinated in. Omit it and the server uses the parent agreement's own chat — which is where a slice with no conversation of its own belongs.",
+        },
+        price: {
+            type: 'number',
+            description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Recording a price here does not itself move any.',
+        },
+        lifecycle: {
+            type: 'string',
+            enum: ['open', 'time-bound', 'count-bound'],
+            description: "Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing).",
+        },
+        expiresAt: { type: 'string' },
+        maxExecutions: { type: 'number' },
+        agreementDescription: { type: 'string' },
+        payerId: {
+            type: 'string',
+            description: 'Who pays for the subcontracted work. Defaults to the delegating side.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const chatId = args['chatId'];
+        const agreement = await delegateAgreement({
+            parentAgreementId: args['parentAgreementId'],
+            executorId: args['executorId'],
+            description: args['description'],
+            ...(typeof chatId === 'string' && chatId.trim()
+                ? { chatId: chatId.trim() }
+                : {}),
+            ...(args['price'] === undefined ? {} : { price: args['price'] }),
+            ...(args['lifecycle'] === undefined
+                ? {}
+                : { lifecycle: args['lifecycle'] }),
+            ...(args['expiresAt'] === undefined
+                ? {}
+                : { expiresAt: args['expiresAt'] }),
+            ...(args['maxExecutions'] === undefined
+                ? {}
+                : { maxExecutions: args['maxExecutions'] }),
+            ...(args['agreementDescription'] === undefined
+                ? {}
+                : { agreementDescription: args['agreementDescription'] }),
+            ...(args['payerId'] === undefined
+                ? {}
+                : { payerId: args['payerId'] }),
+        }, fullCreds(env));
+        return { agreement };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};

package/dist/capabilities/artifacts.js

@@ -18,7 +18,10 @@ function reportingHint(env, contentType, taskId) {
             ? `Recorded as a task-bound result artifact. Close the task by setting its terminal result with ${close}.`
             : `Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with ${close}.`;
     }
-    return `Reporting finished work? Record it with contentType=result bound to the task (taskId), then close the task with ${close} — chat messages are conversation only.`;
+    // The record and the delivery are different acts. A chat message
+    // is not where the next agent collects the work, and saying that as "chat is
+    // conversation only" read as a ban on telling the person who asked.
+    return `Reporting finished work? Record it with contentType=result bound to the task (taskId), then close the task with ${close} — that record is what the next agent reads. Telling the person who asked is a separate chat message, and still worth sending.`;
 }
 /** Inline body cap + escape hatch, shared by SDK/MCP descriptions. */
 const ARTIFACT_RECORD_INLINE_CAP = 'Inline text max 50000 characters. Over that: pass the body as a file ' +
@@ -269,8 +272,8 @@ export const listArtifactsCapability = {
     names: { sdk: 'artifact_list', mcp: 'ziggs_artifact_list' },
     title: 'List artifacts you wrote',
     descriptions: {
-        sdk: 'List artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Forward-delta with `after`.',
-        mcp: 'List artifacts YOU authored, across every scope and none. Use this to find something you ' +
+        sdk: 'List business artifacts you authored, in any scope or none — including free-standing ones no scope read can reach. Tool-operation and thought traces are excluded. Forward-delta with `after`.',
+        mcp: 'List business artifacts YOU authored, across every scope and none; tool-operation and thought traces are excluded. Use this to find something you ' +
             'recorded free-standing (no chat/agreement/task), which the scope reads cannot return. ' +
             'To read an artifact someone shared WITH you, use ziggs_context_read with via=artifact:<id>; ' +
             'to see what has been shared with you, use ziggs_grant_list with scopeKind=artifact.',
@@ -299,8 +302,27 @@ export const listArtifactsCapability = {
 };
 const UNSEARCHED_NOTE = 'These were NOT searched. You hold no grant on them, so only their label is ' +
     'visible here — no contents, no message counts, nothing that would leak what ' +
-    'is inside. Each row carries requestAccess: the grant that would open it, ' +
-    'which a human issues. Nothing is read until they do.';
+    'is inside. Each row carries requestAccess: an access explanation, not a ' +
+    'root grant. A human issues the grant; this never widens the scope to the ' +
+    'chat, agreement, or org around one artifact.';
+const OPEN_ID_FIELD = {
+    chat: 'chatId',
+    agreement: 'agreementId',
+    artifact: 'artifactId',
+    task: 'taskId',
+};
+function pendingAccessReceipt(result, extra) {
+    return {
+        ...extra,
+        ok: false,
+        outcome: 'pending',
+        status: 'pending_approval',
+        state: 'requested',
+        recoverable: true,
+        agreementId: result.agreementId,
+        ownerId: result.ownerId,
+    };
+}
 /**
  * The locked scopes near a search that found nothing.
  *
@@ -329,19 +351,18 @@ async function unsearchedContext(env) {
         };
     }
     return {
-        items: items.map((item) => ({
-            ...item,
-            requestAccess: nextCall(env, 'context_issue_grant', {
-                holderId: creds.agentId,
-                scopeKind: item.scopeRef.kind,
-                scopeId: item.scopeRef.id,
-            }, `open ${item.type} "${item.label}" so its contents become searchable`, 
-            // Not a call the agent runs. A root grant over a scope somebody else
-            // owns is human authority, and saying so here is the difference
-            // between a continuation and a dead end: the args are complete, the
-            // hold names who has to act.
-            { hold: 'human_approval' }),
-        })),
+        items: items.map((item) => {
+            const idField = OPEN_ID_FIELD[item.scopeRef.kind];
+            return {
+                ...item,
+                requestAccess: nextCall(env, 'access_explain', idField ? { [idField]: item.scopeRef.id } : undefined, idField
+                    ? `explain access to locked ${item.type} "${item.label}" — a human issues a root grant; this call does not request or widen`
+                    : `locked ${item.type} "${item.label}" cannot be requested from this surface — a human issues a root grant; this never widens the scope`, {
+                    hold: 'human_approval',
+                    ...(idField ? {} : { outcome: 'unavailable' }),
+                }),
+            };
+        }),
         count: items.length,
         note: UNSEARCHED_NOTE,
     };
@@ -366,10 +387,10 @@ export const findArtifactsCapability = {
     names: { sdk: 'artifact_find', mcp: 'ziggs_artifact_find' },
     title: 'Find artifacts you can read',
     descriptions: {
-        sdk: 'Search artifacts you can already reach — what you authored, what your readable chats/agreements/tasks hold, and what artifact grants you hold — by words in the name, filename or body. Bounded by your active lane and the rooms this wake is shared into, the same fences a point read obeys; there is no cross-customer arm and narrowing filters are refused, not ignored. Every answer carries coverage (fields searched, reach arms and their sizes, any that hit a cap), so an empty result means no match in what was searched, never that the thing does not exist. When nothing matched you also get notSearched: labels of context you hold no grant on, with the grant that would open each — metadata only, never contents.',
-        mcp: 'Search the artifacts YOU can read for words in their name, filename or body. Covers what you authored, what the chats/agreements/tasks you can read contain, and artifacts shared with you — bounded by your active lane and shared-room containment, exactly like a point read. Open a hit with ziggs_context_read (via=artifact:<id>). ' +
+        sdk: 'Search business artifacts you can already reach (excluding tool-operation and thought traces) — what you authored, what your readable chats/agreements/tasks hold, and what artifact grants you hold — by words in the name, filename or body. Bounded by your active lane and the rooms this wake is shared into, the same fences a point read obeys; there is no cross-customer arm and narrowing filters are refused, not ignored. Every answer carries coverage (fields searched, reach arms and their sizes, any that hit a cap), so an empty result means no match in what was searched, never that the thing does not exist. When nothing matched you also get notSearched: labels of context you hold no grant on, each with an access explanation — a human issues a root grant; this never widens. Metadata only, never contents.',
+        mcp: 'Search the business artifacts YOU can read for words in their name, filename or body; tool-operation and thought traces are excluded. Covers what you authored, what the chats/agreements/tasks you can read contain, and artifacts shared with you — bounded by your active lane and shared-room containment, exactly like a point read. Open a hit with ziggs_context_read (via=artifact:<id>). ' +
             'Read the coverage block before concluding anything: it names the fields searched, the arms that produced candidates and any that hit a cap. No match means no match in THOSE sources — it is never a statement that the artifact does not exist. ' +
-            'If nothing matched, notSearched lists context you cannot read yet (same rows as ziggs_context_discover_grantable): labels only, never contents, each with the grant a human would issue to open it. Do not report "not found" while notSearched is non-empty — say what you searched and what is still locked.',
+            'If nothing matched, notSearched lists context you cannot read yet (same rows as ziggs_context_discover_grantable): labels only, never contents, each with an access explanation. A human issues a root grant; do not treat that as a share or a wider container grant. Do not report "not found" while notSearched is non-empty — say what you searched and what is still locked.',
     },
     annotation: 'read-only',
     params: {
@@ -446,6 +467,10 @@ export const shareArtifactCapability = {
             type: 'string',
             description: 'Chat to surface the approval request in, when the receiver’s owner has to approve',
         },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Replay the same share. Same key and payload recover the original request; the same key with a different payload is a conflict, not a second share.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -460,14 +485,16 @@ export const shareArtifactCapability = {
             holderId,
             expiresAt: args['expiresAt'],
             chatId: args['chatId'],
+        }, {
+            idempotencyKey: typeof args['idempotencyKey'] === 'string'
+                ? args['idempotencyKey']
+                : undefined,
         });
         if (result.status === 'pending_approval') {
-            return {
-                ok: false,
-                outcome: 'pending',
+            return pendingAccessReceipt(result, {
                 ...result,
-                note: `Not shared yet — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}.`,
-            };
+                note: `Requested, not granted — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}. Recover that id; do not open a second card.`,
+            });
         }
         return {
             ok: true,

package/dist/capabilities/chat.d.ts

@@ -1,4 +1,34 @@
-import { type CapabilityDefinition } from './types.js';
+import { type SendChatMessageResult } from '../http/ChatClient.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+import { type WorkContext } from './nextCall.js';
+export interface SendPresentation {
+    ok: true;
+    chatId: string;
+    messageId: string;
+    /** What the server did with this send, stated so it cannot be over-read. */
+    delivered: string;
+    /** Who it was addressed to, exactly as the server resolved it. */
+    to?: {
+        id: string;
+        type: string;
+    };
+    workContext?: WorkContext;
+}
+/**
+ * Present a send as what it is: a message that now exists, addressed to
+ * somebody, which may or may not wake anyone.
+ *
+ * An agent that sent an answer and read `success: true` had every reason to
+ * report the answer delivered. Three different things hide behind that word.
+ * The message exists — that much is certain. Who it reached is the server's
+ * decision, not the caller's, because an omitted recipient may be inferred.
+ * Mailbox routing is a separate asynchronous decision, including coverage by
+ * an assistant when the addressee is a person.
+ *
+ * A server that does not report the destination gets one honest line about the
+ * message existing, and nothing invented about where it went.
+ */
+export declare function presentSendResult(result: SendChatMessageResult, env: CapabilityEnv): SendPresentation;
 /**
  * the decided chat surface for agents: chat_open only.
  * There is deliberately NO chat-listing tool on the SDK: taking part in a room

package/dist/capabilities/chat.js

@@ -1,5 +1,44 @@
 import { openConversation } from '../http/ChatClient.js';
 import { fullCreds } from './types.js';
+import { workContextFromEnv } from './nextCall.js';
+/**
+ * Present a send as what it is: a message that now exists, addressed to
+ * somebody, which may or may not wake anyone.
+ *
+ * An agent that sent an answer and read `success: true` had every reason to
+ * report the answer delivered. Three different things hide behind that word.
+ * The message exists — that much is certain. Who it reached is the server's
+ * decision, not the caller's, because an omitted recipient may be inferred.
+ * Mailbox routing is a separate asynchronous decision, including coverage by
+ * an assistant when the addressee is a person.
+ *
+ * A server that does not report the destination gets one honest line about the
+ * message existing, and nothing invented about where it went.
+ */
+export function presentSendResult(result, env) {
+    const workContext = workContextFromEnv(env);
+    const delivery = result.delivery;
+    const base = {
+        ok: true,
+        chatId: result.chatId,
+        messageId: result.messageId,
+        ...(workContext ? { workContext } : {}),
+    };
+    if (!delivery) {
+        return {
+            ...base,
+            delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}. Accepted is not read: nothing here says anyone has seen it.`,
+        };
+    }
+    const destination = delivery.broadcast
+        ? 'the humans in the room, not one addressee'
+        : `${delivery.to.id} (${delivery.to.type})`;
+    return {
+        ...base,
+        delivered: `Message ${result.messageId} was accepted into chat ${result.chatId}, addressed to ${destination}. Mailbox routing is unconfirmed; a person may be covered by an assistant. Accepted is not read and does not confirm a wake or reply.`,
+        to: delivery.to,
+    };
+}
 /**
  * the decided chat surface for agents: chat_open only.
  * There is deliberately NO chat-listing tool on the SDK: taking part in a room

package/dist/capabilities/context.d.ts

@@ -23,3 +23,4 @@ export declare const contextDelegateCapability: CapabilityDefinition;
 export declare const openCapability: CapabilityDefinition;
 export declare const accessExplainCapability: CapabilityDefinition;
 export declare const CONTEXT_CAPABILITIES: CapabilityDefinition[];
+export declare const contextRequestCapability: CapabilityDefinition;

package/dist/capabilities/context.js

@@ -195,6 +195,10 @@ export const contextDelegateCapability = {
             type: 'string',
             description: 'from-now watermark ISO-8601 (optional; server may default)',
         },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Replay the same delegate. Same key and payload recover the original request; the same key with a different payload is a conflict, not a second card.',
+        },
     },
     needsAgentId: true,
     handler: async (args, env) => {
@@ -222,12 +226,18 @@ export const contextDelegateCapability = {
             temporal: temporal,
             expiresAt: args['expiresAt'] ?? undefined,
             watermarkAt: args['watermarkAt'],
+        }, {
+            idempotencyKey: typeof args['idempotencyKey'] === 'string'
+                ? args['idempotencyKey']
+                : undefined,
         });
         if (result.status === 'pending_approval') {
             return {
                 status: 'pending_approval',
+                state: 'requested',
                 outcome: 'pending',
-                message: "This grant's original owner must approve sharing it. A request was opened for them — surface it to the human; nothing is granted yet.",
+                recoverable: true,
+                message: "Requested, not granted — this grant's original owner must approve. Recover agreementId; do not treat this as a share and do not widen the scope.",
                 parentGrantId: args['parentGrantId'],
                 agreementId: result.agreementId,
                 ownerId: result.ownerId,
@@ -329,3 +339,34 @@ export const CONTEXT_CAPABILITIES = [
     contextExpandReachCapability,
     contextDiscoverGrantableCapability,
 ];
+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.',
+        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.',
+    },
+    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' },
+        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: 'Waiting for the artifact owner. No access granted yet; open the original artifact only after approval.' };
+    },
+};

package/dist/capabilities/index.d.ts

@@ -1,17 +1,17 @@
 export { type CapabilitySurface, type CapabilityAnnotation, type CapabilityParam, type CapabilityEnv, type CapabilityDefinition, fullCreds, rethrowWithContext, } from './types.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, type NextCall, type NextCallOutcome, type NextCallEffects, type NextCallHold, type NextCallOptions, type WorkContext, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
 export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
-export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
+export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTaskOutcome, type TaskOutcomeEffects, type TaskOutcomePresentation, } from './tasks.js';
 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, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } 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';
-export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';
+export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, type SendPresentation, } from './chat.js';

package/dist/capabilities/index.js

@@ -1,17 +1,17 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
 export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
+export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, agreementSubcontractCapability, } from './agreementVerbs.js';
 export { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
 export { INTRODUCTION_CAPABILITIES, mintIntroductionCapability, redeemIntroductionCapability, listIntroductionsCapability, revokeIntroductionCapability, } from './introductions.js';
 export { AGREEMENT_CAPABILITIES, agreementClaimCapability, presentClaimResult, } from './agreements.js';
 export { LIST_FIELDS_PARAM, parseListFields, pickListedRow, pickListedRows, } from './listedFields.js';
-export { TASK_CAPABILITIES, listTasksCapability } from './tasks.js';
+export { TASK_CAPABILITIES, listTasksCapability, cancelTaskCapability, presentTaskOutcome, } from './tasks.js';
 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, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } from './context.js';
+export { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextRequestCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextBounds, resolveOrgScopeId, } 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';
-export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';
+export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';

package/dist/capabilities/marketplace.js

@@ -1,14 +1,16 @@
+import { marketplaceFormation } from '../engagementGuide.js';
 import { pullOffers, pullRequests } from '../http/MarketplaceClient.js';
 import { fullCreds } from './types.js';
 import { nextCall } from './nextCall.js';
 import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
 const VIEW_KINDS = ['all', 'requests', 'offers'];
 function publishHint(env) {
-    const propose = env.surface === 'mcp' ? 'ziggs_agreement_request' : 'agreement_request';
     const claim = env.surface === 'mcp' ? 'ziggs_agreement_claim' : 'agreement_claim';
-    return (`Claim any row with ${claim} (agreementId). Publish your own with ${propose}: ` +
-        `proposedTo "everyone" or "org" with no providerId broadcasts a request (claimer works, you pay); ` +
-        `the same with providerId = your own id publishes a standing offer (you work, claimer pays).`);
+    const publish = env.surface === 'mcp'
+        ? 'Publish a request with ziggs_agreement_request (claimer works, you pay) or a standing offer with ziggs_agreement_offer (you work, claimer pays).'
+        : 'Publish your own via agreement_propose with proposedTo "everyone"/"org" (providerId = your id for an offer, omitted for a request).';
+    return (`Reuse an active agreement that already covers the work. Otherwise claim any row with ${claim} ` +
+        `(agreementId) — listings are take-it-or-leave-it, never counter one. ${publish}`);
 }
 /** A broadcast sentinel in a party slot means "open", not a counterparty. */
 const BROADCASTS = new Set(['everyone', 'org']);
@@ -98,6 +100,10 @@ export const marketplaceViewCapability = {
         const fields = parseListFields(args['fields']);
         const requestRows = pickListedRows(requests.map((q) => toListingRow(q, 'request')), fields);
         const offerRows = pickListedRows(offers.map((o) => toListingRow(o, 'offer')), fields);
+        const listingAgreementIds = [...requests, ...offers]
+            .map((row) => row.agreementId)
+            .filter((id) => typeof id === 'string' && id.length > 0);
+        const engagement = marketplaceFormation(env, { listingAgreementIds });
         return {
             ...(kind !== 'offers'
                 ? { requests: requestRows, requestCount: requests.length }
@@ -105,13 +111,16 @@ export const marketplaceViewCapability = {
             ...(kind !== 'requests'
                 ? { offers: offerRows, offerCount: offers.length }
                 : {}),
+            engagement,
             // Claiming is the move after browsing, and the id is in the row the
             // caller just received. The prose hint stays for the publish side, which
             // is a choice rather than a call.
             readPlan: [
-                ...(requests.length || offers.length
+                ...(listingAgreementIds.length
                     ? [
-                        nextCall(env, 'agreement_claim', undefined, 'claim a listing from this view by passing its agreementId — listings are take-it-or-leave-it, never countered'),
+                        nextCall(env, 'agreement_claim', listingAgreementIds.length === 1
+                            ? { agreementId: listingAgreementIds[0] }
+                            : undefined, 'claim a listing from this view by passing its agreementId — listings are take-it-or-leave-it, never countered'),
                     ]
                     : []),
             ],

package/dist/capabilities/nextCall.js

@@ -3,7 +3,13 @@
  * and must never be offered here — chat_open / chat_send refuse it, and the
  * baseline's provider learned that only by being refused.
  */
-const ADDRESS_FIELDS = ['participantId', 'to', 'receiverId'];
+const ADDRESS_FIELDS = [
+    'participantId',
+    'to',
+    'receiverId',
+    'counterparty',
+    'executorId',
+];
 /**
  * Required arguments for the capability keys this helper is asked to emit.
  * Kept next to the HTTP bindings so a ready call cannot advertise a schema
@@ -15,9 +21,18 @@ const REQUIRED_ARGS = {
     chat_open: ['participantId'],
     chat_send: ['chatId'],
     agreement_claim: ['agreementId'],
+    agreement_get: ['agreementId'],
+    agreement_buy: ['counterparty', 'description'],
+    agreement_bid: ['counterparty', 'description'],
+    agreement_request: ['audience', 'description'],
+    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'],
+    task_cancel: ['taskId'],
 };
 /**
  * Published HTTP invocation per capability key. Paths match the api-client
@@ -31,17 +46,31 @@ const HTTP_BINDINGS = {
     introduction_mint: { method: 'POST', path: '/introductions' },
     introduction_redeem: { method: 'POST', path: '/introductions/:token/redeem' },
     agreement_claim: { method: 'POST', path: '/agreements/:agreementId/claim' },
+    agreement_get: { method: 'GET', path: '/agreements/:agreementId' },
+    agreement_buy: { method: 'POST', path: '/agreements/proposals' },
+    agreement_bid: { method: 'POST', path: '/agreements/proposals' },
+    agreement_request: { method: 'POST', path: '/agreements/proposals' },
+    agreement_subcontract: {
+        method: 'POST',
+        path: '/agreements/:parentAgreementId/delegations',
+    },
     agreement_respond: {
         method: 'PUT',
         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' },
     access_explain: { method: 'POST', path: '/context/access/explain' },
     inbox_peek: { method: 'GET', path: '/inbox/peek' },
+    task_get: { method: 'GET', path: '/tasks/:taskId' },
+    task_list: { method: 'GET', path: '/tasks' },
     link_list: { method: 'GET', path: '/agreements?engagementKind=link' },
     link_propose: { method: 'POST', path: '/agreements/links' },
+    task_create: { method: 'POST', path: '/tasks' },
+    task_cancel: { method: 'PATCH', path: '/tasks/:taskId/cancel' },
 };
 /**
  * Intentional surface exclusions. A ready next call has to exist as a tool
@@ -50,8 +79,15 @@ const HTTP_BINDINGS = {
  */
 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.
+    task_get: ['mcp'],
 };
 const MATERIAL_EFFECTS = {
+    task_get: {
+        disclosure: 'reads back what was recorded; it changes nothing',
+    },
     agreement_claim: {
         commitment: 'claiming makes you a party to the posted terms',
         relationship: 'you become the open party on that broadcast',
@@ -71,6 +107,26 @@ const MATERIAL_EFFECTS = {
     chat_open: {
         disclosure: 'opening a room issues the other side a grant on it',
     },
+    task_create: {
+        commitment: 'creates a task under the named agreement',
+    },
+    task_cancel: {
+        commitment: 'cancel ends this task; a held graph withdraws by cancelling the root',
+    },
+    agreement_buy: {
+        commitment: 'proposes that they work and your side pays',
+        relationship: 'a named counterparty — not a listing claim',
+    },
+    agreement_bid: {
+        commitment: 'proposes that you work and they pay',
+    },
+    agreement_request: {
+        commitment: 'posts work anyone may claim; you pay the claimer',
+    },
+    agreement_subcontract: {
+        commitment: 'opens a sub-agreement under the parent; the worker must approve — never impersonated',
+        relationship: 'the slice sits under the parent you already hold',
+    },
 };
 /** A persona face (`psn_…`) is display state, not a message address. */
 export function isPersonaFace(id) {
@@ -155,6 +211,7 @@ export function nextCall(env, capabilityKey, args, why, opts) {
         };
     }
     const missing = [];
+    const strippedFaces = [];
     const filled = {};
     for (const [key, value] of Object.entries(args ?? {})) {
         if (!isFilled(value))
@@ -162,6 +219,7 @@ export function nextCall(env, capabilityKey, args, why, opts) {
         if (ADDRESS_FIELDS.includes(key) &&
             isPersonaFace(value)) {
             missing.push(key);
+            strippedFaces.push(key);
             continue;
         }
         filled[key] = value;
@@ -183,11 +241,11 @@ export function nextCall(env, capabilityKey, args, why, opts) {
                     ? 'partial'
                     : 'unavailable');
     const http = HTTP_BINDINGS[capabilityKey];
-    const faceMissing = missing.some((name) => ADDRESS_FIELDS.includes(name));
+    const faceWasPassed = strippedFaces.length > 0;
     const reason = hold && missing.length === 0
         ? why
-        : !ready && faceMissing
-            ? `${why} — a next call for reaching a person names the user id or their agent, never a psn_ face`
+        : !ready && faceWasPassed
+            ? `${why} — missing ${missing.join(', ')}. a next call for reaching a person names the user id or their agent, never a psn_ face`
             : !ready
                 ? `${why} — missing ${missing.join(', ')}`
                 : why;