@giladbarnea/pi-user-agents 0.0.12 → 0.0.13

package/INTERNALS.md

@@ -81,11 +81,11 @@ The attached agent parks idle first (`runAttachedTurns` waits for an instruction
 
 `h` and `-h` hand a child session to a Pi running in a new [herdr](https://herdr.dev) pane. Both go through `openPiInHerdrPane` (`herdr.ts`), a thin wrapper over the `herdr` CLI: `pane layout --current` picks the split direction (a wide caller pane splits right, a narrow or tall one down), `pane split --current --cwd <cwd> --no-focus` creates the pane without taking the user's focus, and `agent start <name> --kind pi --pane <id> -- <pi args>` starts pi there and returns once it is ready for input. The agent name is `agent-` plus the first 13 characters of the child's session id, which hold a v7 id's complete millisecond timestamp, so names stay unique among live agents. Every command runs with the caller's environment, so `--current` resolves the pane this Pi lives in; both actions are available only under `HERDR_ENV=1`, and the widget hint hides otherwise.
 
-Both paths hand the pane's Pi `forwardedArgsForPane(...)`, the dispatch's forwarded tokens minus two groups: the *inert* options (`role: "inert"` in the option table — the session, approval, offline, and API-key families), which a background run ignores but a real `pi` process would obey (`--no-session` would run the pane ephemeral, `--fork` would open another file), and `--model`, `--provider`, `--thinking`, which the pane's Pi gets explicitly or from its file.
+Both paths hand the pane's Pi the parent's launch extension options (see [Child extensions](#child-extensions)), then `forwardedArgsForPane(...)`, the dispatch's forwarded tokens minus two groups: the *inert* options (`role: "inert"` in the option table — the session, approval, offline, and API-key families), which a background run ignores but a real `pi` process would obey (`--no-session` would run the pane ephemeral, `--fork` would open another file), and `--model`, `--provider`, `--thinking`, which the pane's Pi gets explicitly or from its file.
 
 **The move (`h`)** is attach in reverse, for another process, in three steps ordered so that failures cost as little as possible. First the delivery resolves the file — like `/agent-attach`, from the session directory listing by exact id; a child that has not answered yet has no file and the move stops here — and splits the pane; a herdr failure at this point leaves the agent untouched. Then the widget ends the agent here: abort, retire, wait for `finished` so the child session is disposed, and keep its row as a completed snapshot. Only then does pi start in the pane, so the file has one writer at a time; the dispatch record's forwarded args replay as CLI flags and the model and thinking level come from the file, as on any resume. A live agent has to be interrupted first. Once the agent is ended, its snapshot row survives whatever happens next — with `herdrPane` set on success, so it renders `herdr pane w1:p3` in place of the status word and withholds `h`, or without it on failure, still squashable. This is the squash pattern: the row persists as the record, and no transcript breadcrumb is written; `d` on the row announces `Detached session …` like any other, which stays true — the file is on disk.
 
-**The dispatch (`-h`)** never creates an in-process child session, and branches off before the child resource load that only a background child needs. The child's session manager is built as usual (dispatch record, inherited snapshot) plus explicit `model_change` and `thinking_level_change` entries appended after the snapshot: pi resumes a session with the model of whichever comes last on the path, a `model_change` entry or an assistant message, and writes `model_change` itself only on its empty-session path, which the pane's Pi never takes for an inherited context. Without the entries a later `/agent-attach` or `/resume` would take the model of main's last answer, or the default. `flushSessionFile` then writes the file to disk, because pi defers a session file until its first assistant message and a snapshot with no assistant message (`-i`, or a main session that has not answered yet) would otherwise exist only in memory; when the snapshot already flushed it, the file is left alone. The pane's Pi runs `pi <forwarded args> --provider <p> --model <id> --thinking <level> --session <file> "<pane preamble + task>"`: the flags repeat the model and thinking level because an isolated child's file has no messages, and pi then takes the flags over the file. The positional prompt carries `PANE_DISPATCH_PREAMBLE`, which tells the child it is interactive in a pane rather than an ephemeral background process; `splitAtDispatchBoundary` accepts either preamble, so attach recognizes the child later. The widget row is a snapshot from birth, with nothing to squash; `-h` and `-s` conflict at parse time.
+**The dispatch (`-h`)** never creates an in-process child session, and branches off before the child resource load that only a background child needs. The child's session manager is built as usual (dispatch record, inherited snapshot) plus explicit `model_change` and `thinking_level_change` entries appended after the snapshot: pi resumes a session with the model of whichever comes last on the path, a `model_change` entry or an assistant message, and writes `model_change` itself only on its empty-session path, which the pane's Pi never takes for an inherited context. Without the entries a later `/agent-attach` or `/resume` would take the model of main's last answer, or the default. `flushSessionFile` then writes the file to disk, because pi defers a session file until its first assistant message and a snapshot with no assistant message (`-i`, or a main session that has not answered yet) would otherwise exist only in memory; when the snapshot already flushed it, the file is left alone. The pane's Pi runs `pi <launch extension options> <forwarded args> --provider <p> --model <id> --thinking <level> --session <file> "<pane preamble + task>"`: the flags repeat the model and thinking level because an isolated child's file has no messages, and pi then takes the flags over the file. The positional prompt carries `PANE_DISPATCH_PREAMBLE`, which tells the child it is interactive in a pane rather than an ephemeral background process; `splitAtDispatchBoundary` accepts either preamble, so attach recognizes the child later. The widget row is a snapshot from birth, with nothing to squash; `-h` and `-s` conflict at parse time.
 
 ## Runtime sharing
 
@@ -93,6 +93,12 @@ Child agent sessions share the parent's `ModelRuntime` instance. This is critica
 
 The shared runtime is extracted from the parent's `ModelRegistry` facade (`ctx.modelRegistry`) which wraps a `ModelRuntime` as a plain `.runtime` property.
 
+## Child extensions
+
+A child loads the extensions its parent loaded. Settings discovery covers configured extensions, but `pi -e <path>` and `pi --no-extensions` live only in the parent process's arguments. `parentExtensionArgs` re-reads them from `process.argv` with Pi's own parser and resolves local `-e` paths against the launch directory, as Pi does. Every child path puts them before the dispatch's forwarded options, as on one pi command line: the background child's resource loader, `/agent-attach`, and both herdr pane paths. The dispatch's `-e` adds extensions, and its `--no-extensions` drops configured ones while explicit `-e` paths still load, as in pi.
+
+The shared runtime alone is not enough. It carries the parent's providers, but a `-e` extension's tools, commands, and hooks exist only where the extension loads.
+
 ## Model name & alias resolution
 
 User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. Other model values must exactly match a live model ID or canonical `provider/id` reference before the extension calls the SDK's `resolveCliModel`. Partial and custom model IDs are rejected.

package/attach.ts

@@ -6,9 +6,9 @@ import { herdrAgentName, insideHerdr, splitPane, startPi } from "./herdr.js";
 import { conversationFingerprint } from "./rebase.js";
 import {
 	assistantText,
-	buildChildResourceLoaderOptions,
 	createChildServices,
 	DISPATCH_PREAMBLES,
+	parentExtensionArgs,
 	parseForwardedArgs,
 	reportAgentFailure,
 	resolveToolOptions,
@@ -278,10 +278,7 @@ async function attachUserAgent(
 	// dispatch, or a /fork) restores pi defaults.
 	const record = readDispatchRecord(childSessionManager);
 	const dispatchArgs = parseForwardedArgs(record?.forwardedArgs ?? []);
-	const services = await createChildServices(
-		ctx,
-		buildChildResourceLoaderOptions(dispatchArgs, ctx.cwd),
-	);
+	const services = await createChildServices(ctx, record?.forwardedArgs ?? []);
 	// A non-empty session manager takes pi's resume path: messages, model, and thinking level
 	// are restored from the child's own file; tools and resources come from the dispatch record.
 	const { session, modelFallbackMessage } = await createAgentSessionFromServices({
@@ -332,9 +329,10 @@ async function attachUserAgent(
 
 /**
  * The herdr mechanism: attach a child session to a Pi in a new herdr pane instead of to this
- * process. The pane's Pi resumes the child's file with the dispatch record's options replayed as
- * CLI flags (see `forwardedArgsForPane`); the model and thinking level come from the file, as on
- * any resume. The file is resolved before the pane is split, so an agent without one costs no pane.
+ * process. The pane's Pi resumes the child's file with this Pi's launch extension options and the
+ * dispatch record's options as CLI flags (see `forwardedArgsForPane`); the model and thinking level
+ * come from the file, as on any resume. The file is resolved before the pane is split, so an agent
+ * without one costs no pane.
  */
 export function createHerdrDelivery(
 	getSessionContext: () => ExtensionCommandContext | undefined,
@@ -350,7 +348,12 @@ export function createHerdrDelivery(
 			)?.file;
 			if (!file) throw new Error("the agent has no session file yet (it has not answered)");
 			const record = readDispatchRecord(SessionManager.open(file));
-			const piArgs = [...forwardedArgsForPane(record?.forwardedArgs ?? []), "--session", file];
+			const piArgs = [
+				...parentExtensionArgs(),
+				...forwardedArgsForPane(record?.forwardedArgs ?? []),
+				"--session",
+				file,
+			];
 			const paneId = await splitPane(ctx.cwd);
 			return { paneId, start: () => startPi(paneId, herdrAgentName(agent.sessionId), piArgs) };
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giladbarnea/pi-user-agents",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Run, view, and control background Pi agents.",
   "keywords": [
     "pi-package",

package/runner.ts

@@ -147,10 +147,7 @@ async function startUserAgent(
 	}
 
 	// The pane's Pi loads its own resources; only a background child needs them here.
-	const services = await createChildServices(
-		ctx,
-		buildChildResourceLoaderOptions(parsedForwardedArgs, ctx.cwd),
-	);
+	const services = await createChildServices(ctx, parsed.forwardedArgs);
 	runningAgents.add(runningAgent);
 	logSteering(runningAgent.id, "agent-created", { command, taskLength: parsed.task.length });
 	if (ctx.hasUI) {
@@ -204,6 +201,7 @@ async function dispatchToHerdrPane(
 	// Explicit on the CLI too: an isolated child's file has no messages, and pi then takes the
 	// flags over the file.
 	const paneId = await openPiInHerdrPane(ctx.cwd, herdrAgentName(runningAgent.sessionId), [
+		...parentExtensionArgs(),
 		...forwardedArgsForPane(parsed.forwardedArgs),
 		"--provider",
 		model.provider,
@@ -367,24 +365,46 @@ type ForwardedOptions = ChildToolOptions & {
 	thinkingLevel?: ThinkingLevel;
 };
 
-/** The cwd-bound services for one child session; the parent's ModelRuntime rides along (see INTERNALS). */
+/**
+ * The cwd-bound services for one child session; the parent's ModelRuntime rides along (see INTERNALS).
+ * Resources come from the parent's launch extension options, then the dispatch's forwarded pi options.
+ */
 export function createChildServices(
 	ctx: ExtensionCommandContext,
-	resourceLoaderOptions?: ChildResourceLoaderOptions,
+	forwardedArgs: readonly string[],
 ): Promise<AgentSessionServices> {
 	const agentDir = getAgentDir();
 	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
 		projectTrusted: ctx.isProjectTrusted(),
 	});
+	const resourceArgs = parseForwardedArgs([...parentExtensionArgs(), ...forwardedArgs]);
 	return createAgentSessionServices({
 		cwd: ctx.cwd,
 		agentDir,
 		settingsManager,
 		modelRuntime: parentModelRuntime(ctx),
-		resourceLoaderOptions,
+		resourceLoaderOptions: buildChildResourceLoaderOptions(resourceArgs, ctx.cwd),
 	});
 }
 
+/**
+ * The extension options this Pi process was launched with, as pi CLI tokens. Pi keeps them out of
+ * settings, so a child that loads extensions from settings alone misses the parent's `-e` extensions.
+ *
+ * @example parentExtensionArgs(["--mode", "rpc", "-ne", "-e", "./a.ts", "-e", "npm:b", "hi"], "/work") // ["--no-extensions", "--extension", "/work/a.ts", "--extension", "npm:b"]
+ */
+export function parentExtensionArgs(
+	launchArgs: readonly string[] = process.argv.slice(2),
+	launchCwd: string = process.cwd(),
+): string[] {
+	const launch = parseArgs([...launchArgs]);
+	const extensions = resolveResourcePaths(launch.extensions ?? [], launchCwd).flatMap((source) => [
+		"--extension",
+		source,
+	]);
+	return launch.noExtensions ? ["--no-extensions", ...extensions] : extensions;
+}
+
 /**
  * The parent's ModelRuntime: the extension facade wraps it as a plain property. Sharing it keeps
  * extension-registered providers (their process-global dedup guard) available to the child.
@@ -532,6 +552,8 @@ export function buildChildResourceLoaderOptions(
 /** Resolve resource paths to absolute against the session cwd, matching how the CLI hands them to the loader. */
 function resolveResourcePaths(values: string[], cwd: string): string[] {
 	return values.map((value) => {
+		// Package sources such as npm:<pkg> are not paths; pi resolves them itself.
+		if (/^(npm|git|github|https?|ssh|builtin):/.test(value)) return value;
 		if (value === "~" || value.startsWith("~/")) return path.join(os.homedir(), value.slice(1));
 		return path.isAbsolute(value) ? value : path.resolve(cwd, value);
 	});