@tt-a1i/openpi 0.1.0

package/extensions/subagents/src/backends/stub.ts

@@ -0,0 +1,296 @@
+/**
+ * Scripted stub sessions, test-only: they stand in for the pi backend so the
+ * manager can be driven without a real child session. A stub session:
+ *
+ * - streams a plausible turn (thinking deltas, one fake tool cycle, text
+ *   deltas, usage ramp, a final assistant message, RunSettled) over a few
+ *   seconds so streaming UI, wait, and the footer counters are observable;
+ * - supports send() while running (queued-steer rendering) and while idle
+ *   (fresh run);
+ * - supports interrupt (RunSettled Interrupted -> status "error", matching v1);
+ * - fails the run when the prompt starts with "FAIL:", and refuses to spawn
+ *   at all when it starts with "SPAWNFAIL:" (error-path testing);
+ * - appends every event to a JSONL "session file" in tmpdir so the
+ *   "full transcript in session file" pointers resolve.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Cause, Scope } from "effect";
+import { Duration, Effect, Fiber, Queue, Ref, Stream } from "effect";
+import type { SubagentBackend, SubagentSession } from "../backend.ts";
+import type {
+  BackendName,
+  QueuedMessage,
+  SpawnTask,
+  SubagentEvent,
+  SubagentMeta,
+} from "../domain.ts";
+import { SendError, SpawnError } from "../domain.ts";
+
+export interface StubProfile {
+  readonly backend: BackendName;
+  readonly defaultModelLabel: string;
+  readonly contextWindow: number;
+  readonly toolName: string;
+  /** Delay between scripted events; varies per backend so streams differ. */
+  readonly cadenceMs: number;
+}
+
+const STUB_DIR = path.join(os.tmpdir(), "subagents-stub");
+let sessionCounter = 0;
+
+export function makeStubBackend(profile: StubProfile): SubagentBackend {
+  return {
+    name: profile.backend,
+    spawn: (task) =>
+      task.prompt.startsWith("SPAWNFAIL:")
+        ? Effect.fail(new SpawnError({ message: "stub refused to spawn" }))
+        : makeStubSession(profile, task),
+  };
+}
+
+function firstLine(text: string): string {
+  return (
+    text
+      .split("\n")
+      .find((line) => line.trim())
+      ?.trim() ?? ""
+  );
+}
+
+function chunked(text: string, size: number): string[] {
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += size)
+    chunks.push(text.slice(i, i + size));
+  return chunks;
+}
+
+const makeStubSession = (
+  profile: StubProfile,
+  task: SpawnTask,
+): Effect.Effect<SubagentSession, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const sessionId = `stub-${profile.backend}-${++sessionCounter}`;
+    const sessionFile = path.join(STUB_DIR, `${sessionId}.jsonl`);
+
+    const state = {
+      meta: {
+        backend: profile.backend,
+        modelLabel: task.model ?? profile.defaultModelLabel,
+        contextWindow: profile.contextWindow,
+        sessionFilePath: sessionFile,
+      } satisfies SubagentMeta as SubagentMeta,
+      pending: [] as string[],
+      turnCount: 0,
+      closed: false,
+      /** True between the driver dequeuing a prompt and registering its turn fiber. */
+      dispatching: false,
+    };
+
+    const events = yield* Queue.make<SubagentEvent, Cause.Done>();
+    const inbox = yield* Queue.make<string, Cause.Done>();
+    const activeTurn = yield* Ref.make<Fiber.Fiber<void> | undefined>(
+      undefined,
+    );
+
+    const emit = (event: SubagentEvent) =>
+      Effect.suspend(() => {
+        try {
+          fs.appendFileSync(sessionFile, `${JSON.stringify(event)}\n`);
+        } catch {
+          // The fake session file is best-effort.
+        }
+        if (event._tag === "MetaChanged") {
+          state.meta = { ...state.meta, ...event.meta };
+        }
+        return Queue.offer(events, event);
+      }).pipe(Effect.asVoid);
+
+    const pause = Effect.sleep(Duration.millis(profile.cadenceMs));
+
+    const runTurn = (userText: string, turn: number) =>
+      Effect.gen(function* () {
+        yield* emit({ _tag: "RunStarted" });
+        const failing = userText.trimStart().startsWith("FAIL:");
+
+        const thinking = "Looking at the task and planning an approach...";
+        for (const delta of chunked(thinking, 16)) {
+          yield* emit({ _tag: "AssistantDelta", kind: "thinking", delta });
+          yield* pause;
+        }
+
+        const toolId = `${sessionId}-tool-${turn}`;
+        const argsPreview = `{"command":"ls ${task.cwd}"}`;
+        yield* emit({
+          _tag: "AssistantMessage",
+          parts: [
+            { type: "thinking", text: thinking },
+            {
+              type: "text",
+              text: `I'll run ${profile.toolName} to look around first.`,
+            },
+            { type: "toolCall", toolId, name: profile.toolName, argsPreview },
+          ],
+        });
+        yield* emit({
+          _tag: "ToolStart",
+          toolId,
+          name: profile.toolName,
+          argsPreview,
+        });
+        yield* pause;
+        yield* emit({
+          _tag: "ToolUpdate",
+          toolId,
+          outputPreview: "src docs package.json",
+        });
+        yield* pause;
+        yield* emit({
+          _tag: "ToolEnd",
+          toolId,
+          name: profile.toolName,
+          isError: false,
+          outputPreview: "src docs package.json",
+        });
+        yield* emit({
+          _tag: "UsageChanged",
+          tokens: Math.min(profile.contextWindow, 2400 * (turn + 1)),
+          contextWindow: profile.contextWindow,
+        });
+
+        if (failing) {
+          yield* pause;
+          yield* emit({
+            _tag: "RunSettled",
+            outcome: {
+              _tag: "Failed",
+              errorText: `[stub:${profile.backend}] task failed as requested by FAIL: prefix`,
+            },
+          });
+          return;
+        }
+
+        const finalText =
+          `[stub:${profile.backend}] completed: ${firstLine(userText).slice(0, 200)}\n\n` +
+          `This is a stubbed ${profile.backend} subagent turn ${turn + 1}. ` +
+          `The real backend integration will replace this scripted output.`;
+        for (const delta of chunked(finalText, 24)) {
+          yield* emit({ _tag: "AssistantDelta", kind: "text", delta });
+          yield* pause;
+        }
+        yield* emit({
+          _tag: "AssistantMessage",
+          parts: [{ type: "text", text: finalText }],
+        });
+        yield* emit({
+          _tag: "UsageChanged",
+          tokens: Math.min(profile.contextWindow, 2400 * (turn + 1) + 900),
+          contextWindow: profile.contextWindow,
+        });
+        yield* emit({
+          _tag: "RunSettled",
+          outcome: { _tag: "Completed", finalText },
+        });
+      });
+
+    const queuedView = (): ReadonlyArray<QueuedMessage> =>
+      state.pending.map((text) => ({ text, kind: "steer" as const }));
+
+    // Driver: one turn at a time, in submission order. Turns run as child
+    // fibers so interrupt() stops the turn without killing the driver.
+    const driver = Effect.gen(function* () {
+      while (true) {
+        const text = yield* Queue.take(inbox);
+        state.dispatching = true;
+        state.pending.shift();
+        yield* emit({ _tag: "QueueChanged", queued: queuedView() });
+        yield* emit({ _tag: "UserMessage", text });
+        const turn = state.turnCount++;
+        const fiber = yield* Effect.forkChild(
+          runTurn(text, turn).pipe(
+            Effect.onInterrupt(() =>
+              emit({
+                _tag: "RunSettled",
+                outcome: { _tag: "Interrupted" },
+              }).pipe(Effect.ignore),
+            ),
+          ),
+        );
+        yield* Ref.set(activeTurn, fiber);
+        state.dispatching = false;
+        yield* Fiber.await(fiber);
+        yield* Ref.set(activeTurn, undefined);
+      }
+    });
+    yield* Effect.forkScoped(driver.pipe(Effect.ignore));
+
+    yield* Effect.addFinalizer(() =>
+      Effect.gen(function* () {
+        state.closed = true;
+        yield* Queue.end(inbox).pipe(Effect.ignore);
+        yield* Queue.end(events).pipe(Effect.ignore);
+      }),
+    );
+
+    const submit = (text: string) =>
+      Effect.gen(function* () {
+        if (state.closed) {
+          return yield* new SendError({
+            message: "Subagent session is closed.",
+          });
+        }
+        state.pending.push(text);
+        const busy = (yield* Ref.get(activeTurn)) !== undefined;
+        if (busy) {
+          // Show the queued steer line until the driver picks it up.
+          yield* emit({ _tag: "QueueChanged", queued: queuedView() });
+        }
+        yield* Queue.offer(inbox, text);
+      });
+
+    // Announce metadata, then kick off the initial run.
+    yield* Effect.try(() => fs.mkdirSync(STUB_DIR, { recursive: true })).pipe(
+      Effect.ignore, // The fake session file directory is best-effort.
+    );
+    yield* emit({ _tag: "MetaChanged", meta: state.meta });
+    // The session cannot be closed yet, so the initial submit cannot fail.
+    yield* submit(task.prompt).pipe(Effect.orDie);
+
+    return {
+      meta: Effect.sync(() => state.meta),
+      events: Stream.fromQueue(events),
+      send: submit,
+      interrupt: Effect.gen(function* () {
+        // Drop queued prompts so interrupting cannot immediately start
+        // another turn, then stop the active turn. A prompt may be mid-flight
+        // between the driver dequeuing it and registering its fiber, so wait
+        // that window out instead of silently missing the turn.
+        const cleared = yield* Queue.clear(inbox).pipe(
+          Effect.orElseSucceed(() => []),
+        );
+        state.pending = [];
+        yield* emit({ _tag: "QueueChanged", queued: [] });
+        while (true) {
+          const fiber = yield* Ref.get(activeTurn);
+          if (fiber) {
+            yield* Fiber.interrupt(fiber);
+            return;
+          }
+          if (!state.dispatching) {
+            // No turn ever started. If we cancelled queued prompts, the run
+            // still needs a terminal event or it would look running forever.
+            if (cleared.length > 0) {
+              yield* emit({
+                _tag: "RunSettled",
+                outcome: { _tag: "Interrupted" },
+              });
+            }
+            return;
+          }
+          yield* Effect.sleep(Duration.millis(5));
+        }
+      }),
+    } satisfies SubagentSession;
+  });

