@shanepadgett/tau-agent 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @shanepadgett/tau-agent
+
+Tau is a custom agentic harness built with Pi extensions: tools, commands, prompts, skills, and themes.
+
+## Install
+
+```bash
+pi install npm:@shanepadgett/tau-agent
+# or from git (monorepo root)
+pi install git:github.com/shanepadgett/tau-agent
+# local
+pi install ./path/to/tau-agent
+pi install ./path/to/tau-agent/packages/agent
+```
+
+## Development
+
+From the monorepo root:
+
+```bash
+npm install --ignore-scripts
+mise run check
+pi -e .
+```
+
+## Docs
+
+- [Extending Tau Agent](./docs/extending-tau-agent.md) — public events and integration
+- [Subagents](./docs/subagents.md) — custom agent definitions
+- [TUI](./docs/tui.md) — shared UI components

package/docs/extending-tau-agent.md

@@ -0,0 +1,119 @@
+# Extending Tau Agent
+
+Tau Agent is a Pi extension harness. External integration uses Pi's native `pi.events` bus.
+
+The caller and Tau Agent must be loaded in the same Pi runtime. External callers use string channel names and documented payloads. They do not import Tau Agent internals.
+
+Only events documented in this file are public. Extensions run trusted in-process; event emitters can ask Tau Agent to do work.
+
+Related:
+
+- [Custom subagents](./subagents.md)
+- [TUI components](./tui.md)
+
+## `tau:autoread.requested`
+
+Ask Tau Agent to read files and inject visible `tau.autoread` messages.
+
+```ts
+pi.events.emit("tau:autoread.requested", {
+  source: "my-extension",
+  title: "Skill context",
+  cwd: ctx.cwd,
+  batchId,
+  files: [{ path: "skills/foo/SKILL.md" }],
+});
+```
+
+Fields:
+
+- `source`: caller identifier shown in Tau metadata.
+- `title`: optional display/context label.
+- `cwd`: root used to resolve file paths.
+- `batchId`: groups visible autoread messages.
+- `files[].path`: file path relative to `cwd`.
+
+Behavior:
+
+- Tau reads each requested file.
+- Tau injects visible `tau.autoread` messages.
+- Missing or unreadable files produce visible failed autoread messages.
+- `pi.events.emit(...)` does not return file contents and should not be treated as completion or ack.
+
+## `tau:footer-item`
+
+Publish a bottom-right footer item in Tau's status footer.
+
+```ts
+pi.events.emit("tau:footer-item", {
+  id: "my-extension.status",
+  text: "syncing",
+  priority: 10,
+});
+```
+
+Fields:
+
+- `id`: stable item id. Re-emitting the same id replaces the previous item.
+- `text`: optional display text. Omit or clear to remove the item (implementation may treat empty/undefined as hide).
+- `priority`: optional sort priority (higher shows first when the footer ranks items).
+
+## `tau:agent.blocked`
+
+Notify that Tau is blocked waiting on the user (confirmations, custom UI, attention).
+
+```ts
+pi.events.emit("tau:agent.blocked", {
+  source: "my-extension",
+  title: "Needs input",
+  body: "Answer the open question to continue.",
+});
+```
+
+Fields:
+
+- `source`: optional caller id.
+- `title`: optional short title.
+- `body`: optional detail text.
+
+Tau's attention extension listens for this event. Other packages can listen too for custom notifications.
+
+## `tau:file-mutation.applied`
+
+Emitted after Tau's `patch` tool applies file changes.
+
+```ts
+pi.events.on("tau:file-mutation.applied", (data) => {
+  // data.source === "patch"
+  // data.status: "completed" | "partial" | "failed"
+  // data.changes: path, kind, line stats, optional move/snapshotRanges
+});
+```
+
+Fields:
+
+- `source`: currently `"patch"`.
+- `toolCallId`: tool call that produced the mutation.
+- `cwd`: working directory for the tool call.
+- `status`: overall result.
+- `changes[]`: per-file change summary (`path`, `kind`, optional `move`, `linesAdded`, `linesRemoved`, optional `snapshotRanges`).
+
+Use this to react after mutations (formatters, review hooks, status UI). Do not treat it as a request channel.
+
+## `tau:tool-row-state.set`
+
+Set visual state on a Tau tool row (for example pruned).
+
+```ts
+pi.events.emit("tau:tool-row-state.set", {
+  rowId: "some-row-id",
+  state: "pruned",
+});
+```
+
+Fields:
+
+- `rowId`: tool row id.
+- `state`: optional visual state. Omit to clear.
+
+Most extenders do not need this; it is for coordinating tool-row rendering with Tau's explore/patch/subagent tooling.

package/docs/subagents.md

