@agentprojectcontext/apx 1.30.2 → 1.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.30.2",
+  "version": "1.31.1",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

package/skills/apx-agency-agents/SKILL.md

@@ -59,7 +59,7 @@ apx agent vault list --all
 # Create a new template (writes ~/.apx/agents/<slug>.md)
 apx agent vault add reviewer \
   --role "Code reviewer" \
-  --model claude-haiku-4-5 \
+  --model ollama:llama3.2:3b \
   --language es \
   --skills code-review,git \
   --description "Reviews PRs and pushes back on hand-wavy diffs."

package/skills/apx-agent/SKILL.md

@@ -5,7 +5,7 @@ description: How to create, configure, and use project agents in APX. Load when
 
 # apx-agent
 
-A project agent is a named persona inside an APC project. Canonical definition: `.apc/agents/<slug>.md` (flat file). `AGENTS.md` is auto-regenerated for discovery. Per-agent runtime data: `.apc/agents/<slug>/memory.md` (and optional `sessions/` only when using external runtimes that write APC session stubs — APX-native sessions live under `~/.apx/projects/<id>/`).
+A project agent is a named persona inside an APC project. Canonical definition: `.apc/agents/<slug>.md` (flat file). `AGENTS.md` is auto-regenerated for discovery. Per-agent runtime data (memory, conversations, sessions) lives under `~/.apx/projects/<apx_id>/agents/<slug>/` and is never committed. APX still reads legacy `.apc/agents/<slug>/memory.md` as a migration fallback only.
 
 ## Concrete CLI calls
 
@@ -13,10 +13,10 @@ A project agent is a named persona inside an APC project. Canonical definition:
 # List agents in a project
 apx agent list --project iacrmar
 
-# Create a new agent (writes .apc/agents/<slug>.md + regenerates AGENTS.md)
+# Create a new agent (writes .apc/agents/<slug>.md, creates runtime dir, regenerates AGENTS.md)
 apx agent add reviewer \
   --role "Code reviewer" \
-  --model claude-haiku-4-5 \
+  --model ollama:llama3.2:3b \
   --language es \
   --description "Reviews PRs and pushes back on hand-wavy diffs." \
   --tools read,write,run \
@@ -45,7 +45,7 @@ apx memory <slug> --project iacrmar --replace < file.md       # full replace fro
 2. Description (from AGENTS.md).
 3. Role + Language fields.
 4. Invocation context: `engine | telegram | routine | runtime` — the channel calling the agent.
-5. Memory: `.apc/agents/<slug>/memory.md` if it exists.
+5. Memory: `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` if it exists, with legacy `.apc/agents/<slug>/memory.md` as a migration fallback.
 6. Skills declared in the agent's `Skills:` field, each loaded from `.apc/skills/<slug>.md` or the bundled set.
 7. The `apx` meta-skill (so the agent knows how to operate APX).
 8. ACTION_DISCIPLINE_RULES (fixed footer — anti-ghost, anti-disclaimer, action-first).
@@ -54,13 +54,13 @@ That's the prompt the engine sees on every `apx exec <agent>` or `apx chat <agen
 
 ## Models per agent
 
-Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Useful when a particular agent should use a cheaper / smaller / specialized model.
+Each agent can set `Model:` in its `AGENT.md` to override the global super-agent model. Leave it empty when the agent should follow the project/global default.
 
 ```markdown
 # .apc/agents/reviewer.md
 ---
 Role: Code reviewer
-Model: claude-haiku-4-5      ← this agent always uses Haiku, independent of super_agent.model
+Model: ollama:llama3.2:3b    ← this agent uses this model, independent of super_agent.model
 Language: es
 ---
 ```

package/skills/apx-project/SKILL.md

@@ -57,7 +57,6 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 └── .apc/
     ├── project.json                            ← { apxId, name, ... }
     ├── agents/<slug>.md
-    ├── agents/<slug>/memory.md
     ├── skills/<slug>.md or <slug>/SKILL.md
     ├── mcps.json                               ← shared MCPs (committed)
     ├── commands/                               ← custom slash-commands
@@ -65,7 +64,7 @@ The CLI calls `resolveProjectId()` which does fuzzy id-or-name-or-path matching.
 
 ~/.apx/projects/<apxId>/                        ← runtime state (never committed)
 ├── messages/YYYY-MM-DD.jsonl
