portal-agent-cli 1.0.1 → 3.0.0

package/LICENSE

@@ -1,21 +1,3 @@
 MIT License
 
-Copyright (c) 2026 your-name
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Copyright (c) 2026

package/README.md

@@ -1,113 +1,55 @@
 # portal-agent
 
-Drive web AI products from the terminal with local tools. Uses a real
-Chromium browser against the provider's own website. No model API key
-required.
+Drive
+```
 
-Supports **DeepSeek** and **ChatGPT**.
+npm install -g portal-agent-cli
 
-## Install
-
-    npm install -g portal-agent-cli
+```
 
 ## Run
 
-    portal-agent --workspace F:/projects/my-app
-
-Or without installing:
-
-    npx portal-agent-cli --workspace F:/projects/my-app
-
-On first run, Chrome opens at the provider site. Log in there. The session
-is stored in `~/.portal-agent/browser` and reused on later runs.
-
-## Commands inside the prompt
-
-    /cd <folder>    change workspace mid-session
-    /pwd            show current workspace
-    /help           show all commands
-    /quit           exit
-
-## Flags
-
-    -w, --workspace DIR    folder the agent works in
-    --provider NAME        deepseek (default) or chatgpt
-    --timeout MS           response timeout (default 180000)
-    --login-timeout MS     login wait (default 600000)
-    --max-steps N          max tool steps per turn (default 8)
+```
 
-## Environment variables
+portal-agent --workspace F:/projects/my-app
 
-    PORTAL_WORKSPACE       same as --workspace
-    PORTAL_BROWSER_PATH    explicit path to Chrome/Edge/Brave
-    PORTAL_PROVIDER        default provider
-    CHROME_PATH            alternative browser path
+```
 
-## One-shot mode
+Or without installing
+```
 
-    portal-agent --workspace F:/proj exec "list the files here"
+npx portal-agent-cli --workspace F:/projects/my-app
 
-## Tools the model can call
+```
 
-- `read_file(path, start_line?, end_line?)`
-- `write_file(path, content)`
-- `edit_file(path, old_string, new_string, replace_all?)`
-- `list_files(path?)`
-- `grep_search(pattern, case_sensitive?)`
-- `shell(command)`
-
-## How it works
-
-Portal launches Chrome, opens the provider site, and injects a system prompt
-telling the model how to call tools. The model writes:
-
-    portal-tool: {"tool":"read_file","args":{"path":"notes.txt"}}
-
-Portal parses that line, runs the tool locally, and sends the result back into
-the same conversation. This repeats until the model stops calling tools.
-
-## Design notes
-
-**Enter-first submit.** The DeepSeek composer has three buttons with the same
-role (DeepThink, Search, Send). Enter always goes to the focused composer, so
-Portal presses Enter first and only falls back to a "Send" button if the
-composer still has text after five seconds.
-
-**Paste-safe insertion.** Prompts are inserted with `keyboard.insertText`,
-which behaves like typing rather than `fill`, which DeepSeek treats as a paste
-and answers with a Cancel/Send confirmation dialog.
-
-**Reply detection.** Portal counts assistant messages before sending, waits
-for the count to rise, then skips any candidate whose text matches the prompt
-it just sent. Without this, DeepSeek echoes your own message back as if it
-were the reply.
+On first run, Chrome opens at the provider site. Log in there. The session
+```
 
-**Backslash repair.** Models copy the Windows backslash style from the
-workspace line in the system prompt. The parser repairs `\t`, `\h`, `\w`,
-`\d`, and `\p` in tool-call JSON before parsing, so `L:\this\file.txt`
-becomes `L:/this/file.txt`.
+portal-agent --workspace F:/proj exec "list the files here"
 
-**Loop breaker.** Identical tool calls are counted per turn. Three calls with
-the same arguments stops the turn.
+```
 
-## Troubleshooting
+## Tools
 
-**`No Chrome found`** -- install Chrome, Edge, or Brave, or set
-`PORTAL_BROWSER_PATH` to the full path of the browser executable.
+| Tool | Description |
+|-|-|
+```
 
-**`Another Chrome window is using the same profile`** -- close every Chrome
-window and try again. Portal uses its own profile in `~/.portal-agent/browser`
-but Chrome's profile lock is global.
+- approval required
+tool: shell
+{
+"command": "npm test"
+}
+allow? yes / always / no:
 
-**`Message stayed in composer`** -- look at the Chrome window. If a
-Cancel/Send bar is showing, click Send once manually. Then resend.
+```
 
