tau-all-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/homeassistant-ops/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: homeassistant-ops
+description: "Operate a Home Assistant instance via the official REST/WebSocket APIs and backups, with safe plan/apply workflows for bulk, reviewable changes."
+---
+
+# Home Assistant Ops
+
+Use this skill as the operator's playbook for making bulk, reviewable changes
+to a Home Assistant instance without SSHing into the host.
+
+## Setup
+
+Set environment variables (never pass tokens on the command line):
+
+```bash
+export HA_URL="http://<home-assistant-host>:8123"
+export HA_TOKEN="<long-lived-access-token>"
+```
+
+Explore the operations:
+
+```bash
+"./scripts/ha_ops.js" --help
+```
+
+Keep logs in a working folder (scripts write timestamped `.md` files by default).
+
+## First questions (to avoid rework)
+
+- What's the HA version and deployment type (OS / Container / Core)?
+- Which Zigbee stack is used (ZHA vs Zigbee2MQTT) and which devices are affected?
+- Which parts are YAML-managed vs UI-managed (automations, scripts, scenes, dashboards)?
+- Do we have a recent backup to inspect before making bulk changes?
+- Is the goal UI clarity, automation correctness, performance/latency, or all of the above?
+
+## Core concepts (what to change where)
+
+- **Entity registry**: source of truth for friendly-name overrides, entity_id renames, hidden/disabled, and some area assignment.
+- **Device registry**: best place to assign areas for physical devices (entity area often inherits).
+- **Blueprint inputs**: not templatable; state triggers need a static entity list at config-load time.
+- **HA "group helpers"**: great for UI/targeting/maintenance, but they don't make Zigbee unicast faster (they expand to member calls).
+
+## Scripts
+
+All scripts read `HA_URL` and `HA_TOKEN` from environment variables.
+
+### `ha_ops.js` - Single CLI with subcommands
+
+All operations are available under a single CLI:
+
+```bash
+# List commands
+node scripts/ha_ops.js --help
+
+# Command help
+node scripts/ha_ops.js cleanup --help
+```
+
+### `ha_ops.js cleanup` - Bulk cleanup (dry-run by default)
+
+```bash
+# Dry-run all default steps (default)
+node scripts/ha_ops.js cleanup
+
+# Apply specific steps
+node scripts/ha_ops.js cleanup --apply \
+  --steps rename-switch-suffix,prefix-lights-cove
+
+# Prefix custom patterns with area names
+node scripts/ha_ops.js cleanup --apply \
+  --steps prefix-generic \
+  --pattern "Thermometer:^Thermometer" \
+  --pattern "Blinds:^Blinds"
+
+# Output proposed changes as JSON
+node scripts/ha_ops.js cleanup --json
+```
+
+Available steps:
+
+- `rename-switch-suffix`: Rename "Lights ... Switch" to "Lights ..."
+- `create-groups`: Create/update switch groups for sync automations
+- `prefix-lights-cove`: Prefix Lights/Cove names with area
+- `prefix-generic`: Prefix entities matching `--pattern` with area
+
+### `ha_ops.js snapshot` - Capture state for diffing
+
+```bash
+# Full snapshot
+node scripts/ha_ops.js snapshot
+
+# Skip noisy sections
+node scripts/ha_ops.js snapshot \
+  --no-lovelace --no-scenes
+
+# Include runtime states (noisy for diffs)
+node scripts/ha_ops.js snapshot --include-states
+```
+
+### `ha_ops.js rollback` - Revert registry changes from a snapshot
+
+```bash
+# Preview what would be rolled back
+node scripts/ha_ops.js rollback \
+  snapshot_before.json --dry-run
+
+# Apply rollback
+node scripts/ha_ops.js rollback \
+  snapshot_before.json --yes
+```
+
+### `ha_ops.js find-references` - Find entity_id usage
+
+```bash
+# Search for entity references before renaming
+node scripts/ha_ops.js find-references \
+  --needle "switch.bedroom_lights"
+
+# Search from a rename mapping file
+node scripts/ha_ops.js find-references \
+  --map-json rename_map.json --backup-root /path/to/backup
+```
+
+### `ha_ops.js update-groups` - Update group memberships after renames
+
+Entity ID renames (via the entity registry) do **not** propagate to config
+entry–based group helpers. This command rewrites group member lists using a
+rename map.
+
+```bash
+# Preview which groups would be updated
+node scripts/ha_ops.js update-groups \
+  --map-json rename_map.json
+
+# Apply changes
+node scripts/ha_ops.js update-groups \
+  --map-json rename_map.json --apply
+
+# Output plan as JSON
+node scripts/ha_ops.js update-groups \
+  --map-json rename_map.json --json
+```
+
+### `ha_ops.js tail-events` - Monitor events in real-time
+
+```bash
+# Tail state changes
+node scripts/ha_ops.js tail-events
+
+# Filter to specific entities
+node scripts/ha_ops.js tail-events \
+  --entity switch.bedroom_lights --entity switch.bedroom_lights_2
+
+# Include ZHA events
+node scripts/ha_ops.js tail-events \
+  --event-type state_changed --event-type zha_event
+```
+
+### `ha_ops.js name-review-from-backup` - Offline naming analysis
+
+```bash
+# Analyze backup for naming candidates
+node scripts/ha_ops.js name-review-from-backup \
+  --backup-root /path/to/backup
+```
+
+## Error recovery
+
+If a script fails mid-way:
+
+1. Check the log file for what was applied before the failure.
+2. Use `ha_ops.js rollback` with your before-snapshot to revert registry changes.
+3. Fix the underlying issue (network, permissions, entity conflicts).
+4. Re-run the script (operations are generally idempotent).
+
+## Resources
+
+- API reference: `references/api.md`
+- Ops playbook: `references/playbook.md`
+- Entity ID conventions: `references/id_conventions.md`
+
+## Logging convention
+
+Prefer one markdown log per run (timestamped), listing every entity/automation changed and the before/after values.