@nuanu-ai/agentify 0.3.1 → 0.5.0

package/README.md

@@ -125,11 +125,12 @@ than the engineer.
 
 ## Versions
 
-This is an early `0.x` pilot surface and the names in it can still change. What
-does not change quietly is the wire: the SDK and the gateway agree on a
-contract version, and a worker whose version the gateway does not share stops
-before it takes an order rather than half reading a document and misreporting
-its own successes. Register `agentify.on('problem', …)`, which is where you
+This is an early `0.x` pilot surface and the names in it can still change. The
+SDK and the gateway agree on a contract version, and a worker whose version the
+gateway does not share stops before it takes an order. During the pilot that
+version does not move with every change, so a release older than the gateway
+can read a word it does not know as a failure rather than stop: keep the
+package current. Register `agentify.on('problem', …)`, which is where you
 hear about that and about everything else that did not get through.
 
 ## License

package/dist/client.d.ts

@@ -14,7 +14,7 @@
  * calls that answer it, and that is the part worth reading before changing
  * anything here, because two things that look alike are deliberately not.
  *
- * `order.delivered(...)`, `order.refused(...)` and `order.accepted(...)`
+ * `order.delivered(...)`, `order.refused(...)` and `order.accepted()`
  * build the answer and send nothing; the handler still returns it. A bot
  * library lets a handler reply and forget, and forgetting there costs a
  * message; forgetting here is an order nobody answered — redelivered, a
@@ -55,7 +55,7 @@
  * branch, under a code this package produces and the gateway never sends. The
  * three codes and what separates them are written down beside them below.
  */
