portal-agent-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,113 @@
+# 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.
+
+Supports **DeepSeek** and **ChatGPT**.
+
+## 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_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
+
+    portal-agent --workspace F:/proj exec "list the files here"
+
+## 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.
+
+**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`.
+
+**Loop breaker.** Identical tool calls are counted per turn. Three calls with
+the same arguments stops the turn.
+
+## Troubleshooting
+
+**`No Chrome found`** -- install Chrome, Edge, or Brave, or set
+`PORTAL_BROWSER_PATH` to the full path of the browser executable.
+
+**`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.
+
+**`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.
+
+**Selectors broken after a provider UI update** -- edit `lib/providers.mjs`
+and add or reorder selectors for the affected provider.
+
+## License
+
+MIT

package/lib/args.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+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
+  };
+  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 === "--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 === "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); }
+    i++;
+  }
+  o.ws = resolve(o.ws);
+  if (!existsSync(o.ws)) {
+    console.error("workspace not found: " + o.ws);
+    process.exit(2);
+  }
+  return o;
+}
+
+function help() {
+  console.log("");
+  console.log("portal-agent -- drive web AI from the terminal");
+  console.log("");
+  console.log("Usage:");
+  console.log("  portal-agent --workspace DIR");
+  console.log("  portal-agent --workspace DIR exec TASK");
+  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("");
+  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("");
+}

package/lib/browser.mjs

@@ -0,0 +1,56 @@
+import { chromium } from "playwright";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+
+const CANDIDATES = [
+  process.env.PORTAL_BROWSER_PATH,
+  process.env.CHROME_PATH,
+  "C:/Program Files/Google/Chrome/Application/chrome.exe",
+  "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",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser"
+];
+
+export function findBrowser() {
+  for (const p of CANDIDATES) {
+    if (p && existsSync(p)) return p;
+  }
+  return null;
+}
+
+export async function launch() {
+  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."
+    );
+  }
+  const dir = join(homedir(), ".portal-agent", "browser");
+  await mkdir(dir, { recursive: true });
+  try {
+    return await chromium.launchPersistentContext(dir, {
+      executablePath: exe,
+      headless: false,
+      viewport: { width: 1280, height: 900 }
+    });
+  } 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. " +
+        "Close every Chrome window and try again."
+      );
+    }
+    throw new Error("Failed to launch Chromium: " + m);
+  }
+}

package/lib/exec.mjs

@@ -0,0 +1,27 @@
+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";
+
+export async function runExec(opts) {
+  const provider = getProvider(opts.provider);
+  setWs(opts.ws);
+
+  const ctx = await launch();
+  const page = await ctx.newPage();
+  page.setDefaultTimeout(30000);
+
+  await page.goto(provider.url);
+  await waitForComposer(page, provider, opts.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 () {});
+  }
+}

package/lib/parse.mjs

@@ -0,0 +1,61 @@
+function findEnd(s, i) {
+  let d = 0;
+  let q = false;
+  let e = 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++;
+    else if (c === "}") {
+      d--;
+      if (!d) return j + 1;
+    }
+  }
+  return -1;
+}
+
+function repair(raw) {
+  let s = raw;
+  const bad = ["\\t", "\\h", "\\w", "\\d", "\\p"];
+  for (const b of bad) s = s.split(b).join("/");
+  return s;
+}
+
+export function parseCalls(text) {
+  const out = [];
+  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);
+    if (e < 0) continue;
+    const raw = text.slice(b, e);
+    try {
+      out.push(JSON.parse(raw));
+    } catch (x) {
+      try {
+        out.push(JSON.parse(repair(raw)));
+      } catch (y) {
+        // skip malformed
+      }
+    }
+  }
+  return out;
+}
+
+export function stripCalls(text) {
+  return text.replace(/portal-tool[\s\S]*?\n\}/g, "").trim();
+}

package/lib/paste.mjs

@@ -0,0 +1,67 @@
+import { sleep } from "./wait.mjs";
+
+export async function dismissPaste(page) {
+  const btns = page.locator("button, [role=button]");
+  let total = 0;
+  try {
+    total = await btns.count();
+  } catch (e) {
+    return;
+  }
+  if (total === 0 || total > 300) return;
+
+  for (let i = 0; i < total; i++) {
+    const b = btns.nth(i);
+    let text = "";
+    try {
+      text = ((await b.textContent()) || "").trim();
+    } catch (e) {
+      continue;
+    }
+    if (text !== "Cancel") continue;
+
+    for (let j = 0; j < total; j++) {
+      if (j === i) continue;
+      const sib = btns.nth(j);
+      let st = "";
+      try {
+        st = ((await sib.textContent()) || "").trim();
+      } catch (e) {
+        continue;
+      }
+      if (st === "Send") {
+        try {
+          await sib.click({ timeout: 1500 });
+          await sleep(200);
+          return;
+        } catch (e) {
+          // fall through
+        }
+      }
+    }
+
+    try {
+      await page.keyboard.press("Enter");
+      await sleep(150);
+    } catch (e) {
+      // ignore
+    }
+    return;
+  }
+}
+
+export async function composerEmpty(input, ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    let v = "";
+    try {
+      v = await input.inputValue();
+    } catch (e) {
+      // contenteditable composers have no inputValue. Treat as sent.
+      return true;
+    }
+    if (!v || v.length === 0) return true;
+    await sleep(150);
+  }
+  return false;
+}

package/lib/providers.mjs

@@ -0,0 +1,29 @@
+export const PROVIDERS = {
+  deepseek: {
+    id: "deepseek",
+    label: "DeepSeek",
+    url: "https://chat.deepseek.com/",
+    input: "textarea",
+    submit: "button[aria-label=Send]",
+    response: "div.ds-markdown",
+    paste: true
+  },
+  chatgpt: {
+    id: "chatgpt",
+    label: "ChatGPT",
+    url: "https://chatgpt.com/",
+    input: "#prompt-textarea",
+    submit: "button[data-testid=send-button]",
+    response: "[data-message-author-role=assistant]",
+    paste: false
+  }
+};
+
+export function getProvider(id) {
+  const p = PROVIDERS[id];
+  if (!p) {
+    const names = Object.keys(PROVIDERS).join(", ");
+    throw new Error("unknown provider: " + id + ". Available: " + names);
+  }
+  return p;
+}

package/lib/repl.mjs

@@ -0,0 +1,119 @@
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { launch } from "./browser.mjs";
+import { getProvider } from "./providers.mjs";
+import { waitForComposer } from "./wait.mjs";
+import { runTurn } from "./turn.mjs";
+import { setWs, getWs } from "./tools.mjs";
+
+export async function runRepl(opts) {
+  const provider = getProvider(opts.provider);
+  setWs(opts.ws);
+
+  console.log("");
+  console.log("Portal -- web AI in your terminal");
+  console.log("workspace: " + getWs());
+  console.log("provider:  " + provider.label);
+  console.log("");
+
+  const ctx = await launch();
+  const page = await ctx.newPage();
+  page.setDefaultTimeout(30000);
+
+  console.log("opening " + provider.label + "...");
+  await page.goto(provider.url);
+  console.log("");
+  console.log("Log in to " + provider.label + " in the Chrome window.");
+  console.log("Waiting up to " + Math.round(opts.loginTimeout / 1000) + "s.");
+  console.log("");
+
+  await waitForComposer(page, provider, opts.loginTimeout);
+
+  console.log("+ " + provider.label + " ready");
+  console.log("type /help for commands");
+  console.log("");
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: "> "
+  });
+  rl.prompt();
+
+  let busy = false;
+
+  rl.on("line", async function (line) {
+    const t = line.trim();
+
+    if (busy) {
+      rl.prompt();
+      return;
+    }
+    if (!t) {
+      rl.prompt();
+      return;
+    }
+    if (t === "/quit" || t === "/exit") {
+      rl.close();
+      return;
+    }
+    if (t === "/help") {
+      help();
+      rl.prompt();
+      return;
+    }
+    if (t === "/pwd") {
+      console.log(getWs());
+      rl.prompt();
+      return;
+    }
+    if (t.slice(0, 4) === "/cd ") {
+      changeDir(t.slice(4).trim(), rl);
+      return;
+    }
+
+    busy = true;
+    try {
+      await runTurn(page, provider, t, opts);
+    } catch (e) {
+      console.log("x " + (e.message || e));
+    }
+    busy = false;
+    console.log("");
+    rl.prompt();
+  });
+
+  rl.on("close", async function () {
+    console.log("");
+    console.log("closing browser...");
+    await ctx.close().catch(function () {});
+    process.exit(0);
+  });
+}
+
+function help() {
+  console.log("  /cd <folder>   change workspace");
+  console.log("  /pwd           show current workspace");
+  console.log("  /help          show this help");
+  console.log("  /quit          exit");
+}
+
+function changeDir(target, rl) {
+  if (!target) {
+    console.log("usage: /cd <folder>");
+    console.log("current: " + getWs());
+    rl.prompt();
+    return;
+  }
+  const clean = target.replace(/^"|"$/g, "");
+  const abs = resolve(clean);
+  if (!existsSync(abs)) {
+    console.log("not found: " + abs);
+    rl.prompt();
+    return;
+  }
+  setWs(abs);
+  console.log("workspace: " + getWs());
+  rl.prompt();
+}

package/lib/send.mjs

@@ -0,0 +1,88 @@
+import { sleep, norm } from "./wait.mjs";
+import { dismissPaste, composerEmpty } from "./paste.mjs";
+
+export async function send(page, provider, prompt, timeoutMs) {
+  const input = page.locator(provider.input).last();
+  await input.waitFor({ state: "visible", timeout: 30000 });
+  const before = await page.locator(provider.response).count();
+
+  await input.focus();
+  try {
+    await page.keyboard.press("Control+A");
+    await page.keyboard.press("Delete");
+  } catch (e) {
+    // composer may be empty
+  }
+
+  await page.keyboard.insertText(prompt);
+  await sleep(300);
+
+  if (provider.paste) await dismissPaste(page);
+
+  try {
+    await input.press("Enter");
+  } catch (e) {
+    // fall through to button
+  }
+
+  let ok = await composerEmpty(input, 5000);
+
+  if (!ok) {
+    const btn = page.locator(provider.submit).last();
+    try {
+      if (await btn.isVisible({ timeout: 1500 })) await btn.click();
+    } catch (e) {
+      // no button
+    }
+    ok = await composerEmpty(input, 3000);
+  }
+
+  if (!ok) {
+    throw new Error(
+      "Message stayed in composer. Look at the Chrome window: if a " +
+      "Cancel/Send bar is showing, click Send manually once, then resend."
+    );
+  }
+
+  const want = norm(prompt);
+  const end = Date.now() + timeoutMs;
+  let appeared = false;
+
+  while (Date.now() < end) {
+    const c = await page.locator(provider.response).count();
+    if (c > before) {
+      appeared = true;
+      break;
+    }
+    await sleep(300);
+  }
+
+  if (!appeared) throw new Error("No response appeared within the timeout.");
+
+  let last = "";
+  let stab = Date.now();
+
+  while (Date.now() < end) {
+    const node = page.locator(provider.response).last();
+    let tx = "";
+    try {
+      tx = (await node.textContent()) || "";
+    } catch (e) {
+      tx = "";
+    }
+    const n = norm(tx);
+    if (!n || n === want) {
+      await sleep(300);
+      continue;
+    }
+    if (tx !== last) {
+      last = tx;
+      stab = Date.now();
+    } else if (Date.now() - stab > 1500) {
+      return tx;
+    }
+    await sleep(300);
+  }
+
+  return last || "(timeout)";
+}

package/lib/system.mjs

@@ -0,0 +1,24 @@
+import { CATALOG } from "./tools.mjs";
+
+export function buildSystem(ws) {
+  const shown = ws.split("\\").join("/");
+  return [
+    "You are a coding agent working in a terminal.",
+    "Workspace: " + shown,
+    "Use forward slashes in every path, even on Windows.",
+    "",
+    "To call a tool, write on its own line:",
+    "portal-tool: {\"tool\":\"name\",\"args\":{\"key\":\"value\"}}",
+    "",
+    "The JSON must use double quotes around keys and values.",
+    "Plain text only. Do not wrap the call in a code block.",
+    "One call per action. Never repeat a call with the same arguments.",
+    "",
+    "If a tool returns an empty result, that is final. Report it.",
+    "If unsure what to do, reply with plain prose and ask.",
+    "When done, reply with plain prose and no tool calls.",
+    "",
+    "Available tools:",
+    CATALOG
+  ].join("\n");
+}

package/lib/tools.mjs

@@ -0,0 +1,151 @@
+import { readFile, writeFile, mkdir, readdir, stat } from "node:fs/promises";
+import { dirname, resolve, relative, sep, join } from "node:path";
+import { spawn } from "node:child_process";
+
+let ws = process.cwd();
+
+export function setWs(p) {
+  ws = resolve(p);
+}
+
+export function getWs() {
+  return ws;
+}
+
+const IGNORE = new Set([
+  "node_modules", ".git", ".hg", ".svn", "dist", "build", "out",
+  ".next", ".nuxt", ".turbo", ".cache", "target", "__pycache__",
+  ".venv", "venv", "env", "coverage", ".idea", ".vscode"
+]);
+
+function safe(p) {
+  const a = resolve(ws, p);
+  const r = relative(ws, a);
+  if (r === ".." || r.slice(0, 3) === "..\\" || r.slice(0, 3) === "../") {
+    throw new Error("path escapes workspace: " + p);
+  }
+  return a;
+}
+
+async function* walk(dir) {
+  let items;
+  try {
+    items = await readdir(dir, { withFileTypes: true });
+  } catch (e) {
+    return;
+  }
+  for (const it of items) {
+    if (IGNORE.has(it.name)) continue;
+    if (it.name.startsWith(".") && it.name !== ".env.example") continue;
+    const full = join(dir, it.name);
+    if (it.isDirectory()) yield* walk(full);
+    else if (it.isFile()) yield full;
+  }
+}
+
+export const tools = {
+  read_file: async function (a) {
+    const t = await readFile(safe(a.path), "utf8");
+    return t.length > 200000 ? t.slice(0, 200000) + "\n[truncated]" : t;
+  },
+
+  write_file: async function (a) {
+    const x = safe(a.path);
+    await mkdir(dirname(x), { recursive: true });
+    await writeFile(x, a.content || "", "utf8");
+    return "wrote " + (a.content || "").length + " bytes to " + a.path;
+  },
+
+  edit_file: async function (a) {
+    const x = safe(a.path);
+    const orig = await readFile(x, "utf8");
+    const n = orig.split(a.old_string).length - 1;
+    if (n === 0) return "old_string not found in " + a.path;
+    if (n > 1 && !a.replace_all) return "old_string appears " + n + " times";
+    const next = a.replace_all
+      ? orig.split(a.old_string).join(a.new_string)
+      : orig.replace(a.old_string, a.new_string);
+    await writeFile(x, next, "utf8");
+    return "edited " + a.path;
+  },
+
+  list_files: async function (a) {
+    const e = await readdir(safe(a.path || "."), { withFileTypes: true });
+    if (!e.length) return "EMPTY. Do not call list_files again.";
+    const names = e.map(function (x) {
+      return (x.isDirectory() ? "[dir] " : "      ") + x.name;
+    });
+    names.sort();
+    return names.join("\n");
+  },
+
+  grep_search: async function (a) {
+    let re;
+    try {
+      re = new RegExp(a.pattern, a.case_sensitive ? "" : "i");
+    } catch (e) {
+      return "bad regex: " + e.message;
+    }
+    const hits = [];
+    for await (const f of walk(ws)) {
+      if (hits.length >= 80) break;
+      let info;
+      try {
+        info = await stat(f);
+      } catch (e) {
+        continue;
+      }
+      if (info.size > 512000) continue;
+      let t;
+      try {
+        t = await readFile(f, "utf8");
+      } catch (e) {
+        continue;
+      }
+      const lines = t.split("\n");
+      for (let i = 0; i < lines.length && hits.length < 80; i++) {
+        if (re.test(lines[i])) {
+          const rel = relative(ws, f).split(sep).join("/");
+          hits.push(rel + ":" + (i + 1) + ":" + lines[i].trim().slice(0, 200));
+        }
+      }
+    }
+    return hits.length ? hits.join("\n") : "no matches";
+  },
+
+  shell: function (a) {
+    const cmd = String(a.command || "");
+    if (!cmd) return Promise.resolve("shell requires command");
+    return new Promise(function (done) {
+      const c = spawn(cmd, { cwd: ws, shell: true, windowsHide: true });
+      let o = "";
+      let e = "";
+      if (c.stdout) c.stdout.on("data", function (d) { o += String(d); });
+      if (c.stderr) c.stderr.on("data", function (d) { e += String(d); });
+      const to = setTimeout(function () {
+        c.kill();
+        done("timed out after 60s");
+      }, 60000);
+      c.on("error", function (err) {
+        clearTimeout(to);
+        done("error: " + err.message);
+      });
+      c.on("close", function (code) {
+        clearTimeout(to);
+        const both = [o.trim(), e.trim()].filter(Boolean).join("\n");
+        let s = "exit " + code + "\n" + (both || "(no output)");
+        if (s.length > 65000) s = s.slice(0, 65000) + "\n[truncated]";
+        done(s);
+      });
+    });
+  }
+};
+
+export const CATALOG = [
+  "- 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)"
+].join("\n");

package/lib/turn.mjs

@@ -0,0 +1,57 @@
+import { send } from "./send.mjs";
+import { parseCalls, stripCalls } from "./parse.mjs";
+import { tools, getWs } from "./tools.mjs";
+import { buildSystem } from "./system.mjs";
+
+export async function runTurn(page, provider, prompt, opts) {
+  const sys = buildSystem(getWs());
+  const seen = new Map();
+  let next = sys + "\n\nTask: " + prompt;
+
+  for (let i = 0; i < opts.maxSteps; i++) {
+    console.log("  waiting for " + provider.label + "...");
+    const r = await send(page, provider, next, opts.timeout);
+    const calls = parseCalls(r);
+
+    if (!calls.length) {
+      const prose = stripCalls(r);
+      if (prose) console.log("\n" + prose + "\n");
+      return;
+    }
+
+    const results = [];
+    let stop = false;
+
+    for (const c of calls) {
+      const sig = c.tool + ":" + JSON.stringify(c.args || {});
+      const n = (seen.get(sig) || 0) + 1;
+      seen.set(sig, n);
+
+      if (n >= 3) {
+        console.log("loop detected: " + c.tool + " repeated. stopping.");
+        stop = true;
+        break;
+      }
+
+      console.log("> " + c.tool + " " + JSON.stringify(c.args || {}).slice(0, 120));
+
+      let out;
+      try {
+        const fn = tools[c.tool];
+        out = fn ? await fn(c.args || {}) : "unknown tool: " + c.tool;
+      } catch (e) {
+        out = "error: " + (e.message || e);
+      }
+
+      console.log("  " + String(out).slice(0, 240).split("\n").join("\n  "));
+      results.push(c.tool + ":\n" + out);
+    }
+
+    if (stop) return;
+
+    next = "Results:\n\n" + results.join("\n\n") +
+      "\n\nContinue. Do not repeat any call with the same arguments.";
+  }
+
+  console.log("max steps reached for this turn.");
+}

package/lib/wait.mjs

@@ -0,0 +1,32 @@
+export function sleep(ms) {
+  return new Promise(function (r) { setTimeout(r, ms); });
+}
+
+export function norm(s) {
+  return String(s || "").replace(/\s+/g, " ").trim();
+}
+
+export async function waitForComposer(page, p, ms) {
+  const end = Date.now() + ms;
+  let hint = Date.now();
+  while (Date.now() < end) {
+    const loc = page.locator(p.input).last();
+    let ok = false;
+    try {
+      ok = await loc.isVisible({ timeout: 250 });
+    } catch (e) {
+      ok = false;
+    }
+    if (ok) return loc;
+    if (Date.now() - hint > 15000) {
+      const left = Math.round((end - Date.now()) / 1000);
+      process.stdout.write("  waiting for login (" + left + "s left)\n");
+      hint = Date.now();
+    }
+    await sleep(1000);
+  }
+  throw new Error(
+    "Timed out waiting for the composer. Log in to the provider " +
+    "and try again, or raise --login-timeout."
+  );
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "portal-agent-cli",
+  "version": "1.0.0",
+  "description": "Drive web AI products from the terminal with local tools. Enter-first submit, paste-safe insertion, prompt-echo skip, loop breaker.",
+  "type": "module",
+  "bin": {
+    "portal-agent": "./portal.mjs"
+  },
+  "main": "./portal.mjs",
+  "files": [
+    "portal.mjs",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node portal.mjs",
+    "build": "pkg portal.mjs --targets node18-win-x64 --output portal.exe"
+  },
+  "dependencies": {
+    "playwright": "^1.48.0"
+  },
+  "devDependencies": {
+    "pkg": "^5.8.1"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "cli",
+    "ai",
+    "agent",
+    "deepseek",
+    "chatgpt",
+    "playwright"
+  ],
+  "author": "your-name",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-name/portal-agent-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/your-name/portal-agent-cli/issues"
+  },
+  "homepage": "https://github.com/your-name/portal-agent-cli#readme"
+}

package/portal.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { parseArgs } from "./lib/args.mjs";
+import { runRepl } from "./lib/repl.mjs";
+import { runExec } from "./lib/exec.mjs";
+
+const opts = parseArgs();
+
+const task = opts.exec ? runExec(opts) : runRepl(opts);
+
+task.catch(function (e) {
+  console.error(e.message || e);
+  process.exit(1);
+});