pi-harness-delegate 0.1.0

package/LICENSE

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

@@ -0,0 +1,179 @@
+# pi-harness-delegate
+
+Delegate work to **any harness** ([Claude Code](https://github.com/anthropics/claude-code), [Muse](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Amp](https://ampcode.com)) from the [pi coding agent](https://github.com/badlogic/pi-mono): code reviews, detailed plans, implementation, security audits, docs — or your own custom templates.
+
+Each harness runs headless in your repo with a normalized permission (`readonly` / `edit` / `danger`). Results stream back live, and token/cost usage feeds into pi's footer stats. Templates are portable — prompt bodies live in `templates/shared/`, harness-specific frontmatter selects the native permission.
+
+> Successor to `@yorch/pi-claude-delegate` (now a deprecated wrapper that re-exports the `claude` harness).
+
+## Install
+
+```bash
+pi install npm:pi-harness-delegate
+# or from git
+pi install git:github.com/yorch/pi-harness-delegate
+```
+
+Requires at least one harness binary on PATH (`claude --version`, `codex --version`, `opencode --version`, `amp --version`). Restart pi (or `/reload`) to activate.
+
+## Usage
+
+The pi agent uses the `delegate` tool automatically when you ask for e.g. *"review this diff"*, *"make a plan for …"*.
+
+Manual delegation:
+
+```bash
+/delegate review the new auth flow                      # default harness (claude)
+/delegate codex review the new auth flow                # harness as first word
+/delegate --harness=codex --mode=review --scope=diff … # explicit flags
+/codex review the new auth flow                         # alias → delegate --harness=codex
+/claude --mode=security-audit --scope=auth/ …          # alias → delegate --harness=claude
+/opencode plan the cache migration
+/amp implement the caching layer
+```
+
+Only the prompt is required. A **harness as first word** and/or **mode as next word** selects them; every `--flag` is optional (harness defaults to `delegate.defaultHarness`, mode to `delegate.defaultMode`, scope to whole repo).
+
+Some modes have **default tasks** when the prompt is omitted:
+`/delegate review` reviews the current git diff (`scope: diff`), `/delegate security-audit` audits the repo. Modes without a default (`plan`, `implement`, `docs`, `general`) print a hint asking for a prompt.
+
+The `delegate` tool takes: `harness`, `task`, `mode`, `scope` (`diff` = git diff, `pr` = PR diff, path list, or whole repo), `model`, `maxBudgetUsd`, `allowDangerous`, `sessionId`, `pr`.
+
+`claude_delegate` remains as a deprecated alias for `delegate{harness:claude}`.
+
+## Harnesses
+
+| Harness | Binary | Permission mapping | Notes |
+|---|---|---|---|
+| `claude` | `claude` | `readonly→plan`, `edit→acceptEdits`, `danger→bypassPermissions` | Full stream-json, cost + context% |
+| `codex` | `codex` | `readonly→read-only`, `edit→workspace-write`, `danger→danger-full-access` | `codex exec --json`, best-effort JSONL |
+| `opencode` | `opencode` | `readonly→read-only`, `edit→allow-edit`, `danger→danger` | `opencode run --format json` |
+| `amp` | `amp` (`omp` alias) | `readonly→read-only`, `edit→workspace`, `danger→danger` | `amp --output jsonl` |
+
+Detect availability: `delegate` checks `harness --version` at startup; missing harnesses hint install instructions.
+
+## Modes (templates)
+
+| Mode | Permission | Purpose |
+|---|---|---|
+| `review` | `readonly` | Code review, cites `file:line`, prioritized findings |
+| `plan` | `readonly` | Detailed implementation plan with steps + risks |
+| `implement` | `edit` | Implements a task, runs checks, reports changes |
+| `security-audit` | `readonly` | Injection, auth, secrets, deserialization, supply chain |
+| `docs` | `edit` | Generate/update docs matching repo style |
+| `general` | `edit` | Any task |
+
+Each mode is a markdown template with frontmatter:
+
+```yaml
+---
+name: review
+description: Code review of a scope. Read-only.
+permission: readonly      # normalized: readonly | edit | danger
+model: sonnet             # or gpt-5 for codex, etc. Aliases resolved via modelAliases
+defaultTask: Review the current git diff
+defaultScope: diff
+---
+You are a senior code reviewer delegated by the pi coding agent.
+...
+```
+
+**Native escape hatch:** if you need a harness-specific permission not covered by the normalized set, use the native key (`permissionMode: dontAsk`, `sandbox: ...`) — it overrides `permission` for that harness.
+
+**Template sources (later wins):**
+
+- `templates/shared/*.md` — portable prompt bodies
+- `templates/<harness>/*.md` — harness-specific frontmatter (built-ins)
+- `~/.pi/agent/delegate/templates/<harness>/<name>.md` (global)
+- `.pi/delegate/templates/<harness>/<name>.md` (project — when trusted)
+- Legacy `~/.pi/agent/claude-delegate/templates/` and `.pi/claude-delegate/templates/` still loaded for migration
+
+Custom templates are just files dropped in the above dirs — any registered name becomes a valid `mode`.
+
+## How the main session consumes the output
+
+- **Agent-driven (`delegate` tool)** — report is the tool result, flows into agent context.
+- **Manual (`/delegate` / aliases)** — report is injected as a custom message on next `before_agent_start`, participates in LLM context; full transcript also in file.
+
+## Inspecting what the harness is doing
+
+- **Live activity feed** — `▶ Bash: ... ✓/✗`, `💭 thinking…`, text tail. `/delegate` shows a framed progress window (spinner, `danger` banner for `danger` permission, `esc`×2 cancels, `m` minimizes, `watch` re-opens).
+- **Full transcript every run** — `~/.pi/agent/delegate/outputs/<harness>/<ts>-<mode>.md` (also legacy `claude-delegate/outputs/` for claude). Tool result ends with path.
+- **Resume:** every run records a session id.
+
+```bash
+/delegate --resume=<session-id> follow up on the review
+# or harness-specific alias:
+/codex --resume=<session-id> fix the nits
+```
+
+Reveal thinking live with `"inspectThinking": true` in config (off by default).
+
+## Config
+
+In `~/.pi/agent/settings.json`:
+
+```json
+{
+  "delegate": {
+    "defaultHarness": "claude",
+    "defaultMode": "general",
+    "model": "sonnet",
+    "timeoutMs": 600000,
+    "allowDangerous": false,
+    "inspectThinking": false,
+    "maxBudgetUsd": 3,
+    "autoDelegateHints": false,
+    "modelAliases": { "economy": "haiku", "balanced": "sonnet", "max": "opus" },
+    "maxConcurrent": 1,
+    "maxTranscripts": 100,
+    "harnesses": {
+      "claude": { "model": "sonnet" },
+      "codex": { "model": "gpt-5" },
+      "opencode": { "model": "opencode-default" }
+    }
+  }
+}
+```
+
+Legacy `claudeDelegate` is auto-migrated into `delegate.harnesses.claude` (deprecated).
+
+- `modelAliases` — templates may use `economy|balanced|max` or any alias; resolution: call → template → harness → global.
+- `maxConcurrent` — cap overlapping runs (default 1 global; may be `{global:1, perHarness:{claude:1}}`).
+- `maxTranscripts` — oldest transcripts pruned beyond this count per harness (`0` disables).
+
+`autoDelegateHints` is off by default — no system-prompt bias. When `true`, explicit markers (`@harness`, `with codex`, `delegate … to claude`) and imperative review/plan phrasing append a hint.
+
+## Metrics recorded
+
+Every run records in details + transcript: harness, mode, permission (normalized + native), cost, tokens (input/output/cache), context% (prompt ÷ window), model, turns, duration, TTFT, stop reason, session id. Token + cost feed pi's `Usage`.
+
+## Security model
+
+- `readonly` — no edits (e.g. Claude `plan`, Codex `read-only`).
+- `edit` — workspace writes auto-accepted (e.g. `acceptEdits`, `workspace-write`).
+- `danger` — unrestricted, **only via `allowDangerous:true` on the call** — never a default. Shows `⚠ danger` banner. `review`/`plan`/`security-audit` templates stay `readonly`.
+
+Review what the harness is asked to do before granting broad permissions.
+
+## Migration from pi-claude-delegate
+
+- `pi-claude-delegate` is now a deprecated wrapper. Install `pi-harness-delegate` instead.
+- `claude_delegate` tool → `delegate{harness:claude}` (alias still works).
+- `/claude` → `/delegate --harness=claude` (alias still works).
+- Config `claudeDelegate` → `delegate` (auto-migrated; move your settings).
+- Transcripts move from `~/.pi/agent/claude-delegate/outputs/` to `~/.pi/agent/delegate/outputs/<harness>/` (legacy dir still read).
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+See `AGENTS.md` for architecture. Release: bump `version` in `package.json`, `npm publish --access public`, `pi update --extensions`.
+
+## License
+
+MIT

package/extensions/activity.ts

@@ -0,0 +1,254 @@
+import { readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ActivityEvent } from './harnesses/types.ts';
+
+function truncate(s: string, max: number): string {
+	return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+
+/** Make a template/mode name safe for use in a filename. */
+export function safeSegmentName(name: string): string {
+	const safe = name.replace(/[^a-zA-Z0-9_-]+/g, '_').replace(/^_+|_+$/g, '');
+	return safe.length > 0 ? safe : 'delegate';
+}
+
+export interface MetricsInput {
+	numTurns: number;
+	totalCostUsd: number;
+	promptTokens: number;
+	contextPercent: number | null;
+	durationMs: number | null;
+}
+
+/** Compact run summary: `3 turn(s) · $0.54 · 62k tok · 6.2% ctx · 12s`. */
+export function formatMetrics(m: MetricsInput): string {
+	const parts: Array<string | null> = [
+		`${m.numTurns} turn(s)`,
+		`$${m.totalCostUsd.toFixed(3)}`,
+		m.promptTokens > 0 ? `${Math.round(m.promptTokens / 1000)}k tok` : null,
+		typeof m.contextPercent === 'number' ? `${m.contextPercent.toFixed(1)}% ctx` : null,
+		typeof m.durationMs === 'number' && m.durationMs !== null ? `${(m.durationMs / 1000).toFixed(0)}s` : null,
+	];
+	return parts.filter((p): p is string => Boolean(p)).join(' · ');
+}
+
+/** Parse the metadata header of a transcript file (without loading the whole body). */
+export function parseTranscriptMeta(head: string): {
+	mode: string;
+	cost: number;
+	sessionId: string | null;
+	harness: string | null;
+} {
+	let mode = 'delegate';
+	let cost = 0;
+	let sessionId: string | null = null;
+	let harness: string | null = null;
+	const mm = /^# Delegated (?:Claude|Harness) run — (.+)$/m.exec(head);
+	if (mm) mode = mm[1];
+	// Also match new header: # Delegated <harness> run — <mode>
+	const hm = /^# Delegated (\w+) run —/m.exec(head);
+	if (hm) harness = hm[1].toLowerCase();
+	const cm = /\bcost: \$([\d.]+)/.exec(head);
+	if (cm) cost = Number(cm[1]);
+	const sm = /\bsession: ([0-9a-f-]+)/.exec(head);
+	if (sm) sessionId = sm[1];
+	// harness explicit field
+	const hfm = /^-\s*harness:\s*(\w+)/m.exec(head);
+	if (hfm) harness = hfm[1];
+	return { mode, cost, sessionId, harness };
+}
+
+/** Build the markdown report content injected into the session on the next turn. */
+export function buildReportContent(opts: {
+	harness?: string;
+	mode: string;
+	metrics: string;
+	body: string;
+	file?: string;
+	sessionId?: string;
+}): string {
+	const harness = opts.harness ?? 'claude';
+	const header = `## ${harness} ${opts.mode} (${opts.metrics})`;
+	const foot: string[] = [];
+	if (opts.file) foot.push(`transcript: ${opts.file}`);
+	if (opts.sessionId) foot.push(`resume: \`/delegate --harness=${opts.harness} --resume=${opts.sessionId} <prompt>\` (or /${opts.harness} --resume=${opts.sessionId})`);
+	return [header, '', opts.body, foot.length > 0 ? `\n_${foot.join(' · ')}_` : ''].join('\n');
+}
+
+/** Legacy wrapper for compat */
+export function buildClaudeReportContent(opts: {
+	mode: string;
+	metrics: string;
+	body: string;
+	file?: string;
+	sessionId?: string;
+}): string {
+	return buildReportContent({ harness: 'claude', ...opts });
+}
+
+/** Delete oldest transcript files beyond `maxCount` (0 = keep everything). */
+export function pruneOutputs(dir: string, maxCount: number): void {
+	if (maxCount <= 0) return;
+	let files: string[];
+	try {
+		files = readdirSync(dir);
+	} catch {
+		return;
+	}
+	const byMtime = files
+		.filter((f) => f.endsWith('.md'))
+		.map((f) => ({ f, mtime: statSync(join(dir, f), { throwIfNoEntry: false })?.mtimeMs ?? 0 }))
+		.sort((a, b) => b.mtime - a.mtime);
+	for (const { f } of byMtime.slice(maxCount)) {
+		try {
+			rmSync(join(dir, f));
+		} catch {
+			// best-effort
+		}
+	}
+}
+
+/** Human-readable one-liner for a tool call (uses Claude's `description` when present). */
+export function formatToolUse(name: string, input: Record<string, unknown>): string {
+	if (typeof input.description === 'string' && input.description) {
+		return `${name}: ${truncate(input.description, 90)}`;
+	}
+	if (typeof input.command === 'string') return `${name}: ${truncate(input.command.split('\n')[0], 90)}`;
+	if (typeof input.file_path === 'string') return `${name}: ${input.file_path}`;
+	if (typeof input.pattern === 'string') return `${name}: ${input.pattern}`;
+	if (typeof input.url === 'string') return `${name}: ${input.url}`;
+	const first = Object.values(input).find((v): v is string => typeof v === 'string' && v.length > 0);
+	return first ? `${name}: ${truncate(first, 90)}` : name;
+}
+
+/** Compact per-line activity log for the transcript (tool_input + results only). */
+export function collectActivityLog(events: ActivityEvent[]): string[] {
+	const log: string[] = [];
+	for (const ev of events) {
+		if (ev.kind === 'tool_input') {
+			log.push(`▶ ${formatToolUse(ev.name, ev.input)}`);
+		} else if (ev.kind === 'tool_result') {
+			const last = log.length - 1;
+			if (last >= 0 && log[last].startsWith('▶')) {
+				log[last] += ev.isError ? '  ✗ error' : '  ✓';
+			}
+		}
+	}
+	return log;
+}
+
+/** Full transcript written to the outputs dir: metadata + activity + output. */
+export function buildTranscript(opts: {
+	harness?: string;
+	mode: string;
+	permission?: string;
+	permissionMode?: string;
+	nativePermission?: string;
+	model: string | null;
+	cwd: string;
+	sessionId: string | null;
+	resumed: boolean;
+	numTurns: number;
+	totalCostUsd: number;
+	isError: boolean;
+	stopReason: string | null;
+	durationMs: number | null;
+	usage: { inputTokens: number; outputTokens: number; cacheCreationInputTokens: number; cacheReadInputTokens: number } | null;
+	contextPercent: number | null;
+	contextWindow: number | null;
+	activityLog: string[];
+	output: string;
+} & Record<string, unknown>): string {
+	const harness = (opts.harness as string | undefined) ?? 'claude';
+	const permissionRaw = (opts.permission as string | undefined) ?? (opts.permissionMode as string | undefined) ?? 'edit';
+	let permission = permissionRaw;
+	let nativePermission = opts.nativePermission as string | undefined;
+	// map legacy permissionMode to normalized if needed
+	if ((opts as Record<string, unknown>).permissionMode && !opts.permission) {
+		const pm = (opts as Record<string, unknown>).permissionMode as string;
+		if (pm === 'plan') { permission = 'readonly'; nativePermission = pm; }
+		else if (pm === 'bypassPermissions') { permission = 'danger'; nativePermission = pm; }
+		else { permission = 'edit'; nativePermission = pm; }
+	}
+	const u = opts.usage;
+	const tokens = u
+		? [
+				`input ${u.inputTokens}`,
+				`output ${u.outputTokens}`,
+				`cache+${u.cacheCreationInputTokens}`,
+				`cache ${u.cacheReadInputTokens}`,
+			].join(' · ')
+		: null;
+	const context =
+		opts.contextPercent !== null && opts.contextWindow
+			? `${opts.contextPercent.toFixed(1)}% of ${opts.contextWindow.toLocaleString()} window`
+			: null;
+	const duration = opts.durationMs !== null ? `${(opts.durationMs / 1000).toFixed(1)}s` : null;
+	const permLine = nativePermission
+		? `- permission: ${permission} (${nativePermission})`
+		: `- permission: ${permission}`;
+
+	return [
+		`# Delegated ${harness.charAt(0).toUpperCase() + harness.slice(1)} run — ${opts.mode}`,
+		'',
+		`- harness: ${harness}`,
+		`- mode: ${opts.mode}`,
+		permLine,
+		`- model: ${opts.model ?? 'default'}`,
+		`- cwd: ${opts.cwd}`,
+		`- session: ${opts.sessionId ?? 'n/a'}${opts.resumed ? ' (resumed)' : ''}`,
+		`- turns: ${opts.numTurns} · cost: $${opts.totalCostUsd.toFixed(4)} · isError: ${opts.isError}`,
+		`- tokens: ${tokens ?? 'n/a'}`,
+		`- context: ${context ?? 'n/a'}`,
+		`- duration: ${duration ?? 'n/a'}`,
+		`- stop reason: ${opts.stopReason ?? 'n/a'}`,
+		'',
+		'## Activity',
+		opts.activityLog.length > 0 ? opts.activityLog.join('\n') : '(no tool activity)',
+		'',
+		'## Output',
+		opts.output || '(empty)',
+		'',
+	].join('\n');
+}
+
+/** Legacy wrapper */
+export function buildClaudeTranscript(opts: {
+	mode: string;
+	permissionMode: string;
+	model: string | null;
+	cwd: string;
+	sessionId: string | null;
+	resumed: boolean;
+	numTurns: number;
+	totalCostUsd: number;
+	isError: boolean;
+	stopReason: string | null;
+	durationMs: number | null;
+	usage: { inputTokens: number; outputTokens: number; cacheCreationInputTokens: number; cacheReadInputTokens: number } | null;
+	contextPercent: number | null;
+	contextWindow: number | null;
+	activityLog: string[];
+	output: string;
+}): string {
+	return buildTranscript({
+		harness: 'claude',
+		mode: opts.mode,
+		permission: opts.permissionMode === 'plan' ? 'readonly' : opts.permissionMode === 'bypassPermissions' ? 'danger' : 'edit',
+		nativePermission: opts.permissionMode,
+		model: opts.model,
+		cwd: opts.cwd,
+		sessionId: opts.sessionId,
+		resumed: opts.resumed,
+		numTurns: opts.numTurns,
+		totalCostUsd: opts.totalCostUsd,
+		isError: opts.isError,
+		stopReason: opts.stopReason,
+		durationMs: opts.durationMs,
+		usage: opts.usage,
+		contextPercent: opts.contextPercent,
+		contextWindow: opts.contextWindow,
+		activityLog: opts.activityLog,
+		output: opts.output,
+	});
+}

package/extensions/command.ts

@@ -0,0 +1,91 @@
+import type { DelegateTemplate } from './templates.ts';
+
+/**
+ * Pure parser for /delegate and alias commands: --key=value flags, with optional
+ * harness as first word and template name as next word.
+ */
+
+export interface DelegateCommandArgs {
+	task: string;
+	harness?: string;
+	mode?: string;
+	model?: string;
+	scope?: string;
+	budget?: number;
+	/** Resume an existing delegated session (--resume=<id>). */
+	sessionId?: string;
+	/** GitHub PR number/URL to review (--pr=). */
+	pr?: string;
+}
+
+export type ClaudeCommandArgs = DelegateCommandArgs;
+
+const KNOWN_HARNESSES = new Set(['claude', 'codex', 'opencode', 'amp', 'omp']);
+
+export function parseDelegateCommand(
+	raw: string,
+	knownModes: ReadonlySet<string>,
+	knownHarnesses: ReadonlySet<string> = KNOWN_HARNESSES,
+): DelegateCommandArgs {
+	const flags: Record<string, string> = {};
+	const rest = raw.replace(/--([a-zA-Z-]+)=(\S+)/g, (_m, k: string, v: string) => {
+		flags[k] = v;
+		return '';
+	});
+
+	let harness = flags.harness?.toLowerCase();
+	let mode = flags.mode;
+	let task = rest.trim();
+
+	// First word handling: harness, mode, or both
+	const words = task.split(/\s+/).filter(Boolean);
+	let idx = 0;
+	if (!harness && words[idx] && knownHarnesses.has(words[idx].toLowerCase())) {
+		harness = words[idx].toLowerCase();
+		if (harness === 'omp') harness = 'amp';
+		idx++;
+	}
+	if (!mode && words[idx] && knownModes.has(words[idx])) {
+		mode = words[idx];
+		idx++;
+	}
+	if (idx > 0) task = words.slice(idx).join(' ').trim();
+
+	const out: DelegateCommandArgs = { task };
+	if (harness) out.harness = harness;
+	if (mode) out.mode = mode;
+	if (flags.model) out.model = flags.model;
+	if (flags.scope) out.scope = flags.scope;
+	if (flags.budget !== undefined) {
+		const budget = Number(flags.budget);
+		if (Number.isFinite(budget) && budget > 0) out.budget = budget;
+	}
+	if (flags.resume) out.sessionId = flags.resume;
+	if (flags.pr) out.pr = flags.pr;
+	return out;
+}
+
+export function parseClaudeCommand(raw: string, knownModes: ReadonlySet<string>): ClaudeCommandArgs {
+	return parseDelegateCommand(raw, knownModes);
+}
+
+/**
+ * Apply template defaults when the prompt is empty.
+ */
+export function resolveDefaults(
+	args: DelegateCommandArgs,
+	templates: ReadonlyMap<string, DelegateTemplate>,
+): { task: string; scope?: string } | null {
+	if (args.task) {
+		return args.scope ? { task: args.task, scope: args.scope } : { task: args.task };
+	}
+	if (args.mode) {
+		const t = templates.get(args.mode);
+		if (t?.defaultTask) {
+			const scope = args.scope ?? t.defaultScope;
+			return scope ? { task: t.defaultTask, scope } : { task: t.defaultTask };
+		}
+		return null;
+	}
+	return null;
+}