@@ -0,0 +1,57 @@
+# Custom subagents
+
+Tau's `subagent` tool delegates one focused task to an isolated child Pi session. You can add your own agent definitions without writing TypeScript.
+
+## Where definitions live
+
+| Scope | Path | Use when |
+| --- | --- | --- |
+| **User (global)** | `~/.pi/agent/tau/agents/*.md` | You want the agent in every project |
+| **Project** | nearest trusted `.pi/tau/agents/*.md` | Repo-specific helpers |
+
+Precedence: **project overrides user**, which overrides Tau's built-ins (`scout`, `web-research`). Duplicate names in one scope are invalid.
+
+## Definition format
+
+Markdown with frontmatter:
+
+```markdown
+---
+name: api-reader
+description: Inspect API declarations and usage
+tools:
+  - read
+  - grep
+model: openai-codex/gpt-5.4-mini
+thinking: medium
+---
+
+Stay within the delegated task. Return exact paths and symbols.
+```
+
+Required:
+
+- `name`
+- `description`
+- `tools` (unique tool names; `subagent` cannot be delegated)
+
+Optional:
+
+- `model` as `provider/model`
+- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`
+
+Named tools and configured models must exist in the normally loaded child Pi environment (including tools from installed packages such as Tau).
+
+## Runtime rules
+
+- Children use the parent's cwd and inherit model/thinking unless the definition overrides them.
+- Children do not receive the parent conversation.
+- At most four children run at once; extra calls wait in order.
+- Returned text is capped (50 KB / 2,000 lines); full truncated output is saved to a private temp file.
+
+## Built-ins
+
+- `scout` — local exploration with `read`, `grep`, `find`, `ls`
+- `web-research` — `websearch`, `codesearch`, `webfetch`
+
+Ask Tau to delegate, or let it call `subagent` with an agent name and task.

package/docs/tui.md

@@ -0,0 +1,107 @@
+# TUI
+
+Build TUI that mirrors Pi aesthetics.
+
+## Reach order
+
+1. Use Pi native UI when it fits:
+   - `ctx.ui.select()`
+   - `ctx.ui.confirm()`
+   - `ctx.ui.input()`
+   - `ctx.ui.editor()`
+   - `SelectList`
+   - `SettingsList`
+   - `BorderedLoader`
+2. Use Tau shared TUI from `@shanepadgett/tau-tui` when a tool needs a custom component flow:
+   - `ToolPanel`
+   - `Tabs`
+   - `SelectableList`
+3. If shared TUI lacks the needed behavior, decide if the missing piece should become a new shared component in `@shanepadgett/tau-tui`.
+4. Build feature-local custom UI only when reuse is unlikely.
+5. Custom components still use Pi TUI primitives from `@earendil-works/pi-tui`.
+
+No one-off visual language. Make it look like Pi.
+
+## Shared components
+
+### `ToolPanel`
+
+Baseline shell for focused custom flows. Use when Pi built-ins do not fit and the user needs a bordered panel with title, header, body, footer key hints, or acknowledgement.
+
+For footer hints, child components expose hints, the parent combines the visible hints, and `ToolPanel` renders them.
+
+### `Tabs`
+
+Use inside a `ToolPanel` when one focused flow has multiple related views. Keeps tab switching out of feature code.
+
+### `SelectableList`
+
+Use inside a `ToolPanel` when the user needs cursor movement, single-select or multi-select behavior, optional inline filtering, and actions over current/selected/visible/older rows.
+
+Filtering is configured with `filter: { searchText }`. Filtered single-select lists focus the filter immediately, so plain typing goes into the filter and action keys must use modified keys like `ctrl+n` or non-printable keys like `delete`. Filtered multi-select lists keep list focus until `/` focuses the filter; `Enter` applies the filter focus, and `Escape` clears it.
+
+Shared components should stay generic. Feature behavior stays in the feature.
+
+## Composition shape
+
+Keep composition small:
+
+```ts
+import { SelectableList, Tabs, ToolPanel } from "@shanepadgett/tau-tui";
+
+const list = new SelectableList(theme, listConfig);
+const archiveList = new SelectableList(theme, archiveListConfig);
+
+const tabs = new Tabs(
+ theme,
+ [
+  { id: "active", label: "Sessions", count: activeCount, body: list, getKeyHints: () => list.getKeyHints() },
+  { id: "archive", label: "Archive", count: archiveCount, body: archiveList },
+ ],
+ "active",
+);
+
+const panel = new ToolPanel(theme, {
+ title: "Manage sessions",
+ secondary: "scope: current",
+ body: tabs,
+ footer: { kind: "hints", hints: tabs.getKeyHints() },
+});
+```
+
+## Key hints
+
+Use `ToolKeyHint` helpers. Use `bindingHint` for one configurable Pi keybinding and `bindingsHint` for grouped bindings like `tui.select.up` + `tui.select.down` rendering as one `move` hint. Use `rawHint` only for fixed local keys.
+
+Interactive shared components expose their own `getKeyHints()`. Composite components include visible child hints through explicit child providers such as `TabItem.getKeyHints`. Parents add only currently available domain/modal actions, then pass the final list to `ToolPanel`.
+
+Do not render disabled actions as key hints. Put non-action text in `secondary`, `header`, `body`, or an acknowledgement footer message.
+
+Do not hardcode key checks or rendered key labels for configurable actions. Keep key handling and key hints tied to the same binding.
+
+## Widgets
+
+Use `ctx.ui.setWidget(...)` for persistent, glanceable UI near the editor.
+
+Good fits:
+
+- persistent tool list
+- todo list
+- progress/status block that should not take focus
+
+Do not use a widget for a focused flow that needs input ownership. Use `ctx.ui.custom(...)` and a component.
+
+## Rules
+
+- Every `render(width)` line must fit `width`.
+- Use `truncateToWidth()` or `wrapTextWithAnsi()` for styled text.
+- Plain text renderers should use Pi `Text` with `new Text("", 0, 0)` so tool rows keep native spacing and wrapping.
+- Custom components must never return raw unbounded content. Split lines and run each line through `truncateToWidth()` or `wrapTextWithAnsi()` before returning it.
+- Truncating styled text can insert resets that break row backgrounds. Prefer wrapping for styled text unless the component owns the whole line background.
+- Custom components must implement `invalidate()`, even if it is a no-op.
+- Use `theme` from the TUI callback. Do not import theme globals.
+- Call `tui.requestRender()` after state changes.
+- Keep feature behavior outside shared components.
+- Keep storage and network outside TUI components.
+- Prefer one composed panel over one giant component.
+- If a helper has one caller and no useful name, inline it.

package/extensions/appshot/README.md

@@ -0,0 +1,11 @@
+# Appshot
+
+Appshot gives Tau direct discovery and capture of macOS application windows. Tau can list visible windows as compact TOON with their application identity, title, process ID, bounds, and stable window ID; capture an exact window as a PNG for visual inspection; and bring an application forward when needed. Captures preserve aspect ratio and fit within 1568×1568 pixels to keep image payloads bounded.
+
+The extension provides three tools:
+
+- `list_windows` discovers visible normal windows.
+- `screenshot_window` captures and inspects one listed window.
+- `activate_app` brings a listed application to the foreground when visual validation requires it.
+
+Appshot requires macOS 14 or newer. On first use, macOS asks for Screen & System Audio Recording access. If access is denied, open **System Settings → Privacy & Security → Screen & System Audio Recording** and grant access to the application running Tau, plus `tau-appshot` if macOS lists it separately.

package/extensions/appshot/capture.swift

@@ -0,0 +1,191 @@
+import AppKit
+import CoreGraphics
+import Darwin
+import Foundation
+import ImageIO
+import ScreenCaptureKit
+import UniformTypeIdentifiers
+
+enum AppshotError: LocalizedError {
+    case invalidArguments
+    case unsupportedOS
+    case processNotFound(pid_t)
+    case activationFailed(pid_t)
+    case permissionDenied
+    case windowNotFound(CGWindowID)
+    case imageDestination
+    case imageWrite
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidArguments:
+            return "Usage: tau-appshot <list|capture|activate> [arguments]"
+        case .unsupportedOS:
+            return "Appshot requires macOS 14 or newer"
+        case let .processNotFound(pid):
+            return "No running application found for PID \(pid)"
+        case let .activationFailed(pid):
+            return "Could not activate application PID \(pid)"
+        case .permissionDenied:
+            return "Screen recording permission is required. In System Settings > Privacy & Security > Screen & System Audio Recording, grant access to the application running Tau (and tau-appshot if listed), then try again"
+        case let .windowNotFound(windowID):
+            return "No visible normal window found for window ID \(windowID); call list_windows again"
+        case .imageDestination:
+            return "Could not create the PNG destination"
+        case .imageWrite:
+            return "Could not write the captured PNG"
+        }
+    }
+}
+
+@main
+struct TauAppshot {
+    static func main() async {
+        do {
+            guard #available(macOS 14.0, *) else {
+                throw AppshotError.unsupportedOS
+            }
+            let application = NSApplication.shared
+            application.setActivationPolicy(.prohibited)
+            application.finishLaunching()
+
+            guard CommandLine.arguments.count >= 2 else {
+                throw AppshotError.invalidArguments
+            }
+            switch CommandLine.arguments[1] {
+            case "list":
+                try await listWindows()
+            case "capture":
+                try await captureWindow()
+            case "activate":
+                try await activateApplication()
+            default:
+                throw AppshotError.invalidArguments
+            }
+        } catch {
+            let message = (error as? LocalizedError)?.errorDescription ?? error.localizedDescription
+            FileHandle.standardError.write(Data("\(message)\n".utf8))
+            exit(EXIT_FAILURE)
+        }
+    }
+
+    static func requireScreenCapturePermission() throws {
+        guard CGPreflightScreenCaptureAccess() || CGRequestScreenCaptureAccess() else {
+            throw AppshotError.permissionDenied
+        }
+    }
+
+    @available(macOS 14.0, *)
+    static func listWindows() async throws {
+        guard CommandLine.arguments.count == 2 else {
+            throw AppshotError.invalidArguments
+        }
+        try requireScreenCapturePermission()
+        let content = try await SCShareableContent.excludingDesktopWindows(true, onScreenWindowsOnly: true)
+        let windows: [[String: Any]] = content.windows
+            .filter({ window in
+                window.windowLayer == 0
+                    && window.frame.width > 0
+                    && window.frame.height > 0
+                    && window.owningApplication != nil
+            })
+            .sorted(by: { lhs, rhs in
+                let leftName = lhs.owningApplication?.applicationName ?? ""
+                let rightName = rhs.owningApplication?.applicationName ?? ""
+                if leftName != rightName {
+                    return leftName.localizedCaseInsensitiveCompare(rightName) == .orderedAscending
+                }
+                return lhs.windowID < rhs.windowID
+            })
+            .map({ window in
+                let owner = window.owningApplication
+                return [
+                    "window_id": Int(window.windowID),
+                    "title": window.title ?? "",
+                    "app_name": owner?.applicationName ?? "",
+                    "bundle_id": owner?.bundleIdentifier ?? "",
+                    "pid": Int(owner?.processID ?? 0),
+                    "bounds": [
+                        "x": window.frame.origin.x,
+                        "y": window.frame.origin.y,
+                        "width": window.frame.width,
+                        "height": window.frame.height,
+                    ],
+                ]
+            })
+        let data = try JSONSerialization.data(withJSONObject: windows, options: [.sortedKeys])
+        FileHandle.standardOutput.write(data)
+        FileHandle.standardOutput.write(Data("\n".utf8))
+    }
+
+    @available(macOS 14.0, *)
+    static func captureWindow() async throws {
+        guard CommandLine.arguments.count == 4,
+              let windowID = CGWindowID(CommandLine.arguments[2]),
+              windowID > 0
+        else {
+            throw AppshotError.invalidArguments
+        }
+        let outputPath = CommandLine.arguments[3]
+        try requireScreenCapturePermission()
+
+        let content = try await SCShareableContent.excludingDesktopWindows(true, onScreenWindowsOnly: true)
+        guard let window = content.windows.first(where: {
+            $0.windowID == windowID
+                && $0.windowLayer == 0
+                && $0.frame.width > 0
+                && $0.frame.height > 0
+        }) else {
+            throw AppshotError.windowNotFound(windowID)
+        }
+
+        let filter = SCContentFilter(desktopIndependentWindow: window)
+        let configuration = SCStreamConfiguration()
+        let pixelWidth = filter.contentRect.width * CGFloat(filter.pointPixelScale)
+        let pixelHeight = filter.contentRect.height * CGFloat(filter.pointPixelScale)
+        let scale = min(1, 1568 / max(pixelWidth, pixelHeight))
+        configuration.width = max(1, Int(floor(pixelWidth * scale)))
+        configuration.height = max(1, Int(floor(pixelHeight * scale)))
+        configuration.showsCursor = false
+        configuration.ignoreShadowsSingleWindow = true
+
+        let image = try await SCScreenshotManager.captureImage(
+            contentFilter: filter,
+            configuration: configuration
+        )
+        let outputURL = URL(fileURLWithPath: outputPath)
+        guard let destination = CGImageDestinationCreateWithURL(
+            outputURL as CFURL,
+            UTType.png.identifier as CFString,
+            1,
+            nil
+        ) else {
+            throw AppshotError.imageDestination
+        }
+        CGImageDestinationAddImage(destination, image, nil)
+        guard CGImageDestinationFinalize(destination) else {
+            throw AppshotError.imageWrite
+        }
+    }
+
+    static func activateApplication() async throws {
+        guard CommandLine.arguments.count == 3,
+              let pid = pid_t(CommandLine.arguments[2]),
+              pid > 0
+        else {
+            throw AppshotError.invalidArguments
+        }
+        guard let application = NSRunningApplication(processIdentifier: pid) else {
+            throw AppshotError.processNotFound(pid)
+        }
+        guard application.activate(options: [.activateAllWindows]) else {
+            throw AppshotError.activationFailed(pid)
+        }
+        for _ in 0..<20 where !application.isActive {
+            try await Task.sleep(for: .milliseconds(100))
+        }
+        guard application.isActive else {
+            throw AppshotError.activationFailed(pid)
+        }
+    }
+}