pi-subagents-j0k3r 1.0.0

package/skills/subagents-configuration/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: subagents-configuration
+description: "configuration-only guidance for Pi Subagents Extension, including markdown subagent definitions, .pi/subagents.json, model profiles, tool allowlists, background handoff shortcuts, history storage, and generic interaction handoff."
+license: Apache-2.0
+metadata:
+  author: j0k3r
+  version: "1.0"
+---
+
+# Subagents Configuration
+
+## Registry Contract
+
+Use this block as the machine-readable source for `.pi/skill-registry.json` generation. Keep it valid JSON.
+
+```json
+{
+  "category": "workflow",
+  "domains": ["subagents-configuration", "subagent-config", "model-profile-config", "tool-allowlist-config", "subagent-history-config", "subagent-shortcut-config"],
+  "triggers": {
+    "paths": [
+      ".pi/subagents/**/*.md",
+      ".pi/subagents.json",
+      "subagents/**/*.md",
+      "subagents.json",
+      "~/.pi/agent/subagents/**/*.md",
+      "~/.pi/agent/subagents.json"
+    ],
+    "keywords": [
+      "subagents configuration",
+      "configure subagents",
+      "configurar subagents",
+      "configuro subagents",
+      "como configurar subagents",
+      "cómo configurar subagents",
+      "como configuro subagents",
+      "cómo configuro subagents",
+      "como se configura subagents",
+      "cómo se configura subagents",
+      "configurar subagentes",
+      "configuro subagentes",
+      "como configurar subagentes",
+      "cómo configurar subagentes",
+      "como configuro subagentes",
+      "cómo configuro subagentes",
+      "como se configura subagentes",
+      "cómo se configura subagentes",
+      "configuracion subagents",
+      "configuración subagents",
+      "configuracion subagentes",
+      "configuración subagentes",
+      "subagent config",
+      "subagents.json",
+      "model profiles configuration",
+      "tool allowlist configuration",
+      "subagent history configuration",
+      "background handoff shortcut",
+      "background_handoff_shortcut",
+      "interaction handoff configuration"
+    ]
+  },
+  "sdd_phases": [],
+  "related_skills": [],
+  "priority": 88
+}
+```
+
+Field conventions:
+
+- `category`: short grouping such as `base`, `transversal`, `workflow`, `quality`, `security`, or `runtime`.
+- `domains`: stable domain tags used for routing.
+- `triggers.paths`: glob-like project paths that should activate this skill.
+- `triggers.keywords`: configuration-only keywords that should activate this skill.
+- `sdd_phases`: keep empty for configuration-only skills so phase routing alone does not load them.
+- `related_skills`: configuration-adjacent skills only; do not add usage, implementation, or workflow skills.
+- `priority`: routing priority from 0 to 100. Higher means consider earlier when multiple skills match.
+
+## Activation Contract
+
+Use this skill only when the user asks how to configure Pi Subagents or when editing/reviewing subagent configuration files: markdown subagent definitions and project/global `subagents.json`. Cover model profiles, allowed tools, history settings, background task config, background handoff shortcuts, lean resources, and generic interaction handoff as configuration topics only.
+
+Do not load this skill for ordinary subagent delegation/use (`subagent_run`, task status/result polling), extension implementation work, task history browsing, or editing this skill file; those are not configuration questions.
+
+## Hard Rules
+
+- The main agent remains the orchestrator; subagents must not delegate to other subagents.
+- Never allow `subagent_*` tools in subagent tool allowlists; the extension filters them, but configs should not include them.
+- Prefer narrow tool allowlists per subagent. Do not grant write/bash tools unless the subagent purpose requires them.
+- For SDD/PRD phase agents, prefer deterministic active-flow memory tools only: `memory_search`, `memory_get`, `memory_add`, and `memory_update`; avoid `memory_context` and `memory_recall` in subagent allowlists unless there is a specific reviewed need.
+- For SDD phase agents, memory write tools may be allowed only for active SDD flow memory/artifacts according to `sdd-workflow`.
+- Project subagents live in `.pi/subagents/*.md`; global user subagents live in `$PI_CODING_AGENT_DIR/subagents/*.md` or `~/.pi/agent/subagents/*.md`.
+- Project definitions override global definitions with the same normalized name.
+- Subagents config resolves as a cascade: project `.pi/subagents.json` overrides global `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Communicate this precedence to users when explaining config behavior.
+- `model_profiles` are deep-merged by agent name with project-local profile fields taking precedence over global profile fields.
+- Nested subagent sessions should use `session_resources: "lean"` by default so the subagent markdown body becomes the nested session system prompt, the delegated user prompt contains only orchestrator context/task, and workflow skills, prompt templates, themes, context files, and startup context injections are not auto-loaded.
+- In lean mode, extensions are loaded for allowlisted tools and tool-safety hooks only; prompt/context lifecycle hooks such as `before_agent_start` and `context` must not inject hidden messages into subagent turns.
+- Subagent task history is stored globally under data storage, but rows remain project-scoped by `cwd`; history stores delegated prompt and subagent system prompt separately.
+- Debug logging is disabled by default with `debug: false`; when enabled in global or project `subagents.json`, logs are written to the executing project's `cwd/.pi/subagents-debug.log`.
+- After changing subagent markdown/config or extension code, tell the user to `/reload` or restart Pi.
+
+Recommended `subagents.json` starter:
+
+```json
+{
+  "mode": "opencode",
+  "timeout_ms": 600000,
+  "stall_timeout_ms": 120000,
+  "max_concurrency": 5,
+  "debug": false,
+  "session_resources": "lean",
+  "history_panel_shortcut": "ctrl+,",
+  "detail_cancel_shortcut": "x",
+  "background_handoff_shortcut": "ctrl+h",
+  "default_tools": [
+    "read",
+    "memory_context",
+    "memory_search",
+    "memory_recall",
+    "memory_get"
+  ],
+  "model_profiles": {}
+}
+```
+
+Markdown subagent frontmatter pattern:
+
+```md
+---
+name: discovery
+description: investigates isolated ideas, code, documentation, and context7 before deciding next workflow
+tools:
+  - read
+  - memory_search
+model: anthropic/claude-sonnet-4-5
+effort: low
+---
+
+# Discovery Subagent
+
+Instructions...
+```
+
+## Decision Gates
+
+- If the subagent will modify files, run bash, or write memory, ask whether a full SDD workflow or stricter review is required.
+- If the subagent needs human input, require a structured `interaction_required` request with enough prompt, payload, and expected-response data for the parent to answer.
+- If a project wants many subagents or broad tools, recommend starting with read-only discovery agents and expanding deliberately.
+- If model profiles are global, confirm the user wants global behavior rather than project-only config.
+
+## Execution Steps
+
+1. Identify target scope: global subagent, project subagent, global config, or project config, and explain the cascade when relevant: project-local config first, then global config for missing fields, then built-in defaults.
+2. Read existing subagent markdown/config before editing.
+3. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions.
+4. Set minimal tool allowlists; remove any `subagent_*` entries.
+5. Configure `model_profiles`, `default_model`, and `default_effort` only when the user wants explicit routing.
+6. Configure `debug: true` only for temporary diagnostics; keep `debug: false` by default and remember logs are written under the executing project's `.pi` directory.
+7. Validate JSON syntax for `subagents.json` and frontmatter/body structure for markdown agents.
+8. When configuring OpenCode-mode history opening, prefer `history_panel_shortcut` with `ctrl+<letter>` or `ctrl+,` values and document any built-in shortcut conflicts.
+9. When configuring history/detail cancellation, prefer `detail_cancel_shortcut` with `x` by default; it supports `ctrl+<letter>`, `ctrl+shift+<letter>`, `ctrl+,`, or one lowercase letter. It only cancels the selected queued/running task while the detail panel is active.
+10. When configuring Claude-mode background handoff, prefer `background_handoff_shortcut` with `ctrl+<letter>` values and document any built-in shortcut conflicts.
+11. Tell the user to `/reload` or restart Pi.
+12. If validating configuration after reload, use `subagent_list_agents` only when the user asks for runtime verification; do not run delegated tasks just to validate configuration.
+
+## Output Contract
+
+Return:
+
+- Skill applied: `subagents-configuration`.
+- Scope/path configured or reviewed.
+- Subagents/config fields added, changed, or preserved.
+- Tool allowlist, system-prompt isolation, Context7 scope, memory-tool scope, debug logging, and model/effort decisions.
+- Related configuration skills considered or loaded.
+- Validation executed, or the concrete reason it was not run.
+- Required reload/restart note and open risks.
+
+## References
+
+- `extensions/subagents/README.md` — Subagents configuration, shortcuts, history settings, and model profiles.
+- `extensions/subagents/src/config.ts` — subagent/config loading and tool filtering.
+- `extensions/subagents/src/history.ts` — global history storage behavior.
+- This package README — generic interaction handoff contract and runtime behavior.

package/src/config.ts

@@ -0,0 +1,262 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ModelRef, SubagentDefinition, SubagentModelProfile, SubagentModelProfiles, SubagentSessionResources, SubagentsConfig, SubagentUiMode, ThinkingEffort } from './types.js';
+
+const DEFAULT_TOOLS = ['read', 'memory_context', 'memory_search', 'memory_recall', 'memory_get'];
+const DEFAULT_MAX_CONCURRENCY = 5;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_STALL_TIMEOUT_MS = 2 * 60 * 1000;
+const DEFAULT_BACKGROUND_HANDOFF_SHORTCUT = 'ctrl+h';
+const DEFAULT_HISTORY_PANEL_SHORTCUT = 'ctrl+,';
+const DEFAULT_DETAIL_CANCEL_SHORTCUT = 'x';
+const BLOCKED_SUBAGENT_TOOLS = new Set([
+  'subagent_run',
+  'subagent_list_agents',
+  'subagent_status',
+  'subagent_result',
+  'subagent_list_tasks',
+  'subagent_cancel',
+]);
+
+function sanitizeTools(tools: string[]): string[] {
+  return tools.map(String).filter((tool) => !BLOCKED_SUBAGENT_TOOLS.has(tool) && !tool.startsWith('subagent_'));
+}
+
+function parseScalar(value: string): any {
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  return trimmed.replace(/^['"]|['"]$/g, '');
+}
+
+export function parseFrontmatter(text: string): { data: Record<string, any>; body: string } {
+  if (!text.startsWith('---\n')) return { data: {}, body: text };
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return { data: {}, body: text };
+  const raw = text.slice(4, end).trim();
+  const body = text.slice(end + 4).replace(/^\r?\n/, '');
+  const data: Record<string, any> = {};
+  let currentKey: string | undefined;
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const list = line.match(/^\s*-\s+(.+)$/);
+    if (list && currentKey) {
+      if (!Array.isArray(data[currentKey])) data[currentKey] = [];
+      data[currentKey].push(parseScalar(list[1]));
+      continue;
+    }
+    const m = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    currentKey = m[1];
+    const value = m[2];
+    if (!value) data[currentKey] = [];
+    else data[currentKey] = parseScalar(value);
+  }
+  return { data, body };
+}
+
+function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), '.pi', 'agent');
+}
+
+function subagentsConfigPath(dir = agentDir()): string {
+  return path.join(dir, 'subagents.json');
+}
+
+function readJson(file: string): any {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return {}; }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function positiveNumber(value: any, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function positiveInteger(value: any, fallback: number): number {
+  return Math.max(1, Math.floor(positiveNumber(value, fallback)));
+}
+
+export function parseModel(value: any): ModelRef | undefined {
+  if (!value || value === 'default') return undefined;
+  if (typeof value === 'string') {
+    const parts = value.split('/');
+    if (parts.length !== 2) return undefined;
+    const [provider, id] = parts.map((part) => part.trim());
+    return provider && id ? { provider, id } : undefined;
+  }
+  if (isPlainObject(value) && typeof value.provider === 'string' && typeof value.id === 'string') {
+    const provider = value.provider.trim();
+    const id = value.id.trim();
+    return provider && id ? { provider, id } : undefined;
+  }
+  return undefined;
+}
+
+const THINKING_EFFORTS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
+
+export function parseEffort(value: any): ThinkingEffort | undefined {
+  if (!value || value === 'default') return undefined;
+  const effort = String(value).trim().toLowerCase();
+  return THINKING_EFFORTS.has(effort) ? effort as ThinkingEffort : undefined;
+}
+
+function parseSessionResources(value: any): SubagentSessionResources {
+  const resources = String(value ?? 'lean').trim().toLowerCase();
+  return resources === 'full' ? 'full' : 'lean';
+}
+
+function parseMode(value: any): SubagentUiMode {
+  const mode = String(value ?? 'opencode').trim().toLowerCase();
+  return mode === 'claude' ? 'claude' : 'opencode';
+}
+
+function parseCtrlShortcut(value: any, fallback: string): string {
+  const shortcut = String(value ?? fallback).trim().toLowerCase();
+  return /^(?:ctrl\+(?:[a-z]|,)|ctrl\+shift\+[a-z])$/.test(shortcut) ? shortcut : fallback;
+}
+
+function parseDetailShortcut(value: any): string {
+  const shortcut = String(value ?? DEFAULT_DETAIL_CANCEL_SHORTCUT).trim().toLowerCase();
+  if (/^[a-z]$/.test(shortcut)) return shortcut;
+  return /^(?:ctrl\+(?:[a-z]|,)|ctrl\+shift\+[a-z])$/.test(shortcut) ? shortcut : DEFAULT_DETAIL_CANCEL_SHORTCUT;
+}
+
+function parseBackgroundHandoffShortcut(value: any): string {
+  return parseCtrlShortcut(value, DEFAULT_BACKGROUND_HANDOFF_SHORTCUT);
+}
+
+function parseBoolean(value: any, fallback = false): boolean {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return fallback;
+}
+
+function parseModelProfile(value: unknown): SubagentModelProfile | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const profile: SubagentModelProfile = {};
+  const model = parseModel(value.model);
+  const effort = parseEffort(value.effort ?? value.thinking_level ?? value.thinkingLevel);
+  if (model) profile.model = model;
+  if (effort) profile.effort = effort;
+  return Object.keys(profile).length ? profile : undefined;
+}
+
+function parseModelProfiles(value: unknown): SubagentModelProfiles {
+  if (!isPlainObject(value)) return {};
+  const profiles: SubagentModelProfiles = {};
+  for (const [name, rawProfile] of Object.entries(value)) {
+    const normalizedName = name.trim();
+    if (!normalizedName) continue;
+    const profile = parseModelProfile(rawProfile);
+    if (profile) profiles[normalizedName] = profile;
+  }
+  return profiles;
+}
+
+function mergeModelProfiles(globalRaw: unknown, projectRaw: unknown): SubagentModelProfiles {
+  const globalProfiles = parseModelProfiles(globalRaw);
+  const projectProfiles = parseModelProfiles(projectRaw);
+  const merged: SubagentModelProfiles = { ...globalProfiles };
+  for (const [name, projectProfile] of Object.entries(projectProfiles)) {
+    merged[name] = { ...(merged[name] ?? {}), ...projectProfile };
+  }
+  return merged;
+}
+
+function serializeModelRef(model: ModelRef): string {
+  return `${model.provider}/${model.id}`;
+}
+
+function cleanProfile(profile: SubagentModelProfile): Record<string, string> | undefined {
+  const cleaned: Record<string, string> = {};
+  if (profile.model) cleaned.model = serializeModelRef(profile.model);
+  if (profile.effort) cleaned.effort = profile.effort;
+  return Object.keys(cleaned).length ? cleaned : undefined;
+}
+
+export function readSubagentsConfig(cwd: string): SubagentsConfig {
+  const globalRaw = readJson(subagentsConfigPath());
+  const projectRaw = readJson(path.join(cwd, '.pi', 'subagents.json'));
+  const raw = { ...globalRaw, ...projectRaw };
+  return {
+    default_model: parseModel(raw.default_model),
+    default_effort: parseEffort(raw.default_effort ?? raw.default_thinking_level ?? raw.thinkingLevel),
+    model_profiles: mergeModelProfiles(globalRaw.model_profiles, projectRaw.model_profiles),
+    timeout_ms: positiveInteger(raw.timeout_ms, DEFAULT_TIMEOUT_MS),
+    stall_timeout_ms: positiveInteger(raw.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
+    max_concurrency: positiveInteger(raw.max_concurrency, DEFAULT_MAX_CONCURRENCY),
+    default_tools: sanitizeTools(Array.isArray(raw.default_tools) ? raw.default_tools.map(String) : DEFAULT_TOOLS),
+    session_resources: parseSessionResources(raw.session_resources ?? raw.sessionResources),
+    mode: parseMode(raw.mode),
+    background_handoff_shortcut: parseBackgroundHandoffShortcut(raw.background_handoff_shortcut ?? raw.backgroundHandoffShortcut),
+    history_panel_shortcut: parseCtrlShortcut(raw.history_panel_shortcut ?? raw.historyPanelShortcut, DEFAULT_HISTORY_PANEL_SHORTCUT),
+    detail_cancel_shortcut: parseDetailShortcut(raw.detail_cancel_shortcut ?? raw.detailCancelShortcut),
+    debug: parseBoolean(raw.debug, false),
+  };
+}
+
+export function saveGlobalSubagentModelProfile(input: { agentName: string; profile: SubagentModelProfile; agentDir?: string }): void {
+  const file = subagentsConfigPath(input.agentDir);
+  const root = readJson(file);
+  const writableRoot: Record<string, unknown> = isPlainObject(root) ? { ...root } : {};
+  const modelProfiles = isPlainObject(writableRoot.model_profiles) ? { ...writableRoot.model_profiles } : {};
+  const agentName = input.agentName.trim().toLowerCase();
+  const cleaned = cleanProfile(input.profile);
+  if (agentName && cleaned) modelProfiles[agentName] = cleaned;
+  if (Object.keys(modelProfiles).length) writableRoot.model_profiles = modelProfiles;
+  else delete writableRoot.model_profiles;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(writableRoot, null, 2)}\n`, 'utf8');
+}
+
+export function resetGlobalSubagentModelProfileField(input: { agentName: string; field: 'model' | 'effort'; agentDir?: string }): void {
+  const file = subagentsConfigPath(input.agentDir);
+  const root = readJson(file);
+  const writableRoot: Record<string, unknown> = isPlainObject(root) ? { ...root } : {};
+  const modelProfiles = isPlainObject(writableRoot.model_profiles) ? { ...writableRoot.model_profiles } : {};
+  const agentName = input.agentName.trim().toLowerCase();
+  const existing = isPlainObject(modelProfiles[agentName]) ? { ...modelProfiles[agentName] } : {};
+  delete existing[input.field];
+  if (Object.keys(existing).length) modelProfiles[agentName] = existing;
+  else delete modelProfiles[agentName];
+  if (Object.keys(modelProfiles).length) writableRoot.model_profiles = modelProfiles;
+  else delete writableRoot.model_profiles;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(writableRoot, null, 2)}\n`, 'utf8');
+}
+
+function loadSubagentsFromDir(dir: string): SubagentDefinition[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((file) => {
+      const filePath = path.join(dir, file);
+      const { data, body } = parseFrontmatter(fs.readFileSync(filePath, 'utf8'));
+      const name = String(data.name || path.basename(file, '.md')).trim().toLowerCase();
+      const description = String(data.description || `${name} subagent`).trim();
+      const tools = sanitizeTools(Array.isArray(data.tools) ? data.tools.map(String) : DEFAULT_TOOLS);
+      return { name, description, filePath, instructions: body.trim(), model: parseModel(data.model), effort: parseEffort(data.effort ?? data.thinking_level ?? data.thinkingLevel), tools };
+    });
+}
+
+export function loadSubagents(cwd: string): SubagentDefinition[] {
+  const byName = new Map<string, SubagentDefinition>();
+  for (const agent of loadSubagentsFromDir(path.join(agentDir(), 'subagents'))) byName.set(agent.name, agent);
+  for (const agent of loadSubagentsFromDir(path.join(cwd, '.pi', 'subagents'))) byName.set(agent.name, agent);
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function getSubagent(cwd: string, name: string): SubagentDefinition | undefined {
+  return loadSubagents(cwd).find((a) => a.name === name.toLowerCase());
+}

package/src/debug.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readSubagentsConfig } from './config.js';
+
+export function isSubagentsDebugEnabled(cwd?: string): boolean {
+  if (!cwd) return false;
+  try {
+    return readSubagentsConfig(cwd).debug === true;
+  } catch {
+    return false;
+  }
+}
+
+const DEBUG_LOG_RELATIVE_PATH = '.pi/subagents-debug.log';
+
+function ensureDebugLogGitignored(root: string): void {
+  try {
+    if (!fs.existsSync(path.join(root, '.git'))) return;
+    const gitignorePath = path.join(root, '.gitignore');
+    let current = '';
+    try { current = fs.readFileSync(gitignorePath, 'utf8'); } catch {}
+    const lines = current.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(DEBUG_LOG_RELATIVE_PATH)) return;
+    const prefix = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync(gitignorePath, `${prefix}${DEBUG_LOG_RELATIVE_PATH}\n`);
+  } catch {}
+}
+
+export function writeSubagentsDebugLog(cwd: string | undefined, scope: string, data: unknown): void {
+  const root = cwd ?? process.cwd();
+  if (!isSubagentsDebugEnabled(root)) return;
+  try {
+    const file = path.join(root, DEBUG_LOG_RELATIVE_PATH);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    ensureDebugLogGitignored(root);
+    fs.appendFileSync(file, `${new Date().toISOString()} ${scope} ${JSON.stringify(data, (_key, value) => value instanceof Error ? { name: value.name, message: value.message, stack: value.stack } : value).slice(0, 4000)}\n`);
+  } catch {}
+}