@selesai/code 0.9.10 → 0.9.12

package/dist/extensions/pi-subagents/prompts/parallel-context-build.md

@@ -1,55 +0,0 @@
----
-description: Parallel context builders for planning handoff
----
-
-Launch fresh-context `explorer` subagents in parallel to build grounded handoff context for planning or implementation.
-
-Use the `subagent` tool with `workflowScript` and `runs.all(...)`; assign each child a distinct absolute or durable output path. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, `label`, and `as` name, for example:
-
-- `context-build/request-and-scope.md`
-- `context-build/codebase-and-patterns.md`
-- `context-build/validation-and-risks.md`
-
-Use one phase such as `phase: "Context build"` for the parallel tasks so async status is readable. A later synthesis step can reference specific outputs with `{outputs.requestScope}`, `{outputs.codebasePatterns}`, and `{outputs.validationRisks}` instead of relying only on `{previous}`.
-
-Do not write these context artifacts into the repository unless I explicitly ask for persistent files.
-
-Treat the slash command arguments as the primary request, target, or focus:
-
-$@
-
-If the invocation provides a URL, issue link, file path, plan path, or freeform request, read or fetch that target before assigning builder angles, then pass the target explicitly into every `explorer` task.
-
-Choose two or three strong builders based on the request. Prefer three only when the scope benefits from independent context slices. These are examples, not fixed defaults:
-
-1. Request and scope
-   Clarify the actual goal, user intent, constraints, non-goals, open questions, and decisions that affect the handoff.
-
-2. Codebase and patterns
-   Inspect relevant files, call paths, existing abstractions, tests, package constraints, and local conventions that the next agent must follow.
-
-3. Validation and risks
-   Identify likely failure modes, edge cases, test strategy, commands to run, dependency/API concerns, and escalation rules.
-
-Adapt the angles when the request calls for it:
-- Issue or PR URL: include issue requirements, acceptance criteria, linked discussion, and likely affected files.
-- Plan file: include plan consistency, missing context, implementation sequence, and validation readiness.
-- External API/library work: include current docs or primary sources through `web_search` when needed.
-- Large refactor: include module boundaries, dependency direction, migration/cutover risks, and testability.
-- UI/product work: include user flow, accessibility, copy, visual constraints, and implementation touchpoints.
-
-Ask each builder to produce a compact handoff file with:
-- relevant files and line ranges;
-- key snippets or patterns, not full dumps;
-- constraints and invariants;
-- risks and unknowns;
-- validation commands or next-best checks;
-- a `meta-prompt` section for the next architect or role subagent.
-
-After the builders return, synthesize their outputs into:
-- the most important context the next agent needs;
-- the recommended meta-prompt to use next;
-- open questions or assumptions;
-- the output artifact paths.
-
-Do not start implementation from this command unless I explicitly ask for it.

package/dist/extensions/pi-subagents/prompts/parallel-handoff-plan.md

