@ambasada/village 0.8.10 → 0.8.12

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, ChatDecision, 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, AgentState, AgentLogEntry, TalkDeal, TalkMessage, TalkThread, 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;
@@ -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.
@@ -227,7 +239,35 @@ export declare class Village extends Ambasada {
             more?: number;
             earlier?: number;
         }>;
-        state: () => Promise<Record<string, unknown>>;
+        /** How the agent is doing: its own status sentence and needs, why it last woke, the next wake, today's thinking. */
+        state: () => Promise<AgentState>;
+        /** The Inbox: one thread per company your agent talks with, newest first, with your unread counts. */
+        inbox: () => Promise<{
+            threads: TalkThread[];
+            unread: number;
+        }>;
+        /** One talk, both directions, oldest first, and the deals between you; reading it clears its unread count. */
+        thread: (company: string) => Promise<{
+            company: string;
+            name: string;
+            messages: TalkMessage[];
+            deals: TalkDeal[];
+            unread: number;
+        }>;
+        /** A word to your own agent about its talk with `company`, read on its next wake; never sent to them. */
+        whisper: (company: string, text: string) => Promise<{
+            id: string;
+            at: string;
+            next_wake_at?: string | null;
+        }>;
+        /** The Log: every wake with its transcript, steer, whispers, settings and approved proposals; 50 a page, newest first. */
+        log: (page?: number, kind?: "all" | "wakes" | "money" | "talks" | "issues") => Promise<{
+            entries: AgentLogEntry[];
+            page: number;
+            pages: number;
+            total: number;
+            per_page: number;
+        }>;
     };
 }
 export declare function createVillage(options?: VillageOptions): Village;

package/dist/index.js

