@vatio-ai/cli 0.47.0 → 0.48.0

package/README.md

@@ -1,44 +1,87 @@
 # @vatio-ai/cli
 
-The CLI for [Vatio](https://vatio.ai) — deploy and manage AI agent workspaces.
+The CLI for [Vatio](https://vatio.ai) — a production runtime for
+customer-facing AI agents. Describe an agent in one `vatio.yml` and deploy it to
+web chat, WhatsApp and Instagram; Vatio runs the conversation, the contacts, the
+identity, the safeguards and the handoff to a human.
 
 ```bash
 npx @vatio-ai/cli init my-agent
 npx @vatio-ai/cli push
 ```
 
-No runtime to install first: if you have Node, you have this.
+No runtime to install first: if you have Node 20 or newer, you have this.
 
 The package is `@vatio-ai/cli`; the command it installs is `vatio`. So
 `npm install -g @vatio-ai/cli` gives you `vatio push`, and `npx @vatio-ai/cli push`
 is the same thing without installing anything.
 
+## If you are a coding agent
+
+```bash
+vatio mcp     # MCP over stdio
+vatio docs    # the whole developer contract as markdown, live from Vatio
+```
+
+`vatio mcp` is the short path: it hands you the contract and the deploy commands
+over MCP, with no browser step. Failing that, `vatio docs` prints the same
+contract that [docs.vatio.ai/docs.md](https://docs.vatio.ai/docs.md) serves, and
+`vatio docs --save` writes it next to the workspace.
+
+Don't guess `vatio.yml` keys. Unknown root keys fail validation, and the rules
+that judge a workspace live on the server — so the printed contract is the
+current one by construction.
+
 ## What a workspace is
 
-A directory with a `vatio.yml` in it. That file says which Vatio workspace the
-directory deploys to, what the agent does, and how the widget looks; `tools/`,
-`lib/` and `auth/` next to it are plain JavaScript the agent runs.
+A directory with a `vatio.yml` in it:
+
+```text
+support-agent/
+  vatio.yml          # required: the agent, its tools, its knowledge
+  tools/*.yml        # one HTTP request each, described in YAML
+  identity.pub       # public key that verifies the JWT saying who a visitor is
+```
 
-Nothing constrains where that directory lives — an agent can sit inside the
-repository of the backend it calls, and every command except `init` finds it by
-walking up from the current directory. There is no `--workspace` flag.
+Only create the files you need. Nothing constrains where that directory lives —
+an agent can sit inside the repository of the backend it calls, and every
+command except `init` finds it by walking up from the current directory. There
+is no `--workspace` flag.
 
 ## Commands
 
 ```
-init [SLUG] [--name NAME]   Create vatio.yml here, and the remote to match
-login [--base-url URL]      Authorize this machine in a browser
+init [SLUG]                 Create vatio.yml here, and the remote to match
+login | logout              Authorize this machine in a browser, or forget it
+doctor                      Node, config, workspace and token status
+
 push [--env NAME]           Validate the workspace, then update a preview
-publish [--env NAME]        Promote a preview to live
+publish [--env NAME]        Promote the latest push to live, or the named preview
 diff [--env NAME]           What this directory would change
 status                      Preview and live deployment state
 rollback                    Restore the previous live deployment
 tools check                 Validate the workspace against Vatio's contracts
-secrets list|set|rm         Credentials your tools read as ctx.env
-tokens list|create|revoke   Publishable tokens for the widget and the SDK
-widget [--env NAME]         What the platform enforces, and the tokens there are
-config show|set|unset       base_url and token, per developer
-doctor                      Node, config, workspace and token status
+
+chat "message" [--env NAME] Talk to your own agent; the token is the identity
+chat transcript|debug|reset|destroy
+chat show CHAT_ID [--json]  Any chat in the workspace, with its deployment and tool calls
+
+kb list|show|create|rm       Knowledge bases
+kb write|cat|rm-entry        Entries, from a file or stdin
+kb follow|unfollow|refresh   Read a site into a base, nightly
+
+secrets list|set|rm          Credentials your tools read
+tokens list|create|revoke    Publishable tokens for the widget and the SDK
+widget [--env NAME]          What the platform enforces, and the tokens there are
+auth --new-key               Keypair that signs the visitor's JWT
+
+whatsapp ...                 Shared preview number, or your own business number
+instagram ...                Shared sandbox, or your own account
+
+docs [--save [PATH]]         The whole developer contract
+mcp                          Speak MCP over stdio, for a coding agent
+issue "what should change"   Send a change request, workspace attached
+config show|set|unset        base_url and token, per developer
 ```
 
 `--env NAME` targets a deployment: `live`, `preview`, or a named preview like

package/lib/commands/chat.mjs

@@ -10,11 +10,11 @@ import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { ApiClient } from "../api-client.mjs";
-import { fail, sleep, takeEnv, takeValue } from "../support.mjs";
+import { fail, sleep, takeEnv, takeFlag, takeValue } from "../support.mjs";
 
 export const STATE_FILE = ".vatio-chat.json";
 
-const SUBCOMMANDS = new Set(["transcript", "debug", "reset", "destroy", "delete", "help"]);
+const SUBCOMMANDS = new Set(["show", "transcript", "debug", "reset", "destroy", "delete", "help"]);
 const REMOVED_FLAGS = ["--channel", "--from", "--as", "--sandbox-url"];
 
 export async function chat(config, args) {
@@ -30,14 +30,17 @@ export async function chat(config, args) {
 
   const environment = takeEnv(args, { fallback: "preview" });
   const timeout = Number(takeValue(args, "--timeout") ?? 120);
-  const last = Number(takeValue(args, "--last") ?? 10);
+  const lastValue = takeValue(args, "--last");
+  const last = Number(lastValue ?? 10);
+  const json = takeFlag(args, "--json");
   const apiUrl = takeValue(args, "--api-url");
   const token = takeValue(args, "--token");
 
-  const options = { environment, timeout, last, apiUrl, token };
+  const options = { environment, timeout, last, lastGiven: lastValue != null, json, apiUrl, token };
   const sub = SUBCOMMANDS.has(args[0]) ? args.shift() : null;
 
   if (sub === "help") return console.log(chatHelp());
+  if (sub === "show") return await showChat(config, options, args);
   if (sub === "transcript") return await transcript(config, options);
   if (sub === "debug") return await debugChat(config, options);
   if (sub === "reset") return await resetChat(config, options);
@@ -54,6 +57,7 @@ function chatHelp() {
   vatio chat "message" [--env NAME] [--timeout N]
   vatio chat transcript [--last N]
   vatio chat debug [--last N]
+  vatio chat show CHAT_ID [--last N] [--json]
   vatio chat reset
   vatio chat destroy CHAT_ID
 
@@ -61,6 +65,10 @@ function chatHelp() {
 name like pr-42. A chat against live is a real conversation and shows up in
 your inbox.
 
+\`show\` reads any chat in the workspace by id -- one a visitor had on the web,
+WhatsApp or Instagram, not only yours -- with the environment and deployment
+that answered it, and every tool call.
+
 The open chat per deployment is remembered in ${STATE_FILE}, so a second
 \`vatio chat\` continues the first. \`reset\` starts over as a visitor the
 workspace has never met.`;
@@ -200,6 +208,66 @@ async function debugChat(config, options) {
   }
 }
 
+// Every message, not the first page: a chat worth reading by id is usually one
+// that went wrong somewhere in the middle.
+async function allMessages(api, chatId) {
+  const messages = [];
+  let after = null;
+  for (;;) {
+    const payload = await api.chatMessages({ chatId, after, limit: 200 });
+    const page = Array.isArray(payload.data) ? payload.data : [];
+    messages.push(...page);
+    if (page.length < 200) return messages;
+    after = page[page.length - 1].id;
+  }
+}
+
+async function showChat(config, options, args) {
+  const chatId = args.shift();
+  if (!chatId || !/^\d+$/.test(chatId)) fail("Usage: vatio chat show CHAT_ID [--last N] [--json]");
+
+  const api = client(config, options);
+  const chat = await api.showChat({ chatId });
+  let messages = await allMessages(api, chatId);
+  if (options.lastGiven) messages = messages.slice(-options.last);
+
+  if (options.json) return console.log(JSON.stringify({ chat, messages }, null, 2));
+
+  const header = [
+    `Chat ${chat.chat_id}`,
+    chat.channel,
+    chat.environment,
+    chat.deployment_id && `deployment #${chat.deployment_id}`,
+    `agent ${chat.agent_slug}`
+  ];
+  console.log(header.filter(Boolean).join(" · "));
+  console.log(`Started ${chat.created_at}, last activity ${chat.updated_at}`);
+  if (chat.identity) console.log(`Identity: ${JSON.stringify(chat.identity)}`);
+  console.log("");
+
+  for (const message of messages) {
+    const content = String(message.content ?? "").trim();
+    if (message.role === "system") {
+      console.log(`[system] ${content.length} characters of prompt (--json prints it)`);
+      continue;
+    }
+    if (message.role === "tool") {
+      console.log(`  [tool result] ${truncate(content, 400)}`);
+      continue;
+    }
+    const flags = message.discarded ? " (discarded)" : "";
+    if (content !== "" || flags) console.log(`[${message.role}]${flags} ${content}`);
+    for (const call of Array.isArray(message.tool_calls) ? message.tool_calls : []) {
+      console.log(`  -> ${call.name}(${truncate(JSON.stringify(call.arguments ?? {}), 400)})`);
+    }
+  }
+  if (messages.length === 0) console.log("(no messages)");
+}
+
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
 async function resetChat(config, options) {
   const apiUrl = config.resolveApiUrl({ explicit: options.apiUrl });
   const payload = await openChat(config, options, {

package/lib/commands/deploy.mjs

@@ -145,14 +145,17 @@ export async function push(config, args) {
 
 export async function publish(config, args) {
   // Here `--env` names the preview being promoted, not a destination: the
-  // destination of a publish is always live.
+  // destination of a publish is always live. Without it the platform promotes
+  // the most recent push, whichever preview it landed on.
   const environment = takeEnv(args, { fallback: null });
   const workspace = config.resolveWorkspaceRequired();
   const payload = await deployClient(config, workspace).publish({
     createdBy: process.env.USER ?? null,
     environment
   });
-  console.log(`Published live deployment #${payload.deployment_id} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
+  const from = asArray(payload.published_from);
+  const source = from.length > 0 ? ` from ${from.join(", ")}` : "";
+  console.log(`Published live deployment #${payload.deployment_id}${source} (git_sha=${JSON.stringify(payload.git_sha ?? null)})`);
 }
 
 export async function rollback(config) {

package/lib/commands/mcp.mjs

@@ -67,7 +67,8 @@ const COMMANDS = {
   publish: {
     usage: "[--env NAME]",
     summary:
-      "Promote a preview to live, which is what customers see. Ask the developer first: this is " +
+      "Promote the latest push to live (or the preview `--env` names), which is what customers " +
+      "see. Ask the developer first: this is " +
       "the one step that changes what real visitors get.",
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
@@ -77,11 +78,12 @@ const COMMANDS = {
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   chat: {
-    usage: '"message" | transcript | debug | reset [--env NAME]',
+    usage: '"message" | transcript | debug | reset [--env NAME] | show CHAT_ID [--json]',
     summary:
       "Talk to the deployed agent as the developer holding the token, and read the transcript. " +
       "`debug` shows the developer view, including tool calls. `--env live` is a real conversation " +
-      "that appears in the inbox.",
+      "that appears in the inbox. `show CHAT_ID` reads any chat in the workspace — a visitor's on " +
+      "the web or WhatsApp too — with the environment and deployment that answered it.",
     annotations: { readOnlyHint: false }
   },
   secrets: {

package/lib/help.mjs

@@ -24,7 +24,8 @@ flag, the directory decides.
 
   Deploy:
     push [--env NAME]          Validate the workspace, then update a preview
-    publish [--env NAME]       Promote a preview to live. --env names which one
+    publish [--env NAME]       Promote the latest push to live. --env promotes
+                               a specific preview instead
     rollback                   Restore the previous live deployment
     status                     Preview and live deployment state
     diff [--env NAME]          What this directory would change (default: preview)
@@ -35,6 +36,8 @@ flag, the directory decides.
   Talk to your agent (as yourself — the token is the identity):
     chat "message" [--env NAME]        preview by default; --env live is real
     chat transcript|debug|reset [--last N]
+    chat show CHAT_ID [--json] Any chat in the workspace (web, WhatsApp, ...) with
+                               its channel, environment, deployment and tool calls
     chat destroy CHAT_ID
 
   Knowledge:

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@vatio-ai/cli",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
-  "keywords": ["vatio", "agent", "ai", "cli", "deploy"],
+  "keywords": [
+    "vatio",
+    "agent",
+    "ai",
+    "cli",
+    "deploy"
+  ],
   "homepage": "https://vatio.ai",
   "bugs": "https://docs.vatio.ai",
   "license": "SEE LICENSE IN LICENSE.txt",