@ziggs-ai/api-client 0.20.0 → 0.22.0

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;

package/dist/capabilities/tasks.d.ts

@@ -1,4 +1,6 @@
-import { type CapabilityDefinition } from './types.js';
+import { type TaskWriteConfirm } from '../http/TaskClient.js';
+import { type CapabilityDefinition, type CapabilityEnv } from './types.js';
+import { type NextCall, type NextCallOutcome, type WorkContext } from './nextCall.js';
 /**
  * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
  * same GET /tasks filters; assignedToMe vs assignedTo precedence then
@@ -6,4 +8,69 @@ import { type CapabilityDefinition } from './types.js';
  * those shorthands onto the HTTP query.
  */
 export declare const listTasksCapability: CapabilityDefinition;
+/**
+ * Withdraw a task — including a held graph, which is one cancel on the root.
+ * Catalog, not native: this is the pointer AX-07 names, not a new protocol verb.
+ */
+export declare const cancelTaskCapability: CapabilityDefinition;
+/**
+ * What a terminal transition actually did, as the server reported it.
+ *
+ * Mirrors the backend's `effects` block on the task write confirmation. Every
+ * field is optional because an older server does not send it, and a fact that
+ * did not arrive must not be narrated: silence beats a guess about money.
+ */
+export interface TaskOutcomeEffects {
+    resultRecorded?: boolean;
+    /** The transition was a de-duplicated replay; no effect ran a second time. */
+    replayed?: boolean;
+    /** Who a completion wake was QUEUED for — never who read it. */
+    notified?: string[];
+    settlement?: {
+        metered: boolean;
+        settled: boolean;
+        reason?: string;
+        amount?: number;
+        transactionId?: string;
+    };
+    agreement?: {
+        agreementId: string;
+        billing?: string | null;
+        status?: string | null;
+        fulfilledNow: boolean;
+    };
+}
+export interface TaskOutcomePresentation {
+    ok: true;
+    taskId: string;
+    state: string;
+    outcome: NextCallOutcome;
+    /** Where the outcome now lives, and who can read it. */
+    recorded: string;
+    /** What was queued for whom — stated as queued, never as received. */
+    handoff?: string;
+    /** Delivery to the person, which a task result is not. */
+    delivery?: string;
+    /** What metering did on this completion. Absent when the server said nothing. */
+    metering?: string;
+    /** What the agreement is now. Absent when the server said nothing. */
+    agreement?: string;
+    next: NextCall[];
+    workContext?: WorkContext;
+}
+/**
+ * Present a terminal transition as the four separate facts it produces.
+ *
+ * `{ ok: true, state: 'completed' }` was the whole answer, and four
+ * different claims were read out of it: the work is delivered, the next agent
+ * has it, the money moved, the engagement is done. Only the first is in the
+ * word. The rest are effects the server ran (or declined to run) beside it, and
+ * each one gets its own clause here — including the ones that say nothing
+ * happened, because "no settlement ran" is exactly the fact an agent otherwise
+ * fills in with an assumption.
+ *
+ * The lookup route is named rather than described: a completion whose response
+ * was lost is recovered by reading the task back, not by completing it twice.
+ */
+export declare function presentTaskOutcome(confirm: TaskWriteConfirm, env: CapabilityEnv): TaskOutcomePresentation;
 export declare const TASK_CAPABILITIES: CapabilityDefinition[];

package/dist/capabilities/tasks.js

@@ -1,6 +1,7 @@
-import { listTasks } from '../http/TaskClient.js';
-import { fullCreds } from './types.js';
+import { cancelTask, listTasks } from '../http/TaskClient.js';
+import { fullCreds, rethrowWithContext, } from './types.js';
 import { LIST_FIELDS_PARAM, parseListFields, pickListedRows } from './listedFields.js';