-import type { Acceptance, CardInput, Delivery, HandlerAnswer, Money, Order, OrderAcceptResponse, OrderCallResponse, OrderWithStatus, PublishResult, QuoteRequest, QuoteResponse, Refusal } from "@nuanu-ai/agentify-contracts";
+import type { CardInput, Delivery, HandlerAnswer, Money, Order, OrderAcceptResponse, OrderCallResponse, OrderWithStatus, PublishResult, QuoteRequest, QuoteResponse, Refusal } from "@nuanu-ai/agentify-contracts";
 import { type EventHandler, type ProblemReporter, type StreamHandlerKind } from "./worker.js";
 export interface ClientOptions {
     /**
@@ -112,11 +112,11 @@ export interface OrderCalls {
     /** A final "this cannot be delivered", as the handler's answer. */
     refused(refusal: Refusal): HandlerAnswer;
     /**
-     * Taking the order on without delivering yet, as the handler's answer. An
-     * empty acceptance is a complete answer; the expected time is said where it
-     * is known.
+     * Taking the order on without delivering yet, as the handler's answer. It
+     * carries nothing: what the merchant is held to is the delivery deadline on
+     * the card.
      */
-    accepted(acceptance?: Acceptance): HandlerAnswer;
+    accepted(): HandlerAnswer;
     /**
      * The goods for an order taken on earlier. Idempotent by the order's own
      * identifier, so repeating it after a dropped connection does no work twice.
@@ -125,7 +125,7 @@ export interface OrderCalls {
     /** A final "this cannot be delivered" for an order already taken on. */
     refuse(refusal: Refusal): Promise<OrderCallResponse>;
     /** Takes the order on from outside a handler. Repeats are ordinary. */
-    accept(acceptance?: Acceptance): Promise<OrderAcceptResponse>;
+    accept(): Promise<OrderAcceptResponse>;
 }
 /**
  * The least an order can be and still be answerable: its identifier, and the
@@ -295,8 +295,11 @@ export interface AgentifyClient {
      * safe to call on a client that was never started.
      *
      * Two things are abandoned rather than finished, and they are not abandoned
-     * on the same terms. A poll parked at the gateway is dropped, and whatever
-     * it would have carried was never handed to anybody, so it is redelivered.
+     * on the same terms. A poll parked at the gateway is dropped, and the
+     * gateway stops it and keeps whatever arrives for the next poll; only
+     * something taken in the instant before the drop is lost, and that is an
+     * order, which comes again, or an event, which is sent once — the list of
+     * open orders is what finds a refund owed whose event went missing.
      * An answer already on its way — a delivery the handler produced a moment
      * ago — is dropped too, and there the honest thing to say is that nobody on
      * this side knows whether it arrived first: the order may already be closed

package/dist/client.js

@@ -14,7 +14,7 @@
  * calls that answer it, and that is the part worth reading before changing
  * anything here, because two things that look alike are deliberately not.
  *
- * `order.delivered(...)`, `order.refused(...)` and `order.accepted(...)`
+ * `order.delivered(...)`, `order.refused(...)` and `order.accepted()`
  * build the answer and send nothing; the handler still returns it. A bot
  * library lets a handler reply and forget, and forgetting there costs a
  * message; forgetting here is an order nobody answered — redelivered, a
@@ -241,8 +241,7 @@ const reportToConsole = (problem) => {
  * side means changing both in the same commit.
  *
  * A key matching neither prefix says nothing at all, which is the third case
- * ADR-0020 names: a key issued before the prefix existed, or one that is not
- * ours. There is nothing to fall back to. Guessing is wrong in both directions
+ * ADR-0020 names: a key naming no environment, or one that is not ours. There is nothing to fall back to. Guessing is wrong in both directions
  * — telling a merchant their money is play when it is real, or the other way
  * round — and no line at all is better than a wrong claim about whose money is
  * at stake.
@@ -360,11 +359,11 @@ export const createClient = (options) => {
             ? answer.document
             : { ok: false, error: failedCall(route === "deliver_order", answer.failure) };
     };
-    const acceptCall = async (orderId, acceptance) => {
+    const acceptCall = async (orderId) => {
         reachable();
         const answer = await callRoute(gateway, "accept_order", {
             path: { order_id: orderId },
-            body: acceptance ?? {},
+            body: {},
         });
         // Accepting the same order again is ordinary: an order is taken on afresh
         // on every redelivery, so a repeat does no work twice.
@@ -384,10 +383,10 @@ export const createClient = (options) => {
     const callsFor = (orderId) => ({
         delivered: (delivery) => ({ delivered: delivery }),
         refused: (refusal) => ({ refused: refusal }),
-        accepted: (acceptance) => ({ accepted: acceptance ?? {} }),
+        accepted: () => ({ accepted: {} }),
         deliver: (delivery) => orderCall("deliver_order", orderId, delivery),
         refuse: (refusal) => orderCall("refuse_order", orderId, refusal),
-        accept: (acceptance) => acceptCall(orderId, acceptance),
+        accept: () => acceptCall(orderId),
     });
     const withCalls = (order) => Object.assign({}, order, callsFor(order.id));
     const askedWithAnswers = (question) => Object.assign({}, question, {

package/dist/index.d.ts

@@ -32,7 +32,7 @@
  * here from the contracts package, so that integration code has one import and
  * not two.
  */
-export type { Acceptance, CallError, Card, CardInput, Delivery, Fulfillment, HandlerAnswer, MerchantFinding, Money, Order, OrderCallResponse, OrderCallResult, OrderEvent, OrderList, OrderStatus, OrderWithStatus, Problem, PublishResult, QuotePurpose, QuoteRequest, QuoteResponse, Refusal, RefusalCode, SalePrice, } from "@nuanu-ai/agentify-contracts";
+export type { CallError, Card, CardInput, Delivery, Fulfillment, HandlerAnswer, MerchantFinding, Money, Order, OrderCallResponse, OrderCallResult, OrderEvent, OrderList, OrderStatus, OrderWithStatus, Problem, PublishResult, QuotePurpose, QuoteRequest, QuoteResponse, Refusal, RefusalCode, SalePrice, Shipment, ShipTo, } from "@nuanu-ai/agentify-contracts";
 export { CARD_REJECTED, MERCHANT_FINDINGS, ORDER_EVENT_TYPES, RECOMMENDED_REFUSAL_CODES, } from "@nuanu-ai/agentify-contracts";
 export type { CardCheck } from "./check-card.js";
 export { checkCard } from "./check-card.js";

package/dist/verify.d.ts

