pi-t3-bridge 0.3.0 → 0.4.0

package/src/pstack/models.ts

@@ -1,12 +1,12 @@
 import { readFileSync } from "node:fs";
 
-import { Type } from "@earendil-works/pi-ai";
-import type { Static } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import type {
   ExtensionAPI,
   ExtensionToolContext,
 } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
 import { Value } from "typebox/value";
 
 import {

package/src/pstack/overlay.ts

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+interface Patch {
+  readonly find: string;
+  readonly replace: string;
+}
+
+const PatchSchema = Type.Object({
+  find: Type.String(),
+  replace: Type.String(),
+});
+
+const OverlayManifestSchema = Type.Object({
+  files: Type.Record(Type.String(), Type.Array(PatchSchema)),
+  global: Type.Array(PatchSchema),
+  shared: Type.Array(
+    Type.Object({
+      files: Type.Array(Type.String()),
+      patches: Type.Array(PatchSchema),
+    })
+  ),
+  version: Type.Number(),
+});
+
+export type OverlayManifest = Static<typeof OverlayManifestSchema>;
+
+const TEXT_SUFFIX = ".md";
+const COPIED_ENTRIES = ["skills", "agents", "models.json"] as const;
+
+export const overlayDir = (extensionDir: string): string =>
+  path.join(extensionDir, "overlay");
+
+export const loadManifest = (dir: string): OverlayManifest => {
+  const manifestPath = path.join(dir, "overlay.json");
+  const parsed: unknown = JSON.parse(readFileSync(manifestPath, "utf-8"));
+
+  if (!Value.Check(OverlayManifestSchema, parsed)) {
+    throw new Error(
+      `overlay manifest ${manifestPath} does not match the overlay schema`
+    );
+  }
+
+  return parsed;
+};
+
+const patchesFor = (
+  manifest: OverlayManifest,
+  relativePath: string
+): readonly Patch[] => {
+  const own = manifest.files[relativePath] ?? [];
+
+  const shared = manifest.shared
+    .filter((group) => group.files.includes(relativePath))
+    .flatMap((group) => group.patches);
+
+  return [...shared, ...own];
+};
+
+export const applyOverlay = (
+  manifest: OverlayManifest,
+  relativePath: string,
+  text: string
+): string => {
+  let result = text;
+
+  for (const patch of patchesFor(manifest, relativePath)) {
+    if (!result.includes(patch.find)) {
+      throw new Error(
+        `overlay patch for ${relativePath} no longer matches upstream text: ${JSON.stringify(patch.find.slice(0, 120))}. Update overlay/overlay.json for the new upstream wording.`
+      );
+    }
+
+    result = result.replaceAll(patch.find, patch.replace);
+  }
+
+  for (const patch of manifest.global) {
+    result = result.replaceAll(patch.find, patch.replace);
+  }
+
+  return result;
+};
+
+const walkFiles = (root: string, base = root): string[] =>
+  readdirSync(base, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(base, entry.name);
+
+    if (entry.isDirectory()) {
+      return walkFiles(root, full);
+    }
+
+    return entry.isFile() ? [path.relative(root, full)] : [];
+  });
+
+const overlayCacheRoot = (): string => {
+  const stateHome =
+    process.env.XDG_STATE_HOME?.trim() ||
+    path.join(homedir(), ".local", "state");
+
+  return path.join(stateHome, "pi-t3", "pstack-overlay");
+};
+
+const INPUT_ENTRIES = [
+  ...COPIED_ENTRIES,
+  "hooks/session-start-context.md",
+] as const;
+
+const fingerprint = (
+  upstreamRoot: string,
+  manifestText: string,
+  extensionModules: string
+): string => {
+  const hash = createHash("sha256")
+    .update(manifestText)
+    .update(extensionModules);
+
+  for (const entry of INPUT_ENTRIES) {
+    const full = path.join(upstreamRoot, entry);
+
+    if (!existsSync(full)) {
+      continue;
+    }
+
+    const files = statSync(full).isDirectory() ? walkFiles(full) : [entry];
+
+    for (const relative of files.toSorted()) {
+      const filePath = statSync(full).isDirectory()
+        ? path.join(full, relative)
+        : full;
+
+      const name = statSync(full).isDirectory()
+        ? path.join(entry, relative)
+        : entry;
+
+      hash.update(name).update(readFileSync(filePath));
+    }
+  }
+
+  return hash.digest("hex").slice(0, 16);
+};
+
+// The pstack the agent reads: upstream copied out of pstack/, with the
+// overlay in overlay/ applied. A copy keyed by the hash of both inputs, so
+// an upstream sync or an overlay edit builds a fresh copy and a stale one
+// is never served. Nothing here writes into pstack/.
+export const materializePstack = (
+  upstreamRoot: string,
+  dir: string,
+  cacheRoot: string = overlayCacheRoot()
+): string => {
+  if (!existsSync(path.join(upstreamRoot, "skills"))) {
+    return upstreamRoot;
+  }
+
+  const manifestText = readFileSync(path.join(dir, "overlay.json"), "utf-8");
+  const manifest = loadManifest(dir);
+
+  const extensionModules = path.resolve(
+    path.dirname(upstreamRoot),
+    "node_modules"
+  );
+
+  const target = path.join(
+    cacheRoot,
+    fingerprint(upstreamRoot, manifestText, extensionModules)
+  );
+
+  if (
+    existsSync(path.join(target, ".complete")) &&
+    (!existsSync(extensionModules) ||
+      existsSync(path.join(target, "node_modules")))
+  ) {
+    return target;
+  }
+
+  mkdirSync(cacheRoot, { recursive: true });
+  rmSync(target, { force: true, recursive: true });
+
+  const staging = `${target}.${process.pid}.tmp`;
+
+  rmSync(staging, { force: true, recursive: true });
+
+  try {
+    for (const entry of COPIED_ENTRIES) {
+      const from = path.join(upstreamRoot, entry);
+
+      if (existsSync(from)) {
+        cpSync(from, path.join(staging, entry), { recursive: true });
+      }
+    }
+
+    const hookFrom = path.join(
+      upstreamRoot,
+      "hooks",
+      "session-start-context.md"
+    );
+
+    if (existsSync(hookFrom)) {
+      mkdirSync(path.join(staging, "hooks"), { recursive: true });
+      cpSync(hookFrom, path.join(staging, "hooks", "session-start-context.md"));
+    }
+
+    // Scripts under skills/ import packages such as commander. Inside the
+    // extension they resolve them from the extension's node_modules, so
+    // the copy links that directory in instead of copying it.
+    if (
+      existsSync(extensionModules) &&
+      !existsSync(path.join(staging, "node_modules"))
+    ) {
+      symlinkSync(extensionModules, path.join(staging, "node_modules"), "dir");
+    }
+
+    for (const relative of walkFiles(staging)) {
+      if (!relative.endsWith(TEXT_SUFFIX)) {
+        continue;
+      }
+
+      const filePath = path.join(staging, relative);
+
+      writeFileSync(
+        filePath,
+        applyOverlay(manifest, relative, readFileSync(filePath, "utf-8"))
+      );
+    }
+
+    writeFileSync(path.join(staging, ".complete"), "");
+    renameSync(staging, target);
+  } catch (error) {
+    rmSync(staging, { force: true, recursive: true });
+    throw error;
+  }
+
+  return target;
+};

