pi-soly 0.3.0 → 0.4.0

package/ask/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": [
+      "esnext"
+    ],
+    "types": [
+      "node"
+    ],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "allowImportingTsExtensions": true
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/index.ts

@@ -62,6 +62,10 @@ import { detectEnv, buildEnvSection, type EnvSummary } from "./env.ts";
 import { buildCodeMap, buildCodeMapSection, type CodeMap } from "./codemap.ts";
 import { loadIntentDocs, buildIntentSection, loadInlineIntentBodies, type IntentDoc } from "./intent.ts";
 
+// Built-in sub-features (merged from former pi-asked, pi-agented packages):
+import piAskExtension from "./ask/index.ts";
+import piSwitchExtension from "./switch/index.ts";
+
 export default function solyExtension(pi: ExtensionAPI) {
 	// ============================================================================
 	// State (module-local, lives for the duration of one extension instance)
@@ -715,4 +719,8 @@ export default function solyExtension(pi: ExtensionAPI) {
 			updateStatus(ctx);
 		}
 	});
+
+	// Mount built-in sub-features
+	piAskExtension(pi);
+	piSwitchExtension(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Project management for pi — plans, state, subagent-driven execution. Inspired by GSD.",
   "type": "module",
   "main": "index.ts",
@@ -38,6 +38,8 @@
     "tools.ts",
     "agents-install.ts",
     "agents",
+    "ask",
+    "switch",
     "workflows",
     "workflows-data"
   ],
@@ -47,7 +49,9 @@
     "pi-package",
     "project-management",
     "planning",
