@oh-my-pi/pi-coding-agent 15.13.3 → 16.0.1

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
+ * - instructions: *.instructions.md under .github/instructions/ (project) 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,19 @@ 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 Skill, skillCapability } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
 
-import { calculateDepth, createSourceMeta, getProjectPath, loadFilesFromDir, scanSkillsFromDir } from "./helpers";
+import {
+	calculateDepth,
+	createSourceMeta,
+	getProjectPath,
+	loadFilesFromDir,
+	parseCSV,
+	resolveCopilotHome,
+	scanSkillsFromDir,
+} from "./helpers";
 
 const PROVIDER_ID = "github";
 const DISPLAY_NAME = "GitHub Copilot";
@@ -52,6 +64,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 +104,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 +152,39 @@ function transformInstruction(name: string, content: string, filePath: string, s
 	};
 }
 
+// =============================================================================
+// 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 +218,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,7 +227,7 @@ 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,
 });
@@ -152,3 +239,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.