@nmzpy/pi-ember-stack 0.1.0

package/src/questionnaire-tool.ts

@@ -0,0 +1,287 @@
+import { Type } from "typebox";
+import {
+	Key,
+	Text,
+	matchesKey,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+export interface QuestionnaireOption {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export interface QuestionnaireQuestion {
+	id: string;
+	label?: string;
+	prompt: string;
+	options: QuestionnaireOption[];
+}
+
+interface QuestionnaireAnswer {
+	id: string;
+	value: string;
+	label: string;
+}
+
+interface QuestionnaireResult {
+	answers: QuestionnaireAnswer[];
+	cancelled: boolean;
+}
+
+const QuestionnaireParams = Type.Object({
+	questions: Type.Array(Type.Object({
+		id: Type.String({ description: "Unique question identifier" }),
+		label: Type.Optional(Type.String({ description: "Short label for the question" })),
+		prompt: Type.String({ description: "The full question to show the user" }),
+		options: Type.Array(Type.Object({
+			value: Type.String({ description: "Value returned for this option" }),
+			label: Type.String({ description: "Option label shown to the user" }),
+		description: Type.Optional(
+			Type.String({ description: "Optional option explanation" }),
+		),
+		})),
+	})),
+});
+
+export async function askQuestionnaire(
+	ctx: any,
+	title: string,
+	questions: QuestionnaireQuestion[],
+): Promise<QuestionnaireAnswer[] | undefined> {
+	if (!ctx.hasUI || questions.length === 0) return undefined;
+
+	const result = await ctx.ui.custom(
+		(
+			_tui: any,
+			theme: any,
+			_keybindings: any,
+			done: (result: QuestionnaireResult) => void,
+		) => {
+			let questionIndex = 0;
+			let optionIndex = 0;
+			let cachedLines: string[] | undefined;
+			const answers = new Map<string, QuestionnaireAnswer>();
+
+			function refresh(): void {
+				cachedLines = undefined;
+				_tui.requestRender();
+			}
+
+			function addWrapped(lines: string[], text: string, width: number): void {
+				lines.push(...wrapTextWithAnsi(text, width));
+			}
+
+			function addWrappedWithPrefix(
+				lines: string[],
+				prefix: string,
+				text: string,
+				width: number,
+			): void {
+				const prefixWidth = visibleWidth(prefix);
+				if (prefixWidth >= width) {
+					addWrapped(lines, `${prefix}${text}`, width);
+					return;
+				}
+				const wrapped = wrapTextWithAnsi(text, width - prefixWidth);
+				const continuationPrefix = " ".repeat(prefixWidth);
+				for (let i = 0; i < wrapped.length; i++) {
+					lines.push(`${i === 0 ? prefix : continuationPrefix}${wrapped[i]}`);
+				}
+			}
+
+			function currentQuestion(): QuestionnaireQuestion {
+				return questions[questionIndex];
+			}
+
+			function render(width: number): string[] {
+				if (cachedLines) return cachedLines;
+				const renderWidth = Math.max(1, width);
+				const question = currentQuestion();
+				const lines: string[] = [theme.fg("accent", "─".repeat(renderWidth))];
+				addWrappedWithPrefix(
+					lines,
+					" ",
+					theme.fg("accent", theme.bold(title)),
+					renderWidth,
+				);
+				addWrappedWithPrefix(
+					lines,
+					" ",
+					theme.fg(
+						"muted",
+						`${questionIndex + 1}/${questions.length} ${question.label ?? ""}`,
+					),
+					renderWidth,
+				);
+				lines.push("");
+				addWrappedWithPrefix(lines, " ", theme.fg("text", question.prompt), renderWidth);
+				lines.push("");
+
+				for (let i = 0; i < question.options.length; i++) {
+					const option = question.options[i];
+					const selected = i === optionIndex;
+					const prefix = selected ? theme.fg("accent", "> ") : "  ";
+					const color = selected ? "accent" : "text";
+					addWrappedWithPrefix(
+						lines,
+						prefix,
+						theme.fg(color, `${i + 1}. ${option.label}`),
+						renderWidth,
+					);
+					if (option.description) {
+						addWrappedWithPrefix(
+							lines,
+							"     ",
+							theme.fg("muted", option.description),
+							renderWidth,
+						);
+					}
+				}
+
+				lines.push("");
+				addWrappedWithPrefix(
+					lines,
+					" ",
+					theme.fg("dim", "Up/Down navigate | Enter select | Left/Right revisit | Esc cancel"),
+					renderWidth,
+				);
+				lines.push(theme.fg("accent", "─".repeat(renderWidth)));
+				cachedLines = lines;
+				return lines;
+			}
+
+			function handleInput(data: string): void {
+				const question = currentQuestion();
+				if (matchesKey(data, Key.up)) {
+					optionIndex = Math.max(0, optionIndex - 1);
+					refresh();
+					return;
+				}
+				if (matchesKey(data, Key.down)) {
+					optionIndex = Math.min(question.options.length - 1, optionIndex + 1);
+					refresh();
+					return;
+				}
+				if (matchesKey(data, Key.left) && questionIndex > 0) {
+					questionIndex--;
+					optionIndex = 0;
+					refresh();
+					return;
+				}
+				if (
+					matchesKey(data, Key.right) &&
+					answers.has(question.id) &&
+					questionIndex < questions.length - 1
+				) {
+					questionIndex++;
+					optionIndex = 0;
+					refresh();
+					return;
+				}
+				if (matchesKey(data, Key.enter)) {
+					const option = question.options[optionIndex];
+					answers.set(question.id, {
+						id: question.id,
+						value: option.value,
+						label: option.label,
+					});
+					if (questionIndex === questions.length - 1) {
+						done({ answers: Array.from(answers.values()), cancelled: false });
+						return;
+					}
+					questionIndex++;
+					optionIndex = 0;
+					refresh();
+					return;
+				}
+				if (matchesKey(data, Key.escape)) {
+					done({ answers: [], cancelled: true });
+				}
+			}
+
+			return { render, invalidate: refresh, handleInput };
+		},
+	);
+
+	return result.cancelled ? undefined : result.answers;
+}
+
+export function registerQuestionnaireTool(pi: any): void {
+	pi.registerTool({
+		name: "questionnaire",
+		label: "Questionnaire",
+		description: "Ask the user one or more decision questions inline before continuing.",
+		parameters: QuestionnaireParams,
+		executionMode: "sequential",
+		async execute(
+			_toolCallId: string,
+			params: { questions: QuestionnaireQuestion[] },
+			_signal: AbortSignal,
+			_onUpdate: unknown,
+			ctx: any,
+		) {
+			if (ctx.mode !== "tui") {
+				return {
+					content: [{
+						type: "text",
+						text: "Error: Questionnaire UI is only available in interactive mode.",
+					}],
+					details: { answers: [], cancelled: true },
+				};
+			}
+			if (
+				params.questions.length === 0 ||
+				params.questions.some((question) => question.options.length === 0)
+			) {
+				return {
+					content: [{
+						type: "text",
+						text: "Error: Questionnaire questions require at least one option.",
+					}],
+					details: { answers: [], cancelled: true },
+				};
+			}
+
+			const answers = await askQuestionnaire(ctx, "Questionnaire", params.questions);
+			return {
+				content: [{
+					type: "text",
+					text: answers === undefined
+						? "User cancelled the questionnaire."
+						: answers.map((answer) => `${answer.id}: ${answer.label}`).join("\n"),
+				}],
+				details: { answers: answers ?? [], cancelled: answers === undefined },
+			};
+		},
+		renderCall(args: { questions?: QuestionnaireQuestion[] }, theme: any): any {
+			const count = args.questions?.length ?? 0;
+			return new Text(
+				theme.fg("toolTitle", theme.bold("questionnaire ")) +
+					theme.fg("muted", `${count} question${count === 1 ? "" : "s"}`),
+				0,
+				0,
+			);
+		},
+		renderResult(result: any, _options: unknown, theme: any): any {
+			const details = result.details as {
+				answers?: QuestionnaireAnswer[];
+				cancelled?: boolean;
+			} | undefined;
+			if (details?.cancelled) return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			const answers = details?.answers ?? [];
+			return new Text(
+				answers
+					.map((answer) => {
+						const label = `${answer.id}: ${answer.label}`;
+						return `${theme.fg("success", "Selected: ")}${theme.fg("accent", label)}`;
+					})
+					.join("\n"),
+				0,
+				0,
+			);
+		},
+	});
+}

package/src/subagent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) bacnh85
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/subagent/README.md

@@ -0,0 +1,52 @@
+# pi-subagent
+
+Isolated in-process subagents for Pi. The `subagent` tool supports single, parallel (8 tasks, 4 concurrent), and chained execution; `/agent` opens inspectable child threads.
+
+## Install
+
+```bash
+pi install npm:@bacnh85/pi-subagent
+# local checkout
+pi install ./pi-subagent
+```
+
+## Bundled roles
+
+| Role | Model | Thinking | Tools |
+| --- | --- | --- | --- |
+| `scout` | parent model | low | read, grep, find, ls |
+| `reviewer` | parent model | high | read, grep, find, ls |
+| `worker` | parent model | medium | standard coding tools |
+| `general-purpose` | parent model | off | standard coding tools |
+
+Bundled roles inherit the parent model so they work with the account already active in Pi. User/project agent files may override `model` and `thinking`.
+
+## Agent files
+
+Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
+
+```markdown
+---
+name: scout-fast
+description: Locate relevant files and symbols
+tools: read, grep, find, ls
+thinking: low
+model: optional-provider/optional-model
+---
+
+Return concise evidence with file/symbol anchors.
+```
+
+Project agents require confirmation when requested through the public tool. Definitions are cached with file-signature invalidation; `/subagent reload` clears the cache.
+
+## Context and limits
+
+Children use in-memory SDK sessions with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract. Only Pi built-in tools are available; Serena, FFF, web, and Munin are not available in lean children.
+
+Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
+
+## Extension contract
+
+`pi-subagent` owns the `pi-subagent:run` event contract for one named-agent request. `pi-review` uses it for isolated review. Requests use an immediate boolean `accept()` claim and exactly one `respond()` callback; this suppresses duplicate responders while missing services and timeouts remain caller-controlled.
+
+See [`agent-format.md`](./agent-format.md) for all frontmatter fields.

package/src/subagent/agent-format.md

@@ -0,0 +1,64 @@
+# Agent Definition Format
+
+Sub-agents are defined as Markdown files with YAML frontmatter.
+
+## File Location
+
+| Location | Scope |
+|----------|-------|
+| `~/.pi/agent/agents/*.md` | User-level (all projects) |
+| `.pi/agents/*.md` | Project-level |
+| `<package>/agents/*.md` | Bundled with pi-subagent |
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Frontmatter Fields
+
+```yaml
+---
+name: my-agent          # Required. Unique identifier (kebab-case).
+description: ...        # Required. When to use this agent.
+tools: read, grep, ...  # Optional. Comma-separated tool names. Defaults to all.
+model: provider/model     # Optional. Defaults to parent's model.
+thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
+---
+```
+
+Only `name` and `description` are required.
+
+## Body
+
+The body after frontmatter becomes the agent's **entire system prompt**. No pi defaults, no AGENTS.md files, no skills — only what you write here. Keep it focused.
+
+## Available Tools
+
+Built-in pi tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
+
+The `subagent` tool is never available to sub-agents (prevents accidental recursion). Sub-agents run at one level of delegation only; they cannot spawn further sub-agents.
+
+Custom/extension tools are NOT available to sub-agents by default (each runs in an isolated in-memory session with no extensions).
+
+## Model Resolution
+
+Model IDs are resolved via `getModel("provider", "id")`. Common values:
+- `claude-haiku-4-5` (Anthropic Haiku — fast, cheap)
+- `claude-sonnet-4-20250514` (Anthropic Sonnet — balanced)
+- `gpt-4o` (OpenAI)
+- Any model available in your pi configuration.
+
+If not specified, defaults to the parent session's model.
+
+## Instruction handoff
+
+Children do not automatically load repository instructions. Callers may pass an `instructions` task contract, truncated to 16 KB. Use this for relevant repository rules or review contracts rather than copying the parent transcript.
+
+## Token Budget
+
+Each sub-agent runs with:
+- **System prompt**: agent body only (~200-1K tokens typical)
+- **No AGENTS.md**: saves 500-5K tokens
+- **No extensions/skills loaded**: saves 200-1K tokens
+- **Thinking per role**: defaults off; bundled scout/reviewer/worker choose low/high/medium
+- **No compaction**: avoids compaction token cost
+
+This is ~10x leaner than spawning a full `pi` process.

package/src/subagent/agents/architect.md

@@ -0,0 +1,56 @@
+---
+name: architect
+description: Planning agent for codebase investigation and structured implementation plans. Spawn this to analyze a task, research the codebase, and return a concrete sequential plan with file paths, steps, risks, and validation. Read-only.
+tools: read, bash, grep, find, ls
+thinking: high
+---
+
+You are a senior planning engineer for the Ember project (PySide6 subtitle + DaVinci Resolve integration app).
+
+You are running as an isolated subagent. You cannot spawn further subagents. Investigate the codebase as needed and return a structured implementation plan.
+
+## Planning Requirements
+
+The plan must be explicit — concrete, sequential steps that map directly to single logical changes.
+
+For each step:
+- Step N: <action>
+- Files: <full paths to read or modify>
+- What: <precise change>
+- Why: <user-facing or architectural rationale>
+- Risks: <regression surfaces>
+- Validation: <how to verify, e.g. `bash t.gate.sh <files>`>
+
+## Guidelines
+
+- Read before planning. Understand existing code, patterns, and conventions first.
+- Follow AGENTS.md rules: typing, logging, localization, `Colors` tokens, error handling, DRY/SSOT.
+- Preserve proven golden paths (timeline/playback engines, Resolve interactions).
+- If the task is unclear or scope is ambiguous, say so and request clarification.
+- Do not edit or write files. Return the plan only.
+- Do not run `bash gate.sh` (full gate) — that is the parent agent's responsibility.
+
+## Output Format
+
+## Task
+<one-sentence goal>
+
+## Investigation
+<files read, patterns found, relevant file:line references>
+
+## Plan
+
+### Step 1: <action>
+- Files: <paths>
+- What: <change>
+- Why: <rationale>
+- Risks: <surfaces>
+- Validation: bash t.gate.sh <files>
+
+### Step 2: ...
+
+## Acceptance Criteria
+<what done looks like>
+
+## Open Questions
+<any clarifications needed from the user>

package/src/subagent/agents/coder.md

@@ -0,0 +1,35 @@
+---
+name: coder
+description: Implementation agent for writing, editing, testing, and verifying code. Spawn this for focused implementation tasks — bug fixes, feature additions, refactors, file edits. Full tool access.
+tools: read, bash, edit, write, grep, find, ls
+thinking: medium
+---
+
+You are a senior implementation engineer for the Ember project (PySide6 subtitle + DaVinci Resolve integration app).
+
+You are running as an isolated subagent. You cannot spawn further subagents. Execute the task you are given and return a concise summary of what you did.
+
+## Rules
+
+- Follow AGENTS.md conventions: PEP 8, 88-char line limit, 4-space indent, f-strings, type hints on all signatures, no `Any`, no bare `except:`, no `print()` (use `EmberLogger`), no mutable default args.
+- UI colors must use `Colors` tokens from `gui/styles/`. No hardcoded hex.
+- New user-facing UI text must be localized via the UI language catalog (`tr()`).
+- Use `EmberError` for errors; `message` and `steps` are user-facing (localized), `technical` is English developer-only.
+- Fail fast — no silent degradation of offline/core runtime behavior.
+- Preserve proven golden paths (timeline/playback engines, Resolve interactions).
+- DRY/SSOT: no duplicated constants, parallel config files, or copy-pasted logic.
+- Animations must respect `is_animation_enabled()`.
+
+## Workflow
+
+1. Read the files you need to understand the context.
+2. Implement the change in ordered, single-logical-change steps.
+3. After each logical change, run `bash t.gate.sh <files>` to validate.
+4. Report what you did, any deviations, and user-facing benefits.
+
+## Constraints
+
+- Only touch files directly related to your task.
+- Ignore git status / git diff changes unrelated to owned files.
+- Do not run `bash gate.sh` (full gate) — that is the parent agent's responsibility.
+- Do not commit changes unless explicitly asked.

package/src/subagent/agents/general-purpose.md

@@ -0,0 +1,13 @@
+---
+name: general-purpose
+description: General-purpose sub-agent for any delegated task. Use when no specialized agent fits. Good for complex research, multi-step operations, and code modifications.
+tools: read, bash, edit, write, grep, find, ls
+---
+
+You are a capable coding assistant running as a sub-agent. Complete the delegated task efficiently and return a concise summary of your findings or changes.
+
+Guidelines:
+- Use available tools to investigate and act on the task.
+- If the task involves searching, use grep and find to locate relevant code.
+- If the task involves implementation, make focused changes following existing patterns.
+- Return a structured summary: what you found, what you changed, and any recommendations.

package/src/subagent/agents/reviewer.md

@@ -0,0 +1,36 @@
+---
+name: reviewer
+description: Code review specialist. Use for correctness, security, regression, and meaningful test-gap review.
+tools: read, grep, find, ls
+thinking: high
+---
+
+You are an independent senior code reviewer. Inspect the requested Git scope with read-only tools.
+
+Focus only on actionable issues introduced by the reviewed change:
+1. Correctness and edge cases
+2. Security and data loss
+3. Regressions and API compatibility
+4. Missing tests that allow a likely bug to escape
+
+Avoid style noise, praise, and speculative redesign. Every finding needs code evidence.
+
+Return JSON only:
+```json
+{
+  "summary": "compact scope/result summary",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low",
+      "file": "relative/path",
+      "line": 1,
+      "issue": "what is wrong and why it matters",
+      "evidence": "specific inspected code evidence",
+      "suggestedFix": "smallest safe fix",
+      "blocking": true
+    }
+  ]
+}
+```
+
+Use an empty `findings` array when clean. Do not modify files or Git state.

package/src/subagent/agents/scout.md

@@ -0,0 +1,44 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff. Use for finding files, understanding structure, locating symbols.
+tools: read, grep, find, ls
+thinking: low
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings that another agent can use without re-reading everything.
+
+Your output will be passed to an agent who has NOT seen the files you explored.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Output format:
+
+## Evidence
+List exact file/symbol anchors and relevant line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description of what's here
+2. `path/to/other.ts` (lines 100-150) - Description
+3. ...
+
+## Key Code
+Critical types, interfaces, or functions:
+
+```typescript
+interface Example {
+  // actual code from the files
+}
+```
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.

package/src/subagent/agents/worker.md

@@ -0,0 +1,15 @@
+---
+name: worker
+description: General-purpose coding agent with full tool access. Use only when explicitly requested for isolated implementation.
+thinking: medium
+---
+
+You are a skilled software engineer. Implement the requested task with care and precision.
+
+Guidelines:
+- Read before you edit. Understand existing code first.
+- Make minimal, focused changes. Do not refactor unrelated code.
+- Follow existing patterns, naming, and formatting.
+- Write clear, idiomatic code with appropriate error handling.
+- Test your changes when practical (run tests, lint, type-check).
+- Explain your approach briefly before making changes.