@ambasada/village 0.8.2 → 0.8.4

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, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, ChatLine, ChatProposal, ChatTurn, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
 /** 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";
@@ -136,8 +136,25 @@ export declare class Village extends Ambasada {
             config: unknown;
             limits?: unknown;
         }>;
-        /** A message the agent answers on its next wake. */
+        /** A message from the team: the agent answers in the chat now, and reads it on its next wake. */
         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.
+         */
+        chat: (text: string, options?: {
+            idempotencyKey?: string;
+            wait?: boolean;
+        }) => Promise<ChatTurn>;
+        /** The chat, oldest first: your words, the agent's replies and proposals, and cards for what happened. */
+        messages: (options?: {
+            since?: number;
+            limit?: number;
+        }) => 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<{
             entries: TranscriptEntry[];
             next_since: number;

package/dist/index.js

@@ -85,6 +85,7 @@ __export(src_exports, {
   parseCheckpoint: () => parseCheckpoint,
   parseVerifierKey: () => parseVerifierKey,
   pngInfo: () => pngInfo,
+  probeManifest: () => probeManifest,
   publicJwkOf: () => publicJwkOf,
   randomId: () => randomId,
   rootFromLeafHashes: () => rootFromLeafHashes,
@@ -151,6 +152,8 @@ var ERROR_STATUS = {
   BUDGET_EXCEEDED: 402,
   CAP_INBOX_RATE: 429,
   // 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)
   // Additions needed by the gateway and bank
   UPSTREAM_ERROR: 502,
   PRICE_ABOVE_MAX: 409,
@@ -1266,6 +1269,34 @@ var USER_AGENT = "ambasada-check/1 (+https://ambasada.id)";
 async function get(fetchImpl, url) {
   return fetchImpl(url, { redirect: "manual", signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers: { "user-agent": USER_AGENT, accept: "*/*" } });
 }
+async function probeManifest(origin, fetchImpl = fetch) {
+  try {
+    const res = await get(fetchImpl, new URL(MANIFEST_URL_PATH, origin).toString());
+    if (res.status !== 200) {
+      await res.body?.cancel();
+      return { on: false, entry: null };
+    }
+    const m = JSON.parse(await res.text());
+    if (!m || typeof m !== "object" || m.schema !== MANIFEST_SCHEMA && m.schema !== 1) return { on: false, entry: null };
+    return { on: true, entry: typeof m.entry === "string" && m.entry.startsWith("/") ? m.entry : "/" };
+  } catch {
+    return { on: false, entry: null };
+  }
+}
+async function checkPage(fetchImpl, url, report, html) {
+  try {
+    const started = Date.now();
+    const res = await get(fetchImpl, url);
+    const text = res.status === 200 && html ? await res.text() : "";
+    if (!html) await res.body?.cancel();
+    const ms = Date.now() - started;
+    if (res.status !== 200) report.problems.push({ code: "entry_status", message: `${url} answered ${res.status}${res.headers.get("location") ? ` \u2192 ${res.headers.get("location")}` : ""}; ${html ? "the entry" : "the app"} must answer 200 without redirects` });
+    else if (html) merge(report, checkHtml(text));
+    if (ms > SLOW_ENTRY_MS) report.warnings.push({ code: "slow_entry", message: `${url} took ${ms} ms; aim for under ${SLOW_ENTRY_MS} ms${html ? " (the splash stays until ready())" : ""}` });
+  } catch (error) {
+    report.problems.push({ code: "entry_fetch", message: `could not fetch ${url}: ${error.message}` });
+  }
+}
 async function checkRemote(url, fetchImpl = fetch, options = {}) {
   const report = { ok: true, target: url, problems: [], warnings: [], notes: [] };
   let origin;
@@ -1279,8 +1310,23 @@ async function checkRemote(url, fetchImpl = fetch, options = {}) {
   if (origin.protocol !== "https:") report.problems.push({ code: "not_https", message: "the app must be served over https" });
   let manifest = null;
   const manifestUrl = new URL(MANIFEST_URL_PATH, origin).toString();
+  if (options.miniapp === false) {
+    report.miniapp = { on: false, entry: null };
+    report.notes.push("mini app: off");
+    await checkPage(fetchImpl, new URL("/", origin).toString(), report, false);
+    report.ok = report.problems.length === 0;
+    return report;
+  }
   try {
     let res = await get(fetchImpl, manifestUrl);
+    if (res.status === 404 && options.miniapp === void 0) {
+      await res.body?.cancel();
+      report.miniapp = { on: false, entry: null };
+      report.notes.push(`mini app: off (no ${MANIFEST_URL_PATH})`);
+      await checkPage(fetchImpl, new URL("/", origin).toString(), report, false);
+      report.ok = report.problems.length === 0;
+      return report;
+    }
     if (res.status >= 300 && res.status < 400) {
       const location = res.headers.get("location") ?? "";
       if (res.status === 307 && HOSTED_MANIFEST.test(location)) {
@@ -1302,18 +1348,8 @@ async function checkRemote(url, fetchImpl = fetch, options = {}) {
     report.problems.push({ code: "manifest_fetch", message: `could not fetch ${manifestUrl}: ${error.message}` });
   }
   const entryPath = typeof manifest?.entry === "string" && manifest.entry.startsWith("/") ? manifest.entry : "/";
-  const entryUrl = new URL(entryPath, origin).toString();
-  try {
-    const started = Date.now();
-    const res = await get(fetchImpl, entryUrl);
-    const html = res.status === 200 ? await res.text() : "";
-    const ms = Date.now() - started;
-    if (res.status !== 200) report.problems.push({ code: "entry_status", message: `${entryUrl} answered ${res.status}${res.headers.get("location") ? ` \u2192 ${res.headers.get("location")}` : ""}; the entry must answer 200 without redirects` });
-    else merge(report, checkHtml(html));
-    if (ms > SLOW_ENTRY_MS) report.warnings.push({ code: "slow_entry", message: `${entryUrl} took ${ms} ms; the splash stays until ready(), aim for under ${SLOW_ENTRY_MS} ms` });
-  } catch (error) {
-    report.problems.push({ code: "entry_fetch", message: `could not fetch ${entryUrl}: ${error.message}` });
-  }
+  report.miniapp = { on: true, entry: entryPath };
+  await checkPage(fetchImpl, new URL(entryPath, origin).toString(), report, true);
   if (typeof manifest?.icon === "string" && manifest.icon) {
     const iconUrl = new URL(manifest.icon, origin).toString();
     try {
@@ -1381,9 +1417,11 @@ function summarizeCheck(report, now = /* @__PURE__ */ new Date()) {
     ...report.warnings.map((w) => ({ ...w, level: "warning", label: findingLabel(w.code) }))
   ];
   const needs = [...new Set(issues.filter((i) => i.level === "problem").map((i) => i.label))];
-  return { ok: report.ok, issues, needs, checked_at: now.toISOString() };
+  const miniapp = report.miniapp ? { miniapp: report.miniapp.on ? "on" : "off", entry: report.miniapp.entry } : {};
+  return { ok: report.ok, issues, needs, checked_at: now.toISOString(), ...miniapp };
 }
 function listingLine(tier, check) {
+  if (check?.miniapp === "off") return "Mini app: off";
   if (tier === "verified") return "Verified";
   if (tier === "listed") return "Listed for the event";
   if (tier === "unlisted") return check?.needs.length ? `Unlisted \xB7 needs: ${check.needs.join(", ")}` : "Unlisted";
@@ -1805,8 +1843,19 @@ var Village = class extends Ambasada {
   agent = {
     /** Replaces the agent's prompt (`agent.md`) and settings (`settings.json`). */
     config: (config) => this.call("POST", "/v1/agent/config", { body: config }),
-    /** A message the agent answers on its next wake. */
+    /** A message from the team: the agent answers in the chat now, and reads it on its next wake. */
     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.
+     */
+    chat: (text, options = {}) => this.call("POST", "/v1/agent/chat/turn", { body: { text, wait: options.wait ?? true, idempotency_key: options.idempotencyKey ?? randomKey() } }),
+    /** 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 } : {} } }),
     transcript: (since = 0, limit = 200) => this.call("GET", "/v1/agent/transcript", { query: { since, limit } }),
     state: () => this.call("GET", "/v1/agent/state")
   };

package/dist/types.d.ts

@@ -296,6 +296,45 @@ export interface TranscriptEntry {
     data?: unknown;
     [key: string]: unknown;
 }
+/** Something the agent wants to do, waiting for the team in the chat (docs/AGENT-CHAT.md). */
+export interface ChatProposal {
+    /** What `agent.decide(id, …)` takes. */
+    id: string;
+    tool: string;
+    /** One plain sentence: "Change the price of translate to 1.2 TON". */
+    text: string;
+    input: unknown;
+    risk?: "low" | "medium" | "high";
+    state: "pending" | "approved" | "declined" | "done" | "failed";
+}
+/** One line of the chat with your agent: your words, its reply (with proposals), or a card for what happened. */
+export interface ChatLine {
+    id: string;
+    role: "user" | "agent" | "card" | "village";
+    at: number | null;
+    text: string;
+    card?: {
+        id: string;
+        kind: string;
+        title: string;
+        body?: string | null;
+        delta_ton?: number | null;
+        from?: string | null;
+        at: number;
+    };
+    proposals?: ChatProposal[];
+    cost_ton?: number;
+}
+export interface ChatTurn {
+    submission_id: string;
+    message_id: string;
+    /** false when this idempotency key was already sent: the same turn, not a new one. */
+    accepted: boolean;
+    /** With `wait`: how the turn ended and the agent's reply. */
+    status?: "completed" | "error" | "aborted" | "skipped" | "pending" | "running";
+    error?: string;
+    reply?: ChatLine | null;
+}
 export interface MarketOffering {
     id: string;
     company?: string;

package/package.json

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