@oalo-ai/cli 0.0.0-stage → 0.1.1

package/src/args.js

@@ -0,0 +1,67 @@
+import { COMMANDS } from "./help.js";
+
+/**
+ * The command line's flags, read from the help registry so the parser and the
+ * help can't disagree. A flag documented with no value (`--force`) is a
+ * switch: it never takes the next word, so `oalo pull --force flows` keeps
+ * `flows`. A flag documented with `<value>` takes the next word, and one with
+ * `[<value>]` (`--new [<name>]`, `--list [<text>]`) takes it when it isn't
+ * another flag. A flag the registry doesn't list is read like an optional one.
+ */
+
+// `--field`, `--scope`, `--add`, `--remove` and `--header` may repeat; every
+// other flag keeps its last value.
+const REPEATABLE = new Set(["field", "scope", "add", "remove", "header"]);
+
+// Switches the registry doesn't list per command (global ones).
+const GLOBAL_SWITCHES = ["version", "help"];
+
+/** Each documented flag's name and whether it takes a value. */
+export function flagKinds(commands = COMMANDS) {
+  const kinds = new Map();
+  for (const c of commands) {
+    for (const f of c.flags) {
+      const m = f.flag.match(/^--([a-z0-9-]+)\s*(.*)$/);
+      if (!m) continue;
+      const kind = !m[2] ? "switch" : m[2].startsWith("[") ? "optional" : "value";
+      // A name that takes a value anywhere takes it everywhere: treating it as a
+      // switch would drop the value where it's needed.
+      const prev = kinds.get(m[1]);
+      if (!prev || prev === "switch") kinds.set(m[1], kind);
+    }
+  }
+  return kinds;
+}
+
+const KINDS = flagKinds();
+
+export const SWITCHES = new Set([...GLOBAL_SWITCHES, ...[...KINDS].filter(([, k]) => k === "switch").map(([n]) => n)]);
+
+// Flags that always take a value, so a value starting with "-" (`--order -seqnum`)
+// is still theirs. Only another `--flag` ends them.
+export const VALUED = new Set([...KINDS].filter(([, k]) => k === "value").map(([n]) => n));
+
+/** Tiny flag parser: --key value, --switch, -h. No dependency needed. */
+export function parse(argv, { switches = SWITCHES, valued = VALUED } = {}) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      const takes = valued.has(key) ? next !== undefined && !next.startsWith("--") : next && !next.startsWith("-");
+      if (takes && !switches.has(key)) {
+        flags[key] = REPEATABLE.has(key) ? [...(flags[key] || []), next] : next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else if (a === "-h") {
+      flags.help = true;
+    } else {
+      rest.push(a);
+    }
+  }
+  return { flags, rest };
+}

package/src/bot-settings.json