@@ -1,61 +0,0 @@
----
-description: Parallel research/context builders into an implementation handoff plan
----
-
-Use parallel subagents to understand the request, compare any external references, inspect the local codebase, and produce a grounded implementation handoff plan with a final implementation-ready meta-prompt.
-
-Primary request, target, or focus:
-
-$@
-
-Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
-
-Use the `subagent` tool with `workflowScript`:
-
-1. First step: a parallel group.
-   - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.
-   - `explorer` for local codebase context.
-   - Add a second `explorer` only when the scope is large enough to benefit from a separate implementation-strategy pass.
-
-2. Second step: a synthesis `explorer` that reads the parallel findings and writes the final handoff plan and meta-prompt.
-
-Use distinct output paths, `label` values, and `as` names under the chain directory. Example outputs:
-- `handoff/external-reference.md`
-- `handoff/local-context.md`
-- `handoff/implementation-strategy.md`
-- `handoff/final-handoff-plan.md`
-
-Use phases such as `Research`, `Local context`, and `Synthesis` so async status is readable. Prefer `{outputs.externalReference}`, `{outputs.localContext}`, and `{outputs.implementationStrategy}` in the synthesis task when those specific inputs are available; keep `{previous}` only when the whole parallel fan-in summary is the desired input.
-
-Do not write these artifacts into the repository unless I explicitly ask for persistent files.
-
-Role guidance:
-
-External reference researcher:
-- Study linked projects, docs, issues, examples, source code, or prompt guidance.
-- Identify the behavior, API, implementation files, constraints, and transferable ideas.
-- Conduct web research if needed. Use `web_search` if it is available; otherwise use whatever equivalent research capability is available.
-- Return source links, repo paths, key evidence, risks, and what matters for this implementation.
-
-Local explorer:
-- Read all files needed to fully understand the local issue, not just the first match.
-- Follow imports, callers, tests, fixtures, configuration, docs, and adjacent patterns until the local problem, solution space, and validation path are clear.
-- Return relevant file paths and line ranges, current architecture, constraints, tests, risks, and open questions.
-
-Implementation-strategy explorer, when used:
-- Compare the external evidence against the local architecture.
-- Propose the safest implementation shape, files likely to change, edge cases, validation commands, and decisions that need approval.
-- Stay review/planning-only unless I explicitly ask for implementation.
-
-Final synthesis explorer:
-- Read the parallel outputs and produce one concise handoff plan.
-- Include what the feature/change should do, what the external reference teaches, what the local codebase implies, the recommended approach, likely files to change, constraints, non-goals, validation, risks, and unresolved questions.
-- End with a compact implementation-ready meta-prompt for the next builder/architect.
-
-After the chain returns, synthesize the result for me with:
-- the recommended approach;
-- artifact paths;
-- the final meta-prompt;
-- any questions or assumptions that remain.
-
-Do not start implementation from this command unless I explicitly ask for it.

package/dist/extensions/pi-subagents/src/agents/task-aware-routing.ts

