@jopqior/pi-subagents 1.0.0

package/src/lifecycle/turn-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * turn-limits.ts — Pure turn-limit normalization for subagent execution.
+ *
+ * Extracted from agent-runner.ts (issue #265) so the turn-counting policy has a
+ * focused home independent of session assembly. Consumed by the subagent tool's
+ * spawn-config resolution and by the turn loop in SubagentSession.
+ */
+
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export function normalizeMaxTurns(n: number | undefined): number | undefined {
+  if (n == null || n === 0) return undefined;
+  return Math.max(1, n);
+}

package/src/lifecycle/usage.ts

@@ -0,0 +1,60 @@
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+export type LifetimeUsage = { input: number; output: number; cacheWrite: number };
+
+/** Sum of lifetime usage components, or 0 if undefined. */
+export function getLifetimeTotal(u?: LifetimeUsage): number {
+  return u ? u.input + u.output + u.cacheWrite : 0;
+}
+
+/** Add a usage delta into a target accumulator (mutates target). */
+export function addUsage(into: LifetimeUsage, delta: LifetimeUsage): void {
+  into.input += delta.input;
+  into.output += delta.output;
+  into.cacheWrite += delta.cacheWrite;
+}
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+  tokens: { input: number; output: number; cacheWrite: number };
+  contextUsage?: { percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/**
+ * Session-scoped token count: input + output + cacheWrite as reported by
+ * upstream `getSessionStats().tokens` for the *current* session window.
+ *
+ * RESETS at compaction — upstream replaces `session.state.messages` and the
+ * stats are derived from that array. For a lifetime total that survives
+ * compaction, use `getLifetimeTotal(lifetimeUsage)` instead, which reads
+ * from an independent accumulator fed by `message_end` events.
+ *
+ * Avoids upstream's `tokens.total` field, which sums per-turn `cacheRead`
+ * and so counts the cumulative cached prefix N times across N turns
+ * (issue #38).
+ */
+export function getSessionTokens(session: SessionLike | undefined): number {
+  if (!session) return 0;
+  try {
+    const t = session.getSessionStats().tokens;
+    return t.input + t.output + t.cacheWrite;
+  } catch { return 0; }
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+  if (!session) return null;
+  try { return session.getSessionStats().contextUsage?.percent ?? null; }
+  catch { return null; }
+}

package/src/lifecycle/workspace-bracket.ts

@@ -0,0 +1,76 @@
+/**
+ * workspace-bracket.ts — Owned prepare/dispose lifecycle for a child workspace.
+ *
+ * Captures the provider resolver (not the provider itself) so provider
+ * resolution stays lazy at run-start. The prepared Workspace is held
+ * privately; dispose() centralises the guard and addendum-unwrap so callers
+ * never reach through to workspace.dispose().resultAddendum directly.
+ *
+ * dispose() is idempotent — a workspace can outlive the run that prepared it
+ * (a child holding it for a resume), so more than one lifecycle edge may reach
+ * for it — and it deliberately does NOT catch errors: the best-effort
+ * try/catch belongs at the call site, preserving the per-caller semantics.
+ */
+
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+/** Owns the child workspace lifecycle: prepare at run-start, dispose at run-end. */
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+	private disposedWorkspace = false;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/**
+	 * True once a prepared workspace has been torn down — the directory the run
+	 * used is gone. False for a bracket that never held one, and false while one
+	 * is still held, so it distinguishes "no workspace" from "workspace removed".
+	 */
+	wasDisposed(): boolean {
+		return this.disposedWorkspace;
+	}
+
+	/**
+	 * Returns true when a workspace provider is currently registered.
+	 * Use to guard the `await prepare(...)` call and avoid an unnecessary
+	 * microtask boundary in the no-provider path.
+	 */
+	hasProvider(): boolean {
+		return this.resolveProvider() !== undefined;
+	}
+
+	/**
+	 * Resolve the registered provider and prepare the child workspace.
+	 * Returns the workspace's cwd, or undefined when no provider is registered
+	 * or the provider resolves to undefined.
+	 */
+	async prepare(ctx: WorkspacePrepareContext): Promise<string | undefined> {
+		const provider = this.resolveProvider();
+		if (!provider) return undefined;
+		this.prepared = await provider.prepare(ctx);
+		return this.prepared?.cwd;
+	}
+
+	/**
+	 * Dispose the prepared workspace (if any) and return the result addendum
+	 * verbatim. Returns an empty string when no workspace was prepared, when one
+	 * was already disposed, or when the workspace returns no addendum.
+	 *
+	 * The workspace is released and recorded as disposed before it is torn down,
+	 * so a provider whose dispose() throws still leaves the bracket reporting a
+	 * gone workspace — a failed teardown makes reuse no safer than a clean one.
+	 * The throw itself still propagates.
+	 */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		const workspace = this.prepared;
+		if (!workspace) return "";
+		this.prepared = undefined;
+		this.disposedWorkspace = true;
+		return workspace.dispose(outcome)?.resultAddendum ?? "";
+	}
+}