-**`No response appeared within the timeout`** -- raise `--timeout`. DeepSeek
-can be slow under load.
+Answer
+```
 
-**Selectors broken after a provider UI update** -- edit `lib/providers.mjs`
-and add or reorder selectors for the affected provider.
+portal-tool: {"tool":"read_file","args":{"path":"notes.txt"}}
 
-## License
+```
 
-MIT
+Portal parses that line, runs the tool locally, and sends the result back
+into the same conversation. This

package/lib/args.mjs

@@ -1,55 +1,89 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { theme } from "./theme.mjs";
 
 export function parseArgs() {
   const a = process.argv.slice(2);
   const o = {
-    ws: process.env.PORTAL_WORKSPACE || process.cwd(),
-    provider: process.env.PORTAL_PROVIDER || "deepseek",
-    maxSteps: 8,
-    timeout: 180000,
-    loginTimeout: 600000,
-    exec: null
+    ws: null,
+    provider: null,
+    model: null,
+    maxSteps: null,
+    timeout: null,
+    loginTimeout: null,
+    exec: null,
+    verbose: false,
+    yolo: false,
+    session: null,
+    resume: null,
+    theme: "auto"
   };
+
   let i = 0;
   while (i < a.length) {
     const t = a[i];
     if (t === "-w" || t === "--workspace") o.ws = a[++i];
-    else if (t === "--provider") o.provider = a[++i];
+    else if (t === "-p" || t === "--provider") o.provider = a[++i];
+    else if (t === "--model") o.model = a[++i];
     else if (t === "--timeout") o.timeout = Number(a[++i]);
     else if (t === "--login-timeout") o.loginTimeout = Number(a[++i]);
     else if (t === "--max-steps") o.maxSteps = Number(a[++i]);
+    else if (t === "--session") o.session = a[++i];
+    else if (t === "--resume") o.resume = a[++i];
+    else if (t === "--theme") o.theme = a[++i];
+    else if (t === "--verbose" || t === "-V") o.verbose = true;
+    else if (t === "--yolo") o.yolo = true;
     else if (t === "exec") { o.exec = a.slice(i + 1).join(" "); break; }
     else if (t === "--help" || t === "-h") { help(); process.exit(0); }
-    else if (t === "--version" || t === "-v") { console.log("1.0.0"); process.exit(0); }
+    else if (t === "--version" || t === "-v") { console.log("2.0.0"); process.exit(0); }
     i++;
   }
-  o.ws = resolve(o.ws);
-  if (!existsSync(o.ws)) {
-    console.error("workspace not found: " + o.ws);
-    process.exit(2);
+
+  if (o.ws) {
+    o.ws = resolve(o.ws);
+    if (!existsSync(o.ws)) {
+      process.stderr.write("workspace not found: " + o.ws + "\n");
+      process.exit(2);
+    }
   }
+
   return o;
 }
 
 function help() {
+  const t = theme;
+  console.log("");
+  console.log(t.bold("portal-agent") + t.dim(" -- drive web AI from the terminal"));
   console.log("");
-  console.log("portal-agent -- drive web AI from the terminal");
+  console.log(t.bold("USAGE"));
+  console.log("  portal-agent [options]");
+  console.log("  portal-agent [options] exec <task>");
   console.log("");
-  console.log("Usage:");
-  console.log("  portal-agent --workspace DIR");
-  console.log("  portal-agent --workspace DIR exec TASK");
+  console.log(t.bold("OPTIONS"));
+  console.log("  -w, --workspace <dir>     folder the agent works in");
+  console.log("  -p, --provider <name>     deepseek | chatgpt | gemini | grok");
+  console.log("  --model <name>            provider-specific model hint");
+  console.log("  --timeout <ms>            response timeout (default 180000)");
+  console.log("  --login-timeout <ms>      login wait (default 600000)");
+  console.log("  --max-steps <n>           max tool steps per turn (default 12)");
+  console.log("  --session <name>          start or reuse a named session");
+  console.log("  --resume <name>           resume a saved session");
+  console.log("  --theme <name>            auto | dark | light");
+  console.log("  -V, --verbose             print config on startup");
+  console.log("  --yolo                    auto-approve every tool call");
+  console.log("  -h, --help                show this help");
+  console.log("  -v, --version             show version");
   console.log("");
-  console.log("Flags:");
-  console.log("  -w, --workspace DIR    folder the agent works in");
-  console.log("  --provider NAME        deepseek (default) or chatgpt");
-  console.log("  --timeout MS           response timeout (default 180000)");
-  console.log("  --login-timeout MS     login wait (default 600000)");
-  console.log("  --max-steps N          max tool steps per turn (default 8)");
+  console.log(t.bold("ENVIRONMENT"));
+  console.log("  PORTAL_WORKSPACE          same as --workspace");
+  console.log("  PORTAL_PROVIDER           default provider");
+  console.log("  PORTAL_BROWSER_PATH       explicit browser executable");
+  console.log("  PORTAL_DEBUG              print stack traces on error");
+  console.log("  PORTAL_YOLO               same as --yolo");
   console.log("");
-  console.log("Environment:");
-  console.log("  PORTAL_WORKSPACE       same as --workspace");
-  console.log("  PORTAL_BROWSER_PATH    explicit path to Chrome/Edge/Brave");
-  console.log("  PORTAL_PROVIDER        default provider");
+  console.log(t.bold("EXAMPLES"));
+  console.log("  portal-agent --workspace F:/projects/app");
+  console.log("  portal-agent -w . -p chatgpt");
+  console.log("  portal-agent exec \"list the files here\"");
   console.log("");
 }

package/lib/browser.mjs

@@ -1,7 +1,7 @@
 import { chromium } from "playwright";
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
-import { resolve, join } from "node:path";
+import { join } from "node:path";
 import { homedir } from "node:os";
 
 const CANDIDATES = [
@@ -11,13 +11,16 @@ const CANDIDATES = [
   "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
   "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe",
   "C:/Program Files/BraveSoftware/Brave-Browser/Application/brave.exe",
+  "C:/Program Files (x86)/BraveSoftware/Brave-Browser/Application/brave.exe",
   "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
   "/Applications/Chromium.app/Contents/MacOS/Chromium",
   "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
   "/usr/bin/google-chrome",
   "/usr/bin/google-chrome-stable",
   "/usr/bin/chromium",
-  "/usr/bin/chromium-browser"
+  "/usr/bin/chromium-browser",
+  "/usr/bin/microsoft-edge"
 ];
 
 export function findBrowser() {
@@ -27,27 +30,48 @@ export function findBrowser() {
   return null;
 }
 
-export async function launch() {
+export function listBrowsers() {
+  const found = [];
+  for (const p of CANDIDATES) {
+    if (p && existsSync(p)) found.push(p);
+  }
+  return found;
+}
+
+export async function launch(opts) {
   const exe = findBrowser();
   if (!exe) {
     throw new Error(
-      "No Chrome, Chromium, Edge, or Brave found. " +
-      "Install one, or set PORTAL_BROWSER_PATH to its full path."
+      "No Chrome, Chromium, Edge, or Brave found.\n" +
+      "Install one, or set PORTAL_BROWSER_PATH to the full path of your browser."
     );
   }
-  const dir = join(homedir(), ".portal-agent", "browser");
-  await mkdir(dir, { recursive: true });
+
+  const profileDir = join(homedir(), ".portal-agent", "browser");
+  await mkdir(profileDir, { recursive: true });
+
   try {
-    return await chromium.launchPersistentContext(dir, {
+    const ctx = await chromium.launchPersistentContext(profileDir, {
       executablePath: exe,
       headless: false,
-      viewport: { width: 1280, height: 900 }
+      viewport: { width: 1280, height: 900 },
+      args: ["--disable-blink-features=AutomationControlled"]
+    });
+
+    // Auto-dismiss dialogs (alert, confirm, prompt) so a stray modal cannot
+    // freeze the session.
+    ctx.on("page", function (page) {
+      page.on("dialog", function (d) {
+        d.dismiss().catch(function () {});
+      });
     });
+
+    return ctx;
   } catch (e) {
     const m = e.message || String(e);
     if (/ProcessSingleton|already running|profile/i.test(m)) {
       throw new Error(
-        "Another Chrome window is using the same profile. " +
+        "Another Chrome window is using the Portal profile.\n" +
         "Close every Chrome window and try again."
       );
     }

package/lib/config.mjs

@@ -0,0 +1,78 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { mkdir, writeFile } from "node:fs/promises";
+
+const DEFAULTS = {
+  provider: "deepseek",
+  maxSteps: 12,
+  timeout: 180000,
+  loginTimeout: 600000,
+  theme: "auto",
+  yolo: false,
+  verbose: false,
+  instructions: ["PORTAL.md", "AGENTS.md", ".portal.md"],
+  ignored: [
+    "node_modules", ".git", ".hg", ".svn", "dist", "build", "out",
+    ".next", ".nuxt", ".turbo", ".cache", "target", "__pycache__",
+    ".venv", "venv", "env", "coverage", ".idea", ".vscode"
+  ]
+};
+
+export function configPath() {
+  return join(homedir(), ".portal-agent", "config.json");
+}
+
+export function readGlobalConfig() {
+  const p = configPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch (e) {
+    return {};
+  }
+}
+
+export async function writeGlobalConfig(obj) {
+  const p = configPath();
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(obj, null, 2), "utf8");
+}
+
+export async function loadConfig(args) {
+  const global = readGlobalConfig();
+
+  const config = {
+    ...DEFAULTS,
+    ...global,
+    ws: args.ws || process.env.PORTAL_WORKSPACE || process.cwd(),
+    provider: args.provider || process.env.PORTAL_PROVIDER || global.provider || DEFAULTS.provider,
+    maxSteps: args.maxSteps || global.maxSteps || DEFAULTS.maxSteps,
+    timeout: args.timeout || global.timeout || DEFAULTS.timeout,
+    loginTimeout: args.loginTimeout || global.loginTimeout || DEFAULTS.loginTimeout,
+    theme: args.theme || global.theme || DEFAULTS.theme,
+    yolo: args.yolo || process.env.PORTAL_YOLO === "true" || global.yolo || DEFAULTS.yolo,
+    verbose: args.verbose || global.verbose || DEFAULTS.verbose,
+    exec: args.exec,
+    session: args.session || null,
+    resume: args.resume || null
+  };
+
+  config.ws = resolve(config.ws);
+  if (!existsSync(config.ws)) {
+    throw new Error("workspace does not exist: " + config.ws);
+  }
+
+  // Per-project config file
+  const localPath = join(config.ws, "portal.config.json");
+  if (existsSync(localPath)) {
+    try {
+      const local = JSON.parse(readFileSync(localPath, "utf8"));
+      Object.assign(config, local);
+    } catch (e) {
+      // ignore malformed local config
+    }
+  }
+
+  return config;
+}

package/lib/exec.mjs

@@ -2,26 +2,31 @@ import { launch } from "./browser.mjs";
 import { getProvider } from "./providers.mjs";
 import { waitForComposer } from "./wait.mjs";
 import { runTurn } from "./turn.mjs";
-import { setWs } from "./tools.mjs";
+import { setWorkspace } from "./tools/path.mjs";
+import { setIgnore } from "./tools/walk.mjs";
+import { loadInstructions } from "./instructions.mjs";
+import { info, error } from "./log.mjs";
 
-export async function runExec(opts) {
-  const provider = getProvider(opts.provider);
-  setWs(opts.ws);
+export async function runExec(config) {
+  const provider = getProvider(config.provider);
+  setWorkspace(config.ws);
+  setIgnore(config.ignored);
+
+  config.instructionsText = await loadInstructions(config.ws);
 
   const ctx = await launch();
   const page = await ctx.newPage();
   page.setDefaultTimeout(30000);
 
+  info("opening " + provider.label + "...");
   await page.goto(provider.url);
-  await waitForComposer(page, provider, opts.loginTimeout);
+  await waitForComposer(page, provider, config.loginTimeout);
 
-  try {
-    await runTurn(page, provider, opts.exec, opts);
-    process.exitCode = 0;
-  } catch (e) {
-    console.error("error: " + (e.message || e));
-    process.exitCode = 1;
-  } finally {
-    await ctx.close().catch(function () {});
-  }
-}
+  const session = {
+    id: "exec-" + Date.now(),
+    ws: config.ws,
+    provider: config.provider,
+    turns: [],
+    approvedAlways: [],
+    startedAt: Date.now(),
+   

package/lib/instructions.mjs

@@ -0,0 +1,44 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+const FILENAMES = ["PORTAL.md", "AGENTS.md", ".portal.md", "CLAUDE.md"];
+
+let cache = null;
+let cacheKey = "";
+
+export async function loadInstructions(ws) {
+  for (const name of FILENAMES) {
+    const path = join(ws, name);
+    let info;
+    try {
+      info = await stat(path);
+    } catch (e) {
+      continue;
+    }
+
+    const key = path + ":" + info.mtimeMs;
+    if (cache && cacheKey === key) return cache;
+
+    try {
+      const content = await readFile(path, "utf8");
+      const trimmed = content.trim();
+      if (!trimmed) return null;
+      cache = [
+        "# Project instructions",
+        "",
+        "The user placed these instructions in " + name + ". Follow them.",
+        "",
+        trimmed
+      ].join("\n");
+      cacheKey = key;
+      return cache;
+    } catch (e) {
+      continue;
+    }
+  }
+  return null;
+}
+
+export function activeInstructionFile() {
+  return cacheKey ? cacheKey.split(":")[0] : null;
+}

package/lib/log.mjs

@@ -0,0 +1,41 @@
+import { theme } from "./theme.mjs";
+
+export function info(s) {
+  process.stdout.write(theme.dim(s) + "\n");
+}
+
+export function warn(s) {
+  process.stdout.write(theme.warn("! " + s) + "\n");
+}
+
+export function error(s) {
+  process.stderr.write(theme.error("x " + s) + "\n");
+}
+
+export function ok(s) {
+  process.stdout.write(theme.ok("+ " + s) + "\n");
+}
+
+export function status(s) {
+  process.stdout.write(theme.dim("  " + s) + "\n");
+}
+
+export function tool(name, args) {
+  const preview = args ? JSON.stringify(args).slice(0, 140) : "";
+  process.stdout.write("\n" + theme.tool("> " + name) + " " + theme.dim(preview) + "\n");
+}
+
+export function toolResult(text, isError) {
+  const body = String(text || "").split("\n").slice(0, 12).join("\n  ");
+  const prefix = isError ? theme.red("  x ") : theme.dim("    ");
+  process.stdout.write(prefix + body + "\n");
+}
+
+export function reply(text) {
+  if (!text) return;
+  process.stdout.write("\n" + theme.cyan("* ") + text + "\n");
+}
+
+export function blank() {
+  process.stdout.write("\n");
+}

package/lib/parse.mjs

@@ -1,53 +1,57 @@
-function findEnd(s, i) {
-  let d = 0;
-  let q = false;
-  let e = false;
+// Tool call protocol:
+//
+//   portal-tool: {"tool":"name","args":{"key":"value"}}
+//
+// Written as plain text on its own line. The parser scans for the literal
+// string "portal-tool", finds the balanced JSON object that follows, and
+// tries to parse it. If parse fails, common Windows backslash escapes are
+// repaired first (models copy "L:\this\file" and JSON sees \t, \h, \w as
+// escapes that blow up the parse).
+
+function findJsonEnd(s, i) {
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
   for (let j = i; j < s.length; j++) {
     const c = s[j];
-    if (e) {
-      e = false;
-      continue;
-    }
-    if (c === "\\") {
-      e = true;
-      continue;
-    }
-    if (c === String.fromCharCode(34)) {
-      q = !q;
-      continue;
-    }
-    if (q) continue;
-    if (c === "{") d++;
+    if (esc) { esc = false; continue; }
+    if (c === "\\") { esc = true; continue; }
+    if (c === String.fromCharCode(34)) { inStr = !inStr; continue; }
+    if (inStr) continue;
+    if (c === "{") depth++;
     else if (c === "}") {
-      d--;
-      if (!d) return j + 1;
+      depth--;
+      if (!depth) return j + 1;
     }
   }
   return -1;
 }
 
-function repair(raw) {
+function repairBackslashes(raw) {
   let s = raw;
-  const bad = ["\\t", "\\h", "\\w", "\\d", "\\p"];
+  const bad = ["\\t", "\\h", "\\w", "\\d", "\\p", "\\v", "\\x", "\\c"];
   for (const b of bad) s = s.split(b).join("/");
   return s;
 }
 
 export function parseCalls(text) {
   const out = [];
+  const seen = new Set();
   const re = /portal-tool[:\s]*/g;
   let m;
   while ((m = re.exec(text))) {
     const b = text.indexOf("{", m.index + m[0].length);
     if (b < 0) continue;
-    const e = findEnd(text, b);
+    const e = findJsonEnd(text, b);
     if (e < 0) continue;
     const raw = text.slice(b, e);
+    if (seen.has(raw)) continue;
+    seen.add(raw);
     try {
       out.push(JSON.parse(raw));
     } catch (x) {
       try {
-        out.push(JSON.parse(repair(raw)));
+        out.push(JSON.parse(repairBackslashes(raw)));
       } catch (y) {
         // skip malformed
       }
@@ -59,3 +63,7 @@ export function parseCalls(text) {
 export function stripCalls(text) {
   return text.replace(/portal-tool[\s\S]*?\n\}/g, "").trim();
 }
+
+export function hasToolCall(text) {
+  return /portal-tool[:\s]*\{/.test(text);
+}