package/extensions/subagents/src/by-the-way.ts

@@ -0,0 +1,21 @@
+import type { SubagentOrigin } from "./domain.ts";
+
+export const BTW_TITLE_MAX_LENGTH = 60;
+
+/** Build a compact dashboard title from the first non-empty prompt line. */
+export function deriveBtwTitle(prompt: string) {
+  const firstLine = prompt
+    .split("\n")
+    .find((line) => line.trim())
+    ?.trim();
+  const title = firstLine?.replace(/\s+/g, " ") ?? "";
+  if (!title) return "by the way";
+  const codePoints = Array.from(title);
+  if (codePoints.length <= BTW_TITLE_MAX_LENGTH) return title;
+  return `${codePoints.slice(0, BTW_TITLE_MAX_LENGTH - 1).join("")}…`;
+}
+
+/** User asides remain visible in the dashboard but hidden from model tools. */
+export function isModelVisible(snap: { readonly origin: SubagentOrigin }) {
+  return snap.origin === "model";
+}

package/extensions/subagents/src/domain.ts

@@ -0,0 +1,271 @@
+/**
+ * Domain model for subagents.
+ *
+ * Everything downstream of a backend (manager, tools, UI) speaks only these
+ * types. A backend translates its native stream (pi session events) into the
+ * normalized `SubagentEvent` union.
+ */
+
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { Data } from "effect";
+
+export const BACKEND_NAMES = ["pi"] as const;
+export type BackendName = (typeof BACKEND_NAMES)[number];
+
+/** Who initiated the session. User asides stay out of model-facing tooling. */
+export type SubagentOrigin = "model" | "btw";
+
+/**
+ * Reasoning-effort scale; these are pi's thinking levels, used directly as the
+ * level. Omitted = inherit the parent session's level.
+ */
+export const REASONING_EFFORTS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+export type SubagentStatus = "running" | "done" | "error";
+
+/** Parent-session context resolved by the tool layer and passed opaquely. */
+export interface ParentContext {
+  readonly parentCwd: string;
+  readonly projectTrusted: boolean;
+  /** Parent pi model, for the pi backend's "inherit" default. */
+  readonly inheritedModel?: { readonly provider: string; readonly id: string };
+  readonly inheritedThinkingLevel?: string;
+  /** Parent model registry; required by the pi backend to resolve models. */
+  readonly modelRegistry?: ModelRegistry;
+}
+
+export interface SpawnTask {
+  /** Omitted for normal tool-driven spawns. */
+  readonly origin?: SubagentOrigin;
+  readonly prompt: string;
+  readonly title: string;
+  readonly cwd: string;
+  /**
+   * Model hint: "provider/model-id", or a bare model id resolved against the
+   * parent's provider. Omitted = inherit the parent model.
+   */
+  readonly model?: string;
+  /** Thinking level for the child; omitted inherits the parent level. */
+  readonly reasoningEffort?: ReasoningEffort;
+  /**
+   * Agent-type fields, resolved by the tool layer. The backend applies them
+   * verbatim; it does not know where they came from.
+   */
+  readonly appendSystemPrompt?: readonly string[];
+  /**
+   * Tool allowlist for the child. Composed with (never replacing) the child
+   * denylist, so this can only narrow. Omitted = the normal child tool set.
+   */
+  readonly tools?: readonly string[];
+  /** Agent type that supplied the above, for the session label. */
+  readonly agentTypeName?: string;
+  /**
+   * Isolated git worktree this child runs in, created by the tool layer. The
+   * backend only reclaims it when the session scope closes; it does not know
+   * how it was made.
+   */
+  readonly worktree?: {
+    readonly path: string;
+    readonly branch: string;
+    /** Repository the worktree belongs to, for the reclaim call. */
+    readonly repoCwd: string;
+    /** Creation-time commit; reclaim measures "produced nothing" against it. */
+    readonly baseSha?: string;
+  };
+  readonly parent: ParentContext;
+}
+
+export interface SubagentMeta {
+  readonly backend: BackendName;
+  /** Display label, e.g. "seal/kimi-k3". */
+  readonly modelLabel?: string;
+  /** Context window capacity for utilization display, when known. */
+  readonly contextWindow?: number;
+  /** Child session file on disk. */
+  readonly sessionFilePath?: string;
+}
+
+// --- Transcript ------------------------------------------------------------
+
+export type TranscriptPart =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "thinking";
+      readonly text: string;
+      readonly redacted?: boolean;
+    }
+  | {
+      readonly type: "toolCall";
+      readonly toolId: string;
+      readonly name: string;
+      readonly argsPreview?: string;
+    };
+
+export type TranscriptItem =
+  | { readonly kind: "user"; readonly text: string }
+  | {
+      readonly kind: "assistant";
+      readonly parts: ReadonlyArray<TranscriptPart>;
+    }
+  | {
+      readonly kind: "toolResult";
+      readonly toolId: string;
+      readonly name: string;
+      readonly isError: boolean;
+      readonly outputPreview?: string;
+    };
+
+export interface LiveToolState {
+  readonly toolId: string;
+  readonly name: string;
+  readonly argsPreview?: string;
+  readonly outputPreview?: string;
+  readonly done?: boolean;
+  readonly isError?: boolean;
+}
+
+export interface QueuedMessage {
+  readonly text: string;
+  readonly kind: "steer" | "follow-up";
+}
+
+// --- Events ------------------------------------------------------------------
+
+export type RunOutcome =
+  | { readonly _tag: "Completed"; readonly finalText: string }
+  | {
+      readonly _tag: "Failed";
+      readonly errorText: string;
+      readonly partialText?: string;
+    }
+  | { readonly _tag: "Interrupted"; readonly partialText?: string };
+
+/**
+ * Normalized activity stream. Previews (`argsPreview`, `outputPreview`) stay
+ * bounded, pre-flattened strings; the UI may compact known argument fields but
+ * never retains arbitrary raw tool payloads.
+ */
+export type SubagentEvent =
+  // lifecycle (a session can run multiple turns via send())
+  | { readonly _tag: "RunStarted" }
+  | { readonly _tag: "RunSettled"; readonly outcome: RunOutcome }
+  // transcript building blocks
+  | { readonly _tag: "UserMessage"; readonly text: string }
+  | {
+      readonly _tag: "AssistantDelta";
+      readonly kind: "text" | "thinking";
+      readonly delta: string;
+    }
+  | {
+      readonly _tag: "AssistantMessage";
+      readonly parts: ReadonlyArray<TranscriptPart>;
+    }
+  | {
+      readonly _tag: "ToolStart";
+      readonly toolId: string;
+      readonly name: string;
+      readonly argsPreview?: string;
+    }
+  | {
+      readonly _tag: "ToolUpdate";
+      readonly toolId: string;
+      readonly outputPreview?: string;
+    }
+  | {
+      readonly _tag: "ToolEnd";
+      readonly toolId: string;
+      readonly name: string;
+      readonly isError: boolean;
+      readonly outputPreview?: string;
+    }
+  // bookkeeping
+  | {
+      readonly _tag: "QueueChanged";
+      readonly queued: ReadonlyArray<QueuedMessage>;
+    }
+  | {
+      readonly _tag: "UsageChanged";
+      readonly tokens?: number;
+      readonly contextWindow?: number;
+    }
+  | { readonly _tag: "MetaChanged"; readonly meta: Partial<SubagentMeta> }
+  /** Non-fatal diagnostics. Fatal failures arrive as a RunSettled outcome. */
+  | { readonly _tag: "BackendError"; readonly message: string };
+
+// --- Snapshot ---------------------------------------------------------------
+
+/**
+ * The manager folds `SubagentEvent`s into one snapshot per subagent. This is
+ * everything the tools, footer status, and both TUI views read.
+ */
+export interface SubagentSnapshot {
+  readonly id: string;
+  readonly origin: SubagentOrigin;
+  readonly backend: BackendName;
+  readonly title: string;
+  readonly prompt: string;
+  readonly cwd: string;
+  readonly status: SubagentStatus;
+  readonly createdAt: number;
+  readonly settledAt?: number;
+  readonly errorText?: string;
+  readonly meta: SubagentMeta;
+  readonly usage: { readonly tokens?: number; readonly contextWindow?: number };
+  readonly transcript: ReadonlyArray<TranscriptItem>;
+  /** Streaming assistant buffers, cleared when the finalized message lands. */
+  readonly liveAssistant?: { readonly text: string; readonly thinking: string };
+  readonly liveTools: ReadonlyArray<LiveToolState>;
+  readonly queued: ReadonlyArray<QueuedMessage>;
+  /** Final text of the most recent completed run (v1 `finalOutput`). */
+  readonly finalText: string;
+  /** Count of finalized assistant messages (for subagent_check). */
+  readonly turns: number;
+}
+
+/** Final text, or the live streaming buffer while a run is active (v1 `latestOutput`). */
+export function latestText(snap: SubagentSnapshot) {
+  const live = snap.liveAssistant?.text.trim();
+  if (live) return live;
+  return snap.finalText;
+}
+
+export function formatElapsed(snap: SubagentSnapshot) {
+  const end = snap.settledAt ?? Date.now();
+  const totalSeconds = Math.max(0, Math.round((end - snap.createdAt) / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0
+    ? `${minutes}m${seconds.toString().padStart(2, "0")}s`
+    : `${seconds}s`;
+}
+
+// --- Errors -------------------------------------------------------------------
+
+export class SpawnError extends Data.TaggedError("SpawnError")<{
+  readonly message: string;
+}> {}
+
+export class BackendUnavailableError extends Data.TaggedError(
+  "BackendUnavailableError",
+)<{
+  readonly message: string;
+}> {}
+
+export class ConcurrencyLimitError extends Data.TaggedError(
+  "ConcurrencyLimitError",
+)<{
+  readonly message: string;
+}> {}
+
+export class SendError extends Data.TaggedError("SendError")<{
+  readonly message: string;
+}> {}

package/extensions/subagents/src/format.ts

@@ -0,0 +1,48 @@
+/**
+ * Formatting helpers (self-contained copy of the v1 shared
+ * context-utilization helper).
+ */
+
+export interface ContextUtilization {
+  /** Current conversation context occupancy; undefined while unknown. */
+  tokens?: number | null;
+  /** Capacity of the model currently serving the conversation. */
+  contextWindow?: number | null;
+}
+
+function usableTokens(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+function usableCapacity(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+export function contextPercent(usage: ContextUtilization) {
+  const tokens = usableTokens(usage.tokens);
+  const capacity = usableCapacity(usage.contextWindow);
+  if (tokens === undefined || capacity === undefined) return undefined;
+  return Math.round(Math.min(100, Math.max(0, (tokens / capacity) * 100)));
+}
+
+export function formatCompactTokens(count: number) {
+  if (count < 1000) return Math.round(count).toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1000000).toFixed(1)}M`;
+}
+
+/**
+ * Render `%/capacity`. If occupancy is unknown, retain the useful capacity
+ * as `?%/capacity`; with no valid capacity, omit the statistic entirely.
+ */
+export function formatContextUtilization(usage: ContextUtilization) {
+  const capacity = usableCapacity(usage.contextWindow);
+  if (capacity === undefined) return "";
+  const percent = contextPercent(usage);
+  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
+}