@oh-my-pi/pi-coding-agent 16.0.0 → 16.0.2

package/src/discovery/github.ts

@@ -5,11 +5,14 @@
  * Priority: 30 (shared standard provider)
  *
  * Sources:
- * - Project: .github/ (project-only, no user-level discovery)
+ * - Project: .github/ (repo-local Copilot config)
+ * - User: ~/.copilot/ (user-global Copilot CLI config; relocatable via COPILOT_HOME)
+ * - Extra: directories listed in COPILOT_CUSTOM_INSTRUCTIONS_DIRS
  *
  * Capabilities:
- * - context-files: copilot-instructions.md in .github/
- * - instructions: *.instructions.md in .github/instructions/ with applyTo frontmatter
+ * - context-files: copilot-instructions.md in .github/ and ~/.copilot/; AGENTS.md in each COPILOT_CUSTOM_INSTRUCTIONS_DIRS
+ * - rules: *.instructions.md under .github/instructions/ and <dir>/.github/instructions/ for each custom dir (applyTo frontmatter)
+ * - prompts: *.prompt.md in .github/prompts/ (VS Code Copilot prompt files)
  * - skills: <name>/SKILL.md in .github/skills/ (GitHub Agent Skills layout)
  */
 import * as path from "node:path";
@@ -18,10 +21,21 @@ import { registerProvider } from "../capability";
 import { type ContextFile, contextFileCapability } from "../capability/context-file";
 import { readFile } from "../capability/fs";
 import { type Instruction, instructionCapability } from "../capability/instruction";
+import { type Prompt, promptCapability } from "../capability/prompt";
+import { type Rule, ruleCapability } from "../capability/rule";
 import { type Skill, skillCapability } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 
-import { calculateDepth, createSourceMeta, getProjectPath, loadFilesFromDir, scanSkillsFromDir } from "./helpers";
+import {
+	buildRuleFromMarkdown,
+	calculateDepth,
+	createSourceMeta,
+	getProjectPath,
+	loadFilesFromDir,
+	parseCSV,
+	resolveCopilotHome,
+	scanSkillsFromDir,
+} from "./helpers";
 
 const PROVIDER_ID = "github";
 const DISPLAY_NAME = "GitHub Copilot";
@@ -52,6 +66,33 @@ async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFil
 		}
 	}
 
+	// User-global instructions (~/.copilot/copilot-instructions.md), applied across all repos.
+	const userInstructionsPath = path.join(resolveCopilotHome(ctx.home), "copilot-instructions.md");
+	const userContent = await readFile(userInstructionsPath);
+	if (userContent) {
+		items.push({
+			path: userInstructionsPath,
+			content: userContent,
+			level: "user",
+			_source: createSourceMeta(PROVIDER_ID, userInstructionsPath, "user"),
+		});
+	}
+
+	// Each COPILOT_CUSTOM_INSTRUCTIONS_DIRS entry contributes an AGENTS.md (Copilot CLI
+	// searches these dirs for AGENTS.md + .github/instructions/**; the latter is handled
+	// by loadInstructions). copilot-instructions.md is NOT part of the custom-dir spec.
+	for (const dir of copilotCustomInstructionDirs()) {
+		const agentsMdPath = path.join(dir, "AGENTS.md");
+		const agentsMdContent = await readFile(agentsMdPath);
+		if (agentsMdContent) {
+			items.push({
+				path: agentsMdPath,
+				content: agentsMdContent,
+				level: "user",
+				_source: createSourceMeta(PROVIDER_ID, agentsMdPath, "user"),
+			});
+		}
+	}
 	return { items, warnings };
 }
 
@@ -65,9 +106,23 @@ async function loadInstructions(ctx: LoadContext): Promise<LoadResult<Instructio
 
 	const instructionsDir = getProjectPath(ctx, "github", "instructions");
 	if (instructionsDir) {
+		// Path-specific instructions live "within or below" .github/instructions/ → recurse.
 		const result = await loadFilesFromDir<Instruction>(ctx, instructionsDir, PROVIDER_ID, "project", {
 			extensions: ["md"],
 			transform: transformInstruction,
+			recursive: true,
+		});
+		items.push(...result.items);
+		if (result.warnings) warnings.push(...result.warnings);
+	}
+
+	// Each COPILOT_CUSTOM_INSTRUCTIONS_DIRS entry contributes <dir>/.github/instructions/**/*.instructions.md.
+	for (const dir of copilotCustomInstructionDirs()) {
+		const customInstructionsDir = path.join(dir, ".github", "instructions");
+		const result = await loadFilesFromDir<Instruction>(ctx, customInstructionsDir, PROVIDER_ID, "user", {
+			extensions: ["md"],
+			transform: transformInstruction,
+			recursive: true,
 		});
 		items.push(...result.items);
 		if (result.warnings) warnings.push(...result.warnings);
@@ -99,6 +154,118 @@ function transformInstruction(name: string, content: string, filePath: string, s
 	};
 }
 
