surgent 0.7.0-alpha.0

package/src/subagent/subsession.ts

@@ -0,0 +1,266 @@
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+import {
+  createErrorResult,
+  createSubsessionBridge,
+  formatToolUse,
+  getLastAssistantOutput,
+} from "./helpers.js";
+import { validateBuiltInOutput } from "./validation.js";
+import {
+  findSubsession,
+  findSubsessionFile,
+  loadSubsessionOutput,
+  resolveRuntime,
+  saveSubsession,
+} from "./storage.js";
+import type {
+  CreateSubsessionParams,
+  ExecuteTurnRequest,
+  RuntimeConfig,
+  Subsession,
+  SubsessionRequest,
+  SubsessionResult,
+  SubsessionSnapshot,
+} from "./types.js";
+import { getPiPath } from "../utils.js";
+
+const DISALLOWED_TOOLS = new Set(["subagent", "call_mcp_tool", "list_mcp_tools"]);
+
+async function executeTurn(request: ExecuteTurnRequest): Promise<SubsessionResult> {
+  const snapshot: SubsessionSnapshot = {
+    id: request.session.sessionId,
+    status: "running",
+    toolsUsed: [],
+    usage: request.usage,
+  };
+  const toolCounts: Record<string, number> = {};
+  let aborted = false;
+  let errorMessage = "";
+  let lastMessage = "";
+  let stoppedWithError = false;
+
+  request.onSnapshot?.(snapshot);
+  const unsubscribe = request.session.subscribe((event) => {
+    if (event.type !== "message_end" || event.message.role !== "assistant") return;
+
+    const message = event.message;
+    snapshot.usage.input += message.usage?.input ?? 0;
+    snapshot.usage.output += message.usage?.output ?? 0;
+    snapshot.usage.cost += message.usage?.cost.total ?? 0;
+    snapshot.contextUsage = request.session.getContextUsage();
+
+    if (message.stopReason === "aborted") {
+      aborted = true;
+    } else if (message.stopReason === "error") {
+      stoppedWithError = true;
+      errorMessage ||= message.errorMessage || "Subsession failed";
+    }
+
+    for (const contentPart of message.content) {
+      if (contentPart.type === "text") {
+        lastMessage = contentPart.text;
+        continue;
+      }
+      if (contentPart.type !== "toolCall") continue;
+
+      const toolCount = (toolCounts[contentPart.name] ?? 0) + 1;
+      toolCounts[contentPart.name] = toolCount;
+      snapshot.usage.toolCalls += 1;
+      snapshot.toolsUsed.push(formatToolUse(contentPart.name, contentPart.arguments));
+    }
+
+    request.onSnapshot?.(snapshot);
+  });
+
+  const abortTurn = () => {
+    aborted = true;
+    void request.session.abort().catch(() => undefined);
+  };
+
+  try {
+    if (request.signal?.aborted) {
+      abortTurn();
+    } else {
+      request.signal?.addEventListener("abort", abortTurn, { once: true });
+      await request.session.prompt(request.input);
+    }
+  } catch (error) {
+    errorMessage = error instanceof Error ? error.message : String(error);
+  } finally {
+    request.signal?.removeEventListener("abort", abortTurn);
+    unsubscribe();
+  }
+
+  const output = lastMessage || getLastAssistantOutput(request.session);
+  const errorOutput = errorMessage || output || "Subsession failed";
+  const status = aborted ? "aborted" : stoppedWithError || errorMessage ? "error" : "done";
+
+  snapshot.status = status;
+  request.onSnapshot?.(snapshot);
+
+  return {
+    id: request.session.sessionId,
+    status,
+    output: status === "error" ? errorOutput : output,
+    usage: snapshot.usage,
+    toolCounts,
+  };
+}
+
+async function openSessionManager(request: SubsessionRequest): Promise<SessionManager> {
+  if (request.label === "subagent") {
+    return SessionManager.inMemory(request.ctx.cwd);
+  }
+
+  const subsessionsDir = getPiPath("subsessionsDir", request.ctx.cwd);
+  if (!request.id) {
+    const parentSession = request.ctx.sessionManager.getSessionFile();
+    return SessionManager.create(request.ctx.cwd, subsessionsDir, { parentSession });
+  }
+
+  const subsessionFile = await findSubsessionFile(request.ctx.cwd, request.id);
+  if (!subsessionFile) {
+    throw new Error(`Subsession file not found: ${request.id}`);
+  }
+
+  return SessionManager.open(subsessionFile.path, subsessionFile.dir, request.ctx.cwd);
+}
+
+async function createSdkSession(
+  request: SubsessionRequest,
+  runtime: RuntimeConfig,
+): Promise<AgentSession> {
+  const sessionManager = await openSessionManager(request);
+  const modelId = runtime.meta.model;
+  const model = modelId
+    ? request.ctx.modelRegistry.find(
+        modelId.slice(0, modelId.indexOf("/")),
+        modelId.slice(modelId.indexOf("/") + 1),
+      )
+    : request.ctx.model;
+  if (modelId && !model) {
+    throw new Error(`Unknown model "${modelId}" in agent config`);
+  }
+
+  const resourceLoader = new DefaultResourceLoader({
+    cwd: request.ctx.cwd,
+    agentDir: getAgentDir(),
+    noExtensions: true,
+    systemPromptOverride: () => runtime.systemPrompt,
+    extensionFactories: [
+      createSubsessionBridge(request.ctx, runtime.meta, sessionManager.getSessionId()),
+    ],
+  });
+  await resourceLoader.reload();
+
+  const { session } = await createAgentSession({
+    cwd: request.ctx.cwd,
+    model,
+    thinkingLevel:
+      runtime.meta.thinking_level ?? (request.id ? undefined : request.ctx.thinkingLevel),
+    resourceLoader,
+    sessionManager,
+  });
+
+  const availableTools = session.getAllTools().map((tool) => tool.name);
+  const activeTools = runtime.meta.tools ?? availableTools;
+  session.setActiveToolsByName(activeTools.filter((name) => !DISALLOWED_TOOLS.has(name)));
+  return session;
+}
+
+async function createSubsession(params: CreateSubsessionParams): Promise<Subsession> {
+  const { cwd, onSnapshot, session, ...rest } = params;
+  const subsession: Subsession = {
+    ...rest,
+    async exec(input: string, signal?: AbortSignal) {
+      if (!session) {
+        subsession.result = createErrorResult("Subsession unavailable");
+        return;
+      }
+
+      let validationError: string | undefined;
+      const request = { session, input, signal, onSnapshot, usage: subsession.result.usage };
+
+      for (let attempt = 0; attempt < 2; attempt++) {
+        if (attempt === 1) {
+          request.input = `Output failed validation: ${validationError}\nReturn only corrected output required by <output_contract>.`;
+        }
+
+        subsession.result = await executeTurn(request);
+        if (!subsession.runtime.builtIn || subsession.result.status !== "done") {
+          validationError = undefined;
+          break;
+        }
+
+        validationError = validateBuiltInOutput(
+          subsession.runtime.agent,
+          subsession.result.output,
+          input,
+        );
+        if (!validationError) break;
+      }
+
+      if (validationError) {
+        subsession.result.status = "error";
+        subsession.result.output = `Output validation failed: ${validationError}`;
+      }
+
+      await saveSubsession(cwd, subsession);
+    },
+    async dispose() {
+      session?.dispose();
+    },
+  };
+
+  await saveSubsession(cwd, subsession);
+  return subsession;
+}
+
+export async function openSubsession(request: SubsessionRequest): Promise<Subsession> {
+  const pid = request.ctx.sessionManager.getSessionId();
+  const existing =
+    request.label !== "subagent" ? await findSubsession(request.ctx.cwd, request.id, pid) : null;
+  const agentName = existing?.agent ?? request.agent;
+  const runtime = await resolveRuntime(request.ctx.cwd, agentName);
+
+  const params: CreateSubsessionParams = {
+    cwd: request.ctx.cwd,
+    label: request.label,
+    pid,
+    title: "Untitled",
+    result: {
+      status: "done",
+      output: "",
+      usage: { input: 0, output: 0, toolCalls: 0, cost: 0 },
+      toolCounts: {},
+    },
+    runtime,
+    onSnapshot: request.onSnapshot,
+  };
+
+  try {
+    if (!existing && request.id) {
+      throw Error(`Subsession not found: ${request.id}`);
+    }
+    params.session = await createSdkSession(request, runtime);
+    if (existing && request.id) {
+      params.title = existing.title;
+      params.result.id = request.id;
+      params.result.usage = existing.usage;
+      params.result.output = await loadSubsessionOutput(request.ctx.cwd, request.id);
+    }
+  } catch (error) {
+    params.result = createErrorResult(error instanceof Error ? error.message : String(error));
+    if (params.session && !params.result.id) {
+      params.result.id = params.session.sessionId;
+    }
+  }
+
+  return createSubsession(params);
+}

