@ambasada/village 0.8.7 → 0.8.9

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 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, ChatDecision, 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;
@@ -58,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`). */
@@ -119,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.
@@ -163,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;
@@ -176,8 +206,13 @@ export declare class Village extends Ambasada {
         }) => Promise<ChatLine[]>;
         /** Proposals waiting for your team. */
         proposals: () => Promise<ChatProposal[]>;
-        /** Approve (it runs now) or decline a proposal. */
-        decide: (id: string, decision: "approve" | "decline", reason?: string) => Promise<unknown>;
+        /**
+         * Approve (it runs now) or decline a proposal. `wait` (approve): also what the agent said after it, up to a
+         * minute (`follow_up`).
+         */
+        decide: (id: string, decision: "approve" | "decline", reason?: string, options?: {
+            wait?: boolean;
+        }) => Promise<ChatDecision>;
         transcript: (since?: number, limit?: number) => Promise<{
             entries: TranscriptEntry[];
             next_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

@@ -12,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,
@@ -49,6 +50,7 @@ __export(src_exports, {
   appNotifyBody: () => appNotifyBody,
   appNotifyResult: () => appNotifyResult,
   appWebhookHeaders: () => appWebhookHeaders,
+  asyncOfferingProblem: () => asyncOfferingProblem,
   base64url: () => base64url,
   bundlesMiniappSdk: () => bundlesMiniappSdk,
   checkHtml: () => checkHtml,
@@ -1491,6 +1493,16 @@ 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) {
@@ -1636,6 +1648,7 @@ var CLIENT_TIMEOUT_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() {
@@ -1738,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);
@@ -1833,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) ───────────────────────
   /**
@@ -1922,15 +1975,27 @@ 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. */
     proposals: async () => (await this.call("GET", "/v1/agent/chat/proposals")).proposals,
-    /** Approve (it runs now) or decline a proposal. */
-    decide: (id, decision, reason) => this.call("POST", `/v1/agent/chat/proposals/${encodeURIComponent(id)}`, { body: { decision, ...reason ? { reason } : {} } }),
+    /**
+     * Approve (it runs now) or decline a proposal. `wait` (approve): also what the agent said after it, up to a
+     * minute (`follow_up`).
+     */
+    decide: (id, decision, reason, options = {}) => this.call("POST", `/v1/agent/chat/proposals/${encodeURIComponent(id)}`, {
+      body: { decision, ...reason ? { reason } : {}, ...options.wait ? { wait: true } : {} },
+      ...options.wait ? { timeoutMs: CHAT_WAIT_MS + 15e3 } : {}
+    }),
     transcript: (since = 0, limit = 200) => this.call("GET", "/v1/agent/transcript", { query: { since, limit } }),
     state: () => this.call("GET", "/v1/agent/state")
   };
@@ -1938,6 +2003,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) {
@@ -1950,6 +2029,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;
 }
 

package/dist/types.d.ts

@@ -17,6 +17,8 @@ export interface ReceiptClaims {
     /** TON you may still spend downstream on behalf of this call. */
     budget?: number;
     deal_id?: string;
+    /** An async offering's call: when the buyer's max_wait_s runs out (unix seconds); `startJob(…, { deadline: call.deadline * 1000 })`. */
+    deadline?: number;
     body_sha256: string;
     iat: number;
     exp: number;
@@ -149,7 +151,28 @@ 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 = 
+/** `attempts`: the failed ones so far (the template's `jobAnswer(job)`); the buyer sees "working (attempt 2, last error: …)". */
+{
+    status: "working";
+    attempts?: {
+        at: string;
+        error: string;
+    }[];
+} | {
+    status: "done";
+    output: unknown;
+} | {
+    status: "failed";
+    error: string;
+};
 export interface BuyResult<Output = any> {
     output: Output;
     callId: string | null;
@@ -163,6 +186,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 & {});
@@ -250,6 +277,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;
@@ -371,7 +402,22 @@ 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); also on a `wait: false` send during a wake. */
+    queued?: "wake";
     reply?: ChatLine | null;
+    /** The turn ended and the agent said nothing, even after the village asked it once more: "No reply (the model returned nothing)". */
+    no_reply?: string;
+}
+/** `agent.decide`: what ran, and with `wait` (approve) what the agent said after it. */
+export interface ChatDecision {
+    id: string;
+    decision: "approve" | "decline";
+    /** The action's outcome (approve): its result, or `{ error: { code, message } }` when it failed. */
+    result: unknown;
+    /** The API's time of the decision (ms). */
+    at?: number;
+    /** With `wait`: the agent's next line (its reply, or the "no reply" card), null when a minute went by. */
+    follow_up?: ChatLine | null;
 }
 export interface MarketOffering {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "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.7"
+    "@ambasada/sdk": "^0.8.9"
   },
   "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.7"
+    "@ambasada/cli": "0.8.9"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",