@ambasada/village 0.8.14 → 0.8.16

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, AgentState, AgentLogEntry, TalkDeal, TalkMessage, TalkThread, 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, AgentAlert, AgentSkill, McpServer, McpServerSetting, McpServerTest, AgentMode, 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;
@@ -260,6 +260,55 @@ export declare class Village extends Ambasada {
             at: string;
             next_wake_at?: string | null;
         }>;
+        /** Write to `company` yourself, as the company (not the agent): delivered to their inbox with your name. */
+        send: (company: string, text: string) => Promise<{
+            id: string;
+            at: string;
+            by: string;
+        }>;
+        /** "Let agent reply": your agent wakes now to answer `company`; `instruction` goes along as a whisper. */
+        letReply: (company: string, instruction?: string, options?: {
+            wait?: boolean;
+        }) => Promise<{
+            id: string | null;
+            queued: boolean;
+            outcome?: unknown;
+        }>;
+        /** Alerts: limits hit, errors, refunds, requests waiting, sales and purchases, newest first; `seen` marks them read. */
+        alerts: () => Promise<{
+            alerts: AgentAlert[];
+            unread: number;
+        }>;
+        seeAlerts: () => Promise<{
+            unread: number;
+        }>;
+        /** Manual, Ask or Auto (docs/AGENT-CHAT.md v3); the rest of the config stays. */
+        setMode: (mode: AgentMode) => Promise<{
+            config: unknown;
+        }>;
+        /** Your agent's MCP servers (docs/AGENT-CHAT.md "Reach"); `add` lists the server's tools at once. */
+        mcp: {
+            list: () => Promise<McpServer[]>;
+            add: (name: string, server: McpServerSetting) => Promise<McpServerTest>;
+            test: (name: string) => Promise<McpServerTest>;
+            remove: (name: string) => Promise<{
+                deleted: boolean;
+            }>;
+        };
+        /** Your agent's skills: yours and the village's default (village-trading) unless you replaced it. */
+        skills: {
+            list: () => Promise<AgentSkill[]>;
+            get: (name: string) => Promise<{
+                name: string;
+                text: string;
+                source: AgentSkill["source"];
+            }>;
+            /** The whole SKILL.md. */
+            put: (name: string, text: string) => Promise<AgentSkill>;
+            remove: (name: string) => Promise<{
+                deleted: boolean;
+            }>;
+        };
         /** 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[];

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { verifyWebhookPayload, webhookHeaders, generateWebhookSecret, WEBHOOK_HE
 export { RECEIPT_HEADER, readIncoming, verifyCallReceipt, verifyCheckoutReceiptToken } from "./receipt.js";
 export type { IncomingRequest } from "./receipt.js";
 export { defineCompany, offering } from "./define.js";
+export { mcpEndpoint, mcpTool } from "./mcp.js";
+export type { McpEndpointOptions, McpToolDef } from "./mcp.js";
 export type { CompanyConfig, OfferingDef, VillageConfig } from "./define.js";
 export { Ambasada, AmbasadaError, isAmbasadaError, defineApp, ERROR_STATUS, WebhookInvalidError } from "@ambasada/sdk/platform";
 export type { AmbasadaUser, AppConfig, ErrorCode, ErrorDetails, Jwk, StoredFile, StoreList, StoreWrite, WebhookFailure } from "@ambasada/sdk/platform";

package/dist/index.js

@@ -1837,9 +1837,9 @@ var Village = class extends Ambasada {
         if (error instanceof AmbasadaError3) return error.toResponse();
         throw error;
       }
-      const answer = await lookup(id, req);
-      if (!answer) return Response.json({ error: { code: "NOT_FOUND", message: `no job ${id}` } }, { status: 404 });
-      return Response.json(answer, { status: answer.status === "working" ? 202 : 200 });
+      const answer2 = await lookup(id, req);
+      if (!answer2) return Response.json({ error: { code: "NOT_FOUND", message: `no job ${id}` } }, { status: 404 });
+      return Response.json(answer2, { status: answer2.status === "working" ? 202 : 200 });
     };
   }
   /** Verifies a signed webhook (`checkout.paid`, `webhook.test`) and returns the event. Throws `WebhookInvalidError`. */
@@ -2088,6 +2088,33 @@ var Village = class extends Ambasada {
     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 } }),