package/src/subagent/types.ts

@@ -0,0 +1,83 @@
+import type { AgentSession, ContextUsage, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentMeta } from "../agent/types.js";
+
+export type SubsessionStatus = "done" | "aborted" | "error";
+export type SubsessionLabel = "plan" | "subagent";
+
+export interface SubsessionUsage {
+  input: number;
+  output: number;
+  toolCalls: number;
+  cost: number;
+}
+
+export interface SubsessionSnapshot {
+  id: string;
+  status: "running" | SubsessionStatus;
+  toolsUsed: string[];
+  usage: SubsessionUsage;
+  contextUsage?: ContextUsage;
+}
+
+export interface SubsessionResult {
+  id?: string;
+  status: SubsessionStatus;
+  output: string;
+  usage: SubsessionUsage;
+  toolCounts: Record<string, number>;
+}
+
+export interface RuntimeConfig {
+  agent: string;
+  builtIn: boolean;
+  meta: AgentMeta;
+  systemPrompt: string;
+}
+
+export interface SubsessionRequest {
+  ctx: ExtensionContext;
+  label: SubsessionLabel;
+  agent: string;
+  id?: string;
+  signal?: AbortSignal;
+  onSnapshot: (snapshot: SubsessionSnapshot) => void;
+}
+
+export interface StoredSubsessions {
+  [id: string]: {
+    agent: string;
+    label: SubsessionLabel;
+    pid: string;
+    title: string;
+    usage: SubsessionUsage;
+  };
+}
+
+export interface Subsession {
+  pid: string;
+  label: SubsessionLabel;
+  title: string;
+  result: SubsessionResult;
+  runtime: RuntimeConfig;
+  exec(input: string, signal?: AbortSignal): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export interface ExecuteTurnRequest {
+  input: string;
+  session: AgentSession;
+  usage: SubsessionUsage;
+  signal?: AbortSignal;
+  onSnapshot: (snapshot: SubsessionSnapshot) => void;
+}
+
+export interface CreateSubsessionParams {
+  pid: string;
+  cwd: string;
+  title: string;
+  label: SubsessionLabel;
+  result: SubsessionResult;
+  runtime: RuntimeConfig;
+  session?: AgentSession;
+  onSnapshot: (snapshot: SubsessionSnapshot) => void;
+}

package/src/subagent/validation.ts

@@ -0,0 +1,100 @@
+function validatePlannerOutput(output: string): string | undefined {
+  const headings = [
+    "Objective",
+    "Out of scope",
+    "Assumptions",
+    "Steps",
+    "Risks & Mitigations",
+    "Handoff Packet",
+    "Open Questions",
+  ];
+  const optionalHeadings = ["Assumptions", "Open Questions"];
+  const mainHeadings = [...output.matchAll(/^#\s+(.+?)\s*$/gm)];
+  const firstLine = output.trimStart().split(/\r?\n/, 1)[0]?.trim();
+  if (mainHeadings.length !== 1 || !firstLine || !/^# Plan:\s+\S/.test(firstLine)) {
+    return "Plan output must start with '# Plan: [title]'.";
+  }
+
+  const sectionHeadings = [...output.matchAll(/^##\s+(.+?)\s*$/gm)].map((match) =>
+    match[1]!.trim(),
+  );
+  let headingIndex = 0;
+  for (const sectionHeading of sectionHeadings) {
+    while (
+      headingIndex < headings.length &&
+      headings[headingIndex] !== sectionHeading &&
+      optionalHeadings.includes(headings[headingIndex]!)
+    ) {
+      headingIndex += 1;
+    }
+    if (headings[headingIndex] !== sectionHeading) {
+      return `Plan output has unexpected or out-of-order "## ${sectionHeading}".`;
+    }
+    headingIndex += 1;
+  }
+
+  for (; headingIndex < headings.length; headingIndex += 1) {
+    if (!optionalHeadings.includes(headings[headingIndex]!)) {
+      return `Plan output is missing "## ${headings[headingIndex]}".`;
+    }
+  }
+}
+
+function validateScoutOutput(output: string, input: string): string | undefined {
+  const depthMatch = input.match(/^Depth:\s*(quick|standard|deep)\s*$/im);
+  const depth = depthMatch?.[1]?.toLowerCase() ?? "standard";
+  const headings =
+    depth === "quick"
+      ? ["Answer", "Evidence", "Gaps"]
+      : depth === "deep"
+        ? [
+            "Answer",
+            "Execution flow",
+            "Relevant locations",
+            "Change impact",
+            "Verification",
+            "Evidence",
+            "Gaps",
+          ]
+        : ["Answer", "Execution flow", "Relevant locations", "Evidence", "Gaps"];
+  const firstLine = output.trimStart().split(/\r?\n/, 1)[0]?.trim();
+  if (firstLine !== "## Answer") {
+    return "Scout output must start with '## Answer'.";
+  }
+
+  const sections = [...output.matchAll(/^##\s+(.+?)\s*$/gm)];
+  for (let headingIndex = 0; headingIndex < headings.length; headingIndex += 1) {
+    const actualHeading = sections[headingIndex]?.[1]?.trim();
+    if (!actualHeading) return `Scout output is missing "## ${headings[headingIndex]}".`;
+    if (actualHeading !== headings[headingIndex]) {
+      return `Scout output has unexpected or out-of-order "## ${actualHeading}".`;
+    }
+  }
+  if (sections.length > headings.length) {
+    return `Scout output has unexpected or out-of-order "## ${sections[headings.length]![1]!.trim()}".`;
+  }
+
+  for (let sectionIndex = 0; sectionIndex < sections.length; sectionIndex += 1) {
+    const contentStart = (sections[sectionIndex]!.index ?? 0) + sections[sectionIndex]![0].length;
+    const contentEnd = sections[sectionIndex + 1]?.index ?? output.length;
+    if (!output.slice(contentStart, contentEnd).trim()) {
+      return `Scout output section "## ${sections[sectionIndex]![1]!.trim()}" cannot be empty.`;
+    }
+  }
+
+  const evidenceIndex = headings.indexOf("Evidence");
+  const evidenceStart = (sections[evidenceIndex]!.index ?? 0) + sections[evidenceIndex]![0].length;
+  const evidenceEnd = sections[evidenceIndex + 1]?.index ?? output.length;
+  if (!/^- `[^`\r\n]+` — `[^`\r\n]+`: \S+/m.test(output.slice(evidenceStart, evidenceEnd))) {
+    return "Scout output must include evidence as '- `path:line` — `symbol`: finding'.";
+  }
+}
+
+export function validateBuiltInOutput(
+  agent: string,
+  output: string,
+  input: string,
+): string | undefined {
+  if (agent === "planner") return validatePlannerOutput(output);
+  if (agent === "scout") return validateScoutOutput(output, input);
+}

package/src/ui/components/action-select-list.ts

@@ -0,0 +1,165 @@
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
+import { Lines } from "./lines.js";
+import { PlaceholderInput } from "./placeholder-input.js";
+
+export type ActionSelectOption = {
+  value: string;
+  label: string;
+};
+
+export type ActionSelectResult =
+  | { type: "option"; value: string; index: number }
+  | { type: "input"; value: string };
+
+export type ActionSelectListOptions = {
+  title: string;
+  options: ActionSelectOption[];
+  placeholder: string;
+};
+
+export class ActionSelectList implements Component, Focusable {
+  onSubmit?: (result: ActionSelectResult) => void;
+  onCancel?: () => void;
+
+  private readonly input: PlaceholderInput;
+  private readonly options: ActionSelectOption[];
+  private readonly title: string;
+
+  private cursor = 0;
+  private _focused = false;
+
+  constructor(
+    tui: TUI,
+    keybindings: KeybindingsManager,
+    private readonly theme: Theme,
+    options: ActionSelectListOptions,
+  ) {
+    this.title = options.title;
+    this.options = options.options;
+    this.input = new PlaceholderInput(tui, keybindings, theme, options.placeholder);
+  }
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.syncInputFocus();
+  }
+
+  render(width: number): string[] {
+    const lines = new Lines(width);
+
+    lines.add(this.theme.bold(this.title));
+    for (const [optionIndex, option] of this.options.entries()) {
+      lines.add(this.renderOptionLine(optionIndex, option.label));
+    }
+
+    const inputOptionLines = this.renderInputOptionLines(width);
+    for (const inputOptionLine of inputOptionLines) {
+      lines.add(inputOptionLine);
+    }
+
+    return lines.get();
+  }
+
+  invalidate() {
+    this.input.invalidate();
+  }
+
+  handleInput(data: string) {
+    if (matchesKey(data, Key.escape)) {
+      this.onCancel?.();
+      return;
+    }
+    if (this.isInputSelected()) {
+      this.handleInputEditingMode(data);
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.moveCursor(-1);
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.moveCursor(1);
+      return;
+    }
+    if (matchesKey(data, Key.enter) && data !== "\n") {
+      this.commitSelection();
+      return;
+    }
+  }
+
+  private handleInputEditingMode(data: string) {
+    if (matchesKey(data, Key.up)) {
+      this.moveCursor(-1);
+      this.syncInputFocus();
+      return;
+    }
+    if (matchesKey(data, Key.enter) && data !== "\n") {
+      this.submitInputSelection();
+      return;
+    }
+    this.input.handleInput(data);
+  }
+
+  private commitSelection() {
+    const selected = this.options[this.cursor];
+    if (!selected) return;
+    this.onSubmit?.({ type: "option", value: selected.value, index: this.cursor });
+  }
+
+  private submitInputSelection() {
+    const trimmedInput = this.input.getText().trim();
+    if (trimmedInput.length === 0) return;
+    this.onSubmit?.({ type: "input", value: trimmedInput });
+  }
+
+  private renderOptionLine(optionIndex: number, label: string): string {
+    const selected = optionIndex === this.cursor;
+    const prefix = selected ? "→" : " ";
+    const content = `${prefix} ${optionIndex + 1}. ${label}`;
+    return this.theme.fg(selected ? "accent" : "text", content);
+  }
+
+  private renderInputOptionLines(width: number): string[] {
+    const inputOptionIndex = this.options.length;
+    const selected = inputOptionIndex === this.cursor;
+    const prefix = selected ? "→" : " ";
+    const marker = `${prefix} ${inputOptionIndex + 1}. `;
+    const markerColor = selected ? "accent" : "text";
+    const markerText = this.theme.fg(markerColor, marker);
+
+    const inputContentWidth = Math.max(1, width - marker.length);
+    const inputLines = this.input.render(inputContentWidth);
+    if (inputLines.length === 0) {
+      return [markerText];
+    }
+
+    const renderedLines: string[] = [];
+    renderedLines.push(`${markerText}${inputLines[0] ?? ""}`);
+
+    const continuationIndent = marker.length;
+    for (const continuationLine of inputLines.slice(1)) {
+      renderedLines.push(`${" ".repeat(continuationIndent)}${continuationLine}`);
+    }
+
+    return renderedLines;
+  }
+
+  private moveCursor(delta: number) {
+    const lastIndex = this.options.length;
+    this.cursor = Math.max(0, Math.min(lastIndex, this.cursor + delta));
+    this.syncInputFocus();
+  }
+
+  private isInputSelected(): boolean {
+    return this.cursor === this.options.length;
+  }
+
+  private syncInputFocus() {
+    this.input.focused = this._focused && this.isInputSelected();
+  }
+}