+// =============================================================================
+// Rules
+// =============================================================================
+
+async function loadRules(ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const items: Rule[] = [];
+	const warnings: string[] = [];
+
+	const load = async (dir: string, level: "user" | "project") => {
+		const applyToWarnings: string[] = [];
+		const result = await loadFilesFromDir<Rule>(ctx, dir, PROVIDER_ID, level, {
+			extensions: ["md"],
+			transform: (name, content, filePath, source) =>
+				transformInstructionRule(name, content, filePath, source, applyToWarnings),
+			recursive: true,
+		});
+		items.push(...result.items);
+		if (result.warnings) warnings.push(...result.warnings);
+		warnings.push(...applyToWarnings);
+	};
+
+	const instructionsDir = getProjectPath(ctx, "github", "instructions");
+	if (instructionsDir) {
+		await load(instructionsDir, "project");
+	}
+
+	for (const dir of copilotCustomInstructionDirs()) {
+		await load(path.join(dir, ".github", "instructions"), "user");
+	}
+
+	return { items, warnings };
+}
+
+function transformInstructionRule(
+	name: string,
+	content: string,
+	filePath: string,
+	source: SourceMeta,
+	warnings: string[],
+): Rule | null {
+	if (!name.endsWith(".instructions.md")) {
+		return null;
+	}
+
+	const { frontmatter } = parseFrontmatter(content, { source: filePath });
+	const applyToGlobs = normalizeApplyToGlobs(frontmatter.applyTo);
+	if (!applyToGlobs) {
+		warnings.push(`Missing applyTo in ${filePath}; loaded without GitHub glob scoping.`);
+	}
+
+	const rule = buildRuleFromMarkdown(name, content, filePath, source, {
+		stripNamePattern: /\.instructions\.md$/,
+	});
+	if (applyToGlobs?.some(isAlwaysApplyGlob)) {
+		return { ...rule, alwaysApply: true, globs: undefined };
+	}
+
+	const description = rule.description ?? describeInstructionRule(applyToGlobs);
+	return { ...rule, alwaysApply: false, globs: applyToGlobs, description };
+}
+
+function normalizeApplyToGlobs(value: unknown): string[] | undefined {
+	// GitHub documents applyTo as a single comma-separated string (e.g.
+	// "**/*.ts,**/*.tsx"); also tolerate a YAML array of such strings.
+	const raw = Array.isArray(value) ? value : [value];
+	const globs = raw.flatMap(item => (typeof item === "string" ? parseCSV(item) : []));
+	return globs.length > 0 ? globs : undefined;
+}
+
+function isAlwaysApplyGlob(glob: string): boolean {
+	// GitHub treats "*", "**", and "**/*" as matching every file.
+	return glob === "*" || glob === "**" || glob === "**/*";
+}
+
+function describeInstructionRule(globs: string[] | undefined): string {
+	if (!globs) return "GitHub Copilot instructions without applyTo metadata";
+	return `GitHub Copilot instructions for ${globs.join(", ")}`;
+}
+
+// =============================================================================
+// Prompts
+// =============================================================================
+
+async function loadPrompts(ctx: LoadContext): Promise<LoadResult<Prompt>> {
+	// `.github/prompts/*.prompt.md` is the VS Code Copilot prompt-file convention (the
+	// Copilot CLI has no prompt-file feature of its own); surface them as slash commands.
+	const promptsDir = getProjectPath(ctx, "github", "prompts");
+	if (!promptsDir) return { items: [], warnings: [] };
+
+	return loadFilesFromDir<Prompt>(ctx, promptsDir, PROVIDER_ID, "project", {
+		extensions: ["md"],
+		transform: transformPrompt,
+	});
+}
+
+function transformPrompt(name: string, content: string, filePath: string, source: SourceMeta): Prompt | null {
+	// Prompt files are `*.prompt.md`; ignore other markdown that may share the dir.
+	if (!name.endsWith(".prompt.md")) return null;
+
+	const { frontmatter, body } = parseFrontmatter(content, { source: filePath });
+	const promptName =
+		typeof frontmatter.name === "string" && frontmatter.name ? frontmatter.name : path.basename(name, ".prompt.md");
+
+	return { name: promptName, path: filePath, content: body, _source: source };
+}
+
+/** Directories listed in the COPILOT_CUSTOM_INSTRUCTIONS_DIRS env var (comma-separated). */
+function copilotCustomInstructionDirs(): string[] {
+	const raw = process.env.COPILOT_CUSTOM_INSTRUCTIONS_DIRS;
+	return raw ? parseCSV(raw) : [];
+}
+
 // =============================================================================
 // Skills
 // =============================================================================
