pi-harness-delegate 0.1.0

package/extensions/harnesses/opencode.ts

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { Harness, BuildArgsOpts, NormalizedPermission, ParseOutcome, ParseState, StreamedResult } from './types.ts';
+
+const execFileAsync = promisify(execFile);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+const PERMISSION_MAP: Record<NormalizedPermission, string> = {
+	readonly: 'read-only',
+	edit: 'allow-edit',
+	danger: 'danger',
+};
+
+function extractOpencodeText(o: Record<string, unknown>): string | undefined {
+	if (typeof o.text === 'string') return o.text;
+	if (typeof o.output === 'string') return o.output;
+	if (typeof o.delta === 'string') return o.delta;
+	if (typeof o.content === 'string') return o.content;
+	if (isRecord(o.event) && typeof o.event.text === 'string') return o.event.text;
+	if (isRecord(o.message) && typeof o.message.text === 'string') return o.message.text;
+	return undefined;
+}
+
+export function parseOpencodeLine(line: string, state: ParseState): ParseOutcome {
+	let o: unknown;
+	try {
+		o = JSON.parse(line);
+	} catch {
+		if (line.trim().length > 0) return { streamedText: line + '\n', activities: [] };
+		return { activities: [] };
+	}
+	if (!isRecord(o)) return { activities: [] };
+	const activities: ParseOutcome['activities'] = [];
+	let streamedText: string | undefined;
+	const typeStr = typeof o.type === 'string' ? o.type : '';
+
+	if (typeStr.includes('tool') || o.type === 'tool_use' || o.type === 'tool_result') {
+		const name = typeof o.name === 'string' ? o.name : typeof (o as Record<string, unknown>).tool === 'string' ? (o as Record<string, unknown>).tool as string : 'tool';
+		if (typeStr.includes('start') || o.type === 'tool_use') {
+			activities.push({ kind: 'tool_start', name });
+			if (isRecord(o.input)) activities.push({ kind: 'tool_input', name, input: o.input as Record<string, unknown> });
+		} else if (typeStr.includes('result') || typeStr.includes('completed') || o.type === 'tool_result') {
+			activities.push({ kind: 'tool_result', isError: o.is_error === true || o.error === true });
+		}
+	}
+	if (typeStr.includes('thinking') || o.type === 'reasoning') {
+		activities.push({ kind: 'thinking', chars: 10 });
+	}
+
+	const text = extractOpencodeText(o);
+	if (text && !typeStr.includes('tool') && !typeStr.includes('thinking')) streamedText = text;
+
+	if (o.type === 'result' || o.type === 'completed' || o.type === 'done') {
+		const usage = isRecord(o.usage) ? o.usage : null;
+		const result: StreamedResult = {
+			result: typeof o.result === 'string' ? o.result : typeof o.output === 'string' ? o.output : state.streamedText + (streamedText ?? ''),
+			isError: o.is_error === true,
+			numTurns: typeof o.num_turns === 'number' ? o.num_turns : 0,
+			totalCostUsd: typeof o.total_cost_usd === 'number' ? o.total_cost_usd : 0,
+			sessionId: typeof o.session_id === 'string' ? o.session_id : typeof o.id === 'string' ? o.id : null,
+			stopReason: typeof o.stop_reason === 'string' ? o.stop_reason : null,
+			permissionDenials: [],
+			durationMs: typeof o.duration_ms === 'number' ? o.duration_ms : null,
+			durationApiMs: null,
+			ttftMs: null,
+			model: typeof o.model === 'string' ? o.model : null,
+			contextWindow: null,
+			maxOutputTokens: null,
+			usage: usage
+				? {
+						inputTokens: typeof usage.input_tokens === 'number' ? usage.input_tokens : 0,
+						outputTokens: typeof usage.output_tokens === 'number' ? usage.output_tokens : 0,
+						cacheCreationInputTokens: 0,
+						cacheReadInputTokens: 0,
+					}
+				: null,
+		};
+		return { activities, streamedText, result };
+	}
+	return { activities, streamedText };
+}
+
+export const opencodeHarness: Harness = {
+	name: 'opencode',
+	displayName: 'OpenCode',
+	binary: 'opencode',
+	async detect() {
+		try {
+			const { stdout } = await execFileAsync('opencode', ['--version'], { timeout: 5000 });
+			return { ok: true, version: stdout.trim() };
+		} catch {
+			return { ok: false, hint: 'Install OpenCode: https://opencode.ai' };
+		}
+	},
+	buildArgs(opts: BuildArgsOpts): string[] {
+		const args = ['run', '--format', 'json', opts.prompt];
+		// permission not fully standardized; pass as --permission if supported
+		const perm = opts.nativePermission ?? PERMISSION_MAP[opts.permission] ?? 'allow-edit';
+		args.push('--permission', perm);
+		if (opts.model) args.push('--model', opts.model);
+		if (opts.resumeSessionId) args.push('--session', opts.resumeSessionId);
+		for (const dir of opts.addDirs ?? []) args.push('--add-dir', dir);
+		return args;
+	},
+	parseLine(line: string, state: ParseState): ParseOutcome {
+		return parseOpencodeLine(line, state);
+	},
+	extractResult(state: ParseState): StreamedResult | null {
+		if (state.result) return state.result;
+		if (state.streamedText.trim().length > 0) {
+			return {
+				result: state.streamedText,
+				isError: false,
+				numTurns: 1,
+				totalCostUsd: 0,
+				sessionId: null,
+				stopReason: null,
+				permissionDenials: [],
+				durationMs: null,
+				durationApiMs: null,
+				ttftMs: null,
+				model: null,
+				contextWindow: null,
+				maxOutputTokens: null,
+				usage: null,
+			};
+		}
+		return null;
+	},
+	permissionMap: {
+		readonly: ['read-only'],
+		edit: ['allow-edit'],
+		danger: ['danger'],
+	},
+};