package/src/lifecycle/workspace.ts

@@ -0,0 +1,46 @@
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+import type { SubagentStatus } from "#src/lifecycle/subagent";
+import type { SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  status: SubagentStatus;
+  description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+  /** Appended verbatim to the child's result text — the provider owns the wording. */
+  resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+  /** The working directory — already exists when the workspace is handed back. */
+  readonly cwd: string;
+  dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+  prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}

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

@@ -0,0 +1,74 @@
+import { debugLog } from "#src/debug";
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/**
+ * Fans out SubagentManager lifecycle notifications to multiple observers.
+ *
+ * Lets the manager keep its single-observer contract while several independent
+ * consumers (event/notification dispatch, the reactive widget) subscribe.
+ * Each delegate is isolated: a throw in one does not suppress the others.
+ */
+export class CompositeSubagentObserver implements SubagentManagerObserver {
+  private readonly delegates: SubagentManagerObserver[];
+
+  constructor(delegates: SubagentManagerObserver[]) {
+    this.delegates = [...delegates];
+  }
+
+  /** Register an additional observer (breaks the widget↔manager construction cycle). */
+  add(observer: SubagentManagerObserver): void {
+    this.delegates.push(observer);
+  }
+
+  onSubagentStarted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentStarted(record), "onSubagentStarted");
+  }
+
+  onSubagentCreated(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCreated(record), "onSubagentCreated");
+  }
+
+  onSubagentCompleted(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentCompleted(record), "onSubagentCompleted");
+  }
+
+  onSubagentResuming(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentResuming(record), "onSubagentResuming");
+  }
+
+  onSubagentResumed(record: Subagent): void {
+    this.dispatch((o) => o.onSubagentResumed(record), "onSubagentResumed");
+  }
+
+  onSubagentUpdate(record: Subagent, message: string): void {
+    this.dispatch((o) => o.onSubagentUpdate?.(record, message), "onSubagentUpdate");
+  }
+
+  /**
+   * Required here even though `SubagentManagerObserver` declares it optional:
+   * the manager's observer is always this composite, so a member it does not
+   * enumerate is dropped silently — no compiler error, no runtime error, and
+   * the announcement simply never fires.
+   */
+  onSubagentWorkspaceNotice(record: Subagent, notice: string): void {
+    this.dispatch(
+      (o) => o.onSubagentWorkspaceNotice?.(record, notice),
+      "onSubagentWorkspaceNotice",
+    );
+  }
+
+  onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+    this.dispatch((o) => o.onSubagentCompacted(record, info), "onSubagentCompacted");
+  }
+
+  private dispatch(call: (o: SubagentManagerObserver) => void, label: string): void {
+    for (const o of this.delegates) {
+      try {
+        call(o);
+      } catch (err) {
+        debugLog(`CompositeSubagentObserver.${label}`, err);
+      }
+    }
+  }
+}