@inetafrica/open-claudia 3.5.19 → 3.5.20

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 3.5.20
+
+The Browser app in Kazee Chat, bot apps v1 (Sumeet, 9 Oct 12:02 EAT: "fine go ahead and push but also ensure you clear the images after they all done"). Kazee Chat opens it through Agent Space, which calls these pod routes with the control token.
+
+- **A person can open the bot's browser from their direct chat.** `POST /api/apps/check` lets the Kazee owner or a chat on auth.json's authorized list open the `browser` app. After its slash commands, the Kazee adapter registers the app with chat-central at `AGENTSPACE_API_URL` + `/apps/browser`. A non-https or in-cluster address is skipped. `OC_BROWSER_APP=off` withdraws the app.
+- **Take over and Hand back.** A driver lock (`browser-driver.json`, 0600) lasts 120 s from the last input, and a second person gets 409. Input events are checked field by field and relayed to the agent-browser stream. A hand-back wakes the bot once in that person's chat. While someone drives, the tool guard refuses the bot's own `agent-browser` commands, except reads.
+- **Teach me.** It records clicks (with the element and a picture), typing per field, keys and scrolls. Characters typed into password or one-time-code fields are never kept. On Stop the bot is woken to post the steps, do one watched run, save the skill, and then run `open-claudia teach finish <id>`, which deletes the pictures and keeps the text. `teach cancel` deletes everything. A sweeper runs at boot and hourly: it deletes pictures after 24 h, stops abandoned recordings after 2 h, and removes recordings after 7 days.
+- **Cards** pass `open: { app, label }` through. The system prompt tells bots that offer the app to send an Open Browser card when they need a person, and never to ask for passwords in chat.
+- **Tests:** `test-browser-control.js`, `test-browser-teach.js`, `test-kazee-bot-apps.js` and `test-web-browser-app.js`, all in `npm test`.
+
 ## 3.5.19
 
 The memory duplicate-check fix as its own release (Sumeet, 8 Oct 13:08 EAT: "I'd rather just push out another release now rather than waiting for another day or so"). Everything in 3.5.18 below comes with it.

package/bin/cli.js

@@ -452,6 +452,11 @@ switch (command) {
     require("./cards").runDecide(args.slice(1));
     break;
   }
