surgent 0.7.0-alpha.0

package/src/cleanup/subsession.ts

@@ -0,0 +1,46 @@
+import { unlink } from "node:fs/promises";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { StoredSubsessions } from "../subagent/types.js";
+import { getPiPath, isMissingFileError, readJson, writeJson } from "../utils.js";
+
+function collectOrphanedSubsessionIds(store: StoredSubsessions, pids: Set<string>): Set<string> {
+  const orphanedIds = new Set<string>();
+  for (const [subsessionId, metadata] of Object.entries(store)) {
+    if (!pids.has(metadata.pid)) {
+      orphanedIds.add(subsessionId);
+    }
+  }
+  return orphanedIds;
+}
+
+async function deleteSessionFilesByIds(cwd: string, sessionIds: Set<string>): Promise<void> {
+  if (sessionIds.size === 0) return;
+  const sessions = await SessionManager.list(cwd, getPiPath("subsessionsDir", cwd));
+  const sessionPaths = sessions
+    .filter((session) => sessionIds.has(session.id))
+    .map((session) => session.path);
+
+  for (const sessionPath of sessionPaths) {
+    try {
+      await unlink(sessionPath);
+    } catch (error) {
+      if (isMissingFileError(error)) continue;
+      throw error;
+    }
+  }
+}
+
+export async function cleanupSubsessions(cwd: string, pids: Set<string>): Promise<void> {
+  const storeFilePath = getPiPath("subsessions", cwd);
+  const store = await readJson<StoredSubsessions>(storeFilePath, {});
+
+  const orphanedIds = collectOrphanedSubsessionIds(store, pids);
+  if (orphanedIds.size === 0) return;
+  await deleteSessionFilesByIds(cwd, orphanedIds);
+
+  for (const subsessionId of orphanedIds) {
+    delete store[subsessionId];
+  }
+
+  await writeJson(storeFilePath, store);
+}

package/src/commands/helpers.ts

