@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/src/runs/foreground/clarification-draft.ts

@@ -0,0 +1,92 @@
+import type { ResolvedStepBehavior } from "../../shared/types/workflow.ts";
+import type { BehaviorOverride, EditMode } from "./clarify-contracts.ts";
+
+/** Owns replace-only preview values and downstream output/read dependencies. */
+function resolveList(value: readonly string[] | false): string[] | false {
+  return value === false ? false : [...value];
+}
+export class ClarificationDraft {
+  private readonly templateValues: string[];
+  get templates(): readonly string[] {
+    return this.templateValues;
+  }
+  private readonly behaviors: readonly ResolvedStepBehavior[];
+  private readonly overrides = new Map<number, BehaviorOverride>();
+  constructor(templates: readonly string[], behaviors: readonly ResolvedStepBehavior[]) {
+    this.templateValues = [...templates];
+    this.behaviors = behaviors;
+  }
+  behavior(index: number): ResolvedStepBehavior {
+    const base = this.behaviors.at(index);
+    if (!base) {
+      throw new Error(`Missing clarification behavior for step ${index}.`);
+    }
+    const override = this.overrides.get(index);
+    return {
+      ...base,
+      ...override,
+      reads: resolveList(override?.reads ?? base.reads),
+      skills: resolveList(override?.skills ?? base.skills),
+    };
+  }
+  override(index: number): BehaviorOverride | undefined {
+    return this.overrides.get(index);
+  }
+  update(index: number, override: BehaviorOverride): void {
+    this.overrides.set(index, { ...this.overrides.get(index), ...override });
+  }
+  toggleProgress(): void {
+    const enabled = this.behaviors.some((_, index) => this.behavior(index).progress);
+    this.behaviors.forEach((_, index) => {
+      this.update(index, { progress: !enabled });
+    });
+  }
+  save(index: number, field: EditMode, text: string): void {
+    if (field === "template") {
+      const lines = (this.templateValues[index] ?? "").split("\n");
+      lines[0] = text;
+      this.templateValues[index] = lines.join("\n");
+      return;
+    }
+    if (field === "reads") {
+      const reads = text
+        .trim()
+        .split(",")
+        .map((file) => file.trim())
+        .filter((file) => file.length > 0);
+      this.update(index, { reads: reads.length > 0 ? reads : false });
+      return;
+    }
+    if (field === "output") {
+      this.saveOutput(index, text.trim());
+    }
+  }
+  private saveOutput(index: number, text: string): void {
+    const previous = this.behavior(index).output;
+    const output = text.length === 0 ? false : text;
+    this.update(index, { output });
+    if (
+      typeof previous === "string" &&
+      previous.length > 0 &&
+      typeof output === "string" &&
+      previous !== output
+    ) {
+      this.propagateOutput(index, previous, output);
+    }
+  }
+  private propagateOutput(index: number, previous: string, output: string): void {
+    for (let next = index + 1; next < this.behaviors.length; next++) {
+      const reads = this.behavior(next).reads;
+      if (reads === false) {
+        continue;
+      }
+      const found = reads.indexOf(previous);
+      if (found < 0) {
+        continue;
+      }
+      const updated = [...reads];
+      updated[found] = output;
+      this.update(next, { reads: updated });
+    }
+  }
+}

package/src/runs/foreground/clarify-contracts.ts

@@ -0,0 +1,33 @@
+import type { AgentConfig, ModelInfo } from "../../shared/types/config.ts";
+import type { ResolvedStepBehavior } from "../../shared/types/workflow.ts";
+export interface BehaviorOverride {
+  readonly output?: string | false;
+  readonly reads?: readonly string[] | false;
+  readonly progress?: boolean;
+  readonly model?: string;
+  readonly skills?: readonly string[] | false;
+}
+export interface ChainClarifyResult {
+  readonly confirmed: boolean;
+  readonly templates: readonly string[];
+  readonly behaviorOverrides: readonly (BehaviorOverride | undefined)[];
+  readonly runInBackground?: boolean;
+}
+export type ClarifyMode = "single" | "parallel" | "chain";
+export type EditMode = "template" | "output" | "reads" | "model" | "thinking" | "skills";
+interface SkillChoice {
+  readonly name: string;
+  readonly source: string;
+  readonly description?: string;
+}
+export interface ChainClarifyOptions {
+  readonly agentConfigs: readonly AgentConfig[];
+  readonly templates: readonly string[];
+  readonly originalTask: string;
+  readonly chainDir?: string;
+  readonly resolvedBehaviors: readonly ResolvedStepBehavior[];
+  readonly availableModels: readonly ModelInfo[];
+  readonly preferredProvider?: string;
+  readonly availableSkills: readonly SkillChoice[];
+  readonly mode?: ClarifyMode;
+}