-    "subagents"
+    "subagents",
+    "multi-question",
+    "agent-switcher"
   ],
   "license": "MIT",
   "pi": {

package/switch/README.md

@@ -0,0 +1,107 @@
+# pi-switch — generic subagent switcher for pi
+
+A tiny pi extension that gives you a **persistent indicator of the current subagent** (header bar above chat) and lets you **cycle / set / create** agents. Generic — works with any agent in `~/.pi/agent/agents/`.
+
+## Features
+
+- **Header bar above chat** — shows current agent with emoji + description
+- **Ctrl+Shift+S** to cycle to next agent (Shift+Tab is taken by pi's thinking-level cycler)
+- **`/agent`** slash command to show current + available
+- **`/agent <name>`** to set explicitly
+- **`/agent create <name>`** to scaffold a new user agent
+- **`/agent doctor`** to diagnose
+- **`/agent recommend <task>`** to suggest the right agent for a task
+- **Task → agent heuristics** baked into the system prompt so the LLM picks the right agent for the task
+- Persists to `.soly/agent` (if soly project) or `~/.pi-switch/agent` (standalone)
+- Reads user agents from `~/.pi/agent/agents/*.md` on every cycle — drop a file and Ctrl+Shift+S to see it
+
+## How agents work
+
+Agents are markdown files with YAML frontmatter. pi-subagents (and pi-switch) discover them from these locations:
+
+| Path | Type | Editable |
+|---|---|---|
+| `~/.pi/agent/npm/node_modules/pi-subagents/agents/*.md` | built-in (worker, oracle, scout, ...) | ❌ |
+| `~/.pi/agent/agents/*.md` | user-defined | ✅ |
+| `~/.pi/agent/extensions/soly/agents/*.md` (auto-installed if `useSolyWorkerSubagents: true` in `.soly/config.json`) | soly-augmented (soly-worker, soly-debugger, ...) | ✅ source |
+
+### Frontmatter schema
+
+```markdown
+---
+name: my-reviewer              # required, unique, [a-zA-Z0-9_-]{1,64}
+description: One-liner shown in picker
+thinking: medium               # off | minimal | low | medium | high | xhigh
+systemPromptMode: replace      # replace | append
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+defaultContext: fork           # fresh | fork
+---
+
+You are `my-reviewer`. The system prompt goes here.
+```
+
+## Create a new agent
+
+### Option A: manually
+Drop a markdown file in `~/.pi/agent/agents/<name>.md` (see schema above). Press `Ctrl+Shift+S` in pi — it joins the cycle.
+
+### Option B: via slash command
+```
+/agent create my-debugger
+```
+You'll be prompted for a one-liner description. Then edit the file to specialize the system prompt.
+
+## Test agents
+
+| Action | How |
+|---|---|
+| See current + available | `/agent` |
+| Cycle | `Ctrl+Shift+S` |
+| Set explicitly | `/agent soly-debugger` |
+| Diagnose | `/agent doctor` |
+| Recommend for a task | `/agent recommend investigate React Server Components` |
+
+The LLM can also auto-pick — see "Task → agent" below.
+
+## Task → agent heuristics
+
+The LLM's system prompt includes a table mapping task keywords to agents. When the user request matches, the LLM should call `/agent <name>` first, then `subagent({ agent: <name>, ... })`.
+
+| Keywords | Agent | Why |
+|---|---|---|
+| research, investigate, look up, find out, explore, compare libraries | 📚 researcher | external docs, ecosystem behavior |
+| scout, scan, map, where is, locate, skim | 🔍 scout | codebase recon |
+| plan, design, architect, outline, structure | 📋 planner | decompose into steps |
+| review, audit, check, adversarial, critique, qa | 👀 reviewer | adversarial review |
+| oracle, decision, tradeoff, which approach, drift | 🔮 oracle | decision consistency |
+| debug, bug, fix, crash, error, repro | 🐞 soly-debugger | bug investigation |
+| test, tests, coverage, spec, assert | 🧪 soly-tester | test-only work |
+| refactor, clean up, simplify, extract, rename | 🔄 soly-refactor | pure refactoring |
+| document, docs, readme, jsdoc | 📝 soly-documenter | doc updates |
+| implement, build, write code, add feature | ⚡ worker | implementation |
+| orchestrate, coordinate, dispatch, chain | 🤝 delegate | multi-agent |
+
+Same keywords in Russian work (изучи, баг, тест, etc.).
+
+## Integration with other extensions
+
+- **soly** reads `globalThis.__PI_SWITCH_AGENT__` to know which subagent to launch for `soly execute`. Falls back to `"worker"` if pi-switch isn't loaded.
+- **Soly** also auto-installs soly-augmented agents (soly-worker, soly-debugger, etc.) to `~/.pi/agent/agents/` when `useSolyWorkerSubagents: true` in `.soly/config.json`.
+
+## Files
+
+- `core.ts` — agent metadata, discovery, cycling, persistence
+- `prompt.ts` — system-prompt section + task→agent heuristics + `recommendAgent`
+- `index.ts` — header bar, Ctrl+Shift+S, `/agent` slash command, `/agent create`/`/agent doctor`/`/agent recommend`
+- `tests/core.test.ts` — 21 tests for core logic
+- `tests/prompt.test.ts` — 20 tests for prompt + recommendAgent
+
+## Development
+
+```bash
+cd ~/.pi/agent/extensions/pi-switch
+bun test          # 41 tests
+bun run typecheck # tsc --noEmit
+```

package/switch/core.ts

@@ -0,0 +1,202 @@
+// =============================================================================
+// core.ts — Generic subagent switcher for pi
+// =============================================================================
+//
+// Lets the user pick which subagent the LLM uses (for `subagent(...)` calls
+// in the pi-subagents system, and for any extension that reads the current
+// agent). Generic — works with pi-subagents' built-ins (worker, oracle,
+// scout, ...) AND any user-defined agent in `~/.pi/agent/agents/`.
+//
+// Cycle order (Shift+Tab in pi is taken by thinking-level, so we use
+// Ctrl+Shift+S — mnemonic for "S"witch).
+//
+// Communication with other extensions:
+// - Writes `globalThis.__PI_SWITCH_AGENT__` (in-process)
+// - Reads/writes `.soly/agent` if it exists (cross-session persistence,
+//   shared with soly extension). If no soly project, persists to
+//   `~/.pi-switch/agent` instead.
+// =============================================================================
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Default agent used when no override is set. */
+export const DEFAULT_AGENT = "worker";
+
+/** Built-in pi-subagents that we always offer in the cycle. */
+export const BUILTIN_AGENTS: readonly string[] = [
+	"worker",
+	"oracle",
+	"scout",
+	"researcher",
+	"planner",
+	"context-builder",
+	"reviewer",
+	"delegate",
+] as const;
+
+/** Visual metadata for every known agent. Used by the rich status badge,
+ *  the header bar, and the multi-line switch notify. */
+export interface AgentMeta {
+	emoji: string;
+	shortLabel: string;
+	description: string;
+	writesFiles: boolean;
+}
+
+export const AGENT_META: Record<string, AgentMeta> = {
+	worker: { emoji: "\u26a1", shortLabel: "worker", description: "generic implementation, all tools", writesFiles: true },
+	oracle: { emoji: "\ud83d\udd2e", shortLabel: "oracle", description: "decision-consistency, no file edits", writesFiles: false },
+	scout: { emoji: "\ud83d\udd0d", shortLabel: "scout", description: "codebase recon, read-only", writesFiles: false },
+	researcher: { emoji: "\ud83d\udcda", shortLabel: "researcher", description: "external docs / libraries", writesFiles: false },
+	planner: { emoji: "\ud83d\udccb", shortLabel: "planner", description: "planning + ordering, no code", writesFiles: false },
+	"context-builder": { emoji: "\ud83c\udfd7", shortLabel: "ctx-builder", description: "context handoff for other agents", writesFiles: true },
+	reviewer: { emoji: "\ud83d\udc40", shortLabel: "reviewer", description: "adversarial code review", writesFiles: false },
+	delegate: { emoji: "\ud83e\udd1d", shortLabel: "delegate", description: "pure orchestration, dispatches others", writesFiles: false },
+};
+
+/** Get metadata for an agent. Falls back to a neutral entry for unknown. */
+export function getAgentMeta(name: string): AgentMeta {
+	return AGENT_META[name] ?? {
+		emoji: "\u2753",
+		shortLabel: name.length > 12 ? name.slice(0, 11) + "\u2026" : name,
+		description: "user-defined agent",
+		writesFiles: true,
+	};
+}
+
+/** Validate an agent name. */
+export function isValidAgentName(name: string): boolean {
+	return /^[a-zA-Z0-9_-]{1,64}$/.test(name);
+}
+
+/** Discover agent `.md` files in user dir. */
+export function discoverUserAgents(userDir: string = path.join(os.homedir(), ".pi", "agent", "agents")): string[] {
+	if (!fs.existsSync(userDir)) return [];
+	const names: string[] = [];
+	for (const file of fs.readdirSync(userDir)) {
+		if (!file.endsWith(".md")) continue;
+		try {
+			const raw = fs.readFileSync(path.join(userDir, file), "utf-8");
+			const m = raw.match(/^---\n([\s\S]*?)\n---/);
+			if (!m) continue;
+			const fm = m[1] ?? "";
+			const nameMatch = fm.match(/^name:\s*(.+)$/m);
+			if (nameMatch) {
+				const n = (nameMatch[1] ?? "").trim();
+				if (isValidAgentName(n)) names.push(n);
+			}
+		} catch { /* skip */ }
+	}
+	return names;
+}
+
+/** Build the full cycle of available agents. Built-ins first, then
+ *  user-discovered. Dedupes while preserving first-occurrence order. */
+export function availableAgents(userDir?: string): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	const push = (n: string) => {
+		if (!seen.has(n)) {
+			seen.add(n);
+			out.push(n);
+		}
+	};
+	for (const a of BUILTIN_AGENTS) push(a);
+	for (const a of discoverUserAgents(userDir)) push(a);
+	return out;
+}
+
+/** Cycle order. */
+export function nextAgent(current: string, cycle: readonly string[]): string {
+	if (cycle.length === 0) return DEFAULT_AGENT;
+	const idx = cycle.indexOf(current);
+	if (idx < 0) return cycle[0]!;
+	return cycle[(idx + 1) % cycle.length]!;
+}
+
+/** Parse a user-supplied agent name. */
+export function parseAgentName(raw: string): string | null {
+	const n = raw.trim();
+	if (!isValidAgentName(n)) return null;
+	return n;
+}
+
+/** Short badge: `<emoji> <name>`. Null for default (silent). */
+export function formatAgentBadge(agent: string): string | null {
+	if (agent === DEFAULT_AGENT) return null;
+	const meta = getAgentMeta(agent);
+	return `${meta.emoji} ${agent}`;
+}
+
+/** Multi-line switch notify. */
+export function formatAgentSwitchNotify(prev: string, next: string): string {
+	const prevMeta = getAgentMeta(prev);
+	const nextMeta = getAgentMeta(next);
+	const lines: string[] = [
+		"pi-switch agent changed",
+		"",
+		`  ${prevMeta.emoji} ${prev.padEnd(16)} →  ${nextMeta.emoji} ${next}`,
+		`  ${"".padEnd(16)}     ${nextMeta.description}`,
+		"",
+		`  writes files: ${nextMeta.writesFiles ? "yes" : "no (read-only)"}  ·  next subagent call uses: ${next}`,
+	];
+	return lines.join("\n");
+}
+
+/** Group agents: built-ins + user-defined. */
+export function groupedAvailableAgents(userDir?: string): Array<{ header: string; agents: string[] }> {
+	const all = availableAgents(userDir);
+	const groups: Array<{ header: string; agents: string[] }> = [];
+	const builtin = all.filter((a) => BUILTIN_AGENTS.includes(a));
+	if (builtin.length > 0) groups.push({ header: "built-in", agents: builtin });
+	const user = all.filter((a) => !BUILTIN_AGENTS.includes(a));
+	if (user.length > 0) groups.push({ header: "user-defined", agents: user });
+	return groups;
+}
+
+/** Header line shown above chat. Persistent, dim, single line. */
+export function formatHeaderLine(agent: string): string {
+	const meta = getAgentMeta(agent);
+	const writeTag = meta.writesFiles ? "" : " \u00b7 read-only";
+	return `${meta.emoji} ${agent}  \u00b7  ${meta.description}${writeTag}    [Ctrl+Shift+S to cycle]`;
+}
+
+// ---------------------------------------------------------------------------
+// Persistence
+// ---------------------------------------------------------------------------
+
+/** Where to persist the current agent. Prefers `.soly/agent` if a soly
+ *  project exists (shared with soly extension). Otherwise `~/.pi-switch/agent`. */
+export function agentFilePath(cwd: string): string {
+	const solyAgent = path.join(cwd, ".soly", "agent");
+	if (fs.existsSync(path.join(cwd, ".soly"))) return solyAgent;
+	// Respect HOME/USERPROFILE for testability (otherwise os.homedir() ignores them on Windows)
+	const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+	const fallbackDir = path.join(home, ".pi-switch");
+	fs.mkdirSync(fallbackDir, { recursive: true });
+	return path.join(fallbackDir, "agent");
+}
+
+/** Read persisted agent from disk. Returns null if missing/invalid. */
+export function loadAgent(cwd: string): string | null {
+	try {
+		const file = agentFilePath(cwd);
+		if (!fs.existsSync(file)) return null;
+		const raw = fs.readFileSync(file, "utf-8").trim();
+		if (!isValidAgentName(raw)) return null;
+		return raw;
+	} catch {
+		return null;
+	}
+}
+
+/** Write current agent to disk. */
+export function saveAgent(cwd: string, agent: string): void {
+	try {
+		const file = agentFilePath(cwd);
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, agent + "\n", "utf-8");
+	} catch { /* best-effort */ }
+}