@ziggs-ai/api-client 0.19.0 → 0.21.0

package/dist/capabilities/context.js

@@ -1,4 +1,5 @@
 import { ContextReadClient, CONTEXT_READ_TYPES, CONTEXT_READ_VIA, parseVia, viaHint, } from '../http/ContextReadClient.js';
+import { ContextOpenClient } from '../http/ContextOpenClient.js';
 import { ContextGrantsClient, } from '../http/ContextGrantsClient.js';
 import { ContextDiscoveryClient } from '../http/ContextDiscoveryClient.js';
 import { grantCaveat, CONTEXT_GRANT_SCOPE_KINDS, } from '../http/grants.js';
@@ -194,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) => {
@@ -221,11 +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',
-                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.",
+                state: 'requested',
+                outcome: 'pending',
+                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,
@@ -234,15 +246,127 @@ export const contextDelegateCapability = {
         const grant = result.grant;
         return {
             status: 'delegated',
+            outcome: 'ok',
             parentGrantId: args['parentGrantId'],
             grant,
             bounds: contextBounds(grant),
         };
     },
 };
+const OPEN_ID_PARAMS = {
+    artifactId: {
+        type: 'string',
+        description: 'Artifact id from a prior response. Pass exactly one id field.',
+    },
+    chatId: {
+        type: 'string',
+        description: 'Chat id from a prior response. Pass exactly one id field.',
+    },
+    taskId: {
+        type: 'string',
+        description: 'Task id from a prior response. Pass exactly one id field.',
+    },
+    agreementId: {
+        type: 'string',
+        description: 'Agreement id from a prior response. Pass exactly one id field.',
+    },
+};
+function openBodyFromArgs(args) {
+    const body = {};
+    for (const key of ['artifactId', 'chatId', 'taskId', 'agreementId']) {
+        const value = args[key];
+        if (typeof value === 'string' && value.trim())
+            body[key] = value.trim();
+    }
+    if (typeof args['cursor'] === 'string')
+        body.cursor = args['cursor'];
+    if (typeof args['after'] === 'string')
+        body.after = args['after'];
+    if (typeof args['limit'] === 'number')
+        body.limit = args['limit'];
+    return body;
+}
+function presentOpenResult(result) {
+    // Never attach a ready write. An unreadable row already carries
+    // access.continuation (owner-decision); this call must not execute it.
+    return { ...result, actions: [] };
+}
+export const openCapability = {
+    key: 'open',
+    names: { sdk: 'open', mcp: 'ziggs_open' },
+    title: 'Open a returned resource',
+    descriptions: {
+        sdk: 'Open an artifact, chat, task, or agreement you were given an id for. Pass exactly one of artifactId, chatId, taskId, agreementId. Do not pick a grant id or reconstruct type/via — the server resolves the read path and rechecks authorization every time. Read-only: this never requests access or records an approval. Reading is not reply, share, delegate, approve, or original-file download. Extraction pending/failed is not an empty document.',
+        mcp: 'Open an artifact, chat, task, or agreement from an ordinary returned id (inbox, find, task result). Pass exactly one of artifactId, chatId, taskId, agreementId. Do not call ziggs_grant_list first, do not pick a grant id, and do not reconstruct type/via — the server resolves the path and rechecks every call. A saved id is not authority. Read-only: never requests access or approves. Hidden and unknown look the same; a discoverable-but-unreadable row names an owner-decision, which this call does not execute. Text access is not a file download. Extraction pending/failed is not an empty document.',
+    },
+    annotation: 'read-only',
+    params: {
+        ...OPEN_ID_PARAMS,
+        cursor: { type: 'string', description: 'Opaque cursor from a prior open page' },
+        after: { type: 'string', description: 'ISO timestamp for a forward-delta' },
+        limit: { type: 'number', description: 'Page size' },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
+        return presentOpenResult(await client.open(openBodyFromArgs(args)));
+    },
+};
+export const accessExplainCapability = {
+    key: 'access_explain',
+    names: { sdk: 'access_explain', mcp: 'ziggs_access_explain' },
+    title: 'Explain access to a resource',
+    descriptions: {
+        sdk: 'Read-only access explanation for an ordinary returned id. Same one-of artifactId/chatId/taskId/agreementId as open. Says whether you can read, and that reading does not imply reply, share, delegate, approve, or download. Does not return content and does not request or approve anything.',
+        mcp: 'Read-only access explanation for an ordinary returned id (exactly one of artifactId, chatId, taskId, agreementId). No grant id. Rechecks authorization. Names the owner-decision route when you cannot read a discoverable resource; this call never executes that request. Hidden and unknown reveal no labels, owners, excerpts, or counts.',
+    },
+    annotation: 'read-only',
+    params: OPEN_ID_PARAMS,
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const client = new ContextOpenClient(creds.operatorKey, creds.agentId, env.baseUrl, creds.laneId);
+        const result = await client.explain(openBodyFromArgs(args));
+        return presentOpenResult(result);
+    },
+};
 export const CONTEXT_CAPABILITIES = [
     contextReadCapability,
+    openCapability,
+    accessExplainCapability,
     contextDelegateCapability,
     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, peerPrincipalId, type NextCall, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.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, 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, 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, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
-export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.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, peerPrincipalId, } from './nextCall.js';
-export { AGREEMENT_VERB_CAPABILITIES, agreementBuyCapability, agreementBidCapability, agreementBrokerCapability, agreementRequestCapability, agreementOfferCapability, agreementHandoffCapability, } from './agreementVerbs.js';
+export { nextCall, nextCallsFromUntrustedContent, isStaleAdvertisedAction, peerPrincipalId, isPersonaFace, workContextFromEnv, } from './nextCall.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, 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, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
-export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';
+export { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
+export { CHAT_CAPABILITIES, openConversationCapability, presentSendResult, } from './chat.js';

package/dist/capabilities/introductions.js

@@ -79,6 +79,7 @@ export const redeemIntroductionCapability = {
         const staged = intro.outcome === 'link_pending';
         return {
             introduction: intro,
+            outcome: staged ? 'pending' : 'ok',
             message: staged
                 ? `Redeemed. A pending link with org ${intro.from.orgId} (${intro.from.agentId ?? 'no agent id'}) is staged (${intro.agreementId}). The display name they claimed is self-chosen and unverified. The link becomes real when both people approve it — a link is reach only, and shares no context by itself.`
                 : intro.outcome === 'already_teammates'
@@ -88,6 +89,9 @@ export const redeemIntroductionCapability = {
             // relationship exists, so the next move is simply to talk. Leaving the
             // plan empty there read as "nothing to do" on the branch a returning
             // counterparty is most likely to land on.
+            //
+            // A staged redeem is not a live hire: do not advertise a ready chat_open
+            // or a ready agreement_respond the agent can run. The human signs.
             readPlan: !staged
                 ? intro.counterparty?.agentId
                     ? [
@@ -95,16 +99,7 @@ export const redeemIntroductionCapability = {
                     ]
                     : []
                 : [
-                    nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your human must approve it; do not sign on their behalf'),
-                    // The minter's AGENT, not their principal. A link's party principal
-                    // can be a persona face, which the chat rail refuses as an address
-                    // ("a face is display state and names no single party") — so the
-                    // door to that person is the agent that carried the introduction.
-                    ...(intro.from.agentId
-                        ? [
-                            nextCall(env, 'chat_open', { participantId: intro.from.agentId }, 'once the link is live, this is the door to the agent that introduced itself'),
-                        ]
-                        : []),
+                    nextCall(env, 'agreement_respond', intro.agreementId ? { agreementId: intro.agreementId } : undefined, 'the link is pending — your human must approve it; do not sign on their behalf', { hold: 'human_approval' }),
                 ],
         };
     },

package/dist/capabilities/links.js

@@ -177,6 +177,7 @@ export const proposeLinkCapability = {
         // in both directions, because none of them could ask.
         return {
             status: 'sent',
+            outcome: 'pending',
             shareUrl,
             agreementId,
             message: to

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.d.ts

@@ -1,28 +1,72 @@
 import type { AgreementParties } from '../types.js';
-import type { CapabilityEnv } from './types.js';
+import type { CapabilityDefinition, CapabilityEnv } from './types.js';
 /**
- * One runnable next step: a tool name, pre-filled arguments, and why.
+ * One next step: the tool the calling surface registers, any args already
+ * known, and why.
  *
- * The inbox and the context read already answer this way, and it is the part of
- * those tools that works best: a caller runs the entries verbatim instead of
- * parsing a paragraph for a tool name and then digging the ids out of the
- * response body it just received.
+ * Ready means a caller can run it verbatim. Incomplete means a required
+ * argument is missing or an address field is not an address — the suggestion
+ * still names the tool, and `missing` says what has to be filled first.
  *
- * Everywhere else said the same thing in prose, under two other field names, so
- * an agent had to read English to find out that "open a chat with the peer"
- * meant `chat_open` with a `participantId` it had to locate itself. Prose is
- * still right when the next move is not a call at all (a human has to decide
- * something); it is wrong when the call and its arguments are both already
- * known here.
+ * `http` is the same invocation on the published HTTP surface, bound from the
+ * capability key rather than a second implementation. Profile is not a field
+ * here: assistant vs worker is not a transport.
  */
 export interface NextCall {
     /** Registered tool name on the calling surface. */
     tool: string;
     /** Arguments, filled in from what the response already carries. */
     args?: Record<string, unknown>;
-    /** One clause: what running this achieves. */
+    /** One clause: what running this achieves, or what is still missing. */
     why: string;
+    /** True only when every required argument is present and addressable. */
+    ready: boolean;
+    /** Required argument names that are absent or not an address. */
+    missing?: readonly string[];
+    /** Published HTTP method/path for the same capability, when we have one. */
+    http?: {
+        method: string;
+        path: string;
+    };
+    /**
+     * Whether this step is a finished action, a parked human decision, a
+     * half-filled suggestion, or something this surface cannot run.
+     */
+    outcome: NextCallOutcome;
+    /** Material effects of running this, when the verb has any. */
+    effects?: NextCallEffects;
+    /** Who would run it, from the env — never a caller-chosen principal. */
+    workContext?: WorkContext;
+    /** Why a complete-looking call is still not runnable. */
+    hold?: NextCallHold;
 }
+export type NextCallOutcome = 'ok' | 'pending' | 'partial' | 'unavailable';
+export type NextCallHold = 'human_approval' | 'relationship';
+export interface NextCallEffects {
+    disclosure?: string;
+    commitment?: string;
+    metering?: string;
+    relationship?: string;
+}
+export interface WorkContext {
+    actingAgentId?: string;
+    laneId?: string;
+}
+export interface NextCallOptions {
+    /** Live capability schema — required args come from here when present. */
+    definition?: Pick<CapabilityDefinition, 'params'>;
+    outcome?: NextCallOutcome;
+    effects?: NextCallEffects;
+    /**
+     * Args may be complete but the caller must not run it: a human signs, or
+     * a relationship is not live yet.
+     */
+    hold?: NextCallHold;
+}
+/** A persona face (`psn_…`) is display state, not a message address. */
+export declare function isPersonaFace(id: unknown): boolean;
+/** Acting agent and lane from the env. Never a caller-chosen principal. */
+export declare function workContextFromEnv(env: CapabilityEnv): WorkContext | undefined;
 /**
  * Build a next step naming the tool as the calling surface registers it.
  *
@@ -31,7 +75,21 @@ export interface NextCall {
  * the 31 capability definitions follows that one rule, so the key is enough and
  * a caller cannot accidentally emit a name the surface does not have.
  */
-export declare function nextCall(env: CapabilityEnv, capabilityKey: string, args: Record<string, unknown> | undefined, why: string): NextCall;
+export declare function nextCall(env: CapabilityEnv, capabilityKey: string, args: Record<string, unknown> | undefined, why: string, opts?: NextCallOptions): NextCall;
+/**
+ * E23: messages, artifacts, and agreement prose are data. They cannot mint
+ * a server action. The only legal parse is "none".
+ */
+export declare function nextCallsFromUntrustedContent(_content: unknown): NextCall[];
+/**
+ * E22: a next call advertised against an earlier snapshot is stale when the
+ * row is no longer in the state that action assumed. Execution still has to
+ * hit the existing precondition (claim 400, respond refuse) — this is the
+ * client-side invalidation so a caller does not treat the suggestion as live.
+ */
+export declare function isStaleAdvertisedAction(advertised: Pick<NextCall, 'tool' | 'args'>, current: {
+    status?: string | null;
+}): boolean;
 /**
  * The other PRINCIPAL in a two-party agreement, from the perspective of
  * `selfId`.