@@ -1,17 +1,16 @@
 /**
- * `agentify verify` — the check a merchant runs on themselves before they
- * ask us to look.
- *
- * The portal describes two checks. Is the card enough for an agent to assemble
- * a correct purchase, and does the merchant's handler hold idempotency — that
- * is, does a second delivery appear when one and the same order arrives twice.
- *
- * The first is here in full. The second is not, and this file refuses to
- * pretend otherwise: it names what is missing, in the same words anyone can
- * check against the route table, and answers with a code of its own that says
- * "did not run" rather than "passed" or "failed". The reasons are written out
- * in `IDEMPOTENCY_IS_NOT_BUILDABLE` below and are worth reading before anybody
- * tries to add the check, because the gap is not in this package.
+ * `agentify verify` — the check a merchant runs on their cards before they
+ * publish them.
+ *
+ * It checks one thing, in full: whether a card is enough for an agent to
+ * assemble a correct purchase, read the way publication reads it. Whether the
+ * merchant's handler holds against one order delivered twice is not something
+ * a command holding only card files can try — no route raises an order for a
+ * merchant's own card — so it is not one of this command's checks, and the
+ * output says so and where it is proved instead: with a test purchase against
+ * the merchant's own delivery system. Counted here as a check that "did not
+ * run", it made every complete card answer as something short of success, and
+ * a build reading the exit code took a good card for a failure.
  *
  * Which cards are checked is asked for rather than discovered. Nothing in this
  * package, in the contract or in any decision says where a merchant keeps
@@ -19,56 +18,15 @@
  * convention — a file name, a directory, a manifest — that nobody agreed to
  * and that every merchant would then have to work around.
  */
-/**
- * What the command answers with.
- *
- * Four and not two, because a build that branches on this needs to tell a
- * check that failed from a check that never ran. Collapsing the two would make
- * a missing check look like a passing one on the day somebody decides that
- * anything non-zero is a failure and anything else is fine.
- */
+/** What the command answers with. */
 export declare const VERIFY_EXIT: Readonly<{
-    /** Every check ran and every check passed. */
+    /** Every card it was given is complete as far as the contract can tell. */
     PASSED: 0;
-    /** A check ran and found something. */
+    /** A card has findings. */
     PROBLEMS: 1;
     /** The command was called with something it cannot work from. */
     USAGE: 2;
-    /** A check could not be run at all, so nothing is claimed about it. */
-    COULD_NOT_RUN: 3;
 }>;
-/**
- * Why the idempotency run is not in this version, stated so it can be checked
- * rather than taken on trust.
- *
- * The run the portal describes needs a test order to exist: the same order
- * delivered twice through the live subscription, marked `test`, against a card
- * that is published but not yet in any catalog. Four things it needs are
- * absent, and none of them is ours to add here.
- *
- * There is no route that asks for one. The only way an order comes into being
- * on this surface is `purchase_item`, and that is the payment exchange itself
- * — an agent buying — not a request a merchant can make about their own card.
- *
- * `PurchaseRequestSchema` is closed and carries the purchase parameters and
- * nothing else, so there is nowhere in a purchase to say "this one is a test".
- *
- * Nothing says how an order's `test` flag comes to be true. The order carries
- * it, the handler is told to branch on it, and no document in the contract
- * describes who sets it or from what.
- *
- * And a card carries no marker for "published, not yet in catalogs", which is
- * the state the portal says these orders are raised against.
- *
- * What is missing is not an environment to run it in. There are two sites, the
- * test one settles against test funds, and a key says which it belongs to
- * (ADR-0020) — so a merchant already has somewhere to try their integration
- * without spending anything. What is missing is a way to make an order happen
- * there: no route raises one, and the four absences above are the whole of what
- * would have to exist first. Inventing a route or a field here would be
- * designing that, and this is not the place where it is designed.
- */
-export declare const IDEMPOTENCY_IS_NOT_BUILDABLE: string;
 /** The code a finding carries when the file held no card to check at all. */
 export declare const NOT_JSON = "not_json";
 export type Say = (line: string) => void;

package/dist/verify.js

