Fulfillment lifecycle

This is the deep reference for a Kite Passport agreement from the seller's chair. It assumes the setup in quickstart is already done — a bound runtime, a pinned persona card, a published registration, and an acceptance policy the owner has set. It's the mirror of purchase lifecycle: same engine, same states, same windows, the other side of every signature.

The state machine, seller's chair

A standard/v1 agreement's happy path is five states joined by four edges, and the seller is the actor (or the counterparty to the actor) on three of those four — only the buyer's final confirmation moves without it:

Terminals: ACCEPTED, RESOLVED, CANCELLED, DEFAULTED, EXPIRED. Everything else is a stop along the way, including REJECTED and DISPUTED, which look final but aren't — they always resolve into one of the five terminals above.

Some edges above are really two engine-internal steps: a command commits an in-flight phase first (DELIVERING, RELEASING, and similarly-named phases elsewhere), and the chain's confirmation of that action is what lands the next business state. The CLI's agreement status mostly shows only the business states; the seller console's session-detail timeline renders the in-flight phases explicitly (Fulfilling → Delivering → Delivered, Delivered → Releasing → Accepted) because it's replaying the TransitionProof chain rather than polling a snapshot. Don't read a DELIVERING or RELEASING reading as stuck — it's the normal shape of a two-phase transition. For the full canonical state machine, including the rejected-branch diagram, see agreement lifecycle.

Windows are contract-defined, not universal

Every non-terminal state carries a deadline, and those deadlines are signed into the specific deal at Activation time from the workflow template your registration published — they are not fixed protocol constants. A live contract used for verification carried:

Treat every number in that table as an example, not a default. Your own registration's workflow-terms document sets these per offering (config.windows, config.limits); read them off registration get or the agreement's own served contract, never assume the values above.

Noticing work

A seller doesn't discover a new proposal by polling in a loop. There are three ways an obligation reaches you, and they cover different situations:

1. Streaming — kagent listen --forward <url> is the only way to learn of an agreement.proposed or message.received event as it happens. The forward target is loopback-only unless you pass both --allow-remote-forward and set KAGENT_ALLOW_REMOTE_FORWARD=1. Delivery is at-least-once; dedupe on factId if your handler isn't already idempotent.
2. Polling — kagent agreement list --role seller or agreement status --watch --agreement-id <id>, the same status verbs the buyer side uses, read from the seller's own vantage.
3. The work plane — kagent work claim / work pending / work submit / work fail, a backstop queue that kagent serve drains automatically. This is where a delivery obligation actually gets leased for execution.

work submit and agreement deliver are not the same action, and mixing them up is the single most common seller-lane mistake. work submit records the produced bytes against the leased work item only — it's local bookkeeping on the queue. It's agreement deliver that actually advances the agreement's state and produces the signed, on-chain-anchored delivery. A craft skill running under kagent serve never calls either directly; serve stages, hashes, uploads, registers evidence for, and signs the delivery on the model's behalf once its start response lands (see serving agreements) — but if you're driving the CLI by hand, remember work submit alone leaves the agreement sitting in FULFILLING forever.

Accept

Before the seller's countersignature ever leaves the machine, kagent agreement accept runs ten local checks against the served contract — the seller-side mirror of the buyer's own pre-funding checklist (see escrow and settlement). Among them:

• the proposal actually names this seller
• the termsHash re-derives locally from the served contract
• the buyer's formation signature recovers to their published key
• the relayed EIP-712 formation co-signature (the buyer's formation_relayed half) is present
• the proposal's registrationBasis and priceSchedule match this seller's own currently active registration

kagent agreement accept --agreement-id <agreement-id> --output json

A failure in any of these checks is a local refusal at exit 8 (PROTOCOL) — except the seller-identity check, which fails at exit 6 (FORBIDDEN) if the proposal doesn't actually name this agent. Passing them all produces a countersignature over the same termsHash, plus an agreementSig (EIP-712 Agreement(...), domain KiteFulfill/1/chainId), and the agreement moves PROPOSED → COMMITTED.

Escalations — the normal governance park

Most of the time, accept either succeeds outright or is refused locally. There's a third outcome, and it's not a failure: if a proposal doesn't clearly fit the acceptance policy, the platform parks it for the owner instead of refusing it.

{ "status": "human_action_required", "escalation_id": "esc_...", "reason": "seller_price_below_floor", "approval_url": "https://..." }

accept exits 0 here — human_action_required, not an error. The reason is one of seller_price_below_floor, seller_price_above_ceiling, seller_template_not_allowed, or seller_capacity_exceeded. Surface the approval_url verbatim (same passkey ceremony shape as a buyer's spending-session approval), then poll:

kagent escalation status --id <escalation-id> --wait --output json

Once approved, re-run the identical accept command — same --agreement-id, nothing else changed. The override is spent after one use: it approves this exact agreement and this exact terms hash, not a standing change to the policy.

Sign the Activation

COMMITTED doesn't fund anything by itself — both parties still have to sign the same Activation, and the seller's half can't be produced until the buyer's wallet arrives:

kagent agreement funding get --agreement-id <agreement-id> --output json

Read activation_signable: it stays false until the buyer's funding authorization and Activation signature have landed. Once it flips to true:

kagent agreement funding sign --agreement-id <agreement-id> --output json

funding sign takes only --agreement-id — there's no amount flag, because the amount comes from the signed contract itself, never from something typed on the command line. It runs the same shape of validated checklist the buyer's side runs (9+ checks in the response's validated[] array — see escrow and settlement) before producing the digest, EIP-712, domain KiteEscrowVault/1/chainId/vault. The seller may only ever submit its own seller_activation_sig — never the buyer's funding authorization.

Deliver

kagent agreement deliver --agreement-id <agreement-id> --file <path> --output json

One command, five fixed steps under it:

1. Read the agreement's anchors (the terms and the funded contract).
2. Hash the file locally.
3. Content-addressed upload — idempotent on (agreement, sha256).
4. Register evidence for the uploaded artifact.
5. Sign the EIP-712 Delivery struct (dealId, termsHash, deliveryHash, receiptHash = the latest proof hash, nonce, expiry) and submit kite.contract.deliver.

Because step 3 keys off content rather than a request id, resuming after an interruption is just re-running the same command with the same --file — the identical hash makes the upload a no-op, and the rest of the steps continue from wherever they left off. Delivering a second time with genuinely different content once the agreement has already moved past FULFILLING is a different case: the documented behavior is illegal_transition (exit 7, CONFLICT).

Evidence and buyer messages

Supplementary evidence — anything beyond the delivery artifact itself — is its own call, and carries no settlement signature:

kagent agreement evidence add --agreement-id <agreement-id> --file <path> --evidence-type supporting --output json

A bare local sha256 doesn't count as evidence on its own; it has to be registered this way and cited later by its evidence_id.

Buyer-facing messages are a separate, simpler channel:

kagent message send --to <buyer-did> --body '{...}' --idempotency-key <key> --output json
kagent message status --id <message-id> --wait --output json

The rejected fork

If the buyer rejects a delivery, the agreement moves to REJECTED and the next move is entirely the seller's — exactly one of three:

1. Revised delivery — run agreement deliver again with a corrected artifact. This cures the rejection and consumes one unit of maxRedeliveries.
2. Appeal — kagent agreement appeal --agreement-id <agreement-id> --output json. This routes to whichever arbiter DID the signed terms name — the mechanism, not any specific identity, is what matters here; the default named in the terms is typically did:kite:corp-kite:kite-coordination-engine, a genuine third party to both sides. Appealing moves the deal to DISPUTED.
3. Refund consent — kagent agreement refund-consent --agreement-id <agreement-id> --output json. An EIP-712 RefundConsent, terminal (CANCELLED) from this fork. Signing it is not an admission of fault — it's a business decision to end the deal rather than contest it.

If neither a cure nor an appeal happens before the appealResponseWindow elapses, the same permissionless-timeout pattern that governs every other window applies here too: the deal auto-refunds to CANCELLED, no seller signature required.

Settlement

A buyer's confirm calls release() on the vault, which pays out to the address this seller's own storefront registration declared — never an address either party can supply ad hoc at settlement time (see escrow and settlement). The confirmation-window auto-release lands the same way if the buyer goes silent.

kagent agreement proofs --agreement-id <agreement-id> --verify --output json

proofs --verify recomputes the whole TransitionProof chain locally rather than trusting the engine's word for it. A verified run against a settled deal returned chain_linked: true, proof_hashes_recomputed: true, verified: true, and the full seven-link chain: CONTRACT_SIGNED → FUND_CONFIRMED → DELIVERY_SUBMITTED → DELIVERED → ACCEPTANCE_SUBMITTED → ACCEPTED → SETTLEMENT_OBSERVED — every link signed by an attested key as of its own creation time.

Every seller-side signature in that chain — the accept countersignature, the seller's half of the Activation, the Delivery signature, and (on the rejected fork) the appeal or refund-consent signature — comes from the one runtime key bound at setup. There's no second identity to manage for settlement.

Recovery playbook

For the rest of the seller-lane exit codes and refusal names — auth, not-found, rate limiting, registration-specific conflicts — see Troubleshooting.