-├── agents/<slug>/{sessions/, conversations/}
+├── agents/<slug>/{memory.md, sessions/, conversations/}
 ├── routines.json
 ├── tasks/YYYY-MM.jsonl
 ├── artifacts/

package/src/core/agent/prompt-builder.js

@@ -271,6 +271,11 @@ export function buildSuperAgentSystem({
   // Pre-rendered "# Hilos activos en otros canales" block (recency-based
   // cross-channel awareness; see core/memory/active-threads.js). "" → omitted.
   activeThreadsBlock = "",
+  // Compact "# Tools adicionales (activación on-demand)" block: instructions +
+  // the NAMES (no schemas) of tools that exist but aren't loaded on this
+  // channel, so the model knows they're reachable via discover_tools without
+  // paying for their schemas. "" → omitted (full channels load everything).
+  lazyToolsBlock = "",
 }) {
   const sa = globalConfig.super_agent;
   const projectIndex = projects
@@ -305,6 +310,7 @@ export function buildSuperAgentSystem({
     projectIndex || "(no projects registered)",
     buildProjectAgentsBlock(channelMeta?.projectPath),
     buildSkillsCatalog(listSkills),
+    lazyToolsBlock,
     voiceModeBlock,
     systemSuffix,
   ]

package/src/core/agent/run-agent.js

@@ -178,6 +178,25 @@ export async function runAgent({
       })
     : rawHandlers;
 
+  // Lazy tools: when the super-agent runs a `discover_tools` activation, its
+  // handler pushes the newly-revealed schemas onto session.pending. We drain
+  // that queue into effectiveSchemas at the top of each iteration, so tools
+  // activated on step N are callable from step N+1. No session → no-op.
+  const toolSession = toolHandlerCtx?.toolSession || null;
+  const drainPendingTools = () => {
+    if (!toolSession || toolSession.pending.length === 0) return;
+    const seen = new Set(
+      effectiveSchemas.map((s) => s?.function?.name || s?.name)
+    );
+    const additions = [];
+    for (const sc of toolSession.pending) {
+      const n = sc?.function?.name || sc?.name;
+      if (n && !seen.has(n)) { additions.push(sc); seen.add(n); }
+    }
+    toolSession.pending = [];
+    if (additions.length > 0) effectiveSchemas = effectiveSchemas.concat(additions);
+  };
+
   const conversation = [...previousMessages, { role: "user", content: prompt }];
   const trace = [];
   let totalUsage = { input_tokens: 0, output_tokens: 0 };
@@ -236,6 +255,8 @@ export async function runAgent({
   };
 
   for (let iter = 0; iter < maxIters; iter++) {
+    // Merge any tools activated via discover_tools on the previous iteration.
+    drainPendingTools();
     await emitProgress(onEvent, { type: "model_start", iteration: iter + 1, model: activeModel });
     // Force a tool call on iter 0 ONLY when the user message looks like a real
     // action request ("listame…", "mandá…", "buscá…"). For chit-chat ("hola",

package/src/core/agent/self-memory.js

@@ -2,7 +2,7 @@
 //
 // This is distinct from:
 //   - identity.json   → who Roby is (name, personality, owner)
-//   - project agents' .apc/agents/<slug>/memory.md → per-agent, per-project
+//   - project agents' ~/.apx/projects/<apx_id>/agents/<slug>/memory.md → per-agent, per-project
 //   - sessions        → raw transcripts of past work (search_sessions)
 //
 // It is a single free-form markdown file at ~/.apx/memory.md that Roby keeps

package/src/core/agent-memory.js

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { projectStorageRoot } from "./config.js";
+import { getOrCreateApxId } from "./scaffold.js";
+
+const EMPTY_MEMORY = (slug) =>
+  `# Memory — ${slug}\n\n` +
+  `## Identity\n- \n\n` +
+  `## Long-term facts\n- \n\n` +
+  `## Recent context\n- \n`;
+
+export function agentRuntimeDir(projectOrRoot, slug) {
+  const storagePath =
+    typeof projectOrRoot === "object" && projectOrRoot?.storagePath
+      ? projectOrRoot.storagePath
+      : null;
+  const root =
+    typeof projectOrRoot === "string"
+      ? projectOrRoot
+      : projectOrRoot?.path;
+  const base = storagePath || projectStorageRoot(getOrCreateApxId(root));
+  return path.join(base, "agents", slug);
+}
+
+export function agentMemoryPath(projectOrRoot, slug) {
+  return path.join(agentRuntimeDir(projectOrRoot, slug), "memory.md");
+}
+
+export function legacyAgentMemoryPath(projectRoot, slug) {
+  return path.join(projectRoot, ".apc", "agents", slug, "memory.md");
+}
+
+export function ensureAgentRuntimeDir(projectOrRoot, slug, { createMemory = false } = {}) {
+  const dir = agentRuntimeDir(projectOrRoot, slug);
+  fs.mkdirSync(dir, { recursive: true });
+  if (createMemory) {
+    const memory = path.join(dir, "memory.md");
+    if (!fs.existsSync(memory)) fs.writeFileSync(memory, EMPTY_MEMORY(slug));
+  }
+  return dir;
+}
+
+export function readAgentMemory(projectOrRoot, slug) {
+  const primary = agentMemoryPath(projectOrRoot, slug);
+  if (fs.existsSync(primary)) return fs.readFileSync(primary, "utf8");
+
+  const root =
+    typeof projectOrRoot === "string"
+      ? projectOrRoot
+      : projectOrRoot?.path;
+  if (root) {
+    const legacy = legacyAgentMemoryPath(root, slug);
+    if (fs.existsSync(legacy)) return fs.readFileSync(legacy, "utf8");
+  }
+
+  return "";
+}
+
+export function writeAgentMemory(projectOrRoot, slug, body) {
+  ensureAgentRuntimeDir(projectOrRoot, slug);
+  const memory = agentMemoryPath(projectOrRoot, slug);
+  fs.writeFileSync(memory, body);
+  return memory;
+}

package/src/core/agent-system.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { readAgentMemory } from "./agent-memory.js";
 
 // ---------------------------------------------------------------------------
 // Anti-ghost-response rules injected into every agent system prompt.
@@ -62,8 +63,8 @@ export function buildAgentSystem(project, agent, {
 
   parts.push(buildInvocationContext({ invocation, runtime, channel, caller, routine }));
 
-  const memPath = path.join(project.path, ".apc", "agents", agent.slug, "memory.md");
-  if (fs.existsSync(memPath)) parts.push("## Memory\n" + fs.readFileSync(memPath, "utf8"));
+  const memory = readAgentMemory(project, agent.slug);
+  if (memory) parts.push("## Memory\n" + memory);
 
   const apxSkill = path.join(project.path, ".apc", "skills", "apx.md");
   if (fs.existsSync(apxSkill)) parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8"));

package/src/core/scaffold.js

@@ -325,24 +325,60 @@ const AGENTS_MD_TEMPLATE = `# AGENTS.md
 <!-- Hard constraints: what agents must always / never do here. -->
 `;
 
-const APC_GITIGNORE = `# APC runtime data — never in the repository
-# Chat conversations and runtime sessions belong in ~/.apx/projects/<id>/
-agents/*/sessions/
-agents/*/conversations/
+const APC_GITIGNORE = `# APC repository-safe context only.
+# Runtime state belongs in ~/.apx/projects/<id>/, not in .apc/.
+
+# Legacy per-agent runtime dirs (agent definitions are flat: agents/<slug>.md)
+agents/*/
+
+# Runtime sessions / conversations / messages
 sessions/
 conversations/
 messages/
 chats/
+threads/
+transcripts/
+runs/
+
+# Runtime memory, indexes, databases, and caches
+memory.local.md
+auto-memory.md
 cache/
 tmp/
 private/
 secrets/
+*.db
+*.db-*
+*.sqlite
+*.sqlite3
+project.db
+memory.db
+memory-index.jsonl
+memory-cursor.json
+
+# Local config and secrets
+.env
 *.local.json
 *.secret.json
 *.env
 *.env.*
-project.db
+*.key
+*.pem
+*.p12
+*.crt
+credentials.json
+service-account*.json
+token*.json
+mcps.local.json
+config.local.json
+
+# Scratch planning state
+plans/scratch/
+plans/*.local.md
+
+# Migration marker and OS noise
 migrate.md
+.DS_Store
 `;
 
 function nowIso() {
@@ -448,19 +484,8 @@ export function initApf(directory, { name } = {}) {
 }
 
 export function ensureAgentDir(root, slug) {
-  const dir = path.join(root, ".apc", "agents", slug);
-  fs.mkdirSync(dir, { recursive: true });
-  const memory = path.join(dir, "memory.md");
-  if (!fs.existsSync(memory)) {
-    fs.writeFileSync(
-      memory,
-      `# Memory — ${slug}\n\n` +
-        `## Identity\n- \n\n` +
-        `## Long-term facts\n- \n\n` +
-        `## Recent context\n- \n`
-    );
-  }
-  return dir;
+  fs.mkdirSync(path.join(root, ".apc", "agents"), { recursive: true });
+  return path.join(root, ".apc", "agents");
 }
 
 // Write .apc/agents/<slug>.md — the canonical agent definition file.

package/src/core/tools/browser.js

@@ -181,19 +181,104 @@ async function ensureBrowser({ launch_options, allow_dangerous } = {}) {
   return _page;
 }
 
+// ---------------------------------------------------------------------------
+// Context-destruction resilience
+// ---------------------------------------------------------------------------
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Puppeteer throws this family of errors when an action (evaluate / get_text /
+// click / …) runs while the page is navigating, redirecting, or reloading —
+// the frame's JS execution context is torn down mid-call. Redirect-heavy sites
+// (ESPN geo/consent hops, login walls) trigger it constantly. These are
+// transient: waiting for the navigation to settle and retrying succeeds.
+const CONTEXT_DESTROYED_RE =
+  /Execution context was destroyed|Cannot find context|Execution context is not available|detached frame|frame (?:was|got) detached|Target closed|Session closed|Protocol error.*(?:Runtime|Page)\./i;
+
+export function isContextDestroyed(err) {
+  return CONTEXT_DESTROYED_RE.test(String(err?.message || err));
+}
+
+// Let any in-flight navigation finish so the next action sees a stable context.
+async function settlePage(page, { timeout = 5000 } = {}) {
+  if (!page || page.isClosed()) return;
+  await page.waitForNetworkIdle({ idleTime: 500, timeout }).catch(() => {});
+}
+
+// Run a page action, retrying on a transient "Execution context was destroyed"
+// (and friends): wait `delayMs`, let the page settle, try again — up to
+// `retries` extra attempts. Non-context errors bubble immediately.
+export async function withContextRetry(fn, { retries = 2, delayMs = 1500 } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      lastErr = e;
+      if (!isContextDestroyed(e) || attempt === retries) throw e;
+      await sleep(delayMs);
+      await settlePage(_page);
+    }
+  }
+  throw lastErr;
+}
+
+// Convenience: ensure the browser/page, then run an action under context-retry.
+async function onPage(fn) {
+  const page = await ensureBrowser();
+  return withContextRetry(() => fn(page));
+}
+
 // ---------------------------------------------------------------------------
 // Tool implementations
 // ---------------------------------------------------------------------------
 
-export async function browser_navigate({ url, launch_options, allow_dangerous } = {}) {
+export async function browser_navigate({ url, launch_options, allow_dangerous, wait_until } = {}) {
   if (!url) throw new Error("url required");
   const page = await ensureBrowser({ launch_options, allow_dangerous });
-  const response = await page.goto(url, { waitUntil: "networkidle2", timeout: 30000 });
+
+  const go = async (waitUntil) => {
+    const response = await page.goto(url, { waitUntil, timeout: 30000 });
+    // Some sites fire a client-side redirect/reload right after the initial
+    // load. Give it a beat to settle so the execution context is stable for
+    // the caller's NEXT tool (get_text/evaluate) instead of being destroyed
+    // out from under it.
+    await settlePage(page, { timeout: 3000 });
+    return response;
+  };
+
+  // Preferred wait strategy: networkidle2 (or caller override). On a
+  // context-destroyed / timeout / navigation error, fall back to the much more
+  // permissive "domcontentloaded" which resolves as soon as the DOM is parsed,
+  // before late redirects/XHR can tear the context down.
+  const preferred = wait_until || "networkidle2";
+  let response;
+  try {
+    response = await go(preferred);
+  } catch (e) {
+    const recoverable =
+      isContextDestroyed(e) ||
+      /TimeoutError|Navigation timeout|net::ERR_ABORTED|frame was detached/i.test(String(e?.message || e));
+    if (!recoverable || preferred === "domcontentloaded") throw e;
+    await sleep(1500);
+    response = await go("domcontentloaded");
+  }
+
+  // title() evaluates in-page, so it can itself throw if a redirect is still
+  // in flight — read it defensively (url() is sync and always safe).
+  let title = "";
+  try {
+    title = await withContextRetry(() => page.title(), { retries: 1, delayMs: 1000 });
+  } catch {
+    title = "";
+  }
+
   return {
     ok: true,
     url: page.url(),
     status: response?.status() ?? null,
-    title: await page.title(),
+    title,
+    wait_until: response ? (preferred) : null,
   };
 }
 
@@ -206,12 +291,13 @@ export async function browser_screenshot({ selector, full_page = false, width, h
     });
   }
 
-  const target = selector ? await page.$(selector) : null;
-  if (selector && !target) throw new Error(`Element not found: ${selector}`);
-
-  const buf = target
-    ? await target.screenshot({ type: "png", encoding: "base64" })
-    : await page.screenshot({ type: "png", encoding: "base64", fullPage: !!full_page });
+  const buf = await withContextRetry(async () => {
+    const target = selector ? await page.$(selector) : null;
+    if (selector && !target) throw new Error(`Element not found: ${selector}`);
+    return target
+      ? await target.screenshot({ type: "png", encoding: "base64" })
+      : await page.screenshot({ type: "png", encoding: "base64", fullPage: !!full_page });
+  });
 
   const size = Buffer.from(String(buf), "base64").length;
   if (size > MAX_SCREENSHOT_BYTES) {
@@ -248,50 +334,56 @@ export async function browser_screenshot({ selector, full_page = false, width, h
 
 export async function browser_click({ selector } = {}) {
   if (!selector) throw new Error("selector required");
-  const page = await ensureBrowser();
-  await page.waitForSelector(selector, { timeout: 10000 });
-  await page.click(selector);
-  await page.waitForNetworkIdle({ timeout: 5000 }).catch(() => {});
-  return { ok: true, selector, url: page.url() };
+  return onPage(async (page) => {
+    await page.waitForSelector(selector, { timeout: 10000 });
+    await page.click(selector);
+    await page.waitForNetworkIdle({ timeout: 5000 }).catch(() => {});
+    return { ok: true, selector, url: page.url() };
+  });
 }
 
 export async function browser_type({ selector, text, clear = true } = {}) {
   if (!selector) throw new Error("selector required");
   if (text === undefined) throw new Error("text required");
-  const page = await ensureBrowser();
-  await page.waitForSelector(selector, { timeout: 10000 });
-  await page.focus(selector);
-  if (clear) {
-    await page.keyboard.down("Control");
-    await page.keyboard.press("KeyA");
-    await page.keyboard.up("Control");
-    await page.keyboard.press("Backspace");
-  }
-  await page.type(selector, String(text), { delay: 20 });
-  return { ok: true, selector, typed: String(text).length };
+  return onPage(async (page) => {
+    await page.waitForSelector(selector, { timeout: 10000 });
+    await page.focus(selector);
+    if (clear) {
+      await page.keyboard.down("Control");
+      await page.keyboard.press("KeyA");
+      await page.keyboard.up("Control");
+      await page.keyboard.press("Backspace");
+    }
+    await page.type(selector, String(text), { delay: 20 });
+    return { ok: true, selector, typed: String(text).length };
+  });
 }
 
 export async function browser_select({ selector, value } = {}) {
   if (!selector) throw new Error("selector required");
   if (value === undefined) throw new Error("value required");
-  const page = await ensureBrowser();
-  await page.waitForSelector(selector, { timeout: 10000 });
-  await page.select(selector, String(value));
-  return { ok: true, selector, value };
+  return onPage(async (page) => {
+    await page.waitForSelector(selector, { timeout: 10000 });
+    await page.select(selector, String(value));
+    return { ok: true, selector, value };
+  });
 }
 
 export async function browser_hover({ selector } = {}) {
   if (!selector) throw new Error("selector required");
-  const page = await ensureBrowser();
-  await page.waitForSelector(selector, { timeout: 10000 });
-  await page.hover(selector);
-  return { ok: true, selector };
+  return onPage(async (page) => {
+    await page.waitForSelector(selector, { timeout: 10000 });
+    await page.hover(selector);
+    return { ok: true, selector };
+  });
 }
 
 export async function browser_evaluate({ code } = {}) {
   if (!code) throw new Error("code required");
-  const page = await ensureBrowser();
+  return onPage((page) => evaluateOnPage(page, code));
+}
 
+async function evaluateOnPage(page, code) {
   // Install in-page console capture so evaluated code's logs come back.
   await page.evaluate(() => {
     window.__apxHelper = { logs: [], orig: { ...console } };
@@ -325,54 +417,56 @@ export async function browser_evaluate({ code } = {}) {
 }
 
 export async function browser_get_text({ selector } = {}) {
-  const page = await ensureBrowser();
-  const text = await page.evaluate((sel) => {
-    const root = sel ? document.querySelector(sel) : document.body;
-    if (!root) return null;
-    const clone = root.cloneNode(true);
-    for (const tag of ["script", "style", "nav", "header", "footer", "noscript"]) {
-      for (const el of clone.querySelectorAll(tag)) el.remove();
-    }
-    return clone.innerText || clone.textContent || "";
-  }, selector ?? null);
-  if (text === null) throw new Error(`Element not found: ${selector}`);
-  const cleaned = text.replace(/\n{3,}/g, "\n\n").trim();
-  return {
-    ok: true,
-    url: page.url(),
-    title: await page.title(),
-    text: cleaned,
-    chars: cleaned.length,
-  };
+  return onPage(async (page) => {
+    const text = await page.evaluate((sel) => {
+      const root = sel ? document.querySelector(sel) : document.body;
+      if (!root) return null;
+      const clone = root.cloneNode(true);
+      for (const tag of ["script", "style", "nav", "header", "footer", "noscript"]) {
+        for (const el of clone.querySelectorAll(tag)) el.remove();
+      }
+      return clone.innerText || clone.textContent || "";
+    }, selector ?? null);
+    if (text === null) throw new Error(`Element not found: ${selector}`);
+    const cleaned = text.replace(/\n{3,}/g, "\n\n").trim();
+    let title = "";
+    try { title = await page.title(); } catch { title = ""; }
+    return {
+      ok: true,
+      url: page.url(),
+      title,
+      text: cleaned,
+      chars: cleaned.length,
+    };
+  });
 }
 
 export async function browser_get_content({ selector } = {}) {
-  const page = await ensureBrowser();
-  let content = selector
-    ? await page.$eval(selector, el => el.innerHTML).catch(() => null)
-    : await page.content();
-  if (content === null) throw new Error(`Element not found: ${selector}`);
-
-  let truncated = false;
-  if (content.length > MAX_CONTENT_CHARS) {
-    content = content.slice(0, MAX_CONTENT_CHARS) + "\n[TRUNCATED]";
-    truncated = true;
-  }
-  return {
-    ok: true,
-    url: page.url(),
-    selector: selector ?? null,
-    chars: content.length,
-    truncated,
-    html: content,
-  };
+  return onPage(async (page) => {
+    let content = selector
+      ? await page.$eval(selector, el => el.innerHTML).catch(() => null)
+      : await page.content();
+    if (content === null) throw new Error(`Element not found: ${selector}`);
+
+    let truncated = false;
+    if (content.length > MAX_CONTENT_CHARS) {
+      content = content.slice(0, MAX_CONTENT_CHARS) + "\n[TRUNCATED]";
+      truncated = true;
+    }
+    return {
+      ok: true,
+      url: page.url(),
+      selector: selector ?? null,
+      chars: content.length,
+      truncated,
+      html: content,
+    };
+  });
 }
 
 export async function browser_wait_for_selector({ selector, timeout = 30000 } = {}) {
   if (!selector) throw new Error("selector required");
-  const page = await ensureBrowser();
-  await page.waitForSelector(selector, { timeout });
-  return { ok: true, selector };
+  return onPage((page) => page.waitForSelector(selector, { timeout }).then(() => ({ ok: true, selector })));
 }
 
 export async function browser_close() {