tau-coding-agent 0.1.0

package/skills/browser-tools/scripts/browser-watch.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+/**
+ * Background logging for browser-tools.
+ *
+ * Logs console output, page errors, and network activity to JSONL.
+ *
+ * Default log root:
+ *   $TMPDIR/agent-browser-tools/logs
+ *
+ * Override with:
+ *   BROWSER_TOOLS_LOG_ROOT=/some/dir
+ */
+
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import puppeteer from "puppeteer-core";
+
+const DEFAULT_TMP = process.platform === "win32" ? tmpdir() : "/tmp";
+
+const LOG_ROOT =
+  process.env.BROWSER_TOOLS_LOG_ROOT || join(DEFAULT_TMP, "agent-browser-tools", "logs");
+
+const PID_FILE = join(LOG_ROOT, ".watch.pid");
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getDateDir() {
+  const now = new Date();
+  const yyyy = String(now.getFullYear());
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  return join(LOG_ROOT, `${yyyy}-${mm}-${dd}`);
+}
+
+function safeFileName(value) {
+  return String(value).replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+async function connectBrowser(timeout = 5000) {
+  return Promise.race([
+    puppeteer.connect({ browserURL: "http://127.0.0.1:9222", defaultViewport: null }),
+    new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("timeout")), timeout).unref();
+    }),
+  ]);
+}
+
+ensureDir(LOG_ROOT);
+
+// Prevent duplicate watchers.
+if (existsSync(PID_FILE)) {
+  try {
+    const existing = Number(readFileSync(PID_FILE, "utf8").trim());
+    if (existing && isProcessAlive(existing)) {
+      console.log("✓ watch already running");
+      process.exit(0);
+    }
+  } catch {
+    // ignore stale pid
+  }
+}
+
+writeFileSync(PID_FILE, String(process.pid));
+
+const dateDir = getDateDir();
+ensureDir(dateDir);
+
+// targetId -> { stream, filepath }
+const targetState = new Map();
+// request object -> requestId
+const requestIds = new WeakMap();
+// page -> targetId
+const pageToTarget = new WeakMap();
+const instrumentedPages = new WeakSet();
+let nextSyntheticPageId = 1;
+
+function getOrCreateTargetState(targetId) {
+  let state = targetState.get(targetId);
+  if (state) return state;
+
+  const filename = `${safeFileName(targetId)}.jsonl`;
+  const filepath = join(dateDir, filename);
+  const stream = createWriteStream(filepath, { flags: "a" });
+
+  state = { stream, filepath };
+  targetState.set(targetId, state);
+  return state;
+}
+
+function writeLog(targetId, payload) {
+  const state = getOrCreateTargetState(targetId);
+  const record = {
+    ts: nowIso(),
+    targetId,
+    ...payload,
+  };
+  state.stream.write(`${JSON.stringify(record)}\n`);
+}
+
+function internalTargetId(page) {
+  try {
+    const t = page.target?.();
+    return t?._targetId || t?._targetInfo?.targetId || t?._id || null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureTargetId(page) {
+  const existing = pageToTarget.get(page);
+  if (existing) return existing;
+
+  const internal = internalTargetId(page);
+  const chosen = internal ? String(internal) : `page-${nextSyntheticPageId++}`;
+  pageToTarget.set(page, chosen);
+  return chosen;
+}
+
+function ensureRequestId(targetId, request) {
+  if (requestIds.has(request)) return requestIds.get(request);
+  const id = `${targetId}-${Math.random().toString(16).slice(2)}-${Date.now()}`;
+  requestIds.set(request, id);
+  return id;
+}
+
+function closeTarget(targetId) {
+  const state = targetState.get(targetId);
+  if (!state) return;
+  try {
+    state.stream.end();
+  } catch {
+    // ignore
+  }
+  targetState.delete(targetId);
+}
+
+async function instrumentPage(page) {
+  if (instrumentedPages.has(page)) return;
+  instrumentedPages.add(page);
+
+  const targetId = ensureTargetId(page);
+
+  // Do not double-instrument.
+  if (targetState.has(targetId)) {
+    // Note: this assumes a 1:1 mapping between targetId and page.
+    // That’s fine for our usage.
+  }
+
+  writeLog(targetId, {
+    type: "target.attached",
+    url: page.url?.() || null,
+  });
+
+  page.on("console", (msg) => {
+    try {
+      writeLog(targetId, {
+        type: "console",
+        level: msg.type?.() || null,
+        text: msg.text?.() || null,
+        args: (msg.args?.() || []).map((a) => a.toString()),
+      });
+    } catch {
+      // ignore
+    }
+  });
+
+  page.on("pageerror", (err) => {
+    writeLog(targetId, {
+      type: "exception",
+      text: err?.message || String(err),
+      stack: err?.stack || null,
+    });
+  });
+
+  page.on("error", (err) => {
+    writeLog(targetId, {
+      type: "page.crash",
+      text: err?.message || String(err),
+      stack: err?.stack || null,
+    });
+  });
+
+  page.on("request", (req) => {
+    const requestId = ensureRequestId(targetId, req);
+    writeLog(targetId, {
+      type: "network.request",
+      requestId,
+      method: req.method?.() || null,
+      url: req.url?.() || null,
+      resourceType: req.resourceType?.() || null,
+      isNavigationRequest: !!req.isNavigationRequest?.(),
+      hasPostData: !!req.postData?.(),
+    });
+  });
+
+  page.on("response", (res) => {
+    try {
+      const req = res.request();
+      const requestId = ensureRequestId(targetId, req);
+      const headers = res.headers?.() || {};
+      const contentType = headers["content-type"] || headers["Content-Type"] || null;
+
+      writeLog(targetId, {
+        type: "network.response",
+        requestId,
+        url: res.url?.() || null,
+        status: res.status?.(),
+        statusText: res.statusText?.() || null,
+        mimeType: contentType,
+        fromDiskCache: !!res.fromCache?.(),
+        fromServiceWorker: !!res.fromServiceWorker?.(),
+      });
+    } catch (e) {
+      writeLog(targetId, {
+        type: "network.response",
+        requestId: null,
+        url: null,
+        status: null,
+        statusText: null,
+        mimeType: null,
+        error: e?.message || String(e),
+      });
+    }
+  });
+
+  page.on("requestfailed", (req) => {
+    const requestId = ensureRequestId(targetId, req);
+    writeLog(targetId, {
+      type: "network.failure",
+      requestId,
+      url: req.url?.() || null,
+      errorText: req.failure?.()?.errorText || null,
+      canceled: req.failure?.()?.errorText === "net::ERR_ABORTED",
+    });
+  });
+
+  page.on("framenavigated", (frame) => {
+    if (frame === page.mainFrame()) {
+      writeLog(targetId, {
+        type: "page.navigated",
+        url: frame.url?.() || null,
+      });
+    }
+  });
+
+  page.on("close", () => {
+    writeLog(targetId, { type: "target.closed" });
+    closeTarget(targetId);
+  });
+}
+
+function cleanupAndExit(code = 0) {
+  try {
+    for (const targetId of targetState.keys()) {
+      closeTarget(targetId);
+    }
+    try {
+      unlinkSync(PID_FILE);
+    } catch {
+      // ignore
+    }
+  } finally {
+    process.exit(code);
+  }
+}
+
+process.on("SIGINT", () => cleanupAndExit(0));
+process.on("SIGTERM", () => cleanupAndExit(0));
+
+async function main() {
+  const browser = await connectBrowser(5000).catch((e) => {
+    console.error("✗ Could not connect to browser:", e.message);
+    console.error("  Run: browser-start.js");
+    process.exit(1);
+  });
+
+  // Existing pages.
+  const pages = await browser.pages();
+  for (const page of pages) {
+    await instrumentPage(page);
+  }
+
+  // New pages.
+  browser.on("targetcreated", async (target) => {
+    try {
+      if (target.type?.() !== "page") return;
+      const page = await target.page();
+      if (page) await instrumentPage(page);
+    } catch {
+      // ignore
+    }
+  });
+
+  console.log(`✓ watch started (logs: ${dateDir})`);
+}
+
+await main();

package/skills/browser-tools/scripts/utils.js

@@ -0,0 +1,60 @@
+import puppeteer from "puppeteer-core";
+
+/**
+ * Connect to browser with timeout, exit on failure.
+ * @param {number} timeout - Connection timeout in ms (default: 5000)
+ * @returns {Promise<Browser>}
+ */
+export async function connectBrowser(timeout = 5000) {
+  const browser = await Promise.race([
+    puppeteer.connect({
+      browserURL: "http://127.0.0.1:9222",
+      defaultViewport: null,
+    }),
+    new Promise((_, reject) => {
+      setTimeout(() => reject(new Error("timeout")), timeout).unref();
+    }),
+  ]).catch((e) => {
+    console.error("✗ Could not connect to browser:", e.message);
+    console.error("  Run: browser-start.js");
+    process.exit(1);
+  });
+  return browser;
+}
+
+/**
+ * Get the active/focused page. Fall back to the last http/https page, then the last page.
+ * Exit if none found.
+ * @param {Browser} browser
+ * @returns {Promise<Page>}
+ */
+export async function getActivePage(browser) {
+  const pages = await browser.pages();
+  if (pages.length === 0) {
+    console.error("✗ No active tab found");
+    process.exit(1);
+  }
+
+  for (const page of [...pages].reverse()) {
+    try {
+      const isActive = await page.evaluate(
+        () => document.visibilityState === "visible" && document.hasFocus(),
+      );
+      if (isActive) return page;
+    } catch {}
+  }
+
+  return pages.filter((page) => page.url().startsWith("http")).at(-1) || pages.at(-1);
+}
+
+/**
+ * Print result, using JSON for objects/arrays.
+ * @param {any} result
+ */
+export function printResult(result) {
+  if (typeof result === "object" && result !== null) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result);
+  }
+}