package/extensions/harnesses/registry.ts

@@ -0,0 +1,51 @@
+import { claudeHarness } from './claude.ts';
+import { codexHarness } from './codex.ts';
+import { opencodeHarness } from './opencode.ts';
+import { ampHarness } from './amp.ts';
+import type { Harness } from './types.ts';
+
+export const HARNESSES: Record<string, Harness> = {
+	claude: claudeHarness,
+	codex: codexHarness,
+	opencode: opencodeHarness,
+	amp: ampHarness,
+};
+
+export const ALIASES: Record<string, string> = {
+	omp: 'amp',
+};
+
+export const HARNESS_NAMES = Object.keys(HARNESSES);
+
+export function resolveHarnessName(name: string): string {
+	const lower = name.toLowerCase();
+	if (HARNESSES[lower]) return lower;
+	if (ALIASES[lower] && HARNESSES[ALIASES[lower]]) return ALIASES[lower];
+	return lower;
+}
+
+export function getHarness(name: string): Harness | undefined {
+	const resolved = resolveHarnessName(name);
+	return HARNESSES[resolved];
+}
+
+export function getAllHarnesses(): Harness[] {
+	return Object.values(HARNESSES);
+}
+
+export async function detectAll(): Promise<Record<string, { ok: boolean; version?: string; hint?: string }>> {
+	const out: Record<string, { ok: boolean; version?: string; hint?: string }> = {};
+	await Promise.all(
+		Object.entries(HARNESSES).map(async ([name, h]) => {
+			out[name] = await h.detect();
+		}),
+	);
+	return out;
+}
+
+export function isKnownHarness(name: string): boolean {
+	const r = resolveHarnessName(name);
+	return r in HARNESSES;
+}
+
+export const normalizeHarnessName = resolveHarnessName;

package/extensions/harnesses/types.ts