package/src/runs/foreground/clarify-invocation.ts

@@ -1,77 +1,204 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AgentConfig } from "../../agents/agents.ts";
+import type { AgentConfig } from "../../shared/types/config.ts";
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
 import { validateForkContextModelPolicy } from "../../shared/agent-context-policy.ts";
 import { toModelInfo } from "../../shared/model-info.ts";
-import { createChainDir, isDynamicParallelStep, isParallelStep, removeChainDir, resolveChainTemplates, resolveStepBehavior, type SequentialStep } from "../../shared/settings.ts";
+import {
+  createChainDir,
+  isDynamicParallelStep,
+  isParallelStep,
+  removeChainDir,
+  resolveChainTemplates,
+  resolveStepBehavior,
+  type SequentialStep,
+} from "../../shared/settings.ts";
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
 import { normalizeSingleOutputOverride } from "../shared/single-output.ts";
 import { ChainClarifyComponent, type ChainClarifyResult } from "./chain-clarify.ts";
-import type { SubagentParamsLike } from "./subagent-params.ts";
+import type { SubagentParamsLike, TaskParam } from "./subagent-params.ts";
+
+type ClarifyStep = Omit<TaskParam, "task"> & { readonly task?: string };
+function previewSteps(params: SubagentParamsLike): readonly ClarifyStep[] {
+  if (params.chain) {
+    return params.chain.map((step) => {
+      if (isParallelStep(step) || isDynamicParallelStep(step)) {
+        throw new Error("Parallel groups cannot use the sequential preview.");
+      }
+      return step;
+    });
+  }
+  if (params.tasks) {
+    return params.tasks;
+  }
+  if (params.agent === undefined) {
+    throw new Error("Clarification requires an agent.");
+  }
+  return [{ ...params, agent: params.agent }];
+}
+function applyPreview(step: ClarifyStep, result: ChainClarifyResult, index: number): ClarifyStep {
+  const override = result.behaviorOverrides[index];
+  const updated = { ...step, task: result.templates[index] ?? "" };
+  return Object.assign(updated, overrideFields(override));
+}
+function overrideFields(
+  override: ChainClarifyResult["behaviorOverrides"][number],
+): Partial<ClarifyStep> {
+  if (!override) {
+    return {};
+  }
+  return {
+    ...(override.model !== undefined && override.model.length > 0 ? { model: override.model } : {}),
+    ...(override.output !== undefined ? { output: override.output } : {}),
+    ...(override.reads !== undefined
+      ? { reads: override.reads === false ? false : [...override.reads] }
+      : {}),
+    ...(override.progress !== undefined ? { progress: override.progress } : {}),
+    ...(override.skills !== undefined
+      ? { skill: override.skills === false ? false : [...override.skills] }
+      : {}),
+  };
+}
+function applyInvocationPreview(
+  params: SubagentParamsLike,
+  result: ChainClarifyResult,
+): SubagentParamsLike {
+  const updated = previewSteps(params).map((step, index) => applyPreview(step, result, index));
+  const confirmed = { clarify: false, async: result.runInBackground === true };
+  if (params.chain) {
+    return { ...params, chain: updated.map(toSequentialStep), ...confirmed };
+  }
+  if (params.tasks) {
+    return {
+      ...params,
+      tasks: updated.map((step) => ({ ...step, task: step.task ?? "" })),
+      ...confirmed,
+    };
+  }
+  return { ...params, ...updated[0], ...confirmed };
+}
 
 /** Preview changes launch input only; waiting and background runs share the same owner. */
