@vatio-ai/cli 0.58.0 → 0.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/vatio.mjs CHANGED
@@ -18,9 +18,10 @@ import { chat } from "../lib/commands/chat.mjs";
18
18
  import { kb } from "../lib/commands/knowledge.mjs";
19
19
  import { business } from "../lib/commands/business.mjs";
20
20
  import { instagram, whatsapp } from "../lib/commands/channels.mjs";
21
- import { docs } from "../lib/commands/support-commands.mjs";
21
+ import { docs, feedback } from "../lib/commands/support-commands.mjs";
22
22
  import { evalCommand, flags } from "../lib/commands/improve.mjs";
23
23
  import { printUpdateNotice, startUpdateCheck } from "../lib/update-notice.mjs";
24
+ import { beginRun, isCodingAgent, reportRun, telemetryEnabled } from "../lib/telemetry.mjs";
24
25
 
25
26
  // Commands that existed and are gone, answered by name rather than as
26
27
  // unknown: removed from the product, or what npm does now.
@@ -39,16 +40,19 @@ const RETIRED = {
39
40
  "`npm install -g @vatio-ai/cli@latest` updates a global install."
40
41
  };
41
42
 
43
+ const config = new Config({ startDir: process.cwd() });
44
+
42
45
  async function main(argv) {
43
46
  const args = argv.slice(2);
44
47
  const command = args.shift();
48
+ beginRun(command, args);
45
49
  const updateCheck = startUpdateCheck(command);
46
50
  await run(command, args);
51
+ await reportRun(config, { exitCode: process.exitCode ?? 0 });
47
52
  await printUpdateNotice(updateCheck);
48
53
  }
49
54
 
