@junghanacs/entwurf 0.31.0 → 0.32.0

package/pi/pi-durable/bootstrap.mjs

@@ -16,11 +16,13 @@
 //   (`withGardenIdentity`).
 // Nothing of the native registry, controller or TUI is rebuilt here.
 //
-// It runs under the operator-provided runtime's own source resolver, which is what selects the
-// runtime — this file carries no path into it. `entwurf pi-durable` (run.sh) locates that runtime
-// at its one fixed place, verifies it against the pin, and execs:
+// The durable app itself is this package's CARRIER (./carrier/, the pinned upstream files emitted by
+// the maintainer — upstream publishes no experimental app), and it runs under the carrier's resolver,
+// which maps the app's pi-coding-agent internals to the published package the carrier resolves.
+// `entwurf pi-durable` (run.sh) verifies the carrier and its SDK set (pi-durable-runtime.ts) and
+// execs:
 //
-//   node --import <runtime>/packages/coding-agent/src/experimental/source-resolver.ts \
+//   node --import <entwurf>/pi/pi-durable/carrier-resolver.mjs \
 //        <entwurf>/pi/pi-durable/bootstrap.mjs \
 //        --provider <provider> --model <model id> --width task-wide [--entwurf-bootstrap <json>]
 //   ... bootstrap.mjs --continue
@@ -43,21 +45,36 @@
 // `--continue` opens the newest session for this directory as upstream does (not a chosen
 // record), so every flag that only a new session can honour is refused beside it by name.
 //
