@ilya-lesikov/pi-pi 0.4.0 → 0.6.0

package/extensions/orchestrator/subagent-session-marker.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+
+// Documents the shared contract for Symbol.for("pi-pi:subagent-session") between
+// extensions/orchestrator/index.ts (writer) and 3p/pi-subagents/src/agent-runner.ts
+// (depth tracker). The canonical shape is { depth: number }; a legacy boolean true
+// must still be tolerated as depth 1. This mirrors agent-runner's read so a future
+// shape change on either side is caught.
+function readDepth(marker: unknown): number {
+  return typeof marker === "object" && marker !== null
+    ? ((marker as { depth?: number }).depth ?? 0)
+    : marker
+      ? 1
+      : 0;
+}
+
+describe("subagent-session marker contract", () => {
+  it("treats the orchestrator's { depth: 1 } write as depth 1 (truthy, not reset to 0)", () => {
+    const marker = { depth: 1 };
+    expect(readDepth(marker)).toBe(1);
+    expect(Boolean(marker)).toBe(true);
+  });
+
+  it("still tolerates a legacy boolean marker as depth 1", () => {
+    expect(readDepth(true)).toBe(1);
+  });
+
+  it("reports depth 0 when no marker is set", () => {
+    expect(readDepth(undefined)).toBe(0);
+  });
+
+  it("increments nesting from an existing object marker", () => {
+    const previous = { depth: 2 };
+    const next = { depth: readDepth(previous) + 1 };
+    expect(next.depth).toBe(3);
+  });
+});

package/extensions/orchestrator/test-helpers.ts

