@ambasada/village 0.8.9 → 0.8.11

package/dist/client.d.ts

@@ -53,11 +53,23 @@ export declare class Village extends Ambasada {
     /**
      * Wraps a paid offering as a fetch handler: verifies the receipt (402 if missing or bad), runs
      * `handler(input, call, req)` and answers JSON. A thrown `AmbasadaError` keeps its status (the
-     * Gateway then refunds the buyer).
+     * Gateway then refunds the buyer). The buyer pays only for what you deliver, so a handler that returns an error
+     * object (`{ error: { code, message } }`) or nothing (`undefined`, `null`, `""`) is answered as an error too, never
+     * 200 (dry run 7 #8: "busy, try again" answers were charged). If you can't deliver the paid thing (a tool you
+     * need is rate-limited, CAP_TOOLS_RATE, or down, TOOL_UNAVAILABLE), throw, or rethrow what you caught: the buyer
+     * is refunded and told when to try again.
      *
      *   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>;
+    /**
+     * A warning worth seeing in `ambasada logs` even though the request succeeded, e.g. an answer degraded because a
+     * tool was rate-limited: `console.warn("[village]", …)`. The templates send a request's `[village]` lines along with
+     * any answer, and ambasada.dev keeps them as warnings (at most 50 an hour; never counted as errors).
+     *
+     *   village.warn("wikipedia.search: CAP_TOOLS_RATE, answering from the model alone");
+     */
+    warn(...message: unknown[]): void;
     /**
      * 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.
@@ -157,6 +169,7 @@ export declare class Village extends Ambasada {
         /** Generates an image; the URL is re-hosted in the village files store. Default model: nano_banana. */
         generate: (req: ImageRequest) => Promise<ImageResult>;
     };
+    private generateImage;
     readonly tools: {
         /** The curated LLMOK tool catalog with TON prices. */
         list: () => Promise<ToolListing[]>;
@@ -165,6 +178,7 @@ export declare class Village extends Ambasada {
             idempotencyKey?: string;
         }) => Promise<ToolResult<Output>>;
     };
