@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,75 @@
+import {
+	buildLifecycleEventData,
+	buildLifecycleRecord,
+} from "#src/lifecycle/lifecycle-record";
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import type { NotificationSystem } from "#src/observation/notification";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		this.emit("subagents:started", buildLifecycleEventData(record));
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		this.persistTerminal(
+			record,
+			record.isTerminalError() ? "subagents:failed" : "subagents:completed",
+		);
+	}
+
+	onSubagentResumed(record: Subagent): void {
+		this.persistTerminal(record, "subagents:resumed");
+	}
+
+	/** Public terminal event and persisted custom entry share one exact v2 object. */
+	private persistTerminal(record: Subagent, eventName: string): void {
+		const data = buildLifecycleRecord(record);
+		this.emit(eventName, data);
+		this.appendEntry("subagents:record", data);
+		if (record.isBackground) this.notifications.sendCompletion(record);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		this.emit("subagents:compacted", {
+			...buildLifecycleEventData(record),
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		this.emit("subagents:created", buildLifecycleEventData(record));
+	}
+}

package/src/runtime.ts

@@ -0,0 +1,78 @@
+/**
+ * runtime.ts — SubagentRuntime: composition root for all mutable extension state.
+ *
+ * Eliminates module-scope state in agent-runner.ts and closure-scoped state
+ * in index.ts by consolidating them into a single, testable object.
+ * Follows the same pattern as pi-permission-system's ExtensionRuntime.
+ */
+
+import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { ModelInfo } from "#src/tools/spawn-config";
+import type { SessionContext } from "#src/types";
+
+/** Runtime safety ceilings shared by tool and service-driven invocations. */
+export interface RunConfig {
+  readonly maxTurns: number;
+  readonly wrapUpTurns: number;
+  readonly maxDurationSeconds: number;
+  readonly maxQueueWaitSeconds: number;
+  readonly abortGraceSeconds: number;
+}
+
+/**
+ * All mutable state owned by the pi-subagents extension.
+ *
+ * Created once inside `piSubagentsExtension()` via `createSubagentRuntime()`.
+ * Tests construct a fresh runtime per test for full isolation.
+ */
+export class SubagentRuntime {
+  // ── Session state (was closure-scoped in index.ts) ───────────────────────
+  /** Active Pi session context — set on session_start, cleared on session_shutdown. */
+  currentCtx: SessionContext | undefined = undefined;
+
+  // ── Session-context methods ──────────────────────────────────────────────
+
+  /** Store the active Pi session context (called from session_start). */
+  setSessionContext(ctx: SessionContext): void {
+    this.currentCtx = ctx;
+  }
+
+  /** Clear the session context (called from session_shutdown). */
+  clearSessionContext(): void {
+    this.currentCtx = undefined;
+  }
+
+  /**
+   * Build a parent snapshot from the current session context.
+   * Only valid during an active session (currentCtx is defined).
+   */
+  buildSnapshot(inheritContext: boolean): ParentSnapshot {
+
+    return buildParentSnapshot(this.currentCtx!, inheritContext);
+  }
+
+  /** Extract model info from the current session context. */
+  getModelInfo(): ModelInfo {
+    return {
+      parentModel: this.currentCtx?.model,
+      modelRegistry: this.currentCtx?.modelRegistry,
+    };
+  }
+
+  /** Extract session identity from the current session context. */
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string } {
+    return {
+      parentSessionFile: this.currentCtx?.sessionManager.getSessionFile() ?? "",
+      parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
+    };
+  }
+}
+
+/**
+ * Create a fully-initialized SubagentRuntime with default values.
+ *
+ * Call once at extension startup; pass the result to factories and handlers.
+ */
+export function createSubagentRuntime(): SubagentRuntime {
+  return new SubagentRuntime();
+}

package/src/service/service-adapter.ts

