pi-tandem 0.2.0 → 0.3.0

package/README.md

@@ -18,6 +18,17 @@ Modern coding agents lean toward autonomy: multi-file changes in one go, subagen
 - **`subagent` skill** to run a task in a fresh agent session on request, with full visibility and control, instead of harness-managed subagents
 - **Tool-specific instructions** (`gh`, `aws`, `jira`, ...), added to the prompt only if the tool is actually installed
 
+## Recommended tools
+
+The plugin notices which CLI tools are actually installed on your machine, and for each one it finds, adds a short note telling the model that the tool is available and recommended to use. Installing these gets you significantly more out of this package:
+
+- `gh` - GitHub CLI: repos, issues, PRs, releases, workflows
+- `pandoc` - read docx/odt/rtf/html (and fetched web pages) as text instead of raw markup
+- `pdftotext` (poppler) - extract text from PDFs
+- a Chromium-based browser (Brave, Chromium, Chrome, Edge) - headless-render fallback for JS-heavy or bot-blocked pages
+- `osascript` (macOS only) - drive the user's real browser sessions via AppleScript
+- `jira`, `aws`, `saml2aws` - if your workflow includes them
+
 ## Attribution
 
 The "lazy senior" part of the coding section in the prompt is adapted from [ponytail](https://github.com/DietrichGebert/ponytail) by DietrichGebert (MIT).

package/extensions/tandem/index.ts

@@ -1,8 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import injectProjectContext from "./pi-tandem";
-import registerWebTools from "./web-tools";
 
 export default function (pi: ExtensionAPI) {
   injectProjectContext(pi);
-  registerWebTools(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tandem",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/skhoroshavin/tandem-skills.git"
@@ -9,6 +9,7 @@
   "keywords": [
     "pi-package"
   ],
+  "type": "module",
   "license": "MIT",
   "files": [
     "extensions/",
@@ -17,5 +18,10 @@
     "prompt.md",
     "LICENSE",
     "README.md"
-  ]
+  ],
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2"
+  }
 }

package/prompt.md

@@ -43,6 +43,17 @@ A number of CLI tools are installed on this laptop and fully authenticated, you'
 <!--cli:saml2aws-->
 - AWS credentials are short-lived: on an expired or invalid token error, ask the user to run saml2aws login --idp-account <profile> --skip-prompt themselves, giving them the full command to copy-paste
 <!--/cli-->
+<!--cli:pdftotext-->
+- Use `pdftotext` to extract text from PDFs: `pdftotext input.pdf output.txt`, or `pdftotext input.pdf -` to print to stdout
+<!--/cli-->
+<!--cli:pandoc-->
+- Use `pandoc` to read documents other than pdf as markdown or plain text: `pandoc input.docx -o output.md` (also works for odt, rtf, html, ...)
+- Unless your task requires seeing actual tags, always convert HTML fetched from the web to plain text or markdown, instead of reading it raw, for example when using `curl`: `curl -s <url> | pandoc -f html -t plain`.
+<!--/cli-->
+<!--cli:browser-->
+- Use a real headless browser when you need to read a JS-rendered or bot-blocked page: `<browser-binary> --headless --disable-gpu --user-data-dir=$(mktemp -d) --dump-dom --virtual-time-budget=5000 <url>`
+- When in doubt, always try `curl` first before resorting to a headless browser
+<!--/cli-->
 <!--cli:osascript-->
 - Use `osascript` with `execute <tab> javascript "<js>"` to read pages and interact using the user's
   real logged-in sessions (analyzing dashboards, checking Google Calendar and Mail, etc)

package/runtime/cli-tools.mjs

@@ -18,18 +18,41 @@ export function isOnPath(binary) {
   return false;
 }
 
+// Chromium-family binary for the headless-render fallback; PATH first, then app bundles
+function findBrowserBinary() {
+  for (const name of ["brave", "brave-browser", "chromium", "chromium-browser", "google-chrome", "google-chrome-stable"]) {
+    if (isOnPath(name)) return name;
+  }
+  if (process.platform === "darwin") {
+    for (const app of ["Brave Browser", "Chromium", "Google Chrome", "Microsoft Edge"]) {
+      const bin = `/Applications/${app}.app/Contents/MacOS/${app}`;
+      try {
+        if (statSync(bin).isFile()) return bin;
+      } catch {}
+    }
+  }
+}
+
 // drop <!--cli:tool--> blocks for absent tools, and the whole section when none remain
