pi-dev-team 0.2.0

package/extensions/dev-team/lib/session-spend.ts

@@ -0,0 +1,123 @@
+/**
+ * What a session spent, one run at a time: the single walk over session entries that both the cost
+ * meter (metrics.ts) and the GitHub Copilot AI credits status line (ai-credits.ts) read, so the two
+ * classify entries the same way. Each reader chooses which threads it counts: the cost meter leaves
+ * out "overhead" runs (cache warming, compaction, branch summaries), the AI credits count them.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { creditedRuns, SUBAGENT_USAGE_ENTRY, type SubagentUsageEntry } from "./subagent-types.ts";
+
+/** The model of a run whose entry does not name one. */
+export const UNKNOWN_MODEL = "unknown";
+/** The provider of a model id that names none. */
+export const UNKNOWN_PROVIDER = "unknown";
+/** The agent of a subagent run whose entry does not name one as text. */
+export const UNKNOWN_AGENT = "unknown";
+
+/** Token usage as session entries carry it: pi's Usage (cost.total) or our UsageTotals (cost as a number). */
+export interface PiUsage {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: { total?: number } | number;
+}
+
+export interface SpendRun {
+	/**
+	 * "main": one of the session's own assistant turns. "subagent": a dispatched agent's own turns, or
+	 * an agent it dispatched itself. "overhead": spend pi records outside any turn, such as cache
+	 * warming, compaction and branch summaries.
+	 */
+	thread: "main" | "subagent" | "overhead";
+	/** "main", the dispatched agent's name, the usage entry's kind (e.g. "cache_warm"), "compaction" or "branch summary". */
+	agent: string;
+	/** "provider/model", or UNKNOWN_MODEL when the entry does not name one. */
+	model: string;
+	usage: PiUsage;
+	/** Model messages the run covers. */
+	messages: number;
+}
+
+/** The provider part of a "provider/model" id; UNKNOWN_PROVIDER when the id names none. */
+export function providerOf(model: string): string {
+	const slash = model.indexOf("/");
+	return slash > 0 ? model.slice(0, slash) : UNKNOWN_PROVIDER;
+}
+
+/** Session files are untyped JSON: a cost or count that is not a positive finite number counts as none. */
+export const positiveFiniteOrZero = (n: unknown): number => (typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0);
+
+export function costUsd(u: PiUsage): number {
+	return typeof u.cost === "number" ? u.cost : (u.cost?.total ?? 0);
+}
+
+/** The session's entries, every branch, as the plain records this module reads. */
+export function sessionEntries(ctx: ExtensionContext): readonly Record<string, unknown>[] {
+	return ctx.sessionManager.getEntries() as unknown as Record<string, unknown>[];
+}
+
+/** "provider/model", the bare model when no provider is named, UNKNOWN_MODEL when no model is (session files are untyped JSON, so a name that is not text counts as none). */
+const qualifiedModelId = (provider: unknown, model: unknown): string => {
+	if (typeof model !== "string" || !model) return UNKNOWN_MODEL;
+	return typeof provider === "string" && provider ? `${provider}/${model}` : model;
+};
+
+/** The overhead name of each entry type that records summary usage. */
+const SUMMARY_AGENT: ReadonlyMap<string, string> = new Map([
+	["compaction", "compaction"],
+	["branch_summary", "branch summary"],
+]);
+
+/** The model a compaction or branch summary is booked to: updated as the walk passes switches and turns. */
+interface ModelInEffect {
+	model: string;
+}
+
+/** The runs one entry records spend for, updating `effect` when the entry puts another model in effect. */
+function entryRuns(entry: Record<string, unknown>, effect: ModelInEffect): SpendRun[] {
+	const type = String(entry.type);
+	const summaryAgent = SUMMARY_AGENT.get(type);
+	if (type === "model_change") {
+		effect.model = qualifiedModelId(entry.provider, entry.modelId);
+	} else if (type === "message") {
+		const msg = entry.message as { role?: string; usage?: PiUsage; model?: string; provider?: string } | undefined;
+		if (msg?.role !== "assistant") return [];
+		const model = qualifiedModelId(msg.provider, msg.model);
+		if (msg.model) effect.model = model;
+		if (msg.usage) return [{ thread: "main", agent: "main", model, usage: msg.usage, messages: 1 }];
+	} else if (type === "custom" && entry.customType === SUBAGENT_USAGE_ENTRY) {
+		const usageEntry = entry.data as SubagentUsageEntry | undefined;
+		if (!usageEntry?.usage) return [];
+		// The child's own turns, then each agent it dispatched itself, credited to that agent and model.
+		// Session files are untyped JSON: a non-string name must not reach code that treats it as one.
+		return creditedRuns(usageEntry).map((run) => ({
+			thread: "subagent",
+			agent: typeof run.agent === "string" && run.agent ? run.agent : UNKNOWN_AGENT,
+			model: qualifiedModelId(undefined, run.model),
+			usage: run.usage,
+			messages: run.usage.turns ?? 0,
+		}));
+	} else if (type === "usage" && entry.usage) {
+		return [{ thread: "overhead", agent: String(entry.kind ?? "usage"), model: qualifiedModelId(entry.provider, entry.model), usage: entry.usage as PiUsage, messages: 0 }];
+	} else if (summaryAgent && entry.usage) {
+		return [{ thread: "overhead", agent: summaryAgent, model: effect.model, usage: entry.usage as PiUsage, messages: 0 }];
+	}
+	return [];
+}
+
+/**
+ * Every entry with the runs it records spend for (none for most entries), in one walk. Compaction and
+ * branch-summary entries carry usage but not the provider that served it; pi summarizes with the
+ * session's current model, so they are booked to the model in effect when they were written: the last
+ * model switch or assistant turn before them, UNKNOWN_MODEL when there is none.
+ */
+export function* sessionSpendByEntry<E extends Record<string, unknown>>(entries: Iterable<E>): Generator<{ entry: E; runs: SpendRun[] }> {
+	const effect: ModelInEffect = { model: UNKNOWN_MODEL };
+	for (const entry of entries) yield { entry, runs: entryRuns(entry, effect) };
+}
+
+/** Every run the entries record spend for: sessionSpendByEntry() without the entries. */
+export function* sessionSpend(entries: Iterable<Record<string, unknown>>): Generator<SpendRun> {
+	for (const { runs } of sessionSpendByEntry(entries)) yield* runs;
+}