@@ -1,17 +1,16 @@
 /**
- * `agentify verify` — the check a merchant runs on themselves before they
- * ask us to look.
+ * `agentify verify` — the check a merchant runs on their cards before they
+ * publish them.
  *
- * The portal describes two checks. Is the card enough for an agent to assemble
- * a correct purchase, and does the merchant's handler hold idempotency — that
- * is, does a second delivery appear when one and the same order arrives twice.
- *
- * The first is here in full. The second is not, and this file refuses to
- * pretend otherwise: it names what is missing, in the same words anyone can
- * check against the route table, and answers with a code of its own that says
- * "did not run" rather than "passed" or "failed". The reasons are written out
- * in `IDEMPOTENCY_IS_NOT_BUILDABLE` below and are worth reading before anybody
- * tries to add the check, because the gap is not in this package.
+ * It checks one thing, in full: whether a card is enough for an agent to
+ * assemble a correct purchase, read the way publication reads it. Whether the
+ * merchant's handler holds against one order delivered twice is not something
+ * a command holding only card files can try — no route raises an order for a
+ * merchant's own card — so it is not one of this command's checks, and the
+ * output says so and where it is proved instead: with a test purchase against
+ * the merchant's own delivery system. Counted here as a check that "did not
+ * run", it made every complete card answer as something short of success, and
+ * a build reading the exit code took a good card for a failure.
  *
  * Which cards are checked is asked for rather than discovered. Nothing in this
  * package, in the contract or in any decision says where a merchant keeps
@@ -23,68 +22,21 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { checkCard } from "./check-card.js";
 import { describeProblems } from "./schema.js";
-/**
- * What the command answers with.
- *
- * Four and not two, because a build that branches on this needs to tell a
- * check that failed from a check that never ran. Collapsing the two would make
- * a missing check look like a passing one on the day somebody decides that
- * anything non-zero is a failure and anything else is fine.
- */
+/** What the command answers with. */
 export const VERIFY_EXIT = Object.freeze({
-    /** Every check ran and every check passed. */
+    /** Every card it was given is complete as far as the contract can tell. */
     PASSED: 0,
-    /** A check ran and found something. */
+    /** A card has findings. */
     PROBLEMS: 1,
     /** The command was called with something it cannot work from. */
     USAGE: 2,
-    /** A check could not be run at all, so nothing is claimed about it. */
-    COULD_NOT_RUN: 3,
 });