package/skills/git-clean-history/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: git-clean-history
+description: "Reimplement the current Git branch on a fresh branch off `main` with a clean, narrative-quality commit history."
+---
+
+# Git Rebase
+
+Use this skill to reimplement the current branch on a new branch with a clean, narrative-quality git commit history suitable for reviewer comprehension.
+
+## Steps
+
+1. **Validate the source branch**
+   - Ensure no uncommitted changes or merge conflicts
+   - Confirm it is up to date with `main`
+
+2. **Analyze the diff**
+   - Study all changes between source branch and `main`
+   - Form a clear understanding of the final intended state
+
+3. **Create the clean branch**
+   - Create a new branch off of `main` using the new branch name
+   - Use the `{source_branch}-clean` name unless another name is provided by the user
+
+4. **Plan the commit storyline**
+   - Break the implementation into self-contained logical steps
+   - Each step should reflect a stage of development, as if writing a tutorial
+
+5. **Reimplement the work**
+   - Recreate changes in the clean branch, committing step by step
+   - Each commit must:
+     - Introduce a single coherent idea
+     - Include a clear commit message and description
+     - Follow best practices for the message as outlined by the `git-commit` skill
+   - **Use `git commit --no-verify` for all intermediate commits**
+     - Pre-commit hooks check tests, types, and imports that may not pass until the full implementation is complete; do not waste time fixing issues in intermediate commits that will be resolved by later commits
+
+6. **Verify correctness**
+   - Confirm the final state exactly matches the source branch
+   - Run the final commit **without** `--no-verify` to ensure all checks pass
+
+### Rules
+
+- Do not add yourself as an author or contributor
+- Do not include "Generated with ...", "Co-Authored-By: ...", or any AI attribution
+- The end state of the clean branch must be identical to the source branch