@@ -0,0 +1,468 @@
+{
+  "groups": [
+    "knowledge",
+    "memory",
+    "model",
+    "replies",
+    "limits",
+    "data"
+  ],
+  "settings": [
+    {
+      "clear_word": null,
+      "default": "hybrid",
+      "doc": "How the bot's knowledge reaches the AI each turn. preload packs the best matching passages into the prompt, with no search tools. adhoc gives the AI search tools only, and it searches when it decides to. hybrid does both. none uses no knowledge (the persona only).",
+      "effect": null,
+      "group": "knowledge",
+      "key": "retrieval_strategy",
+      "type": "one of",
+      "values": [
+        "hybrid",
+        "preload",
+        "adhoc",
+        "none"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "fast",
+      "doc": "How documents are cut and searched. fast: small chunks, few hits, no reranking (FAQs). deep: big chunks, more hits, reranked (long or system-level material).",
+      "effect": "re-indexes the bot's knowledge",
+      "group": "knowledge",
+      "key": "retrieval_mode",
+      "type": "one of",
+      "values": [
+        "fast",
+        "deep"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "auto",
+      "doc": "How the knowledge graph adds to what's found. hierarchical always brings the matched passage's parent topics (its governing rules). similar_only adds related passages beside it. auto is hierarchical when the graph has real depth, else similar_only. off adds nothing.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "graph_retrieval",
+      "type": "one of",
+      "values": [
+        "auto",
+        "hierarchical",
+        "similar_only",
+        "off"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": 3,
+      "doc": "How many levels of parent topics come with a match when graph_retrieval brings them, nearest first. Cheap to raise when the documents are small.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "ancestor_preload_depth",
+      "type": "number",
+      "values": [
+        1,
+        32
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "retrieval",
+      "doc": "How each turn's context is put together. retrieval: the frame, the persona and what search finds. graph_resolver: everything the member's tier unlocks in the knowledge graph, whole (high recall, more tokens). graph_focused: the same unlocking, but only the unlocked topics' own text, plus a search over the graph for this turn (token-bounded). The context.* settings below are read by the graph strategies.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.strategy",
+      "type": "one of",
+      "values": [
+        "retrieval",
+        "graph_resolver",
+        "graph_focused"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": [],
+      "doc": "Graph topics that load on top of the frame, each its own way. resident: the topic and everything under it, every turn (rules that must always bind). semantic: only the parts that match this turn, plus a list of all its titles. semantic_expand: semantic, with the question rephrased first for a better match. structural: only what the member's tier unlocks under it. Written `THE RULES=resident; THE MAP=semantic`, or as JSON. Titles match exactly (case aside).",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.frame_segments",
+      "type": "segments",
+      "values": [
+        "resident",
+        "semantic",
+        "semantic_expand",
+        "structural"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": [],
+      "doc": "Graph topics loaded every turn whatever the member's tier, by title, comma-separated.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.resident_subtrees",
+      "type": "list",
+      "values": null
+    },
+    {
+      "clear_word": "default",
+      "default": null,
+      "doc": "How much of each resident topic loads: full (it and everything under it) or shallow (its own text only). default: full for graph_resolver, shallow for graph_focused.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.resident_subtree_depth",
+      "type": "one of",
+      "values": [
+        "full",
+        "shallow"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "band",
+      "doc": "The member field that holds their tier, which decides what the graph strategies unlock.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.tier_field",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": "Band",
+      "doc": "The word before the tier value in the title of each tier's topic: \"Band 3\" for tier 3.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.tier_label",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": "grants",
+      "doc": "The graph relation from a tier's topic to the topics it unlocks.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.grant_rel",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": "recurses_into",
+      "doc": "The graph relation followed from an unlocked topic to the further topics it unlocks.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.recurse_rel",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": "child_of",
+      "doc": "The graph relation from a topic to its parent: what \"everything under it\" follows.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "context.child_rel",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": [],
+      "doc": "Fields of what the conversation has collected (or the member's own data) whose current values drive an extra search every turn, so the knowledge for the member's situation is there however they phrase the question. Comma-separated; empty is off.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "state_fields",
+      "type": "list",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": null,
+      "doc": "Rules that apply to every answer, always in the prompt (they can't depend on a search finding them). @file reads the text from a file; an empty value clears it.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "frame",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "After each reply, remove any passage copied word for word from the knowledge loaded that turn. For bots grounded in material that must not be quoted out.",
+      "effect": null,
+      "group": "knowledge",
+      "key": "protect_canon",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": "auto",
+      "doc": "Whether the AI sees what the conversation has established. auto: shown when there are facts. extract: auto, plus reading every customer message for the facts the bot defines. off: never shown (it's still recorded).",
+      "effect": null,
+      "group": "knowledge",
+      "key": "conversation_record",
+      "type": "one of",
+      "values": [
+        "auto",
+        "extract",
+        "off"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": true,
+      "doc": "Keep what members tell the bot across conversations. The master switch for the three below.",
+      "effect": null,
+      "group": "memory",
+      "key": "member_learning.memory",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "Track the topics each member asks about.",
+      "effect": null,
+      "group": "memory",
+      "key": "member_learning.interests",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "Note when a member's state_fields change between turns.",
+      "effect": null,
+      "group": "memory",
+      "key": "member_learning.trajectory",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "Lean searches toward the member's main interests.",
+      "effect": null,
+      "group": "memory",
+      "key": "member_learning.query_priors",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": "default",
+      "default": null,
+      "doc": "The AI model this bot answers with. default: the workspace's default model.",
+      "effect": null,
+      "group": "model",
+      "key": "model",
+      "type": "text",
+      "values": null
+    },
+    {
+      "clear_word": "default",
+      "default": null,
+      "doc": "How the model is reached: anthropic directly, or opencode (for models from other providers). default: anthropic.",
+      "effect": null,
+      "group": "model",
+      "key": "provider",
+      "type": "one of",
+      "values": [
+        "anthropic",
+        "opencode"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "5m",
+      "doc": "How long the provider keeps the bot's prompt cached. 1h costs more to write and pays off when a member's messages come 5 to 60 minutes apart. The AI sees the same text either way.",
+      "effect": null,
+      "group": "model",
+      "key": "prompt_cache_ttl",
+      "type": "one of",
+      "values": [
+        "5m",
+        "1h"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "handoff",
+      "doc": "Whether the bot answers new conversations. on: it answers. off: a human inbox, the bot never answers. handoff: it answers until it hands the conversation to a person.",
+      "effect": null,
+      "group": "replies",
+      "key": "autopilot_default",
+      "type": "one of",
+      "values": [
+        "on",
+        "off",
+        "handoff"
+      ]
+    },
+    {
+      "clear_word": "default",
+      "default": null,
+      "doc": "How long to wait for more messages before answering, so a burst of short messages gets one reply. 0 answers at once. default: the channel's own.",
+      "effect": null,
+      "group": "replies",
+      "key": "ingestion_window_ms",
+      "type": "number",
+      "values": [
+        0,
+        600000
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "text",
+      "doc": "On WhatsApp and Instagram, which can't show a form: text asks for the answers in the chat, link sends a link to the form on the web.",
+      "effect": null,
+      "group": "replies",
+      "key": "offchannel_widget_fallback",
+      "type": "one of",
+      "values": [
+        "text",
+        "link"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "off",
+      "doc": "On WhatsApp and Instagram: off answers there, link moves the customer to the web chat on the first reply (it costs nothing per message).",
+      "effect": null,
+      "group": "replies",
+      "key": "offchannel_handoff",
+      "type": "one of",
+      "values": [
+        "off",
+        "link"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "handoff",
+      "doc": "When a sale is ready: handoff passes the lead to a salesperson, direct has the bot close it in the chat.",
+      "effect": null,
+      "group": "replies",
+      "key": "offchannel_close",
+      "type": "one of",
+      "values": [
+        "handoff",
+        "direct"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": "tag",
+      "doc": "Flag WhatsApp and Instagram leads about to be lost. tag: a tag and a note only. assign: also assign the conversation to the least busy teammate. off.",
+      "effect": null,
+      "group": "replies",
+      "key": "lead_watch.mode",
+      "type": "one of",
+      "values": [
+        "tag",
+        "assign",
+        "off"
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": 30,
+      "doc": "Minutes a customer can leave the bot waiting before the lead counts as stalled.",
+      "effect": null,
+      "group": "replies",
+      "key": "lead_watch.stalled_minutes",
+      "type": "number",
+      "values": [
+        10,
+        1440
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": 20,
+      "doc": "Hours after the customer's last WhatsApp message to flag the 24-hour window as closing.",
+      "effect": null,
+      "group": "replies",
+      "key": "lead_watch.window_hours",
+      "type": "number",
+      "values": [
+        1,
+        23
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "Show an attach button in the web chat, so members can send files with their message.",
+      "effect": null,
+      "group": "replies",
+      "key": "allow_ambient_uploads",
+      "type": "true or false",
+      "values": null
+    },
+    {
+      "clear_word": "none",
+      "default": null,
+      "doc": "Conversations API requests a minute, per end user. none: the workspace default.",
+      "effect": null,
+      "group": "limits",
+      "key": "api_rate_limit_per_min",
+      "type": "number",
+      "values": [
+        1,
+        100000
+      ]
+    },
+    {
+      "clear_word": "none",
+      "default": null,
+      "doc": "Messages a day per end user. none: no cap.",
+      "effect": null,
+      "group": "limits",
+      "key": "daily_message_cap_per_user",
+      "type": "number",
+      "values": [
+        1,
+        100000
+      ]
+    },
+    {
+      "clear_word": "none",
+      "default": null,
+      "doc": "AI spend a day, in cents, past which the workspace is warned. none: no warning.",
+      "effect": null,
+      "group": "limits",
+      "key": "soft_daily_cap_cents",
+      "type": "number",
+      "values": [
+        1,
+        100000000
+      ]
+    },
+    {
+      "clear_word": "none",
+      "default": null,
+      "doc": "AI spend a day, in cents, past which the bot stops answering until tomorrow. none: no cap.",
+      "effect": null,
+      "group": "limits",
+      "key": "hard_daily_cap_cents",
+      "type": "number",
+      "values": [
+        1,
+        100000000
+      ]
+    },
+    {
+      "clear_word": null,
+      "default": false,
+      "doc": "Let the workspace's dashboards read this bot's member memories and profiles over the Sync API. They are personal data; off unless you need them.",
+      "effect": null,
+      "group": "data",
+      "key": "expose_member_data",
+      "type": "true or false",
+      "values": null
+    }
+  ]
+}

package/src/channel.js

@@ -0,0 +1,162 @@
+import { Socket } from "phoenix";
+import WebSocket from "ws";
+
+/**
+ * Thin client over the Oalo BuilderChannel — the same Phoenix channel the
+ * dashboard drives, which is where the whole build surface lives (there is no
+ * REST API for it).
+ *
+ * Auth is a CLI token (`cli_token` connect param). It is user-bound, so the
+ * server loads the minting user's NodeAccess at join and this client can never
+ * reach further than that user can.
+ */
+export class OaloChannel {
+  constructor({ url, token, timeoutMs = 30000, verbose = !!process.env.OALO_DEBUG }) {
+    if (!url) throw new Error("OALO_URL is required");
+    if (!token) throw new Error("OALO_CLI_TOKEN is required");
+
+    this.wsUrl = url.replace(/^http/, "ws").replace(/\/$/, "") + "/socket";
+    this.token = token;
+    this.timeoutMs = timeoutMs;
+    this.verbose = verbose;
+    this.socket = null;
+    this.channel = null;
+    // In-flight calls, so a channel crash can fail them immediately instead of
+    // leaving each one to wait out its own timeout.
+    this.pending = new Set();
+    this.listeners = new Set();
+  }
+
+  /**
+   * Observe EVERY message the server pushes, including ones this client has no
+   * code for. Deliberately a firehose hook rather than a fixed `channel.on`
+   * list: the server pushes ~25 distinct event names today and gains more, and
+   * a tail that silently omits new ones is worse than useless when you are
+   * debugging why something did not happen.
+   */
+  onEvent(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this.socket = new Socket(this.wsUrl, {
+        params: { cli_token: this.token },
+        transport: WebSocket,
+        heartbeatIntervalMs: 30000,
+        // Quiet by default. Two reasons: Phoenix logs to stdout, which would
+        // corrupt the MCP stdio protocol stream; and in a CLI command the
+        // transport chatter buries the message the user actually needs (it hid
+        // a token-rejected explanation during testing). OALO_DEBUG=1 brings it
+        // back, on stderr.
+        logger: this.verbose
+          ? (kind, msg) => process.stderr.write(`[phoenix] ${kind}: ${msg}\n`)
+          : () => {},
+      });
+
+      let settled = false;
+      const fail = (why) => {
+        if (settled) return;
+        settled = true;
+        reject(new Error(why));
+      };
+
+      this.socket.onError(() => fail("couldn't connect to your Base. Check its address (`oalo whoami`) and that your login is still valid (`oalo login`)."));
+      this.socket.connect();
+
+      // Topic is a free-form discriminator: the server takes org_id and user_id
+      // from socket assigns, never from the topic. Randomised so two clients
+      // don't share a session-scoped event stream.
+      const session = `cli-${Math.random().toString(36).slice(2, 10)}`;
+      this.channel = this.socket.channel(`builder:${session}`, {});
+
+      // A raising handler kills the channel process. Phoenix rejoins, but the
+      // push that caused it never gets a reply — without this every such call
+      // would hang for the full timeout. Fail them now with a usable message.
+      this.channel.onError(() => {
+        const dead = [...this.pending];
+        this.pending.clear();
+        for (const reject of dead) {
+          reject(
+            new Error(
+              "the Base couldn't handle that request (most likely a parameter it didn't expect). If it keeps happening, your CLI may be newer than your Base.",
+            ),
+          );
+        }
+      });
+
+      // onMessage sees everything, replies and internal frames included; the
+      // caller decides what to ignore. Returning the payload is required —
+      // Phoenix uses the return value as the message body.
+      this.channel.onMessage = (event, payload, ref) => {
+        for (const fn of this.listeners) {
+          try {
+            fn(event, payload, ref);
+          } catch {
+            /* a bad listener must not break the transport */
+          }
+        }
+        return payload;
+      };
+
+      this.channel
+        .join(this.timeoutMs)
+        .receive("ok", () => {
+          if (settled) return;
+          settled = true;
+          resolve();
+        })
+        .receive("error", (err) => fail(joinRefused(err)))
+        // Without this the promise hangs forever on a silent server.
+        .receive("timeout", () => fail("your Base didn't answer in time. Try again in a moment."));
+    });
+  }
+
+  /** Push one event and resolve its reply. Rejects on error OR timeout. */
+  call(event, params = {}, timeoutMs = this.timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (!this.channel) return reject(new Error("not connected"));
+
+      this.pending.add(reject);
+      const done = (fn) => (arg) => {
+        this.pending.delete(reject);
+        fn(arg);
+      };
+
+      this.channel
+        .push(event, params, timeoutMs)
+        .receive("ok", done(resolve))
+        .receive(
+          "error",
+          done((err) => {
+            const msg =
+              typeof err?.error === "string" ? err.error : typeof err?.message === "string" ? err.message : JSON.stringify(err);
+            const e = new Error(msg);
+            // The structured reply ({code, current, findings, ...}) for callers
+            // that act on it: push reads a conflict's current version and a
+            // refused save's lint findings from here.
+            e.reply = err;
+            e.code = err?.code;
+            reject(e);
+          }),
+        )
+        // A push with no timeout handler is a hang waiting to happen.
+        .receive("timeout", done(() => reject(new Error(`${event} timed out after ${timeoutMs}ms`))));
+    });
+  }
+
+  close() {
+    try { this.channel?.leave(); } catch { /* already gone */ }
+    try { this.socket?.disconnect(); } catch { /* already gone */ }
+  }
+}
+
+// What a refused join means, in words (not the raw reply).
+export function joinRefused(err) {
+  const reason = typeof err?.reason === "string" ? err.reason : null;
+  if (reason === "unauthorized") return "your login isn't allowed on this Base. Sign in again (`oalo login`), or ask an admin for access.";
+  if (reason === "not_a_member") return "your account isn't a member of this workspace. Ask an admin to invite you, then `oalo login`.";
+  if (reason) return `your Base refused the connection: ${reason.replace(/_/g, " ")}.`;
+  return "your Base refused the connection.";
+}