-/**
- * Why the idempotency run is not in this version, stated so it can be checked
- * rather than taken on trust.
- *
- * The run the portal describes needs a test order to exist: the same order
- * delivered twice through the live subscription, marked `test`, against a card
- * that is published but not yet in any catalog. Four things it needs are
- * absent, and none of them is ours to add here.
- *
- * There is no route that asks for one. The only way an order comes into being
- * on this surface is `purchase_item`, and that is the payment exchange itself
- * — an agent buying — not a request a merchant can make about their own card.
- *
- * `PurchaseRequestSchema` is closed and carries the purchase parameters and
- * nothing else, so there is nowhere in a purchase to say "this one is a test".
- *
- * Nothing says how an order's `test` flag comes to be true. The order carries
- * it, the handler is told to branch on it, and no document in the contract
- * describes who sets it or from what.
- *
- * And a card carries no marker for "published, not yet in catalogs", which is
- * the state the portal says these orders are raised against.
- *
- * What is missing is not an environment to run it in. There are two sites, the
- * test one settles against test funds, and a key says which it belongs to
- * (ADR-0020) — so a merchant already has somewhere to try their integration
- * without spending anything. What is missing is a way to make an order happen
- * there: no route raises one, and the four absences above are the whole of what
- * would have to exist first. Inventing a route or a field here would be
- * designing that, and this is not the place where it is designed.
- */
-export const IDEMPOTENCY_IS_NOT_BUILDABLE = [
-    "The idempotency run needs a test order, and nothing on the surface can ask for one:",
-    "  - no route raises an order for a merchant's own card; the only way an order",
-    "    comes into being is purchase_item, which is an agent's payment exchange",
-    "  - purchase_item's body carries the purchase parameters and nothing else, so",
-    "    there is nowhere in it to say that a purchase is a test",
-    "  - nothing in the contract says how an order's test flag comes to be true",
-    "  - a card carries no marker for published-but-not-yet-in-catalogs, which is",
-    "    the state the documentation raises these orders against",
-    "The test site is not what is missing: it exists, it settles against test",
-    "funds, and a csk_test_ key belongs to it. What is missing is a way to make",
-    "an order happen there, and inventing a route or a field here would be",
-    "designing one.",
+/** What this command does not check, and where that is proved instead. */
+const NOT_CHECKED_HERE = [
+    "Repeats of one order: not checked by this command.",
+    "  Whether a second delivery of the same order makes second goods is proved",
+    "  against your own delivery system, with a test purchase: the buyer has to",
+    "  keep what the first delivery carried.",
 ].join("\n");
 /** The code a finding carries when the file held no card to check at all. */
 export const NOT_JSON = "not_json";
@@ -99,10 +51,9 @@ const USAGE = [
     "",
     "Checks each card against the published contract before it is published.",
     "",
-    "Answers: 1 a check found something, 2 called with something it cannot work",
-    "from, 3 a check could not be run. Zero, which means every check passed, is",
-    "not reachable today: the idempotency run cannot be built, and this command",
-    "will not report success for a check that never happened.",
+    "Answers: 0 every card is complete as far as the contract can tell, 1 a card",
+    "has findings, 2 called with something it cannot work from. Whether your",
+    "handler holds against an order delivered twice is not checked here.",
 ].join("\n");
 /**
  * Why the bare command the documentation shows does not run.
@@ -138,8 +89,8 @@ const USAGE = [
  * dry run of publishing, which can refuse for reasons no schema carries; there
  * is no such route (`docs/research/00-open-questions.md`).
  *
- * So this is a stop and not a scolding, and it is answered with the code that
- * means "did not run". The way through it is to name the card files, which are
+ * So this is a stop and not a scolding, and it is answered as a call the
+ * command cannot work from. The way through it is to name the card files, which are
  * the copy the merchant can still change — the file is what the next publish
  * carries, whether the card is new or an edit to one already out.
  */
@@ -195,7 +146,7 @@ export const runVerify = async (argv, say) => {
         say(NOTHING_TO_CHECK);
         say("");
         say(USAGE);
-        return VERIFY_EXIT.COULD_NOT_RUN;
+        return VERIFY_EXIT.USAGE;
     }
     const checked = [];
     for (const file of files) {
@@ -225,12 +176,10 @@ export const runVerify = async (argv, say) => {
         say("  Fix these and run again: a card whose shape is wrong is not checked against the rules that compare one field with another, so there may be more behind them.");
     }
     say("");
-    say("Idempotency");
-    say("  could not be run.");
-    say(IDEMPOTENCY_IS_NOT_BUILDABLE);
+    say(NOT_CHECKED_HERE);
     say("");
     say(faulted.length > 0
-        ? "Verdict: the cards have findings, and the idempotency run did not happen."
-        : "Verdict: the cards are complete. Nothing is claimed about idempotency — that check did not run.");
-    return faulted.length > 0 ? VERIFY_EXIT.PROBLEMS : VERIFY_EXIT.COULD_NOT_RUN;
+        ? "Verdict: the cards have findings."
+        : "Verdict: the cards are complete as far as the contract can tell.");
+    return faulted.length > 0 ? VERIFY_EXIT.PROBLEMS : VERIFY_EXIT.PASSED;
 };

package/dist/worker.d.ts