@@ -1,132 +0,0 @@
-/**
- * Pure task-aware advisory agent recommender.
- *
- * Given an already-discovered, effective agent set and the current capability
- * ceiling, deterministically selects at most one canonical agent to recommend
- * for a task, or returns recovery guidance when intent is unknown or no safe
- * candidate exists. This module is deliberately pure: it performs no
- * filesystem/discovery access, no alias/chains/executor/RPC/preflight/settings
- * access, no mutation, launch, scheduling, or persistence, and never writes to
- * params. Launching stays explicit: the caller must make a separate execution
- * call with the recommended canonical `agent.name`.
- */
-
-import type { AgentConfig, AgentSource } from "./agents.ts";
-import { agentHasWriteTools } from "./agent-memory.ts";
-import { classifyTaskMutationIntent } from "../runs/shared/task-intent.ts";
-import { isAgentAllowedByCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
-
-function resolveAgentRoutingRole(name: string, acceptanceRole: AgentConfig["acceptanceRole"]): "writer" | "read-only" | undefined {
-	if (acceptanceRole === "writer" || acceptanceRole === "read-only") return acceptanceRole;
-	if (/^(?:builder|developer|coder|implementer|develop)$/i.test(name)) return "writer";
-	if (/^(?:architect|commentator|explorer|researcher|recapper)$/i.test(name)) return "read-only";
-	return undefined;
-}
-
-/** Core tools that make an implementation agent able to write (matches agent-memory). */
-const WRITER_TOOLS = new Set(["edit", "write", "bash"]);
-
-/** Source precedence for deterministic ordering: project > user > package > builtin. */
-const AGENT_SOURCE_PRECEDENCE: Record<AgentSource, number> = { builtin: 0, package: 1, user: 2, project: 3 };
-
-export type TaskAwareAgentIntent = "implementation" | "read-only" | "unknown";
-
-export interface TaskAwareAgentRecommendationAgent {
-	/** Canonical runtime agent name accepted by execution; never an alias. */
-	name: string;
-	source: AgentSource;
-	role: "writer" | "read-only";
-	roleBasis: "declared" | "inferred";
-	reason: string;
-}
-
-export interface TaskAwareAgentRecommendation {
-	intent: TaskAwareAgentIntent;
-	agent?: TaskAwareAgentRecommendationAgent;
-	/** Recovery guidance when no safe recommendation exists (unknown intent or no candidate). */
-	next?: string;
-}
-
-/**
- * Recommend a canonical agent for a trimmed non-empty task, or `undefined` for
- * an empty/whitespace task (no-op). Never recommends disabled or
- * capability-disallowed agents, never guesses for unknown intent, and never
- * outputs an alias or a role-incompatible agent.
- */
-export function recommendTaskAwareAgent(input: {
-	task: string;
-	agents: AgentConfig[];
-	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
-}): TaskAwareAgentRecommendation | undefined {
-	const task = input.task.trim();
-	if (!task) return undefined;
-
-	const intent = classifyTaskMutationIntent("builder", task).kind;
-	if (intent === "unknown") {
-		return {
-			intent,
-			next: "Clarify whether the task is read-only analysis/review or implementation allowed to edit files.",
-		};
-	}
-
-	const candidates: TaskAwareAgentRecommendationAgent[] = [];
-	for (const agent of input.agents) {
-		if (agent.disabled) continue;
-		if (!isAgentAllowedByCapabilityCeiling(agent.name, input.capabilityCeiling)) continue;
-		const role = resolveAgentRoutingRole(agent.name, agent.acceptanceRole);
-		if (!role) continue;
-		const hasWriteTools = agentHasWriteTools(agent);
-		if (intent === "implementation") {
-			if (role !== "writer" || !hasWriteTools) continue;
-			const allowedTools = input.capabilityCeiling?.allowedTools;
-			if (allowedTools !== undefined && !allowedTools.some((tool) => WRITER_TOOLS.has(tool))) continue;
-		} else {
-			if (role !== "read-only" || hasWriteTools) continue;
-		}
-		const roleBasis = agent.acceptanceRole !== undefined ? "declared" : "inferred";
-		candidates.push({
-			name: agent.name,
-			source: agent.source,
-			role,
-			roleBasis,
-			reason: intent === "implementation"
-				? `${roleBasis} writer role with write tools`
-				: `${roleBasis} read-only role without known write tools`,
-		});
-	}
-
-	candidates.sort((a, b) => {
-		const sourceOrder = AGENT_SOURCE_PRECEDENCE[b.source] - AGENT_SOURCE_PRECEDENCE[a.source];
-		if (sourceOrder !== 0) return sourceOrder;
-		const declaredOrder = (a.roleBasis === "declared" ? 0 : 1) - (b.roleBasis === "declared" ? 0 : 1);
-		if (declaredOrder !== 0) return declaredOrder;
-		return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-	});
-
-	const agent = candidates[0];
-	if (!agent) {
-		return {
-			intent,
-			next: intent === "implementation"
-				? "No executable agent has a writer role with write tools for this task. Check the executable/restricted sections above or adjust the capability ceiling."
-				: "No executable agent has a read-only role without known write tools for this task. Check the executable/restricted sections above.",
-		};
-	}
-	return { intent, agent };
-}
-
-/** Text-only advisory lines; `undefined` (empty-task no-op) renders nothing. */
-export function formatTaskAwareAgentRecommendation(recommendation: TaskAwareAgentRecommendation | undefined): string[] {
-	if (!recommendation) return [];
-	const lines = ["Task-aware advisory routing:", `- Intent: ${recommendation.intent}`];
-	if (recommendation.agent) {
-		lines.push(`- Recommended: ${recommendation.agent.name} (${recommendation.agent.source})`);
-		lines.push(`- Reason: ${recommendation.agent.reason}`);
-		lines.push("- Advisory only: no subagent was launched. To proceed, explicitly call subagent with this canonical agent name and the task.");
-	} else {
-		lines.push("- Recommendation: none");
-		lines.push(`- Next: ${recommendation.next ?? "Refine the task wording and retry."}`);
-		lines.push("- Advisory only: no subagent was launched.");
-	}
-	return lines;
-}

package/dist/extensions/pi-subagents/src/extension/chain-validation.ts

@@ -1,181 +0,0 @@
-/**
- * Friendly chain parameter validation.
- *
- * The runtime (pi-ai) validates tool arguments against the TypeBox schema before
- * the tool's `execute` runs. When a chain step has an extra property, the model
- * receives a raw TypeBox message such as `chain.1: must not have additional
- * properties` — which does not name the offending property, list the allowed
- * ones, or show the expected shape. Agents then iteratively guess the format and
- * waste several turns before getting it right.
- *
- * `validateChainInput` runs from the tool's `prepareArguments` shim (and the RPC
- * bridge) *before* schema validation. It throws a rich, actionable error for the
- * common chain-shape failures, so the model sees which property is disallowed,
- * what is allowed, and a valid example — instead of a raw TypeBox diagnostic.
- *
- * Allowed property names and additional-property strictness are derived directly
- * from the schema objects in `schemas.ts` so this stays aligned with TypeBox.
- */
-
-import {
-	ChainItem,
-	ParallelTaskSchema,
-	DynamicParallelTemplateSchema,
-	DynamicExpandSchema,
-	DynamicCollectSchema,
-} from "./schemas.ts";
-
-type ObjectSchema = {
-	properties?: Record<string, unknown>;
-	additionalProperties?: unknown;
-};
-
-function allowedKeysOf(schema: ObjectSchema | undefined): string[] {
-	return schema?.properties ? Object.keys(schema.properties) : [];
-}
-
-const ExpandFromSchema = (DynamicExpandSchema.properties?.from ?? {}) as ObjectSchema;
-
-export const CHAIN_STEP_KEYS = allowedKeysOf(ChainItem);
-export const PARALLEL_TASK_KEYS = allowedKeysOf(ParallelTaskSchema);
-export const DYNAMIC_TEMPLATE_KEYS = allowedKeysOf(DynamicParallelTemplateSchema);
-export const EXPAND_KEYS = allowedKeysOf(DynamicExpandSchema);
-export const EXPAND_FROM_KEYS = allowedKeysOf(ExpandFromSchema);
-export const COLLECT_KEYS = allowedKeysOf(DynamicCollectSchema);
-
-const CHAIN_STEP_EXAMPLE = '{"agent": "builder", "task": "do X"} or {"checkpoint": "review", "message": "Approve before implementation?"}';
-const PARALLEL_TASK_EXAMPLE = '{"agent": "builder", "task": "do X"}';
-const DYNAMIC_TEMPLATE_EXAMPLE = '{"agent": "builder", "task": "Review {item.path}"}';
-const EXPAND_EXAMPLE = '{"from": {"output": "targets", "path": "/items"}, "maxItems": 4}';
-const EXPAND_FROM_EXAMPLE = '{"output": "targets", "path": "/items"}';
-const COLLECT_EXAMPLE = '{"as": "reviews"}';
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function disallowedKeys(value: Record<string, unknown>, allowed: readonly string[]): string[] {
-	return Object.keys(value).filter((key) => !allowed.includes(key));
-}
-
-function validateCheckpointShape(step: Record<string, unknown>, path: string): void {
-	if (step.checkpoint === undefined) return;
-	const allowed = new Set(["checkpoint", "message", "phase", "label"]);
-	const mixed = Object.keys(step).filter((key) => !allowed.has(key));
-	if (mixed.length > 0) {
-		throw new Error(`subagent ${path}: checkpoint steps cannot be mixed with child-launch properties ${quoteList(mixed)}.\n\nExample: {"checkpoint": "review", "message": "Approve before implementation?"}`);
-	}
-	if (typeof step.checkpoint !== "string" || !step.checkpoint.trim()) {
-		throw new Error(`subagent ${path}.checkpoint: expected a non-empty string.`);
-	}
-	if (step.message !== undefined && typeof step.message !== "string") {
-		throw new Error(`subagent ${path}.message: expected a string.`);
-	}
-}
-
-function typeName(value: unknown): string {
-	if (Array.isArray(value)) return "array";
-	return typeof value;
-}
-
-function quoteList(keys: string[]): string {
-	return keys.map((key) => `"${key}"`).join(", ");
-}
-
-function disallowedMessage(
-	path: string,
-	keys: string[],
-	allowed: readonly string[],
-	example?: string,
-): string {
-	const subject = keys.length === 1
-		? `property "${keys[0]}" is not allowed`
-		: `properties ${quoteList(keys)} are not allowed`;
-	const examplePart = example ? `\n\nExample: ${example}` : "";
-	return `subagent ${path}: ${subject}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`;
-}
-
-function expectObject(value: unknown, path: string, allowed: readonly string[], example?: string): asserts value is Record<string, unknown> {
-	if (!isPlainObject(value)) {
-		const examplePart = example ? `\n\nExample: ${example}` : "";
-		throw new Error(
-			`subagent ${path}: expected an object, received ${typeName(value)}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`,
-		);
-	}
-}
-
-function checkNoExtraKeys(
-	value: Record<string, unknown>,
-	path: string,
-	schema: ObjectSchema,
-	allowed: readonly string[],
-	example?: string,
-): void {
-	if (schema.additionalProperties !== false) return;
-	const extra = disallowedKeys(value, allowed);
-	if (extra.length > 0) {
-		throw new Error(disallowedMessage(path, extra, allowed, example));
-	}
-}
-
-/**
- * Validates the `chain` array on a raw subagent tool-call argument object and
- * throws a friendly, actionable error when a chain step (or a nested
- * `parallel`/`expand`/`collect` object) has a disallowed property or wrong shape.
- *
- * No-op when `chain` is absent or not an array, so management/control/single/
- * parallel calls are unaffected.
- */
-export function validateChainInput(args: unknown): void {
-	if (!isPlainObject(args)) return;
-	const chain = (args as Record<string, unknown>).chain;
-	if (!Array.isArray(chain)) return;
-
-	chain.forEach((step, index) => {
-		const stepPath = `chain step validation failed at chain[${index}]`;
-		expectObject(step, stepPath, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
-		checkNoExtraKeys(step, stepPath, ChainItem, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
-		validateCheckpointShape(step, stepPath);
-
-		if (step.expand !== undefined) {
-			const expandPath = `${stepPath}.expand`;
-			expectObject(step.expand, expandPath, EXPAND_KEYS, EXPAND_EXAMPLE);
-			checkNoExtraKeys(step.expand, expandPath, DynamicExpandSchema, EXPAND_KEYS, EXPAND_EXAMPLE);
-
-			const from = (step.expand as Record<string, unknown>).from;
-			if (from !== undefined) {
-				const fromPath = `${expandPath}.from`;
-				expectObject(from, fromPath, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
-				checkNoExtraKeys(from, fromPath, ExpandFromSchema, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
-			}
-		}
-
-		if (step.collect !== undefined) {
-			const collectPath = `${stepPath}.collect`;
-			expectObject(step.collect, collectPath, COLLECT_KEYS, COLLECT_EXAMPLE);
-			checkNoExtraKeys(step.collect, collectPath, DynamicCollectSchema, COLLECT_KEYS, COLLECT_EXAMPLE);
-		}
-
-		const parallel = step.parallel;
-		if (parallel === undefined) return;
-
-		if (Array.isArray(parallel)) {
-			parallel.forEach((task, pIndex) => {
-				const taskPath = `${stepPath}.parallel[${pIndex}]`;
-				expectObject(task, taskPath, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
-				checkNoExtraKeys(task, taskPath, ParallelTaskSchema, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
-			});
-			return;
-		}
-
-		if (isPlainObject(parallel)) {
-			const templatePath = `${stepPath}.parallel (dynamic fanout template)`;
-			checkNoExtraKeys(parallel, templatePath, DynamicParallelTemplateSchema, DYNAMIC_TEMPLATE_KEYS, DYNAMIC_TEMPLATE_EXAMPLE);
-			return;
-		}
-
-		throw new Error(
-			`subagent ${stepPath}.parallel: expected an array of task objects or a dynamic fanout template object, received ${typeName(parallel)}.\n\nExample static: [${PARALLEL_TASK_EXAMPLE}]\nExample dynamic: ${DYNAMIC_TEMPLATE_EXAMPLE}`,
-		);
-	});
-}