@ziggs-ai/api-client 0.19.0 → 0.20.0

package/dist/capabilities/agreements.d.ts

@@ -1,5 +1,6 @@
 import type { ClaimedKind } from '../http/AgreementClient.js';
 import type { Agreement } from '../types.js';
+import { type NextCallOutcome, type WorkContext } from './nextCall.js';
 import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
 /**
  * One claim result shape for both surfaces. The SDK protocol runner used to
@@ -8,9 +9,11 @@ import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
  */
 export declare function presentClaimResult(agreement: Agreement, kind: ClaimedKind, env: CapabilityEnv): {
     status: string;
+    outcome: NextCallOutcome;
     kind: ClaimedKind;
     message: string;
     agreement: Agreement;
+    workContext?: WorkContext;
 };
 /**
  * the one claim verb. Requests, standing offers, and link invites

package/dist/capabilities/agreements.js

@@ -1,6 +1,7 @@
 import { agreementAppUrl } from '../utils/appUrls.js';
 import { claimOpenAgreement } from '../http/agreementFlows.js';
 import { linkIsReachOnly, webAppOrigin } from './links.js';
+import { workContextFromEnv } from './nextCall.js';
 import { fullCreds } from './types.js';
 /** Which side the claimer just took, for a claim that has not activated yet. */
 function claimedWhat(kind) {
@@ -16,12 +17,15 @@ function claimedWhat(kind) {
  * agreement}` — same HTTP call, two answers.
  */
 export function presentClaimResult(agreement, kind, env) {
+    const workContext = workContextFromEnv(env);
     if (kind === 'link') {
         return {
             status: 'linked',
+            outcome: 'ok',
             kind,
             message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
             agreement,
+            ...(workContext ? { workContext } : {}),
         };
     }
     if (agreement?.status !== 'active') {
@@ -31,16 +35,19 @@ export function presentClaimResult(agreement, kind, env) {
             ? 'This is a first engagement with that counterparty — your human approves once; a standing link covers it after that.'
             : 'Claiming for a job your human already approved activates at once — name the job with mandateAgreementId.';
         return {
-            status: 'claimed',
+            status: 'pending_approval',
+            outcome: 'pending',
             kind,
             message: `${claimedWhat(kind)} It is not active yet: the formation is waiting on ` +
                 'human approval, so nothing can be created under it until that lands. ' +
                 `Your human can approve it here: ${approveUrl} — ${remedy}`,
             agreement,
+            ...(workContext ? { workContext } : {}),
         };
     }
     return {
         status: 'claimed',
+        outcome: 'ok',
         kind,
         message: kind === 'offer'
             ? 'Standing offer claimed — the publisher provides, your side pays. Spawn work under it with the task-create tool.'
@@ -48,6 +55,7 @@ export function presentClaimResult(agreement, kind, env) {
                 ? 'Hand-off claimed — the pinned agent works FOR you: you are the customer (and the payer when priced), never the worker. Spawn work under it with the task-create tool.'
                 : 'Request claimed — you provide the work. Read the terms, then post progress and set the task result under this agreement.',
         agreement,
+        ...(workContext ? { workContext } : {}),
     };
 }
 /**

package/dist/capabilities/artifacts.d.ts

@@ -1,4 +1,6 @@
+import { type DiscoverableItem } from '../http/ContextDiscoveryClient.js';
 import { type CapabilityDefinition } from './types.js';
+import { type NextCall } from './nextCall.js';
 export declare const recordArtifactCapability: CapabilityDefinition;
 /**
  * the artifacts you wrote, across every scope and none.
@@ -8,6 +10,42 @@ export declare const recordArtifactCapability: CapabilityDefinition;
  * agent finds what it recorded without naming a container.
  */
 export declare const listArtifactsCapability: CapabilityDefinition;
+/**
+ * What the agent could not read, said as metadata and nothing else.
+ *
+ * The one thing this block must never become is a second results list. A row
+ * here is a LABEL — `context_discover_grantable` re-shapes every row to
+ * type/label/scopeRef/orgId on the way through, so no message, no member name
+ * and no artifact body can travel in it, and none of these scopes were searched
+ * at all. Keeping them in a separate field with its own wording is the whole
+ * point: an agent that cannot tell "no match in what I can read" from "there is
+ * a locked room over there" will confidently report the first while the answer
+ * sits in the second.
+ */
+export interface UnsearchedContext {
+    /** Locked scopes, labels only — never content, never counts of content. */
+    items: (DiscoverableItem & {
+        requestAccess: NextCall;
+    })[];
+    count: number;
+    note: string;
+}
+/**
+ * search the work you hold, and say what you searched.
+ *
+ * `artifact_list` answers "what did I write" and the scope reads answer "what
+ * is in this container". Neither answers "where is the thing about X", which is
+ * the question an agent actually has when it has been handed work that refers
+ * to something it did not produce. The server bounds this by the agent's own
+ * reach — authorship, readable containers, artifact grants it holds — under the
+ * active lane and shared-room containment, so there is no `reach` arm to ask
+ * for and the narrowing filters are refused rather than ignored.
+ *
+ * The response is deliberately two things that never merge: `artifacts`, which
+ * is readable content that matched, and `notSearched`, which is labels of
+ * scopes that were never opened. `coverage` sits between them naming what ran.
+ */
+export declare const findArtifactsCapability: CapabilityDefinition;
 /**
  * hand one artifact you authored to one other agent.
  *

package/dist/capabilities/artifacts.js

@@ -1,7 +1,9 @@
 import { ArtifactsClient } from '../http/ArtifactsClient.js';
 import { ContextGrantsClient } from '../http/ContextGrantsClient.js';
+import { ContextDiscoveryClient, } from '../http/ContextDiscoveryClient.js';
 import { fullCreds } from './types.js';
 import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { nextCall } from './nextCall.js';
 /**
  * teaching: name the result slot on the success path so an agent finds
  * the right move unaided — worded in each surface's task grammar (SDK
@@ -295,6 +297,115 @@ export const listArtifactsCapability = {
             : listed;
     },
 };
+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.';
+/**
+ * The locked scopes near a search that found nothing.
+ *
+ * Fetched only when it changes what a caller should conclude, which is why it
+ * is not on every response: an agent holding a page of matches does not need
+ * the list of doors it has not opened, and an extra round trip on every find
+ * would buy nothing. A search that came back empty is exactly where the wrong
+ * conclusion gets drawn, so that is where this arrives unasked.
+ *
+ * Discovery failing is not find failing. It is bounded to orgs the agent holds
+ * an active work agreement in and can legitimately return nothing, or refuse;
+ * either way the matches already computed are the answer, and the miss is
+ * reported as a limitation rather than thrown over the top of them.
+ */
+async function unsearchedContext(env) {
+    const creds = fullCreds(env);
+    let items;
+    try {
+        items = await new ContextDiscoveryClient(creds.operatorKey, creds.agentId).discoverGrantable();
+    }
+    catch (err) {
+        return {
+            note: 'Could not check for context you cannot read yet: ' +
+                `${err instanceof Error ? err.message : String(err)}. ` +
+                'Treat this answer as covering only what was searched.',
+        };
+    }
+    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' }),
+        })),
+        count: items.length,
+        note: UNSEARCHED_NOTE,
+    };
+}
+/**
+ * search the work you hold, and say what you searched.
+ *
+ * `artifact_list` answers "what did I write" and the scope reads answer "what
+ * is in this container". Neither answers "where is the thing about X", which is
+ * the question an agent actually has when it has been handed work that refers
+ * to something it did not produce. The server bounds this by the agent's own
+ * reach — authorship, readable containers, artifact grants it holds — under the
+ * active lane and shared-room containment, so there is no `reach` arm to ask
+ * for and the narrowing filters are refused rather than ignored.
+ *
+ * The response is deliberately two things that never merge: `artifacts`, which
+ * is readable content that matched, and `notSearched`, which is labels of
+ * scopes that were never opened. `coverage` sits between them naming what ran.
+ */
+export const findArtifactsCapability = {
+    key: 'artifact_find',
+    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>). ' +
+            '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.',
+    },
+    annotation: 'read-only',
+    params: {
+        q: {
+            type: 'string',
+            required: true,
+            description: 'Words to match; every term must appear. This is a lexical match on name, filename and extracted text — not a semantic search.',
+        },
+        limit: { type: 'number', description: 'Page size (server default when omitted)' },
+        before: {
+            type: 'string',
+            description: 'Older-rows cursor: pass the previous page’s coverage.nextCursor back verbatim (opaque).',
+        },
+        includeUnreadable: {
+            type: 'boolean',
+            description: 'Also list context you hold no grant on (labels only, never contents). Defaults on when nothing matched, since that is when an empty answer is most likely to be misread; pass true to ask for it alongside matches.',
+        },
+        fields: LIST_FIELDS_PARAM,
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const creds = fullCreds(env);
+        const found = await new ArtifactsClient(creds.operatorKey, creds.agentId, creds.laneId).find(args['q'], {
+            limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
+            before: args['before'],
+        });
+        const fields = parseListFields(args['fields']);
+        const shaped = fields
+            ? { ...found, artifacts: pickListedRows(found.artifacts, fields) }
+            : found;
+        const asked = args['includeUnreadable'] === true;
+        if (!asked && found.artifacts.length > 0)
+            return shaped;
+        return { ...shaped, notSearched: await unsearchedContext(env) };
+    },
+};
 /**
  * hand one artifact you authored to one other agent.
  *
@@ -352,13 +463,15 @@ export const shareArtifactCapability = {
         });
         if (result.status === 'pending_approval') {
             return {
-                ok: true,
+                ok: false,
+                outcome: 'pending',
                 ...result,
                 note: `Not shared yet — ${result.ownerId ?? 'the owner'} must approve agreement ${result.agreementId}.`,
             };
         }
         return {
             ok: true,
+            outcome: 'ok',
             ...result,
             note: `${holderId} can now read artifact ${artifactId} with via=artifact:${artifactId}.`,
         };
@@ -644,6 +757,7 @@ export const reextractArtifactCapability = {
 export const ARTIFACT_CAPABILITIES = [
     recordArtifactCapability,
     listArtifactsCapability,
+    findArtifactsCapability,
     shareArtifactCapability,
     attachArtifactCapability,
     uploadArtifactUrlCapability,

package/dist/capabilities/context.d.ts

@@ -20,4 +20,6 @@ export declare const contextReadCapability: CapabilityDefinition;
 export declare const contextExpandReachCapability: CapabilityDefinition;
 export declare const contextDiscoverGrantableCapability: CapabilityDefinition;
 export declare const contextDelegateCapability: CapabilityDefinition;
+export declare const openCapability: CapabilityDefinition;
+export declare const accessExplainCapability: CapabilityDefinition;
 export declare const CONTEXT_CAPABILITIES: CapabilityDefinition[];

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';
@@ -225,6 +226,7 @@ export const contextDelegateCapability = {
         if (result.status === 'pending_approval') {
             return {
                 status: 'pending_approval',
+                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.",
                 parentGrantId: args['parentGrantId'],
                 agreementId: result.agreementId,
@@ -234,14 +236,95 @@ 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,

package/dist/capabilities/index.d.ts

@@ -1,5 +1,5 @@
 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 { 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 { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
@@ -10,8 +10,8 @@ export { TASK_CAPABILITIES, listTasksCapability } 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, 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 { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, type UnsearchedContext, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } from './chat.js';

package/dist/capabilities/index.js

@@ -1,5 +1,5 @@
 export { fullCreds, rethrowWithContext, } from './types.js';
-export { nextCall, peerPrincipalId, } from './nextCall.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 { PAYMENT_CAPABILITIES, paymentBalanceCapability } from './payments.js';
 export { LINK_CAPABILITIES, listLinksCapability, proposeLinkCapability, linkIsReachOnly, } from './links.js';
@@ -10,8 +10,8 @@ export { TASK_CAPABILITIES, listTasksCapability } 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, 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 { ARTIFACT_CAPABILITIES, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, } from './artifacts.js';
 export { CHAT_CAPABILITIES, openConversationCapability } 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/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`.