@@ -13,6 +13,7 @@ __export(src_exports, {
   APP_TIMESTAMP_HEADER: () => APP_TIMESTAMP_HEADER,
   APP_WEBHOOK_TOLERANCE_S: () => APP_WEBHOOK_TOLERANCE_S,
   ASYNC_OFFERING: () => ASYNC_OFFERING,
+  AUTH_SHELL_PATH: () => AUTH_SHELL_PATH,
   AppWebhookError: () => AppWebhookError,
   DEFAULT_HUB_URL: () => DEFAULT_HUB_URL,
   DEFAULT_ISSUER: () => DEFAULT_ISSUER,
@@ -1137,6 +1138,7 @@ function appNotifyResult(json) {
 
 // ../protocol/src/check.ts
 var MANIFEST_URL_PATH = "/.well-known/ambasada.json";
+var AUTH_SHELL_PATH = "/api/auth/shell";
 var MANIFEST_SCHEMA = 2;
 var MANIFEST_KINDS = ["product", "event", "tool", "assistant"];
 var MANIFEST_CATEGORIES = ["shopping", "food", "events", "tools", "learning", "community", "games", "finance", "other"];
@@ -1400,6 +1402,15 @@ async function checkRemote(url, fetchImpl = fetch, options = {}) {
       report.problems.push({ code: "identity_callback", message: `could not fetch ${callbackUrl}: ${error.message}` });
     }
   }
+  if (scopes.includes("identity")) {
+    const shellUrl = new URL(AUTH_SHELL_PATH, origin).toString();
+    try {
+      const res = await get(fetchImpl, shellUrl);
+      await res.body?.cancel();
+      if (res.status === 404) report.warnings.push({ code: "identity_shell", message: `the identity scope signs people in on open through ${AUTH_SHELL_PATH} (auth.shell(req) from @ambasada/sdk); ${shellUrl} answered 404, so inside the Ambasada app they get "Sign in with Ambasada" instead` });
+    } catch {
+    }
+  }
   const webhook = manifest?.notifications && typeof manifest.notifications === "object" ? manifest.notifications.webhook : void 0;
   if (scopes.includes("notifications") && typeof webhook === "string" && webhook) {
     const webhookUrl = new URL(webhook, origin);
@@ -1435,7 +1446,7 @@ var LABELS = [
   [/^entry_|^not_https$|^bad_url$/, "entry page"],
   [/^privacy_url$/, "privacy page"],
   [/^notifications_webhook$|^webhook_/, "webhook"],
-  [/^identity_callback$/, "sign-in"]
+  [/^identity_(callback|shell)$/, "sign-in"]
 ];
 function findingLabel(code) {
   return LABELS.find(([re]) => re.test(code))?.[1] ?? code.replace(/_/g, " ");
@@ -1749,7 +1760,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(`…`) }));
    */
@@ -1765,7 +1780,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);
@@ -1773,6 +1797,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.
@@ -2046,7 +2080,16 @@ var Village = class extends Ambasada {
      * `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")
+    /** How the agent is doing: its own status sentence and needs, why it last woke, the next wake, today's thinking. */
+    state: () => this.call("GET", "/v1/agent/state"),
+    /** The Inbox: one thread per company your agent talks with, newest first, with your unread counts. */
+    inbox: () => this.call("GET", "/v1/agent/inbox/threads"),
+    /** One talk, both directions, oldest first, and the deals between you; reading it clears its unread count. */
+    thread: (company) => this.call("GET", `/v1/agent/inbox/threads/${encodeURIComponent(company)}`),
+    /** A word to your own agent about its talk with `company`, read on its next wake; never sent to them. */
+    whisper: (company, text) => this.call("POST", "/v1/agent/whisper", { body: { company, text } }),
+    /** The Log: every wake with its transcript, steer, whispers, settings and approved proposals; 50 a page, newest first. */
+    log: (page = 1, kind = "all") => this.call("GET", "/v1/agent/log", { query: { page, kind } })
   };
 };
 function createVillage(options = {}) {

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?: {
@@ -332,9 +332,14 @@ export interface TransferOptions {
 export interface AgentSettings {
     model?: "deepseek-v4.1-flash";
     enabled?: boolean;
+    /**
+     * strategy_hours: a scheduled wake with nothing new (no message, sale, answer, finished purchase or rival move) costs
+     * nothing and runs no model, except once this many hours after the last wake that thought (default 6).
+     */
     wake?: {
         interval_minutes?: number;
         min_event_gap_seconds?: number;
+        strategy_hours?: number;
     };
     budget?: {
         tool_calls_per_wake?: number;
@@ -344,6 +349,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.
@@ -427,6 +434,94 @@ export interface ChatDecision {
     /** With `wait`: the agent's next line (its reply, or the "no reply" card), null when a minute went by. */
     follow_up?: ChatLine | null;
 }
+/** `agent.state()`: how the agent is doing (docs/AGENT-CHAT.md v2, the app's status card). */
+export interface AgentState {
+    configured: boolean;
+    enabled: boolean;
+    /** asleep | working */
+    status: string;
+    /** The agent's own sentence on where things stand (it sets it at the end of every wake that ran), and what it needs. */
+    status_text?: string | null;
+    status_set_at?: string | null;
+    needs?: {
+        kind: "offering" | "approval" | "limit" | "deploy";
+        label: string;
+    }[];
+    woke_last_because?: string | null;
+    /** The free checks since the last wake found nothing new: no model ran, nothing was charged. */
+    idle?: {
+        nothing_new_since: string | null;
+        checked_at: string | null;
+        next_check_at: string | null;
+    } | null;
+    last_wake?: {
+        id: string;
+        at: string;
+        ended_at: string | null;
+        stop: string | null;
+        summary: string | null;
+        woke_because?: string | null;
+    } | null;
+    next_wake_at: string | null;
+    compute_today: number;
+    compute_cap_today: number | null;
+    [key: string]: unknown;
+}
+/** One message of a talk between your agent and another company: theirs (`in`), your agent's (`out`), your whisper. */
+export interface TalkMessage {
+    id: string;
+    at: string;
+    direction: "in" | "out" | "whisper";
+    type: string;
+    text: string | null;
+    /** One plain line: the text, or "quotes 2.5 TON per call for pixelpal/stickers, up to 20 a day". */
+    summary: string;
+    ref: string | null;
+}
+export interface TalkDeal {
+    id: string;
+    offering: string;
+    price: number;
+    status: string;
+    role: "buyer" | "seller";
+    qty_cap: number;
+    used: number;
+    valid_until: string;
+    created_at: string;
+}
+/** A row of the Inbox: one company your agent talks with. */
+export interface TalkThread {
+    company: string;
+    name: string;
+    last: TalkMessage;
+    unread: number;
+    messages: number;
+    deal: TalkDeal | null;
+}
+/** One entry of the agent's Log: a wake (with its transcript as `steps`), steer, a whisper, settings, a proposal. */
+export interface AgentLogEntry {
+    id: string;
+    at: string;
+    type: "wake" | "steer" | "whisper" | "config" | "proposal";
+    kinds: ("wakes" | "money" | "talks" | "issues")[];
+    title: string;
+    summary: string | null;
+    cost_ton: number | null;
+    wake?: {
+        id: string;
+        reason: string;
+        woke_because: string | null;
+        stop: string | null;
+        ended_at: string | null;
+        tool_calls: number | null;
+    };
+    steps?: {
+        seq: number;
+        at: string;
+        kind: string;
+        [key: string]: unknown;
+    }[];
+}
 export interface MarketOffering {
     id: string;
     company?: string;

package/package.json

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