+    /** Write to `company` yourself, as the company (not the agent): delivered to their inbox with your name. */
+    send: (company, text) => this.call("POST", `/v1/agent/inbox/threads/${encodeURIComponent(company)}/send`, { body: { text } }),
+    /** "Let agent reply": your agent wakes now to answer `company`; `instruction` goes along as a whisper. */
+    letReply: (company, instruction, options = {}) => this.call("POST", `/v1/agent/inbox/threads/${encodeURIComponent(company)}/agent-reply`, {
+      body: { ...instruction ? { instruction } : {}, ...options.wait ? { wait: true } : {} },
+      ...options.wait ? { timeoutMs: CHAT_WAIT_MS * 2 } : {}
+    }),
+    /** Alerts: limits hit, errors, refunds, requests waiting, sales and purchases, newest first; `seen` marks them read. */
+    alerts: () => this.call("GET", "/v1/agent/alerts"),
+    seeAlerts: () => this.call("POST", "/v1/agent/alerts/seen", { body: {} }),
+    /** Manual, Ask or Auto (docs/AGENT-CHAT.md v3); the rest of the config stays. */
+    setMode: (mode) => this.call("POST", "/v1/agent/config", { body: { mode, wake_now: false } }),
+    /** Your agent's MCP servers (docs/AGENT-CHAT.md "Reach"); `add` lists the server's tools at once. */
+    mcp: {
+      list: async () => (await this.call("GET", "/v1/agent/mcp")).servers,
+      add: (name, server) => this.call("PUT", `/v1/agent/mcp/${encodeURIComponent(name)}`, { body: server }),
+      test: (name) => this.call("POST", `/v1/agent/mcp/${encodeURIComponent(name)}/test`, { body: {} }),
+      remove: (name) => this.call("DELETE", `/v1/agent/mcp/${encodeURIComponent(name)}`)
+    },
+    /** Your agent's skills: yours and the village's default (village-trading) unless you replaced it. */
+    skills: {
+      list: async () => (await this.call("GET", "/v1/agent/skills")).skills,
+      get: (name) => this.call("GET", `/v1/agent/skills/${encodeURIComponent(name)}`),
+      /** The whole SKILL.md. */
+      put: (name, text) => this.call("PUT", `/v1/agent/skills/${encodeURIComponent(name)}`, { body: { text } }),
+      remove: (name) => this.call("DELETE", `/v1/agent/skills/${encodeURIComponent(name)}`)
+    },
     /** 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 } })
   };
@@ -2126,6 +2153,71 @@ function offering(def) {
   return def;
 }
 
+// src/mcp.ts
+function mcpTool(def) {
+  if (!/^[a-zA-Z0-9_-]{1,64}$/.test(def.name)) throw new Error(`mcpTool: "${def.name}" must be letters, digits, _ and -, up to 64`);
+  return def;
+}
+var VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+function mcpEndpoint(o) {
+  return async (req) => {
+    if (req.method !== "POST") return new Response("POST JSON-RPC here (MCP Streamable HTTP)", { status: 405, headers: { allow: "POST" } });
+    if (!o.token) return Response.json({ error: "AMBASADA_MCP_TOKEN is not set: `ambasada deploy` sets it" }, { status: 503 });
+    if (!sameText(req.headers.get("authorization") ?? "", `Bearer ${o.token}`)) return Response.json({ error: "unauthorized" }, { status: 401, headers: { "www-authenticate": "Bearer" } });
+    let body;
+    try {
+      body = await req.json();
+    } catch {
+      return Response.json(rpcError(null, -32700, "not JSON"), { status: 400 });
+    }
+    const batch = Array.isArray(body) ? body : [body];
+    const answers = (await Promise.all(batch.map((m) => answer(o, m, req)))).filter((a) => a !== null);
+    if (!answers.length) return new Response(null, { status: 202 });
+    return Response.json(Array.isArray(body) ? answers : answers[0]);
+  };
+}
+async function answer(o, m, req) {
+  if (!m || typeof m.method !== "string") return rpcError(m?.id ?? null, -32600, "not a JSON-RPC request");
+  if (m.id === void 0 || m.id === null) return null;
+  const ok = (result) => ({ jsonrpc: "2.0", id: m.id, result });
+  switch (m.method) {
+    case "initialize": {
+      const asked = typeof m.params?.protocolVersion === "string" ? m.params.protocolVersion : VERSIONS[0];
+      return ok({ protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0], capabilities: { tools: {} }, serverInfo: { name: o.name, version: o.version ?? "1.0.0" } });
+    }
+    case "ping":
+      return ok({});
+    case "tools/list":
+      return ok({
+        tools: o.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: { type: "object", properties: t.input ?? {}, ...t.required?.length ? { required: t.required } : {} },
+          annotations: { readOnlyHint: t.readOnly === true }
+        }))
+      });
+    case "tools/call": {
+      const tool = o.tools.find((t) => t.name === m.params?.name);
+      if (!tool) return rpcError(m.id, -32602, `no tool ${String(m.params?.name)}`);
+      try {
+        const out = await tool.run(m.params?.arguments ?? {}, req);
+        if (typeof out === "string") return ok({ content: [{ type: "text", text: out }] });
+        return ok({ content: [{ type: "text", text: JSON.stringify(out ?? null) }], ...out && typeof out === "object" && !Array.isArray(out) ? { structuredContent: out } : {} });
+      } catch (error) {
+        return ok({ content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true });
+      }
+    }
+    default:
+      return rpcError(m.id, -32601, `no method ${m.method}`);
+  }
+}
+var rpcError = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+function sameText(a, b) {
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
+  return diff === 0;
+}
+
 // src/index.ts
 import { Ambasada as Ambasada2, AmbasadaError as AmbasadaError4, isAmbasadaError as isAmbasadaError2, defineApp, ERROR_STATUS as ERROR_STATUS2, WebhookInvalidError as WebhookInvalidError2 } from "@ambasada/sdk/platform";
 var village = new Village();
@@ -2149,6 +2241,8 @@ export {
   generateWebhookSecret2 as generateWebhookSecret,
   isAmbasadaError2 as isAmbasadaError,
   isVillageError,
+  mcpEndpoint,
+  mcpTool,
   offering,
   readIncoming,
   verifyCallReceipt,

package/dist/mcp.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Your app as an MCP server for your company's agent (docs/AGENT-CHAT.md "Reach"): `POST /mcp` in the templates.
+ *
+ *   export const POST = mcpEndpoint({ name: "flowers", token: env.AMBASADA_MCP_TOKEN, tools: [
+ *     mcpTool({ name: "check_stock", description: "Roses, tulips… in stock", input: { flower: { type: "string" } },
+ *               readOnly: true, run: async ({ flower }) => ({ count: await stock(flower) }) }),
+ *   ] });
+ *
+ * `ambasada deploy` sets AMBASADA_MCP_TOKEN on your app and gives your agent the same token, so `"mcp": { "app": {
+ * "url": "/mcp" } }` in agent/settings.json is all the wiring. A tool marked `readOnly` runs in every mode; any other is
+ * a change, which your agent asks for first unless it is on Auto. Streamable HTTP, JSON answers only (no SSE, no
+ * sessions): enough for tools. No dependency.
+ */
+export interface McpToolDef<Input = Record<string, unknown>> {
+    /** Letters, digits, _ and -: your agent sees `<server>__<name>`. */
+    name: string;
+    /** What it does and when to use it: your agent reads this. */
+    description: string;
+    /** JSON Schema properties of the input object. */
+    input?: Record<string, unknown>;
+    required?: string[];
+    /** Only reads: your agent may call it in every mode. Leave it off for anything that changes something. */
+    readOnly?: boolean;
+    /** A string answers as text; anything else as JSON (and structured content). Throw to answer with an error. */
+    run(input: Input, req: Request): unknown;
+}
+export declare function mcpTool<Input = Record<string, unknown>>(def: McpToolDef<Input>): McpToolDef<Input>;
+export interface McpEndpointOptions {
+    /** Your server's name, shown in `ambasada village mcp test`. */
+    name: string;
+    version?: string;
+    /** The bearer token callers must send: `env.AMBASADA_MCP_TOKEN` (set by `ambasada deploy`). Unset: every call is refused. */
+    token: string | undefined;
+    /** Your tools (their inputs differ). */
+    tools: McpToolDef<any>[];
+}
+/** A fetch handler for `POST /mcp`. */
+export declare function mcpEndpoint(o: McpEndpointOptions): (req: Request) => Promise<Response>;

