@tt-a1i/openpi 0.1.0

package/extensions/shared/below-editor-navigation.ts

@@ -0,0 +1,343 @@
+import type {
+  AppKeybinding,
+  KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type {
+  AutocompleteProvider,
+  EditorComponent,
+  Focusable,
+} from "@earendil-works/pi-tui";
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+/** Shared focus bit used by an editor wrapper and its below-editor strip. */
+export class BelowEditorStripState {
+  focused = false;
+}
+
+export type BelowEditorStripInputAction = "focus" | "blur" | "open" | "next";
+
+/**
+ * Interpret the navigation state between the editor and one management strip.
+ * Unrecognized input blurs the strip and falls through to the editor, so the
+ * interaction never traps normal typing.
+ */
+export function belowEditorStripInput(options: {
+  data: string;
+  focused: boolean;
+  available: boolean;
+  editorEmpty: boolean;
+}): BelowEditorStripInputAction | undefined {
+  const { data, focused, available, editorEmpty } = options;
+  if (!focused) {
+    return available && editorEmpty && matchesKey(data, Key.down)
+      ? "focus"
+      : undefined;
+  }
+  if (
+    matchesKey(data, Key.up) ||
+    matchesKey(data, Key.left) ||
+    matchesKey(data, Key.escape)
+  ) {
+    return "blur";
+  }
+  if (matchesKey(data, Key.enter) || matchesKey(data, Key.right)) {
+    return "open";
+  }
+  if (matchesKey(data, Key.down)) return "next";
+  return undefined;
+}
+
+interface AppAwareEditor extends EditorComponent {
+  actionHandlers: Map<AppKeybinding, () => void>;
+  onEscape?: () => void;
+  onCtrlD?: () => void;
+  onPasteImage?: () => void;
+  onExtensionShortcut?: (data: string) => boolean;
+}
+
+function appAwareEditor(editor: EditorComponent): AppAwareEditor | undefined {
+  const candidate = editor as EditorComponent & Partial<AppAwareEditor>;
+  return candidate.actionHandlers instanceof Map
+    ? (candidate as AppAwareEditor)
+    : undefined;
+}
+
+/**
+ * Editor wrapper that owns keyboard focus while one below-editor strip is
+ * selected. Wrappers compose: Down on a focused outer strip advances to the
+ * next available nested strip, while Down on the final strip stays consumed.
+ */
+export class BelowEditorNavigationEditor implements EditorComponent, Focusable {
+  private readonly fallbackActions = new Map<AppKeybinding, () => void>();
+  private readonly base: EditorComponent;
+  private readonly keybindings: KeybindingsManager;
+  private readonly strip: BelowEditorStripState;
+  private readonly canManage: () => boolean;
+  private readonly open: () => void;
+  private readonly requestRender: () => void;
+  private fallbackEscape?: () => void;
+  private fallbackCtrlD?: () => void;
+  private fallbackPasteImage?: () => void;
+  private fallbackExtensionShortcut?: (data: string) => boolean;
+  private _focused = false;
+
+  constructor(
+    base: EditorComponent,
+    keybindings: KeybindingsManager,
+    strip: BelowEditorStripState,
+    canManage: () => boolean,
+    open: () => void,
+    requestRender: () => void,
+  ) {
+    this.base = base;
+    this.keybindings = keybindings;
+    this.strip = strip;
+    this.canManage = canManage;
+    this.open = open;
+    this.requestRender = requestRender;
+  }
+
+  get focused() {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    const child = this.base as EditorComponent & Partial<Focusable>;
+    if (typeof child.focused === "boolean") child.focused = value;
+  }
+
+  get wantsKeyRelease() {
+    return this.base.wantsKeyRelease;
+  }
+
+  // Pi recognizes these properties as CustomEditor-compatible and copies all
+  // app-level handlers onto the outermost wrapper.
+  get actionHandlers() {
+    return appAwareEditor(this.base)?.actionHandlers ?? this.fallbackActions;
+  }
+
+  get onExtensionShortcut() {
+    return (
+      appAwareEditor(this.base)?.onExtensionShortcut ??
+      this.fallbackExtensionShortcut
+    );
+  }
+
+  set onExtensionShortcut(value: ((data: string) => boolean) | undefined) {
+    const child = appAwareEditor(this.base);
+    if (child) child.onExtensionShortcut = value;
+    else this.fallbackExtensionShortcut = value;
+  }
+
+  get onEscape() {
+    return appAwareEditor(this.base)?.onEscape ?? this.fallbackEscape;
+  }
+
+  set onEscape(value: (() => void) | undefined) {
+    const child = appAwareEditor(this.base);
+    if (child) child.onEscape = value;
+    else this.fallbackEscape = value;
+  }
+
+  get onCtrlD() {
+    return appAwareEditor(this.base)?.onCtrlD ?? this.fallbackCtrlD;
+  }
+
+  set onCtrlD(value: (() => void) | undefined) {
+    const child = appAwareEditor(this.base);
+    if (child) child.onCtrlD = value;
+    else this.fallbackCtrlD = value;
+  }
+
+  get onPasteImage() {
+    return appAwareEditor(this.base)?.onPasteImage ?? this.fallbackPasteImage;
+  }
+
+  set onPasteImage(value: (() => void) | undefined) {
+    const child = appAwareEditor(this.base);
+    if (child) child.onPasteImage = value;
+    else this.fallbackPasteImage = value;
+  }
+
+  get onSubmit() {
+    return this.base.onSubmit;
+  }
+
+  set onSubmit(value: ((text: string) => void) | undefined) {
+    this.base.onSubmit = value;
+  }
+
+  get onChange() {
+    return this.base.onChange;
+  }
+
+  set onChange(value: ((text: string) => void) | undefined) {
+    this.base.onChange = value;
+  }
+
+  get borderColor() {
+    return this.base.borderColor;
+  }
+
+  set borderColor(value: ((text: string) => string) | undefined) {
+    this.base.borderColor = value;
+  }
+
+  hasFocusedStrip(): boolean {
+    return (
+      this.strip.focused ||
+      (this.nestedNavigation()?.hasFocusedStrip() ?? false)
+    );
+  }
+
+  blurAllStrips() {
+    this.strip.focused = false;
+    this.nestedNavigation()?.blurAllStrips();
+  }
+
+  /** Focus this strip, or the first available nested strip when it is hidden. */
+  focusAvailableStrip(): boolean {
+    if (this.canManage()) {
+      this.strip.focused = true;
+      return true;
+    }
+    return this.nestedNavigation()?.focusAvailableStrip() ?? false;
+  }
+
+  private nestedNavigation() {
+    return this.base instanceof BelowEditorNavigationEditor
+      ? this.base
+      : undefined;
+  }
+
+  handleInput(data: string) {
+    const nested = this.nestedNavigation();
+    if (!this.strip.focused && nested?.hasFocusedStrip()) {
+      // Availability is dynamic: if an outer strip appears after a nested one
+      // gained focus, Down cycles to the newly visible peer instead of being
+      // consumed forever by the old focus owner.
+      if (this.canManage() && matchesKey(data, Key.down)) {
+        nested.blurAllStrips();
+        this.strip.focused = true;
+        this.requestRender();
+        return;
+      }
+      this.base.handleInput(data);
+      return;
+    }
+    const action = belowEditorStripInput({
+      data,
+      focused: this.strip.focused,
+      available: this.canManage(),
+      editorEmpty: this.base.getText().length === 0,
+    });
+    if (action) {
+      if (action === "focus") this.strip.focused = true;
+      if (action === "blur") this.strip.focused = false;
+      if (action === "open") {
+        this.strip.focused = false;
+        this.open();
+      }
+      if (action === "next") {
+        this.strip.focused = false;
+        if (!this.nestedNavigation()?.focusAvailableStrip()) {
+          this.strip.focused = true;
+        }
+      }
+      this.requestRender();
+      return;
+    }
+    if (this.strip.focused) {
+      this.strip.focused = false;
+      this.requestRender();
+    }
+
+    const child = appAwareEditor(this.base);
+    if (!child) {
+      if (this.onExtensionShortcut?.(data)) return;
+      if (this.keybindings.matches(data, "app.clipboard.pasteImage")) {
+        this.fallbackPasteImage?.();
+        return;
+      }
+      if (this.keybindings.matches(data, "app.interrupt")) {
+        this.fallbackEscape?.();
+        return;
+      }
+      if (
+        this.keybindings.matches(data, "app.exit") &&
+        this.base.getText().length === 0
+      ) {
+        this.fallbackCtrlD?.();
+        return;
+      }
+      for (const [binding, handler] of this.fallbackActions) {
+        if (!this.keybindings.matches(data, binding)) continue;
+        if (binding === "app.exit" && this.base.getText().length > 0) break;
+        handler();
+        return;
+      }
+    }
+    this.base.handleInput(data);
+  }
+
+  render(width: number) {
+    return this.base.render(width);
+  }
+
+  invalidate() {
+    this.base.invalidate();
+  }
+
+  getText() {
+    return this.base.getText();
+  }
+
+  getExpandedText() {
+    return this.base.getExpandedText?.() ?? this.base.getText();
+  }
+
+  setText(text: string) {
+    this.strip.focused = false;
+    this.base.setText(text);
+  }
+
+  addToHistory(text: string) {
+    this.base.addToHistory?.(text);
+  }
+
+  insertTextAtCursor(text: string) {
+    this.base.insertTextAtCursor?.(text);
+  }
+
+  setAutocompleteProvider(provider: AutocompleteProvider) {
+    this.base.setAutocompleteProvider?.(provider);
+  }
+
+  setPaddingX(padding: number) {
+    this.base.setPaddingX?.(padding);
+  }
+
+  setAutocompleteMaxVisible(maxVisible: number) {
+    this.base.setAutocompleteMaxVisible?.(maxVisible);
+  }
+}
+
+/** Fit a left label and right metrics into exactly one bounded terminal row. */
+export function fitNavigationSides(left: string, right: string, width: number) {
+  const boundedRight = truncateToWidth(right, Math.max(0, width - 4), "…");
+  const rightWidth = visibleWidth(boundedRight);
+  const leftWidth = Math.max(0, width - rightWidth - 1);
+  const boundedLeft = truncateToWidth(left, leftWidth, "…");
+  const gap = Math.max(1, width - visibleWidth(boundedLeft) - rightWidth);
+  return truncateToWidth(
+    boundedLeft + " ".repeat(gap) + boundedRight,
+    width,
+    "",
+  );
+}

package/extensions/shared/child-session.ts

@@ -0,0 +1,352 @@
+import * as path from "node:path";
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  ProjectTrustStore,
+  SettingsManager,
+  type AgentSession,
+  type SessionShutdownEvent,
+} from "@earendil-works/pi-coding-agent";
+
+export const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
+
+/**
+ * The only package tools a headless child may keep. Read-only discovery tools
+ * are safe for children; every other tool this package registers is parent-only
+ * because it orchestrates work, mutates shared runtime state, drives the parent
+ * UI, or asks the user. This is the allowlist half of a fail-closed boundary:
+ * anything registered by this package and not listed here MUST be excluded, and
+ * `child-session.test.ts` scans the extensions to enforce exactly that — so a
+ * future tool cannot silently leak into children by being forgotten. The scan
+ * covers both inline-named registrations and factory-style ones (e.g.
+ * `registerTool(createEditToolDefinition(...))`); an unrecognized factory
+ * registration fails the guard rather than escaping it.
+ */
+export const CHILD_SAFE_PACKAGE_TOOL_NAMES = ["fd", "rg"] as const;
+
+/**
+ * pi-intercom resources are unsafe inside concurrent in-process child sessions.
+ * It stores session identity and optional supervisor bridge metadata in
+ * process.env, which is shared by every Direct/Workflow child in this process.
+ * Loading it in children can therefore cross-wire identities; the parent
+ * extension remains loaded and fully usable.
+ */
+function isPiIntercomNpmResource(resource: {
+  resolvedPath?: string;
+  filePath?: string;
+}) {
+  const resourcePath = resource.resolvedPath ?? resource.filePath;
+  if (!resourcePath) return false;
+  const segments = path.resolve(resourcePath).split(path.sep);
+  return segments.some(
+    (segment, index) =>
+      segment === "node_modules" && segments[index + 1] === "pi-intercom",
+  );
+}
+
+/**
+ * Tools that headless children must not receive. Children run without a UI and
+ * cannot orchestrate, so every parent-only tool this package ships is denied.
+ * Grouped by owning extension; keep in sync with the extensions (guarded by the
+ * drift test in child-session.test.ts).
+ */
+export const CHILD_EXCLUDED_TOOL_NAMES = [
+  // subagents — children cannot spawn/observe more agents
+  "subagent_spawn",
+  "subagent_wait",
+  "subagent_cancel",
+  "subagent_send",
+  "subagent_check",
+  "subagent_list",
+  // workflows — children cannot recursively orchestrate or manage runs
+  "workflow",
+  "workflow_stop",
+  "workflow_status",
+  // ask-user — headless children have no user to ask or handoff to
+  "ask_user",
+  "human_handoff",
+  // plan-mode — completion controls the parent session's write gate and UI
+  "plan_ready",
+  // tasks — the parent session owns its work-intent ledger
+  "tasks_add",
+  "tasks_update",
+  "tasks_list",
+  // goal — the parent session owns its persistent goal
+  "get_goal",
+  "create_goal",
+  "update_goal",
+  // setup — configuration is a package-owned, parent-only choice
+  "configure_my_pi_setup",
+  // background-terminals — a child's processes would be invisible to the
+  // parent's /ps and could outlive the child, so children cannot start them
+  "bg_start",
+  "bg_status",
+  "bg_list",
+  "bg_kill",
+  "bg_watch",
+  // context-pivot — compaction of the conversation is a parent-only decision
+  "context_pivot",
+] as const;
+
+/**
+ * Fresh SDK options avoid turning the denylist into an accidental allowlist.
+ *
+ * `tools` narrows further, for an agent type that fixes a child's capabilities
+ * (see `../subagents/src/agent-types.ts`). It can only ever REMOVE: pi admits a
+ * tool when `(!allowed || allowed.has(name)) && !excluded.has(name)`, so an
+ * allowlist naming an excluded tool still cannot obtain it, and the boundary
+ * above stays authoritative. Omitting `tools` keeps today's behavior.
+ *
+ * Remove parent-only tools before exposing or enforcing a requested allowlist.
+ * Undefined preserves the normal child tool set; an empty array deliberately
+ * means no tools.
+ */
+export function effectiveChildToolAllowlist(tools?: readonly string[]) {
+  return tools?.filter(
+    (tool) => !CHILD_EXCLUDED_TOOL_NAMES.includes(tool as never),
+  );
+}
+
+export function childToolPolicy(tools?: readonly string[]) {
+  const effectiveTools = effectiveChildToolAllowlist(tools);
+  return {
+    excludeTools: [...CHILD_EXCLUDED_TOOL_NAMES],
+    ...(effectiveTools ? { tools: effectiveTools } : {}),
+  };
+}
+
+export interface ChildResourceOptions {
+  cwd: string;
+  projectTrusted: boolean;
+  appendSystemPrompt?: string[];
+  agentDir?: string;
+}
+
+/** Load normal global/package resources and trust-gated project resources. */
+export async function createChildResources(options: ChildResourceOptions) {
+  const agentDir = options.agentDir ?? getAgentDir();
+  const settingsManager = SettingsManager.create(options.cwd, agentDir, {
+    projectTrusted: options.projectTrusted,
+  });
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+    ...(options.appendSystemPrompt
+      ? { appendSystemPrompt: options.appendSystemPrompt }
+      : {}),
+    extensionsOverride: (base) => ({
+      ...base,
+      extensions: base.extensions.filter(
+        (extension) => !isPiIntercomNpmResource(extension),
+      ),
+    }),
+    skillsOverride: (base) => ({
+      ...base,
+      skills: base.skills.filter((skill) => !isPiIntercomNpmResource(skill)),
+    }),
+  });
+  await loader.reload();
+  return { loader, settingsManager };
+}
+
+/**
+ * Whether Pi's persisted trust store explicitly trusts this directory (or a
+ * containing one). Unreadable or invalid trust data fails closed.
+ *
+ * Use this when no live trust decision exists yet — notably at extension
+ * registration, which runs before `session_start`.
+ */
+export function isProjectTrustedOnDisk(cwd: string, agentDir?: string) {
+  try {
+    const trustStore = new ProjectTrustStore(agentDir ?? getAgentDir());
+    return trustStore.get(cwd) === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Same-directory children inherit the live parent decision. An alternate cwd
+ * is trusted only when Pi's persisted trust store explicitly trusts it (or a
+ * containing directory); unreadable/invalid trust data fails closed.
+ */
+export function resolveStandaloneChildProjectTrust(options: {
+  parentCwd: string;
+  childCwd: string;
+  parentTrusted: boolean;
+  agentDir?: string;
+}) {
+  if (path.resolve(options.childCwd) === path.resolve(options.parentCwd)) {
+    return options.parentTrusted;
+  }
+  return isProjectTrustedOnDisk(options.childCwd, options.agentDir);
+}
+
+interface ChildSessionStartup {
+  bindExtensions(bindings: { mode: "print" }): Promise<void>;
+  getActiveToolNames(): string[];
+}
+
+function boundedToolNames(names: readonly string[]) {
+  const shown = names
+    .slice(0, 8)
+    .map((name) => JSON.stringify(name.slice(0, 128)))
+    .join(", ");
+  return names.length > 8 ? `${shown}, and ${names.length - 8} more` : shown;
+}
+
+/**
+ * Start child extensions, then fail before the first prompt if an explicit
+ * allowlist names a tool that the final bound registry cannot actually expose.
+ * Parent-only names are deliberately ignored here: the denylist remains
+ * authoritative, so naming one can never turn this check into a grant.
+ */
+export async function bindChildSessionExtensions(
+  session: ChildSessionStartup,
+  requestedTools?: readonly string[],
+) {
+  await session.bindExtensions({ mode: "print" });
+  const requested = effectiveChildToolAllowlist(requestedTools);
+  if (!requested) return;
+
+  const active = new Set(session.getActiveToolNames());
+  const missing = [...new Set(requested)].filter((name) => !active.has(name));
+  if (missing.length === 0) return;
+
+  throw new Error(
+    `Child tool preflight failed: requested tool${missing.length === 1 ? "" : "s"} ${boundedToolNames(missing)} ${missing.length === 1 ? "is" : "are"} unavailable after child extensions initialized. Check the Agent Type tools list and child extension loading.`,
+  );
+}
+
+interface ChildExtensionRunner {
+  hasHandlers(eventType: string): boolean;
+  emit(event: SessionShutdownEvent): Promise<unknown>;
+}
+
+export interface DisposableChildSession {
+  readonly extensionRunner: ChildExtensionRunner;
+  abort?(): Promise<unknown>;
+  dispose(): void;
+}
+
+export interface ChildShutdownResult {
+  ok: boolean;
+  errors: string[];
+  timedOut: boolean;
+}
+
+const childShutdowns = new WeakMap<object, Promise<ChildShutdownResult>>();
+
+function shutdownError(error: unknown) {
+  return (error instanceof Error ? error.message : String(error)).slice(
+    0,
+    4096,
+  );
+}
+
+/** Await an operation but never longer than `timeoutMs`; return whether it settled. */
+export async function waitBounded(
+  operation: Promise<unknown>,
+  timeoutMs: number,
+) {
+  const result = await waitUntil(
+    operation,
+    Date.now() + timeoutMs,
+    "Operation",
+  );
+  return !result.timedOut;
+}
+
+/** Await an operation until a shared deadline and retain failure information. */
+async function waitUntil(
+  operation: Promise<unknown>,
+  deadline: number,
+  label: string,
+): Promise<{ error?: string; timedOut: boolean }> {
+  const remaining = Math.max(0, deadline - Date.now());
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<{ error: string; timedOut: true }>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ error: `${label} timed out`, timedOut: true }),
+      remaining,
+    );
+    timer.unref?.();
+  });
+  const completed = operation.then(
+    () => ({ timedOut: false as const }),
+    (error) => ({
+      error: `${label} failed: ${shutdownError(error)}`,
+      timedOut: false as const,
+    }),
+  );
+  const result = await Promise.race([completed, timeout]);
+  if (timer) clearTimeout(timer);
+  return result;
+}
+
+/**
+ * Request abort when needed, emit child session_shutdown once, and dispose
+ * once. The whole sequence shares one deadline and reports timeout/failure
+ * instead of silently turning failed cleanup into success.
+ */
+export function shutdownAndDisposeChildSession(
+  session: DisposableChildSession,
+  options: {
+    timeoutMs?: number;
+    abort?: boolean;
+    abortOperation?: Promise<unknown>;
+  } = {},
+) {
+  const existing = childShutdowns.get(session);
+  if (existing) return existing;
+
+  const shutdown = (async (): Promise<ChildShutdownResult> => {
+    const errors: string[] = [];
+    let timedOut = false;
+    const deadline =
+      Date.now() + (options.timeoutMs ?? CHILD_SHUTDOWN_TIMEOUT_MS);
+
+    if (options.abort || options.abortOperation) {
+      let abortOperation = options.abortOperation;
+      try {
+        abortOperation ??= session.abort?.();
+      } catch (error) {
+        errors.push(`Agent abort failed: ${shutdownError(error)}`);
+      }
+      if (abortOperation) {
+        const result = await waitUntil(abortOperation, deadline, "Agent abort");
+        if (result.error) errors.push(result.error);
+        timedOut ||= result.timedOut;
+      }
+    }
+
+    try {
+      if (session.extensionRunner.hasHandlers("session_shutdown")) {
+        const result = await waitUntil(
+          session.extensionRunner.emit({
+            type: "session_shutdown",
+            reason: "quit",
+          }),
+          deadline,
+          "Child session shutdown",
+        );
+        if (result.error) errors.push(result.error);
+        timedOut ||= result.timedOut;
+      }
+    } catch (error) {
+      errors.push(`Child session shutdown failed: ${shutdownError(error)}`);
+    }
+
+    try {
+      session.dispose();
+    } catch (error) {
+      errors.push(`Child session disposal failed: ${shutdownError(error)}`);
+    }
+
+    return { ok: errors.length === 0, errors, timedOut };
+  })();
+
+  childShutdowns.set(session, shutdown);
+  return shutdown;
+}