@jwilger/pi-development-system 0.10.5 → 0.11.0

package/src/subagents/orch/tools.ts

@@ -0,0 +1,166 @@
+// @ts-nocheck: vendored upstream pi-subagent-manager 0.14.0 compiled under looser options; see src/subagents/VENDORED.md
+import { Type } from "typebox";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ThreadManager } from "./manager.ts";
+import { ModelPreferenceError } from "../prefs/models.ts";
+import type { AgentType, ResolvedAgentSettings, ThreadView } from "../types.ts";
+
+const path = Type.String({ description: "Absolute agent path, or name relative to the caller" });
+const text = Type.String({ minLength: 1 });
+function compact(thread: ThreadView): ThreadView & { outputTruncated?: boolean } {
+  if (thread.output && thread.output.length > 16000)
+    return { ...thread, output: thread.output.slice(0, 16000), outputTruncated: true };
+  return thread;
+}
+function result(value: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
+    details: value,
+  };
+}
+
+/** All threads see the same verbs, with caller identity bound by closure, never model input. */
+export function agentTools(
+  getManager: () => ThreadManager,
+  caller: string,
+  getTypes: () => AgentType[],
+  resolveSettings: (type: AgentType) => ResolvedAgentSettings,
+): ToolDefinition[] {
+  const threads = () => getManager().scope(caller);
+  const make = (
+    name: string,
+    description: string,
+    parameters: any,
+    execute: (params: any, signal?: AbortSignal) => Promise<any> | any,
+  ): ToolDefinition => ({
+    name,
+    label: name,
+    description,
+    parameters,
+    execute: async (_id, params, signal) => execute(params, signal),
+  });
+  return [
+    make(
+      "agent_types",
+      "List agent names, descriptions, resolved models and thinking levels for new children of this caller. Reflects current configuration; call before choosing a type. Other parent paths may inherit different settings.",
+      Type.Object({}),
+      () => {
+        const entries = getTypes().map((type) => {
+          const { name, description } = type;
+          try {
+            return { name, description, ...resolveSettings(type) };
+          } catch (error) {
+            return {
+              name,
+              description,
+              error:
+                error instanceof ModelPreferenceError
+                  ? error.summary
+                  : error instanceof Error
+                    ? error.message
+                    : String(error),
+            };
+          }
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text:
+                entries
+                  .map((entry) =>
+                    "error" in entry
+                      ? `${entry.name} (unavailable): ${entry.description}\n  ${entry.error}`
+                      : `${entry.name} (${entry.model}, thinking: ${entry.thinkingLevel}): ${entry.description}`,
+                  )
+                  .join("\n") || "No agent types available.",
+            },
+          ],
+          details: entries,
+        };
+      },
+    ),
+    make(
+      "agent_spawn",
+      "Spawn a named child. The lexical parent, NOT the caller, supplies a context snapshot. /root is the main thread; independent roots have no inherited context. Foreground waits by default; wait:false runs detached. For parallel work, spawn every independent sibling with wait:false before calling agent_wait; child agents with delegation tools should do the same. Existing paths are retained and can be resumed with agent_steer. Use agent_types to discover current types.",
+      Type.Object({
+        path: Type.String({
+          description:
+            "Task-based kebab-case path, not the agent type (e.g. /root/controller-security-research), or a task name relative to the caller",
+        }),
+        type: text,
+        task: text,
+        wait: Type.Optional(Type.Boolean()),
+      }),
+      async (params, signal) => result(compact(await threads().spawn(params, signal))),
+    ),
+    make(
+      "agent_wait",
+      "Wait for a descendant to complete, fail, stop or pause. Paused means no final answer handback. Cancellation/timeouts do not stop the child; poll status or wait again.",
+      Type.Object({
+        path,
+        timeoutMs: Type.Optional(Type.Integer({ minimum: 0, maximum: 3600000 })),
+      }),
+      async (params, signal) =>
+        result(compact(await threads().wait(params.path, params.timeoutMs, signal))),
+    ),
+    make(
+      "agent_steer",
+      "Send input to a descendant. Working threads receive queued steering; completed, stopped and paused threads resume the SAME session with its previous context. Returns immediately; use agent_wait for the result.",
+      Type.Object({ path, message: text }),
+      async (params) => result(compact(await threads().steer(params.path, params.message))),
+    ),
+    make(
+      "agent_status",
+      "Read a thread's status or list visible descendants. Root can inspect all trees. Completion retains the session; pause retains it without final answer handback.",
+      Type.Object({ path: Type.Optional(path) }),
+      (params) =>
+        result(params.path ? compact(threads().get(params.path)) : threads().list().map(compact)),
+    ),
+    make(
+      "agent_update",
+      "Child-only: send progress to the parent without ending this task. Delivery is recorded and displayed but does not interrupt or automatically restart the parent model.",
+      Type.Object({ message: Type.String({ minLength: 1, maxLength: 8000 }) }),
+      (params) => result(compact(threads().update(params.message))),
+    ),
+    make(
+      "agent_pause",
+      "Child-only: stop at this turn boundary WITHOUT returning a final answer. Keep the SAME session for user/parent input via agent_steer. To finish and hand back an answer instead, simply return your final assistant answer. Both states can be resumed.",
+      Type.Object({ reason: text }),
+      (params) => ({
+        ...result({
+          path: caller,
+          pauseRequested: true,
+          status: threads().pause(params.reason).status,
+        }),
+        terminate: true,
+      }),
+    ),
+    make(
+      "agent_stop",
+      "Stop a descendant and its working children. Session history is retained; resume with agent_steer. This is cooperative cancellation, not sandbox process termination.",
+      Type.Object({ path }),
+      async (params) => result(compact(await threads().stop(params.path))),
+    ),
+    make(
+      "agent_output",
+      "Read completed thread output in character pages. Paused threads deliberately have no final answer handback. All sessions can be viewed by the user with /agents tree; select a thread and press Enter to inspect it.",
+      Type.Object({
+        path,
+        offset: Type.Optional(Type.Integer({ minimum: 0 })),
+        limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000 })),
+      }),
+      (params) => {
+        const output = threads().output(params.path),
+          offset = params.offset ?? 0,
+          limit = params.limit ?? 8000;
+        return result({
+          path: threads().get(params.path).path,
+          text: output.slice(offset, offset + limit),
+          totalCharacters: output.length,
+          nextOffset: offset + limit < output.length ? offset + limit : null,
+        });
+      },
+    ),
+  ];
+}