-// Without that resolver the two pi-coding-agent experimental subpath imports below fail: the
-// published package ships no experimental source, and that failure is the honest one. They are the
-// one sanctioned pi private-subpath exception (check-pi-import-surface, #129).
-import { realpathSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+// `--native-module <absolute file>` (#130 P2) names ONE operator module, for a new or a continued
+// session. It is an ordinary ES module: its own top-level evaluation (top-level await included) is
+// its initialization, and its default export is a native durable Extension, handed to `openDurable`
+// by reference after the contact. Initialization runs before the TUI or the runtime is imported —
+// the runtime creates the provider runtime before it installs any extension (carrier/runtime.js
+// 140-146), so an extension object cannot carry an environment phase. Entwurf checks only what the
+// ingress needs: a default export object with a name, no extension name the app installs itself (a
+// same-name install REPLACES), and no tool name of the contact. Every other field is the native
+// registry's to validate. The module is trusted operator code: the identity carriers and the
+// process directory are compared across its initialization and a change is refused by name — a
+// mistake guard, not a sandbox, and nothing is rolled back. Nothing is discovered: no directory,
+// setting, environment variable or profile names a module.
+//
+// Without that resolver the carrier's first pi-coding-agent internal import fails by name (an
+// unsupported entwurf-pi-dist: URL scheme), and that failure is the honest one.
+import { realpathSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { decodeOmpBootstrapPayload } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-omp.js";
 import {
 	closeAll,
 	createPiDurableContact,
 	failAfterCleanup,
+	PI_DURABLE_EXTENSION_NAME,
+	PI_DURABLE_TOOL_NAMES,
 	withGardenIdentity,
 } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js";
 
-const RUNTIME = "@earendil-works/pi-coding-agent/experimental/durable/runtime.ts";
-const TUI = "@earendil-works/pi-coding-agent/experimental/durable/tui.ts";
+const RUNTIME = "./carrier/runtime.js";
+const TUI = "./carrier/tui.js";
 
 /** The entwurf-bridge of THIS package closure: the one the contact spawns as its MCP hand. */
 export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
@@ -66,10 +83,19 @@ export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
 
 /** Flags that take a value. Anything else but `--continue`/`-c` is an unknown argument — a bridge
  * entry included: the launch argv cannot point the contact at another bridge. */
-const VALUE_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
+const VALUE_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap", "--native-module"];
 /** Flags only a NEW session can honour. */
 const FRESH_ONLY_FLAGS = ["--provider", "--model", "--width", "--entwurf-bootstrap"];
 
+/**
+ * Extension names the durable app installs itself — the contact, then the carrier's own
+ * (`coding-tools` pi-durable/tools, `pi-prompt` carrier/prompt.js:70, `subagent`
+ * carrier/subagent.js:25). The native registry REPLACES an installed extension of the same name.
+ */
+const RESERVED_EXTENSION_NAMES = [PI_DURABLE_EXTENSION_NAME, "coding-tools", "pi-prompt", "subagent"];
+/** The identity carriers a module's initialization must leave as it found them, every ENTWURF_* included. */
+const IDENTITY_KEYS = ["PI_SESSION_ID", "PI_CODING_AGENT_DIR", "HOME"];
+
 /** A refusal with a stable name first, so a launcher and an operator can tell the repairs apart. */
 function refuse(reason, detail) {
 	return Object.assign(new Error(`${reason}: ${detail}`), { reason });
@@ -77,6 +103,90 @@ function refuse(reason, detail) {
 
 const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
 
+/** The identity carriers present now: names and values, compared in memory and never printed. */
+function identitySnapshot() {
+	return Object.fromEntries(
+		Object.entries(process.env).filter(([key]) => IDENTITY_KEYS.includes(key) || key.startsWith("ENTWURF_")),
+	);
+}
+
+/** Keys changed, added or removed between two snapshots, sorted. */
+function identityChanges(before, after) {
+	return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+		.filter((key) => before[key] !== after[key])
+		.sort();
+}
+
+/** The operator's module path: absolute, resolving to a regular file. Decided before anything loads. */
+function nativeModuleFile(value) {
+	if (!isAbsolute(value))
+		throw refuse("native-module-path-not-absolute", `--native-module takes an absolute path, got ${value}`);
+	let file;
+	try {
+		file = realpathSync(value);
+	} catch (error) {
+		throw Object.assign(refuse("native-module-path-invalid", `${value} does not resolve`), { cause: error });
+	}
+	if (!statSync(file).isFile()) throw refuse("native-module-path-invalid", `${value} is not a regular file`);
+	return file;
+}
+
+/** The module's default export, checked only for what the ingress needs and returned BY REFERENCE. */
+function nativeExtensionOf(extension, file) {
+	if (typeof extension === "function") {
+		throw refuse(
+			"native-module-export-invalid",
+			`${file} exports a function by default — a classic ExtensionAPI factory is not a native durable extension; export the Extension object ({ name, tools?, … })`,
+		);
+	}
+	if (typeof extension !== "object" || extension === null || Array.isArray(extension)) {
+		throw refuse("native-module-export-invalid", `${file} has no default export object`);
+	}
+	if (!nonEmpty(extension.name)) throw refuse("native-module-export-invalid", `${file}'s default export has no name`);
+	if (RESERVED_EXTENSION_NAMES.includes(extension.name)) {
+		throw refuse(
+			"native-module-name-reserved",
+			`${file} names its extension ${extension.name}, which the durable app installs itself; the same name would replace it`,
+		);
+	}
+	const taken = (Array.isArray(extension.tools) ? extension.tools : [])
+		.map((tool) => tool?.name)
+		.filter((name) => PI_DURABLE_TOOL_NAMES.includes(name));
+	if (taken.length > 0) {
+		throw refuse("native-module-name-reserved", `${file} registers ${taken.join(", ")}, the contact's own tool name`);
+	}
+	return extension;
+}
+
+/**
+ * Initialize the operator's module and return its native Extension. The identity carriers and the
+ * process directory are read BEFORE its first line runs and compared once its evaluation completes.
+ */
+async function loadNativeModule(file) {
+	const before = identitySnapshot();
+	const cwd = process.cwd();
+	let namespace;
+	try {
+		namespace = await import(pathToFileURL(file).href);
+	} catch (error) {
+		throw Object.assign(
+			refuse("native-module-import-failed", `${file}: ${error instanceof Error ? error.message : String(error)}`),
+			{ cause: error },
+		);
+	}
+	const changed = identityChanges(before, identitySnapshot());
+	if (changed.length > 0) {
+		throw refuse(
+			"native-module-env-identity-changed",
+			`initializing ${file} changed ${changed.join(", ")}; a module sets its own environment, never an identity carrier`,
+		);
+	}
+	if (process.cwd() !== cwd) {
+		throw refuse("native-module-cwd-changed", `initializing ${file} moved the process out of ${cwd}`);
+	}
+	return nativeExtensionOf(namespace.default, file);
+}
+
 /**
  * Open the durable app with the contact installed, then birth the citizen and arm its doorbell on
  * the root conversation, then admit the first input (when given) to the root once. On any failure
@@ -88,6 +198,8 @@ const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0
  * roots; tests also pass a connector). `open` replaces the runtime's `openDurable` for tests.
  * `bridgeEntry` defaults to this package's own compiled bridge; only a programmatic caller (the
  * checkout-only gates, which drive a private bundle) passes another one — never the launch argv.
+ * `extensions` are the operator's native extensions (`--native-module`), installed after the
+ * contact, by reference.
  *
  * @param {{
  *   bridgeEntry?: string,
@@ -95,6 +207,7 @@ const nonEmpty = (value) => typeof value === "string" && value.trim().length > 0
  *   cwd?: string,
  *   model?: { provider: string, model: string },
  *   firstInput?: string,
+ *   extensions?: readonly object[],
  *   contact?: Record<string, unknown>,
  *   open?: (options: { cwd: string, continueSession: boolean, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
  * }} options
@@ -108,6 +221,7 @@ export async function openDurableCitizen({
 	cwd = process.cwd(),
 	model,
 	firstInput,
+	extensions = [],
 	contact: contactOptions = {},
 	open,
 }) {
@@ -130,7 +244,7 @@ export async function openDurableCitizen({
 		durable = await openDurable({
 			cwd,
 			continueSession,
-			extensions: [contact.extension],
+			extensions: [contact.extension, ...extensions],
 			...(model === undefined ? {} : { model }),
 		});
 	} catch (error) {
@@ -205,7 +319,9 @@ function parseArgs(argv) {
 			`${fresh.join(", ")} apply only to a new session; --continue reopens this directory's newest session as it was saved`,
 		);
 	}
-	if (continueSession) return { continueSession };
+	const moduleArg = values.get("--native-module");
+	const nativeModule = moduleArg === undefined ? {} : { nativeModule: nativeModuleFile(moduleArg) };
+	if (continueSession) return { continueSession, ...nativeModule };
 	const provider = values.get("--provider");
 	if (provider === undefined) {
 		throw refuse(
@@ -233,26 +349,33 @@ function parseArgs(argv) {
 		continueSession,
 		model: { provider, model },
 		...(firstInput === undefined ? {} : { firstInput }),
+		...nativeModule,
 	};
 }
 
 /**
- * Parse, load the TUI, open, run, close. `loadTui`, `open` and `contact` are test seams.
+ * Parse, initialize the operator's module, load the TUI, open, run, close. `loadTui`, `open` and
+ * `contact` are test seams; `bridgeEntry` is the checkout-only gates' private bundle, as in
+ * `openDurableCitizen` — never the launch argv.
  *
  * @param {readonly string[]} argv
  * @param {{
  *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void> }>,
  *   open?: (options: any) => Promise<any>,
  *   contact?: Record<string, unknown>,
+ *   bridgeEntry?: string,
  * }} [seams]
  */
-export async function main(argv, { loadTui = () => import(TUI), open, contact } = {}) {
-	// Every refusal is decided here, before the TUI loads and before anything opens.
-	const args = parseArgs(argv);
+export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry } = {}) {
+	// Every argument refusal is decided here, before any module, the TUI or the app loads.
+	const { nativeModule, ...args } = parseArgs(argv);
+	// The caller's directory, fixed before any operator code runs and handed to the app explicitly.
+	const cwd = process.cwd();
+	const extensions = nativeModule === undefined ? [] : [await loadNativeModule(nativeModule)];
 	// Loaded before anything opens, as upstream main.ts imports it statically: a TUI that cannot
 	// load opens no session, mints no citizen and leaves nothing to clean up.
 	const { runDurableTui } = await loadTui();
-	const citizen = await openDurableCitizen({ ...args, open, contact });
+	const citizen = await openDurableCitizen({ ...args, cwd, extensions, bridgeEntry, open, contact });
 	try {
 		await runDurableTui(
 			withGardenIdentity(citizen.durable.view, citizen.attachment.gardenId),

package/pi/pi-durable/carrier/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/pi/pi-durable/carrier/harness-setup.js

@@ -0,0 +1,123 @@
+                                                     
+                                                                
+import {
+	createRegistry,
+	               
+	                     
+	              
+	              
+} from "@earendil-works/pi-durable";
+import { NodeExecutionEnv } from "@earendil-works/pi-durable/env/node";
+import { CodingTools } from "@earendil-works/pi-durable/tools";
+import { applyHttpProxySettings, configureHttpDispatcher } from "entwurf-pi-dist:core/http-dispatcher.js";
+import { findInitialModel, resolveCliModel } from "entwurf-pi-dist:core/model-resolver.js";
+                                                                
+                                                                      
+import { createPiPrompt } from "./prompt.js";
+
+/** pi's HTTP setup: proxy, idle timeouts, and one undici for fetch. Without it, some provider streams break off. */
+export function configureHarnessHttp(settingsManager                 )       {
+	applyHttpProxySettings(settingsManager.getGlobalSettings().httpProxy);
+	configureHttpDispatcher(settingsManager.getHttpIdleTimeoutMs());
+}
+
+/** Harness settings read at every use from pi's settings as loaded at startup. */
+export function createHarnessSettings(settingsManager                 )                  {
+	return {
+		get stream() {
+			const provider = settingsManager.getProviderRetrySettings();
+			const idle = settingsManager.getHttpIdleTimeoutMs();
+			return {
+				timeoutMs: provider.timeoutMs ?? (idle === 0 ? 2147483647 : idle),
+				maxRetryDelayMs: provider.maxRetryDelayMs,
+				...(provider.maxRetries === undefined ? {} : { maxRetries: provider.maxRetries }),
+			};
+		},
+		get compaction() {
+			return settingsManager.getCompactionSettings();
+		},
+		get retry() {
+			return settingsManager.getRetrySettings();
+		},
+		get steeringMode() {
+			return settingsManager.getSteeringMode();
+		},
+		get followUpMode() {
+			return settingsManager.getFollowUpMode();
+		},
+	};
+}
+
+/** A registry with pi's coding tools and system prompt. */
+export function createCodingRegistry(settingsManager                 , cwd        )           {
+	const registry = createRegistry();
+	registry.install(CodingTools);
+	registry.install(createPiPrompt(settingsManager, cwd));
+	return registry;
+}
+
+/** One execution environment per directory, shared by every conversation in it. */
+export class ExecutionEnvs {
+	         #defaultCwd        ;
+	         #envs = new Map                          ();
+
+	constructor(defaultCwd        ) {
+		this.#defaultCwd = defaultCwd;
+	}
+
+	         env = ({ cwd = this.#defaultCwd }           )                   => {
+		let env = this.#envs.get(cwd);
+		if (env === undefined) {
+			env = new NodeExecutionEnv({ cwd });
+			this.#envs.set(cwd, env);
+		}
+		return env;
+	};
+
+	async cleanup(context         )                {
+		const envs = [...this.#envs.values()];
+		this.#envs.clear();
+		for (const env of envs) await env.cleanup(context);
+	}
+}
+
+                               
+	                          
+	                                            
+	                                  
+ 
+
+/** The model a new root conversation starts with: an explicit `--provider`/`--model`, or pi's default resolution. */
+export async function findInitialAgentModel(
+	settingsManager                 ,
+	modelRuntime              ,
+	cli                                                         ,
+)                        {
+	if (cli !== undefined) {
+		const resolved = resolveCliModel({ cliProvider: cli.provider, cliModel: cli.model, modelRuntime });
+		if (resolved.error !== undefined || resolved.model === undefined) {
+			throw new Error(`Could not resolve model: ${resolved.error ?? cli.model}`);
+		}
+		return {
+			model: { provider: resolved.model.provider, modelId: resolved.model.id },
+			...(resolved.thinkingLevel === undefined ? {} : { thinkingLevel: resolved.thinkingLevel }),
+		};
+	}
+	const initial = await findInitialModel({
+		scopedModels: [],
+		isContinuing: false,
+		defaultProvider: settingsManager.getDefaultProvider(),
+		defaultModelId: settingsManager.getDefaultModel(),
+		defaultThinkingLevel: settingsManager.getDefaultThinkingLevel(),
+		modelRuntime,
+	});
+	return {
+		...(initial.model === undefined
+			? {}
+			: {
+					model: { provider: initial.model.provider, modelId: initial.model.id },
+					thinkingLevel: initial.thinkingLevel,
+				}),
+		...(initial.fallbackMessage === undefined ? {} : { fallbackMessage: initial.fallbackMessage }),
+	};
+}

package/pi/pi-durable/carrier/prompt.js

@@ -0,0 +1,74 @@
+import { defineExtension,                   section } from "@earendil-works/pi-durable";
+import { getAgentDir } from "entwurf-pi-dist:config.js";
+import { loadProjectContextFiles } from "entwurf-pi-dist:core/resource-loader.js";
+                                                                      
+import { loadSkills,            } from "entwurf-pi-dist:core/skills.js";
+import { buildSystemPromptSections } from "entwurf-pi-dist:core/system-prompt.js";
+import { bashToolSystemPromptContribution } from "entwurf-pi-dist:core/tools/bash.js";
+import { editToolSystemPromptContribution } from "entwurf-pi-dist:core/tools/edit.js";
+import { readToolSystemPromptContribution } from "entwurf-pi-dist:core/tools/read.js";
+import { writeToolSystemPromptContribution } from "entwurf-pi-dist:core/tools/write.js";
+
+const CONTRIBUTIONS = {
+	read: readToolSystemPromptContribution,
+	bash: bashToolSystemPromptContribution,
+	edit: editToolSystemPromptContribution,
+	write: writeToolSystemPromptContribution,
+};
+
+/** pi's section order; `buildSystemPromptSections()` omits the ones without content. */
+const KEYS = ["preamble", "tools", "rules", "docs", "project_context", "skills", "cwd"]         ;
+
+/**
+ * pi's system prompt as one extension: the sections of `buildSystemPromptSections()` for the request's tools and the
+ * conversation's directory. Context files and skills load once per directory, like pi at startup.
+ */
+export function createPiPrompt(settings                 , fallbackCwd        ) {
+	const resources = new Map                                                                                ();
+	const load = (cwd        ) => {
+		let found = resources.get(cwd);
+		if (found === undefined) {
+			const agentDir = getAgentDir();
+			found = {
+				contextFiles: loadProjectContextFiles({ cwd, agentDir }),
+				skills: loadSkills({ cwd, agentDir, skillPaths: settings.getSkillPaths(), includeDefaults: true }).skills,
+			};
+			resources.set(cwd, found);
+		}
+		return found;
+	};
+	// The sections of one request render from one build.
+	const built = new WeakMap                                     ();
+	const build = (input             )                         => {
+		let sections = built.get(input);
+		if (sections === undefined) {
+			sections = buildSections(input);
+			built.set(input, sections);
+		}
+		return sections;
+	};
+	const buildSections = (input             )                         => {
+		const cwd = input.env?.cwd ?? input.agent.cwd ?? fallbackCwd;
+		const selectedTools = input.agent.tools.map((tool) => tool.name);
+		const snippets                         = {};
+		const guidelines                           = {};
+		for (const name of selectedTools) {
+			const contribution = CONTRIBUTIONS[name                              ];
+			if (contribution === undefined) continue;
+			snippets[name] = contribution.snippet;
+			guidelines[name] = [...contribution.guidelines];
+		}
+		return buildSystemPromptSections({
+			cwd,
+			selectedTools,
+			toolSnippets: snippets,
+			toolGuidelines: guidelines,
+			...load(cwd),
+		});
+	};
+	return defineExtension({
+		name: "pi-prompt",
+		// The built sections carry their own tags.
+		sections: KEYS.map((key) => section(key, (input) => build(input)[key], { tag: false })),
+	});
+}