@@ -0,0 +1,159 @@
+/**
+ * service-adapter.ts — Adapter that wraps SubagentManager to satisfy SubagentsService.
+ *
+ * Handles model resolution at the API boundary, record serialization
+ * (stripping non-serializable fields), and session gating.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { AgentTypeRegistry } from "#src/config/agent-types";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import type { SessionContext, Subagent } from "#src/types";
+
+/** Narrow interface for the SubagentManager — avoids coupling to the concrete class. */
+export interface SubagentManagerLike {
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
+  getRecord(id: string): Subagent | undefined;
+  listAgents(): Subagent[];
+  abort(id: string): boolean;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+
+/**
+ * Narrow runtime interface consumed by the service adapter.
+ * `SubagentRuntime` satisfies this structurally; tests use plain stubs.
+ */
+export interface ServiceRuntimeLike {
+  readonly currentCtx: SessionContext | undefined;
+  buildSnapshot(inheritContext: boolean): ParentSnapshot;
+}
+
+/** Test-only fallback; the extension composition root always injects the live registry. */
+const DEFAULT_REGISTRY = new AgentTypeRegistry(() => new Map());
+
+/** Adapter that wraps SubagentManager to satisfy SubagentsService. */
+export class SubagentsServiceAdapter implements SubagentsService {
+  constructor(
+    private readonly manager: SubagentManagerLike,
+    private readonly resolveModel: (input: string, registry: ModelRegistry) => Model<any> | string,
+    private readonly runtime: ServiceRuntimeLike,
+    private readonly registry: Pick<AgentTypeRegistry, "reload" | "resolveSpawnType"> = DEFAULT_REGISTRY,
+  ) {}
+
+  spawn(type: string, prompt: string, options?: SpawnOptions): string {
+    if (!this.runtime.currentCtx) {
+      throw new Error("No active session — cannot spawn agents outside a session.");
+    }
+
+    this.registry.reload();
+    const agentType = this.registry.resolveSpawnType(type);
+    const model = this.resolveModelOption(options?.model);
+    const description = options?.description ?? prompt.slice(0, 80);
+    const isBackground = !(options?.foreground ?? false);
+
+    const snapshot = this.runtime.buildSnapshot(options?.inheritContext ?? false);
+    return this.manager.spawn(snapshot, agentType, prompt, {
+      description,
+      model,
+      maxTurns: options?.maxTurns,
+      wrapUpTurns: options?.wrapUpTurns,
+      maxDurationSeconds: options?.maxDurationSeconds,
+      thinkingLevel: options?.thinkingLevel,
+      inheritContext: options?.inheritContext,
+      bypassQueue: options?.bypassQueue,
+      isBackground,
+      lifecycleInvocation: { kind: "fresh", source: "service" },
+    });
+  }
+
+  getRecord(id: string): SubagentRecord | undefined {
+    const record = this.manager.getRecord(id);
+    return record ? toSubagentRecord(record) : undefined;
+  }
+
+  listAgents(): SubagentRecord[] {
+    return this.manager.listAgents().map(toSubagentRecord);
+  }
+
+  abort(id: string): boolean {
+    return this.manager.abort(id);
+  }
+
+  async steer(id: string, message: string): Promise<boolean> {
+    const record = this.manager.getRecord(id);
+    if (!record) {
+      return false;
+    }
+    const outcome = await record.steer(message);
+    return outcome.kind !== "rejected";
+  }
+
+  async waitForAll(): Promise<void> {
+    return this.manager.waitForAll();
+  }
+
+  hasRunning(): boolean {
+    return this.manager.hasRunning();
+  }
+
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    return this.manager.registerWorkspaceProvider(provider);
+  }
+
+  /** Resolve an optional model-string override against the current session's registry. */
+  private resolveModelOption(modelInput: string | undefined): Model<any> | undefined {
+    if (!modelInput) return undefined;
+    const registry = this.runtime.currentCtx?.modelRegistry;
+    if (!registry) {
+      throw new Error("No model registry available.");
+    }
+    const resolved = this.resolveModel(modelInput, registry);
+    if (typeof resolved === "string") {
+      throw new Error(resolved);
+    }
+    return resolved;
+  }
+}
+
+/**
+ * Convert an internal Subagent to a serializable SubagentRecord.
+ * Uses an explicit allowlist — new fields must be opted in.
+ */
+export function toSubagentRecord(record: Subagent): SubagentRecord {
+  const out: SubagentRecord = {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    phase: record.phase,
+    isBackground: record.isBackground,
+    lifecycleInvocation: { ...record.lifecycleInvocation },
+    invocationIndex: record.invocationIndex,
+    sessionState: record.sessionState,
+    toolUses: record.toolUses,
+    startedAt: record.startedAt,
+    lifetimeUsage: { ...record.lifetimeUsage },
+    invocationStartedAt: record.invocationStartedAt,
+    invocationToolUses: record.invocationToolUses,
+    invocationUsage: { ...record.invocationUsage },
+    compactionCount: record.compactionCount,
+    invocationTurnCount: record.invocationTurnCount,
+    lifetimeTurnCount: record.lifetimeTurnCount,
+    maxTurns: record.maxTurns,
+    wrapUpTurns: record.wrapUpTurns,
+    maxDurationSeconds: record.maxDurationSeconds,
+  };
+
+  if (record.outcome !== undefined) out.outcome = record.outcome;
+  if (record.result !== undefined) out.result = record.result;
+  if (record.error !== undefined) out.error = record.error;
+  if (record.sessionId !== undefined) out.sessionId = record.sessionId;
+  if (record.outputFile !== undefined) out.outputFile = record.outputFile;
+  if (record.completedAt !== undefined) out.completedAt = record.completedAt;
+
+  return out;
+}