+  case "teach": {
+    Promise.resolve(require("./teach").run(args.slice(1)))
+      .catch((e) => { console.error(`teach command failed: ${e.message}`); process.exitCode = 1; });
+    break;
+  }
   case "schedule-wakeup": {
     require("./schedule").runScheduleWakeup(args.slice(1));
     break;
@@ -623,6 +628,7 @@ Send tools (only work inside an active bot-spawned task):
   open-claudia card send <spec|->    Send a Kazee Card (decision, choice, rating, slider, report); answers wake this conversation
   open-claudia card update <id> ...  Close/open a card you sent, add a note, or replace its spec (card example <kind> for specs)
   open-claudia decide "<q>" --option id="label" ...   Queue a decision card for the owner (one at a time; decide list|cancel)
+  open-claudia teach list|show|finish|cancel <id>   Browser recordings from Teach me; finish deletes the pictures, cancel the whole recording
 
 Memory tools:
   open-claudia transcript-search <query>     Ranked FTS5 search over indexed transcripts

package/bin/teach.js

@@ -0,0 +1,78 @@
+// `open-claudia teach ...`: the bot's side of Teach me recordings (core/browser-teach.js). The
+// bot is woken with a recording, posts its steps, checks them with the person, saves the skill,
+// and then deletes the pictures with `teach finish`.
+//
+// Whose recordings a call may use is decided by the RUNNING BOT (loopback whoami over the run's
+// attestation), never by this process's env: an owner turn sees every recording, anyone else's
+// turn only their own, and a process with no live run behind it none.
+
+const { whoami } = require("./loopback-client");
+
+const HELP = `Usage:
+  open-claudia teach list            Browser recordings (Teach me) you may see, newest first
+  open-claudia teach show <id>       The steps as text
+  open-claudia teach finish <id>     Delete the pictures, keep the text steps (once the skill is saved)
+  open-claudia teach cancel <id>     Delete the whole recording
+An owner turn sees every recording; anyone else's turn sees only their own.`;
+
+function fail(message, code = 1) {
+  console.error(message);
+  process.exitCode = code;
+}
+
+async function run(args, { caller = null } = {}) {
+  const teach = require("../core/browser-teach");
+  const sub = args[0];
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    return;
+  }
+  if (!["list", "show", "finish", "cancel"].includes(sub)) return fail(HELP, 2);
+  let who = caller;
+  if (!who) {
+    try { who = await whoami(); } catch (_) { who = null; }
+  }
+  if (!who || who.attributed !== true) {
+    return fail("⛔ teach: this process is not attributed to a chat turn of this bot, so it cannot tell whose recordings it may use. Run it from the bot's turn.", 3);
+  }
+  const userId = who.owner === true ? null : String(who.userId || "");
+  if (userId === "") return fail("⛔ teach: this turn has no person to match recordings to.", 3);
+
+  if (sub === "list") {
+    const list = teach.listRecordings({ userId });
+    if (!list.length) {
+      console.log("No recordings.");
+      return;
+    }
+    for (const r of list) {
+      const pictures = r.picturesDeleted ? "pictures deleted" : "pictures kept";
+      console.log(`${r.id}  ${String(r.status).padEnd(9)} ${String(r.steps).padStart(3)} steps  ${pictures.padEnd(16)} ${r.startedAt}  "${teach.cleanText(r.title, 80).replace(/"/g, "'")}"`);
+    }
+    return;
+  }
+
+  const id = args[1];
+  if (!teach.validId(id)) return fail(`teach ${sub}: give a recording id (open-claudia teach list)`, 2);
+  const rec = teach.getRecording(id, { userId });
+  if (!rec) return fail(`teach ${sub}: no recording ${id} that this turn may use`);
+
+  if (sub === "show") {
+    console.log(teach.formatRecording(rec));
+    return;
+  }
+  if (sub === "finish") {
+    const result = teach.finishRecording(id);
+    if (!result.ok) {
+      return fail(result.error === "still-recording"
+        ? `teach finish: ${id} is still recording; it can be finished once it is stopped`
+        : `teach finish: no recording ${id}`);
+    }
+    console.log(`Finished ${id}: ${result.removed} picture${result.removed === 1 ? "" : "s"} deleted, ${result.recording.steps.length} text steps kept.`);
+    return;
+  }
+  const result = teach.cancelRecording(id);
+  if (!result.ok) return fail(`teach cancel: no recording ${id}`);
+  console.log(`Cancelled ${id}: the recording and its pictures are deleted.`);
+}
+
+module.exports = { run, HELP };

package/bot.js

@@ -275,6 +275,8 @@ async function safeModeBoot() {
       console.error(`Adapter ${adapter.id} failed to start in safe mode:`, e.message);
     }
   }
+  // Teach-me pictures are still deleted on schedule: it only removes files, never runs a turn.
+  try { require("./core/browser-teach").startRetentionSweeper(); } catch (e) { console.error("Teach-me retention sweeper start failed:", e.message); }
   const alert = safeBoot.formatSafeModeAlert({ version: CURRENT_VERSION });
   console.error(alert);
   const tg = adapters.find((a) => a.type === "telegram");