+import { nextCall, workContextFromEnv, } from './nextCall.js';
 /**
  * One list-tasks verb. MCP and the hosted SDK both used to re-declare the
  * same GET /tasks filters; assignedToMe vs assignedTo precedence then
@@ -63,4 +64,112 @@ export const listTasksCapability = {
             : listed;
     },
 };
-export const TASK_CAPABILITIES = [listTasksCapability];
+/**
+ * Withdraw a task — including a held graph, which is one cancel on the root.
+ * Catalog, not native: this is the pointer AX-07 names, not a new protocol verb.
+ */
+export const cancelTaskCapability = {
+    key: 'task_cancel',
+    names: { sdk: 'task_cancel', mcp: 'ziggs_task_cancel' },
+    title: 'Cancel a task',
+    descriptions: {
+        sdk: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
+        mcp: 'Cancel one task (PATCH /tasks/:id/cancel). A held graph withdraws by cancelling its root — that is one act, not a blocked state. Cancel ends this task; it does not amend a live hire.',
+    },
+    annotation: 'write',
+    params: {
+        taskId: {
+            type: 'string',
+            required: true,
+            description: 'The task to cancel. For a held graph, pass the root.',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        try {
+            return await cancelTask(args['taskId'], fullCreds(env));
+        }
+        catch (e) {
+            rethrowWithContext(e, 'task_cancel');
+        }
+    },
+};
+/** Why a metered settlement moved nothing, in words rather than a code. */
+const SETTLEMENT_REASONS = {
+    not_metered: 'this agreement does not bill per completed task',
+    unpriced: 'the agreement carries no price',
+    parties_unresolved: 'the paying or providing side is not a resolvable party',
+    self_hire: 'payer and provider are the same side — paying yourself is a no-op',
+    same_wallet: 'both sides resolve to one wallet',
+    wallet_missing: 'a wallet is missing',
+    transfer_failed: 'the transfer failed and is left for reconciliation',
+    agreement_missing: 'the agreement could not be read',
+};
+/**
+ * Present a terminal transition as the four separate facts it produces.
+ *
+ * `{ ok: true, state: 'completed' }` was the whole answer, and four
+ * different claims were read out of it: the work is delivered, the next agent
+ * has it, the money moved, the engagement is done. Only the first is in the
+ * word. The rest are effects the server ran (or declined to run) beside it, and
+ * each one gets its own clause here — including the ones that say nothing
+ * happened, because "no settlement ran" is exactly the fact an agent otherwise
+ * fills in with an assumption.
+ *
+ * The lookup route is named rather than described: a completion whose response
+ * was lost is recovered by reading the task back, not by completing it twice.
+ */
+export function presentTaskOutcome(confirm, env) {
+    const effects = confirm.effects;
+    const workContext = workContextFromEnv(env);
+    const taskId = confirm.taskId;
+    const state = String(confirm.state);
+    const completed = state === 'completed';
+    const stored = effects?.resultRecorded ?? confirm.resultRecorded ?? false;
+    // MCP delegates read one task by id; the hosted surface lists its own work.
+    const lookupKey = env.surface === 'mcp' ? 'task_get' : 'task_list';
+    const lookup = nextCall(env, lookupKey, lookupKey === 'task_get' ? { taskId } : { assignedToMe: true }, 'read the recorded outcome back — the route for a completion whose response you never saw, and the one that never completes the task twice');
+    const recorded = effects?.replayed
+        ? `Task ${taskId} was already ${state}: this call matched a transition already applied, so nothing was recorded, queued, metered or fulfilled a second time.`
+        : stored
+            ? `Task ${taskId} is ${state} and its result is stored on the task. That is where the next agent reads it — it stays readable whether or not any notification lands.`
+            : `Task ${taskId} is ${state} with no result payload stored. Nothing is waiting there for the next reader.`;
+    const notified = effects?.notified;
+    const handoff = notified === undefined
+        ? undefined
+        : notified.length > 0
+            ? `Completion queued for ${notified.join(', ')}. Queued is not read: the wake says it was sent, never that anyone has it.`
+            : 'No completion wake was queued — nobody on this agreement was addressable, so the result waits to be read rather than delivered.';
+    const delivery = completed
+        ? 'A task result is how the next AGENT collects the work. If a person set this goal, send it to them as well, in the conversation the work rides on — that delivery is a chat message, not a second record.'
+        : undefined;
+    const settlement = effects?.settlement;
+    const metering = !settlement
+        ? undefined
+        : settlement.settled
+            ? `Metered per completed task: this completion settled ${settlement.amount ?? 'the agreed rate'}${settlement.transactionId ? ` (tx ${settlement.transactionId})` : ''}. One execution, once — a retry of this same transition does not charge again.`
+            : `No payment moved on this completion — ${SETTLEMENT_REASONS[settlement.reason ?? ''] ?? settlement.reason ?? 'settlement did not run'}. Do not report this task as paid.`;
+    const agreementFacts = effects?.agreement;
+    const agreement = !agreementFacts
+        ? undefined
+        : agreementFacts.fulfilledNow
+            ? `Agreement ${agreementFacts.agreementId} reached its execution quota and is now fulfilled — the engagement is over, and its grants went with it.`
+            : `Agreement ${agreementFacts.agreementId} is still ${agreementFacts.status ?? 'in force'}${agreementFacts.billing === 'per_task' ? ', charging per completed task' : agreementFacts.billing === 'total' ? ', priced as one total for the engagement' : ''}. Finishing a task does not end a hire; ending one is its own deliberate call.`;
+    return {
+        ok: true,
+        taskId,
+        state,
+        outcome: 'ok',
+        recorded,
+        ...(handoff ? { handoff } : {}),
+        ...(delivery ? { delivery } : {}),
+        ...(metering ? { metering } : {}),
+        ...(agreement ? { agreement } : {}),
+        next: [lookup],
+        ...(workContext ? { workContext } : {}),
+    };
+}
+export const TASK_CAPABILITIES = [
+    listTasksCapability,
+    cancelTaskCapability,
+];

package/dist/decisionWords.d.ts

@@ -0,0 +1,51 @@
+/**
+ * One decision, one sentence, on every rail.
+ *
+ * When somebody answers a request an agent made (an access request on an
+ * artifact, a connection request, its own proposal), the agent hears about it
+ * as an agreement row whose `reason` names the decision. Rendered generically
+ * ("open the agreement <id>") that row says nothing about what was decided,
+ * and the agent learned it was approved or refused only if it happened to list
+ * its agreements. The hosted brain already had words for these reasons; the
+ * MCP rail did not. Both now call this function, so they say the same thing.
+ *
+ * The sentence is server state only. It never interpolates anything a
+ * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
+ * and an instant are all it carries.
+ */
+export type DecisionOutcome = 'approved' | 'rejected' | 'fulfilled' | 'held';
+export interface DecisionWordsInput {
+    /** The delivery row's `reason`. Anything that is not a decision maps to null. */
+    reason: string | null | undefined;
+    /** Who answered (the row's `actorId`). Absent on some emits. */
+    actorId?: string | null;
+    /** When it was answered (the row's `ts`), as an ISO instant. */
+    ts?: string | null;
+    /** The request agreement. */
+    agreementId?: string | null;
+    /**
+     * What the request was about, when the caller knows it. Named only when
+     * `kind` is `artifact`; today's delivery row does not carry it, so the
+     * sentence sends the reader to the agreement to find the artifact instead.
+     */
+    scope?: {
+        kind: string;
+        id: string;
+    } | null;
+    /**
+     * Which surface's tool names to use. MCP registers `ziggs_open` and
+     * `ziggs_context_read`; the hosted SDK registers `open` and `context_read`.
+     */
+    surface?: 'mcp' | 'sdk';
+}
+export interface DecisionWords {
+    outcome: DecisionOutcome;
+    /** Plain, model-facing, server state only. */
+    sentence: string;
+}
+/**
+ * Map a delivery row's decision reason to words. Returns null when the reason
+ * is not a decision (an ordinary doorbell, a store claim, a withheld contact),
+ * so a caller can use it as the test for "does this row need explaining".
+ */
+export declare function decisionWords(input: DecisionWordsInput): DecisionWords | null;

package/dist/decisionWords.js

@@ -0,0 +1,86 @@
+/**
+ * One decision, one sentence, on every rail.
+ *
+ * When somebody answers a request an agent made (an access request on an
+ * artifact, a connection request, its own proposal), the agent hears about it
+ * as an agreement row whose `reason` names the decision. Rendered generically
+ * ("open the agreement <id>") that row says nothing about what was decided,
+ * and the agent learned it was approved or refused only if it happened to list
+ * its agreements. The hosted brain already had words for these reasons; the
+ * MCP rail did not. Both now call this function, so they say the same thing.
+ *
+ * The sentence is server state only. It never interpolates anything a
+ * counterparty wrote: no titles, no messages, no descriptions. Ids, an actor id
+ * and an instant are all it carries.
+ */
+const REFUSED_REASONS = new Set([
+    'approval:rejected',
+    'context_request_rejected',
+    'connection_request_rejected',
+]);
+function requestNoun(reason) {
+    if (reason.startsWith('context_request_'))
+        return 'access request';
+    if (reason.startsWith('connection_request_'))
+        return 'connection request';
+    return 'request';
+}
+/**
+ * Map a delivery row's decision reason to words. Returns null when the reason
+ * is not a decision (an ordinary doorbell, a store claim, a withheld contact),
+ * so a caller can use it as the test for "does this row need explaining".
+ */
+export function decisionWords(input) {
+    const reason = typeof input.reason === 'string' ? input.reason : '';
+    if (!reason)
+        return null;
+    const tool = (key) => input.surface === 'sdk' ? key : `ziggs_${key}`;
+    const on = input.agreementId
+        ? `agreement ${input.agreementId}`
+        : 'this agreement';
+    const by = input.actorId ? ` by ${input.actorId}` : '';
+    const at = input.ts ? ` at ${input.ts}` : '';
+    const artifactId = input.scope?.kind === 'artifact' && input.scope.id ? input.scope.id : null;
+    if (REFUSED_REASONS.has(reason)) {
+        return {
+            outcome: 'rejected',
+            sentence: `Your ${requestNoun(reason)} on ${on} was refused${by}${at}. ` +
+                'Report the unresolved dependency where you asked, and ask what to change.',
+        };
+    }
+    if (reason === 'context_request_fulfilled') {
+        const open = artifactId
+            ? `Open the artifact ${artifactId} with ${tool('context_read')} or ${tool('open')}; `
+            : `Open the agreement with ${tool('open')} to find the artifact, then open the artifact with ${tool('context_read')} or ${tool('open')}; `;
+        return {
+            outcome: 'fulfilled',
+            sentence: `Your access request on ${on} was approved${by}${at}. ` +
+                open +
+                'the grant is bounded, check its expiry on the agreement.',
+        };
+    }
+    if (reason === 'connection_request_fulfilled') {
+        return {
+            outcome: 'fulfilled',
+            sentence: `Your connection request on ${on} was fulfilled${by}${at}. ` +
+                `The connection is ready to use; open the agreement with ${tool('open')} for its connection and grant ids and the bound on the grant.`,
+        };
+    }
+    if (reason === 'approval:approved') {
+        return {
+            outcome: 'approved',
+            sentence: `An approval on ${on} was given${by}${at}. ` +
+                'If it answers a request you made, carry out the next step you promised where you asked; ' +
+                `open the agreement with ${tool('open')} to see which slot was answered. ` +
+                'Approval of your own request is not a new hire and needs no introduction.',
+        };
+    }
+    if (reason === 'formation_held') {
+        return {
+            outcome: 'held',
+            sentence: `${on.charAt(0).toUpperCase()}${on.slice(1)} is held${at}: a consent it needs has not been given yet, so nothing is granted. ` +
+                `Open the agreement with ${tool('open')} to see whose decision it waits on.`,
+        };
+    }
+    return null;
+}

package/dist/engagementGuide.d.ts

@@ -0,0 +1,148 @@
+/**
+ * What to do with a piece of engagement, from records the caller already has.
+ *
+ * This is a receipt and a next-call pointer. It does not invent a worker
+ * protocol, a wake store, or a blocked task state. Waiting-on-person is a
+ * field on the receipt so a later human view can show waiting instead of
+ * active. A held graph is not work until deps release; failed or cancelled
+ * deps are not inputs. Withdraw is cancel on the root. A live hire does not
+ * take a second hire or an in-place amend.
+ */
+import type { InboxDeliveryRef, InboxEnvelope, InboxTaskRef, Task } from './types.js';
+import { type NextCall } from './capabilities/nextCall.js';
+import type { CapabilityEnv } from './capabilities/types.js';
+import type { SessionContinuation } from './sessionOrientation.js';
+export type EngagementGuideKind = 'work_order' | 'duplicate' | 'held' | 'waiting' | 'contact' | 'stranger_brief' | 'hire_terms' | 'reminder' | 'reuse' | 'claim' | 'request' | 'direct' | 'subcontract';
+export type EngagementOutcome = 'ok' | 'pending' | 'noop' | 'unavailable';
+export type WaitingOn = {
+    kind: 'user' | 'agent';
+    id: string;
+};
+export interface GraphHonesty {
+    ready: boolean;
+    heldByDeps: boolean;
+    failedDepsAreNotInputs: true;
+    failedDepCount: number;
+}
+export interface HireTermsHonesty {
+    secondHire: 'refused';
+    amendLive: 'unavailable';
+}
+export interface EngagementGuide {
+    kind: EngagementGuideKind;
+    outcome: EngagementOutcome;
+    summary: string;
+    /** Room the brief arrived in — never a substitute for agreementId. */
+    chatId?: string | null;
+    agreementId?: string | null;
+    taskId?: string | null;
+    waitingOn?: WaitingOn | null;
+    graph?: GraphHonesty;
+    hireTerms?: HireTermsHonesty;
+    next?: NextCall;
+}
+export interface EngagementTaskHint {
+    taskId: string;
+    agreementId?: string | null;
+    rootTaskId?: string | null;
+    heldByDeps?: boolean;
+    waitsOn?: string[];
+    /** Known terminal states for named deps, when the caller has them. */
+    depStates?: Record<string, string>;
+    dueAt?: string | null;
+    checkBack?: {
+        everyMinutes: number;
+        maxReminders: number;
+    } | null;
+    lastAct?: 'question';
+    waitingOn?: WaitingOn | null;
+}
+export interface ContactPathInput {
+    partyKind: 'person' | 'agent';
+    partyId: string;
+    /** Active Ziggs link (or same-org membership) to that person. */
+    linked: boolean;
+    /** The agent has a take-it-or-leave-it listing. */
+    listed?: boolean;
+    sameOrg?: boolean;
+}
+/**
+ * How to form (or refuse to form) an engagement from facts the caller
+ * already has. The ladder is reuse → claim → request → direct. A parent
+ * subcontract is its own rail. A listing is never countered.
+ */
+export interface FormationInput {
+    /** Active agreement that already covers this work on matching terms. */
+    matchingActive?: {
+        agreementId: string;
+    } | null;
+    /** Live hire with this counterparty, whether or not terms still match. */
+    liveHire?: {
+        agreementId: string;
+    } | null;
+    /** Caller wants different terms than the live hire. */
+    wantsChangedTerms?: boolean;
+    /**
+     * A posted listing to claim. `true` means listings exist and the caller
+     * still has to pick the id. An object with an id is that listing.
+     */
+    listing?: {
+        agreementId?: string;
+    } | true | null;
+    /** Active parent under which this slice would be a subcontract. */
+    parentAgreementId?: string | null;
+    /** Named counterparty for a direct proposal. */
+    counterparty?: string | null;
+    /** `doors.acceptsProposals` — most published agents are claim-only. */
+    acceptsProposals?: boolean;
+    /** They work (buy) vs you work (bid). */
+    direction?: 'buy' | 'bid';
+}
+export interface InboxEngagementInput {
+    env: CapabilityEnv;
+    agentId: string;
+    inbox: Pick<InboxEnvelope, 'deliveries' | 'tasksAwaitingMe'>;
+    tasks?: EngagementTaskHint[];
+    continuation?: Pick<SessionContinuation, 'canScheduleWake' | 'kind'>;
+}
+/** Same event twice, or a hire-room brief that already has an open task. */
+export declare function isEchoOrDuplicate(inbox: Pick<InboxEnvelope, 'deliveries' | 'tasksAwaitingMe'>, agentId: string): boolean;
+/**
+ * Assigned message under a live hire. Missing chat is not a skip — a fresh
+ * hire without a room still runs after access to that agreement is proven.
+ * An agrn- notification lane is not treated as a chat row.
+ */
+export declare function isHireWorkOrder(delivery: InboxDeliveryRef, agentId: string, tasksAwaitingMe?: readonly InboxTaskRef[]): boolean;
+export declare function waitingOnFromTask(task: EngagementTaskHint): WaitingOn | null;
+export declare function graphReleaseHonesty(task: EngagementTaskHint): GraphHonesty;
+export declare function liveHireChangedTerms(env: CapabilityEnv): EngagementGuide;
+/** Map a hire-formation 409 onto the refuse-second-hire receipt. */
+export declare function liveHireConflictFromStatus(env: CapabilityEnv, status: number): EngagementGuide | null;
+export declare function withdrawHeldGraph(env: CapabilityEnv, rootTaskId: string): EngagementGuide;
+export declare function reminderHonesty(task: EngagementTaskHint, continuation?: Pick<SessionContinuation, 'canScheduleWake' | 'kind'>): EngagementGuide;
+/**
+ * Formation receipt. Reuse a matching active agreement. Claim a listing
+ * and never counter it. Request when nothing listed fits. Direct only when
+ * they accept proposals. Subcontract under a parent you already hold.
+ * A second formation on a live hire is refused.
+ */
+export declare function formationGuide(env: CapabilityEnv, input: FormationInput): EngagementGuide;
+/** Browse result: claim when rows exist, request when the board is empty. */
+export declare function marketplaceFormation(env: CapabilityEnv, input: {
+    listingAgreementIds: readonly string[];
+}): EngagementGuide;
+/**
+ * Contact path. Same-org people are reachable under the scoped identity.
+ * An outside person needs an active link. A link is not a roster. An agent
+ * with a listing is claimed, not chatted into a hire.
+ */
+export declare function contactPath(env: CapabilityEnv, input: ContactPathInput): EngagementGuide;
+export declare function hireWorkOrderGuide(env: CapabilityEnv, delivery: InboxDeliveryRef): EngagementGuide;
+export declare function strangerBriefGuide(env: CapabilityEnv, chatId: string | null): EngagementGuide;
+export declare function duplicateGuide(): EngagementGuide;
+/**
+ * First engagement that matters on this envelope. Empty mail with no held
+ * tasks returns null so an empty inbox result stays a pass-through.
+ */
+export declare function inboxEngagement(input: InboxEngagementInput): EngagementGuide | null;
+export declare function hintsFromTasks(tasks: Task[] | undefined): EngagementTaskHint[];