+function toSequentialStep(step: ClarifyStep): SequentialStep {
+  return {
+    ...step,
+    output: step.output === true ? undefined : step.output,
+    reads: step.reads === true ? undefined : step.reads,
+    skill: step.skill === true ? undefined : step.skill,
+  };
+}
+function sequentialTemplates(params: SubagentParamsLike, steps: readonly ClarifyStep[]): string[] {
+  if (!params.chain) {
+    return steps.map((step) => step.task ?? "");
+  }
+  return resolveChainTemplates(params.chain).map((template) => {
+    if (typeof template !== "string") {
+      throw new Error("Sequential preview received parallel templates.");
+    }
+    return template;
+  });
+}
+function preparePreview(params: SubagentParamsLike, agents: readonly AgentConfig[]) {
+  const steps = previewSteps(params);
+  const profiles = steps.map((step) => {
+    const profile = agents.find((agent) => agent.name === step.agent);
+    if (!profile) {
+      throw new Error(`Unknown agent: ${step.agent}`);
+    }
+    return profile;
+  });
+  let mode: "single" | "parallel" | "chain" = "single";
+  if (params.chain) {
+    mode = "chain";
+  } else if (params.tasks) {
+    mode = "parallel";
+  }
+  const templates = sequentialTemplates(params, steps);
+  const chainSkills = mode === "chain" ? (normalizeSkillInput(params.skill) ?? []) : [];
+  const behaviors = steps.map((step, index) => {
+    const profile = profiles.at(index);
+    if (!profile) {
+      throw new Error(`Missing profile for clarification step ${index}.`);
+    }
+    return resolveStepBehavior(
+      profile,
+      {
+        output: normalizeSingleOutputOverride(step.output, profile.output),
+        outputMode: step.outputMode,
+        reads: step.reads === true ? undefined : step.reads,
+        progress: step.progress,
+        skills: normalizeSkillInput(step.skill),
+        model: step.model,
+      },
+      chainSkills,
+    );
+  });
+  return {
+    mode,
+    profiles,
+    templates,
+    behaviors,
+    originalTask: params.task ?? (mode === "chain" ? (templates[0] ?? "") : ""),
+  };
+}
+export function canClarifyInvocation(params: SubagentParamsLike, ctx: ExtensionContext): boolean {
+  return (
+    params.clarify === true &&
+    ctx.hasUI &&
+    ctx.mode === "tui" &&
+    params.chain?.some((step) => isParallelStep(step) || isDynamicParallelStep(step)) !== true
+  );
+}
 export async function clarifyInvocation(input: {
-	params: SubagentParamsLike;
-	agents: AgentConfig[];
-	ctx: ExtensionContext;
-	cwd: string;
-	runId: string;
+  readonly params: SubagentParamsLike;
+  readonly agents: readonly AgentConfig[];
+  readonly ctx: ExtensionContext;
+  readonly cwd: string;
+  readonly runId: string;
 }): Promise<SubagentParamsLike | undefined> {
-	const { params, agents, ctx, cwd, runId } = input;
-	if (params.clarify !== true || !ctx.hasUI) return params;
-	if (params.chain?.some((step) => isParallelStep(step) || isDynamicParallelStep(step))) return params;
-	const mode = params.chain ? "chain" : params.tasks ? "parallel" : "single";
-	const steps = params.chain as SequentialStep[] | undefined ?? params.tasks ?? [{ ...params, agent: params.agent!, reads: undefined }];
-	const profiles = steps.map((step) => {
-		const profile = agents.find((agent) => agent.name === step.agent);
-		if (!profile) throw new Error(`Unknown agent: ${step.agent}`);
-		return profile;
-	});
-	const templates = params.chain ? resolveChainTemplates(params.chain) as string[] : steps.map((step) => step.task ?? "");
-	const originalTask = params.task ?? (mode === "chain" ? templates[0] ?? "" : "");
-	const chainSkills = mode === "chain" ? normalizeSkillInput(params.skill) ?? [] : [];
-	const behaviors = profiles.map((profile, index) => {
-		const step = steps[index]!;
-		return resolveStepBehavior(profile, {
-			output: normalizeSingleOutputOverride(step.output, profile.output),
-			outputMode: step.outputMode,
-			reads: step.reads === true ? undefined : step.reads,
-			progress: step.progress,
-			skills: normalizeSkillInput(step.skill),
-			model: step.model,
-		}, chainSkills);
-	});
-	const models = ctx.modelRegistry.getAvailable().map(toModelInfo);
-	const skills = discoverAvailableSkills(cwd, { projectTrusted: ctx.isProjectTrusted() });
-	const chainDir = mode === "chain" ? createChainDir(runId, params.chainDir, cwd) : undefined;
-	let confirmed = false;
-	try {
-		const result = await ctx.ui.custom<ChainClarifyResult>((tui, theme, _kb, done) => new ChainClarifyComponent(
-			tui, theme, profiles, templates, originalTask, chainDir, behaviors, models, ctx.model?.provider, skills, done, mode,
-		), { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } });
-		if (!result?.confirmed) return undefined;
-		const updated = steps.map((step, index) => {
-			const override = result.behaviorOverrides[index];
-			return {
-				...step, task: result.templates[index]!,
-				...(override?.model ? { model: override.model } : {}),
-				...(override?.output !== undefined ? { output: override.output } : {}),
-				...(override?.reads !== undefined ? { reads: override.reads } : {}),
-				...(override?.progress !== undefined ? { progress: override.progress } : {}),
-				...(override?.skills !== undefined ? { skill: override.skills } : {}),
-			};
-		});
-		const next: SubagentParamsLike = {
-			...params,
-			...(mode === "chain" ? { chain: updated as SequentialStep[] }
-				: mode === "parallel" ? { tasks: updated } : updated[0]),
-			clarify: false, async: result.runInBackground === true,
-		};
-		const error = validateForkContextModelPolicy(next, agents, (model) => resolveModelCandidate(model, models, ctx.model?.provider));
-		if (error) throw new Error(error);
-		confirmed = true;
-		return next;
-	} finally {
-		if (!confirmed && chainDir) removeChainDir(chainDir);
-	}
+  const { params, agents, ctx, cwd, runId } = input;
+  if (!canClarifyInvocation(params, ctx)) {
+    return params;
+  }
+  const preview = preparePreview(params, agents);
+  const models = ctx.modelRegistry.getAvailable().map(toModelInfo);
+  const skills = discoverAvailableSkills(cwd, { projectTrusted: ctx.isProjectTrusted() });
+  const chainDir =
+    preview.mode === "chain" ? createChainDir(runId, params.chainDir, cwd) : undefined;
+  let confirmed = false;
+  try {
+    const result = await ctx.ui.custom<ChainClarifyResult>(
+      (tui, theme, _kb, done) =>
+        new ChainClarifyComponent(
+          tui,
+          theme,
+          {
+            ...preview,
+            agentConfigs: preview.profiles,
+            chainDir,
+            resolvedBehaviors: preview.behaviors,
+            availableModels: models,
+            preferredProvider: ctx.model?.provider,
+            availableSkills: skills,
+          },
+          done,
+        ),
+      { overlay: true, overlayOptions: { anchor: "center", width: 84, maxHeight: "80%" } },
+    );
+    if (!result.confirmed) {
+      return;
+    }
+    const next = applyInvocationPreview(params, result);
+    const error = validateForkContextModelPolicy(next, agents, (model) =>
+      resolveModelCandidate(model, models, ctx.model?.provider),
+    );
+    if (error !== undefined && error.length > 0) {
+      throw new Error(error);
+    }
+    confirmed = true;
+    return next;
+  } finally {
+    if (!confirmed && chainDir !== undefined && chainDir.length > 0) {
+      removeChainDir(chainDir);
+    }
+  }
 }