@@ -391,6 +393,11 @@ async function safeModeBoot() {
   // Kazee Cards: snoozed owner decisions are asked again when due.
   try { require("./core/cards").startDecisionPump(registry); } catch (e) { console.error("Decision pump start failed:", e.message); }
 
+  // Browser app: a driver whose panel went quiet hands the browser back (30 s sweep), and
+  // Teach-me pictures and old recordings are deleted on schedule (boot + hourly).
+  try { require("./core/browser-control").startSweeper(); } catch (e) { console.error("Browser lock sweeper start failed:", e.message); }
+  try { require("./core/browser-teach").startRetentionSweeper(); } catch (e) { console.error("Teach-me retention sweeper start failed:", e.message); }
+
   // This incarnation counts as healthy once it survives the stable window —
   // resets the crash-loop streak the safe-mode gate counts at boot.
   setTimeout(() => { try { safeBoot.markBootStable(); } catch (e) {} }, safeBoot.STABLE_UPTIME_MS).unref();

package/channels/kazee/adapter.js

@@ -1750,6 +1750,36 @@ class KazeeAdapter {
     } catch (e) {
       console.error("Kazee registerCommands failed:", e.message);
     }
+    await this.registerApps();
+  }
+
+  // Bot apps (chat-central PUT /bot/:botId/apps, the same shape as commands): with Agent Space
+  // configured, the Browser app, opened from the Apps button of a direct chat with this bot or a
+  // card's Open button (core/bot-apps.js). OC_BROWSER_APP=off sends an empty list. An
+  // AGENTSPACE_API_URL that is not a public https address is skipped with one log line (chat-central
+  // would refuse it). An older chat-central answers 404; that, or any failure, is logged once and
+  // otherwise ignored.
+  async registerApps(env = process.env) {
+    const { apps, skip } = require("../../core/bot-apps").registrationPlan(env);
+    if (skip && !this._appsSkipLogged) {
+      this._appsSkipLogged = true;
+      console.error(`Kazee registerApps skipped: ${skip}. The Browser app stays hidden.`);
+    }
+    if (!apps || !this.botUserId) return null;
+    try {
+      const res = await this._request("PUT", `/bot/${this.botUserId}/apps`, { apps });
+      if (apps.length) console.log(`Kazee bot apps registered: ${apps.map((a) => a.key).join(", ")}`);
+      return res;
+    } catch (e) {
+      if (!this._appsFailureLogged) {
+        this._appsFailureLogged = true;
+        const old = / → 404:/.test(String(e.message || ""));
+        console.error(old
+          ? "Kazee registerApps: this chat-central has no bot apps yet (404); the Browser app stays hidden."
+          : `Kazee registerApps failed (the Browser app stays hidden): ${String(e.message || e).slice(0, 300)}`);
+      }
+      return null;
+    }
   }
 
   // ── HTTP helpers ────────────────────────────────────────────────

package/core/bot-apps.js