@@ -0,0 +1,93 @@
+/** Harness abstraction — normalized permission + generic runner contract. */
+
+export type NormalizedPermission = 'readonly' | 'edit' | 'danger';
+
+export interface StreamedUsage {
+	inputTokens: number;
+	outputTokens: number;
+	cacheCreationInputTokens: number;
+	cacheReadInputTokens: number;
+}
+
+export interface StreamedResult {
+	result: string;
+	isError: boolean;
+	numTurns: number;
+	totalCostUsd: number;
+	sessionId: string | null;
+	stopReason: string | null;
+	permissionDenials: unknown[];
+	usage: StreamedUsage | null;
+	durationMs: number | null;
+	durationApiMs: number | null;
+	ttftMs: number | null;
+	model: string | null;
+	contextWindow: number | null;
+	maxOutputTokens: number | null;
+}
+
+export type ActivityEvent =
+	| { kind: 'tool_start'; name: string }
+	| { kind: 'tool_input'; name: string; input: Record<string, unknown> }
+	| { kind: 'tool_result'; isError: boolean }
+	| { kind: 'thinking'; chars: number };
+
+export interface ParseState {
+	streamedText: string;
+	activities: ActivityEvent[];
+	result: StreamedResult | null;
+	/** Harness-internal scratch space. */
+	_harness?: Record<string, unknown>;
+}
+
+export interface ParseOutcome {
+	streamedText?: string;
+	activities?: ActivityEvent[];
+	result?: StreamedResult | null;
+}
+
+export interface StreamParseOutcome {
+	streamedText: string;
+	result: StreamedResult | null;
+	activities: ActivityEvent[];
+}
+
+export interface BuildArgsOpts {
+	prompt: string;
+	cwd: string;
+	permission: NormalizedPermission;
+	nativePermission?: string;
+	model?: string;
+	maxBudgetUsd?: number;
+	addDirs?: string[];
+	resumeSessionId?: string;
+	resumeId?: string;
+}
+
+export type HarnessBuildOpts = BuildArgsOpts;
+
+export interface DetectResult {
+	ok: boolean;
+	version?: string;
+	hint?: string;
+}
+
+export interface Harness {
+	name: string;
+	displayName: string;
+	binary: string;
+	aliases?: string[];
+	/** Check if binary is available. */
+	detect(): Promise<DetectResult>;
+	/** Build CLI args (excluding binary). */
+	buildArgs(opts: BuildArgsOpts): string[];
+	/** Parse a single stdout line. State is mutated by runner; return deltas. */
+	parseLine(line: string, state: ParseState): ParseOutcome;
+	/** Extract final result after process exit (state.result may already be set). */
+	extractResult(state: ParseState): StreamedResult | null;
+	/** Normalized -> native arg fragments. */
+	permissionMap?: Record<NormalizedPermission, string[]>;
+	permissionHint?: (permission: NormalizedPermission) => string[];
+}
+
+export const DEFAULT_TIMEOUT_MS = 600_000;

package/extensions/hint.ts

@@ -0,0 +1,57 @@
+/**
+ * Delegation-intent detection for user input.
+ *
+ * Gated entirely by `autoDelegateHints` — when off, user input is never
+ * touched and nothing nudges the agent toward this tool (the tool still
+ * exists in the available-tools list, so the agent may still choose it).
+ * When on:
+ *   - Explicit markers: `@claude`, `@codex`, "…with claude/codex …"
+ *     (marker stripped, hint appended)
+ *   - Keyword phrasing: imperative review/plan/audit/docs (hint appended)
+ *
+ * Never hints when the text already names the tool or the /delegate command.
+ */
+
+export interface HintConfig {
+	/** Master switch — false = no hinting at all. */
+	autoDelegateHints: boolean;
+}
+
+const EXPLICIT_MARKER_RE =
+	/(?:^|\s)@(?:claude|codex|opencode|amp)\b|(?:\b(with|via|using)\s+(?:claude|codex|opencode|amp|delegate)\b)|(?:\bdelegate\b[\s\S]*\b(?:claude|codex|opencode|amp|delegate)\b)/i;
+
+const KEYWORD_RE = /^\s*(review|plan|audit|security\s*audit|document|implement|write\s+tests?)\b/i;
+
+const HINT_TEXT =
+	'[delegate] The user wants this delegated to a harness. ' +
+	'Call the delegate tool with a fitting harness (claude, codex, opencode, amp) and mode (review, plan, security-audit, docs, implement, …) ' +
+	'rather than doing the work yourself. Only skip it if delegation is clearly inappropriate.';
+
+const LEGACY_HINT_TEXT =
+	'[claude-delegate] The user wants this delegated to Claude Code. ' +
+	'Call the claude_delegate tool with a fitting mode (review, plan, security-audit, docs, implement, …) ' +
+	'rather than doing the work yourself. Only skip it if delegation is clearly inappropriate.';
+
+export function delegationHint(text: string, cfg: HintConfig): string | null {
+	if (!cfg.autoDelegateHints) return null;
+
+	// already explicit about the tool or command — nothing to add
+	if (/\bclaude_delegate\b|\/(?:claude|delegate|codex|opencode|amp)\b/.test(text)) return null;
+
+	if (EXPLICIT_MARKER_RE.test(text)) return HINT_TEXT;
+
+	if (KEYWORD_RE.test(text)) return HINT_TEXT;
+
+	return null;
+}
+
+export function claudeDelegationHint(text: string, cfg: HintConfig): string | null {
+	const h = delegationHint(text, cfg);
+	if (h === HINT_TEXT) return LEGACY_HINT_TEXT;
+	return h;
+}
+
+/** Remove the @harness prefix marker from the text before sending. */
+export function stripMarker(text: string): string {
+	return text.replace(/(?:^|\s)@(?:claude|codex|opencode|amp|delegate)\b/g, ' ').replace(/\s{2,}/g, ' ').trim();
+}