@@ -0,0 +1,217 @@
+import { unlink, writeFile } from "node:fs/promises";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Subsession, SubsessionRequest } from "../subagent/types.js";
+import { terminateSubsession } from "../subagent/storage.js";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { StoredSubsessions } from "../subagent/types.js";
+import { ExtendedSelectList, type SelectEntry } from "../ui/components/extended-select-list.js";
+import { getPiPath, isMissingFileError, isUuidv7, openInEditor, readJson } from "../utils.js";
+import { openSubsession } from "../subagent/subsession.js";
+import { renderSnapshotWidget, showPlanUi } from "./render.js";
+import type { CommandInput } from "./types.js";
+
+async function savePlanOutput(
+  ctx: ExtensionCommandContext,
+  subsession: Subsession,
+): Promise<string | null> {
+  if (!subsession.result.id) {
+    ctx.ui.notify("Failed to save plan: missing subsession ID", "error");
+    return null;
+  }
+
+  const outputPath = getPiPath("plans", ctx.cwd, `${subsession.result.id}.md`);
+
+  try {
+    await writeFile(outputPath, `${subsession.result.output.trimEnd()}\n`, "utf8");
+    return outputPath;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(`Failed to save plan: ${message}`, "error");
+    return null;
+  }
+}
+
+function discardSubsession(ctx: ExtensionCommandContext, subsession: Subsession) {
+  const subsessionId = subsession.result.id;
+  if (!subsessionId) return;
+  terminateSubsession(ctx.cwd, subsessionId).catch(() => undefined);
+}
+
+async function forwardAction(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  subsession: Subsession,
+  outputPath: string | null,
+): Promise<boolean> {
+  const normalizedOutput = subsession.result.output.trim();
+  if (!normalizedOutput) {
+    ctx.ui.notify(`No ${subsession.label} to forward`, "warning");
+    return false;
+  }
+
+  try {
+    pi.sendUserMessage(normalizedOutput);
+  } catch {
+    ctx.ui.notify(`Failed to forward ${subsession.label}`, "error");
+    return false;
+  }
+
+  if (outputPath) {
+    try {
+      await unlink(outputPath);
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Failed to delete ${subsession.label}: ${message}`, "error");
+      }
+    }
+  }
+
+  discardSubsession(ctx, subsession);
+  return true;
+}
+
+export async function runPlanLoop(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  subsession: Subsession,
+) {
+  try {
+    const outputPath = await savePlanOutput(ctx, subsession);
+    while (true) {
+      ctx.ui.setWidget("planner", undefined);
+      const action = await showPlanUi(ctx, subsession.result.output, outputPath);
+
+      if (action.kind === "save") {
+        ctx.ui.notify(
+          `Saved plan to ${outputPath}. Resume with '/plan <saved-plan-id>'`,
+          "info",
+        );
+        return;
+      }
+      if (action.kind === "discard") {
+        discardSubsession(ctx, subsession);
+        return;
+      }
+
+      if (action.kind === "open") {
+        if (outputPath) await openInEditor(ctx, outputPath);
+      } else if (action.kind === "forward") {
+        const forwarded = await forwardAction(pi, ctx, subsession, outputPath);
+        if (forwarded) return;
+      } else {
+        await subsession.exec(action.feedback);
+      }
+    }
+  } finally {
+    await subsession.dispose();
+    ctx.ui.setWidget("planner", undefined);
+  }
+}
+
+export async function getPlanPreviews(
+  cwd: string,
+  sessionId: string,
+): Promise<{ subsessionId: string; title: string }[]> {
+  const store = await readJson<StoredSubsessions>(getPiPath("subsessions", cwd), {});
+  const previews: { subsessionId: string; title: string }[] = [];
+
+  for (const [subsessionId, metadata] of Object.entries(store)) {
+    if (metadata.label === "plan" && metadata.pid === sessionId) {
+      previews.push({ subsessionId, title: metadata.title });
+    }
+  }
+
+  return previews;
+}
+
+export async function getPlanCompletions(cwd: string, sessionId: string, prefix: string) {
+  const normalizedPrefix = prefix.trim().toLowerCase();
+  const items = (await getPlanPreviews(cwd, sessionId))
+    .filter(
+      ({ subsessionId, title }) =>
+        subsessionId.startsWith(normalizedPrefix) || title.toLowerCase().includes(normalizedPrefix),
+    )
+    .map(({ subsessionId, title }) => ({ value: subsessionId, label: title }));
+  return items.length > 0 ? items : null;
+}
+
+async function pickPlanId(ctx: ExtensionContext): Promise<string | null> {
+  const previews = await getPlanPreviews(ctx.cwd, ctx.sessionManager.getSessionId());
+  if (previews.length === 0) {
+    ctx.ui.notify("No stored plan sessions", "warning");
+    return null;
+  }
+
+  const items: SelectEntry<{ subsessionId: string }>[] = previews.map((preview) => ({
+    value: preview.subsessionId,
+    label: preview.title,
+    data: { subsessionId: preview.subsessionId },
+  }));
+
+  return ctx.ui.custom<string | null>((_tui, theme, _keybindings, done) => {
+    const selectList = new ExtendedSelectList<{ subsessionId: string }>(theme, {
+      title: "Reopen plan session",
+      items,
+      maxVisibleRows: 12,
+    });
+
+    selectList.onCancel = () => done(null);
+    selectList.onSelect = (item) => done(item.data?.subsessionId ?? null);
+    selectList.onDelete = (item) => {
+      const subsessionId = item.data?.subsessionId;
+      if (!subsessionId) return;
+      terminateSubsession(ctx.cwd, subsessionId)
+        .then(() => ctx.ui.notify("Deleted plan session", "info"))
+        .catch(() => ctx.ui.notify("Failed to delete plan session", "error"));
+    };
+
+    return selectList;
+  });
+}
+
+export async function resolvePlan(
+  ctx: ExtensionCommandContext,
+  input: CommandInput,
+): Promise<Subsession | null> {
+  let prompt = "";
+  const request: SubsessionRequest = {
+    ctx,
+    label: "plan",
+    agent: "planner",
+    onSnapshot: (snapshot) => renderSnapshotWidget(ctx, "planner", snapshot),
+  };
+
+  if (input.kind === "prompt") {
+    prompt = input.prompt;
+  } else if (input.kind === "resume") {
+    request.id = input.subsessionId;
+  } else {
+    const selectedSubsessionId = await pickPlanId(ctx);
+    if (!selectedSubsessionId) return null;
+    request.id = selectedSubsessionId;
+  }
+
+  const subsession = await openSubsession(request);
+  if (!request.id && subsession.result.status !== "error") {
+    await subsession.exec(prompt);
+  }
+  if (!subsession.result.id) {
+    await subsession.dispose();
+    ctx.ui.notify(subsession.result.output || "Failed to initiate subsession", "error");
+    return null;
+  }
+
+  return subsession;
+}
+
+export function parseCommandInput(args: string): CommandInput {
+  const normalized = args.trim();
+  if (!normalized) {
+    return { kind: "list" };
+  }
+  if (isUuidv7(normalized)) {
+    return { kind: "resume", subsessionId: normalized };
+  }
+  return { kind: "prompt", prompt: normalized };
+}

package/src/commands/index.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { renderSnapshotWidget } from "./render.js";
+import { openSubsession } from "../subagent/subsession.js";
+import { getPlanCompletions, parseCommandInput, resolvePlan, runPlanLoop } from "./helpers.js";
+
+const INIT_PROMPT = `Analyze this repository and create or update AGENTS.md in its root. This file gives future coding agents concise, project-specific instructions.
+
+Use only facts verified in repository files. Include build, lint, type-check, and test commands, focused test commands when available, architecture and important directories, coding conventions, and project-specific gotchas. Check existing AGENTS.md and other instruction files such as CLAUDE.md, .cursor/rules, .cursorrules, and .github/copilot-instructions.md. Preserve valid existing guidance and reference related files instead of duplicating them. Do not blindly replace AGENTS.md. Write the file, then briefly report what changed.`;
+
+export default function (pi: ExtensionAPI) {
+  let cwd = "";
+  let pid = "";
+
+  pi.on("session_start", (_event, ctx) => {
+    cwd = ctx.cwd;
+    pid = ctx.sessionManager.getSessionId();
+  });
+
+  pi.registerCommand("init", {
+    description: "Create or update project AGENTS.md instructions",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/init requires interactive UI", "error");
+        return;
+      }
+
+      const subsession = await openSubsession({
+        ctx,
+        label: "subagent",
+        agent: "documenter",
+        onSnapshot: (snapshot) => renderSnapshotWidget(ctx, "documenter", snapshot),
+      });
+      try {
+        if (subsession.result.status !== "error") {
+          await subsession.exec(INIT_PROMPT);
+        }
+
+        if (subsession.result.status === "done") {
+          ctx.ui.notify("AGENTS.md initialization finished", "info");
+          return;
+        }
+        ctx.ui.notify(subsession.result.output, "error");
+      } finally {
+        await subsession.dispose();
+        ctx.ui.setWidget("documenter", undefined);
+      }
+    },
+  });
+
+  pi.registerCommand("plan", {
+    description: `[empty|<plan-id>|<request>] - Resume or start a 'plan' background session. Leave empty to list saved plans`,
+    getArgumentCompletions: (prefix) => {
+      if (!cwd || !pid) return null;
+      return getPlanCompletions(cwd, pid, prefix);
+    },
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify(`/plan requires interactive UI`, "error");
+        return;
+      }
+
+      const parsedInput = parseCommandInput(args);
+      const subsession = await resolvePlan(ctx, parsedInput);
+
+      if (!subsession) {
+        ctx.ui.setWidget("planner", undefined);
+        return;
+      }
+      if (subsession.result.status === "error") {
+        await subsession.dispose();
+        ctx.ui.setWidget("planner", undefined);
+        ctx.ui.notify(subsession.result.output, "error");
+        return;
+      }
+
+      await runPlanLoop(pi, ctx, subsession);
+    },
+  });
+}

package/src/commands/render.ts

@@ -0,0 +1,95 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+  ActionSelectList,
+  type ActionSelectOption,
+  type ActionSelectResult,
+} from "../ui/components/action-select-list.js";
+import { ScrollableView } from "../ui/components/scrollable-view.js";
+import type { LoopAction } from "./types.js";
+import { Container, Loader } from "@earendil-works/pi-tui";
+import { TruncatedText } from "@earendil-works/pi-tui";
+import { Spacer } from "@earendil-works/pi-tui";
+import { formatSnapshotText } from "../subagent/helpers.js";
+import type { SubsessionSnapshot } from "../subagent/types.js";
+
+const ACTIVITY_LABELS = [
+  "analyzing",
+  "researching",
+  "synthesizing",
+  "scrutinizing",
+  "processing",
+  "cooking",
+] as const;
+
+function mapActionResult(result: ActionSelectResult): LoopAction {
+  if (result.type === "input") {
+    return { kind: "feedback", feedback: result.value };
+  }
+  if (result.value === "open") {
+    return { kind: "open" };
+  }
+  if (result.value === "save") {
+    return { kind: "save" };
+  }
+  return { kind: "forward" };
+}
+
+export async function showPlanUi(
+  ctx: ExtensionCommandContext,
+  output: string,
+  outputPath: string | null,
+): Promise<LoopAction> {
+  const markdown = output.trim().length > 0 ? output : "_No planner output yet._";
+  const options: ActionSelectOption[] = [{ value: "forward", label: "Implement this plan" }];
+  if (outputPath) {
+    options.push({ value: "open", label: "Open plan in external editor" });
+  }
+  options.push({ value: "save", label: "Save and exit" });
+
+  return ctx.ui.custom<LoopAction>((tui, theme, keybindings, done) => {
+    const actionSelectList = new ActionSelectList(tui, keybindings, theme, {
+      title: "What should surgent do next?",
+      options,
+      placeholder: "Feedback for planner agent",
+    });
+    actionSelectList.onSubmit = (result) => done(mapActionResult(result));
+    actionSelectList.onCancel = () => done({ kind: "discard" });
+
+    const scrollableView = new ScrollableView(tui, theme, { markdown, input: actionSelectList });
+    scrollableView.focused = true;
+    scrollableView.onCancel = () => done({ kind: "discard" });
+
+    return scrollableView;
+  });
+}
+
+export function renderSnapshotWidget(
+  ctx: ExtensionCommandContext,
+  label: string,
+  snapshot: SubsessionSnapshot,
+) {
+  const activity = ACTIVITY_LABELS[Math.floor(Math.random() * ACTIVITY_LABELS.length)]!;
+  const snapshotText = formatSnapshotText(snapshot);
+
+  ctx.ui.setWidget(label, (tui, theme) => {
+    const widget = new Container() as Container & { dispose?: () => void };
+    const loader = new Loader(
+      tui,
+      (content) => theme.fg("accent", content),
+      (content) => theme.fg("muted", content),
+      `${label} (${activity}): ${snapshotText[0]}`,
+    );
+    if (snapshot.status !== "running") {
+      loader.setIndicator({ frames: ["•"] });
+    }
+
+    widget.addChild(loader);
+    for (const line of snapshotText.slice(1)) {
+      widget.addChild(new TruncatedText(`  ${line}`, 1, 0));
+    }
+
+    widget.addChild(new Spacer(1));
+    widget.dispose = () => loader.stop();
+    return widget;
+  });
+}

package/src/commands/types.ts

@@ -0,0 +1,11 @@
+export type LoopAction =
+  | { kind: "forward" }
+  | { kind: "feedback"; feedback: string }
+  | { kind: "open" }
+  | { kind: "save" }
+  | { kind: "discard" };
+
+export type CommandInput =
+  | { kind: "list" }
+  | { kind: "resume"; subsessionId: string }
+  | { kind: "prompt"; prompt: string };

package/src/mcp-client/call-tool.ts

@@ -0,0 +1,143 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resolveServerConfig } from "./storage.js";
+import { McpClientManager } from "./client.js";
+import type { McpToolCallDetails } from "./types.js";
+import { renderCallText } from "../utils.js";
+
+export function createMcpCallTool(clientManager: McpClientManager) {
+  return defineTool({
+    name: "call_mcp_tool",
+    label: "MCP Call Tool",
+    description: "Call known tool on configured MCP server.",
+    promptSnippet: "Call known tool on configured MCP server.",
+    promptGuidelines: [
+      "Use call_mcp_tool only with known server and tool names.",
+      "Use call_mcp_tool instead of recreating capability already exposed by MCP.",
+      "Use call_mcp_tool arguments as schema-matching JSON.",
+    ],
+    parameters: Type.Object({
+      server: Type.String({ description: "Configured server name" }),
+      tool: Type.String({ description: "Remote tool name" }),
+      arguments: Type.Optional(
+        Type.Object({}, { additionalProperties: true, description: "JSON arguments" }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (signal?.aborted) {
+        throw new Error("call_mcp_tool was cancelled.");
+      }
+
+      const serverName = params.server.trim();
+      const toolName = params.tool.trim();
+      const serverConfig = await resolveServerConfig(ctx.cwd, serverName);
+
+      if (!serverConfig) {
+        throw new Error(`Unknown MCP server: ${serverName}. Configure it with /mcp.`);
+      }
+      if (serverConfig.enabled === false) {
+        throw new Error(`MCP server ${serverName} is disabled.`);
+      }
+
+      const toolsResult = await clientManager.listTools(serverConfig);
+      const remoteTool = toolsResult.tools.find((item) => item.name === toolName);
+
+      if (!remoteTool) {
+        const availableTools = toolsResult.tools
+          .map((item) => item.name)
+          .sort()
+          .join(", ");
+        throw new Error(
+          `MCP server ${serverName} does not expose ${toolName}.${availableTools ? ` Available tools: ${availableTools}.` : ""}`,
+        );
+      }
+
+      if (signal?.aborted) {
+        throw new Error("call_mcp_tool was cancelled.");
+      }
+
+      const result = await clientManager.callTool(serverConfig, {
+        name: toolName,
+        arguments: (params.arguments ?? {}) as Record<string, unknown>,
+      });
+      const text = formatCallToolResult(result);
+
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          server: serverConfig.name,
+          transport: serverConfig.transport,
+          remoteTool: toolName,
+        } satisfies McpToolCallDetails,
+        isError: result.isError === true,
+      };
+    },
+    renderCall(args, theme, { isPartial }) {
+      return renderCallText(
+        `${theme.fg("toolTitle", "call_mcp_tool")} ${theme.fg("accent", `${args.server}:${args.tool}`)}`,
+        isPartial,
+      );
+    },
+  });
+}
+
+function formatCallToolResult(result: {
+  content?: Array<Record<string, unknown>>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+  toolResult?: unknown;
+}): string {
+  if ("toolResult" in result) {
+    return JSON.stringify(result.toolResult, null, 2);
+  }
+
+  const chunks: string[] = [];
+  for (const item of result.content ?? []) {
+    if (item.type === "text" && typeof item.text === "string") {
+      chunks.push(item.text);
+      continue;
+    }
+
+    if (item.type === "image" && typeof item.mimeType === "string") {
+      chunks.push(`[image content: ${item.mimeType}]`);
+      continue;
+    }
+
+    if (item.type === "audio" && typeof item.mimeType === "string") {
+      chunks.push(`[audio content: ${item.mimeType}]`);
+      continue;
+    }
+
+    if (item.type === "resource" && item.resource && typeof item.resource === "object") {
+      const resource = item.resource as Record<string, unknown>;
+      if (typeof resource.uri === "string" && typeof resource.text === "string") {
+        chunks.push(`Resource ${resource.uri}\n${resource.text}`);
+        continue;
+      }
+      if (typeof resource.uri === "string") {
+        chunks.push(`[resource content: ${resource.uri}]`);
+        continue;
+      }
+    }
+
+    if (item.type === "resource_link" && typeof item.uri === "string") {
+      chunks.push(`[resource link: ${item.uri}]`);
+      continue;
+    }
+
+    chunks.push(JSON.stringify(item, null, 2));
+  }
+
+  if (result.structuredContent && Object.keys(result.structuredContent).length > 0) {
+    chunks.push(JSON.stringify(result.structuredContent, null, 2));
+  }
+
+  const body = chunks.filter(Boolean).join("\n\n").trim();
+  if (!body) {
+    return result.isError
+      ? "MCP tool returned an error with no content."
+      : "MCP tool returned no content.";
+  }
+
+  return result.isError ? `Remote MCP tool reported an error.\n\n${body}` : body;
+}

package/src/mcp-client/client.ts

@@ -0,0 +1,90 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { CallToolRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { ResolvedMcpServer } from "./types.js";
+
+interface ManagedConnection {
+  client: Client;
+  transport: StdioClientTransport | StreamableHTTPClientTransport;
+  configHash: string;
+}
+
+export class McpClientManager {
+  private readonly connections = new Map<string, ManagedConnection>();
+  private readonly CLIENT_INFO = {
+    name: "surgent-mcp-client",
+    version: "0.1.0",
+  };
+
+  async listTools(serverConfig: ResolvedMcpServer) {
+    const connection = await this.getConnection(serverConfig);
+    return connection.client.listTools();
+  }
+
+  async callTool(serverConfig: ResolvedMcpServer, params: CallToolRequest["params"]) {
+    const connection = await this.getConnection(serverConfig);
+    return connection.client.callTool(params);
+  }
+
+  async disposeAll() {
+    const activeConnections = Array.from(this.connections.values());
+    this.connections.clear();
+    await Promise.allSettled(
+      activeConnections.map((connection) => this.disposeConnection(connection)),
+    );
+  }
+
+  private async getConnection(serverConfig: ResolvedMcpServer): Promise<ManagedConnection> {
+    const cacheKey = serverConfig.name;
+    const configHash = JSON.stringify(serverConfig);
+    const existing = this.connections.get(cacheKey);
+
+    if (existing && existing.configHash === configHash) {
+      return existing;
+    }
+
+    if (existing) {
+      await this.disposeConnection(existing);
+      this.connections.delete(cacheKey);
+    }
+
+    const connection = await this.createConnection(serverConfig, configHash);
+    this.connections.set(cacheKey, connection);
+    return connection;
+  }
+
+  private async createConnection(
+    serverConfig: ResolvedMcpServer,
+    configHash: string,
+  ): Promise<ManagedConnection> {
+    const client = new Client(this.CLIENT_INFO);
+    const transport =
+      serverConfig.transport === "stdio"
+        ? new StdioClientTransport({
+            command: serverConfig.command,
+            args: serverConfig.args,
+            cwd: serverConfig.cwd,
+            env: serverConfig.env,
+          })
+        : new StreamableHTTPClientTransport(new URL(serverConfig.url), {
+            requestInit: serverConfig.headers ? { headers: serverConfig.headers } : undefined,
+          });
+
+    await client.connect(transport);
+
+    return { client, transport, configHash };
+  }
+
+  private async disposeConnection(connection: ManagedConnection) {
+    if (connection.transport instanceof StreamableHTTPClientTransport) {
+      await Promise.allSettled([
+        connection.transport.terminateSession(),
+        connection.transport.close(),
+      ]);
+      return;
+    }
+
+    await connection.transport.close();
+  }
+}