@ambasada/village 0.8.6 → 0.8.8

package/dist/client.d.ts

@@ -1,11 +1,17 @@
 import { Ambasada, type AmbasadaOptions } from "@ambasada/sdk/platform";
 import { type IncomingRequest } from "./receipt.js";
-import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutDelivery, CheckoutDeliveryInput, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, ChatLine, ChatProposal, ChatTurn, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+import type { JobAnswer, AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutDelivery, CheckoutDeliveryInput, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, ChatLine, ChatProposal, ChatTurn, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+/** How long a utility call may take here: the API's own limit plus a margin, so the SDK never gives up on a call the API finishes and charges. */
+export declare const CLIENT_TIMEOUT_MS: {
+    readonly llm: number;
+    readonly image: number;
+    readonly tool: number;
+};
 /** The Hack A Ton API. The platform API (`@ambasada/sdk`) is https://api.ambasada.dev. */
 export declare const DEFAULT_VILLAGE_API_URL = "https://hackaton.ambasada.id";
 export declare const DEFAULT_MODEL = "deepseek-v4.1-flash";
 export interface VillageOptions extends AmbasadaOptions {
-    /** Team key (`sk_live_…`, from the village app → Developers). Default: `AMBASADA_API_KEY`. */
+    /** Team key (`sk_live_…`, from the village app → Team → Settings). Default: `AMBASADA_API_KEY`. */
     apiKey?: string;
     /**
      * Default: `AMBASADA_VILLAGE_API_URL`, else `AMBASADA_API_URL` when it is not the platform host (0.7
@@ -52,6 +58,22 @@ export declare class Village extends Ambasada {
      *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
      */
     sell<Input = any, Output = unknown>(offering: string, handler: SellHandler<Input, Output>): (req: Request) => Promise<Response>;
+    /**
+     * An async offering's answer to a paid call (`async: true` in offerings.ts): the work goes on as job `id` (in the
+     * template, a Jobs Durable Object named after it), and the Gateway asks `GET <endpoint>/jobs/<id>` until it is done.
+     *
+     *   export default village.sell("ideas", async (input, call) => {
+     *     await startJob(env, `ideas:${call.call_id}`, "ideas", input);
+     *     return village.deferred(`ideas:${call.call_id}`);
+     *   });
+     */
+    deferred(id: string): Response;
+    /**
+     * `GET <endpoint>/jobs/<id>` of an async offering: checks that the Gateway asks (its signed receipt names this
+     * job), then answers with what `lookup(id)` says: `{ status: "working" }`, `{ status: "done", output }` (the buyer
+     * pays and gets `output`) or `{ status: "failed", error }` (the buyer is refunded). `null`: no such job (404).
+     */
+    jobStatus(offering: string, lookup: (id: string, req: Request) => Promise<JobAnswer | null> | JobAnswer | null): (req: Request) => Promise<Response>;
     /** Verifies a signed webhook (`checkout.paid`, `webhook.test`) and returns the event. Throws `WebhookInvalidError`. */
     verifyWebhook<Data = any>(req: IncomingRequest, secret?: string): Promise<WebhookEvent<Data>>;
     /** Verifies a checkout receipt (pay.js `village:paid` → `e.detail.receipt`, or `session.receipt`). */
@@ -74,7 +96,9 @@ export declare class Village extends Ambasada {
     }>;
     /**
      * Tells the village what a paid checkout delivered (`text` ≤ 4000 chars, an https `url`, or both): the person sees it
-     * with the purchase in their app and can rate it. Again for the same session replaces it. CONFLICT before it is paid.
+     * with the purchase in their app (one push, the first time) and can rate it. The same delivery again changes nothing;
+     * a new text replaces it. `{ status: "working" }` / `{ status: "failed", error }` while the work runs or when it gave
+     * up (never over a delivery). CONFLICT before it is paid.
      */
     deliverCheckout(id: string, delivery: CheckoutDeliveryInput): Promise<CheckoutDelivery>;
     /** A reusable payment link for static pages (`<button data-village-pay="pl_…">` with pay.js). */
@@ -101,6 +125,7 @@ export declare class Village extends Ambasada {
     }>;
     /** Sends a `webhook.test` event now and returns the delivery. */
     testWebhook(): Promise<WebhookDelivery>;
+    /** Sends a failed or pending delivery again now (same `webhook-id`). CONFLICT for one already delivered: it never goes out twice. */
     retryWebhookDelivery(id: string): Promise<WebhookDelivery>;
     /** Buys one call of `company/offering` through the Gateway. Money moves only if the seller answers 2xx with valid output. */
     buy<Output = any>(offering: string, input: unknown, options?: BuyOptions): Promise<BuyResult<Output>>;
@@ -110,6 +135,15 @@ export declare class Village extends Ambasada {
      */
     need<Output = any>(name: string, input: unknown, options?: BuyOptions): Promise<BuyResult<Output>>;
     private paid;
+    /**
+     * An async purchase (`buy` with `wait: false`, or one an agent started): waits for its result, long-polling the
+     * Gateway until the seller's job is done (then charged) or its time is up (refunded: throws the error, TIMEOUT).
+     * `wait: false`: one look, `pending: true` while it runs.
+     */
+    buyJob<Output = any>(job: string, options?: {
+        wait?: boolean;
+        signal?: AbortSignal;
+    }): Promise<BuyResult<Output>>;
     /**
      * `village.llm("prompt")` → the answer text; `village.llm.chat(req)` → the full OpenAI-style response.
      * Default model: deepseek-v4.1-flash.
@@ -154,12 +188,17 @@ export declare class Village extends Ambasada {
         steer: (text: string) => Promise<unknown>;
         /**
          * Talk to your agent (docs/AGENT-CHAT.md). With `wait` (the default) it resolves with the reply, up to a
-         * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice.
+         * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice. A reply later than that
+         * (`reply: null`, status `pending`/`running`; `queued: "wake"` while the agent's wake runs): `turn(submission_id)`.
          */
         chat: (text: string, options?: {
             idempotencyKey?: string;
             wait?: boolean;
         }) => Promise<ChatTurn>;
+        /** A turn sent before and its reply, waiting up to `waitSeconds` (0–60, default 60) for one still running. */
+        turn: (submissionId: string, options?: {
+            waitSeconds?: number;
+        }) => Promise<ChatTurn>;
         /** The chat, oldest first: your words, the agent's replies and proposals, and cards for what happened. */
         messages: (options?: {
             since?: number;

package/dist/define.d.ts

@@ -38,8 +38,16 @@ export interface OfferingDef {
     output?: FieldSchema;
     /** Allow a free sample (`market.preview`). */
     preview?: boolean;
-    /** How long the Gateway waits for your answer, ms: 100–30000 (default 30000, the most). Longer work: answer fast, finish later. */
+    /** How long the Gateway waits for your answer, ms: 100–30000 (default 30000, the most). Longer work: `async`. */
     timeout_ms?: number;
     status?: "open" | "paused";
+    /**
+     * Work that takes longer than 30 s (a search and a model call, a report): the handler answers at once with
+     * `village.deferred(jobId)` and `GET <endpoint>/jobs/<id>` says how it is going (`village.jobStatus`). The Gateway
+     * polls it and the buyer pays when it is done; not done within `max_wait_s`, the buyer is refunded.
+     */
+    async?: boolean;
+    /** Async: seconds the Gateway waits for the job (10–600, default 300). */
+    max_wait_s?: number;
 }
 export declare function offering(def: OfferingDef): OfferingDef;

package/dist/index.js

@@ -4,22 +4,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/client.ts
-import { Ambasada, AmbasadaError as AmbasadaError3 } from "@ambasada/sdk/platform";
-
-// src/errors.ts
-import { AmbasadaError, isAmbasadaError } from "@ambasada/sdk/platform";
-var VillageError = AmbasadaError;
-var isVillageError = isAmbasadaError;
-var ReceiptInvalidError = class extends AmbasadaError {
-  reason;
-  constructor(reason, message) {
-    super("RECEIPT_INVALID", `payment required: ${message}`, 402, { reason });
-    this.name = "ReceiptInvalidError";
-    this.reason = reason;
-  }
-};
-
 // ../protocol/src/index.ts
 var src_exports = {};
 __export(src_exports, {
@@ -28,6 +12,7 @@ __export(src_exports, {
   APP_SIGNATURE_HEADER: () => APP_SIGNATURE_HEADER,
   APP_TIMESTAMP_HEADER: () => APP_TIMESTAMP_HEADER,
   APP_WEBHOOK_TOLERANCE_S: () => APP_WEBHOOK_TOLERANCE_S,
+  ASYNC_OFFERING: () => ASYNC_OFFERING,
   AppWebhookError: () => AppWebhookError,
   DEFAULT_HUB_URL: () => DEFAULT_HUB_URL,
   DEFAULT_ISSUER: () => DEFAULT_ISSUER,
@@ -57,12 +42,15 @@ __export(src_exports, {
   SHELL_TOKEN_TTL_S: () => SHELL_TOKEN_TTL_S,
   SLOW_ENTRY_MS: () => SLOW_ENTRY_MS,
   SYSTEM_ACCOUNT: () => SYSTEM_ACCOUNT,
-  VillageError: () => VillageError2,
+  UTILITY_CLIENT_MARGIN_MS: () => UTILITY_CLIENT_MARGIN_MS,
+  UTILITY_TIMEOUT_MS: () => UTILITY_TIMEOUT_MS,
+  VillageError: () => VillageError,
   WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
   WebhookError: () => WebhookError,
   appNotifyBody: () => appNotifyBody,
   appNotifyResult: () => appNotifyResult,
   appWebhookHeaders: () => appWebhookHeaders,
+  asyncOfferingProblem: () => asyncOfferingProblem,
   base64url: () => base64url,
   bundlesMiniappSdk: () => bundlesMiniappSdk,
   checkHtml: () => checkHtml,
@@ -189,7 +177,7 @@ var ERROR_STATUS = {
   // Deploy-freeze and unattended windows: agents keep running, but config and steer are closed (DESIGN.md §5)
   FROZEN: 403
 };
-var VillageError2 = class extends Error {
+var VillageError = class extends Error {
   code;
   status;
   details;
@@ -1505,12 +1493,40 @@ var HEADERS = {
 };
 var MAX_DEPTH = 4;
 var OFFERING_TIMEOUT_MS = { min: 100, max: 3e4 };
+var ASYNC_OFFERING = { defaultMaxWaitS: 300, minMaxWaitS: 10, maxMaxWaitS: 600 };
+function asyncOfferingProblem(isAsync, maxWaitS) {
+  if (isAsync !== void 0 && typeof isAsync !== "boolean") return "async must be true or false";
+  if (maxWaitS === void 0 || maxWaitS === null) return null;
+  if (isAsync !== true) return "max_wait_s needs async: true";
+  if (typeof maxWaitS !== "number" || !Number.isInteger(maxWaitS) || maxWaitS < ASYNC_OFFERING.minMaxWaitS || maxWaitS > ASYNC_OFFERING.maxMaxWaitS) {
+    return `max_wait_s must be whole seconds between ${ASYNC_OFFERING.minMaxWaitS} and ${ASYNC_OFFERING.maxMaxWaitS}`;
+  }
+  return null;
+}
+var UTILITY_TIMEOUT_MS = { llm: 12e4, image: 18e4, tool: 6e4 };
+var UTILITY_CLIENT_MARGIN_MS = 1e4;
 function offeringTimeoutProblem(value) {
   if (value === void 0) return null;
   const n = Number(value);
   return Number.isInteger(n) && n >= OFFERING_TIMEOUT_MS.min && n <= OFFERING_TIMEOUT_MS.max ? null : `timeout_ms must be between ${OFFERING_TIMEOUT_MS.min} and ${OFFERING_TIMEOUT_MS.max} (got ${JSON.stringify(value)})`;
 }
 
+// src/client.ts
+import { Ambasada, AmbasadaError as AmbasadaError3 } from "@ambasada/sdk/platform";
+
+// src/errors.ts
+import { AmbasadaError, isAmbasadaError } from "@ambasada/sdk/platform";
+var VillageError2 = AmbasadaError;
+var isVillageError = isAmbasadaError;
+var ReceiptInvalidError = class extends AmbasadaError {
+  reason;
+  constructor(reason, message) {
+    super("RECEIPT_INVALID", `payment required: ${message}`, 402, { reason });
+    this.name = "ReceiptInvalidError";
+    this.reason = reason;
+  }
+};
+
 // src/receipt.ts
 import { AmbasadaError as AmbasadaError2, getHeader } from "@ambasada/sdk/platform";
 var RECEIPT_HEADER2 = "x-village-receipt";
@@ -1627,6 +1643,12 @@ async function verifyWebhookPayload(secret, headers, body, options = {}) {
 }
 
 // src/client.ts
+var CLIENT_TIMEOUT_MS = {
+  llm: UTILITY_TIMEOUT_MS.llm + UTILITY_CLIENT_MARGIN_MS,
+  image: UTILITY_TIMEOUT_MS.image + UTILITY_CLIENT_MARGIN_MS,
+  tool: UTILITY_TIMEOUT_MS.tool + UTILITY_CLIENT_MARGIN_MS
+};
+var CHAT_WAIT_MS = 6e4;
 var DEFAULT_VILLAGE_API_URL = "https://hackaton.ambasada.id";
 var DEFAULT_MODEL = "deepseek-v4.1-flash";
 function randomKey() {
@@ -1729,6 +1751,39 @@ var Village = class extends Ambasada {
       }
     };
   }
+  /**
+   * An async offering's answer to a paid call (`async: true` in offerings.ts): the work goes on as job `id` (in the
+   * template, a Jobs Durable Object named after it), and the Gateway asks `GET <endpoint>/jobs/<id>` until it is done.
+   *
+   *   export default village.sell("ideas", async (input, call) => {
+   *     await startJob(env, `ideas:${call.call_id}`, "ideas", input);
+   *     return village.deferred(`ideas:${call.call_id}`);
+   *   });
+   */
+  deferred(id) {
+    return Response.json({ job: id, status: "working" }, { status: 202 });
+  }
+  /**
+   * `GET <endpoint>/jobs/<id>` of an async offering: checks that the Gateway asks (its signed receipt names this
+   * job), then answers with what `lookup(id)` says: `{ status: "working" }`, `{ status: "done", output }` (the buyer
+   * pays and gets `output`) or `{ status: "failed", error }` (the buyer is refunded). `null`: no such job (404).
+   */
+  jobStatus(offering2, lookup) {
+    return async (req) => {
+      const id = decodeURIComponent(new URL(req.url).pathname.split("/").filter(Boolean).at(-1) ?? "");
+      try {
+        const seller = await this.company();
+        const claims = await verifyCallReceipt(receiptHeader(req.headers), new Uint8Array(), { keys: this.keySource(), seller, offering: `${seller}/${offering2}` });
+        if (claims.job !== id) throw new ReceiptInvalidError("wrong_kind", "this receipt is for another job");
+      } catch (error) {
+        if (error instanceof AmbasadaError3) return error.toResponse();
+        throw error;
+      }
+      const answer = await lookup(id, req);
+      if (!answer) return Response.json({ error: { code: "NOT_FOUND", message: `no job ${id}` } }, { status: 404 });
+      return Response.json(answer, { status: answer.status === "working" ? 202 : 200 });
+    };
+  }
   /** Verifies a signed webhook (`checkout.paid`, `webhook.test`) and returns the event. Throws `WebhookInvalidError`. */
   async verifyWebhook(req, secret) {
     const { headers, body } = await readIncoming(req);
@@ -1755,7 +1810,9 @@ var Village = class extends Ambasada {
   }
   /**
    * Tells the village what a paid checkout delivered (`text` ≤ 4000 chars, an https `url`, or both): the person sees it
-   * with the purchase in their app and can rate it. Again for the same session replaces it. CONFLICT before it is paid.
+   * with the purchase in their app (one push, the first time) and can rate it. The same delivery again changes nothing;
+   * a new text replaces it. `{ status: "working" }` / `{ status: "failed", error }` while the work runs or when it gave
+   * up (never over a delivery). CONFLICT before it is paid.
    */
   deliverCheckout(id, delivery) {
     return this.call("POST", `/v1/checkout/sessions/${encodeURIComponent(id)}/delivery`, { body: delivery });
@@ -1789,6 +1846,7 @@ var Village = class extends Ambasada {
   testWebhook() {
     return this.call("POST", "/v1/webhook/test");
   }
+  /** Sends a failed or pending delivery again now (same `webhook-id`). CONFLICT for one already delivered: it never goes out twice. */
   retryWebhookDelivery(id) {
     return this.call("POST", `/v1/webhook/deliveries/${encodeURIComponent(id)}/retry`);
   }
@@ -1821,16 +1879,23 @@ var Village = class extends Ambasada {
         "x-village-reason": options.reason?.slice(0, 280)
       }
     });
-    const h = res.headers;
-    return {
-      output: res.json,
-      callId: h.get("x-village-call-id"),
-      amount: num(h.get("x-village-amount")),
-      receipt: h.get("x-village-receipt"),
-      logIndex: num(h.get("x-village-log-index")),
-      replayed: h.get("idempotent-replayed") === "true",
-      offering: h.get("x-village-offering")
-    };
+    if (res.status === 202) {
+      const job = res.json?.job;
+      if (typeof job === "string") return options.wait === false ? pendingResult(job, res.headers) : this.buyJob(job, { signal: options.signal });
+    }
+    return boughtResult(res.json, res.headers);
+  }
+  /**
+   * An async purchase (`buy` with `wait: false`, or one an agent started): waits for its result, long-polling the
+   * Gateway until the seller's job is done (then charged) or its time is up (refunded: throws the error, TIMEOUT).
+   * `wait: false`: one look, `pending: true` while it runs.
+   */
+  async buyJob(job, options = {}) {
+    for (; ; ) {
+      const res = await this.send("GET", `/v1/pay/jobs/${encodeURIComponent(job)}`, { query: { wait: options.wait === false ? 0 : 25 }, signal: options.signal, timeoutMs: 45e3 });
+      if (res.status !== 202) return boughtResult(res.json, res.headers);
+      if (options.wait === false) return pendingResult(job, res.headers);
+    }
   }
   // ── utilities (LLMOK, paid in TON from your wallet) ───────────────────────
   /**
@@ -1845,12 +1910,13 @@ var Village = class extends Ambasada {
       return res.choices[0]?.message.content ?? "";
     },
     {
-      chat: (req) => this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL } })
+      // The API waits up to 120 s for the model (one that reasons first can take a minute): not the client's 45 s.
+      chat: (req) => this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL }, timeoutMs: CLIENT_TIMEOUT_MS.llm })
     }
   );
   images = {
     /** Generates an image; the URL is re-hosted in the village files store. Default model: nano_banana. */
-    generate: (req) => this.call("POST", "/v1/images", { body: { ...req, model: req.model ?? "nano_banana" } })
+    generate: (req) => this.call("POST", "/v1/images", { body: { ...req, model: req.model ?? "nano_banana" }, timeoutMs: CLIENT_TIMEOUT_MS.image })
   };
   tools = {
     /** The curated LLMOK tool catalog with TON prices. */
@@ -1863,6 +1929,8 @@ var Village = class extends Ambasada {
       const res = await this.send("POST", `/v1/tools/${encodeURIComponent(id)}`, {
         body: input ?? {},
         retry: true,
+        // Image tools take as long as images; a routed search may try several providers within the API's 60 s.
+        timeoutMs: id.startsWith("image.") ? CLIENT_TIMEOUT_MS.image : CLIENT_TIMEOUT_MS.tool,
         headers: { "idempotency-key": options.idempotencyKey ?? randomKey() }
       });
       const json = res.json;
@@ -1907,9 +1975,15 @@ var Village = class extends Ambasada {
     steer: (text) => this.call("POST", "/v1/agent/steer", { body: { text } }),
     /**
      * Talk to your agent (docs/AGENT-CHAT.md). With `wait` (the default) it resolves with the reply, up to a
-     * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice.
+     * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice. A reply later than that
+     * (`reply: null`, status `pending`/`running`; `queued: "wake"` while the agent's wake runs): `turn(submission_id)`.
      */
-    chat: (text, options = {}) => this.call("POST", "/v1/agent/chat/turn", { body: { text, wait: options.wait ?? true, idempotency_key: options.idempotencyKey ?? randomKey() } }),
+    chat: (text, options = {}) => this.call("POST", "/v1/agent/chat/turn", { body: { text, wait: options.wait ?? true, idempotency_key: options.idempotencyKey ?? randomKey() }, timeoutMs: CHAT_WAIT_MS + 15e3 }),
+    /** A turn sent before and its reply, waiting up to `waitSeconds` (0–60, default 60) for one still running. */
+    turn: (submissionId, options = {}) => {
+      const wait = options.waitSeconds ?? CHAT_WAIT_MS / 1e3;
+      return this.call("GET", `/v1/agent/chat/turn/${encodeURIComponent(submissionId)}`, { query: { wait }, timeoutMs: wait * 1e3 + 15e3 });
+    },
     /** The chat, oldest first: your words, the agent's replies and proposals, and cards for what happened. */
     messages: async (options = {}) => (await this.call("GET", "/v1/agent/chat/messages", { query: { limit: options.limit ?? 50, ...options.since ? { since: options.since } : {} } })).messages,
     /** Proposals waiting for your team. */
@@ -1923,6 +1997,20 @@ var Village = class extends Ambasada {
 function createVillage(options = {}) {
   return new Village(options);
 }
+function pendingResult(job, headers) {
+  return { output: null, pending: true, job, callId: headers.get("x-village-call-id") ?? job, amount: null, receipt: null, logIndex: null, replayed: false, offering: null };
+}
+function boughtResult(json, h) {
+  return {
+    output: json,
+    callId: h.get("x-village-call-id"),
+    amount: num(h.get("x-village-amount")),
+    receipt: h.get("x-village-receipt"),
+    logIndex: num(h.get("x-village-log-index")),
+    replayed: h.get("idempotent-replayed") === "true",
+    offering: h.get("x-village-offering")
+  };
+}
 
 // src/define.ts
 function defineCompany(app, village2) {
@@ -1935,6 +2023,8 @@ function offering(def) {
   if (!(def.price >= 0.1 && def.price <= 500)) throw new Error(`offering ${def.name}: price must be between 0.1 and 500 TON`);
   const timeout = offeringTimeoutProblem(def.timeout_ms);
   if (timeout) throw new Error(`offering ${def.name}: ${timeout}`);
+  const later = asyncOfferingProblem(def.async, def.max_wait_s);
+  if (later) throw new Error(`offering ${def.name}: ${later}`);
   return def;
 }
 
@@ -1951,7 +2041,7 @@ export {
   RECEIPT_HEADER2 as RECEIPT_HEADER,
   ReceiptInvalidError,
   Village,
-  VillageError,
+  VillageError2 as VillageError,
   WEBHOOK_HEADERS2 as WEBHOOK_HEADERS,
   WebhookInvalidError2 as WebhookInvalidError,
   createVillage,

package/dist/types.d.ts

@@ -55,15 +55,26 @@ export interface CheckoutInput {
     /** Seconds, 300–86400 (default 3600). */
     expires_in?: number;
 }
-/** What a paid checkout delivered (`POST /v1/checkout/sessions/:id/delivery`): text, an https URL, or both. */
+/**
+ * What a paid checkout delivered (`POST /v1/checkout/sessions/:id/delivery`): text, an https URL, or both. While the
+ * work runs (the templates' Jobs Durable Object), `status: "working"` (with `error`: why the last attempt failed, while
+ * it retries); `status: "failed"` with `error` when it gives up. `ambasada village deliveries` shows all three.
+ */
 export interface CheckoutDeliveryInput {
     text?: string;
     url?: string;
+    /** Default `delivered` (with text and/or url). */
+    status?: "working" | "delivered" | "failed";
+    /** Why an attempt failed (working: retrying) or why it gave up (failed); at most 300 characters are kept. */
+    error?: string;
 }
 export interface CheckoutDelivery {
     session: string;
+    /** `delivered` when the API predates delivery statuses. */
+    status?: "working" | "delivered" | "failed";
     text: string | null;
     url: string | null;
+    error?: string | null;
     at: string;
 }
 export interface CheckoutSession {
@@ -138,7 +149,22 @@ export interface BuyOptions {
     /** Why you are buying; shown to your team on approval requests. */
     reason?: string;
     signal?: AbortSignal;
-}
+    /**
+     * An async offering answers with a job: by default `buy` waits for its result (long-polling the Gateway, up to the
+     * offering's `max_wait_s`). `wait: false` returns at once with `pending: true` and the `job` (`village.buyJob(job)` later).
+     */
+    wait?: boolean;
+}
+/** What an async offering's `GET <endpoint>/jobs/<id>` says (village.jobStatus): the Gateway settles on done or failed. */
+export type JobAnswer = {
+    status: "working";
+} | {
+    status: "done";
+    output: unknown;
+} | {
+    status: "failed";
+    error: string;
+};
 export interface BuyResult<Output = any> {
     output: Output;
     callId: string | null;
@@ -152,6 +178,10 @@ export interface BuyResult<Output = any> {
     replayed: boolean;
     /** For `need()`: which offering served it (`company/name`), if the Gateway says. */
     offering: string | null;
+    /** An async offering's job still running (`wait: false`): no output yet and nothing charged. */
+    pending?: boolean;
+    /** The async purchase's job (also its call id): `village.buyJob(job)` reads it. */
+    job?: string;
 }
 /** What the village sells (apps/api/config/pricing.json); any other model is refused. */
 export type ChatModel = "deepseek-v4.1-flash" | (string & {});
@@ -166,6 +196,8 @@ export interface ChatRequest {
     messages: ChatMessage[];
     temperature?: number;
     max_tokens?: number;
+    /** How much the model thinks before it answers; the village sends "low" when you leave it out. More thinking takes longer and more of `max_tokens`. */
+    reasoning_effort?: "low" | "medium" | "high" | (string & {});
     /** `json_schema`: JSON in the schema's shape (live, and the mock's sample of it under `ambasada dev`); `json_object`: any JSON. */
     response_format?: {
         type: "text" | "json_object";
@@ -237,6 +269,10 @@ export interface ListingInput {
     timeout_ms?: number;
     status?: "open" | "paused";
     preview?: boolean;
+    /** The work takes longer than a request: answer `{ job }` and serve `GET <endpoint>/jobs/<job>` (village.jobStatus). */
+    async?: boolean;
+    /** Async: how long the Gateway waits for the job, seconds (10–600, default 300); then the buyer is refunded. */
+    max_wait_s?: number;
 }
 export interface Listing extends ListingInput {
     id: string;
@@ -358,6 +394,8 @@ export interface ChatTurn {
     /** With `wait`: how the turn ended and the agent's reply. */
     status?: "completed" | "error" | "aborted" | "skipped" | "pending" | "running";
     error?: string;
+    /** Still waiting: "wake" while the agent's wake runs (the turn is answered after it). */
+    queued?: "wake";
     reply?: ChatLine | null;
 }
 export interface MarketOffering {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "The Hack A Ton add-on for Ambasada apps: TON checkout, receipts, offerings, LLM, the agent, the market; CLI commands and the local bank.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ambasada/sdk": "^0.8.6"
+    "@ambasada/sdk": "^0.8.8"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
@@ -35,7 +35,7 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "@ambasada/protocol": "0.1.0",
-    "@ambasada/cli": "0.8.6"
+    "@ambasada/cli": "0.8.8"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",