package/src/service/service.ts

@@ -0,0 +1,147 @@
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@yefengr/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent";
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import type {
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+import type { SubagentInvocationIdentity } from "#src/types";
+
+
+// SubagentPhase/SubagentOutcome are defined in the lifecycle layer (single home)
+// and re-exported here for the public API surface — mirrors the LifetimeUsage /
+// workspace pattern.
+export type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent";
+// Generative extension seam (ADR 0002, Phase 16 Step 2). The provider type
+// and all four collaborator types it references are re-exported by name so
+// consumers can import them directly rather than recovering them via
+// indexed-access inference (e.g. `Parameters<WorkspaceProvider["prepare"]>[0]`).
+export type {
+  LifetimeUsage,
+  SubagentInvocationIdentity,
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+};
+
+/** Serializable snapshot of an agent's state — no live session objects. */
+export interface SubagentRecord {
+  id: string;
+  type: string;
+  description: string;
+  phase: SubagentPhase;
+  outcome?: SubagentOutcome;
+  result?: string;
+  error?: string;
+  isBackground: boolean;
+  lifecycleInvocation: SubagentInvocationIdentity;
+  invocationIndex: number;
+  sessionState: "created" | "not-created";
+  sessionId?: string;
+  outputFile?: string;
+  toolUses: number;
+  startedAt: number;
+  completedAt?: number;
+  lifetimeUsage: LifetimeUsage;
+  invocationStartedAt: number;
+  invocationToolUses: number;
+  invocationUsage: LifetimeUsage;
+  compactionCount: number;
+  invocationTurnCount: number;
+  lifetimeTurnCount: number;
+  maxTurns: number;
+  wrapUpTurns: number;
+  maxDurationSeconds: number;
+}
+
+/** Options for spawning an agent via the service. */
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  wrapUpTurns?: number;
+  maxDurationSeconds?: number;
+  thinkingLevel?: string;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  bypassQueue?: boolean;
+}
+
+/** The public service contract for cross-extension subagent access. */
+export interface SubagentsService {
+  /** Spawn an agent. Returns the agent ID immediately. */
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+
+  /** Get a snapshot of an agent's current state. */
+  getRecord(id: string): SubagentRecord | undefined;
+
+  /** List all tracked agents, most recent first. */
+  listAgents(): SubagentRecord[];
+
+  /** Abort a running or queued agent. Returns false if not found. */
+  abort(id: string): boolean;
+
+  /** Send a steering message to a running agent. */
+  steer(id: string, message: string): Promise<boolean>;
+
+  /** Wait for all running and queued agents to complete. */
+  waitForAll(): Promise<void>;
+
+  /** Whether any agents are running or queued. */
+  hasRunning(): boolean;
+
+  /**
+   * Register the single workspace provider that supplies a child's working
+   * directory plus bracketed setup/teardown. Throws if one is already
+   * registered. Returns a disposer that unregisters the provider.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+}
+
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  FAILED: "subagents:failed",
+  RESUMED: "subagents:resumed",
+  COMPACTED: "subagents:compacted",
+  CREATED: "subagents:created",
+  STEERED: "subagents:steered",
+} as const;
+
+// ---- Accessor functions ----
+
+const SERVICE_KEY = Symbol.for("@yefengr/pi-subagents:service");
+
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+export function publishSubagentsService(service: SubagentsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+export function getSubagentsService(): SubagentsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | SubagentsService
+    | undefined;
+}
+
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+export function unpublishSubagentsService(): void {
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/src/session/content-items.ts

@@ -0,0 +1,53 @@
+/**
+ * content-items.ts — Shared parsing utilities for Pi SDK message content items.
+ *
+ * Provides type-safe extraction of text parts and tool-call names from
+ * assistant message content arrays. Pure functions — no IO.
+ */
+
+import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Extracted text parts and tool names from assistant message content. */
+export interface AssistantContentParts {
+  textParts: string[];
+  toolNames: string[];
+}
+
+// ── Functions ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts the display name from a tool-call content item.
+ *
+ * Returns 'unknown' for non-toolCall items.
+ * The Pi SDK's ToolCall.name is always present — no fallback chain needed.
+ */
+export function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  return (c as ToolCall).name;
+}
+
+/**
+ * Extract text parts and tool-call names from assistant message content items.
+ *
+ * Accepts any array whose elements carry a `type` discriminant — all Pi SDK
+ * content types (TextContent, ThinkingContent, ToolCall) satisfy this constraint.
+ * Pure data extraction — consumers apply their own presentation formatting.
+ * Skips items of unknown types (e.g. thinking blocks, images) and empty text.
+ */
+export function extractAssistantContent(
+  content: ReadonlyArray<{ type: string }>,
+): AssistantContentParts {
+  const textParts: string[] = [];
+  const toolNames: string[] = [];
+  for (const c of content) {
+    if (c.type === "text") {
+      const text = (c as TextContent).text;
+      if (text) textParts.push(text);
+    } else if (c.type === "toolCall") {
+      toolNames.push(getToolCallName(c));
+    }
+  }
+  return { textParts, toolNames };
+}

