@oalo-ai/cli 0.0.0-stage → 0.1.1

package/src/commands/sources.js

@@ -0,0 +1,377 @@
+import { readFileSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { requireFeature } from "../server.js";
+import { parseRecords } from "../data.js";
+import { dim } from "../events.js";
+
+/**
+ * `oalo sources`: feeds that send Oalo rows from outside (another system, a
+ * webhook, an export), keeping only the fields you choose.
+ *
+ *   oalo sources                                   list them
+ *   oalo sources create <name> --from <file> [--table t] [--id-field f] [--mode upsert|snapshot] [--auth bearer|hmac|url]
+ *   oalo sources create <name> --table <model or table> [--fields a,b] [--keep-from-ai a,b] [--retention days] ...
+ *   oalo sources show <name>                       its address, fields and recent arrivals
+ *   oalo sources create <name> --bot <bot>        documents into a bot's knowledge
+ *   oalo sources push <name> <file.csv|.json|.jsonl>
+ *   oalo sources push <name> <doc.pdf> [more...]   into a knowledge source
+ *   oalo sources remove <name> <document>          a knowledge source's document
+ *   oalo sources fetch <name> <url> [--every 60] [--header "Name: value"]... [--records-at a.b] [--document name]
+ *   oalo sources fetch <name> --now | --off        Oalo fetches the address instead of a sender posting
+ *   oalo sources fields <name> a,b                 keep exactly these of the table's fields
+ *   oalo sources retention <name> <days|off>       a made model drops rows not sent in that many days
+ *   oalo sources rotate <name>                     a new secret; the old one stops now
+ *   oalo sources delete <name> [--wipe]
+ *
+ * A sender posts to the source's address with its secret; `push` sends a file
+ * from here over your CLI token instead.
+ */
+export async function sources(flags, rest, opts = {}) {
+  const sub = rest[1] || "list";
+  const name = rest[2];
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`oalo sources needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+  if (!["list", "create", "show", "push", "remove", "fetch", "fields", "retention", "rotate", "delete"].includes(sub)) return fail(`unknown sources command: ${sub}\n\n${USAGE}`, 2);
+  if (sub !== "list" && !name) return fail(USAGE, 2);
+
+  if (!opts.channel) {
+    try {
+      await requireFeature(url, "sources", "oalo sources");
+    } catch (e) {
+      return fail(e.message, 1);
+    }
+  }
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    switch (sub) {
+      case "list":
+        return await list(ch, flags);
+      case "create":
+        return await create(ch, name, flags);
+      case "show":
+        return await show(ch, name, flags);
+      case "push":
+        return await push(ch, name, rest.slice(3), flags, opts);
+      case "remove":
+        return await remove(ch, name, rest[3], flags);
+      case "fetch":
+        return await fetchCmd(ch, name, rest[3], flags);
+      case "fields":
+        return await fields(ch, name, rest[3], flags);
+      case "retention":
+        return await retention(ch, name, rest[3], flags);
+      case "rotate":
+        return await rotate(ch, name, flags);
+      case "delete":
+        return await del(ch, name, flags);
+    }
+  } catch (e) {
+    return fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+}
+
+const USAGE = [
+  "usage: oalo sources [list]",
+  "       oalo sources create <name> --from <sample file> [--table <new model>] [--id-field <field>] [--mode upsert|snapshot] [--auth bearer|hmac|url]",
+  "       oalo sources create <name> --table <existing model or table> [--fields a,b] [--id-field <field>] [--auth ...]",
+  "         (either form: [--keep-from-ai a,b] [--retention <days>], retention for a new model only)",
+  "       oalo sources show <name> | rotate <name> | delete <name> [--wipe]",
+  "       oalo sources fields <name> a,b | retention <name> <days|off>",
+  "       oalo sources create <name> --bot <bot> [--auth ...]   documents into the bot's knowledge",
+  "       oalo sources push <name> <file.csv|.json|.jsonl>   or, for --bot, <doc.pdf|.docx|.md|.html|.txt> ...",
+  "       oalo sources remove <name> <document>",
+  "       oalo sources fetch <name> <https url> [--every <minutes>] [--header \"Name: value\"] [--records-at <a.b>] [--document <name>]",
+  "       oalo sources fetch <name> --now | --off",
+].join("\n");
+
+const BATCH = 1000;
+const list_ = (v) => (typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : undefined);
+
+async function list(ch, flags) {
+  const { sources: all = [] } = await ch.call("sources:list", {});
+  if (flags.json) return void console.log(JSON.stringify(all, null, 2));
+  if (!all.length) return void console.log("no sources yet. Make one: oalo sources create <name> --from <sample file>");
+  for (const s of all) {
+    if (s.kind === "knowledge") {
+      console.log(`${s.name}  ${dim(`-> ${s.bot}'s knowledge, ${s.auth}, ${s.received_count} documents sent${s.last_received_at ? `, last ${s.last_received_at}` : ""}`)}`);
+      continue;
+    }
+    console.log(`${s.name}  ${dim(`-> ${s.table} (${s.env}), ${s.mode}, ${s.auth}, ${s.received_count} rows${s.last_received_at ? `, last ${s.last_received_at}` : ""}`)}`);
+  }
+}
+
+async function create(ch, name, flags) {
+  const params = { name };
+  for (const [flag, key] of [["bot", "bot"], ["table", "table"], ["id-field", "id_field"], ["mode", "mode"], ["auth", "auth"], ["env", "env"], ["hmac-header", "hmac_header"], ["hmac-format", "hmac_format"]]) {
+    if (flags[flag] === true) return fail(`--${flag} needs a value`, 2);
+    if (typeof flags[flag] === "string") params[key] = flags[flag];
+  }
+  if (flags.fields) params.fields = list_(flags.fields);
+  for (const f of ["keep-from-ai", "retention"]) if (flags[f] === true) return fail(`--${f} needs a value`, 2);
+  if (flags["keep-from-ai"]) params.keep_from_ai = list_(flags["keep-from-ai"]);
+  if (flags.retention) params.retention_days = flags.retention;
+
+  if (typeof flags.from === "string") {
+    const text = readFileSync(flags.from, "utf8");
+    // A sample is enough to read the fields and their types.
+    params.sample = /\.csv$/i.test(flags.from)
+      ? { csv: text.split(/\r?\n/).slice(0, 201).join("\n") }
+      : parseRecords(text, { name: basename(flags.from) }).slice(0, 200);
+  }
+
+  const s = await ch.call("sources:create", params);
+  if (flags.json) return void console.log(JSON.stringify(s, null, 2));
+
+  if (s.kind === "knowledge") {
+    console.log(`made source ${s.name} -> ${s.bot}'s knowledge`);
+    console.log(`  address     ${s.url}`);
+    console.log(`  secret      ${s.secret}`);
+    console.log(dim("\nThe secret is shown only now. Keep it where the sender keeps secrets; `oalo sources rotate` replaces it."));
+    console.log(dim(sendExample(s)));
+    console.log(dim(`Each upload is one document, by name: the same name again replaces it, and DELETE with ?name= removes it. The bot answers from it once it's indexed, live at once. A workflow can start on ${s.event}.`));
+    return;
+  }
+
+  console.log(`made source ${s.name} -> ${s.table} (${s.env})${s.owns_table ? `, a new model` : s.kind === "table" ? `, a plain table` : ""}`);
+  console.log(`  fields      ${Object.entries(s.fields).map(([k, t]) => `${k}:${t}`).join(", ")}`);
+  if (s.keep_from_ai?.length) console.log(`  kept from AI ${s.keep_from_ai.join(", ")}`);
+  if (s.retention_days) console.log(`  retention   rows not sent in ${s.retention_days} days are dropped`);
+  console.log(`  id field    ${s.id_field}${s.mode === "snapshot" ? ", snapshot (each upload is the whole set)" : ""}`);
+  console.log(`  address     ${s.url}`);
+  console.log(`  secret      ${s.secret}`);
+  console.log(dim("\nThe secret is shown only now. Keep it where the sender keeps secrets; `oalo sources rotate` replaces it."));
+  console.log(dim(sendExample(s)));
+  console.log(dim(`Fields a sender adds that aren't listed above are dropped, and each upload says which. A workflow can start on ${s.event}.`));
+}
+
+function sendExample(s) {
+  if (s.kind === "knowledge") {
+    const auth = s.auth === "bearer" ? ` -H "Authorization: Bearer <secret>"` : "";
+    const how = `\nSend: curl -X POST "${s.url}?name=handbook.pdf"${auth} -H "Content-Type: application/pdf" --data-binary @handbook.pdf\n(Word .docx, Markdown, HTML and plain text too; or JSON {"name": "...", "text": "..."}.)`;
+    return s.auth === "hmac" ? `${how}\nThe sender signs the raw body with the secret and sends header ${s.hmac_header}.` : how;
+  }
+  if (s.auth === "url") return `\nSend: curl -X POST "${s.url}" -H "Content-Type: application/json" -d '[{"${s.id_field}": "1", ...}]'`;
+  if (s.auth === "hmac") {
+    const value = s.hmac_format === "base64" ? "<base64 HMAC-SHA256>" : s.hmac_format === "hex" ? "<hex HMAC-SHA256>" : "sha256=<hex HMAC-SHA256>";
+    return `\nThe sender signs the raw body with the secret and sends header ${s.hmac_header}: ${value}`;
+  }
+  return `\nSend: curl -X POST "${s.url}" -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '[{"${s.id_field}": "1", ...}]'\n(CSV with Content-Type: text/csv, or NDJSON with application/x-ndjson.)`;
+}
+
+// One document per file, named by the file. The server reads its text.
+const MAX_DOC = 10_000_000;
+const MAX_UPLOAD = 50_000_000;
+
+// Over 10 MB: an upload address from the Base, the file put there directly,
+// then complete, and its status until it's read (AppBuilder.Sources.Uploads).
+async function uploadDocument(ch, name, doc, type, bytes, opts = {}) {
+  const put = opts.put || ((url, init) => fetch(url, init));
+  const start = await ch.call("sources:upload_start", { name, file: doc, content_type: type, size: bytes.length });
+  const res = await put(start.upload_url, { method: "PUT", headers: start.headers, body: bytes });
+  if (!res.ok) throw new Error(`the upload was refused (HTTP ${res.status})`);
+  await ch.call("sources:upload_complete", { name, upload_id: start.upload_id });
+  const wait = opts.wait || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  for (let i = 0; i < 90; i++) {
+    const s = await ch.call("sources:upload_status", { name, upload_id: start.upload_id });
+    if (s.status === "done") return s.result;
+    if (s.status === "failed") throw new Error(s.error || "it couldn't be read");
+    await wait(2000);
+  }
+  throw new Error("still reading it after 3 minutes; oalo sources show " + name + " lists it once done");
+}
+const DOC_TYPES = { ".pdf": "application/pdf", ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", ".md": "text/markdown", ".markdown": "text/markdown", ".html": "text/html", ".htm": "text/html", ".txt": "text/plain" };
+
+async function pushDocuments(ch, name, files, flags, opts = {}) {
+  const results = [];
+  let failed = 0;
+  for (const file of files) {
+    const doc = basename(file);
+    const type = DOC_TYPES[extname(doc).toLowerCase()];
+    if (!type) {
+      results.push({ document: doc, error: "not a PDF, Word .docx, Markdown, HTML or text file" });
+      failed++;
+      continue;
+    }
+    const bytes = readFileSync(file);
+    if (bytes.length > MAX_UPLOAD) {
+      results.push({ document: doc, error: "over 50 MB" });
+      failed++;
+      continue;
+    }
+    try {
+      results.push(
+        bytes.length > MAX_DOC
+          ? await uploadDocument(ch, name, doc, type, bytes, opts)
+          : await ch.call("sources:push_document", { name, document: doc, content_type: type, content_base64: bytes.toString("base64") }, 120000),
+      );
+    } catch (e) {
+      results.push({ document: doc, error: e.message });
+      failed++;
+    }
+  }
+  if (failed) process.exitCode = 1;
+  if (flags.json) return void console.log(JSON.stringify(results, null, 2));
+  for (const r of results) {
+    console.log(r.error ? `${r.document}: refused: ${r.error}` : `${r.document}: ${r.replaced ? "replaced" : "added"}, ${r.chars} characters, indexing`);
+  }
+}
+
+// Oalo fetches the address on a schedule. The header's value goes to the
+// server once, sealed there; show prints only its name.
+async function fetchCmd(ch, name, url, flags) {
+  for (const f of ["every", "records-at", "document", "relation", "key", "cursor"]) if (flags[f] === true) return fail(`--${f} needs a value`, 2);
+  if (url && /^postgres(ql)?:\/\//.test(url) && !flags.relation) return fail("a database address needs the view or table to read: --relation public.orders_for_oalo", 2);
+  if ([].concat(flags.header ?? []).includes(true)) return fail("--header needs a value", 2);
+  if (flags.off) {
+    await ch.call("sources:set_fetch", { name, off: true });
+    return void console.log(`${name}: no longer fetched. Senders can still post to its address.`);
+  }
+  if (url) {
+    const params = { name, url };
+    if (flags.every) params.every = flags.every;
+    // Repeatable: each --header is one; --header "" clears them.
+    if (flags.header !== undefined) params.headers = [].concat(flags.header).filter((h) => typeof h === "string" && h !== "");
+    if (flags["records-at"]) params.records_at = flags["records-at"];
+    if (flags.document) params.document = flags.document;
+    for (const f of ["relation", "key", "cursor"]) if (flags[f]) params[f] = flags[f];
+    const { fetch: f } = await ch.call("sources:set_fetch", params);
+    if (flags.json && !flags.now) return void console.log(JSON.stringify(f, null, 2));
+    if (f.relation) console.log(`${name}: reads ${f.relation} from ${f.url} every ${f.every_minutes} minutes, by ${f.key}${f.cursor ? `, only rows past the last ${f.cursor} seen` : ", the whole view each time"}`);
+    else console.log(`${name}: fetches ${f.url} every ${f.every_minutes} minutes${f.headers?.length ? `, with header${f.headers.length > 1 ? "s" : ""} ${f.headers.join(", ")}` : ""}${f.records_at ? `, records at ${f.records_at}` : ""}`);
+    if (!flags.now) console.log(dim(`The first fetch is within a minute. An answer that hasn't changed is skipped. \`oalo sources fetch ${name} --now\` fetches at once.`));
+  } else if (!flags.now) {
+    return fail(`usage: oalo sources fetch ${name} <https url> [--every <minutes>] [--header "Name: value"]   or   --now | --off`, 2);
+  }
+  if (flags.now) {
+    const r = await ch.call("sources:fetch_now", { name }, 120000);
+    if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+    if (r.unchanged) return void console.log(`${name}: the answer is the same as last time, so nothing changed.`);
+    if (r.document) return void console.log(`${name}: ${r.document} ${r.replaced ? "replaced" : "added"}, ${r.chars} characters, indexing`);
+    console.log(`${name}: ${r.upserted} of ${r.records} stored${r.deleted ? `, ${r.deleted} deleted (snapshot)` : ""}${r.rejected_count ? `, ${r.rejected_count} rejected` : ""}`);
+    if (r.rejected_count) process.exitCode = 1;
+  }
+}
+
+async function remove(ch, name, doc, flags) {
+  if (!doc) return fail("usage: oalo sources remove <name> <document>", 2);
+  const r = await ch.call("sources:remove_document", { name, document: doc });
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  if (!r.removed) {
+    process.exitCode = 1;
+    return void console.log(`${name} has no document ${doc} (oalo sources show ${name} lists them)`);
+  }
+  console.log(`${doc}: removed from ${name}; the bot stops answering from it now.`);
+}
+
+function printFetch(f) {
+  if (!f) return;
+  if (f.relation) console.log(`  reads     ${f.relation} from ${f.url} every ${f.every_minutes} min, by ${f.key}${f.cursor ? `, cursor ${f.cursor}` : ""}`);
+  else console.log(`  fetches   ${f.url} every ${f.every_minutes} min${f.headers?.length ? `, headers ${f.headers.join(", ")}` : ""}${f.records_at ? `, records at ${f.records_at}` : ""}`);
+  if (f.last_fetched_at) console.log(`            last ${f.last_fetched_at}${f.last_error ? `: ${f.last_error}` : ", ok"}`);
+}
+
+async function show(ch, name, flags) {
+  const s = await ch.call("sources:get", { name });
+  if (flags.json) return void console.log(JSON.stringify(s, null, 2));
+  if (s.kind === "knowledge") {
+    console.log(`${s.name} -> ${s.bot}'s knowledge, ${s.auth}${s.auth === "hmac" ? ` (${s.hmac_header}, ${s.hmac_format})` : ""}`);
+    console.log(`  address   ${s.url}`);
+    console.log(`  event     ${s.event}`);
+    printFetch(s.fetch);
+    console.log(`  documents ${s.documents.length ? "" : "none yet"}`);
+    for (const d of s.documents) console.log(`    ${d.name}  ${dim(`${d.chars} characters, ${d.status}, ${d.updated_at}`)}`);
+    return;
+  }
+  console.log(`${s.name} -> ${s.table} (${s.env}), ${s.mode}, ${s.auth}${s.auth === "hmac" ? ` (${s.hmac_header}, ${s.hmac_format})` : ""}`);
+  console.log(`  address   ${s.url}`);
+  console.log(`  fields    ${Object.entries(s.fields).map(([k, t]) => `${k}:${t}`).join(", ")}  (id: ${s.id_field})`);
+  if (s.keep_from_ai?.length) console.log(`  kept from AI  ${s.keep_from_ai.join(", ")}`);
+  if (s.retention_days) console.log(`  retention ${s.retention_days} days`);
+  console.log(`  event     ${s.event}`);
+  printFetch(s.fetch);
+  console.log(`  stored    ${s.received_count} rows${s.last_received_at ? `, last ${s.last_received_at}` : ""}`);
+  if (s.log?.length) {
+    console.log("\nRecent arrivals:");
+    for (const l of s.log) {
+      const what = l.error ? `refused: ${l.error}` : `${l.upserted} stored${l.rejected ? `, ${l.rejected} rejected` : ""}${l.deleted ? `, ${l.deleted} deleted` : ""}`;
+      console.log(`  ${l.at}  ${l.sender || "?"}  ${l.records} records, ${what}${l.dropped_fields?.length ? dim(`  dropped: ${l.dropped_fields.join(", ")}`) : ""}`);
+    }
+  }
+}
+
+async function push(ch, name, files, flags, opts = {}) {
+  const file = files[0];
+  if (!file) return fail(`usage: oalo sources push ${name} <file.csv|.json|.jsonl>   (a knowledge source: <doc> [more...])`, 2);
+  const s = await ch.call("sources:get", { name });
+  if (s.kind === "knowledge") return pushDocuments(ch, name, files, flags, opts);
+  if (files.length > 1) return fail(`${name} takes records: push one file at a time`, 2);
+  const records = parseRecords(readFileSync(file, "utf8"), { name: basename(file) });
+  if (records.length === 0) return fail(`${file} has no records`, 2);
+  const pushId = randomBytes(9).toString("base64url");
+  const total = { records: 0, upserted: 0, rejected_count: 0, deleted: 0, dropped: new Set(), rejected: [] };
+
+  for (let i = 0; i < records.length; i += BATCH) {
+    const batch = records.slice(i, i + BATCH);
+    const final = i + BATCH >= records.length;
+    const r = await ch.call("sources:push", { name, records: batch, push_id: pushId, final }, 120000);
+    total.records += r.records;
+    total.upserted += r.upserted;
+    total.rejected_count += r.rejected_count;
+    total.deleted += r.deleted;
+    (r.dropped_fields || []).forEach((f) => total.dropped.add(f));
+    total.rejected.push(...(r.rejected || []).map((x) => ({ ...x, index: x.index + i })));
+  }
+
+  if (flags.json) return void console.log(JSON.stringify({ ...total, dropped: [...total.dropped] }, null, 2));
+  console.log(`${name}: ${total.upserted} of ${total.records} stored${total.deleted ? `, ${total.deleted} deleted (snapshot)` : ""}`);
+  if (total.dropped.size) console.log(dim(`  dropped (not one of the source's fields): ${[...total.dropped].join(", ")}`));
+  if (total.rejected_count) {
+    console.log(`  ${total.rejected_count} rejected:`);
+    total.rejected.slice(0, 10).forEach((x) => console.log(`    record ${x.index + 1}: ${x.error}`));
+    process.exitCode = 1;
+  }
+}
+
+async function fields(ch, name, csv, flags) {
+  const want = list_(csv);
+  if (!want?.length) return fail(`usage: oalo sources fields ${name} a,b`, 2);
+  const s = await ch.call("sources:set_fields", { name, fields: want });
+  if (flags.json) return void console.log(JSON.stringify(s, null, 2));
+  console.log(`${name} keeps: ${Object.entries(s.fields).map(([k, t]) => `${k}:${t}`).join(", ")}`);
+  console.log(dim("Its address and secret are unchanged. Other fields a sender sends are dropped."));
+}
+
+async function retention(ch, name, value, flags) {
+  if (!value) return fail("usage: oalo sources retention <name> <days|off>", 2);
+  const days = value === "off" ? null : value;
+  const s = await ch.call("sources:set_retention", { name, days });
+  if (flags.json) return void console.log(JSON.stringify(s, null, 2));
+  console.log(s.retention_days ? `${name}: rows the source hasn't sent in ${s.retention_days} days are dropped each night (04:30 UTC).` : `${name}: rows stay until they're deleted.`);
+}
+
+async function rotate(ch, name, flags) {
+  const r = await ch.call("sources:rotate", { name });
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  console.log(`new secret for ${name}: ${r.secret}`);
+  console.log(`  address   ${r.url}`);
+  console.log(dim("The old secret stopped working just now; give the sender the new one."));
+}
+
+async function del(ch, name, flags) {
+  const r = await ch.call("sources:delete", { name, wipe: flags.wipe === true });
+  if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+  console.log(`deleted source ${name}${r.rows_deleted ? `, and its ${r.rows_deleted} rows` : ""}`);
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/switches.js

@@ -0,0 +1,156 @@
+import { readFileSync } from "node:fs";
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { dim } from "../events.js";
+import { appIdFor } from "../app-ref.js";
+
+/**
+ * `oalo loops` and `oalo flows`: test, switch on or off, and delete, without
+ * pulling and pushing the whole definition.
+ *
+ *   oalo loops test <name> [--sample latest|example] [--input <json|@file>]
+ *   oalo loops on <name> | off <name> | delete <name>
+ *   (each with --app <slug> for a loop pinned to one app)
+ *   oalo flows on <bot> <flow> | off <bot> <flow> | delete <bot> <flow>
+ *
+ * A test runs every step but simulates the ones that send messages or change
+ * records. Starting a loop for real is `oalo run loop <name>`.
+ */
+export async function loops(flags, rest, opts = {}) {
+  const [, sub, name] = rest;
+  if (sub === "runs") return runs(flags, name, opts);
+  if (!["test", "on", "off", "delete"].includes(sub) || !name) {
+    return fail("usage: oalo loops test|on|off|delete <name>, or oalo loops runs [<name>] [--id <run>]", 2);
+  }
+
+  let input;
+  if (sub === "test" && flags.input !== undefined) {
+    try {
+      input = readInput(flags.input);
+    } catch (e) {
+      return fail(e.message, 2);
+    }
+  }
+  if (flags.sample !== undefined && !["latest", "example"].includes(flags.sample)) {
+    return fail("--sample is latest or example", 2);
+  }
+
+  return withChannel(flags, opts, async (ch) => {
+    const appId = await pinnedApp(ch, flags);
+    if (sub === "test") {
+      console.error(dim(`testing ${name}: sends and record changes are simulated`));
+      const params = { name, ...appId, ...(flags.sample ? { sample: flags.sample } : {}), ...(input !== undefined ? { input } : {}) };
+      const r = await ch.call("loops:test", params, 200_000);
+      if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+      printTest(r);
+      if (r.status !== "success") process.exitCode = 1;
+      return;
+    }
+    if (sub === "delete") {
+      const r = await ch.call("loops:delete", { name, ...appId });
+      return void console.log(r.message || `deleted ${name}`);
+    }
+    const r = await ch.call("loops:set_enabled", { name, enabled: sub === "on", ...appId });
+    console.log(r.message || `${name} ${sub}`);
+    if (sub === "on") console.error(dim("it now runs for real whenever its triggers fire"));
+  });
+}
+
+export async function flows(flags, rest, opts = {}) {
+  const [, sub, bot, flow] = rest;
+  if (!["on", "off", "delete"].includes(sub) || !bot || !flow) {
+    return fail("usage: oalo flows on|off|delete <bot> <flow>  (bot: its public id; flow: its name or id)", 2);
+  }
+
+  return withChannel(flags, opts, async (ch) => {
+    const r =
+      sub === "delete"
+        ? await ch.call("chat:bots:flows:delete", { bot_id: bot, flow })
+        : await ch.call("chat:bots:flows:set_enabled", { bot_id: bot, flow, enabled: sub === "on" });
+    console.log(r.message || `${flow} ${sub}`);
+  });
+}
+
+/** `oalo loops runs [name]`: recent runs; `--id <run>`: one run, step by step. */
+async function runs(flags, name, opts) {
+  return withChannel(flags, opts, async (ch) => {
+    const appId = await pinnedApp(ch, flags);
+    if (flags.id !== undefined) {
+      const r = await ch.call("loops:get_run", { run_id: Number(flags.id) });
+      if (flags.json) return void console.log(JSON.stringify(r, null, 2));
+      const run = r.run || {};
+      console.log(`${run.name} run ${run.id}: ${run.status}${run.error ? `: ${oneLine(run.error)}` : ""} ${dim(`(${run.trigger || "?"}, ${String(run.started_at || "").slice(0, 19).replace("T", " ")})`)}`);
+      for (const n of r.nodes || []) {
+        console.log(`  ${n.node_id} ${dim(`(${n.node_type}${n.status ? `, ${n.status}` : ""})`)}`);
+        const out = n.error || n.output;
+        if (out !== undefined && out !== null) console.log(dim(`    ${oneLine(out)}`));
+      }
+      return;
+    }
+    const limit = Number(flags.limit) || 20;
+    const r = await ch.call("loops:list_runs_for_org", { ...(name ? { name } : {}), ...appId, limit });
+    if (flags.json) return void console.log(JSON.stringify(r.runs, null, 2));
+    if (!r.runs?.length) return void console.log(name ? `no runs of ${name} yet` : "no loop runs yet");
+    for (const x of r.runs) {
+      const when = String(x.started_at || "").slice(0, 16).replace("T", " ");
+      const test = x.rehearsal ? ", test" : "";
+      console.log(`${String(x.id).padEnd(7)} ${x.name}  ${x.status}${x.error ? dim(`: ${oneLine(x.error).slice(0, 120)}`) : ""} ${dim(`${when}, ${x.trigger}${test}`)}`);
+    }
+    console.error(dim("one run step by step: oalo loops runs --id <run>"));
+  });
+}
+
+function printTest(r) {
+  console.log(`${r.status}${r.error ? `: ${r.error}` : ""} ${dim(`(run ${r.run_id})`)}`);
+  for (const s of r.steps || []) {
+    const tag = s.error ? "failed" : s.simulated ? "simulated" : "ran";
+    const ms = Number.isFinite(s.duration_ms) ? `, ${s.duration_ms} ms` : "";
+    console.log(`  ${s.node_id} ${dim(`(${s.type}, ${tag}${ms})`)}`);
+    const out = s.error || s.output;
+    if (out !== undefined && out !== null) console.log(dim(`    ${oneLine(out)}`));
+  }
+  if (r.final_output !== undefined && r.final_output !== null) console.log(`output: ${oneLine(r.final_output)}`);
+}
+
+function oneLine(v) {
+  const text = typeof v === "string" ? v : JSON.stringify(v);
+  return text.length > 300 ? text.slice(0, 300) + "..." : text;
+}
+
+/** `--input '{"type": ...}'` or `--input @event.json`. */
+function readInput(raw) {
+  if (raw === true) throw new Error("--input needs JSON, or @file.json");
+  const text = String(raw).startsWith("@") ? readFileSync(String(raw).slice(1), "utf8") : String(raw);
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error("--input isn't valid JSON");
+  }
+}
+
+/** `{app_id}` for `--app <slug>` (a loop pinned to one app), else `{}`. */
+async function pinnedApp(ch, flags) {
+  if (flags["app-id"] !== undefined) throw new Error("--app-id is now --app <slug> (or the app's id), as in `oalo deploy`.");
+  return typeof flags.app === "string" ? { app_id: await appIdFor(ch, flags.app) } : {};
+}
+
+async function withChannel(flags, opts, fn) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+  if (!url || !token) return fail(`this needs a CLI token.\n\n${HOW_TO_CONNECT}`, 2);
+
+  const ch = (opts.channel || ((o) => new OaloChannel(o)))({ url, token });
+  try {
+    await ch.connect();
+    await fn(ch);
+  } catch (e) {
+    fail(e.message, 1);
+  } finally {
+    ch.close();
+  }
+}
+
+function fail(message, code) {
+  console.error(message);
+  process.exitCode = code;
+}

package/src/commands/tail.js

@@ -0,0 +1,84 @@
+import { OaloChannel } from "../channel.js";
+import { resolve as resolveConfig, controlPlane, HOW_TO_CONNECT } from "../config.js";
+import { isInternal, NOISY, format, clock, dim } from "../events.js";
+
+/**
+ * `oalo tail` — watch the workspace while you work.
+ *
+ * The question this answers is "I did a thing; did the thing I expected
+ * happen?" Loop runs, job state, builds and activity all arrive here, so a flow
+ * that never fired shows up as silence rather than as a mystery.
+ *
+ * What it does NOT show: direct writes through the Sync REST API. Those do not
+ * broadcast on this channel. What you will see is their CONSEQUENCES — the loop
+ * that a write triggered, the job it queued.
+ */
+
+export async function tail(flags) {
+  const cfg = resolveConfig(flags);
+  const { url, token } = controlPlane(cfg);
+
+  if (!url || !token) {
+    console.error(
+      `oalo tail needs a CLI token.\n\n${HOW_TO_CONNECT}`,
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const showAll = !!flags.all;
+  const asJson = !!flags.json;
+  const filter = typeof flags.filter === "string" ? flags.filter.toLowerCase() : null;
+
+  const ch = new OaloChannel({ url, token });
+
+  ch.onEvent((event, payload) => {
+    if (isInternal(event)) return;
+    if (!showAll && NOISY.test(event)) return;
+
+    if (filter) {
+      const hay = `${event} ${JSON.stringify(payload ?? {})}`.toLowerCase();
+      if (!hay.includes(filter)) return;
+    }
+
+    if (asJson) {
+      // One JSON object per line so it pipes straight into jq.
+      console.log(JSON.stringify({ at: new Date().toISOString(), event, payload }));
+      return;
+    }
+
+    const at = payload && typeof payload === "object" ? payload.at : null;
+    // If a formatter produced nothing useful, show the payload rather than a
+    // blank line — a silent event is indistinguishable from no event at all.
+    let line = format(event, payload);
+    if (!line || !line.replace(/\x1b\[[0-9;]*m/g, "").trim().replace(/^[^:]*:$/, "")) {
+      const json = JSON.stringify(payload ?? {});
+      line = json === "{}" ? dim("(no payload)") : json.slice(0, 160);
+    }
+    console.log(`${dim(clock(at))}  ${event.padEnd(22)} ${line}`);
+  });
+
+  try {
+    await ch.connect();
+  } catch (e) {
+    console.error(`tail failed: ${e.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!asJson) {
+    console.error(dim(`watching ${url}; ctrl-c stops`));
+    if (!showAll) console.error(dim("(streaming chunk events hidden; --all shows them)"));
+  }
+
+  const stop = () => {
+    ch.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+
+  // Hold the process open. The channel's own heartbeat keeps the socket alive;
+  // this just stops Node from exiting on an empty event loop.
+  await new Promise(() => {});
+}