@vatio-ai/cli 0.125.0 → 0.127.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.
@@ -81,12 +81,13 @@ export async function checkWorkspace(config, workspace, { environment = null } =
81
81
  const IGNORED_BLOCK = /^vatio\.yml: `[^`]+` is ignored/;
82
82
 
83
83
  // Returns the ignored-block lines it held back, for a caller that prints them
84
- // last (`vatio push`); otherwise they follow the other warnings.
85
- export function printDiagnostics(payload, { holdIgnored = false } = {}) {
86
- for (const row of asArray(payload.errors)) console.error(`error: ${diagnosticLine(row)}`);
84
+ // last (`vatio push`); otherwise they follow the other warnings. Each line is
85
+ // printed once per command: `seen` carries what was already said, for a
86
+ // command that gets warnings from more than one response.
87
+ export function printDiagnostics(payload, { holdIgnored = false, seen = new Set() } = {}) {
88
+ for (const line of unseen(asArray(payload.errors).map(diagnosticLine), seen)) console.error(`error: ${line}`);
87
89
  const ignored = [];
88
- for (const row of asArray(payload.warnings)) {
89
- const line = diagnosticLine(row);
90
+ for (const line of unseen(asArray(payload.warnings).map(diagnosticLine), seen)) {
90
91
  if (IGNORED_BLOCK.test(line)) ignored.push(line);
91
92
  else console.error(`warning: ${line}`);
92
93
  }
@@ -94,6 +95,14 @@ export function printDiagnostics(payload, { holdIgnored = false } = {}) {
94
95
  return ignored;
95
96
  }
96
97
 
98
+ function unseen(lines, seen) {
99
+ return lines.filter((line) => {
100
+ if (seen.has(line)) return false;
101
+ seen.add(line);
102
+ return true;
103
+ });
104
+ }
105
+
97
106
  function printIgnored(lines) {
98
107
  if (lines.length === 0) return;
99
108
  const one = lines.length === 1;
@@ -143,7 +152,8 @@ export async function push(config, args) {
143
152
  }
144
153
 
145
154
  const check = await checkWorkspace(config, workspace, { environment });
146
- const ignored = printDiagnostics(check, { holdIgnored: true });
155
+ const seen = new Set();
156
+ const ignored = printDiagnostics(check, { holdIgnored: true, seen });
147
157
  if (!check.ok) {
148
158
  printIgnored(ignored);
149
159
  fail(`push aborted: check failed (${asArray(check.errors).length} error(s))`);
@@ -151,12 +161,18 @@ export async function push(config, args) {
151
161
 
152
162
  const client = deployClient(config, workspace);
153
163
  const baseUrl = config.resolveBaseUrl();
164
+ const root = config.workspaceRootRequired();
165
+ const gitBranch = detectGitBranch(root);
166
+ // Uncommitted changes under the workspace directory, which is what a push
167
+ // sends: then git_sha alone does not say what was pushed.
168
+ const changes = gitChanges(root, ["."]);
154
169
  let payload;
155
170
  try {
156
171
  payload = await client.pushPreview({
157
172
  manifest: check.manifest,
158
- gitSha: detectGitSha(config.workspaceRootRequired()),
159
- gitBranch: detectGitBranch(config.workspaceRootRequired()),
173
+ gitSha: detectGitSha(root),
174
+ gitBranch,
175
+ gitDirty: changes === null ? null : changes.length > 0,
160
176
  createdBy: process.env.USER ?? null,
161
177
  environment,
162
178
  force,
@@ -164,6 +180,9 @@ export async function push(config, args) {
164
180
  });
165
181
  } catch (error) {
166
182
  if (error instanceof ConflictError && error.errorKey === "preview_edited_outside") fail(editedOutsideMessage(error));
183
+ if (error instanceof UnprocessableError && error.errorKey === "preview_has_unpublished_push") {
184
+ fail(unpublishedPushMessage(error, gitBranch));
185
+ }
167
186
  throw error;
168
187
  }
169
188
  // What the files match now, so the next push is built on it.
@@ -184,9 +203,11 @@ export async function push(config, args) {
184
203
  for (const line of consequenceLines(payload)) console.log(line);
185
204
  // Where to try it: the inbox's Try the agent panel for that environment.
186
205
  if (payload.share_url) console.log(`Try it: ${payload.share_url}`);
187
- for (const warning of asArray(payload.warnings)) {
188
- if (!IGNORED_BLOCK.test(String(warning))) console.log(` warning: ${warning}`);
189
- else if (!ignored.includes(String(warning))) ignored.push(String(warning));
206
+ // Mostly what the check already said: the platform loads the manifest again
207
+ // to apply it.
208
+ for (const warning of unseen(asArray(payload.warnings).map(diagnosticLine), seen)) {
209
+ if (IGNORED_BLOCK.test(warning)) ignored.push(warning);
210
+ else console.log(` warning: ${warning}`);
190
211
  }
191
212
  if (payload.preview_url) console.log(`Preview: ${payload.preview_url}`);
192
213
 
@@ -269,6 +290,42 @@ function editedOutsideMessage(error) {
269
290
  return lines.join("\n");
270
291
  }
271
292
 
293
+ // Refused because preview holds a push from another branch nobody published:
294
+ // whose, so the session that hit it can tell whether that work is done
295
+ // without asking around. A platform older than `held` sends its own sentence.
296
+ function unpublishedPushMessage(error, branch) {
297
+ const held = error.body.held;
298
+ if (!held || typeof held !== "object") return error.message;
299
+
300
+ const yours = branch ? ` Yours is from branch ${branch}.` : "";
301
+ return [
302
+ "Preview holds a push from another branch that is not published:",
303
+ ` ${heldLine(held)}`,
304
+ "",
305
+ `A push would replace it.${yours} Publish what preview holds first (\`vatio publish\`), or`,
306
+ "`vatio push --force` to replace it. `vatio status` shows what preview holds at any time."
307
+ ].join("\n");
308
+ }
309
+
310
+ // `#42 from branch feat/x, a1b2c3d plus uncommitted changes, pushed by ivan on
311
+ // 2026-10-28T14:02:00Z`. Fields as AgentDeployment#held_payload and
312
+ // #status_payload name them; the id is `deployment_id` in one and `id` in the
313
+ // other.
314
+ function heldLine(deployment) {
315
+ const id = deployment.deployment_id ?? deployment.id;
316
+ const parts = [`#${id}`];
317
+ if (deployment.git_branch) parts[0] += ` from branch ${deployment.git_branch}`;
318
+ if (deployment.source === "edit") {
319
+ parts.push(`an edit made outside your files${deployment.change_summary ? ` (${deployment.change_summary})` : ""}`);
320
+ }
321
+ const sha = deployment.git_sha ? String(deployment.git_sha).slice(0, 7) : null;
322
+ if (deployment.git_dirty === true) parts.push(`${sha ?? "no commit"} plus uncommitted changes`);
323
+ else if (sha) parts.push(deployment.git_dirty === false ? `${sha}, committed` : sha);
324
+ const by = deployment.created_by ? ` by ${deployment.created_by}` : "";
325
+ parts.push(`${deployment.source === "edit" ? "made" : "pushed"}${by} on ${deployment.created_at}`);
326
+ return parts.join(", ");
327
+ }
328
+
272
329
  // `#42 by ivan@x.cl via Claude, 2026-10-16T12:00:00Z: instructions, tool my_orders`