@@ -0,0 +1,133 @@
+// Bot apps in Kazee Chat (SPEC "Bot apps v1", contracts C1 and C8).
+//
+// The bot registers the apps it offers with chat-central (PUT /bot/:botId/apps, done by the
+// Kazee adapter after its slash commands), and Kazee Chat shows them behind an Apps button in
+// a direct chat with the bot. Opening one goes through Agent Space (the front door), which asks
+// this bot, over the control token, whether that person may use it: checkAccess() below.
+//
+// v1 has one app, "browser": the bot's own agent-browser, shown live, with Take over and
+// Teach me (core/browser-control.js, core/browser-teach.js). OC_BROWSER_APP=off withdraws it:
+// the next registration sends an empty list and every check answers "not allowed".
+
+const BROWSER_APP_KEY = "browser";
+const ID_RE = /^[A-Za-z0-9._:-]{1,100}$/;
+
+function browserAppEnabled(env = process.env) {
+  return String(env.OC_BROWSER_APP || "").trim().toLowerCase() !== "off";
+}
+
+// An address only reachable inside the cluster or this machine (a Service name such as
+// agentspace-backend.<ns>.svc, localhost, an IP): no person's Kazee Chat can open a page there.
+function internalHost(hostname) {
+  const host = String(hostname || "").toLowerCase().replace(/\.$/, "");
+  if (!host.includes(".") || host.startsWith("[")) return true; // a bare Service name, or IPv6
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return true;
+  return /(^|\.)(localhost|local|internal|svc|cluster\.local)$/.test(host);
+}
+
+// Why AGENTSPACE_API_URL cannot carry the page, or "" when it can. chat-central accepts only
+// https addresses on its allowed origins, so anything else would be refused there anyway.
+function browserAppUrlProblem(apiUrl) {
+  let u;
+  try { u = new URL(String(apiUrl || "").trim()); } catch (_) { return "it is not a URL"; }
+  if (u.protocol !== "https:") return "it is not https";
+  if (internalHost(u.hostname)) return "it is an in-cluster address";
+  return "";
+}
+
+// The page lives on Agent Space's API host: <AGENTSPACE_API_URL without trailing slash> +
+// "/apps/browser". Every live pod has AGENTSPACE_API_URL=https://api.agentspace.kazee.africa/api,
+// so the page is https://api.agentspace.kazee.africa/api/apps/browser. A bare origin means
+// "/api", the same path base the pod's other Agent Space calls use (core/cluster-client.js).
+function browserAppUrl(apiUrl) {
+  if (browserAppUrlProblem(apiUrl)) return null;
+  const u = new URL(String(apiUrl).trim());
+  const base = u.pathname.replace(/\/+$/, "") || "/api";
+  return `${u.origin}${base}/apps/browser`;
+}
+
+// What to do with chat-central, and why not:
+//   { apps: null }              nothing (no Agent Space, so no page to open)
+//   { apps: null, skip: <why> } nothing: AGENTSPACE_API_URL is not a public https address
+//   { apps: [] }                withdraw (OC_BROWSER_APP=off)
+//   { apps: [<browser>] }       offer the Browser app
+function registrationPlan(env = process.env) {
+  const raw = String(env.AGENTSPACE_API_URL || "").trim();
+  if (!raw) return { apps: null, skip: null };
+  if (!browserAppEnabled(env)) return { apps: [], skip: null };
+  const problem = browserAppUrlProblem(raw);
+  if (problem) {
+    let origin = "";
+    try { origin = new URL(raw).origin; } catch (_) { origin = ""; }
+    const shown = origin && origin !== "null" ? ` (${origin})` : "";
+    return { apps: null, skip: `AGENTSPACE_API_URL${shown} cannot carry the Browser page: ${problem}, and chat-central only accepts public https app addresses` };
+  }
+  return { apps: [{ key: BROWSER_APP_KEY, title: "Browser", url: browserAppUrl(raw), icon: "globe" }], skip: null };
+}
+
+// What to register with chat-central: null = do nothing, [] = withdraw, else the Browser app.
+function appsToRegister(env = process.env) {
+  return registrationPlan(env).apps;
+}
+
+function ownerUserId() {
+  try {
+    const value = require("./config").config.KAZEE_OWNER_USER_ID;
+    if (value) return String(value);
+  } catch (_) { /* fall back to the process env */ }
+  return String(process.env.KAZEE_OWNER_USER_ID || "");
+}
+
+function ownerName() {
+  try {
+    const owner = (require("./people").owners() || [])[0];
+    return owner && owner.name ? String(owner.name) : "";
+  } catch (_) {
+    return "";
+  }
+}
+
+// The authorized list of auth.json, read under its store lock so a roster change in flight is
+// never half seen (core/access.js mutateAuth holds the same lock).
+function authorizedEntries() {
+  const { loadAuth } = require("./access");
+  const { withFileLock } = require("./fsutil");
+  const { AUTH_FILE } = require("./config");
+  return withFileLock(AUTH_FILE, () => loadAuth().authorized);
+}
+
+// C1: may this person open this app in this direct chat? Agent Space has already checked with
+// chat-central that `userId` is the person in the direct chat `chatId` with this bot, so:
+//   - the Kazee owner (KAZEE_OWNER_USER_ID) is allowed, role "owner";
+//   - a chat in auth.json's authorized list is allowed, role "user" ("owner" when that entry is
+//     an owner entry), with the name the roster has for it;
+//   - anyone else, and any app other than "browser", is not.
+function checkAccess({ app, chatId, userId } = {}) {
+  const no = { allowed: false, role: null, name: null };
+  if (app !== BROWSER_APP_KEY || !browserAppEnabled()) return no;
+  const chat = String(chatId || "");
+  const user = String(userId || "");
+  if (!ID_RE.test(chat) || !ID_RE.test(user)) return no;
+  let entries = [];
+  try { entries = authorizedEntries(); } catch (_) { entries = []; }
+  const entry = entries.find((a) => a && String(a.chatId) === chat) || null;
+  const owner = ownerUserId();
+  if (owner && user === owner) {
+    return { allowed: true, role: "owner", name: String((entry && entry.name) || ownerName() || "") };
+  }
+  if (entry) {
+    return { allowed: true, role: entry.isOwner === true ? "owner" : "user", name: String(entry.name || "") };
+  }
+  return no;
+}
+
+module.exports = {
+  BROWSER_APP_KEY,
+  ID_RE,
+  appsToRegister,
+  browserAppEnabled,
+  browserAppUrl,
+  browserAppUrlProblem,
+  checkAccess,
+  registrationPlan,
+};