+function toolAvailable(tool, browser) {
+  if (tool === "browser") return browser !== undefined;
+  if (tool === "osascript") return process.platform === "darwin" && isOnPath(tool);
+  return isOnPath(tool);
+}
+
 export function filterCliTools(raw) {
-  let any = false;
-  const filtered = raw.replace(
-    /<!--cli:([a-z0-9]+)-->\n([\s\S]*?)<!--\/cli-->\n?/g,
-    (_marker, tool, body) => {
-      const available =
-        tool === "osascript" ? process.platform === "darwin" && isOnPath(tool) : isOnPath(tool);
-      if (!available) return "";
-      any = true;
-      return body;
-    },
-  ).replace(/\n{3,}/g, "\n\n");
-  return any ? filtered : filtered.replace(/\n## CLI tools[\s\S]*?(?=\n## )/, "");
+  let hasTools = false;
+  const browser = findBrowserBinary();
+  const filtered = raw
+    .replace(
+      /<!--cli:([a-z0-9]+)-->\r?\n?([\s\S]*?)<!--\/cli-->\r?\n?/g,
+      (_marker, tool, body) => {
+        if (!toolAvailable(tool, browser)) return "";
+        hasTools = true;
+        return body;
+      },
+    )
+    .replace(/<browser-binary>/g, () => (browser ? JSON.stringify(browser) : "<browser-binary>"))
+    .replace(/\n{3,}/g, "\n\n");
+  return hasTools ? filtered : filtered.replace(/\n## CLI tools[\s\S]*?(?=\n## )/, "");
 }

package/skills/code-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: code-review
+description: Use when asked to do a code review.
+---
+
+Read the full diff and everything it touches before judging; the worst review
+mistakes come from reviewing the diff only.
+
+Report rules:
+
+- Actionable findings only, ordered by severity: ones requiring changes, or
+  at least explicit decisions; "checked and fine" does not qualify.
+- Each finding: what is wrong and why it matters in 1-3 lines, then the
+  smallest fix - as a diff if it fits within 50 LoC, otherwise described
+  generally, asking for a decision.
+- No praise, no diff summary, no restating the request, no advice beyond
+  findings.
+- If nothing actionable: say exactly that, plus one line on what was checked.
+- Before writing, verify: grep for references to removed or renamed
+  identifiers; where the repo has rendered build output, check it is in sync;
+  diff the commit message claims against the actual change.

package/extensions/tandem/web-tools.ts

@@ -1,246 +0,0 @@
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { formatSize, type TruncationResult, truncateHead } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
-// web_search (Brave Search API) and web_fetch (generic HTTP reader) for pi.
-
-const MIN_SEARCH_RESULTS = 1;
-const MAX_SEARCH_RESULTS = 10;
-const DEFAULT_SEARCH_RESULTS = 5;
-const BRAVE_API_KEY_ENV_VAR = "BRAVE_SEARCH_API_KEY";
-
-interface SearchResult {
-  title: string;
-  url: string;
-  snippet: string;
-}
-
-function refusePrivateHost(hostname: string): never {
-  throw new Error(`Refusing to fetch private/loopback address: ${hostname}`);
-}
-
-// Rejects anything that is not a public http(s) endpoint: no non-HTTP schemes,
-// and hostnames that point at loopback, RFC1918, link-local (incl. cloud
-// metadata) or IPv6 local addresses. Literal hostnames only - no DNS lookup.
-function assertPublicHttpUrl(raw: string): void {
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } catch {
-    throw new Error(`Invalid URL: ${raw}`);
-  }
-  if (!/^https?:$/.test(url.protocol)) {
-    throw new Error(`Unsupported URL protocol: ${url.protocol}. Only http and https are supported.`);
-  }
-
-  const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-  if (host.includes(":")) {
-    // IPv6 literal (DNS names never contain ":"); ::ffff:* are IPv4-mapped
-    // forms whose dotted target is hidden by URL canonicalization.
-    if (
-      host === "::" ||
-      host === "::1" ||
-      host.startsWith("fe80:") ||
-      host.startsWith("fc") ||
-      host.startsWith("fd") ||
-      host.startsWith("::ffff:")
-    ) {
-      refusePrivateHost(url.hostname);
-    }
-  } else {
-    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
-    if (v4) {
-      const [a, b] = [Number(v4[1]), Number(v4[2])];
-      const reserved =
-        a === 0 || // unspecified
-        a === 10 || // RFC1918
-        a === 127 || // loopback
-        (a === 169 && b === 254) || // link-local, incl. cloud metadata
-        (a === 172 && b >= 16 && b <= 31) || // RFC1918
-        (a === 192 && b === 168); // RFC1918
-      if (reserved) refusePrivateHost(url.hostname);
-    }
-  }
-}
-
-const OMITTED_ELEMENTS_REGEX = /<(script|style|noscript)\b[\s\S]*?<\/\1>/gi;
-const BLOCK_BREAK_REGEX =
-  /<\/(p|div|h[1-6]|li|tr|blockquote|pre|section|article|header|footer|nav|details|summary)>|<br\s*\/?>/gi;
-const ANY_TAG_REGEX = /<[^>]+>/g;
-const TITLE_TAG_REGEX = /<title[^>]*>([\s\S]*?)<\/title>/i;
-
-function htmlToText(html: string): string {
-  let text = html.replace(OMITTED_ELEMENTS_REGEX, "").replace(BLOCK_BREAK_REGEX, "\n");
-  text = text.replace(ANY_TAG_REGEX, " ");
-  text = text
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&nbsp;/g, " ")
-    .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
-  return text.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
-}
-
-function pageTitle(html: string): string | undefined {
-  return html.match(TITLE_TAG_REGEX)?.[1].replace(ANY_TAG_REGEX, "").trim() || undefined;
-}
-
-async function braveSearch(
-  query: string,
-  maxResults: number,
-  apiKey: string,
-  signal: AbortSignal | undefined,
-): Promise<SearchResult[]> {
-  const url = new URL("https://api.search.brave.com/res/v1/web/search");
-  url.searchParams.set("q", query);
-  url.searchParams.set("count", String(maxResults));
-  const res = await fetch(url.toString(), {
-    headers: {
-      Accept: "application/json",
-      "Accept-Encoding": "gzip",
-      "X-Subscription-Token": apiKey,
-    },
-    signal,
-  });
-  if (!res.ok) {
-    throw new Error(`Brave API error (${res.status}): ${await res.text()}`);
-  }
-  const raw = (await res.json()) as { web?: { results?: Array<{ title?: string; url?: string; description?: string }> } };
-  return (raw.web?.results ?? []).map((r) => ({ title: r.title ?? "", url: r.url ?? "", snippet: r.description ?? "" }));
-}
-
-async function readPage(url: string, raw: boolean, signal: AbortSignal | undefined): Promise<{ text: string; title?: string; contentType?: string }> {
-  const res = await fetch(url, {
-    signal,
-    redirect: "follow",
-    headers: {
-      "User-Agent": "Mozilla/5.0 (compatible; tandem-pi/1.0)",
-      Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.5",
-    },
-  });
-  if (!res.ok) {
-    throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
-  }
-  const contentType = res.headers.get("content-type") ?? "";
-  if (/^(image|video|audio)\//.test(contentType)) {
-    throw new Error(`Unsupported content type: ${contentType}. web_fetch supports text pages only.`);
-  }
-  const rawBody = await res.text();
-  const pageContentType = contentType || undefined;
-  if (!raw && /text\/html/.test(contentType)) {
-    return { text: htmlToText(rawBody), title: pageTitle(rawBody), contentType: pageContentType };
-  }
-  return { text: rawBody, contentType: pageContentType };
-}
-
-async function writeTempCopy(content: string): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), "tandem-fetch-"));
-  const file = join(dir, "content.txt");
-  await writeFile(file, content, "utf8");
-  return file;
-}
-
-function formatTruncationNote(truncation: TruncationResult, tempFile: string): string {
-  const omittedLines = truncation.totalLines - truncation.outputLines;
-  const omittedBytes = truncation.totalBytes - truncation.outputBytes;
-  return (
-    `\n\n[Content truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines` +
-    ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).` +
-    ` ${omittedLines} lines (${formatSize(omittedBytes)}) omitted.` +
-    ` Full content saved to: ${tempFile}]`
-  );
-}
-
-function formatSearchResults(query: string, results: SearchResult[]): string {
-  const header = `**Search results for "${query}":**`;
-  const list = results
-    .map((r, i) => `${i + 1}. **${r.title}**\n   ${r.url}\n   ${r.snippet}`)
-    .join("\n\n");
-  return `${header}\n\n${list}`;
-}
-
-function formatPageHeader(url: string, title: string | undefined, contentType: string): string {
-  const lines = [`**Fetched:** ${url}`];
-  if (title) lines.push(`**Title:** ${title}`);
-  if (contentType) lines.push(`**Content-Type:** ${contentType}`);
-  return `${lines.join("\n")}\n\n`;
-}
-
-export default function (pi: ExtensionAPI) {
-  pi.registerTool({
-    name: "web_search",
-    label: "Web Search",
-    description:
-      "Search the web for information. Returns a list of results with titles, URLs, and snippets. Use when you need current information not in your training data.",
-    parameters: Type.Object({
-      query: Type.String({
-        description: "The search query. Be specific and use natural language.",
-      }),
-      max_results: Type.Optional(
-        Type.Number({
-          description: `Maximum number of results to return (${MIN_SEARCH_RESULTS}-${MAX_SEARCH_RESULTS}). Default: ${DEFAULT_SEARCH_RESULTS}.`,
-          default: DEFAULT_SEARCH_RESULTS,
-          minimum: MIN_SEARCH_RESULTS,
-          maximum: MAX_SEARCH_RESULTS,
-        }),
-      ),
-    }),
-    async execute(_toolCallId, params, signal, onUpdate) {
-      const apiKey = process.env[BRAVE_API_KEY_ENV_VAR]?.trim();
-      if (!apiKey) {
-        throw new Error(`${BRAVE_API_KEY_ENV_VAR} is not set. Export it to enable web_search.`);
-      }
-      onUpdate?.({
-        content: [{ type: "text", text: `Searching Brave for: "${params.query}"...` }],
-        details: undefined,
-      });
-      const maxResults = Math.min(
-        Math.max(params.max_results ?? DEFAULT_SEARCH_RESULTS, MIN_SEARCH_RESULTS),
-        MAX_SEARCH_RESULTS,
-      );
-      const results = await braveSearch(params.query, maxResults, apiKey, signal);
-      if (results.length === 0) {
-        return { content: [{ type: "text", text: `No results found for "${params.query}".` }], details: undefined };
-      }
-      return { content: [{ type: "text", text: formatSearchResults(params.query, results) }], details: undefined };
-    },
-  });
-
-  pi.registerTool({
-    name: "web_fetch",
-    label: "Web Fetch",
-    description:
-      "Fetch the content of a specific URL. Returns text content for HTML pages (tags stripped), raw text for plain text or JSON. Supports http and https only. Content is truncated to avoid overwhelming the context window.",
-    parameters: Type.Object({
-      url: Type.String({
-        description: "The URL to fetch. Must be http or https.",
-      }),
-      raw: Type.Optional(
-        Type.Boolean({
-          description: "If true, return the raw HTML instead of extracted text. Default: false.",
-          default: false,
-        }),
-      ),
-    }),
-    async execute(_toolCallId, params, signal, onUpdate) {
-      const { url, raw = false } = params;
-      assertPublicHttpUrl(url);
-      onUpdate?.({ content: [{ type: "text", text: `Fetching: ${url}...` }], details: undefined });
-      const { text: pageText, title, contentType } = await readPage(url, raw, signal);
-      const truncation = truncateHead(pageText);
-      let output = truncation.content;
-      if (truncation.truncated) {
-        output += formatTruncationNote(truncation, await writeTempCopy(pageText));
-      }
-      return {
-        content: [{ type: "text", text: formatPageHeader(url, title, contentType ?? "") + output }],
-        details: undefined,
-      };
-    },
-  });
-}