package/src/session/context.ts

@@ -0,0 +1,80 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { TextContent } from "@earendil-works/pi-ai";
+import type { SessionContext } from "#src/types";
+
+/**
+ * Minimal structural types for session branch entries consumed by buildParentContext.
+ * `getBranch()` returns `unknown[]` in SessionContext (ISP), so we cast to these
+ * local shapes instead of coupling to the SDK's SessionEntry type.
+ */
+type MessageEntry = {
+  type: "message";
+  message: { role: string; content: string | { type: string }[] };
+};
+type CompactionEntry = { type: "compaction"; summary?: string };
+type BranchEntry = MessageEntry | CompactionEntry | { type: string };
+
+/** Type predicate: narrow an unknown content block to TextContent. */
+function isTextContent(c: unknown): c is TextContent {
+  return typeof c === "object" && c !== null && (c as { type: string }).type === "text";
+}
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+  return content
+    .filter(isTextContent)
+    .map((c) => c.text)
+    .join("\n");
+}
+
+/** Format a message entry (user/assistant); returns undefined for roles to skip. */
+function formatMessageEntry(entry: MessageEntry): string | undefined {
+  const msg = entry.message;
+  const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+  if (!text.trim()) return undefined;
+  if (msg.role === "user") return `[User]: ${text.trim()}`;
+  if (msg.role === "assistant") return `[Assistant]: ${text.trim()}`;
+  return undefined; // skip toolResult and other roles
+}
+
+/** Format a compaction entry; returns undefined when no summary is present. */
+function formatCompactionEntry(entry: CompactionEntry): string | undefined {
+  return entry.summary ? `[Summary]: ${entry.summary}` : undefined;
+}
+
+/** Dispatch a branch entry to the appropriate formatter. */
+function formatBranchEntry(entry: BranchEntry): string | undefined {
+  if (entry.type === "message") return formatMessageEntry(entry as MessageEntry);
+  if (entry.type === "compaction") return formatCompactionEntry(entry as CompactionEntry);
+  return undefined;
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: SessionContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
+  if (!entries || entries.length === 0) return "";
+
+  const parts = (entries as BranchEntry[])
+    .map(formatBranchEntry)
+    .filter((p): p is string => p !== undefined);
+
+  if (parts.length === 0) return "";
+
+  return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}

package/src/session/conversation.ts

@@ -0,0 +1,49 @@
+/**
+ * conversation.ts — Render a subagent session's messages as formatted text.
+ *
+ * Extracted from agent-runner.ts (issue #265) into the session domain, where the
+ * other message-extraction helpers (content-items, context) live. Consumed by
+ * the get_subagent_result tool's verbose output.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { extractAssistantContent } from "#src/session/content-items";
+import { extractText } from "#src/session/context";
+
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export function getAgentConversation(session: AgentSession): string {
+  const parts: string[] = [];
+
+  for (const msg of session.messages) {
+    if (msg.role === "user") {
+      const text =
+        typeof msg.content === "string"
+          ? msg.content
+          : extractText(msg.content);
+      if (text.trim()) parts.push(`[User]: ${text.trim()}`);
+    } else if (msg.role === "assistant") {
+      const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
+      if (textParts.length > 0)
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
+      if (toolNames.length > 0)
+        parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
+    } else if (msg.role === "toolResult") {
+      const text = extractText(msg.content);
+      const truncated = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      parts.push(`[Tool Result (${msg.toolName})]: ${truncated}`);
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/session/env.ts

@@ -0,0 +1,40 @@
+/**
+ * env.ts — Detect environment info (git, platform) for subagent system prompts.
+ */
+
+import { debugLog } from "#src/debug";
+import type { ShellExec } from "#src/types";
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}
+
+export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
+  let isGitRepo = false;
+  let branch = "";
+
+  try {
+    const result = await exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+    isGitRepo = result.code === 0 && result.stdout.trim() === "true";
+  } catch (err) {
+    debugLog("git rev-parse", err);
+  }
+
+  if (isGitRepo) {
+    try {
+      const result = await exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+      branch = result.code === 0 ? result.stdout.trim() : "unknown";
+    } catch (err) {
+      debugLog("git branch", err);
+      branch = "unknown";
+    }
+  }
+
+  return {
+    isGitRepo,
+    branch,
+    platform: process.platform,
+  };
+}