package/skills/git-commit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: git-commit
+description: "Commit changes with an emphasis on tidiness and reviewability: small, focused commits, with clear rationale in messages."
+---
+
+# Git Commit
+
+Use this skill as the playbook for producing reviewable commits and a clean, consistent commit history.
+
+## Phase 1: Review changes
+
+1. Check what files have changed
+2. If there are no changes to commit, inform the user and stop
+3. If there are unstaged changes, stage them with `git add`
+
+Rules:
+
+- Keep commits small, focused, and atomic
+- Avoid commits that mix unrelated changes (e.g., "Address feedback")
+- Never stage or commit files that look like secrets (e.g. `.env`, credentials, API keys)
+
+## Phase 2: Generate commit message
+
+1. Remember commit messages best practices
+2. Write a short subject line:
+   - Up to 50 chars
+   - Start subject with a capital letter, don’t end with a period
+   - Use imperative mood (e.g. "Fix memory leak while scrolling widget")
+3. Leave a blank line between subject and body
+4. Only when needed (don’t force it for trivial changes), write a body:
+   - Wrap lines at 72 chars
+   - Focus on "what" and "why", not the "how"
+     - Explain the motivation
+     - Mention side effects, trade-offs, or alternatives considered
+     - Reference relevant issue IDs / tickets at the bottom if known
+5. Check style of recent commits in the repo (tone, structure, capitalization, length, etc): `git log -10 --oneline`
+6. Generate a message that adheres to the style in the repo while following best practices
+
+Rules:
+
+- Never stage files that look like secrets (e.g. `.env`, credentials, API keys)
+- Do not add yourself as an author or contributor
+- Do not include "Generated with ...", "Co-Authored-By: ...", or any AI attribution
+
+## Phase 3: Commit
+
+1. Commit staged changes with `git commit`
+
+Rules:
+
+- Avoid `git commit --amend` unless explicitly requested
+- Do not bypass hooks with `git commit --no-verify`
+  - If `git commit` fails due to hooks, fix issues and retry
+- Use `git commit -F` (or heredoc) when there is a body, never newline escapes in `-m`.
+- Never push to remotes unless explicitly requested