package/src/subagents/orch/transcript.ts

@@ -0,0 +1,187 @@
+// @ts-nocheck: vendored upstream pi-subagent-manager 0.14.0 compiled under looser options; see src/subagents/VENDORED.md
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type {
+  TranscriptListener,
+  TranscriptObservation,
+  TranscriptSnapshot,
+  TranscriptToolState,
+} from "../types.ts";
+
+/** Clone once at the ownership boundary, then share immutable state across observers. */
+export function immutableTranscriptValue<T>(value: T): T {
+  const copy = structuredClone(value);
+  const seen = new WeakSet<object>();
+  const freeze = (item: unknown): void => {
+    if (!item || typeof item !== "object" || seen.has(item)) return;
+    seen.add(item);
+    for (const child of Object.values(item)) freeze(child);
+    // Freezing populated typed-array views throws. Their storage was already cloned.
+    if (!ArrayBuffer.isView(item)) Object.freeze(item);
+  };
+  freeze(copy);
+  return copy;
+}
+
+/** SDK event projection. Committed history is copied at boundaries, never for each token. */
+export class TranscriptChannel {
+  private revision = 0;
+  private messages: readonly AgentMessage[];
+  private assistant: AgentMessage | null = null;
+  private tools = new Map<string, TranscriptToolState>();
+  private listeners = new Set<TranscriptListener>();
+  private current: TranscriptSnapshot;
+  private disposed = false;
+  private error: string | undefined;
+
+  constructor(
+    private readMessages: () => readonly AgentMessage[],
+    private inheritedCount: number,
+  ) {
+    this.messages = immutableTranscriptValue(readMessages());
+    this.current = this.snapshot();
+  }
+
+  observe(listener: TranscriptListener): TranscriptObservation {
+    if (this.disposed) throw new Error("Transcript channel is disposed");
+    // No await between registration and snapshot: a finalization cannot fall in a gap.
+    const registered: TranscriptListener = (snapshot) => listener(snapshot);
+    this.listeners.add(registered);
+    return { snapshot: this.current, unsubscribe: () => this.listeners.delete(registered) };
+  }
+
+  accept(event: AgentSessionEvent): void {
+    if (this.disposed) return;
+    try {
+      this.reduce(event);
+    } catch (error) {
+      // Custom tool details can be non-cloneable. Observation must still never fail the run.
+      this.error = error instanceof Error ? error.message : String(error);
+      this.publish();
+    }
+  }
+
+  private reduce(event: AgentSessionEvent): void {
+    this.error = undefined;
+    switch (event.type) {
+      case "message_start":
+      case "message_update":
+        if (event.message.role !== "assistant") return;
+        this.assistant = immutableTranscriptValue(event.message);
+        break;
+      case "message_end":
+        if (event.message.role === "assistant") this.assistant = null;
+        if (event.message.role === "toolResult") this.tools.delete(event.message.toolCallId);
+        this.messages = immutableTranscriptValue(this.readMessages());
+        break;
+      case "tool_execution_start":
+        this.tools.set(
+          event.toolCallId,
+          immutableTranscriptValue({
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            parentToolCallId: event.parentToolCallId,
+            args: event.args,
+            state: "running" as const,
+          }),
+        );
+        break;
+      case "tool_execution_update":
+        this.tools.set(
+          event.toolCallId,
+          immutableTranscriptValue({
+            ...this.tools.get(event.toolCallId),
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            parentToolCallId: event.parentToolCallId,
+            args: event.args,
+            result: event.partialResult,
+            state: "running" as const,
+          }),
+        );
+        break;
+      case "tool_execution_end":
+        this.tools.set(
+          event.toolCallId,
+          immutableTranscriptValue({
+            ...this.tools.get(event.toolCallId),
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            parentToolCallId: event.parentToolCallId,
+            args: this.tools.get(event.toolCallId)?.args,
+            result: event.result,
+            isError: event.isError,
+            state: "completed" as const,
+          }),
+        );
+        // Nested calls have no transcript message. Bound their transient completed retention.
+        for (const [id, tool] of this.tools) {
+          if (this.tools.size <= 128) break;
+          if (tool.state === "completed") this.tools.delete(id);
+        }
+        break;
+      case "compaction_end":
+        // Compaction may replace/reorder history; do not approximate it with append-only deltas.
+        if (event.result && !event.aborted) this.inheritedCount = 0;
+        this.messages = immutableTranscriptValue(this.readMessages());
+        break;
+      case "agent_end":
+      case "agent_settled":
+        this.assistant = null;
+        this.tools.clear();
+        this.messages = immutableTranscriptValue(this.readMessages());
+        break;
+      case "auto_retry_start":
+      case "auto_retry_end":
+        this.messages = immutableTranscriptValue(this.readMessages());
+        break;
+      default:
+        return;
+    }
+    this.publish();
+  }
+
+  /** Non-turn custom delivery is not guaranteed to use core message events. */
+  reconcile(): void {
+    if (this.disposed) return;
+    try {
+      this.messages = immutableTranscriptValue(this.readMessages());
+      this.error = undefined;
+    } catch (error) {
+      this.error = error instanceof Error ? error.message : String(error);
+    }
+    this.publish();
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.listeners.clear();
+    this.tools.clear();
+    this.assistant = null;
+  }
+
+  private snapshot(): TranscriptSnapshot {
+    return Object.freeze({
+      revision: this.revision,
+      generation: 0,
+      messages: this.messages,
+      assistant: this.assistant,
+      tools: Object.freeze([...this.tools.values()]),
+      inheritedCount: Math.min(this.inheritedCount, this.messages.length),
+      ...(this.error ? { error: this.error } : {}),
+    });
+  }
+
+  private publish(): void {
+    this.revision++;
+    this.current = this.snapshot();
+    for (const listener of this.listeners) {
+      // Watching is read-only: a broken renderer must not fail the agent's execution.
+      try {
+        listener(this.current);
+      } catch {
+        /* observer owns its error reporting */
+      }
+    }
+  }
+}