package/extensions/dev-team/lib/shell-scan.ts

@@ -0,0 +1,205 @@
+/**
+ * Split bash text into simple commands (segments) of words, honoring quotes, escapes, `$(...)` and
+ * heredocs. Not a full shell parser: enough to find a command and its literal arguments, and to know
+ * when an argument is computed by the shell instead. Each character is visited a bounded number of
+ * times, so the scan is linear in the input; `$(` nesting deeper than MAX_SUBSTITUTION_DEPTH is not
+ * followed, so it cannot exhaust the stack.
+ */
+
+/**
+ * A shell word. `dynamic` means the shell computes part of it ($VAR, `cmd`, a substitution other than
+ * `$(cat <<'EOF' ...)`), so its text is not what the command receives. A `<<DELIM` heredoc or `<<<`
+ * here-string operator is a word of its own with `redirect` set; a heredoc carries its `heredocBody`.
+ */
+export interface ShellWord {
+	text: string;
+	dynamic: boolean;
+	redirect?: "heredoc" | "here-string";
+	heredocBody?: string;
+}
+export type ShellSegment = ShellWord[];
+
+export const MAX_SUBSTITUTION_DEPTH = 32;
+
+interface PendingHeredoc {
+	word: ShellWord;
+	delimiter: string;
+	stripTabs: boolean;
+	/** `<<'EOF'` or `<<"EOF"`: the body is literal. Unquoted, the shell expands $ and ` in it. */
+	quoted: boolean;
+}
+
+/** Index of `needle` at or after `from`, or the end of `source` when there is none. */
+function indexOrEnd(source: string, needle: string, from: number): number {
+	const index = source.indexOf(needle, from);
+	return index < 0 ? source.length : index;
+}
+
+/** A `$` or backtick that starts an expansion, so the word's final text is computed by the shell. */
+const SHELL_EXPANSION_START = /[A-Za-z_{0-9@*#?$!-]/;
+function startsExpansion(source: string, i: number): boolean {
+	return source[i] === "`" || (source[i] === "$" && SHELL_EXPANSION_START.test(source[i + 1] ?? ""));
+}
+
+/** Body lines up to the delimiter line for each pending heredoc, in order. Returns the index after them. */
+function readHeredocBodies(source: string, start: number, pending: PendingHeredoc[]): number {
+	let i = start;
+	for (const heredoc of pending) {
+		const lines: string[] = [];
+		while (i < source.length) {
+			const lineEnd = indexOrEnd(source, "\n", i);
+			const raw = source.slice(i, lineEnd);
+			i = lineEnd + 1;
+			const line = heredoc.stripTabs ? raw.replace(/^\t+/, "") : raw;
+			if (line === heredoc.delimiter) break;
+			lines.push(line);
+		}
+		const body = lines.join("\n");
+		heredoc.word.heredocBody = body;
+		if (!heredoc.quoted && /[$`]/.test(body)) heredoc.word.dynamic = true;
+	}
+	pending.length = 0;
+	return i;
+}
+
+/** `<<DELIM` / `<<-'DELIM'` at `start` (after the `<<`): registers the heredoc on a new word in `segment`. */
+function readHeredocOperator(source: string, start: number, segment: ShellSegment, pending: PendingHeredoc[]): number {
+	let i = start;
+	const stripTabs = source[i] === "-";
+	if (stripTabs) i++;
+	while (source[i] === " " || source[i] === "\t") i++;
+	// Any quoting in the delimiter word (<<'EOF', <<"EOF", <<\EOF, <<E"OF") makes the body literal.
+	let delimiter = "";
+	let quoted = false;
+	while (i < source.length && !/[\s;&|<>()]/.test(source[i])) {
+		const char = source[i];
+		if (char === "'" || char === '"') {
+			const end = indexOrEnd(source, char, i + 1);
+			delimiter += source.slice(i + 1, end);
+			quoted = true;
+			i = end + 1;
+		} else if (char === "\\") {
+			delimiter += source[i + 1] ?? "";
+			quoted = true;
+			i += 2;
+		} else {
+			delimiter += char;
+			i++;
+		}
+	}
+	const word: ShellWord = { text: "<<", dynamic: false, redirect: "heredoc", heredocBody: "" };
+	segment.push(word);
+	pending.push({ word, delimiter, stripTabs, quoted });
+	return i;
+}
+
+/** `"..."` from `start` (after the opening quote) into `word`. Returns the index after the closing quote. */
+function readDoubleQuoted(source: string, start: number, word: ShellWord, depth: number): number {
+	let i = start;
+	while (i < source.length) {
+		const char = source[i];
+		if (char === '"') return i + 1;
+		if (char === "\\" && i + 1 < source.length && '"\\$`\n'.includes(source[i + 1])) {
+			if (source[i + 1] !== "\n") word.text += source[i + 1];
+			i += 2;
+		} else if (char === "$" && source[i + 1] === "(") {
+			i = readSubstitution(source, i + 2, word, depth + 1);
+		} else {
+			if (startsExpansion(source, i)) word.dynamic = true;
+			word.text += char;
+			i++;
+		}
+	}
+	word.dynamic = true;
+	return i;
+}
+
+/** `$( ... )` from `start` (after `$(`). Only `$(cat <<'DELIM' ...)` with a literal body has known text. */
+function readSubstitution(source: string, start: number, word: ShellWord, depth: number): number {
+	if (depth > MAX_SUBSTITUTION_DEPTH) {
+		word.dynamic = true;
+		return source.length;
+	}
+	const inner = scanSegments(source, start, depth);
+	const [only] = inner.segments;
+	const catHeredoc = inner.segments.length === 1 && only.length === 2 && only[0].text === "cat" && !only[0].dynamic ? only[1] : undefined;
+	if (catHeredoc?.redirect === "heredoc" && !catHeredoc.dynamic) word.text += catHeredoc.heredocBody;
+	else word.dynamic = true;
+	return inner.end;
+}
+
+function scanSegments(source: string, start: number, depth: number): { segments: ShellSegment[]; end: number } {
+	const inSubstitution = depth > 0;
+	const segments: ShellSegment[] = [];
+	const pending: PendingHeredoc[] = [];
+	let segment: ShellSegment = [];
+	let word: ShellWord | undefined;
+	const wordInProgress = (): ShellWord => (word ??= { text: "", dynamic: false });
+	const endWord = () => {
+		if (word) segment.push(word);
+		word = undefined;
+	};
+	const endSegment = () => {
+		endWord();
+		if (segment.length) segments.push(segment);
+		segment = [];
+	};
+	let i = start;
+	while (i < source.length) {
+		const char = source[i];
+		if (char === "\n") {
+			endSegment();
+			i = readHeredocBodies(source, i + 1, pending);
+		} else if (char === " " || char === "\t") {
+			endWord();
+			i++;
+		} else if (char === ";" || char === "&" || char === "|" || char === "(") {
+			endSegment();
+			i++;
+		} else if (char === ")") {
+			endSegment();
+			if (inSubstitution) return { segments, end: i + 1 };
+			i++;
+		} else if (char === "#" && !word) {
+			i = indexOrEnd(source, "\n", i);
+		} else if (char === "\\") {
+			if (source[i + 1] !== "\n") wordInProgress().text += source[i + 1] ?? "";
+			i += 2;
+		} else if (char === "'") {
+			const end = indexOrEnd(source, "'", i + 1);
+			wordInProgress().text += source.slice(i + 1, end);
+			if (end === source.length) wordInProgress().dynamic = true;
+			i = end + 1;
+		} else if (char === "$" && source[i + 1] === "'") {
+			// ANSI-C quoting ($'a\nb'): the escapes are decoded by the shell, so the text is not taken literally.
+			let end = i + 2;
+			while (end < source.length && source[end] !== "'") end += source[end] === "\\" ? 2 : 1;
+			wordInProgress().text += source.slice(i, end + 1);
+			wordInProgress().dynamic = true;
+			i = end + 1;
+		} else if (char === '"') {
+			i = readDoubleQuoted(source, i + 1, wordInProgress(), depth);
+		} else if (char === "$" && source[i + 1] === "(") {
+			i = readSubstitution(source, i + 2, wordInProgress(), depth + 1);
+		} else if (source.startsWith("<<<", i)) {
+			// A here-string: the next word is stdin. Kept as an ordinary word, never a heredoc.
+			endWord();
+			segment.push({ text: "<<<", dynamic: false, redirect: "here-string" });
+			i += 3;
+		} else if (source.startsWith("<<", i)) {
+			endWord();
+			i = readHeredocOperator(source, i + 2, segment, pending);
+		} else {
+			if (startsExpansion(source, i)) wordInProgress().dynamic = true;
+			wordInProgress().text += char;
+			i++;
+		}
+	}
+	endSegment();
+	return { segments, end: i };
+}
+
+/** The simple commands of a bash command line, each as its words. */
+export function scanShell(source: string): ShellSegment[] {
+	return scanSegments(source, 0, 0).segments;
+}

package/extensions/dev-team/lib/skills.ts

@@ -0,0 +1,213 @@
+/**
+ * dev-team skills as pi slash commands and as the `skill` tool (Claude Code's Skill tool).
+ *
+ * Claude Code semantics reproduced here:
+ *   - `/name args` loads the skill body with `$ARGUMENTS`, `$ARGUMENTS[N]` and `$N` (0-based) substituted.
+ *     If the body has no placeholder, the arguments are appended as "ARGUMENTS: ...".
+ *   - Qualified names ("dev-team:plan") resolve to the bare skill.
+ *   - Project skills (.pi/skills, .claude/skills) override package skills with the same name
+ *     (e.g. the project-specific /pr that /setup generates).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseFrontmatter, stripFrontmatter } from "@earendil-works/pi-coding-agent";
+import { readSmallFile } from "./safe-read.ts";
+
+export interface SkillDef {
+	name: string;
+	description: string;
+	argumentHint?: string;
+	userInvocable: boolean;
+	filePath: string;
+	baseDir: string;
+	source: "project" | "package";
+}
+
+type SkillFrontmatter = {
+	name?: unknown;
+	description?: unknown;
+	"argument-hint"?: unknown;
+	"user-invocable"?: unknown;
+};
+
+function loadSkill(filePath: string, source: SkillDef["source"]): SkillDef | undefined {
+	const content = readSmallFile(filePath);
+	if (content === undefined) return undefined;
+	let fm: SkillFrontmatter;
+	try {
+		fm = parseFrontmatter<SkillFrontmatter>(content).frontmatter;
+	} catch {
+		return undefined;
+	}
+	const dirName = path.basename(path.dirname(filePath));
+	const name = typeof fm.name === "string" && fm.name.trim() ? fm.name.trim() : dirName;
+	const description = typeof fm.description === "string" ? fm.description.replace(/\s+/g, " ").trim() : "";
+	return {
+		name,
+		description,
+		argumentHint: typeof fm["argument-hint"] === "string" ? fm["argument-hint"] : undefined,
+		userInvocable: fm["user-invocable"] !== false,
+		filePath,
+		baseDir: path.dirname(filePath),
+		source,
+	};
+}
+
+function loadDir(dir: string, source: SkillDef["source"]): SkillDef[] {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const out: SkillDef[] = [];
+	for (const e of entries) {
+		if (!e.isDirectory() && !e.isSymbolicLink()) continue;
+		const file = path.join(dir, e.name, "SKILL.md");
+		if (!fs.existsSync(file)) continue;
+		const def = loadSkill(file, source);
+		if (def) out.push(def);
+	}
+	return out;
+}
+
+/**
+ * Project skills (.pi/skills, .claude/skills) first, then the package's. Project skills are
+ * repo-supplied instructions, so pass `includeProject: ctx.isProjectTrusted()` as pi does for its own.
+ */
+export function discoverSkills(cwd: string, packageRoot: string, opts: { includeProject: boolean }): Map<string, SkillDef> {
+	const map = new Map<string, SkillDef>();
+	const add = (defs: SkillDef[]) => {
+		for (const d of defs) if (!map.has(d.name)) map.set(d.name, d);
+	};
+	if (opts.includeProject) add(loadProjectSkills(cwd));
+	add(loadDir(path.join(packageRoot, "skills"), "package"));
+	return map;
+}
+
+function loadProjectSkills(cwd: string): SkillDef[] {
+	return [...loadDir(path.join(cwd, ".pi", "skills"), "project"), ...loadDir(path.join(cwd, ".claude", "skills"), "project")];
+}
+
+/** First definition of each name wins. */
+function byName(defs: SkillDef[]): Map<string, SkillDef> {
+	const map = new Map<string, SkillDef>();
+	for (const d of defs) if (!map.has(d.name)) map.set(d.name, d);
+	return map;
+}
+
+/**
+ * Skills a call may use. When pi reports the project untrusted, project skills are left out and
+ * `skippedProjectSkills` names the requested ones that therefore cannot run. Unlike
+ * skippedProjectAgents, a project skill that shadows a package skill is not listed: the package
+ * skill runs instead, as pi does when it skips its own project skills.
+ */
+export function discoverInvocableSkills(
+	cwd: string,
+	packageRoot: string,
+	projectTrusted: boolean,
+	requested: string[],
+): { skills: Map<string, SkillDef>; skippedProjectSkills: string[] } {
+	const skills = discoverSkills(cwd, packageRoot, { includeProject: projectTrusted });
+	if (projectTrusted) return { skills, skippedProjectSkills: [] };
+	// Only the project directories are read again, to name what was left out.
+	const projectOnly = byName(loadProjectSkills(cwd));
+	const skippedProjectSkills = requested.filter((name) => !resolveSkillName(skills, name) && resolveSkillName(projectOnly, name));
+	return { skills, skippedProjectSkills };
+}
+
+/** Why a skill cannot run now: the one wording for the skill tool and /commands. */
+export function unavailableSkillReason(skippedForTrust: boolean): string {
+	return skippedForTrust ? "is a project skill, and this project is not trusted in pi" : "can no longer be found (its SKILL.md is missing or unreadable)";
+}
+
+export function resolveSkillName(skills: Map<string, SkillDef>, requested: string): SkillDef | undefined {
+	const bare = requested.trim().replace(/^\//, "").replace(/^[\w-]+:/, "");
+	return skills.get(bare) ?? skills.get(bare.toLowerCase());
+}
+
+/** Shell-like split honoring single and double quotes. */
+export function splitArgs(args: string): string[] {
+	const out: string[] = [];
+	let cur = "";
+	let quote: string | null = null;
+	let has = false;
+	for (let i = 0; i < args.length; i++) {
+		const ch = args[i];
+		if (quote) {
+			if (ch === quote) quote = null;
+			else cur += ch;
+			continue;
+		}
+		if (ch === '"' || ch === "'") {
+			quote = ch;
+			has = true;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			if (has || cur) out.push(cur);
+			cur = "";
+			has = false;
+			continue;
+		}
+		cur += ch;
+		has = true;
+	}
+	if (has || cur) out.push(cur);
+	return out;
+}
+
+/** Claude Code argument substitution. */
+export function substituteArguments(body: string, args: string): string {
+	const positional = splitArgs(args);
+	let used = false;
+	let out = body.replace(/\$ARGUMENTS\[(\d+)\]/g, (_m, n: string) => {
+		used = true;
+		return positional[Number(n)] ?? "";
+	});
+	out = out.replace(/\$ARGUMENTS\b/g, () => {
+		used = true;
+		return args;
+	});
+	out = out.replace(/\$(\d)(?![\d\w])/g, (_m, n: string) => {
+		used = true;
+		return positional[Number(n)] ?? "";
+	});
+	if (!used && args.trim()) out = `${out.trimEnd()}\n\nARGUMENTS: ${args}`;
+	return out;
+}
+
+/** The text a model sees when a skill is invoked (same wrapper pi uses for /skill:name). */
+export function expandSkill(skill: SkillDef, args: string): string {
+	// Read again with the same guard: the file may have changed since discovery.
+	const raw = readSmallFile(skill.filePath);
+	if (raw === undefined) throw new Error(`Skill "${skill.name}" can no longer be read: ${skill.filePath}`);
+	const body = stripFrontmatter(raw).trim();
+	const substituted = substituteArguments(body, args);
+	const header = `References are relative to ${skill.baseDir}. \${CLAUDE_PLUGIN_ROOT} is set in the shell environment.`;
+	return `<skill name="${skill.name}" location="${skill.filePath}">\n${header}\n\n${substituted}\n</skill>`;
+}
+
+export function commandText(skill: SkillDef, args: string): string {
+	const invocation = `/${skill.name}${args.trim() ? ` ${args.trim()}` : ""}`;
+	return `${expandSkill(skill, args)}\n\nThe user invoked \`${invocation}\`. Follow the skill above.`;
+}
+
+function truncate(text: string, max: number): string {
+	if (text.length <= max) return text;
+	const cut = text.slice(0, max);
+	const dot = cut.lastIndexOf(". ");
+	return (dot > max * 0.5 ? cut.slice(0, dot + 1) : `${cut.trimEnd()}…`).trim();
+}
+
+/** Skill index for the system prompt (Claude Code lists skills for its Skill tool the same way, budgeted). */
+export function skillIndex(skills: Map<string, SkillDef>, mode: "compact" | "full", maxChars: number): string {
+	const lines = [...skills.values()]
+		.sort((a, b) => a.name.localeCompare(b.name))
+		.map((s) => {
+			const desc = mode === "full" ? s.description : truncate(s.description, maxChars);
+			const cmd = s.userInvocable ? ` (/${s.name})` : "";
+			return `- ${s.name}${cmd}: ${desc}`;
+		});
+	return lines.join("\n");
+}