@@ -0,0 +1,217 @@
+import { expect } from "vitest";
+
+export type TextMatch = string | RegExp | ((value: string) => boolean);
+
+export interface MenuExpectation {
+  question?: TextMatch;
+  options?: {
+    exact?: TextMatch[];
+    include?: TextMatch[];
+    exclude?: TextMatch[];
+  };
+  choose: TextMatch | ((options: string[]) => string);
+}
+
+export interface MenuTranscriptEntry {
+  question: string;
+  options: Array<{ title: string; description?: string }>;
+  chosen: string;
+}
+
+export interface AskUserHarness {
+  transcript: MenuTranscriptEntry[];
+  expect(step: MenuExpectation): AskUserHarness;
+  handle(opts: any): Promise<{ kind: "selection"; selections: [string] }>;
+  assertDone(): void;
+}
+
+interface MenuOption {
+  title: string;
+  description?: string;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stringifyMatcher(matcher: TextMatch | undefined): string {
+  if (matcher === undefined) return "<none>";
+  if (typeof matcher === "string") return JSON.stringify(matcher);
+  if (matcher instanceof RegExp) return matcher.toString();
+  return "<function>";
+}
+
+function matchText(matcher: TextMatch, value: string): boolean {
+  if (typeof matcher === "string") return value === matcher;
+  if (matcher instanceof RegExp) return matcher.test(value);
+  return matcher(value);
+}
+
+function renderMenu(question: string, options: MenuOption[]): string {
+  const lines = options.map((option) => {
+    if (!option.description) return `- ${option.title}`;
+    return `- ${option.title} — ${option.description}`;
+  });
+  return `question=${JSON.stringify(question)}\noptions:\n${lines.join("\n")}`;
+}
+
+export function createAskUserHarness(): AskUserHarness {
+  const queue: MenuExpectation[] = [];
+  const transcript: MenuTranscriptEntry[] = [];
+
+  return {
+    transcript,
+    expect(step: MenuExpectation) {
+      queue.push(step);
+      return this;
+    },
+    async handle(opts: any) {
+      const question = String(opts?.question ?? "");
+      const options: MenuOption[] = (Array.isArray(opts?.options) ? opts.options : []).map((option: any): MenuOption => {
+        if (typeof option === "string") return { title: option };
+        return {
+          title: String(option?.title ?? ""),
+          description: option?.description === undefined ? undefined : String(option.description),
+        };
+      });
+      const titles: string[] = options.map((option: MenuOption) => option.title);
+
+      if (queue.length === 0) {
+        throw new Error(`Unexpected menu: ${renderMenu(question, options)}`);
+      }
+
+      const expected = queue.shift()!;
+
+      if (expected.question && !matchText(expected.question, question)) {
+        throw new Error(
+          `Question mismatch: expected ${stringifyMatcher(expected.question)}, actual ${JSON.stringify(question)}\n${renderMenu(question, options)}`,
+        );
+      }
+
+      if (expected.options?.include) {
+        for (const include of expected.options.include) {
+          const found = titles.some((title: string) => matchText(include, title));
+          if (!found) {
+            throw new Error(
+              `Missing expected option ${stringifyMatcher(include)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      if (expected.options?.exclude) {
+        for (const exclude of expected.options.exclude) {
+          const found = titles.some((title: string) => matchText(exclude, title));
+          if (found) {
+            throw new Error(
+              `Found excluded option ${stringifyMatcher(exclude)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      if (expected.options?.exact) {
+        expect(titles.length).toBe(expected.options.exact.length);
+        for (let i = 0; i < expected.options.exact.length; i += 1) {
+          const matcher = expected.options.exact[i]!;
+          const actual = titles[i] ?? "";
+          if (!matchText(matcher, actual)) {
+            throw new Error(
+              `Exact options mismatch at index ${i}: expected ${stringifyMatcher(matcher)}, actual ${JSON.stringify(actual)}\n${renderMenu(question, options)}`,
+            );
+          }
+        }
+      }
+
+      let chosen: string;
+      if (typeof expected.choose === "function") {
+        const maybeChoice = (expected.choose as (options: string[]) => unknown)(titles);
+        if (typeof maybeChoice === "string") {
+          chosen = maybeChoice;
+        } else {
+          const matcher = expected.choose as (value: string) => boolean;
+          const picked = titles.find((title: string) => matcher(title));
+          if (!picked) {
+            throw new Error(`No option matched chooser function\n${renderMenu(question, options)}`);
+          }
+          chosen = picked;
+        }
+      } else {
+        const picked = titles.find((title: string) => matchText(expected.choose as TextMatch, title));
+        if (!picked) {
+          throw new Error(
+            `No option matched chooser ${stringifyMatcher(expected.choose as TextMatch)}\n${renderMenu(question, options)}`,
+          );
+        }
+        chosen = picked;
+      }
+
+      if (!titles.includes(chosen)) {
+        throw new Error(`Chosen option not found: ${JSON.stringify(chosen)}\n${renderMenu(question, options)}`);
+      }
+
+      transcript.push({ question, options, chosen });
+
+      return { kind: "selection", selections: [chosen] };
+    },
+    assertDone() {
+      if (queue.length > 0) {
+        const next = queue[0]!;
+        throw new Error(
+          `Unconsumed menu expectations: ${queue.length}. Next expected question=${stringifyMatcher(next.question)} choose=${stringifyMatcher(
+            typeof next.choose === "function" ? undefined : next.choose,
+          )}`,
+        );
+      }
+    },
+  };
+}
+
+export const m = {
+  taskMenu: (type: string, phase: string) =>
+    (q: string) => q.includes(`Task: ${type}`) && q.includes(`Phase: ${phase}`),
+  anyTaskMenu: (q: string) => q.startsWith("/pp"),
+  preset: (name: string) => new RegExp(`^${escapeRegExp(name)}(?: \\[default\\])?$`),
+  autoReview: /^Auto review(?: \(pass \d+\))?$/,
+};
+
+export function expectActiveTaskNext(menu: AskUserHarness, choose: string): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Next"] }, choose: "Next" });
+  menu.expect({ question: "Next", options: { include: [choose] }, choose });
+}
+
+export function expectBrainstormToPlan(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Continue to plan & implement");
+  menu.expect({ question: "Planner preset", options: { include: [m.preset("regular"), "Back"] }, choose: m.preset("regular") });
+}
+
+export function expectPlanToImplement(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Continue to implement");
+}
+
+export function expectImplementToDone(menu: AskUserHarness): void {
+  expectActiveTaskNext(menu, "Complete");
+}
+
+export function expectQuickMenu(menu: AskUserHarness, choose: string): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: [choose] }, choose });
+}
+
+export function expectReviewAuto(menu: AskUserHarness, preset = "regular"): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Review"] }, choose: "Review" });
+  menu.expect({ question: "Review", options: { include: [m.autoReview] }, choose: m.autoReview });
+  menu.expect({ question: "Review preset", options: { include: [m.preset(preset), "Back"] }, choose: m.preset(preset) });
+}
+
+export function expectReviewOnMyOwn(menu: AskUserHarness): void {
+  menu.expect({ question: m.anyTaskMenu, options: { include: ["Review"] }, choose: "Review" });
+  menu.expect({ question: "Review", options: { include: ["Review on my own"] }, choose: "Review on my own" });
+}
+
+export function expectPpStartImplementAutonomous(menu: AskUserHarness): void {
+  menu.expect({ question: "/pp", options: { include: ["Task"] }, choose: "Task" });
+  menu.expect({ question: "Task", options: { include: ["Implement"] }, choose: "Implement" });
+  menu.expect({ question: "Implement", options: { include: ["New"] }, choose: "New" });
+  menu.expect({ question: "Mode", options: { include: ["Guided", "Autonomous", "Back"] }, choose: "Autonomous" });
+  menu.expect({ question: "Autonomous", options: { include: ["Start", "Back"] }, choose: "Start" });
+}

