@ambasada/village 0.8.8 → 0.8.10

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 { 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";
+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;
@@ -157,6 +157,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 +166,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>;
@@ -206,11 +208,24 @@ 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>;
-        transcript: (since?: number, limit?: number) => Promise<{
+        /**
+         * 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>;
+        /**
+         * 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) {
@@ -1772,8 +1794,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 +1926,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 +1967,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). */
@@ -1988,9 +2033,19 @@ var Village = class extends Ambasada {
     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 } : {} } }),
-    transcript: (since = 0, limit = 200) => this.call("GET", "/v1/agent/transcript", { query: { since, limit } }),
+    /**
+     * 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 } : {}
+    }),
+    /**
+     * 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,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;
@@ -156,8 +158,14 @@ export interface BuyOptions {
     wait?: boolean;
 }
 /** What an async offering's `GET <endpoint>/jobs/<id>` says (village.jobStatus): the Gateway settles on done or failed. */
-export type JobAnswer = {
+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;
@@ -184,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;
@@ -196,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";
@@ -224,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 {
@@ -394,9 +410,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). */
+    /** 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.8",
+  "version": "0.8.10",
   "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.8"
+    "@ambasada/sdk": "^0.8.10"
   },
   "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.8"
+    "@ambasada/cli": "0.8.10"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",