+    private callTool;
     readonly listings: {
         /** Creates or updates an offering (price changes are versioned). */
         put: (name: string, def: ListingInput) => Promise<Listing>;
@@ -213,9 +227,17 @@ export declare class Village extends Ambasada {
         decide: (id: string, decision: "approve" | "decline", reason?: string, options?: {
             wait?: boolean;
         }) => Promise<ChatDecision>;
-        transcript: (since?: number, limit?: number) => Promise<{
+        /**
+         * The agent's transcript after `since`, oldest first: the first `limit` entries, or with `newest` the last `limit`.
+         * `more`: entries after this page (read on from `next_since`); `earlier`: with `newest`, the ones before it.
+         */
+        transcript: (since?: number, limit?: number, options?: {
+            newest?: boolean;
+        }) => Promise<{
             entries: TranscriptEntry[];
             next_since: number;
+            more?: number;
+            earlier?: number;
         }>;
         state: () => Promise<Record<string, unknown>>;
     };

package/dist/errors.d.ts

@@ -12,6 +12,16 @@ export type VillageError = AmbasadaError;
 /** `isAmbasadaError` under its 0.7 name. */
 export declare const isVillageError: typeof isAmbasadaError;
 export type ReceiptFailure = "malformed" | "unknown_key" | "bad_signature" | "expired" | "not_yet_valid" | "wrong_issuer" | "wrong_seller" | "wrong_offering" | "wrong_kind" | "wrong_session" | "body_mismatch" | "replayed" | "missing";
+/** The stack above `fn` (the SDK method the product called): where the product made the call. */
+export declare function callSite(fn: (...args: never[]) => unknown): string | undefined;
+/**
+ * A failed utility call says which one it was and where the product made it (village dry run 6 #9: a provider error in
+ * a job pointed at `errorFromResponse (worker.js:87121:12)`, inside the SDK, and not at the call). The message ends with
+ * `(during tools.call web.search)` (job attempts and `ambasada logs` show it), `during` names the call, and the stack
+ * starts at the product's calling frame, which `ambasada logs` maps to its source (`at api/frost.ts:12`). An error
+ * already named keeps its name; `restack` gives it this call site (llm() through llm.chat).
+ */
+export declare function duringCall(error: unknown, what: string, site: string | undefined, restack?: boolean): unknown;
 /** The request is not paid: no receipt, a forged or expired one, or one for another seller / offering / body. */
 export declare class ReceiptInvalidError extends AmbasadaError {
     readonly reason: ReceiptFailure;

package/dist/index.js

@@ -148,6 +148,8 @@ var ERROR_STATUS = {
   // inbox texts: 20 an hour, 1 unsolicited per counterparty an hour (EXCHANGE.md §8)
   CAP_CHAT_RATE: 429,
   // turns of the CEO chat per company (docs/AGENT-CHAT.md)
+  CAP_TOOLS_RATE: 429,
+  // tool calls per company per minute (the provider's pool has no limit of its own)
   // Additions needed by the gateway and bank
   UPSTREAM_ERROR: 502,
   PRICE_ABOVE_MAX: 409,
@@ -174,6 +176,8 @@ var ERROR_STATUS = {
   // provider refused the model/tool/key (a configuration problem on our side). Never the caller's fault.
   PROVIDER_BUDGET: 503,
   PROVIDER_DENIED: 502,
+  // A tool or model whose supplier failed 3 times in a row: refused for 5 minutes without calling it (never charged)
+  TOOL_UNAVAILABLE: 503,
   // Deploy-freeze and unattended windows: agents keep running, but config and steer are closed (DESIGN.md §5)
   FROZEN: 403
 };
@@ -1518,6 +1522,24 @@ import { Ambasada, AmbasadaError as AmbasadaError3 } from "@ambasada/sdk/platfor
 import { AmbasadaError, isAmbasadaError } from "@ambasada/sdk/platform";
 var VillageError2 = AmbasadaError;
 var isVillageError = isAmbasadaError;
+function callSite(fn) {
+  const site = {};
+  Error.captureStackTrace?.(site, fn);
+  return site.stack;
+}
+function duringCall(error, what, site, restack = false) {
+  if (!(error instanceof Error)) return error;
+  const e = error;
+  if (e.during && !restack) return e;
+  if (!e.during) {
+    e.during = what;
+    e.message = `${e.message} (during ${what})`;
+  }
+  const frames = (site ?? "").split("\n").filter((line) => line.trim().startsWith("at "));
+  if (frames.length) e.stack = `${e.name}: ${e.message}
+${frames.join("\n")}`;
+  return e;
+}
 var ReceiptInvalidError = class extends AmbasadaError {
   reason;
   constructor(reason, message) {
@@ -1727,7 +1749,11 @@ var Village = class extends Ambasada {
   /**
    * Wraps a paid offering as a fetch handler: verifies the receipt (402 if missing or bad), runs
    * `handler(input, call, req)` and answers JSON. A thrown `AmbasadaError` keeps its status (the
-   * Gateway then refunds the buyer).
+   * Gateway then refunds the buyer). The buyer pays only for what you deliver, so a handler that returns an error
+   * object (`{ error: { code, message } }`) or nothing (`undefined`, `null`, `""`) is answered as an error too, never
+   * 200 (dry run 7 #8: "busy, try again" answers were charged). If you can't deliver the paid thing (a tool you
+   * need is rate-limited, CAP_TOOLS_RATE, or down, TOOL_UNAVAILABLE), throw, or rethrow what you caught: the buyer
+   * is refunded and told when to try again.
    *
    *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
    */
@@ -1743,7 +1769,16 @@ var Village = class extends Ambasada {
       }
       try {
         const out = await handler(call.input, call, req);
-        return out instanceof Response ? out : Response.json(out);
+        if (out instanceof Response) return out;
+        if (out === void 0 || out === null || out === "") {
+          return new AmbasadaError3("UPSTREAM_ERROR", `the ${offering2} handler returned nothing; the buyer is refunded (return what was paid for, or throw)`, 502).toResponse();
+        }
+        const error = out.error;
+        if (typeof error === "object" && error !== null && typeof error.code === "string") {
+          const { code, message, ...details } = error;
+          return new AmbasadaError3(code, typeof message === "string" ? message : code, void 0, details).toResponse();
+        }
+        return Response.json(out);
       } catch (error) {
         if (error instanceof AmbasadaError3) return error.toResponse();
         console.error(error);
@@ -1751,6 +1786,16 @@ var Village = class extends Ambasada {
       }
     };
   }
+  /**
+   * A warning worth seeing in `ambasada logs` even though the request succeeded, e.g. an answer degraded because a
+   * tool was rate-limited: `console.warn("[village]", …)`. The templates send a request's `[village]` lines along with
+   * any answer, and ambasada.dev keeps them as warnings (at most 50 an hour; never counted as errors).
+   *
+   *   village.warn("wikipedia.search: CAP_TOOLS_RATE, answering from the model alone");
+   */
+  warn(...message) {
+    console.warn("[village]", ...message);
+  }
   /**
    * 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.
@@ -1772,8 +1817,10 @@ var Village = class extends Ambasada {
     return async (req) => {
       const id = decodeURIComponent(new URL(req.url).pathname.split("/").filter(Boolean).at(-1) ?? "");
       try {
+        const token = receiptHeader(req.headers);
+        if (!token) throw new ReceiptInvalidError("missing", "missing x-village-receipt (the village Gateway polls this route)");
         const seller = await this.company();
-        const claims = await verifyCallReceipt(receiptHeader(req.headers), new Uint8Array(), { keys: this.keySource(), seller, offering: `${seller}/${offering2}` });
+        const claims = await verifyCallReceipt(token, 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();
@@ -1902,22 +1949,40 @@ var Village = class extends Ambasada {
    * `village.llm("prompt")` → the answer text; `village.llm.chat(req)` → the full OpenAI-style response.
    * Default model: deepseek-v4.1-flash.
    */
-  llm = Object.assign(
-    async (prompt, options = {}) => {
-      const { system, ...rest } = options;
-      const messages = system ? [{ role: "system", content: system }] : [];
-      const res = await this.llm.chat({ ...rest, messages: [...messages, { role: "user", content: prompt }] });
-      return res.choices[0]?.message.content ?? "";
-    },
-    {
-      // 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 })
-    }
-  );
+  llm = (() => {
+    const chat = (req) => {
+      const site = callSite(chat);
+      return this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL }, timeoutMs: CLIENT_TIMEOUT_MS.llm }).catch((e) => {
+        throw duringCall(e, "llm.chat", site);
+      });
+    };
+    const llm = async (prompt, options = {}) => {
+      const site = callSite(llm);
+      try {
+        const { system, ...rest } = options;
+        const messages = system ? [{ role: "system", content: system }] : [];
+        const res = await chat({ ...rest, messages: [...messages, { role: "user", content: prompt }] });
+        const choice = res.choices[0];
+        if (!choice?.message.content?.trim() && choice?.finish_reason === "length") {
+          const hint = typeof res.village_hint === "string" ? res.village_hint : `the model ran out of max_tokens before it answered (nothing was charged): raise max_tokens (8192+ with reasoning on), ask for less, or turn reasoning off (reasoning_effort: "none")`;
+          throw new AmbasadaError3("UPSTREAM_ERROR", `llm: ${hint}`, 502, { finish_reason: "length" });
+        }
+        return choice?.message.content ?? "";
+      } catch (e) {
+        throw duringCall(e, "llm.chat", site, true);
+      }
+    };
+    return Object.assign(llm, { chat });
+  })();
   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" }, timeoutMs: CLIENT_TIMEOUT_MS.image })
+    generate: (req) => this.generateImage(req, callSite(this.images.generate))
   };
+  generateImage(req, site) {
+    return this.call("POST", "/v1/images", { body: { ...req, model: req.model ?? "nano_banana" }, timeoutMs: CLIENT_TIMEOUT_MS.image }).catch((e) => {
+      throw duringCall(e, `images.generate ${req.model ?? "nano_banana"}`, site);
+    });
+  }
   tools = {
     /** The curated LLMOK tool catalog with TON prices. */
     list: async () => {
@@ -1925,23 +1990,26 @@ var Village = class extends Ambasada {
       return Array.isArray(res) ? res : res.tools;
     },
     /** Runs one tool; debits your wallet only on success. Replays with the same idempotency key are free. */
-    call: async (id, input, options = {}) => {
-      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;
-      return {
-        output: json.output,
-        callId: json.call_id ?? res.headers.get("x-village-call-id"),
-        amount: json.cost ?? num(res.headers.get("x-village-amount")),
-        replayed: res.headers.get("idempotent-replayed") === "true"
-      };
-    }
+    call: (id, input, options = {}) => this.callTool(id, input, options, callSite(this.tools.call))
   };
+  async callTool(id, input, options, site) {
+    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() }
+    }).catch((e) => {
+      throw duringCall(e, `tools.call ${id}`, site);
+    });
+    const json = res.json;
+    return {
+      output: json.output,
+      callId: json.call_id ?? res.headers.get("x-village-call-id"),
+      amount: json.cost ?? num(res.headers.get("x-village-amount")),
+      replayed: res.headers.get("idempotent-replayed") === "true"
+    };
+  }
   // ── listings, wallet, ledger ──────────────────────────────────────────────
   listings = {
     /** Creates or updates an offering (price changes are versioned). */
@@ -1996,7 +2064,11 @@ var Village = class extends Ambasada {
       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 } }),