@@ -132,7 +299,8 @@ async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
 registerProvider(contextFileCapability.id, {
 	id: PROVIDER_ID,
 	displayName: DISPLAY_NAME,
-	description: "Load copilot-instructions.md from .github/",
+	description:
+		"Load copilot-instructions.md from .github/ and ~/.copilot/; AGENTS.md from COPILOT_CUSTOM_INSTRUCTIONS_DIRS",
 	priority: PRIORITY,
 	load: loadContextFiles,
 });
@@ -140,11 +308,18 @@ registerProvider(contextFileCapability.id, {
 registerProvider(instructionCapability.id, {
 	id: PROVIDER_ID,
 	displayName: DISPLAY_NAME,
-	description: "Load *.instructions.md from .github/instructions/ with applyTo frontmatter",
+	description: "Load *.instructions.md from .github/instructions/ and COPILOT_CUSTOM_INSTRUCTIONS_DIRS",
 	priority: PRIORITY,
 	load: loadInstructions,
 });
 
+registerProvider<Rule>(ruleCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load *.instructions.md from .github/instructions/ as Copilot-scoped rules",
+	priority: PRIORITY,
+	load: loadRules,
+});
 registerProvider<Skill>(skillCapability.id, {
 	id: PROVIDER_ID,
 	displayName: DISPLAY_NAME,
@@ -152,3 +327,11 @@ registerProvider<Skill>(skillCapability.id, {
 	priority: PRIORITY,
 	load: loadSkills,
 });
+
+registerProvider<Prompt>(promptCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load *.prompt.md from .github/prompts/ (VS Code Copilot prompt files)",
+	priority: PRIORITY,
+	load: loadPrompts,
+});

package/src/discovery/helpers.ts

@@ -107,6 +107,17 @@ export function getProjectPath(ctx: LoadContext, source: SourceId, subpath: stri
 	return path.join(ctx.cwd, paths.projectDir, subpath);
 }
 
+/**
+ * Resolve GitHub Copilot CLI's user-global config root. Copilot stores per-user
+ * instructions/prompts/agents/MCP under `~/.copilot`, relocatable via the
+ * `COPILOT_HOME` env var (mirrors Copilot CLI's `--config-dir`). Falls back to
+ * `<home>/.copilot` when the override is unset.
+ */
+export function resolveCopilotHome(home: string): string {
+	const override = process.env.COPILOT_HOME?.trim();
+	return override ? override : path.join(home, ".copilot");
+}
+
 /**
  * Create source metadata for an item.
  */

package/src/eval/__tests__/prelude-agent.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "bun:test";
+import * as vm from "node:vm";
+import { JAVASCRIPT_PRELUDE_SOURCE } from "../js/shared/prelude";
+
+/**
+ * The eval `agent()` helper grows a `returnHandle` option that turns its bare
+ * text result into a DAG node dict carrying the spawned agent's recoverable
+ * `agent://<id>` handle, so a downstream `pipeline`/`parallel` stage can wire
+ * the transcript by reference instead of re-inlining it. These lock the node
+ * shape, backward compatibility of the default path, the schema interaction,
+ * and the no-`details` fallback (the helper must never throw).
+ *
+ * The prelude source is executed verbatim in a throwaway VM context with only
+ * the host bridge (`__omp_call_tool__`) stubbed — no worker, no kernel — so the
+ * test runs against the real shipped helper, not a re-implementation.
+ */
+function loadPrelude(callTool: (name: string, args: unknown) => Promise<unknown>): Record<string, unknown> {
+	const sandbox: Record<string, unknown> = { __omp_call_tool__: callTool };
+	vm.createContext(sandbox);
+	vm.runInContext(JAVASCRIPT_PRELUDE_SOURCE, sandbox);
+	return sandbox;
+}
+
+type AgentHelper = (prompt: string, opts?: Record<string, unknown>) => Promise<unknown>;
+
+describe("eval js agent() returnHandle", () => {
+	it("returns a DAG node carrying the agent:// handle when returnHandle is set", async () => {
+		let seenName: string | undefined;
+		const sandbox = loadPrelude(async name => {
+			seenName = name;
+			return { text: "hello world", details: { agent: "task", id: "abc123", model: "m", structured: false } };
+		});
+		const node = await (sandbox.agent as AgentHelper)("say hi", { returnHandle: true });
+		expect(seenName).toBe("__agent__");
+		expect(node).toEqual({
+			text: "hello world",
+			output: "hello world",
+			handle: "agent://abc123",
+			id: "abc123",
+			agent: "task",
+		});
+	});
+
+	it("returns bare text by default (backward compatible)", async () => {
+		const sandbox = loadPrelude(async () => ({
+			text: "hello world",
+			details: { agent: "task", id: "abc123", structured: false },
+		}));
+		const out = await (sandbox.agent as AgentHelper)("say hi");
+		expect(out).toBe("hello world");
+	});
+
+	it("carries the parsed object under data when schema and returnHandle combine", async () => {
+		const payload = JSON.stringify({ k: 1 });
+		const sandbox = loadPrelude(async () => ({
+			text: payload,
+			details: { agent: "task", id: "id-9", structured: true },
+		}));
+		const node = (await (sandbox.agent as AgentHelper)("emit", {
+			schema: { type: "object" },
+			returnHandle: true,
+		})) as Record<string, unknown>;
+		expect(node.handle).toBe("agent://id-9");
+		expect(node.data).toEqual({ k: 1 });
+		expect(node.text).toBe(payload);
+	});
+
+	it("falls back to a null handle without throwing when the bridge omits details", async () => {
+		const sandbox = loadPrelude(async () => ({ text: "lonely" }));
+		const node = await (sandbox.agent as AgentHelper)("x", { returnHandle: true });
+		expect(node).toEqual({ text: "lonely", output: "lonely", handle: null, id: null, agent: null });
+	});
+});

package/src/eval/js/shared/prelude.txt

@@ -117,10 +117,19 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	};
 
 	const agent = async (prompt, opts, ...rest) => {
-		const o = optionsArg("agent", opts, rest, ["agentType", "model", "label", "schema"], "{ agentType, model, label, schema }");
-		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...o });
+		const o = optionsArg("agent", opts, rest, ["agentType", "model", "label", "schema"], "{ agentType, model, label, schema, returnHandle }");
+		const { returnHandle, ...callArgs } = o;
+		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...callArgs });
 		const text = res && typeof res === "object" ? res.text : res;