package/skills/oracle/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: oracle
+description: Get a second opinion by bundling a prompt + a curated file set, then asking a strong model from a different family through a separate Pi invocation.
+---
+
+# Oracle
+
+Use this skill when you want a second opinion from a capable model in a different family than the current session.
+
+The oracle workflow bundles selected files into a standalone prompt, selects an alternate model with `pi --list-models`, and sends the bundle to `pi -p --no-tools`. It is read-only by default because the oracle receives the selected context directly and does not get tools.
+
+## Model selection
+
+The `./scripts/oracle` wrapper chooses the strongest known model it can find in the first usable family from this order:
+
+| Current family     | Oracle preference                                     |
+| ------------------ | ----------------------------------------------------- |
+| OpenAI / Codex     | Claude / Anthropic → Gemini / Google → OpenAI / Codex |
+| Claude / Anthropic | OpenAI / Codex → Gemini / Google → Claude / Anthropic |
+| Gemini / Google    | OpenAI / Codex → Claude / Anthropic → Gemini / Google |
+| Unknown            | Claude / Anthropic → OpenAI / Codex → Gemini / Google |
+
+It prefers models listed in Pi's `enabledModels`, then falls back to the best matching model shown by `pi --list-models`. Override only when needed with `--model provider/model`.
+
+If the current model is not obvious to the script, pass it explicitly with `--current provider/model`. Otherwise it falls back to Pi's default model from `settings.json`.
+
+## Workflow
+
+1. Pick the smallest file set that contains the truth. Avoid secrets by default.
+2. Preview selected files before sending.
+3. Ask the oracle with a standalone prompt that states the task, constraints, and desired output format.
+4. Treat the result as advice, not authority. Reason from first principles before applying recommendations.
+
+## Commands
+
+Run commands from this skill directory:
+
+```bash
+# Preview selected files
+./scripts/oracle-bundle --dry-run -p "<task>" --file "src/**" --file "!**/*.test.*"
+
+# Preview the full bundle
+./scripts/oracle-bundle -p "<task>" --file "src/**" --file "!**/*.test.*"
+
+# Show which oracle model would be selected
+./scripts/oracle --list-models --current openai-codex/gpt-5.5
+
+# Ask the automatically selected oracle model
+./scripts/oracle --current openai-codex/gpt-5.5 \
+  -p "<task>" --file "src/**" --file "!**/*.test.*"
+
+# Override the oracle model when the automatic choice is wrong
+./scripts/oracle --model github-copilot/claude-opus-4.7 \
+  -p "<task>" --file "src/**" --file "!**/*.test.*"
+```
+
+## Tips
+
+- Prefer a minimal file set over the whole repo.
+- If you need diffs reviewed, paste the diff into the prompt or attach the diff file via `--file`.
+- Make the prompt completely standalone: include intent, goals, constraints, error text, and whether you want a plan, review, pros/cons, or patch guidance.
+- Never include secrets (`.env`, tokens, key files).
+- For general code review, ask for feedback on correctness, consistency with existing code, simplicity, maintainability, performance, security, and edge cases.
+- Oracle can be slow while it reasons. Allow it several minutes to process.