package/src/pstack/resources.ts

@@ -1,21 +1,35 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 
+import { materializePstack, overlayDir } from "./overlay.ts";
+
 export interface PstackPaths {
   readonly extensionDir: string;
   readonly pstackRoot: string;
   readonly skillsDir: string;
+  readonly upstreamRoot: string;
 }
 
+let cached: PstackPaths | undefined;
+
 export const pstackPaths = (): PstackPaths => {
+  if (cached) {
+    return cached;
+  }
+
   const extensionDir = path.resolve(import.meta.dirname, "../..");
-  const pstackRoot = path.join(extensionDir, "pstack");
+  const upstreamRoot = path.join(extensionDir, "pstack");
+
+  const pstackRoot = materializePstack(upstreamRoot, overlayDir(extensionDir));
 
-  return {
+  cached = {
     extensionDir,
     pstackRoot,
     skillsDir: path.join(pstackRoot, "skills"),
+    upstreamRoot,
   };
+
+  return cached;
 };
 
 export const policyPath = (): string =>

package/src/pstack/results.ts

@@ -1,5 +1,5 @@
-import { Type } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { readLedger } from "../bridge/state.ts";

package/src/pstack/sandbox.ts

@@ -4,7 +4,7 @@ import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 
-import { Type } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { readConfig } from "../bridge/config.ts";

package/src/pstack/session.ts

@@ -57,22 +57,8 @@ export const sessionHookEnabled = (): boolean => {
   return !SESSION_HOOK_OFF.test(readFileSync(sheetPath, "utf-8"));
 };
 
-// Upstream's hook text is written for Claude Code and Codex. Each pair
-// rewrites a part that reads differently on Pi, where pstack_model reads the
-// model sheet and no shell output budget cuts a SKILL.md.
-const PI_REWRITES: readonly (readonly [string, string])[] = [
-  ["You have t3-pstack,", "You have pi-t3-bridge,"],
-  ["t3-pstack:poteto-mode", "/skill:poteto-mode"],
-  [
-    " On Codex, open its SKILL.md whole, in a shell call of its own with `max_output_tokens: 10000`, since a smaller budget cuts out its middle.",
-    " Read its SKILL.md in full before you act.",
-  ],
-  [
-    "This runs on T3: before the first subagent or panel in a session, read the model sheet, `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), or `t3-pstack-models.md` in this host's config directory when that file is missing. This chat runs the playbook itself. A step it says to delegate goes through `delegate_task` to that role's sheet entry,",
-    "This chat runs the playbook itself. A step it says to delegate goes through `delegate_task` with a target from `pstack_model`,",
-  ],
-];
-
+// paths.pstackRoot already has the overlay applied, so the hook text on
+// disk is the Pi text. The overlay owns every rewrite of upstream wording.
 export const sessionGuidance = (paths: PstackPaths): string => {
   const contextPath = path.join(
     paths.pstackRoot,
@@ -80,18 +66,12 @@ export const sessionGuidance = (paths: PstackPaths): string => {
     "session-start-context.md"
   );
 
-  const upstreamGuidance = existsSync(contextPath)
+  const guidance = existsSync(contextPath)
     ? readFileSync(contextPath, "utf-8").trim()
     : "You have pi-t3-bridge, pstack for T3 Code.";
 
-  let piGuidance = upstreamGuidance;
-
-  for (const [from, to] of PI_REWRITES) {
-    piGuidance = piGuidance.replaceAll(from, to);
-  }
-
   return [
-    piGuidance,
+    guidance,
     "",
     "Pi notes:",
     `- The pstack root is ${paths.pstackRoot}. Read skill and agent files there when a skill names a plugin root.`,

package/tstack/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Theo Browne
+
+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/tstack/README.md

@@ -0,0 +1,53 @@
+# tstack
+
+The agent skills I use every day, cleaned up so anyone can use them. They work
+in Claude Code and Codex. Some use [T3 Code](https://github.com/pingdotgg/t3code)
+features when they are available and fall back to native tools when they are
+not.
+
+## Skills
+
+| Skill | Say | What it does |
+|---|---|---|
+| `full-send` | "full send" | Takes a change to a merged PR with nobody watching: proves it, reviews it, files it, babysits it, merges it. |
+| `full-stop` | "full stop" | Same as `full-send`, but stops when the PR is ready for you to merge. |
+| `council` | "council" | Gets review from three models from different providers, and loops until they agree. |
+| `sol-loop` | "sol loop" | Reviews a change with GPT Sol in a loop until both agents agree. |
+| `file-pr` | "file a PR" | Files a short PR that leads with the problem, not an inventory of changes. |
+| `takeover` | "take over" | Finishes someone else's PR, branch, or agent thread, and keeps their credit. |
+| `babysit-pr` | "babysit" | Watches a PR through CI and review bots, and fixes the real findings. |
+| `modernize` | "modernize" | Rebases an old PR and decides if it should still exist. |
+| `leaving-pr-comments` | (automatic) | Formats comments that an agent posts on your behalf. |
+
+Some skills call others. Install the ones they need too:
+
+- `full-send` uses `sol-loop`, `file-pr`, and `babysit-pr`.
+- `full-stop` uses `full-send`.
+- `takeover` uses `modernize`, `file-pr`, `babysit-pr`, and `leaving-pr-comments`.
+- `file-pr`, `babysit-pr`, and `modernize` use `leaving-pr-comments`.
+
+## Install
+
+```bash
+git clone https://github.com/t3dotgg/tstack
+cp -R tstack/skills/* ~/.claude/skills/   # Claude Code
+cp -R tstack/skills/* ~/.codex/skills/    # Codex
+```
+
+## Requirements
+
+- An authenticated [GitHub CLI](https://cli.github.com) (`gh`).
+- `python3` for `babysit-pr`'s `pr-wait` script.
+- `council` and `sol-loop` need subagents on other providers' models. T3 Code
+  does this with `delegate_task`. Otherwise you need a harness that can run
+  those models.
+
+## Make them yours
+
+These are starting points. Edit them. Put personal settings, like which models
+sit on your council, in your `CLAUDE.md` or `AGENTS.md`, so you can update the
+skills without losing them.
+
+## License
+
+[MIT](LICENSE)

package/tstack/skills/babysit-pr/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: babysit-pr
+description: Monitor a pull request through review and CI. Use when the user asks to monitor, watch, or babysit a PR.
+---
+
+# Babysit PR
+
+Many repos have AI review bots. They're helpful, even if they are not always
+right.
+
+## Waiting
+
+Never write your own watcher, polling loop, or `sleep` loop. Use one watcher
+per PR: `watch_pull_request` in T3 Code, `pr-wait` everywhere else. Never run
+both on the same PR. Every watcher on a GitHub account shares one rate limit.
+
+### In T3 Code: `watch_pull_request`
+
+Handle the existing checks and comments first. Then call
+`watch_pull_request` and end your turn. T3 Code wakes you with a message when
+a check fails, the required checks pass, someone comments or reviews, or the
+branch conflicts.
+
+- **Only the thread that owns the PR watches it.** If you are a delegated
+  child task (a reviewer, a Sol round, any `delegate_task` child), never call
+  `watch_pull_request`. The parent owns the PR. Do not watch PRs you are not
+  working on.
+- **A wake is news, not a merge decision.** Check the merge gate yourself.
+- **Unwatch when you hand off.** A watched thread stays in Working and out of
+  the user's inbox. When you stop (ready, blocked, or asking the user a question),
+  call `unwatch_pull_request` first. A merge or close ends the watch on its
+  own.
+- **"Stopped watching, could not read it"** usually means GitHub's rate limit
+  is used up. Run `gh api rate_limit --jq .resources.graphql` before you
+  watch again. If `remaining` is near 0, wait for `reset` with one background
+  command, then watch again. Never watch again in a tight loop.
+
+### Everywhere else: `pr-wait`
+
+Wait with `scripts/pr-wait` from this skill's directory (use its absolute
+path).
+
+```bash
+pr-wait <pr> [--repo owner/name] [--until ready|green|any-change]
+```
+
+It prints one line per real event. It exits 0 when the `--until` condition is
+met or the PR merges, 1 when it needs you (a required check failed, conflicts,
+unresolved threads, PR closed), and 2 on bad input.
+
+- `ready` (default): required checks green, Greptile or Macroscope reviewed the
+  head, and no unresolved threads. Use this to babysit.
+- `green`: required checks only. Use it when the repo has no Greptile or
+  Macroscope.
+- `any-change`: exit on the first event.
+
+In Claude Code, run it with the Monitor tool (`timeout_ms: 3600000`), so each
+line wakes you. Without a monitor, run it as one long command. It ends on its
+own.
+
+Start it again after you push, after you handle an exit 1, and after a resume.
+It remembers what it already reported, so nothing that arrived in between is
+lost. If it says another pid already watches the PR, do not start a second one.
+Kill the old one only if its events do not reach you.
+
+With either watcher: when an event needs no action, end your turn without a
+message. Never post or say "still waiting".
+
+## GitHub rate limits
+
+`gh pr create`, `gh pr view`, and `gh pr checks` use GraphQL. When GraphQL is
+used up, the REST limit is separate and usually still has room. Use
+`gh api repos/<owner>/<repo>/pulls/<n>` to read a PR, and
+`gh api repos/<owner>/<repo>/commits/<sha>/check-runs` for checks.
+
+## Reviews
+
+Only act on checks and comments newer than the latest push. Verify every bot
+finding against the source before changing code. Fix real findings and CI
+failures, distinguish repository failures from infrastructure flakes, and reply
+with a written reason when dismissing false positives.
+
+If the repo has `.macroscope/check-run-agents/*.md`, read those rules before you
+reply to a Macroscope finding. Its findings cite them.
+
+CodeRabbit is advisory. Treat its findings like any other finding, but never
+wait for it and never hold a merge for it.
+
+If a review bot leaves feedback you believe is not worth addressing, reply with
+a written reason and resolve the comment. Use the `leaving-pr-comments` skill
+for every comment posted on the user's behalf.
+
+Screenshots and videos help as well, when you have a way to upload them.
+
+Keep the PR at the size the user's goal needs. Review loops tend to grow a
+PR one cheap-looking fix at a time. Fix real bugs in the intended case.
+Decline the rest with a written reason, and list them as follow-ups:
+unneeded tests, guards for edge cases that do not matter, extra integration
+or compatibility, and small performance costs. Prefer the fix that deletes or
+narrows code.
+
+## Base branch and merging
+
+Keep an eye on changes to `main` and rebase when needed. `pr-wait` reports when
+new base commits touch this PR's files, and when the PR becomes BEHIND or DIRTY.
+`watch_pull_request` reports conflicts only, so check for BEHIND yourself
+before you call the PR ready.
+If an overlapping PR makes this one obsolete, stop monitoring, report it to the
+user, and ask before closing the PR unless closure was explicitly authorized.
+
+If nothing has changed, stay quiet rather than posting filler comments. Stop
+when `pr-wait` exits 0, or in T3 Code when the merge gate passes on the latest
+head. Merge only when the user explicitly requested it;
+otherwise report that the PR is ready. Right before a merge, run `git fetch` and
+check the PR again. Never merge when it is BEHIND or DIRTY, or when base commits
+that landed after the last green run touch this PR's files. Rebase, push, and
+wait for green again.