@ambasada/village 0.8.3 → 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

@@ -152,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,
@@ -1841,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.3",
+  "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.3"
+    "@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.3"
+    "@ambasada/cli": "0.8.4"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",