273
330
  function editLine(edit) {
274
331
  const who = edit?.created_by ? ` by ${edit.created_by}` : "";
@@ -417,6 +474,11 @@ export async function status(config) {
417
474
  const workspace = config.resolveWorkspaceRequired();
418
475
  const payload = await deployClient(config, workspace).deployStatus();
419
476
  console.log(JSON.stringify(payload, null, 2));
477
+ printWhatsappIssue(payload.whatsapp);
478
+
479
+ // There is one preview, so a session about to push wants to know whose work
480
+ // is on it, and whether that work has gone live, without reading the JSON.
481
+ printPreviewHolds(payload);
420
482
 
421
483
  // A base with content that no deployed agent reads is knowledge the agent
422
484
  // cannot reach, and nothing else says so -- it just answers without it. On
@@ -442,6 +504,30 @@ export async function status(config) {
442
504
  printImpact(payload.impact);
443
505
  }
444
506
 
507
+ function printPreviewHolds(payload) {
508
+ const preview = payload.preview;
509
+ if (!preview || typeof preview !== "object") return;
510
+
511
+ const live = payload.live;
512
+ const published = preview.current_live
513
+ ? "live runs it"
514
+ : live?.id
515
+ ? `not published: live runs #${live.id}`
516
+ : "not published";
517
+ console.error(`Preview holds ${heldLine(preview)}; ${published}.`);
518
+ }
519
+
520
+ // A number that looks connected while Meta refuses every send from it: first
521
+ // on stderr, because every message the backend sends meanwhile is refused.
522
+ function printWhatsappIssue(whatsapp) {
523
+ const issue = whatsapp?.issue;
524
+ if (!issue) return;
525
+ const code = issue.code ? ` (Meta ${issue.code})` : "";
526
+ console.error(`WhatsApp ${whatsapp.number ?? "number"} is NOT SENDING since ${issue.since}${code}: ${issue.message ?? ""}`);
527
+ console.error(` Fix: ${issue.fix}`);
528
+ console.error(" Until a check passes (vatio whatsapp check), POST /messages answers 409 whatsapp_number_unhealthy.");
529
+ }
530
+
445
531
  // What Vatio did for this workspace in the last 30 days, in one line a
446
532
  // coding agent can repeat to the person: on stderr like the rest, and only
447
533
  // when there is something to count.
@@ -25,7 +25,8 @@ export async function messages(config, args) {
25
25
 
26
26
  console.log(`${page.messages.length} failed messages on ${workspace} (${environment}):`);
27
27
  for (const row of page.messages) {
28
- console.log(` #${row.id} ${row.created_at} ${row.mode} ${row.error_code || "?"} ${row.error_message || ""}`);
28
+ const ref = row.external_ref ? ` ${row.external_ref}` : "";
29
+ console.log(` #${row.id}${ref} ${row.created_at} ${row.mode} ${row.error_code || "?"} ${row.error_message || ""}`);
29
30
  }
30
31
  if (page.next_before) console.log(`More may match. Continue with --before ${page.next_before}.`);
31
32
  }
@@ -176,7 +176,8 @@ const AGENTS_NOTE = [
176
176
  "",
177
177
  "This directory is a Vatio workspace (`vatio.yml`). `vatio docs` prints the",
178
178
  "contract for the manifest, tools, knowledge and the CLI; read it before",
179
- "changing anything here.",
179
+ "changing anything here. `vatio docs search TERM` finds one thing in it, and",
180
+ "`vatio docs PAGE` prints one page (`vatio docs tools`).",
180
181
  "",
181
182
  "To fix what supervisors reported and the tests that fail, take them all in",
182
183
  "one session: `vatio test list` (follow the instructions at the top of its",
@@ -9,6 +9,7 @@ import { gzipSync } from "node:zlib";
9
9
  import * as claudeSessions from "../claude-session.mjs";
10
10
  import * as codexSessions from "../codex-session.mjs";
11
11
  import { configHome } from "../config.mjs";
12
+ import { pageArgument, sectionsOf } from "../docs-sections.mjs";
12
13
  import { ask, fail, takeFlag, takeValue } from "../support.mjs";
13
14
  import { chosenHeaders, clientHeaders, sendFeedback, telemetryEnabled } from "../telemetry.mjs";
14
15
  import { ensureAuthorized } from "./deploy.mjs";
@@ -17,22 +18,18 @@ import { DOCS_URL } from "./misc.mjs";
17
18
  // The whole developer contract as markdown, live from the platform. Fetched
18
19
  // rather than bundled: the docs describe the deploy you are talking to, and a
19
20
  // copy shipped inside this package would start lying the day either moves.
21
+ //
22
+ // The whole of it is thousands of lines. `vatio docs PAGE` prints one page,
23
+ // and `vatio docs search TERM` the sections that mention something.
20
24
  export async function docs(config, args) {
21
- const save = takeFlag(args, "--save");
22
- const savePath = takeValue(args, "--save-to") ?? (save ? args.shift() ?? null : null);
25
+ const saveTo = takeValue(args, "--save-to");
26
+ const save = takeFlag(args, "--save") || saveTo != null;
27
+ const savePath = saveTo ?? (save ? args.shift() ?? null : null);
28
+ if (!save && args[0] === "search") return await searchDocs(config, args.slice(1));
29
+ if (!save && args.length > 0) return await docsPage(config, args);
23
30
 
24
31
  const baseUrl = config.resolveBaseUrl();
25
- let markdown;
26
- try {
27
- const response = await fetch(`${baseUrl}/docs.md`, {
28
- headers: { ...clientHeaders(), Accept: "text/markdown, text/plain" },
29
- signal: AbortSignal.timeout(30_000)
30
- });
31
- if (!response.ok) throw new Error(`HTTP ${response.status}`);
32
- markdown = await response.text();
33
- } catch (error) {
34
- fail(`Could not fetch the docs: ${error.message}\nRead them at ${DOCS_URL} instead.`);
35
- }
32
+ const markdown = await fetchContract(config);
36
33
 
37
34
  if (!save) {
38
35
  process.stdout.write(markdown);
@@ -46,6 +43,164 @@ export async function docs(config, args) {
46
43
  console.log("Point your coding agent at it, and re-run `vatio docs --save` to refresh.");
47
44
  }
48
45
 
46
+ const DOCS_SEARCH_USAGE = "vatio docs search TERM [--all]";
47
+ // Sections `vatio docs search` prints unless --all, and matches per section.
48
+ const SEARCH_SECTIONS = 20;
49
+ const SEARCH_MATCHES = 3;
50
+ const SEARCH_CONTEXT = 2;
51
+
52
+ async function fetchMarkdown(url, { method = "GET" } = {}) {
53
+ const response = await fetch(url, {
54
+ method,
55
+ headers: { ...clientHeaders(), Accept: "text/markdown, text/plain" },
56
+ signal: AbortSignal.timeout(30_000)
57
+ });
58
+ return { ok: response.ok, status: response.status, url: response.url, text: method === "HEAD" ? "" : await response.text() };
59
+ }
60
+
61
+ // docs.md, by way of the base URL, which redirects to where the docs live.
62
+ async function fetchContract(config) {
63
+ try {
64
+ const response = await fetchMarkdown(`${config.resolveBaseUrl()}/docs.md`);
65
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
66
+ return response.text;
67
+ } catch (error) {
68
+ fail(`Could not fetch the docs: ${error.message}\nRead them at ${DOCS_URL} instead.`);
69
+ }
70
+ }
71
+
72
+ // Where the pages' Markdown twins are: beside the docs.md the base URL leads
73
+ // to, https://vatio.ai/docs/ unless that says otherwise.
74
+ async function docsRoot(config) {
75
+ try {
76
+ const { ok, url } = await fetchMarkdown(`${config.resolveBaseUrl()}/docs.md`, { method: "HEAD" });
77
+ if (ok && url.endsWith("/docs.md")) return url.slice(0, -"docs.md".length);
78
+ } catch {
79
+ // The page fetch says what went wrong, if anything does.
80
+ }
81
+ return `${DOCS_URL}/`;
82
+ }
83
+
84
+ // One page as Markdown, by its path under /docs: `tools`, `cli/chat`, `cli`
85
+ // for cli/, a pasted https://vatio.ai/docs/tools#anchor too.
86
+ async function docsPage(config, args) {
87
+ if (args.length > 1) fail(`vatio docs takes one page (\`vatio docs tools\`), or \`${DOCS_SEARCH_USAGE}\`.`);
88
+ const page = args[0]
89
+ .trim()
90
+ .replace(/^https?:\/\/[^/]+/, "")
91
+ .replace(/[#?].*$/, "")
92
+ .replace(/^\/+/, "")
93
+ .replace(/^docs(\/|$)/, "")
94
+ .replace(/\.md$/, "");
95
+ const root = await docsRoot(config);
96
+ const candidates = page === "" || page === "index" ? ["index.md"] : page.endsWith("/") ? [`${page}index.md`] : [`${page}.md`, `${page}/index.md`];
97
+
98
+ for (const candidate of candidates) {
99
+ let response;
100
+ try {
101
+ response = await fetchMarkdown(`${root}${candidate}`);
102
+ } catch (error) {
103
+ fail(`Could not fetch ${root}${candidate}: ${error.message}`);
104
+ }
105
+ if (response.ok) {
106
+ process.stdout.write(response.text.endsWith("\n") ? response.text : `${response.text}\n`);
107
+ return;
108
+ }
109
+ if (response.status !== 404) fail(`Could not fetch ${root}${candidate}: HTTP ${response.status}`);
110
+ }
111
+
112
+ fail(await noSuchPage(root, page));
113
+ }
114
+
115
+ // The pages llms.txt lists whose path or title has the word in it, or all of
116
+ // them: the reader needs a name to pass, not a 404.
117
+ async function noSuchPage(root, page) {
118
+ let pages = [];
119
+ try {
120
+ const response = await fetchMarkdown(`${root}llms.txt`);
121
+ if (response.ok) {
122
+ pages = [...response.text.matchAll(/^- \[([^\]]+)\]\((https?:\/\/[^)]+)\.md\)/gm)].map(([, title, url]) => ({
123
+ title,
124
+ name: pageArgument(`${url.replace(/(^|\/)index$/, "$1")}`)
125
+ }));
126
+ }
127
+ } catch {
128
+ // Said below without the list.
129
+ }
130
+ const words = page.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
131
+ const close = pages.filter(({ title, name }) => words.some((word) => `${name} ${title}`.toLowerCase().includes(word)));
132
+ const listed = close.length > 0 ? close : pages;
133
+ const width = Math.max(0, ...listed.map(({ name }) => name.length));
134
+ return [
135
+ `No docs page ${JSON.stringify(page)}. \`${DOCS_SEARCH_USAGE}\` looks inside the pages.`,
136
+ ...(listed.length > 0 ? ["", close.length > 0 ? "Pages like it:" : "The pages:"] : []),
137
+ ...listed.map(({ title, name }) => ` vatio docs ${name.padEnd(width)} ${title}`)
138
+ ].join("\n");
139
+ }
140
+
141
+ // The sections of the reference that mention TERM, case-insensitively: each
142
+ // with its heading path, its URL and the lines around each match, numbered as
143
+ // in docs.md (`vatio docs --save`).
144
+ async function searchDocs(config, args) {
145
+ const all = takeFlag(args, "--all");
146
+ const term = args.join(" ").trim();
147
+ if (term === "") fail(`Say what to look for: ${DOCS_SEARCH_USAGE}`);
148
+
149
+ const markdown = await fetchContract(config);
150
+ const needle = term.toLowerCase();
151
+ const hits = sectionsOf(markdown)
152
+ .map((section) => ({ ...section, matches: section.lines.filter((line) => line.text.toLowerCase().includes(needle)) }))
153
+ .filter((section) => section.matches.length > 0);
154
+
155
+ if (hits.length === 0) {
156
+ console.log(
157
+ `Nothing in the reference mentions ${JSON.stringify(term)}. Try another word, or \`vatio docs PAGE\` for a page; ` +
158
+ "the guides are not in the reference, and `vatio docs guides/NAME` prints one."
159
+ );
160
+ return;
161
+ }
162
+
163
+ const shown = all ? hits : hits.slice(0, SEARCH_SECTIONS);
164
+ const count = hits.length === 1 ? "1 section" : `${hits.length} sections`;
165
+ console.log(`${count} of the reference mention ${JSON.stringify(term)}${shown.length < hits.length ? `; the first ${shown.length}` : ""}.`);
166
+
167
+ for (const section of shown) {
168
+ console.log("");
169
+ console.log(section.path.join(" › "));
170
+ console.log(`${section.url} (vatio docs ${pageArgument(section.url)})`);
171
+ for (const line of excerpt(section)) console.log(line);
172
+ }
173
+
174
+ if (shown.length < hits.length) {
175
+ console.log("");
176
+ const quoted = /\s/.test(term) ? JSON.stringify(term) : term;
177
+ console.log(`${hits.length - shown.length} more: \`vatio docs search ${quoted} --all\`, or a narrower term.`);
178
+ }
179
+ }
180
+
181
+ // grep -n -C2 style: `288:` a matching line, `287-` one around it, `--`
182
+ // between runs that do not touch.
183
+ function excerpt(section) {
184
+ const { lines, matches } = section;
185
+ const wanted = new Set();
186
+ for (const match of matches.slice(0, SEARCH_MATCHES)) {
187
+ const at = lines.indexOf(match);
188
+ for (let i = Math.max(0, at - SEARCH_CONTEXT); i <= Math.min(lines.length - 1, at + SEARCH_CONTEXT); i++) wanted.add(i);
189
+ }
190
+ const hit = new Set(matches);
191
+ const out = [];
192
+ let previous = null;
193
+ for (const index of [...wanted].sort((a, b) => a - b)) {
194
+ if (previous !== null && index > previous + 1) out.push("--");
195
+ const line = lines[index];
196
+ out.push(`${line.number}${hit.has(line) ? ":" : "-"} ${line.text}`);
197
+ previous = index;
198
+ }
199
+ const more = matches.length - SEARCH_MATCHES;
200
+ if (more > 0) out.push(`(${more} more in this section)`);
201
+ return out;
202
+ }
203
+
49
204
  // What got in the way, in the words of whoever hit it -- usually a coding agent
50
205
  // that just spent ten commands on something the docs should have said. It goes
51
206
  // to the Vatio team with the commands that came before it in this session.
@@ -75,8 +75,9 @@ export async function templates(config, args) {
75
75
  }
76
76
 
77
77
  // On the workspace's own number once it has one, and before that on Vatio's
78
- // test number, where a preview key sends it to the workspace's test phones
79
- // until Vatio moves it to the number the workspace connects. The backend
78
+ // test number, where a preview key sends it to the team's verified WhatsApps
79
+ // and the customer phones, until Vatio moves it to the number the workspace
80
+ // connects. The backend
80
81
  // decides where, so there is no environment to choose.
81
82
  async function createTemplate(config, args, json) {
82
83
  takeValue(args, "--env");
@@ -104,7 +105,8 @@ async function createTemplate(config, args, json) {
104
105
  (own ? "" : " --env preview"));
105
106
  console.log(own
106
107
  ? "Once APPROVED, your backend sends it with a live key outside the 24-hour window with:"
107
- : "Once APPROVED, a preview key sends it to your test phones outside the 24-hour window with:");
108
+ : "Once APPROVED, a preview key sends it on Vatio's test number, to your team's verified WhatsApps and your " +
109
+ "customer phones, outside the 24-hour window with:");
108
110
  console.log(` "template": ${JSON.stringify(template.example)}`);
109
111
  if (!own) {
110
112
  console.log("When you connect your own number, Vatio moves your templates to it, and from then on your backend " +
@@ -0,0 +1,113 @@
1
+ // docs.md, the whole reference as one file, cut back into the sections it was
2
+ // made of, for `vatio docs search`. site/src/docs/contract.mjs writes it:
3
+ //
4
+ // ## Tab (Documentation, CLI, SDK, API Reference)
5
+ // ### Page title
6
+ // `https://vatio.ai/docs/page`
7
+ // #### A heading of the page (its ##, demoted by two), and so on down
8
+ //
9
+ // A section runs from one heading to the next, and knows its heading path and
10
+ // the URL of the page it is on, with the heading's anchor.
11
+
12
+ const FENCE = /^\s*(```|~~~)/;
13
+ const HEADING = /^(#{2,6})\s+(.*?)\s*$/;
14
+ const PAGE_URL = /^`(https?:\/\/[^`\s]+)`$/;
15
+ const CUSTOM_ID = /\s*\{#([\w-]+)\}\s*$/;
16
+
17
+ export function sectionsOf(markdown) {
18
+ const lines = markdown.split("\n");
19
+ const sections = [];
20
+ let tab = null;
21
+ let page = null;
22
+ let trail = [];
23
+ let section = null;
24
+ let fenced = false;
25
+
26
+ const open = (headings, anchor) => {
27
+ section = {
28
+ path: [tab, page?.title, ...headings].filter(Boolean),
29
+ url: page ? (anchor ? `${page.url}#${anchor}` : page.url) : null,
30
+ lines: []
31
+ };
32
+ sections.push(section);
33
+ };
34
+
35
+ lines.forEach((text, index) => {
36
+ const number = index + 1;
37
+ if (FENCE.test(text)) fenced = !fenced;
38
+ const heading = fenced ? null : HEADING.exec(text);
39
+
40
+ if (heading) {
41
+ const level = heading[1].length;
42
+ const title = heading[2].replace(CUSTOM_ID, "");
43
+ if (level === 2) {
44
+ tab = title;
45
+ page = null;
46
+ trail = [];
47
+ open([], null);
48
+ } else if (level === 3) {
49
+ page = { title, url: null, used: new Set([slugify(plain(title))]) };
50
+ trail = [];
51
+ open([], null);
52
+ } else {
53
+ // A page's own ## is #### here.
54
+ const depth = level - 4;
55
+ trail = [...trail.slice(0, depth), plain(title)];
56
+ open(trail, page ? anchorFor(heading[2], page.used) : null);
57
+ }
58
+ section.lines.push({ number, text });
59
+ return;
60
+ }
61
+
62
+ if (page && page.url === null && PAGE_URL.test(text.trim())) {
63
+ page.url = PAGE_URL.exec(text.trim())[1];
64
+ section.url = page.url;
65
+ return;
66
+ }
67
+ section?.lines.push({ number, text });
68
+ });
69
+
70
+ return sections.filter((row) => row.url !== null);
71
+ }
72
+
73
+ // What `vatio docs PAGE` takes for a page URL: "tools", "cli/chat", "cli" for
74
+ // cli/, "index" for the introduction.
75
+ export function pageArgument(url) {
76
+ const path = String(url).replace(/#.*$/, "").replace(/^.*?\/docs\//, "");
77
+ if (path === "") return "index";
78
+ return path.replace(/\/$/, "");
79
+ }
80
+
81
+ // The heading ids the site gives (site/src/plugins/rehype-docs.mjs): an
82
+ // explicit {#id}, or the text lowercased with accents folded and every run of
83
+ // anything else as one hyphen, -1, -2 on a repeat.
84
+ function anchorFor(raw, used) {
85
+ const custom = CUSTOM_ID.exec(raw);
86
+ if (custom) {
87
+ used.add(custom[1]);
88
+ return custom[1];
89
+ }
90
+ const slug = slugify(plain(raw));
91
+ let id = slug;
92
+ for (let i = 1; used.has(id); i++) id = `${slug}-${i}`;
93
+ used.add(id);
94
+ return id;
95
+ }
96
+
97
+ // A heading's text as the page shows it: no backticks, emphasis or link
98
+ // targets.
99
+ function plain(heading) {
100
+ return heading
101
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
102
+ .replace(/[`*]/g, "")
103
+ .trim();
104
+ }
105
+
106
+ function slugify(value) {
107
+ return value
108
+ .normalize("NFKD")
109
+ .replace(/[̀-ͯ]/g, "")
110
+ .toLowerCase()
111
+ .replace(/[^a-z0-9]+/g, "-")
112
+ .replace(/^-+|-+$/g, "");
113
+ }
package/lib/help.mjs CHANGED
@@ -32,6 +32,9 @@ the two you are in. Commands default as listed.
32
32
  updating; this only tells you). --full prints each
33
33
  entry whole instead of its headlines
34
34
  docs [--save [PATH]] The whole developer contract, live from Vatio
35
+ docs PAGE One page of it: tools, cli/chat, guides/NAME...
36
+ docs search TERM [--all] The sections that mention TERM, with their page
37
+ and the lines around each match
35
38
  feedback "TEXT" Tell the Vatio team what got in the way
36
39
  share-session ["FEEDBACK"] Send this Claude Code or Codex session to the
37
40
  Vatio team, after showing what goes; feedback optional
@@ -60,8 +63,11 @@ the two you are in. Commands default as listed.
60
63
  tested preview's version, and while it fails a
61
64
  report live passes; --force publishes anyway
62
65
  rollback Put live back to the previous snapshot: config and knowledge
63
- status Preview and live deployment state, and the replies
64
- Vatio wrote for the agent, and why
66
+ status Preview and live deployment state: which one
67
+ preview holds (branch, commit, uncommitted
68
+ changes, who pushed it and when, published or
69
+ not), the replies Vatio wrote for the agent, and
70
+ your WhatsApp number when Meta refuses its sends
65
71
  env [preview|live] An environment: token, widget snippet, link,
66
72
  knowledge changes and conflicts (default: preview)
67
73
  env list Both environments and what each runs
@@ -70,16 +76,24 @@ the two you are in. Commands default as listed.
70
76
  diff --stat|--name-only|--format json|--full
71
77
 
72
78
  Talk to your agent (as yourself by default — the token is the identity):
73
- chat "message" [--env NAME] [--new] [--as-phone me|PHONE]
79
+ chat "message" [--file PATH]... [--env NAME] [--new] [--as-phone me|PHONE]
74
80
  [--as-subject ID | --visitor-token JWT]
75
81
  preview by default; --env live is real; --new
76
- starts over as a visitor the agent never met.
77
- --as-phone speaks as your verified WhatsApp or a
78
- test phone; --as-subject signs a visitor in with
79
- your identity key, so \`access: private\` tools run
82
+ starts over as a visitor the agent never met,
83
+ in a new chat whose id it prints.
84
+ --file attaches an image, PDF, text or audio file
85
+ as a visitor would (up to 4, 8 MB each).
86
+ --as-phone speaks as your verified WhatsApp or
87
+ a customer phone; --as-subject signs a visitor
88
+ in with your identity key, so \`access: private\`
89
+ tools run
90
+ chat --chat CHAT_ID "message"
91
+ Continue that chat, whatever .vatio-chat.json
92
+ says: for chats running side by side
80
93
  chat show [CHAT_ID] [--json] [--last N]
81
94
  The chat you are in, or any chat in the workspace
82
- (web, WhatsApp, ...): messages, tool calls, channel
95
+ (web, WhatsApp, ...): messages, tool calls, channel,
96
+ and what was read of each file (truncated, unreadable)
83
97
  chat export --from DATE [--to DATE] [--env NAME] [--channel NAME] [--out FILE]
84
98
  What people said and were answered between two
85
99
  dates, redacted by Vatio, one conversation per
@@ -189,21 +203,22 @@ the two you are in. Commands default as listed.
189
203
  to type the ID; without a terminal, needs --yes
190
204
 
191
205
  WhatsApp (everything on the inbox's WhatsApp page; --json on each):
192
- whatsapp [status] Your number, whether it is live, its problems,
193
- and the test phones
206
+ whatsapp [status] Your number, whether it is live, and its problems
207
+ (first: a Meta error that fails every send)
194
208
  whatsapp connect Where to connect your number (Meta's consent
195
209
  screen only opens in the inbox)
196
210
  whatsapp live on|off Answer everyone who writes, or nobody
197
- whatsapp check Check the number with Meta and re-subscribe it
211
+ whatsapp check [--pin PIN] Check the number with Meta and re-subscribe it;
212
+ a pass clears its problem. --pin (its 6-digit
213
+ two-step verification PIN) registers it on the
214
+ Cloud API again first: the fix for 133010
198
215
  whatsapp disconnect [--yes]
199
216
  whatsapp invite EMAIL [--code CODE]
200
- Email whoever holds the number the link that
201
- connects it (owner only)
202
- whatsapp team Who on the team verified their own WhatsApp
203
- whatsapp phones [list] Test phones on Vatio's shared preview number
204
- whatsapp phones add The code a phone sends to join, and its link
205
- whatsapp phones rm PHONE | move PHONE
206
- Remove one, or bring one you verified elsewhere
217
+ Ask whoever manages the number to connect it:
218
+ an email with the link (owner only)
219
+ whatsapp team The team and each person's own WhatsApp: the
220
+ phone the agent knows them by, and that reaches
221
+ it on Vatio's number
207
222
  whatsapp templates [list] [--env live]
208
223
  The number's templates and the "template" to send
209
224
  whatsapp templates create NAME --language CODE --body TEXT [--example VALUE]...
@@ -214,7 +229,8 @@ the two you are in. Commands default as listed.
214
229
  Delete one at Meta; pull back ones made elsewhere
215
230
  whatsapp failed [--since DATE] [--until DATE] [--error-code CODE]
216
231
  [--error-contains TEXT] [--before ID]
217
- Messages Vatio gave up retrying (default: live)
232
+ Messages Vatio gave up retrying, with your
233
+ external_ref (default: live)
218
234
 
219
235
  Channels:
220
236
  instagram The same, for Instagram
package/lib/http.mjs CHANGED
@@ -124,7 +124,10 @@ export class HttpClient {
124
124
  Accept: "application/json"
125
125
  };
126
126
  const init = { method, headers, signal: AbortSignal.timeout(READ_TIMEOUT_MS) };
127
- if (body !== undefined) {
127
+ // Files go as multipart, whose boundary fetch() writes into the header.
128
+ if (body instanceof FormData) {
129
+ init.body = body;
130
+ } else if (body !== undefined) {
128
131
  headers["Content-Type"] = "application/json";
129
132
  init.body = JSON.stringify(body);
130
133
  }
package/lib/pull.mjs CHANGED
@@ -192,6 +192,7 @@ function linkEntry(raw) {
192
192
  const when = String(row.when ?? "").trim();
193
193
  if (when !== "") entry.when = when;
194
194
  if (isPlainObject(row.values) && Object.keys(row.values).length > 0) entry.values = row.values;
195
+ if (row.button === true) entry.button = true;
195
196
  return entry;
196
197
  }
197
198