@ziggs-ai/api-client 0.20.0 → 0.21.0

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/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[];