package/src/runs/foreground/clarify-text-editor.ts

@@ -0,0 +1,229 @@
+import { matchesKey, visibleWidth } from "@earendil-works/pi-tui";
+
+interface WrappedText {
+  readonly lines: readonly string[];
+  readonly starts: readonly number[];
+}
+function wrapSegment(segment: string, width: number): WrappedText {
+  const lines: string[] = [],
+    starts: number[] = [];
+  let start = 0,
+    offset = 0,
+    columns = 0;
+  for (const char of segment) {
+    const charWidth = visibleWidth(char);
+    if (columns > 0 && columns + charWidth > width) {
+      lines.push(segment.slice(start, offset));
+      starts.push(start);
+      start = offset;
+      columns = 0;
+    }
+    offset += char.length;
+    columns += charWidth;
+  }
+  lines.push(segment.slice(start));
+  starts.push(start);
+  return { lines, starts };
+}
+function wrapText(text: string, width: number): WrappedText {
+  if (width <= 0) {
+    return { lines: [text], starts: [0] };
+  }
+  const lines: string[] = [],
+    starts: number[] = [];
+  let offset = 0;
+  for (const segment of text.split("\n")) {
+    const wrapped = wrapSegment(segment, width);
+    lines.push(...wrapped.lines);
+    starts.push(...wrapped.starts.map((start) => start + offset));
+    offset += segment.length + 1;
+  }
+  if (!text.endsWith("\n") && text.length > 0 && visibleWidth(lines.at(-1) ?? "") === width) {
+    starts.push(text.length);
+    lines.push("");
+  }
+  return { lines, starts };
+}
+function cursorPosition(
+  cursor: number,
+  starts: readonly number[],
+): { readonly line: number; readonly col: number } {
+  const line = Math.max(
+    0,
+    starts.findLastIndex((start) => cursor >= start),
+  );
+  return { line, col: cursor - (starts[line] ?? 0) };
+}
+function isWordChar(char: string): boolean {
+  return /[A-Za-z0-9_]/.test(char);
+}
+function wordBackward(buffer: string, cursor: number): number {
+  let position = cursor;
+  while (position > 0 && !isWordChar(buffer[position - 1] ?? "")) {
+    position--;
+  }
+  while (position > 0 && isWordChar(buffer[position - 1] ?? "")) {
+    position--;
+  }
+  return position;
+}
+function wordForward(buffer: string, cursor: number): number {
+  let position = cursor;
+  while (position < buffer.length && isWordChar(buffer[position] ?? "")) {
+    position++;
+  }
+  while (position < buffer.length && !isWordChar(buffer[position] ?? "")) {
+    position++;
+  }
+  return position;
+}
+function insertText(data: string): string | undefined {
+  const text =
+    data
+      .split("\x1b[200~")
+      .join("")
+      .split("\x1b[201~")
+      .join("")
+      .replace(/\r\n?/g, "\n")
+      .split("\n")[0]
+      ?.replace(/\t/g, "    ") ?? "";
+  if (text.length === 0 || Array.from(text).some((char) => char.charCodeAt(0) < 32)) {
+    return;
+  }
+  return text;
+}
+/** Owns the single-line draft and its viewport; the caller decides commit versus discard. */
+export class ClarifyTextEditor {
+  private buffer = "";
+  private cursor = 0;
+  private viewportOffset = 0;
+  setText(text: string): void {
+    this.buffer = text;
+    this.cursor = 0;
+    this.viewportOffset = 0;
+  }
+  getText(): string {
+    return this.buffer;
+  }
+  handleInput(data: string, width: number): void {
+    if (matchesKey(data, "return") || matchesKey(data, "tab")) {
+      return;
+    }
+    if (this.moveCursor(data, width) || this.deleteText(data)) {
+      return;
+    }
+    const text = insertText(data);
+    if (text !== undefined) {
+      this.buffer = this.buffer.slice(0, this.cursor) + text + this.buffer.slice(this.cursor);
+      this.cursor += text.length;
+    }
+  }
+  private moveCursor(data: string, width: number): boolean {
+    if (matchesKey(data, "alt+left") || matchesKey(data, "ctrl+left")) {
+      this.cursor = wordBackward(this.buffer, this.cursor);
+      return true;
+    }
+    if (matchesKey(data, "alt+right") || matchesKey(data, "ctrl+right")) {
+      this.cursor = wordForward(this.buffer, this.cursor);
+      return true;
+    }
+    if (matchesKey(data, "left")) {
+      this.cursor = Math.max(0, this.cursor - 1);
+      return true;
+    }
+    if (matchesKey(data, "right")) {
+      this.cursor = Math.min(this.buffer.length, this.cursor + 1);
+      return true;
+    }
+    if (matchesKey(data, "ctrl+home")) {
+      this.cursor = 0;
+      return true;
+    }
+    if (matchesKey(data, "ctrl+end")) {
+      this.cursor = this.buffer.length;
+      return true;
+    }
+    return this.moveVisualCursor(data, width);
+  }
+  private moveVisualCursor(data: string, width: number): boolean {
+    const { lines, starts } = wrapText(this.buffer, width);
+    const position = cursorPosition(this.cursor, starts);
+    if (matchesKey(data, "home")) {
+      this.cursor = starts[position.line] ?? 0;
+      return true;
+    }
+    if (matchesKey(data, "end")) {
+      this.cursor = (starts[position.line] ?? 0) + (lines[position.line]?.length ?? 0);
+      return true;
+    }
+    const delta = verticalDelta(data);
+    if (delta === 0) {
+      return false;
+    }
+    const line = Math.max(0, Math.min(lines.length - 1, position.line + delta));
+    this.cursor = visualCursor(line, position.col, { lines, starts });
+    return true;
+  }
+  private deleteText(data: string): boolean {
+    if (matchesKey(data, "alt+backspace")) {
+      const target = wordBackward(this.buffer, this.cursor);
+      this.buffer = this.buffer.slice(0, target) + this.buffer.slice(this.cursor);
+      this.cursor = target;
+      return true;
+    }
+    if (matchesKey(data, "backspace")) {
+      if (this.cursor > 0) {
+        this.buffer = this.buffer.slice(0, this.cursor - 1) + this.buffer.slice(this.cursor);
+        this.cursor--;
+      }
+      return true;
+    }
+    if (matchesKey(data, "delete")) {
+      this.buffer = this.buffer.slice(0, this.cursor) + this.buffer.slice(this.cursor + 1);
+      return true;
+    }
+    return false;
+  }
+  render(
+    width: number,
+    height: number,
+  ): { readonly lines: readonly string[]; readonly scrollInfo: string } {
+    const { lines, starts } = wrapText(this.buffer, width);
+    const position = cursorPosition(this.cursor, starts);
+    if (position.line < this.viewportOffset) {
+      this.viewportOffset = position.line;
+    }
+    if (position.line >= this.viewportOffset + height) {
+      this.viewportOffset = Math.max(0, position.line - height + 1);
+    }
+    const rendered = Array.from({ length: height }, (_, index) => {
+      const line = this.viewportOffset + index;
+      const text = lines[line] ?? "";
+      if (line !== position.line) {
+        return text;
+      }
+      return `${text.slice(0, position.col)}\x1b[7m${text[position.col] ?? " "}\x1b[27m${text.slice(position.col + 1)}`;
+    });
+    const below = lines.length - this.viewportOffset - height;
+    const scrollInfo = `${this.viewportOffset > 0 ? "↑" : ""}${below > 0 ? `↓ ${below}+` : ""}`;
+    return { lines: rendered, scrollInfo };
+  }
+}
+function visualCursor(line: number, column: number, wrapped: WrappedText): number {
+  return (wrapped.starts[line] ?? 0) + Math.min(column, wrapped.lines[line]?.length ?? 0);
+}
+function verticalDelta(data: string): number {
+  if (matchesKey(data, "up")) {
+    return -1;
+  }
+  if (matchesKey(data, "down")) {
+    return 1;
+  }
+  if (matchesKey(data, "shift+up") || matchesKey(data, "pageUp")) {
+    return -12;
+  }
+  if (matchesKey(data, "shift+down") || matchesKey(data, "pageDown")) {
+    return 12;
+  }
+  return 0;
+}