mindvest-atlas 0.91.0 → 0.93.0

package/README.md

@@ -30,6 +30,7 @@ atlas options-chain --symbol SPY --expiration 2026-06-20
 atlas historical-contract --symbol NVDA --expiry 2026-07-13 --strike 205 --side call --from 2026-07-06 --to 2026-07-10
 atlas alerts --symbol SPY --name greek_exposure --save-charts ./charts
 atlas flow stream --symbol NVDA
+atlas phone-notify --title "Backtest done" --body "SPY: 61% win" --key backtest   # your own phone
 ```
 
 ## Layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindvest-atlas",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "description": "Atlas CLI \u2014 OAuth login, tool calls, and live alert/flow streaming for the Atlas trading API",
   "type": "module",
   "bin": {

package/src/commands/computer-use.js

@@ -22,6 +22,7 @@
 // a project's script would call, inside the project, so the switch, the claim,
 // the action log and standing back for a person are identically the same rules.
 import { spawn, spawnSync } from 'node:child_process';
+import net from 'node:net';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -59,14 +60,14 @@ const HELP = `atlas computer-use <command>
   press "<name>"        press one of them by name or id (e7), found live [--right] [--double] [--wait <s>]
   type-into "<name>" "<text>" [--enter]   fill a field by its name and read it back
   wait-for "<name>" [--gone] [--timeout <s>]   until a control or text appears (or goes)
-  web-setup             fetch Playwright + Chromium once, for the web verbs
-  web-open <url>        a page in Atlas's browser; your mouse stays yours
-  web-click "<what>"    press a button or link by what it says (or a selector)
-  web-type "<what>" "<text>" [--enter]   fill a field by its label
-  web-read ["<what>"]   the page (or one part) as text
-  web-find "<what>"     where something is on the page
-  web-shot              a sharp picture of the page itself
-  web-close             close Atlas's browser (logins are kept)
+  shortcut <name> [n]   a move by its name, the right keys for this computer: zoom_out, back,
+                        next_tab, next_field, open_list, top, bottom, copy ... (shortcuts lists them)
+  shortcuts             every named move and its keys here
+  fill-form <v> <v>...  a whole form from the keyboard, Tab between: text, "pick:Canada" for a
+                        drop-down, "key:space" for a tick box, "-" to leave a field [--submit] [--keep]
+  pick "<option>"       choose in the drop-down that has the focus, by name [--open]
+  read-text             the words in what is in front, as text (select all, copy)
+  open-link "<words>"   follow a link or press a button on a page by its words, no aiming
   take-over             carry on after a person used it by hand
   stop                  give the computer back
   sessions              this project's recordings, with their ids