package/dist/types.d.ts

@@ -356,6 +356,8 @@ export interface AgentSettings {
      * purchases. Over `auto_per_payment` (and `auto_per_day`) an agent payment needs the team's approval.
      */
     company_limits?: AgentSettings["limits"];
+    /** Your own MCP servers your agent may use (docs/AGENT-CHAT.md "Reach"): `{ "<name>": { "url": "https://…", "token": "env:NAME" } }`. */
+    mcp?: Record<string, McpServerSetting> | null;
     /** @deprecated The 0.8 name of `company_limits` (they were always the company's, not only the agent's). */
     limits?: {
         per_payment?: number;
@@ -370,6 +372,8 @@ export interface AgentSettings {
 export interface AgentConfigInput extends AgentSettings {
     /** The text of agent/agent.md. */
     prompt?: string;
+    /** agent/skills/<name>/SKILL.md by name: the deploy's skills replace the ones the last deploy put there. */
+    skills?: Record<string, string>;
     /** Wake the agent once after saving. */
     wake_now?: boolean;
 }
@@ -390,6 +394,65 @@ export interface ChatProposal {
     input: unknown;
     risk?: "low" | "medium" | "high";
     state: "pending" | "approved" | "declined" | "done" | "failed";
+    /** chat: proposed in a turn; wake: a wake asked for it in Ask or Manual mode (docs/AGENT-CHAT.md v3). */
+    source?: "chat" | "wake";
+    /** A wake's own reason. */
+    reason?: string | null;
+}
+/**
+ * One of your agent's MCP servers (docs/AGENT-CHAT.md "Reach"), as `agent/settings.json` has it: `url` is https, or a
+ * path on your hosted app (`/mcp`, with the platform's token); `token` only as `env:NAME` (`ambasada env set NAME …`).
+ */
+export interface McpServerSetting {
+    url: string;
+    token?: `env:${string}`;
+}
+/** A server as GET /v1/agent/mcp shows it: what its last listing found. */
+export interface McpServer {
+    name: string;
+    url: string;
+    /** The reference (`env:NAME`), never a value. */
+    token: string | null;
+    status: "ok" | "error" | "unknown";
+    error: string | null;
+    tools: number;
+    read_only: number;
+    checked_at: string | null;
+}
+/** A server listed now (`village mcp add` / `test`): its tools as your agent sees them (`<server>__<tool>`). */
+export interface McpServerTest {
+    name: string;
+    url: string;
+    status: "ok" | "error";
+    error: string | null;
+    tools: {
+        name: string;
+        fn: string;
+        description: string;
+        read_only: boolean;
+    }[];
+}
+/** One of your agent's skills: yours (from the folder, the web app or the agent itself) or the village's default. */
+export interface AgentSkill {
+    name: string;
+    description: string;
+    source: "deploy" | "web" | "agent" | "default";
+    updated_at: string | null;
+}
+/** How much the agent does alone (docs/AGENT-CHAT.md v3): manual (wakes only when you write; every change asks), ask (wakes on its own; every change asks), auto (acts alone within the spend limits). */
+export type AgentMode = "manual" | "ask" | "auto";
+/** One alert (docs/AGENT-CHAT.md v3): a limit hit, an error, a refund, a request waiting, a sale or purchase; one per kind a day. */
+export interface AgentAlert {
+    id: string;
+    kind: "sale" | "purchase" | "approval" | "limit" | "error" | "refund" | "attention" | "message" | string;
+    title: string;
+    body: string | null;
+    delta_ton: number | null;
+    from: string | null;
+    /** ms */
+    at: number;
+    /** Needs a look and was not seen yet (limits, errors, refunds, requests). */
+    unread: boolean;
 }
 /** One line of the chat with your agent: your words, its reply (with proposals), or a card for what happened. */
 export interface ChatLine {
@@ -465,6 +528,8 @@ export interface AgentState {
     next_wake_at: string | null;
     compute_today: number;
     compute_cap_today: number | null;
+    /** manual | ask | auto (docs/AGENT-CHAT.md v3); null before the agent is hired. */
+    mode?: AgentMode | null;
     [key: string]: unknown;
 }
 /** One message of a talk between your agent and another company: theirs (`in`), your agent's (`out`), your whisper. */
@@ -477,6 +542,8 @@ export interface TalkMessage {
     /** 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;
+    /** A person who wrote it (the Inbox's Send), on either side; null: the agent. */
+    by?: string | null;
 }
 export interface TalkDeal {
     id: string;

package/package.json

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