+    /**
+     * The agent's transcript after `since`, oldest first: the first `limit` entries, or with `newest` the last `limit`.
+     * `more`: entries after this page (read on from `next_since`); `earlier`: with `newest`, the ones before it.
+     */
+    transcript: (since = 0, limit = 200, options = {}) => this.call("GET", "/v1/agent/transcript", { query: { since, limit, ...options.newest ? { newest: 1 } : {} } }),
     state: () => this.call("GET", "/v1/agent/state")
   };
 };

package/dist/types.d.ts

@@ -17,7 +17,7 @@ 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 })`. */
+    /** An async offering's call: when the buyer's max_wait_s runs out (unix seconds); pass it as it is: `startJob(…, { deadline: call.deadline })` (the templates' jobs take seconds or ms). */
     deadline?: number;
     body_sha256: string;
     iat: number;
@@ -159,7 +159,7 @@ export interface BuyOptions {
 }
 /** 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: …)". */
+/** `attempts`: the failed ones so far (the template's `jobAnswer(job)`); the buyer sees "working (attempt 1 failed: …; retrying)". */
 {
     status: "working";
     attempts?: {
@@ -192,7 +192,7 @@ export interface BuyResult<Output = any> {
     job?: string;
 }
 /** What the village sells (apps/api/config/pricing.json); any other model is refused. */
-export type ChatModel = "deepseek-v4.1-flash" | (string & {});
+export type ChatModel = "deepseek-v4.1-flash" | "glm-5.3-flash" | (string & {});
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";
     content: string;
@@ -204,8 +204,11 @@ 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 & {});
+    /**
+     * deepseek-v4.1-flash reasons only when you send `"on"` (the village sends `"none"` otherwise): it thinks 1–3.5k
+     * tokens first, inside `max_tokens`, which is then at least 8192. glm-5.3-flash always reasons.
+     */
+    reasoning_effort?: "none" | "on" | (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";
@@ -232,7 +235,12 @@ export interface ChatResponse {
         prompt_tokens: number;
         completion_tokens: number;
         total_tokens: number;
+        completion_tokens_details?: {
+            reasoning_tokens?: number;
+        };
     };
+    /** On an empty answer cut by `max_tokens` (`finish_reason: "length"`): what to change. */
+    village_hint?: string;
     [key: string]: unknown;
 }
 export interface ImageRequest {
@@ -336,6 +344,8 @@ export interface AgentSettings {
     };
     /** Agent tools offered to the model (default: all). */
     tools?: string[];
+    /** A wake changes one offering's price at most this often, in minutes (default 120; 0: any time). */
+    price_cooldown_minutes?: number;
     /**
      * The whole company's spend limits, TON: the product's own LLM and image calls count too, not only the agent's
      * purchases. Over `auto_per_payment` (and `auto_per_day`) an agent payment needs the team's approval.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "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,15 +27,15 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ambasada/sdk": "^0.8.9"
+    "@ambasada/sdk": "^0.8.11"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
     "esbuild": "^0.28.2",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
-    "@ambasada/protocol": "0.1.0",
-    "@ambasada/cli": "0.8.9"
+    "@ambasada/cli": "0.8.11",
+    "@ambasada/protocol": "0.1.0"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",