50
55
  async function run(command, args) {
51
- const config = new Config({ startDir: process.cwd() });
52
56
 
53
57
  switch (command) {
54
58
  case "version":
@@ -99,6 +103,8 @@ async function run(command, args) {
99
103
  return await evalCommand(config, args);
100
104
  case "docs":
101
105
  return await docs(config, args);
106
+ case "feedback":
107
+ return await feedback(config, args);
102
108
  case "help":
103
109
  case "-h":
104
110
  case "--help":
@@ -111,35 +117,58 @@ async function run(command, args) {
111
117
  }
112
118
 
113
119
 
114
- main(process.argv).catch((error) => {
120
+ main(process.argv).catch(async (error) => {
121
+ printError(error);
122
+ await reportRun(config, { exitCode: 1, error });
123
+ process.exit(1);
124
+ });
125
+
126
+ function printError(error) {
115
127
  if (error instanceof UserError || error instanceof ConfigError) {
116
128
  console.error(error.message);
117
- process.exit(1);
129
+ return suggestFeedback();
118
130
  }
119
131
  if (error instanceof UnauthorizedError) {
120
132
  console.error("Authentication failed (401). Run `vatio login`.");
121
- if (error.requestId) console.error(`request_id=${error.requestId}`);
122
- process.exit(1);
133
+ return printTrailer(error);
123
134
  }
124
135
  if (error instanceof ForbiddenError) {
125
136
  console.error("Access denied (403). Your token cannot access this workspace.");
126
- if (error.requestId) console.error(`request_id=${error.requestId}`);
127
- process.exit(1);
137
+ return printTrailer(error);
128
138
  }
129
139
  if (error instanceof NotFoundError) {
130
140
  console.error(
131
141
  "Remote resource not found (404). Check the workspace slug; `vatio push` creates a missing remote automatically."
132
142
  );
133
- if (error.requestId) console.error(`request_id=${error.requestId}`);
134
- process.exit(1);
143
+ return printTrailer(error);
135
144
  }
136
145
  if (error instanceof HttpError) {
137
146
  console.error(error.message);
138
- if (error.requestId) console.error(`request_id=${error.requestId}`);
139
- process.exit(1);
147
+ return printTrailer(error);
140
148
  }
141
149
  // Anything left is a bug in this CLI rather than something the developer
142
150
  // did, so it keeps its stack: that is what makes it reportable.
143
151
  console.error(error?.stack ?? String(error));
144
- process.exit(1);
145
- });
152
+ suggestFeedback();
153
+ }
154
+
155
+ // What the platform said to do next, and the ids that find this request in
156
+ // its logs.
157
+ function printTrailer(error) {
158
+ const hint = error.body?.hint;
159
+ if (hint && !(error instanceof UnauthorizedError)) console.error(`Next: ${hint}`);
160
+
161
+ const code = error.body?.error_key ?? (typeof error.body?.error === "string" ? error.body.error : error.body?.error?.code);
162
+ const ids = [code && `error=${code}`, error.requestId && `request_id=${error.requestId}`].filter(Boolean);
163
+ if (ids.length > 0) console.error(ids.join(" "));
164
+ suggestFeedback();
165
+ }
166
+
167
+ // Said to coding agents only: a person at a terminal has better ways to
168
+ // complain, and does not need the line on every typo.
169
+ function suggestFeedback() {
170
+ if (!telemetryEnabled() || !isCodingAgent() || process.argv[2] === "feedback") return;
171
+ console.error(
172
+ '\nIf this has you stuck, tell the Vatio team: vatio feedback "what you were trying to do and what got in the way"'
173
+ );
174
+ }
@@ -8,6 +8,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
8
8
  import { dirname, resolve } from "node:path";
9
9
 
10
10
  import { HttpClient } from "../http.mjs";
11
+ import { clientHeaders } from "../telemetry.mjs";
11
12
  import { fail, sleep, takeEnv, takeFlag, takeValue } from "../support.mjs";
12
13
 
13
14
  const POLL_MS = 3_000;
@@ -23,7 +24,7 @@ function workspaceBase(config) {
23
24
  async function fetchMarkdown(config, path, what) {
24
25
  const { url, token } = workspaceBase(config);
25
26
  const response = await fetch(`${url}${path}`, {
26
- headers: { Accept: "text/markdown, text/plain", Authorization: `Bearer ${token}` },
27
+ headers: { ...clientHeaders(), Accept: "text/markdown, text/plain", Authorization: `Bearer ${token}` },
27
28
  signal: AbortSignal.timeout(30_000)
28
29
  });
29
30
  if (!response.ok) fail(`Could not read ${what} (HTTP ${response.status})`);
@@ -32,7 +33,7 @@ async function fetchMarkdown(config, path, what) {
32
33
 
33
34
  // The open flags as one document: each flagged reply with the conversation
34
35
  // before it, every tool call of that turn with what your backend answered,
35
- // and what the supervisor says it should have said.
36
+ // and what the supervisor says should have happened.
36
37
  export async function flags(config, args) {
37
38
  const json = takeFlag(args, "--json");
38
39
  const save = takeFlag(args, "--save");
@@ -1,9 +1,11 @@
1
- // docs — the command that is about Vatio rather than about a deployment.
1
+ // docs and feedback — the commands that are about Vatio rather than about a
2
+ // deployment.
2
3
 
3
4
  import { mkdirSync, writeFileSync } from "node:fs";
4
5
  import { dirname, resolve } from "node:path";
5
6
 
6
7
  import { fail, takeFlag, takeValue } from "../support.mjs";
8
+ import { clientHeaders, sendFeedback } from "../telemetry.mjs";
7
9
  import { DOCS_URL } from "./misc.mjs";
8
10
 
9
11
  // The whole developer contract as markdown, live from the platform. Fetched
@@ -17,7 +19,7 @@ export async function docs(config, args) {
17
19
  let markdown;
18
20
  try {
19
21
  const response = await fetch(`${baseUrl}/docs.md`, {
20
- headers: { Accept: "text/markdown, text/plain" },
22
+ headers: { ...clientHeaders(), Accept: "text/markdown, text/plain" },
21
23
  signal: AbortSignal.timeout(30_000)
22
24
  });
23
25
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -37,3 +39,30 @@ export async function docs(config, args) {
37
39
  console.log(`Wrote ${target} (${markdown.split("\n").length} lines, from ${baseUrl})`);
38
40
  console.log("Point your coding agent at it, and re-run `vatio docs --save` to refresh.");
39
41
  }
42
+
43
+ // What got in the way, in the words of whoever hit it -- usually a coding agent
44
+ // that just spent ten commands on something the docs should have said. It goes
45
+ // to the Vatio team with the commands that came before it in this session.
46
+ export async function feedback(config, args) {
47
+ let message = args.join(" ").trim();
48
+ if (message === "" && !process.stdin.isTTY) message = (await readStdin()).trim();
49
+ if (message === "") {
50
+ fail(
51
+ 'Say what you were trying to do and what got in the way:\n\n' +
52
+ ' vatio feedback "I ran push twice because the error did not say which field was wrong"'
53
+ );
54
+ }
55
+
56
+ try {
57
+ await sendFeedback(config, message);
58
+ } catch (error) {
59
+ fail(`Could not send it: ${error.message}. Open an issue at https://github.com/vatio-ai/cli/issues instead.`);
60
+ }
61
+ console.log("Sent to the Vatio team, with the commands this session ran before it. Thank you.");
62
+ }
63
+
64
+ async function readStdin() {
65
+ const chunks = [];
66
+ for await (const chunk of process.stdin) chunks.push(chunk);
67
+ return Buffer.concat(chunks).toString("utf8");
68
+ }
@@ -5,6 +5,8 @@
5
5
  // Unauthenticated by definition -- this is what mints the token -- so it does
6
6
  // not go through HttpClient, which requires one.
7
7
 
8
+ import { clientHeaders } from "./telemetry.mjs";
9
+
8
10
  export class DeviceAuthError extends Error {}
9
11
  export class PendingError extends DeviceAuthError {}
10
12
  export class DeniedError extends DeviceAuthError {}
@@ -33,7 +35,7 @@ export class DeviceAuthClient {
33
35
  try {
34
36
  response = await fetch(url, {
35
37
  method: "POST",
36
- headers: { "Content-Type": "application/json", Accept: "application/json" },
38
+ headers: { ...clientHeaders(), "Content-Type": "application/json", Accept: "application/json" },
37
39
  body: JSON.stringify(body),
38
40
  signal: AbortSignal.timeout(30_000)
39
41
  });
package/lib/help.mjs CHANGED
@@ -24,6 +24,7 @@ and the one its pull request deploys to. Elsewhere commands default as listed.
24
24
  doctor Node, config, workspace and token status
25
25
  version What this CLI is
26
26
  docs [--save [PATH]] The whole developer contract, live from Vatio
27
+ feedback "TEXT" Tell the Vatio team what got in the way
27
28
 
28
29
  Deploy:
29
30
  push [--env NAME] Validate the workspace, then update a preview
@@ -51,7 +52,7 @@ and the one its pull request deploys to. Elsewhere commands default as listed.
51
52
  Improve it from what supervisors flagged:
52
53
  flags [--save [PATH]|--json]
53
54
  Every open flag: the conversation, what each tool
54
- answered, and what the reply should have been
55
+ answered, and what should have happened
55
56
  eval [--env NAME] [--agent SLUG] [--no-wait]
56
57
  Replay every eval case (each flag is one) and
57
58
  judge it; exits 1 if one fails. Default: the
@@ -99,7 +100,8 @@ and the one its pull request deploys to. Elsewhere commands default as listed.
99
100
  config show|get KEY|set KEY VALUE|unset KEY
100
101
  Keys: base_url, token
101
102
 
102
- Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_HOME, VATIO_NO_UPDATE_NOTIFIER
103
+ Environment: VATIO_BASE_URL, VATIO_TOKEN, VATIO_HOME, VATIO_NO_UPDATE_NOTIFIER,
104
+ VATIO_TELEMETRY=0 (see docs.vatio.ai/cli/workspace#telemetry)
103
105
 
104
106
  Docs: https://docs.vatio.ai
105
107
  `;
package/lib/http.mjs CHANGED
@@ -5,6 +5,8 @@
5
5
  // fetch() rather than a library: it has been in Node since 18, and this package
6
6
  // stays at one dependency (yaml, for the one file a workspace still parses).
7
7
 
8
+ import { clientHeaders } from "./telemetry.mjs";
9
+
8
10
  export class HttpError extends Error {
9
11
  constructor(message, { status = null, requestId = null, body = {} } = {}) {
10
12
  super(message);
@@ -85,6 +87,7 @@ export class HttpClient {
85
87
  async #perform(method, path, body) {
86
88
  const url = `${this.baseUrl}${path}`;
87
89
  const headers = {
90
+ ...clientHeaders(),
88
91
  Authorization: `Bearer ${this.token}`,
89
92
  Accept: "application/json"
90
93
  };
@@ -0,0 +1,196 @@
1
+ // What the CLI tells Vatio about how it is being used. The reader of this CLI
2
+ // is usually a coding agent, and the only way to learn where it gets stuck is
3
+ // to see the commands it runs, in order, and the errors it is shown.
4
+ //
5
+ // Every request says which CLI made it, which coding agent is driving it, the
6
+ // session it belongs to and the command it is part of. When a command ends,
7
+ // one event says how: the exit code and, on failure, what was printed. Never
8
+ // sent: arguments, file contents, secrets, or what a chat said.
9
+ //
10
+ // VATIO_TELEMETRY=0 (or DO_NOT_TRACK=1) turns all of it off except the
11
+ // User-Agent, which only says which version is calling.
12
+
13
+ import { randomUUID } from "node:crypto";
14
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
15
+ import { dirname, join } from "node:path";
16
+ import { arch, homedir, platform } from "node:os";
17
+
18
+ import { configHome } from "./config.mjs";
19
+ import { VERSION } from "./version.mjs";
20
+
21
+ const SESSION_IDLE_MS = 30 * 60 * 1000;
22
+ const REPORT_TIMEOUT_MS = 1_500;
23
+ const MAX_MESSAGE = 2_000;
24
+
25
+ // Only words a command takes as its first argument are kept: anything else
26
+ // there is a value (`vatio chat "hola"`), and values are not sent.
27
+ const SUBCOMMANDS = {
28
+ chat: ["show"],
29
+ env: ["list", "rm"],
30
+ kb: ["list", "show", "create", "rm", "write", "cat", "rm-entry", "status", "publish", "history"],
31
+ business: ["show", "set", "hours"],
32
+ secrets: ["list", "set", "rm"],
33
+ tokens: ["list", "create", "revoke", "origins"],
34
+ config: ["show", "get", "set", "unset"]
35
+ };
36
+
37
+ export const USER_AGENT = `vatio-cli/${VERSION} (node ${process.version}; ${platform()} ${arch()})`;
38
+
39
+ const run = { command: null };
40
+
41
+ export function telemetryEnabled() {
42
+ const off = ["0", "false", "off", "no"];
43
+ if (off.includes(String(process.env.VATIO_TELEMETRY ?? "").trim().toLowerCase())) return false;
44
+ return !["1", "true"].includes(String(process.env.DO_NOT_TRACK ?? "").trim().toLowerCase());
45
+ }
46
+
47
+ // The coding agent running this CLI, from what each one sets in the
48
+ // environment of the commands it runs. VATIO_AGENT names one we do not know.
49
+ export function codingAgent() {
50
+ const env = process.env;
51
+ if (env.VATIO_AGENT) return String(env.VATIO_AGENT).slice(0, 64);
52
+ if (env.CLAUDECODE) return "claude-code";
53
+ if (env.CURSOR_AGENT || env.CURSOR_TRACE_ID) return "cursor";
54
+ if (env.CODEX_SANDBOX || env.CODEX_MANAGED_BY_NPM) return "codex";
55
+ if (env.GEMINI_CLI) return "gemini-cli";
56
+ if (env.CI) return "ci";
57
+ return process.stdout.isTTY ? "human" : "unknown";
58
+ }
59
+
60
+ export function isCodingAgent() {
61
+ return !["human", "ci"].includes(codingAgent());
62
+ }
63
+
64
+ export function beginRun(command, args) {
65
+ run.command = commandLabel(command, args);
66
+ noticeOnce();
67
+ }
68
+
69
+ // Said once per machine, on stderr, before anything is sent: a coding agent
70
+ // reads it there and can pass it on, which a prompt could never do -- nobody
71
+ // is at the terminal to answer one.
72
+ function noticeOnce() {
73
+ if (!telemetryEnabled()) return;
74
+
75
+ const path = join(configHome(), "telemetry-notice");
76
+ if (existsSync(path)) return;
77
+ process.stderr.write(
78
+ "vatio: the CLI tells Vatio how each command ended (never arguments, files or secrets),\n" +
79
+ "so we can see where coding agents get stuck. Turn it off with VATIO_TELEMETRY=0.\n" +
80
+ "Details: https://docs.vatio.ai/cli/workspace#telemetry\n\n"
81
+ );
82
+ safely(() => {
83
+ mkdirSync(dirname(path), { recursive: true });
84
+ writeFileSync(path, `${new Date().toISOString()}\n`);
85
+ });
86
+ }
87
+
88
+ export function commandLabel(command, args = []) {
89
+ if (!command) return "help";
90
+ const sub = args[0];
91
+ return SUBCOMMANDS[command]?.includes(sub) ? `${command} ${sub}` : command;
92
+ }
93
+
94
+ export function clientHeaders() {
95
+ const headers = { "User-Agent": USER_AGENT };
96
+ if (!telemetryEnabled()) return headers;
97
+
98
+ headers["X-Vatio-Session"] = sessionId();
99
+ headers["X-Vatio-Agent"] = codingAgent();
100
+ if (run.command) headers["X-Vatio-Command"] = run.command;
101
+ return headers;
102
+ }
103
+
104
+ // How the command ended. Awaited, but never for long and never to the point
105
+ // of failing: a CLI that hangs or errors because telemetry could not be sent
106
+ // would be worse than not knowing.
107
+ export async function reportRun(config, { exitCode, error = null }) {
108
+ if (!telemetryEnabled() || !run.command || run.command === "feedback") return;
109
+
110
+ await post(config, {
111
+ kind: "run",
112
+ command: run.command,
113
+ exit_code: exitCode,
114
+ error: error ? describeError(error) : undefined
115
+ }).catch(() => {});
116
+ }
117
+
118
+ // `vatio feedback`: sent even with telemetry off, because running it is the
119
+ // developer (or their agent) choosing to tell us something.
120
+ export async function sendFeedback(config, message) {
121
+ await post(config, { kind: "feedback", command: "feedback", message: message.slice(0, MAX_MESSAGE) }, { strict: true });
122
+ }
123
+
124
+ async function post(config, body, { strict = false } = {}) {
125
+ const token = safely(() => config.resolveToken());
126
+ const headers = { ...clientHeaders(), "Content-Type": "application/json", Accept: "application/json" };
127
+ if (strict) {
128
+ headers["X-Vatio-Session"] ??= sessionId();
129
+ headers["X-Vatio-Agent"] ??= codingAgent();
130
+ }
131
+ if (token) headers.Authorization = `Bearer ${token}`;
132
+
133
+ const response = await fetch(`${config.resolveBaseUrl()}/api/developer/v1/cli/events`, {
134
+ method: "POST",
135
+ headers,
136
+ body: JSON.stringify({
137
+ ...body,
138
+ workspace: safely(() => config.resolveWorkspace())
139
+ }),
140
+ signal: AbortSignal.timeout(strict ? 10_000 : REPORT_TIMEOUT_MS)
141
+ });
142
+ if (strict && !response.ok) throw new Error(`HTTP ${response.status}`);
143
+ }
144
+
145
+ function describeError(error) {
146
+ const body = error?.body && typeof error.body === "object" ? error.body : {};
147
+ const code = typeof body.error === "string" ? body.error : body.error?.code;
148
+ // A bug in the CLI keeps the top of its stack: that is where it happened.
149
+ // Everything else is a sentence the CLI chose to print, and that is the
150
+ // sentence worth knowing.
151
+ const expected = ["UserError", "ConfigError"].includes(error?.name) || (error && "requestId" in error);
152
+ const message = expected
153
+ ? String(error.message ?? "")
154
+ : String(error?.stack ?? error).split("\n").slice(0, 6).join("\n");
155
+
156
+ return {
157
+ class: error?.constructor?.name ?? "Error",
158
+ key: body.error_key ?? code ?? undefined,
159
+ message: message.replaceAll(homedir(), "~").slice(0, MAX_MESSAGE),
160
+ request_id: error?.requestId ?? undefined
161
+ };
162
+ }
163
+
164
+ // One session is one stretch of work in one directory: a new id after half an
165
+ // hour without a command, so an agent coming back tomorrow is a new session,
166
+ // and two agents in two projects are two.
167
+ function sessionId() {
168
+ if (run.sessionId) return run.sessionId;
169
+
170
+ const path = join(configHome(), "sessions.json");
171
+ const key = process.cwd();
172
+ const sessions = safely(() => JSON.parse(readFileSync(path, "utf8"))) ?? {};
173
+ const now = Date.now();
174
+ const current = sessions[key];
175
+ const id = current && now - Date.parse(current.last_used_at) < SESSION_IDLE_MS ? current.id : randomUUID();
176
+
177
+ for (const [dir, session] of Object.entries(sessions)) {
178
+ if (now - Date.parse(session.last_used_at) > SESSION_IDLE_MS) delete sessions[dir];
179
+ }
180
+ sessions[key] = { id, last_used_at: new Date(now).toISOString() };
181
+ safely(() => {
182
+ mkdirSync(dirname(path), { recursive: true });
183
+ writeFileSync(path, JSON.stringify(sessions));
184
+ });
185
+
186
+ run.sessionId = id;
187
+ return id;
188
+ }
189
+
190
+ function safely(fn) {
191
+ try {
192
+ return fn();
193
+ } catch {
194
+ return null;
195
+ }
196
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vatio-ai/cli",
3
- "version": "0.58.0",
3
+ "version": "0.59.0",
4
4
  "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
5
5
  "keywords": [
6
6
  "vatio",