package/src/subagents/prefs/agent-import.ts

@@ -0,0 +1,246 @@
+// @ts-nocheck: vendored upstream pi-subagent-manager 0.14.0 compiled under looser options; see src/subagents/VENDORED.md
+import { constants, lstatSync, mkdirSync, openSync, closeSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { AGENT_COLORS, type ConfigStore } from "./config.ts";
+import { discoverImportCandidates, type ImportCandidate } from "./import-discovery.ts";
+import { selectImportAgents } from "../ui/import-picker.ts";
+import { MIGRATION_INSTRUCTIONS } from "./import-instructions.ts";
+import { dialogText } from "../ui/dialog.ts";
+
+export const IMPORT_REQUEST_PREFIX =
+  "Import ONLY the agents I selected in the pi-subagent-manager migration picker.";
+
+export const IMPORT_CHILD_TOOLS = [
+  "read",
+  "bash",
+  "powershell",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+  "agent_types",
+  "agent_spawn",
+  "agent_wait",
+  "agent_steer",
+  "agent_status",
+  "agent_update",
+  "agent_pause",
+  "agent_stop",
+  "agent_output",
+];
+
+// This records onboarding only. Limits remain in subagent-manager/settings.json.
+const OFFER_MARKER = ".import-offered";
+
+function statIfPresent(path: string) {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) throw new Error(`Unsafe import-state symlink: ${path}`);
+    return stat;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function stateDirectory(agentDir: string, create: boolean): string | undefined {
+  const directory = join(agentDir, "subagent-manager");
+  for (const path of [agentDir, directory]) {
+    let stat = statIfPresent(path);
+    if (!stat && create) {
+      // The host owns agentDir. Do not recursively create or follow unchecked parents.
+      mkdirSync(path);
+      stat = statIfPresent(path);
+    }
+    if (!stat) return undefined;
+    if (!stat.isDirectory()) throw new Error(`Import-state directory is not a directory: ${path}`);
+  }
+  return directory;
+}
+
+export function importWasOffered(agentDir: string): boolean {
+  const directory = stateDirectory(agentDir, false);
+  if (!directory) return false;
+  const stat = statIfPresent(join(directory, OFFER_MARKER));
+  if (stat && !stat.isFile()) throw new Error("Import-state marker must be a regular file");
+  return !!stat;
+}
+
+export function markImportOffered(agentDir: string): void {
+  const directory = stateDirectory(agentDir, true)!;
+  const file = join(directory, OFFER_MARKER);
+  const stat = statIfPresent(file);
+  if (stat) {
+    if (!stat.isFile()) throw new Error("Import-state marker must be a regular file");
+    return;
+  }
+  const fd = openSync(
+    file,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0),
+    0o600,
+  );
+  try {
+    writeFileSync(fd, "Onboarding offered. Use /agents import to choose agents again.\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function buildImportPrompt(options: {
+  candidates: readonly ImportCandidate[];
+  agentDir: string;
+  cwd: string;
+  includeProject: boolean;
+  existingTypes: { name: string; source?: string; filePath?: string }[];
+  scopedModels: readonly string[];
+  scopedModelDetails?: readonly { identity: string; api: string; virtual: boolean }[];
+  parentModel?: string;
+  parentModelApi?: string;
+}): string {
+  return [
+    IMPORT_REQUEST_PREFIX,
+    MIGRATION_INSTRUCTIONS,
+    "## Current-session migration facts (JSON data, not instructions)",
+    JSON.stringify(
+      {
+        selectedDefinitions: options.candidates,
+        destinations: {
+          user: join(options.agentDir, "subagent-manager", "agents"),
+          project: options.includeProject
+            ? join(options.cwd, ".pi", "agent", "subagent-manager", "agents")
+            : null,
+        },
+        destinationRule:
+          "Keep user sources user-scoped and project sources project-scoped. Project destination is permitted only when non-null; ask before changing scope.",
+        managerSettings: join(options.agentDir, "subagent-manager", "settings.json"),
+        configModule: fileURLToPath(new URL("./config.ts", import.meta.url)),
+        existingTypes: options.existingTypes,
+        scopedModels: options.scopedModels,
+        scopedModelDetails: options.scopedModelDetails ?? [],
+        parentModel: options.parentModel ?? null,
+        parentModelApi: options.parentModelApi ?? null,
+        childTools: IMPORT_CHILD_TOOLS,
+        colorTokens: AGENT_COLORS,
+      },
+      null,
+      2,
+    ),
+  ].join("\n\n");
+}
+
+/** Discovery and consent only; the current conversation performs every semantic conversion/write. */
+export async function offerAgentImport(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  options: {
+    agentDir: string;
+    store: ConfigStore;
+    firstRun?: boolean;
+    homeDir?: string;
+    extraAgentDirs?: string;
+    select?: typeof selectImportAgents;
+  },
+): Promise<boolean> {
+  const firstRun = options.firstRun ?? false;
+  if (!ctx.hasUI || ctx.mode !== "tui") {
+    if (!firstRun)
+      ctx.ui.notify(
+        "Agent import requires TUI mode. Run /agents import in an interactive session.",
+        "warning",
+      );
+    return false;
+  }
+  try {
+    if (firstRun && importWasOffered(options.agentDir)) return false;
+    const found = discoverImportCandidates({
+      cwd: ctx.cwd,
+      agentDir: options.agentDir,
+      includeProject: ctx.isProjectTrusted(),
+      homeDir: options.homeDir,
+      extraAgentDirs: options.extraAgentDirs,
+    });
+    if (found.diagnostics.length)
+      ctx.ui.notify(dialogText(found.diagnostics.join("\n")), "warning");
+    const remember = () => {
+      try {
+        markImportOffered(options.agentDir);
+      } catch (error) {
+        ctx.ui.notify(
+          dialogText(`Could not save import onboarding state: ${String(error)}`),
+          "warning",
+        );
+      }
+    };
+    if (!found.candidates.length) {
+      // Retry an incomplete scan next startup, rather than permanently hiding unreadable definitions.
+      if (!found.diagnostics.length) remember();
+      if (!firstRun)
+        ctx.ui.notify(
+          "No external agent definitions found. Package-provided defaults are not scanned.",
+          "info",
+        );
+      return false;
+    }
+    if (
+      firstRun &&
+      !(await ctx.ui.confirm(
+        "Import existing agents?",
+        `Found ${found.candidates.length} external agent definitions. Choose individual agents in a checkbox picker, then the current session model will migrate only your selection. Originals stay unchanged. You can also use /agents import later.`,
+      ))
+    ) {
+      remember();
+      return false;
+    }
+    const ids = await (options.select ?? selectImportAgents)(
+      ctx,
+      found.candidates.map((candidate) => ({
+        id: candidate.id,
+        label: `${candidate.name} (${candidate.scope})`,
+        detail: `${candidate.path}\n${candidate.description}`,
+      })),
+    );
+    if (!ids?.length) {
+      remember();
+      return false;
+    }
+    const selected = new Set(ids);
+    const candidates = found.candidates.filter((candidate) => selected.has(candidate.id));
+    if (!candidates.length) return false;
+    options.store.reload();
+    const prompt = buildImportPrompt({
+      candidates,
+      agentDir: options.agentDir,
+      cwd: ctx.cwd,
+      includeProject: ctx.isProjectTrusted(),
+      existingTypes: options.store
+        .list()
+        .map(({ name, source, filePath }) => ({ name, source, filePath })),
+      scopedModels: (ctx.scopedModels ?? []).map(({ model }) => `${model.provider}/${model.id}`),
+      scopedModelDetails: (ctx.scopedModels ?? []).map(({ model }) => ({
+        identity: `${model.provider}/${model.id}`,
+        api: model.api,
+        virtual: model.api === "pi-virtual",
+      })),
+      parentModel: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
+      parentModelApi: ctx.model?.api,
+    });
+    // This starts (or queues) a turn in the active root session, not another SDK session.
+    pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+    // sendUserMessage is fire-and-forget. The root before_agent_start hook acknowledges
+    // accepted requests; authentication/model failures must leave first-run retryable.
+    ctx.ui.notify(
+      `Asked the current session model to import ${candidates.length} selected agent(s).`,
+      "info",
+    );
+    return true;
+  } catch (error) {
+    ctx.ui.notify(
+      dialogText(`Agent import failed: ${String(error)}. Retry with /agents import.`),
+      "warning",
+    );
+    return false;
+  }
+}