-		return hasOwn(o, "schema") ? JSON.parse(text) : text;
+		const parsed = hasOwn(callArgs, "schema") ? JSON.parse(text) : text;
+		if (!returnHandle) return parsed;
+		const details = res && typeof res === "object" ? res.details : undefined;
+		if (!details || typeof details !== "object" || details.id == null) {
+			return { text, output: text, handle: null, id: null, agent: null };
+		}
+		const node = { text, output: text, handle: `agent://${details.id}`, id: details.id, agent: details.agent ?? null };
+		if (hasOwn(callArgs, "schema")) node.data = parsed;
+		return node;
 	};
 
 	// Pool ceiling mirrors the task tool's `task.maxConcurrency` setting so an

package/src/eval/py/prelude.py

@@ -519,7 +519,7 @@ if "__omp_prelude_loaded__" not in globals():
         text = res.get("text") if isinstance(res, dict) else res
         return json.loads(text) if schema is not None else text
 
-    def agent(prompt, *, agent_type="task", model=None, label=None, schema=None):
+    def agent(prompt, *, agent_type="task", model=None, label=None, schema=None, return_handle=False):
         """Run a subagent and return its final output.
 
         `agent_type` selects the subagent definition (default "task"). Pass
@@ -527,6 +527,15 @@ if "__omp_prelude_loaded__" not in globals():
         id, and `schema` to request structured JSON output; when `schema` is
         supplied the parsed object is returned. Share background by writing a
         local:// file and referencing it in the prompt.
+
+        Set `return_handle=True` to receive a DAG node dict instead of bare
+        text: ``{"text", "output", "handle", "id", "agent"}`` where ``handle``
+        is the spawned agent's recoverable ``agent://<id>`` URI. A downstream
+        ``pipeline``/``parallel`` stage embeds that ``handle`` (or ``output``)
+        in its prompt so a large transcript flows through the graph by
+        reference, never re-inlined. When ``schema`` is also set the parsed
+        object lands under ``"data"``. If the bridge returns no recoverable id
+        the node still resolves with ``handle=None`` — the helper never throws.
         """
         args = {"prompt": prompt}
         if agent_type is not None:
@@ -539,7 +548,22 @@ if "__omp_prelude_loaded__" not in globals():
             args["schema"] = schema
         res = _bridge_call("__agent__", args)
         text = res.get("text") if isinstance(res, dict) else res
-        return json.loads(text) if schema is not None else text
+        parsed = json.loads(text) if schema is not None else text
+        if not return_handle:
+            return parsed
+        details = res.get("details") if isinstance(res, dict) else None
+        if not isinstance(details, dict) or details.get("id") is None:
+            return {"text": text, "output": text, "handle": None, "id": None, "agent": None}
+        node = {
+            "text": text,
+            "output": text,
+            "handle": f"agent://{details['id']}",
+            "id": details["id"],
+            "agent": details.get("agent"),
+        }
+        if schema is not None:
+            node["data"] = parsed
+        return node
 
     def _concurrency_limit():
         """Worker-pool ceiling from the host ``task.maxConcurrency`` setting.

package/src/exec/bash-executor.ts

@@ -11,7 +11,7 @@ import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
-import { NON_INTERACTIVE_ENV } from "./non-interactive-env";
+import { buildNonInteractiveEnv } from "./non-interactive-env";
 
 export interface BashExecutorOptions {
 	cwd?: string;
@@ -184,7 +184,7 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	const minimizer = buildMinimizerOptions(settings.getGroup("shellMinimizer"));
 
 	const commandCwd = await resolveShellCwd(options?.cwd);
-	const commandEnv = options?.env ? { ...NON_INTERACTIVE_ENV, ...options.env } : NON_INTERACTIVE_ENV;
+	const commandEnv = buildNonInteractiveEnv(options?.env);
 
 	// Apply command prefix if configured
 	const prefixedCommand = prefix ? `${prefix} ${command}` : command;

package/src/exec/non-interactive-env.ts

@@ -46,3 +46,74 @@ export const NON_INTERACTIVE_ENV: Readonly<Record<string, string>> = {
 	COMPOSER_NO_INTERACTION: "1",
 	CLOUDSDK_CORE_DISABLE_PROMPTS: "1",
 };
+
+const WINDOWS_UTF8_ENV_DEFAULT_GROUPS: ReadonlyArray<ReadonlyArray<readonly [key: string, value: string]>> = [
+	[
+		["PYTHONIOENCODING", "utf-8"],
+		["PYTHONUTF8", "1"],
+	],
+	[
+		["LANG", "C.UTF-8"],
+		["LC_ALL", "C.UTF-8"],
+	],
+];
+
+function hasEnvValue(
+	env: Record<string, string | undefined> | undefined,
+	key: string,
+	platform: NodeJS.Platform,
+): boolean {
+	if (!env) return false;
+	if (platform !== "win32") return env[key] !== undefined;
+
+	for (const [existingKey, value] of Object.entries(env)) {
+		if (value !== undefined && existingKey.toLowerCase() === key.toLowerCase()) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function hasLocaleEnvValue(env: Record<string, string | undefined> | undefined, platform: NodeJS.Platform): boolean {
+	if (!env) return false;
+	for (const [key, value] of Object.entries(env)) {
+		if (value === undefined) continue;
+		const normalizedKey = platform === "win32" ? key.toUpperCase() : key;
+		if (normalizedKey === "LANG" || normalizedKey.startsWith("LC_")) return true;
+	}
+	return false;
+}
+
+function hasEnvGroupValue(
+	env: Record<string, string | undefined> | undefined,
+	group: ReadonlyArray<readonly [key: string, value: string]>,
+	platform: NodeJS.Platform,
+): boolean {
+	if (group.some(([key]) => key === "LC_ALL") && hasLocaleEnvValue(env, platform)) return true;
+	for (const [key] of group) {
+		if (hasEnvValue(env, key, platform)) return true;
+	}
+	return false;
+}
+
+/** Builds the per-command environment for non-interactive child processes. */
+export function buildNonInteractiveEnv(
+	overrides?: Record<string, string>,
+	baseEnv: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): Record<string, string> {
+	if (platform !== "win32") {
+		return overrides ? { ...NON_INTERACTIVE_ENV, ...overrides } : NON_INTERACTIVE_ENV;
+	}
+
+	const env: Record<string, string> = { ...NON_INTERACTIVE_ENV };
+	for (const group of WINDOWS_UTF8_ENV_DEFAULT_GROUPS) {
+		if (hasEnvGroupValue(baseEnv, group, platform) || hasEnvGroupValue(overrides, group, platform)) {
+			continue;
+		}
+		for (const [key, value] of group) {
+			env[key] = value;
+		}
+	}
+	return overrides ? { ...env, ...overrides } : env;
+}