@@ -100,14 +101,16 @@ export const OPS = {
   cursor: ['get_cursor', 0],
   changed: ['changed', 0],
   code: ['run_code', 1],
-  'web-setup': ['web_setup', 0],
-  'web-open': ['web_open', 1],
-  'web-click': ['web_click', 1],
-  'web-type': ['web_type', -1],
-  'web-read': ['web_read', -1],
-  'web-find': ['web_find', 1],
-  'web-shot': ['web_shot', 0],
-  'web-close': ['web_close', 0],
+  // ── THE KEYS EVERY APP ALREADY ANSWERS TO (2026-10-04) ────────────────
+  // No separate browser verbs any more: one way of using a computer. A named
+  // move needs no aiming and knows this computer's keys (a Mac's are not
+  // Windows's), and a whole form is one call.
+  shortcut: ['shortcut', -1],
+  shortcuts: ['shortcuts', 0],
+  'fill-form': ['fill_form', -1],
+  pick: ['pick', -1],
+  'read-text': ['read_text', 0],
+  'open-link': ['open_link', -1],
   'take-over': ['take_over', 0],
   ready: ['computer_ready', 0],
   // WAIT ESPECIALLY. A sequence without it cannot pause for a page, which is
@@ -160,6 +163,21 @@ export const OPS = {
   'type-into': ['type_into', -1],
   'wait-for': ['wait_for', -1],
 };
+// Verbs whose words are ONE value inside a do "..." step.
+const PHRASES = ['type', 'note', 'find', 'code', 'controls', 'press', 'wait-for', 'pick', 'open-link'];
+
+/** A form's values as fill_form takes them: "-" leaves a field alone; the
+ *  rest are the words as given ("pick:Canada" and "key:space" are read by the
+ *  helper itself). */
+export function formValues(list) {
+  return (list || []).map((v) => String(v).trim()).map((v) => (v === '-' ? null : v));
+}
+
+/** read-text for a person or a model: the words, then how many there were. */
+function readTextLines(out) {
+  return `${out.text}\n(${out.chars} characters${out.cut ? ', cut short' : ''})`;
+}
+
 // Which values are numbers. Passing "840" as a string to click() would move the
 // pointer nowhere and report success. THE SAME SET THE PYTHON CLI USES: a verb
 // that takes numbers in one runtime and strings in the other is a verb nobody
@@ -221,14 +239,22 @@ export function askServer(job, op, args, root) {
   }
   // A synchronous ask, because this command has nothing else to do until the
   // answer comes and the caller is a plain exit code.
+  //
+  // THE NEWLINES BELOW ARE WRITTEN \\n ON PURPOSE. This is a script inside a
+  // template string: a plain \n there becomes a real line break in the middle
+  // of a quoted string, the child fails to parse, and this returned null for
+  // every command, every time, from 2026-09-06 to 2026-10-04. So this runtime
+  // (the one Atlas Studio bundles) never once used the live process, paid for
+  // a fresh Python per command, and deleted the note on the way out. A test
+  // now talks to a real listener through this function.
   const body = JSON.stringify({ token, op, args: args || [], kwargs: {} });
   const out = spawnSync(process.execPath, ['-e', `
     const net = require('node:net');
     const s = net.connect(${port}, '127.0.0.1');
     let got = '';
     s.setTimeout(120000, () => { s.destroy(); process.exit(3); });
-    s.on('connect', () => s.write(process.argv[1] + '\n'));
-    s.on('data', (d) => { got += d; if (got.includes('\n')) { process.stdout.write(got); s.end(); } });
+    s.on('connect', () => s.write(process.argv[1] + '\\n'));
+    s.on('data', (d) => { got += d; if (got.includes('\\n')) { process.stdout.write(got); s.end(); } });
     s.on('error', () => process.exit(3));
   `, body], { encoding: 'utf8' });
   if (out.status !== 0 || !out.stdout) {
@@ -243,6 +269,97 @@ export function askServer(job, op, args, root) {
   }
 }
 
+/**
+ * The same ask WITHOUT a second process, for a command that can wait for its
+ * answer: this process talks to the live one itself. askServer() starts a node
+ * child for every ask, because it must answer synchronously; that child is a
+ * tenth of a second on a fast machine and more on a slow one, per command.
+ * Resolves to the answer, or null when nobody is listening (and then the note
+ * that pointed nowhere is removed, as askServer does).
+ */
+export function askLive(job, op, args, root) {
+  return new Promise((resolve) => {
+    let note;
+    let port;
+    let token;
+    try {
+      const { dir } = workspace(job || '', root);
+      const session = process.env.ATLAS_COMPUTER_SESSION || shellSession(root);
+      note = path.join(dir, '.computer-use', session, 'serve.json');
+      const n = JSON.parse(fs.readFileSync(note, 'utf8'));
+      port = Number(n.port);
+      token = String(n.token);
+    } catch {
+      resolve(null);
+      return;
+    }
+    let got = '';
+    let done = false;
+    const finish = (answer) => {
+      if (done) return;
+      done = true;
+      if (answer === null) { try { fs.rmSync(note, { force: true }); } catch { /* it may be gone */ } }
+      resolve(answer);
+    };
+    const s = net.connect(port, '127.0.0.1');
+    s.setTimeout(120000, () => { s.destroy(); finish(null); });
+    s.on('connect', () => s.write(JSON.stringify({ token, op, args: args || [], kwargs: {} }) + '\n'));
+    s.on('data', (d) => {
+      got += d;
+      if (!got.includes('\n')) return;
+      s.end();
+      try { finish(JSON.parse(got.trim().split('\n').pop())); } catch { finish(null); }
+    });
+    s.on('error', () => finish(null));
+    s.on('close', () => finish(null));
+  });
+}
+
+/** The interpreter in its no-console form, where one exists (Windows:
+ *  pythonw.exe). Only for a process whose output nobody reads. */
+export function windowless(python, platform = process.platform) {
+  if (platform !== 'win32' || !python.length) return python;
+  const exe = python[0];
+  for (const [stem, quiet] of [['python.exe', 'pythonw.exe'], ['py.exe', 'pyw.exe']]) {
+    if (exe.toLowerCase().endsWith(stem)) {
+      const other = exe.slice(0, -stem.length) + quiet;
+      if (fs.existsSync(other)) return [other, ...python.slice(1)];
+    }
+  }
+  return python;
+}
+
+/**
+ * Leave one process up for this session. Best effort, always: a machine where
+ * this cannot run spawns per action as before. It ends itself after a quarter
+ * of an hour idle, and `stop` ends it at once.
+ */
+export function startServer(job, root) {
+  try {
+    if (askServer(job, 'computer_ready', [], root)) return true; // already up
+    const { dir } = workspace(job || '', root);
+    const venv = venvPython(dir);
+    const python = windowless(venv ? [String(venv)] : [...ambientPython()]);
+    const env = { ...process.env, ...jobEnv(dir), ATLAS_JOB: path.basename(dir) };
+    if (!env.ATLAS_ASK_URL || !env.ATLAS_ASK_TOKEN) {
+      const at = askAddress(root);
+      if (at) { env.ATLAS_ASK_URL = at.url; env.ATLAS_ASK_TOKEN = at.token; }
+    }
+    if (!env.ATLAS_COMPUTER_SESSION) env.ATLAS_COMPUTER_SESSION = shellSession(root);
+    if (!env.ATLAS_COMPUTER_PID) env.ATLAS_COMPUTER_PID = '0';
+    env.PYTHONPATH = [dir, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter);
+    // Before it comes up: it imports pyautogui at the start on purpose.
+    ensureDeps(python, dir, env);
+    const child = spawn(python[0], [...python.slice(1), '-c', 'import atlas_env; atlas_env.serve()'],
+      { cwd: dir, env, stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => { /* slower, not broken */ });
+    child.unref();
+    return true;
+  } catch {
+    return false; // slower, not broken
+  }
+}
+
 /** Run one atlas_env call inside the project, and hand back what it said. */
 /** What using the computer needs, and what it is called when you import it. */
 const NEEDED = [['pyautogui', 'pyautogui'], ['mss', 'mss'], ['Pillow', 'PIL']];
@@ -478,6 +595,13 @@ export function computerUseCommand(args) {
       + "e.note('took the computer')\n"
       + 'print(json.dumps(e.computer_ready(), default=str))\n';
     const out = runInProject(job, code);
+    // AND LEAVE ONE PROCESS UP for the rest of the session. Everything after
+    // this is a message to it rather than a Python start and pyautogui's
+    // imports, which on Windows is most of a second for an action that takes
+    // twenty milliseconds. The Python CLI has done this since September; this
+    // one, the one Atlas Studio bundles, never did, so every command in a chat
+    // paid for a fresh start while the guide said it would not (2026-10-04).
+    if (out === 0) startServer(job);
     if (out === 0) {
       println('');
       println(color.dim('Watching opened in Atlas Studio. Now use it:'));
@@ -572,18 +696,31 @@ export function computerUseCommand(args) {
       const [name] = OPS[verb];
       // A quoted phrase is one value: `type "hello there"` means two words
       // typed, not a word typed twice.
-      let vals = (['type', 'note', 'find', 'code', 'web-open', 'web-click', 'web-read', 'web-find',
-        'controls', 'press', 'wait-for'].includes(verb))
+      let vals = (PHRASES.includes(verb))
         ? (bits.length > 1 ? [bits.slice(1).join(' ')] : [])
         : bits.slice(1).map((v) => (NUMERIC.has(verb) ? Number(v) : v));
       // A name can be several words, so the text comes after a "|":
       // "type-into Last name | Smith". Without one, the first word is the name.
       if (verb === 'type-into') vals = splitTarget(bits.slice(1).join(' '));
+      // "shortcut zoom_out 2": the name, then how many times.
+      if (verb === 'shortcut') vals = bits.length > 2 ? [bits[1], Number(bits[2])] : bits.slice(1);
+      // "fill-form Ada | Lovelace | pick:Canada": one value per field.
+      if (verb === 'fill-form') vals = [formValues(bits.slice(1).join(' ').split('|'))];
       steps.push([name, ...vals]);
     }
-    const code = 'import atlas_env as e, json\n'
-      + `print(json.dumps(e.do(*[tuple(s) for s in json.loads(${JSON.stringify(JSON.stringify(steps))})]), default=str, indent=2))\n`;
-    return runInProject(job, code);
+    // THE LIVE PROCESS FIRST, like every other command: a run of steps was the
+    // one thing that always paid for a fresh Python, which is most of what a
+    // short run costs.
+    return askLive(job, 'do', steps).then((live) => {
+      if (live) {
+        if (live.ok) { println(JSON.stringify(live.out, null, 2)); return 0; }
+        eprintln(color.red(String(live.error || 'That did not work.')));
+        return 1;
+      }
+      const code = 'import atlas_env as e, json\n'
+        + `print(json.dumps(e.do(*[tuple(s) for s in json.loads(${JSON.stringify(JSON.stringify(steps))})]), default=str, indent=2))\n`;
+      return runInProject(job, code);
+    });
   }
 
   if (!OPS[sub]) {
@@ -604,22 +741,34 @@ export function computerUseCommand(args) {
     eprintln(color.red(`${sub} takes ${count} value${count === 1 ? '' : 's'}.`));
     return 1;
   }
-  if (count === -1 && !rest.length && sub !== 'web-read' && sub !== 'controls') {
+  if (count === -1 && !rest.length && sub !== 'controls') {
     eprintln(color.red(`${sub} needs at least one.`));
     return 1;
   }
   let values = rest.map((v) => (NUMERIC.has(sub) ? Number(v) : v));
   // A block of code, a sentence to find, an address: the words are one value.
-  if (['code', 'note', 'find', 'type', 'web-open', 'web-click', 'web-read', 'web-find'].includes(sub) && rest.length > 1) {
+  if (['code', 'note', 'find', 'type', 'open-link'].includes(sub) && rest.length > 1) {
     values = [rest.join(' ')];
   }
+  if (sub === 'shortcut') {
+    // The name, then how many times: `shortcut zoom_out 2`.
+    values = rest.length > 1 ? [rest[0], Number(rest[1])] : [rest[0]];
+    if (rest.length > 2 || (rest.length > 1 && !Number.isFinite(values[1]))) {
+      eprintln(color.red('shortcut takes a name and, if you like, how many times: shortcut zoom_out 2'));
+      return 1;
+    }
+  }
+  // One value per field, as given; then whether to press Enter, and whether to
+  // replace what each field held.
+  if (sub === 'fill-form') values = [formValues(rest), Boolean(flags.submit), !flags.keep];
+  if (sub === 'pick') values = [rest.join(' '), Boolean(flags.open)];
   if (sub === 'press' || sub === 'wait-for' || sub === 'controls') {
     values = rest.length ? [rest.join(' ')] : [];
     if (sub === 'press') {
       values.push(right ? 'right' : 'left', twice ? 2 : 1);
       // How long it may wait for the control to appear, stop being grey, or
       // come out from under something (default 5s).
-      if (flags.wait !== undefined) values.push(null, 1.0, Number(flags.wait));
+      if (flags.wait !== undefined) values.push(null, null, Number(flags.wait));
     }
     if (sub === 'wait-for') {
       values.push(gone, flags.timeout !== undefined ? Number(flags.timeout) : 10);
@@ -633,32 +782,33 @@ export function computerUseCommand(args) {
     values = [rest[0], rest.slice(1).join(' '), enter];
     if (flags.wait !== undefined) values.push(true, null, Number(flags.wait));
   }
-  if (sub === 'web-type') {
-    if (rest.length < 2) {
-      eprintln(color.red('web-type takes the field and the text: web-type "Email" "me@x.com" [--enter]'));
+  // THE LIVE PROCESS FIRST: same function, same rules, without a python start
+  // (and without a second node either: this command can wait for its answer).
+  return askLive(job, name, values).then((answer) => {
+    if (answer) {
+      if (answer.ok) {
+        // THE LIST AS LINES: one control per line is what gets read, and the
+        // same list as JSON is five times the words to read it in.
+        if (sub === 'controls' && answer.out && answer.out.summary) println(answer.out.summary);
+        else if (sub === 'read-text' && answer.out && typeof answer.out.text === 'string') println(readTextLines(answer.out));
+        else if (sub === 'shortcuts' && answer.out) println(Object.entries(answer.out).map(([k, v]) => `${k.padEnd(18)} ${v}`).join('\n'));
+        else println(JSON.stringify(answer.out, null, 2));
+        return 0;
+      }
+      eprintln(color.red(String(answer.error || 'That did not work.')));
       return 1;
     }
-    values = [rest[0], rest.slice(1).join(' '), Boolean(flags.enter)];
-  }
-  // THE LIVE PROCESS FIRST: same function, same rules, without a python start.
-  const answer = askServer(job, name, values);
-  if (answer) {
-    if (answer.ok) {
-      // THE LIST AS LINES: one control per line is what gets read, and the
-      // same list as JSON is five times the words to read it in.
-      if (sub === 'controls' && answer.out && answer.out.summary) println(answer.out.summary);
-      else println(JSON.stringify(answer.out, null, 2));
-      return 0;
-    }
-    eprintln(color.red(String(answer.error || 'That did not work.')));
-    return 1;
-  }
-  // JSON rather than pasting: the text may hold quotes, and a snippet built by
-  // pasting is a snippet that breaks on somebody's password.
-  const code = 'import atlas_env as e, json\n'
-    + `out = e.${name}(*json.loads(${JSON.stringify(JSON.stringify(values))}))\n`
-    + (sub === 'controls'
-      ? 'print(out["summary"] if isinstance(out, dict) and out.get("summary") else json.dumps(out, default=str))\n'
-      : 'print(json.dumps(out, default=str))\n');
-  return runInProject(job, code);
+    // JSON rather than pasting: the text may hold quotes, and a snippet built by
+    // pasting is a snippet that breaks on somebody's password.
+    const code = 'import atlas_env as e, json\n'
+      + `out = e.${name}(*json.loads(${JSON.stringify(JSON.stringify(values))}))\n`
+      + (sub === 'controls'
+        ? 'print(out["summary"] if isinstance(out, dict) and out.get("summary") else json.dumps(out, default=str))\n'
+        : sub === 'read-text'
+          ? 'print(out["text"]); print("(%d characters%s)" % (out["chars"], ", cut short" if out.get("cut") else ""))\n'
+          : sub === 'shortcuts'
+            ? 'print("\\n".join("%-18s %s" % kv for kv in out.items()))\n'
+            : 'print(json.dumps(out, default=str))\n');
+    return runInProject(job, code);
+  });
 }

package/src/config.js

@@ -2,7 +2,7 @@
 import path from 'node:path';
 import os from 'node:os';
 
-export const VERSION = '0.91.0';
+export const VERSION = '0.93.0';
 export const DEFAULT_BASE_URL = 'https://atlasmcp.finmanagerai.com';
 export const DEFAULT_SCOPE = 'atlas broker';
 export const CLIENT_NAME = 'Atlas CLI';

package/src/helpers/atlas_env.js

@@ -329,6 +329,62 @@ export async function mcpTools({ server = "", search = "" } = {}) {
   return atlas("mcp-tools", { server, search });
 }
 
+/**
+ * Tell the owner's PHONE (the MindVest Atlas app). A fixed layout you fill in.
+ *
+ * A title (cut at 40 characters) and up to two short lines; plain words. The
+ * same `key` again REPLACES what is on the phone instead of adding to it.
+ * `progress` (0 to 1) draws a bar. `button` puts ONE button on it (16
+ * characters): pressing it runs this project again, by hand, with the press in
+ * the payload (see phonePress()). `done: true` finishes a card that is up. At
+ * most 30 new ones an hour, so say what matters, not every step.
+ *
+ *     await notify("Backtest done", { body: "SPY: 61% win\n214 trades", key: "backtest" });
+ *     await notify("Backtest running", { key: "backtest", progress: 0.4 });
+ *     await notify("Backtest done", { key: "backtest", button: "Run on QQQ" });
+ *
+ * Returns the tool's answer. `sent` is 0 when the owner switched these off
+ * (Profile, Manage notifications, Studio); that is their choice, not an error.
+ */
+export async function notify(title, { body = "", key = "", progress = null, button = "", done = false } = {}) {
+  const params = { title, body: body || "" };
+  if (key) params.key = key;
+  if (progress !== null && progress !== undefined) params.progress = progress;
+  if (button) {
+    params.button = button;
+    // The project the button starts: this one.
+    params.project = process.env.ATLAS_JOB || "";
+  }
+  if (done) params.done = true;
+  return atlas("phone-notify", params);
+}
+
+/**
+ * The button press this is about, or null.
+ *
+ * When a press STARTED this run it is in the payload: {key, button, title,
+ * pressed_at}. A script that was already running when the button was pressed
+ * (a listener, a long job) is not started twice; it passes the `key` it sent
+ * the button with and is told whether it has been pressed.
+ *
+ *     const press = await phonePress();            // did a button start this run?
+ *     if (await phonePress("backtest")) stop();    // still running: pressed yet?
+ */
+export async function phonePress(key = "") {
+  let started = null;
+  try {
+    started = JSON.parse(process.env.ATLAS_JOB_PAYLOAD || "{}").phone;
+  } catch {
+    started = null;
+  }
+  if (started && typeof started === "object" && (!key || started.key === key)) return started;
+  if (!key) return null;
+  const answer = await atlas("phone-button", { key });
+  return answer && answer.pressed
+    ? { key, button: answer.button || "", pressed_at: answer.pressed_at }
+    : null;
+}
+
 /**
  * Use this project's dashboard the way a person would.
  *
@@ -508,6 +564,22 @@ export const computer = {
   press: (target, opts = {}) => useComputer("press", [String(target)], opts),
   typeInto: (target, text, opts = {}) => useComputer("type_into", [String(target), String(text)], opts),
   waitFor: (target, opts = {}) => useComputer("wait_for", [String(target)], opts),
+  /**
+   * THE KEYS EVERY APP ALREADY ANSWERS TO. A keystroke needs no aiming, and
+   * these know this computer's keys (a Mac's are not Windows's), in any browser.
+   *     await computer.shortcut("zoom_out", 2);      // also back, next_tab, top, bottom, open_list...
+   *     await computer.fillForm(["Ada", "Lovelace", { pick: "Canada" }, null, { key: "space" }], { submit: true });
+   *     const page = await computer.readText();      // { text, chars, cut }
+   *     await computer.openLink("Pricing");          // a link or a button, by its words
+   * fillForm starts where the focus is (press or click the first field), puts
+   * one value in each field with Tab between, and looks once at the end.
+   */
+  shortcut: (name, times = 1) => useComputer("shortcut", [String(name), times]),
+  shortcuts: () => useComputer("shortcuts"),
+  fillForm: (values, opts = {}) => useComputer("fill_form", [values || []], opts),
+  pick: (option, opts = {}) => useComputer("pick", [String(option)], opts),
+  readText: (opts = {}) => useComputer("read_text", [], opts),
+  openLink: (words, opts = {}) => useComputer("open_link", [String(words)], opts),
   click: (x, y) => useComputer("click", [x, y]),
   doubleClick: (x, y) => useComputer("double_click", [x, y]),
   rightClick: (x, y) => useComputer("right_click", [x, y]),