@gotgenes/pi-subagents 11.3.0 → 11.5.0

package/src/lifecycle/agent.ts

@@ -26,6 +26,7 @@ import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
+import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
@@ -72,6 +73,10 @@ export interface AgentInit {
 	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
+	/** Resolves the registered workspace provider (if any) at run-start. */
+	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	/** Parent working directory handed to a workspace provider's prepare(). */
+	baseCwd?: string;
 
 	// Run config (required for run(), optional for tests)
 	snapshot?: ParentSnapshot;
@@ -129,6 +134,10 @@ export class Agent {
 	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
+	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	private readonly _baseCwd: string;
+	/** Workspace prepared at run-start by a provider — undefined when none is registered. */
+	private _workspace?: Workspace;
 
 	// Run config — optional (required for run())
 	private readonly _snapshot?: ParentSnapshot;
@@ -186,6 +195,8 @@ export class Agent {
 		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
+		this._getWorkspaceProvider = init.getWorkspaceProvider;
+		this._baseCwd = init.baseCwd ?? "";
 
 		// Run config
 		this._snapshot = init.snapshot;
@@ -223,8 +234,23 @@ export class Agent {
 		this.observer?.onStarted?.(this);
 		this.wireSignal(this._signal, () => this.abort());
 
+		let cwd: string | undefined;
 		try {
-			this.worktree?.setup();
+			// Provider-first: a registered workspace provider supplies the cwd and
+			// owns teardown; otherwise fall back to the legacy worktree collaborator.
+			const provider = this._getWorkspaceProvider?.();
+			if (provider) {
+				this._workspace = await provider.prepare({
+					agentId: this.id,
+					agentType: this.type,
+					baseCwd: this._baseCwd,
+					invocation: this.invocation,
+				});
+				cwd = this._workspace?.cwd;
+			} else {
+				this.worktree?.setup();
+				cwd = this.worktree?.path;
+			}
 		} catch (err) {
 			this.markError(err);
 			this.releaseListeners();
@@ -236,7 +262,7 @@ export class Agent {
 		try {
 			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
 				context: {
-					cwd: this.worktree?.path,
+					cwd,
 					parentSession: this._parentSession,
 				},
 				model: this._model,
@@ -442,9 +468,19 @@ export class Agent {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		const wtResult = this.worktree?.cleanup(this.description);
-		if (wtResult?.hasChanges && wtResult.branch) {
-			finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+		if (this._workspace) {
+			const finalStatus: AgentStatus = result.aborted
+				? "aborted"
+				: result.steered
+					? "steered"
+					: "completed";
+			const disposeResult = this._workspace.dispose({ status: finalStatus, description: this.description });
+			if (disposeResult?.resultAddendum) finalResult += disposeResult.resultAddendum;
+		} else {
+			const wtResult = this.worktree?.cleanup(this.description);
+			if (wtResult?.hasChanges && wtResult.branch) {
+				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+			}
 		}
 
 		if (result.aborted) this.markAborted(finalResult);
@@ -465,8 +501,9 @@ export class Agent {
 		this.releaseListeners();
 
 		try {
-			this.worktree?.cleanup(this.description);
-		} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
+			else this.worktree?.cleanup(this.description);
+		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
 		this.observer?.onRunFinished?.(this);
 	}

package/src/lifecycle/child-lifecycle.ts

@@ -0,0 +1,89 @@
+/**
+ * child-lifecycle.ts — Child-execution lifecycle event contract and publisher.
+ *
+ * The core publishes its child-execution lifecycle as ordered events on the Pi
+ * event bus; reactive consumers (permissions, telemetry, UI) subscribe rather
+ * than the core reaching out to them (ADR 0002). This module owns the channel
+ * names, payload shapes, and the publisher that emits them.
+ *
+ * The publisher takes an injected `emit` callback so this module stays free of
+ * Pi SDK imports — `index.ts` wires it to `pi.events.emit`.
+ */
+
+/** Emitted at the start of a child run, before the session is created. */
+export const SUBAGENT_CHILD_SPAWNING = "subagents:child:spawning";
+
+/**
+ * Emitted after the child session is created, immediately before
+ * `bindExtensions()`. Carries the child identity consumers need to register
+ * the session. Subscribers must register synchronously so the entry lands
+ * before binding proceeds (see ADR 0002 / the event-bus synchronous-dispatch
+ * guarantee).
+ */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted after the child's prompt resolves (normal, steered, or aborted). */
+export const SUBAGENT_CHILD_COMPLETED = "subagents:child:completed";
+
+/** Emitted in the run's `finally` — always fires, on success and error. */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Payload for `subagents:child:spawning`. */
+export interface ChildSpawningEvent {
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:session-created`. */
+export interface ChildSessionCreatedEvent {
+  /** Child session directory — the registry key. */
+  sessionDir: string;
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:completed`. */
+export interface ChildCompletedEvent {
+  sessionDir: string;
+  agentName: string;
+  /** True if the run was hard-aborted (max turns + grace exceeded). */
+  aborted: boolean;
+  /** True if the run was steered to wrap up (soft turn limit) but finished. */
+  steered: boolean;
+}
+
+/** Payload for `subagents:child:disposed`. */
+export interface ChildDisposedEvent {
+  sessionDir: string;
+}
+
+/** Narrow emit seam — injected, never imports the Pi SDK. */
+export type LifecycleEmit = (channel: string, data: unknown) => void;
+
+/** Publishes the child-execution lifecycle on the event bus. */
+export interface ChildLifecyclePublisher {
+  spawning(event: ChildSpawningEvent): void;
+  sessionCreated(event: ChildSessionCreatedEvent): void;
+  completed(event: ChildCompletedEvent): void;
+  disposed(event: ChildDisposedEvent): void;
+}
+
+/** Build a publisher backed by an injected `emit` callback. */
+export function createChildLifecyclePublisher(
+  emit: LifecycleEmit,
+): ChildLifecyclePublisher {
+  return {
+    spawning(event) {
+      emit(SUBAGENT_CHILD_SPAWNING, event);
+    },
+    sessionCreated(event) {
+      emit(SUBAGENT_CHILD_SESSION_CREATED, event);
+    },
+    completed(event) {
+      emit(SUBAGENT_CHILD_COMPLETED, event);
+    },
+    disposed(event) {
+      emit(SUBAGENT_CHILD_DISPOSED, event);
+    },
+  };
+}

package/src/lifecycle/workspace.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 { AgentStatus } from "#src/lifecycle/agent";
+import type { AgentInvocation, SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+  invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  status: AgentStatus;
+  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/service/service-adapter.ts

@@ -6,6 +6,7 @@
  */
 
 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 { Agent, SessionContext } from "#src/types";
@@ -18,6 +19,7 @@ export interface AgentManagerLike {
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
 }
 
 /**
@@ -107,6 +109,10 @@ export class SubagentsServiceAdapter implements SubagentsService {
   hasRunning(): boolean {
     return this.manager.hasRunning();
   }
+
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    return this.manager.registerWorkspaceProvider(provider);
+  }
 }
 
 /**

package/src/service/service.ts

@@ -10,8 +10,13 @@
  */
 
 import type { LifetimeUsage } from "#src/lifecycle/usage";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
-export type { LifetimeUsage };
+// Generative extension seam (ADR 0002, Phase 16 Step 2). Only the provider
+// entry-point type is re-exported here; a consumer assigning to
+// `WorkspaceProvider` gets `Workspace` and the context types via inference.
+// The worktrees package (#263) adds named re-exports when it imports them.
+export type { LifetimeUsage, WorkspaceProvider };
 
 export type SubagentStatus =
   | "queued"
@@ -73,6 +78,13 @@ export interface SubagentsService {
 
   /** 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. */

package/src/lifecycle/permission-bridge.ts

@@ -1,63 +0,0 @@
-/**
- * permission-bridge.ts — Cross-extension bridge to @gotgenes/pi-permission-system.
- *
- * pi-subagents does not import pi-permission-system directly. Instead it
- * accesses the published PermissionsService via a process-global Symbol.for()
- * key, the same mechanism pi-permission-system uses to publish itself.
- *
- * When pi-permission-system is not installed, getPermissionsService() returns
- * undefined and all registration calls are silent no-ops.
- */
-
-/**
- * The two PermissionsService methods pi-subagents needs.
- *
- * Follows ISP — does not expose the full PermissionsService surface
- * (checkPermission, getToolPermission, etc.) to avoid coupling.
- */
-interface PermissionsServiceConsumer {
-	registerSubagentSession(
-		sessionKey: string,
-		info: { parentSessionId?: string; agentName: string },
-	): void;
-	unregisterSubagentSession(sessionKey: string): void;
-}
-
-const PERMISSION_SERVICE_KEY = Symbol.for(
-	"@gotgenes/pi-permission-system:service",
-);
-
-function getPermissionsService(): PermissionsServiceConsumer | undefined {
-	return (globalThis as Record<symbol, unknown>)[
-		PERMISSION_SERVICE_KEY
-	] as PermissionsServiceConsumer | undefined;
-}
-
-/**
- * Register a child session with pi-permission-system's SubagentSessionRegistry.
- *
- * Must be called after deriving sessionDir but before session.bindExtensions()
- * so isSubagentExecutionContext() hits the registry on the first check during
- * child extension initialization.
- *
- * @param sessionKey - The session directory path (unique per session).
- * @param info       - Agent name and optional parent session ID for forwarding.
- */
-export function registerChildSession(
-	sessionKey: string,
-	info: { parentSessionId?: string; agentName: string },
-): void {
-	getPermissionsService()?.registerSubagentSession(sessionKey, info);
-}
-
-/**
- * Unregister a child session from pi-permission-system's SubagentSessionRegistry.
- *
- * Must be called in a finally block so cleanup happens on both success and
- * error paths.
- *
- * @param sessionKey - The session directory path used during registration.
- */
-export function unregisterChildSession(sessionKey: string): void {
-	getPermissionsService()?.unregisterSubagentSession(sessionKey);
-}