@jwilger/pi-development-system 0.10.6 → 0.12.0

package/src/subagents/types.ts

@@ -0,0 +1,209 @@
+// @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 { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export interface ResolvedAgentSettings {
+  model: string;
+  thinkingLevel: ThinkingLevel;
+}
+export interface AgentType {
+  name: string;
+  description: string;
+  models?: string[];
+  /** @deprecated Use ordered models instead. */
+  model?: string;
+  /** Advisory display names. Not provider/model pins and never used for selection. */
+  modelSuggestions?: string[];
+  thinkingLevel?: ThinkingLevel;
+  /** devsys: per-spawn pin set by the coordinator via agent_spawn; beats preferences and inheritance. */
+  spawnOverrides?: { model?: string; thinkingLevel?: ThinkingLevel };
+  /** Pi semantic token for the type pill background and task path foreground. */
+  color?: string;
+  /** Optional literal Nerd Font glyph; displayed only when the labs setting is enabled. */
+  icon?: string;
+  tools?: { allow?: string[]; block?: string[] };
+  systemPrompt: string;
+  filePath?: string;
+  source?: "bundled" | "user" | "project";
+  /**
+   * How this definition is customized relative to its base.
+   * - fork: a full `<name>.md` copy (owns the system prompt).
+   * - override: a settings-only `<name>.yml` merged on top of the base
+   *   (no Markdown body; unset fields follow the base).
+   * Absent for pure bundled definitions and brand-new drafts.
+   */
+  customization?: {
+    kind: "fork" | "override";
+    scope: "user" | "project";
+    filePath: string;
+  };
+  /** Source of the base definition under the customization, if any. */
+  baseSource?: "bundled" | "user" | "project";
+  /** File path of the base definition under the customization, if any. */
+  baseFilePath?: string;
+}
+export type ThreadState = "starting" | "running" | "paused" | "completed" | "failed" | "stopped";
+export interface ThreadView {
+  path: string;
+  parent: string | null;
+  owner: string;
+  type: string;
+  color?: string;
+  icon?: string;
+  state: ThreadState;
+  task: string;
+  status: string;
+  output?: string;
+  error?: string;
+  createdAt: number;
+  updatedAt: number;
+  sessionFile?: string;
+  /** Frozen active time. Renderer adds `Date.now() - startedAt` while a run is active. */
+  elapsedMs?: number;
+  /** Current run start. Live only; omitted from saved views so reloads do not count offline time. */
+  startedAt?: number;
+  /** Cumulative input tokens, including cache read/write. Live views include the in-progress message. */
+  inputTokens?: number;
+  /** Cumulative output tokens. Live views include the in-progress message. */
+  outputTokens?: number;
+}
+export type DriverEvent =
+  | { kind: "activity" | "error"; text: string }
+  | {
+      kind: "checkpoint";
+      text: string;
+      sessionFile?: string;
+      sessionLeafId?: string | null;
+    }
+  | {
+      kind: "usage";
+      /** Cumulative own-assistant tokens for this driver instance, excluding inherited history. */
+      inputTokens: number;
+      outputTokens: number;
+      /** Streaming message_update snapshot. Omit for authoritative message_end. */
+      partial?: boolean;
+    };
+/** Ephemeral read-only transcript state; never part of registry/delivery events. */
+export interface TranscriptToolState {
+  toolCallId: string;
+  toolName: string;
+  parentToolCallId?: string;
+  args: unknown;
+  result?: unknown;
+  isError?: boolean;
+  state: "running" | "completed";
+}
+export interface TranscriptSnapshot {
+  revision: number;
+  /** Changes when a driver is replaced; revisions remain monotonic within the manager. */
+  generation: number;
+  messages: readonly AgentMessage[];
+  assistant: AgentMessage | null;
+  tools: readonly TranscriptToolState[];
+  inheritedCount: number;
+  thread?: ThreadView;
+  error?: string;
+}
+export interface TranscriptObservation {
+  snapshot: TranscriptSnapshot;
+  unsubscribe(): void;
+}
+export type TranscriptListener = (snapshot: TranscriptSnapshot) => void;
+
+export interface AgentDriver {
+  prompt(message: string): Promise<void>;
+  steer(message: string): Promise<void>;
+  snapshot(): AgentMessage[];
+  observeTranscript?(listener: TranscriptListener): TranscriptObservation;
+  output(): string;
+  abort(): Promise<void>;
+  dispose(): void;
+  sendUpdate(content: string): Promise<void> | void;
+  sessionFile?: string;
+  sessionLeafId?: string | null;
+}
+export interface DriverOptions {
+  path: string;
+  type: AgentType;
+  inherited: AgentMessage[];
+  tools: ToolDefinition[];
+  onEvent(event: DriverEvent): void;
+  shouldPause(): boolean;
+  parentPath: string | null;
+  sessionFile?: string;
+  /** Retained transcript of a nested lexical parent. Absent for /root and independent roots. */
+  parentSessionFile?: string;
+  sessionLeafId?: string | null;
+  signal: AbortSignal;
+}
+export interface SavedThreadView {
+  path: string;
+  parent: string | null;
+  owner: string;
+  type: string;
+  color?: string;
+  icon?: string;
+  state: ThreadState;
+  task: string;
+  status: string;
+  output?: string;
+  error?: string;
+  createdAt: number;
+  sessionFile?: string;
+  sessionLeafId?: string | null;
+  /** Frozen cumulative active time. `startedAt` is intentionally not persisted. */
+  elapsedMs?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+export interface SavedThread {
+  view: SavedThreadView;
+  definition: AgentType;
+  /** Reserved threads may not have a transcript yet; preserve their initial context. */
+  inherited?: AgentMessage[];
+}
+export interface ThreadService {
+  list(): ThreadView[];
+  get(path: string): ThreadView;
+  output(path: string): string;
+  transcript(path: string): Promise<string>;
+  /** Optional for portable adapters; the runtime manager always implements this. */
+  observeTranscript?(path: string, listener: TranscriptListener): Promise<TranscriptObservation>;
+  spawn(
+    args: {
+      path: string;
+      type: string;
+      task: string;
+      wait?: boolean;
+      model?: string;
+      thinkingLevel?: string;
+    },
+    signal?: AbortSignal,
+  ): Promise<ThreadView>;
+  steer(path: string, message: string): Promise<ThreadView>;
+  wait(path: string, timeoutMs?: number, signal?: AbortSignal): Promise<ThreadView>;
+  update(message: string): ThreadView;
+  pause(reason: string): ThreadView;
+  stop(path: string): Promise<ThreadView>;
+}
+export type DriverFactory = (options: DriverOptions) => Promise<AgentDriver>;
+export type ThreadEvent =
+  | { kind: "change"; thread: ThreadView }
+  | { kind: "metrics"; thread: ThreadView }
+  | { kind: "update"; thread: ThreadView; message: string; recipient: string }
+  | { kind: "settled"; thread: ThreadView; recipient: string };
+export interface ManagerOptions {
+  createDriver: DriverFactory;
+  rootSnapshot(): AgentMessage[];
+  getType(name: string): AgentType;
+  toolsFor(path: string): ToolDefinition[];
+  onEvent?(event: ThreadEvent): void;
+  /** Maximum levels including the main conversation as L1; defaults to 3. */
+  maxLevels?: number;
+  /** @deprecated Internal legacy path-depth override; prefer maxLevels. */
+  maxDepth?: number;
+  maxThreads?: number;
+  maxConcurrent?: number;
+}

package/src/subagents/ui/agent-navigation-editor.ts

@@ -0,0 +1,210 @@
+// @ts-nocheck: vendored upstream pi-subagent-manager 0.14.0 compiled under looser options; see src/subagents/VENDORED.md
+import {
+  CustomEditor,
+  type CustomEditorOptions,
+  type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+  getKeybindings,
+  Key,
+  matchesKey,
+  type EditorTheme,
+  type Keybinding,
+  type TUI,
+} from "@earendil-works/pi-tui";
+
+export interface AgentNavigationEditorOptions {
+  /** Must return the whole navigation interaction, so repeated Left cannot reopen it. */
+  openTree(): void | Promise<void>;
+  canOpen(): boolean;
+  /** Session-local widget collapse; never saves the configured display mode. */
+  collapseWidget?(): void | Promise<void>;
+  canCollapse?(): boolean;
+  /** Root ownership token; changing it invalidates queued transitions. */
+  generation(): unknown;
+  onError?(error: unknown): void;
+  /**
+   * Chronological user prompts for reload/new/resume/fork. Omit on startup:
+   * Pi hydrates the installed editor after the startup session_start event.
+   */
+  initialHistory?: readonly string[];
+}
+
+/**
+ * Physical arrow boundary adapter. It owns no session/history internals and never
+ * changes the draft. Install once per root UI lifecycle, not for tree navigation.
+ * Another custom editor occupies the same host slot; skip installation rather than stack.
+ */
+export class AgentNavigationEditor extends CustomEditor {
+  private pending: "left" | "right" | undefined;
+  private disposed = false;
+  private dispatchDepth = 0;
+  private inputEpoch = 0;
+  private pastePending = false;
+  private jumpPending = false;
+
+  constructor(
+    tui: TUI,
+    theme: EditorTheme,
+    private navigationKeys: KeybindingsManager,
+    private navigation: AgentNavigationEditorOptions,
+    options?: CustomEditorOptions,
+  ) {
+    super(tui, theme, navigationKeys, options);
+    // SessionStartEvent.reason distinguishes startup (host hydrates AFTER
+    // installation) from reload/replacement (explicit public hydration needed).
+    // Never infer replay from prompt text: intentional repetitions are valid.
+    for (const text of navigation.initialHistory ?? []) this.addToHistory(text);
+  }
+
+  /** Invalidates queued work without resetting a competing extension's editor. */
+  dispose(): void {
+    this.disposed = true;
+    this.inputEpoch++;
+  }
+
+  private ordinaryArrow(data: string, direction: "left" | "right"): boolean {
+    if (!matchesKey(data, direction === "left" ? Key.left : Key.right)) return false;
+    const action = direction === "left" ? "tui.editor.cursorLeft" : "tui.editor.cursorRight";
+    // Editor uses the global TUI bindings; CustomEditor uses the injected app
+    // manager. Both must agree, and a conflicting remap wins conservatively.
+    for (const keys of [this.navigationKeys, getKeybindings()]) {
+      if (!keys.matches(data, action)) return false;
+      for (const other of Object.keys(keys.getResolvedBindings())) {
+        if (
+          other !== action &&
+          (other.startsWith("tui.editor.") ||
+            other.startsWith("tui.input.") ||
+            other.startsWith("tui.altScreen.") ||
+            other.startsWith("app.")) &&
+          keys.matches(data, other as Keybinding)
+        )
+          return false;
+      }
+    }
+    return true;
+  }
+
+  override handleInput(data: string): void {
+    const outer = this.dispatchDepth === 0;
+    const direction = this.ordinaryArrow(data, "left") ? "left"
+      : this.ordinaryArrow(data, "right") ? "right" : undefined;
+    if (outer && (!direction || (this.pending && this.pending !== direction))) this.inputEpoch++;
+    const previousPaste = this.pastePending;
+    const wasPaste = previousPaste || data.includes("\x1b[200~");
+    // Update before dispatch: Pi recursively sends a suffix after the end
+    // marker through this.handleInput, and that suffix is no longer paste.
+    if (data.includes("\x1b[200~")) this.pastePending = true;
+    if (wasPaste && data.includes("\x1b[201~")) this.pastePending = false;
+    const wasJump = this.jumpPending;
+    const cursor = this.getCursor();
+    const text = this.getText();
+    const lines = text.split("\n");
+    const atBoundary = direction === "left"
+      ? cursor.line === 0 && cursor.col === 0
+      : direction === "right" && cursor.line === lines.length - 1 &&
+        cursor.col === lines.at(-1)!.length;
+    const eligible =
+      outer &&
+      direction !== undefined &&
+      this.focused &&
+      !this.disposed &&
+      !wasPaste &&
+      !wasJump &&
+      !this.isShowingAutocomplete() &&
+      atBoundary;
+    const generation = eligible ? this.navigation.generation() : undefined;
+    let changed = false;
+    let consumed = false;
+    const originalChange = this.onChange;
+    const originalShortcut = this.onExtensionShortcut;
+    const observeChange = (value: string) => {
+      changed = true;
+      originalChange?.call(this, value);
+    };
+    const observeShortcut = (value: string) => {
+      const handled = originalShortcut?.call(this, value) ?? false;
+      consumed ||= handled && value === data;
+      return handled;
+    };
+    this.onChange = observeChange;
+    this.onExtensionShortcut = observeShortcut;
+    this.dispatchDepth++;
+    try {
+      // Exactly one stock dispatch, preserving host-wired application controls.
+      super.handleInput(data);
+    } finally {
+      this.dispatchDepth--;
+      if (this.onChange === observeChange) this.onChange = originalChange;
+      if (this.onExtensionShortcut === observeShortcut) this.onExtensionShortcut = originalShortcut;
+      if (consumed) this.pastePending = previousPaste;
+      if (!consumed) {
+        // Track only public input; over-suppress when precedence is ambiguous.
+        // Recursive paste suffix dispatch updates guards, but never opens UI.
+        if (!wasPaste) {
+          const keys = getKeybindings();
+          const jump =
+            keys.matches(data, "tui.editor.jumpForward") ||
+            keys.matches(data, "tui.editor.jumpBackward");
+          this.jumpPending = !wasJump && jump;
+        }
+      }
+    }
+    const after = this.getCursor();
+    if (
+      eligible &&
+      !consumed &&
+      !changed &&
+      !this.isShowingAutocomplete() &&
+      this.getText() === text &&
+      after.line === cursor.line &&
+      after.col === cursor.col
+    ) {
+      this.queueNavigation(text, cursor, generation, direction!);
+    }
+  }
+
+  private queueNavigation(
+    text: string,
+    cursor: { line: number; col: number },
+    generation: unknown,
+    direction: "left" | "right",
+  ): void {
+    const allowed = () => direction === "left"
+      ? this.navigation.canOpen()
+      : !!this.navigation.collapseWidget && (this.navigation.canCollapse?.() ?? false);
+    if (this.pending || !allowed()) return;
+    this.pending = direction;
+    const epoch = this.inputEpoch;
+    queueMicrotask(() => {
+      const after = this.getCursor();
+      if (
+        this.disposed ||
+        !this.focused ||
+        this.inputEpoch !== epoch ||
+        this.navigation.generation() !== generation ||
+        !allowed() ||
+        this.isShowingAutocomplete() ||
+        this.getText() !== text ||
+        after.line !== cursor.line ||
+        after.col !== cursor.col
+      ) {
+        this.pending = undefined;
+        return;
+      }
+      try {
+        // Call within the checked microtask: an extra Promise.then would leave
+        // a gap in which root ownership could change after validation.
+        void Promise.resolve(direction === "left"
+          ? this.navigation.openTree() : this.navigation.collapseWidget!())
+          .catch((error: unknown) => this.navigation.onError?.(error))
+          .finally(() => {
+            this.pending = undefined;
+          });
+      } catch (error) {
+        this.pending = undefined;
+        this.navigation.onError?.(error);
+      }
+    });
+  }
+}