package/extensions/orchestrator/tracer.test.ts

@@ -0,0 +1,132 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, utimesSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { initTracer, finalizeTracer, getTracer } from "./tracer.js";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), "pi-pi-tracer-test-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function readLines(file: string): Record<string, any>[] {
+  if (!existsSync(file)) return [];
+  return readFileSync(file, "utf-8")
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l));
+}
+
+afterEach(() => {
+  finalizeTracer();
+  for (const dir of tempDirs.splice(0)) {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {}
+  }
+});
+
+describe("tracer", () => {
+  it("is a no-op when not initialized", () => {
+    expect(getTracer()).toBeUndefined();
+  });
+
+  it("creates per-session dir with main.jsonl and writes main events", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-abc");
+    const tracer = getTracer();
+    expect(tracer).toBeDefined();
+
+    tracer!.traceMain("before_agent_start", { prompt: "hello", systemPrompt: "sys" });
+    tracer!.traceMain("tool_execution_end", { toolCallId: "t1", result: { ok: true }, isError: false });
+
+    const dir = join(ppDir, "logs", "traces", "sess-abc");
+    expect(existsSync(join(dir, "main.jsonl"))).toBe(true);
+
+    const lines = readLines(join(dir, "main.jsonl"));
+    expect(lines[0].kind).toBe("before_agent_start");
+    expect(lines[0].prompt).toBe("hello");
+    expect(lines[0].systemPrompt).toBe("sys");
+    expect(lines[1].kind).toBe("tool_execution_end");
+    expect(lines[1].result).toEqual({ ok: true });
+  });
+
+  it("writes one file per subagent keyed by id, with prompts and full payloads", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-1");
+    const tracer = getTracer()!;
+
+    tracer.openSubagent({
+      subagentId: "agent-1",
+      type: "Explore",
+      description: "find stuff",
+      parentToolCallId: "call-9",
+      parentSubagentId: "root-agent",
+      depth: 2,
+      systemPrompt: "sub-sys",
+      effectivePrompt: "do the thing",
+    });
+    tracer.traceSubagent("agent-1", "tool_execution_start", { toolCallId: "x", toolName: "grep", args: { pattern: "foo" } });
+
+    const dir = join(ppDir, "logs", "traces", "sess-1");
+    const subLines = readLines(join(dir, "agent-1.jsonl"));
+    expect(subLines[0].kind).toBe("subagent_open");
+    expect(subLines[0].systemPrompt).toBe("sub-sys");
+    expect(subLines[0].effectivePrompt).toBe("do the thing");
+    expect(subLines[0].parentToolCallId).toBe("call-9");
+    expect(subLines[0].parentSubagentId).toBe("root-agent");
+    expect(subLines[0].depth).toBe(2);
+    expect(subLines[1].kind).toBe("tool_execution_start");
+    expect(subLines[1].args).toEqual({ pattern: "foo" });
+
+    const mainLines = readLines(join(dir, "main.jsonl"));
+    const spawned = mainLines.find((l) => l.kind === "subagent_spawned" && l.subagentId === "agent-1");
+    expect(spawned).toBeDefined();
+    expect(spawned!.parentToolCallId).toBe("call-9");
+    expect(spawned!.parentSubagentId).toBe("root-agent");
+  });
+
+  it("keeps concurrent subagents in separate files", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-2");
+    const tracer = getTracer()!;
+
+    tracer.openSubagent({ subagentId: "a", depth: 1 });
+    tracer.openSubagent({ subagentId: "b", depth: 1 });
+    tracer.traceSubagent("a", "turn_end", { turnIndex: 0 });
+    tracer.traceSubagent("b", "turn_end", { turnIndex: 0 });
+
+    const dir = join(ppDir, "logs", "traces", "sess-2");
+    expect(readLines(join(dir, "a.jsonl")).some((l) => l.kind === "turn_end")).toBe(true);
+    expect(readLines(join(dir, "b.jsonl")).some((l) => l.kind === "turn_end")).toBe(true);
+    expect(readLines(join(dir, "a.jsonl")).some((l) => l.subagentId === "b")).toBe(false);
+  });
+
+  it("finalize writes session_finalized and clears the tracer", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "sess-3");
+    const dir = join(ppDir, "logs", "traces", "sess-3");
+    finalizeTracer();
+    expect(getTracer()).toBeUndefined();
+    expect(readLines(join(dir, "main.jsonl")).some((l) => l.kind === "session_finalized")).toBe(true);
+  });
+
+  it("cleans up trace dirs older than 7 days", () => {
+    const ppDir = join(makeTempDir(), ".pp");
+    initTracer(ppDir, "old-session");
+    finalizeTracer();
+    const tracesRoot = join(ppDir, "logs", "traces");
+    const oldDir = join(tracesRoot, "old-session");
+    expect(existsSync(oldDir)).toBe(true);
+
+    const past = (Date.now() - 8 * 24 * 60 * 60 * 1000) / 1000;
+    utimesSync(oldDir, past, past);
+
+    initTracer(ppDir, "new-session");
+    expect(existsSync(oldDir)).toBe(false);
+    expect(existsSync(join(tracesRoot, "new-session"))).toBe(true);
+  });
+});