@@ -320,8 +320,11 @@ export interface RunningWorker {
      * Stops the loop and waits for it to finish. Safe to call twice.
      *
      * Two things are abandoned rather than finished, and they are not abandoned
-     * on the same terms. A poll parked at the gateway is dropped, and whatever
-     * it would have carried was never handed to anybody, so it is redelivered.
+     * on the same terms. A poll parked at the gateway is dropped, and the
+     * gateway stops it and keeps whatever arrives for the next poll; only
+     * something taken in the instant before the drop is lost, and that is an
+     * order, which comes again, or an event, which is sent once — the list of
+     * open orders is what finds a refund owed whose event went missing.
      * An answer already on its way — a delivery the handler produced a moment
      * ago — is dropped too, and there the honest thing to say is that nobody on
      * this side knows whether it arrived first: the order may already be closed

package/dist/worker.js

@@ -67,7 +67,7 @@ import { callRoute, REACH, whatIsKnown } from "./transport.js";
  * order that never comes.
  */
 const andSoTheOrder = (failure) => failure.reach === REACH.NOT_RECEIVED
-    ? ", so the order will be delivered again"
+    ? ", so the order counts as undelivered: it is sent again while it has attempts left and its deadline allows, and otherwise ends undelivered"
     : ", so whether the order is delivered again is not something this side can say";
 /**
  * The things the worker has to tell the merchant about, under the names their
@@ -361,7 +361,7 @@ deadlineMs = POLL_DEADLINE_MS) => {
                 kind: WORKER_PROBLEM_KINDS.NO_HANDLER,
                 fatal: false,
                 subject: order.id,
-                message: `order ${order.id} arrived and no handler was registered with on('${REGISTERED_AS.order}'), so it was left unanswered and will be delivered again`,
+                message: `order ${order.id} arrived and no handler was registered with on('${REGISTERED_AS.order}'), so it was left unanswered: it is sent again while it has attempts left and its deadline allows, and otherwise ends undelivered`,
             });
             return;
         }
@@ -375,7 +375,7 @@ deadlineMs = POLL_DEADLINE_MS) => {
                 fatal: false,
                 cause,
                 subject: order.id,
-                message: `the handler threw on order ${order.id}, so nothing was answered and the order will be delivered again: ${String(cause)}`,
+                message: `the handler threw on order ${order.id}, so nothing was answered and the order counts as undelivered — it is sent again while it has attempts left and its deadline allows, and otherwise ends undelivered: ${String(cause)}`,
             });
             return;
         }
@@ -385,7 +385,7 @@ deadlineMs = POLL_DEADLINE_MS) => {
                 kind: WORKER_PROBLEM_KINDS.HANDLER_ANSWER_REFUSED,
                 fatal: false,
                 subject: order.id,
-                message: `the handler's answer for order ${order.id} is not one the contract carries, so nothing was sent and the order will be delivered again:\n${describeProblems(problemsOf(checked.error.issues))}`,
+                message: `the handler's answer for order ${order.id} is not one the contract carries, so nothing was sent and the order counts as undelivered — it is sent again while it has attempts left and its deadline allows, and otherwise ends undelivered:\n${describeProblems(problemsOf(checked.error.issues))}`,
             });
             return;
         }
@@ -550,11 +550,20 @@ deadlineMs = POLL_DEADLINE_MS) => {
                 const remark = spoken !== undefined && !speaksContract(spoken)
                     ? ` — what answered names contract version ${spoken} while this SDK speaks ${contractVersion}, which may mean the gateway is of another version`
                     : "";
+                // A refusal that says waiting will not change it — a key revoked or
+                // never accepted is the case that matters — is still not taken as the
+                // end: one such answer from a proxy must not stop a merchant's worker
+                // for good. But it is said for what it is, because "asking again"
+                // alone reads as something that will pass, and a revoked key takes no
+                // new orders until it is replaced.
+                const settled = answer.failure.refusal?.retryable === false;
                 failures += 1;
                 report({
                     kind: WORKER_PROBLEM_KINDS.POLL_FAILED,
                     fatal: false,
-                    message: `${answer.failure.reason}${remark} — asking again after a wait`,
+                    message: settled
+                        ? `${answer.failure.reason}${remark} — the gateway says asking again will not change this, and no new orders arrive until it is fixed (a revoked key has to be replaced); asking again after a wait in case it was not the gateway that answered`
+                        : `${answer.failure.reason}${remark} — asking again after a wait`,
                 });
                 await rest(retryDelayMs(failures, clock.random()));
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Sell your existing products to AI agents: publish product cards to an x402 storefront and fill the paid orders from your own service.",
   "keywords": [
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nuanu-ai/agentify-contracts": "0.7.0"
+    "@nuanu-ai/agentify-contracts": "0.9.0"
   },
   "devDependencies": {
     "vitest": "^4.1.11",