package/extensions/orchestrator/tracer.ts

@@ -0,0 +1,127 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from "fs";
+import { join } from "path";
+
+const TRACER_KEY = Symbol.for("pi-pi:tracer");
+
+export interface SubagentMeta {
+  subagentId: string;
+  type?: string;
+  description?: string;
+  parentToolCallId?: string;
+  parentSubagentId?: string;
+  depth: number;
+  systemPrompt?: string;
+  effectivePrompt?: string;
+}
+
+interface Tracer {
+  sessionId: string;
+  dir: string;
+  turnIndex: number;
+  traceMain(kind: string, payload: Record<string, unknown>): void;
+  openSubagent(meta: SubagentMeta): void;
+  traceSubagent(subagentId: string, kind: string, payload: Record<string, unknown>): void;
+  finalize(): void;
+}
+
+function sanitizeSessionId(sessionId: string): string {
+  return sessionId.replace(/[^a-zA-Z0-9_.-]/g, "_") || `session-${Date.now()}`;
+}
+
+function appendLine(file: string, obj: Record<string, unknown>): void {
+  try {
+    appendFileSync(file, JSON.stringify(obj) + "\n");
+  } catch {}
+}
+
+function cleanOldTraceDirs(tracesRoot: string, maxAgeDays: number): void {
+  try {
+    if (!existsSync(tracesRoot)) return;
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    for (const entry of readdirSync(tracesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const dirPath = join(tracesRoot, entry.name);
+      try {
+        if (statSync(dirPath).mtimeMs < cutoff) {
+          rmSync(dirPath, { recursive: true, force: true });
+        }
+      } catch {}
+    }
+  } catch {}
+}
+
+export function initTracer(ppDir: string, sessionId: string): void {
+  try {
+    const tracesRoot = join(ppDir, "logs", "traces");
+    mkdirSync(tracesRoot, { recursive: true });
+    cleanOldTraceDirs(tracesRoot, 7);
+
+    const safeId = sanitizeSessionId(sessionId);
+    const dir = join(tracesRoot, safeId);
+    mkdirSync(dir, { recursive: true });
+
+    const mainFile = join(dir, "main.jsonl");
+
+    const tracer: Tracer = {
+      sessionId,
+      dir,
+      turnIndex: -1,
+      traceMain(kind, payload) {
+        appendLine(mainFile, { ts: Date.now(), scope: "main", sessionId, kind, ...payload });
+      },
+      openSubagent(meta) {
+        const subFile = join(dir, `${sanitizeSessionId(meta.subagentId)}.jsonl`);
+        appendLine(subFile, {
+          ts: Date.now(),
+          scope: "subagent",
+          sessionId,
+          subagentId: meta.subagentId,
+          parentSubagentId: meta.parentSubagentId,
+          parentToolCallId: meta.parentToolCallId,
+          depth: meta.depth,
+          kind: "subagent_open",
+          type: meta.type,
+          description: meta.description,
+          systemPrompt: meta.systemPrompt,
+          effectivePrompt: meta.effectivePrompt,
+        });
+        appendLine(mainFile, {
+          ts: Date.now(),
+          scope: "main",
+          sessionId,
+          kind: "subagent_spawned",
+          subagentId: meta.subagentId,
+          parentSubagentId: meta.parentSubagentId,
+          parentToolCallId: meta.parentToolCallId,
+          depth: meta.depth,
+          type: meta.type,
+          description: meta.description,
+        });
+      },
+      traceSubagent(subagentId, kind, payload) {
+        const subFile = join(dir, `${sanitizeSessionId(subagentId)}.jsonl`);
+        appendLine(subFile, { ts: Date.now(), scope: "subagent", sessionId, subagentId, kind, ...payload });
+      },
+      finalize() {
+        appendLine(mainFile, { ts: Date.now(), scope: "main", sessionId, kind: "session_finalized" });
+      },
+    };
+
+    (globalThis as any)[TRACER_KEY] = tracer;
+  } catch {
+    (globalThis as any)[TRACER_KEY] = undefined;
+  }
+}
+
+export function getTracer(): Tracer | undefined {
+  return (globalThis as any)[TRACER_KEY];
+}
+
+export function finalizeTracer(): void {
+  const tracer = getTracer();
+  if (!tracer) return;
+  try {
+    tracer.finalize();
+  } catch {}
+  (globalThis as any)[TRACER_KEY] = undefined;
+}