@junghanacs/entwurf 0.36.1 → 0.37.1

package/pi/pi-durable/bootstrap.mjs

@@ -80,19 +80,21 @@ import {
 	failAfterCleanup,
 	PI_DURABLE_EXTENSION_NAME,
 	PI_DURABLE_TOOL_NAMES,
+	piDurableGardenIds,
 	withGardenIdentity,
 } from "../../mcp/entwurf-bridge/dist/pi-extensions/meta-bridge-pi-durable.js";
 
 const RUNTIME = "./carrier/runtime.js";
 const TUI = "./carrier/tui.js";
+const SESSIONS = "./carrier/sessions.js";
 
 /** The entwurf-bridge of THIS package closure: the one the contact spawns as its MCP hand. */
 export const PACKAGED_BRIDGE_ENTRY = fileURLToPath(
 	new URL("../../mcp/entwurf-bridge/dist/mcp/entwurf-bridge/src/index.js", import.meta.url),
 );
 
-/** 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. */
+/** Flags that take a value. Anything else but `--continue`/`-c` and `--resume` is an unknown argument — a
+ * bridge entry included: the launch argv cannot point the contact at another bridge. */
 const VALUE_FLAGS = [
 	"--provider",
 	"--model",
@@ -293,12 +295,13 @@ async function loadNativeModules(files) {
  * @param {{
  *   bridgeEntry?: string,
  *   continueSession?: boolean,
+ *   session?: string,
  *   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>,
+ *   open?: (options: { cwd: string, continueSession: boolean, session?: string, extensions: readonly object[], model?: { provider: string, model: string } }) => Promise<any>,
  * }} options
  * @returns {Promise<{ durable: any, contact: any, attachment: { gardenId: string } & Record<string, any>, firstInput?: any, close(): Promise<void> }>}
  *   (stated, because the compiled closure carries no declarations: a cleanup path that rethrows
@@ -307,6 +310,7 @@ async function loadNativeModules(files) {
 export async function openDurableCitizen({
 	bridgeEntry = PACKAGED_BRIDGE_ENTRY,
 	continueSession = false,
+	session,
 	cwd = process.cwd(),
 	model,
 	firstInput,
@@ -320,6 +324,12 @@ export async function openDurableCitizen({
 			"an explicit model and a first input apply only to a new session; a continued session is reopened as it was saved",
 		);
 	}
+	if (session !== undefined && (continueSession || model !== undefined || firstInput !== undefined)) {
+		throw refuse(
+			"fresh-only-argument-with-resume",
+			"a chosen session is reopened as it was saved: no --continue, explicit model or first input",
+		);
+	}
 	if (model !== undefined && !(nonEmpty(model.provider) && nonEmpty(model.model))) {
 		throw refuse("explicit-model-incomplete", "an explicit model names both its provider and its model id");
 	}
@@ -333,6 +343,7 @@ export async function openDurableCitizen({
 		durable = await openDurable({
 			cwd,
 			continueSession,
+			...(session === undefined ? {} : { session }),
 			extensions: [contact.extension, ...extensions],
 			...(model === undefined ? {} : { model }),
 		});
@@ -389,6 +400,7 @@ export async function openDurableCitizen({
 
 function parseArgs(argv) {
 	let continueSession = false;
+	let resume = false;
 	const values = new Map();
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -396,6 +408,10 @@ function parseArgs(argv) {
 			continueSession = true;
 			continue;
 		}
+		if (arg === "--resume") {
+			resume = true;
+			continue;
+		}
 		if (!VALUE_FLAGS.includes(arg)) throw new Error(`Unknown argument: ${arg}`);
 		if (values.has(arg)) throw refuse("argument-repeated", `${arg} is given more than once`);
 		const value = argv[++i];
@@ -404,7 +420,19 @@ function parseArgs(argv) {
 		}
 		values.set(arg, value);
 	}
+	if (resume && continueSession) {
+		throw refuse(
+			"resume-continue-exclusive",
+			"--resume chooses a session and --continue opens the newest one; give one of them",
+		);
+	}
 	const fresh = FRESH_ONLY_FLAGS.filter((flag) => values.has(flag));
+	if (resume && fresh.length > 0) {
+		throw refuse(
+			"fresh-only-argument-with-resume",
+			`${fresh.join(", ")} apply only to a new session; --resume reopens the chosen session as it was saved`,
+		);
+	}
 	if (continueSession && fresh.length > 0) {
 		throw refuse(
 			"fresh-only-argument-with-continue",
@@ -426,6 +454,7 @@ function parseArgs(argv) {
 				? { nativeModules: nativeModuleDirFiles(dirArg) }
 				: {};
 	if (continueSession) return { continueSession, ...nativeModule };
+	if (resume) return { resume, ...nativeModule };
 	const provider = values.get("--provider");
 	if (provider === undefined) {
 		throw refuse(
@@ -457,29 +486,102 @@ function parseArgs(argv) {
 	};
 }
 
+/** A local `YYYY-MM-DD HH:MM` for a list line. */
+function localTime(ms) {
+	const date = new Date(ms);
+	const two = (n) => String(n).padStart(2, "0");
+	return `${date.getFullYear()}-${two(date.getMonth() + 1)}-${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}`;
+}
+
 /**
- * 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.
+ * `--resume` (#143): this directory's durable sessions, most recently written first, each by what its files and
+ * the record store already say — creation time, garden id, last write, whether another process holds it. No
+ * session database is opened to list them, and nothing is named that the store does not hold. Resolves the
+ * chosen session's id, or undefined when the choice was cancelled; never a fallback to another session.
+ */
+async function chooseSession(cwd, sessionsDir, pick) {
+	const { listSessions } = await import(SESSIONS);
+	const sessions = await listSessions(cwd);
+	if (sessions.length === 0) throw refuse("resume-no-session", `no durable session exists for ${cwd}`);
+	const { gardens, unreadable } = piDurableGardenIds(
+		sessions.map((session) => session.id),
+		sessionsDir,
+	);
+	const items = sessions.map((session) => ({
+		value: session.id,
+		label: `${localTime(session.createdAt)}  ${gardens.get(session.id) ?? "no record"}`,
+		description: [
+			session.lastWriteAt === undefined ? "never written" : `last write ${localTime(session.lastWriteAt)}`,
+			session.id,
+			...(session.openElsewhere ? ["open elsewhere"] : []),
+		].join(" · "),
+	}));
+	const title =
+		unreadable === 0 ? "Resume durable session:" : `Resume durable session (${unreadable} unreadable record(s)):`;
+	const id = await pick(title, items);
+	if (id === undefined) return undefined;
+	const chosen = sessions.find((session) => session.id === id);
+	if (chosen === undefined) throw refuse("session-not-found", `${id} is not one of the listed sessions`);
+	if (chosen.openElsewhere) {
+		throw refuse("session-open-elsewhere", `${id} is open in another process; close it there first`);
+	}
+	return chosen.id;
+}
+
+/**
+ * Parse, initialize the operator's module, load the TUI, open, run, close. `loadTui`, `open`,
+ * `contact` and `pick` (the `--resume` list's choice) 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> }>,
+ *   loadTui?: () => Promise<{ runDurableTui: (...args: any[]) => Promise<void>, pickDurableSession?: (title: string, items: object[]) => Promise<string | undefined> }>,
  *   open?: (options: any) => Promise<any>,
  *   contact?: Record<string, unknown>,
  *   bridgeEntry?: string,
+ *   pick?: (title: string, items: { value: string, label: string, description: string }[]) => Promise<string | undefined>,
  * }} [seams]
  */
-export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry } = {}) {
+export async function main(argv, { loadTui = () => import(TUI), open, contact, bridgeEntry, pick } = {}) {
 	// Every argument refusal is decided here, before any module, the TUI or the app loads.
-	const { nativeModules = [], ...args } = parseArgs(argv);
+	const { nativeModules = [], resume = false, ...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 = await loadNativeModules(nativeModules);
 	// 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, cwd, extensions, bridgeEntry, open, contact });
+	const tui = await loadTui();
+	const { runDurableTui } = tui;
+	let session;
+	if (resume) {
+		session = await chooseSession(
+			cwd,
+			contact?.sessionsDir,
+			pick ??
+				((title, items) => {
+					if (!process.stdin.isTTY || !process.stdout.isTTY) {
+						throw refuse(
+							"resume-needs-terminal",
+							"--resume lists the sessions to choose from in an interactive terminal",
+						);
+					}
+					return tui.pickDurableSession(title, items);
+				}),
+		);
+		if (session === undefined) {
+			process.stderr.write("[pi-durable] resume-cancelled: nothing was opened\n");
+			return;
+		}
+	}
+	const citizen = await openDurableCitizen({
+		...args,
+		...(session === undefined ? {} : { session }),
+		cwd,
+		extensions,
+		bridgeEntry,
+		open,
+		contact,
+	});
 	try {
 		await runDurableTui(
 			withGardenIdentity(citizen.durable.view, citizen.attachment.gardenId),

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

@@ -28,13 +28,16 @@ export function createHarnessSettings(settingsManager                 )
 			const provider = settingsManager.getProviderRetrySettings();
 			const idle = settingsManager.getHttpIdleTimeoutMs();
 			return {
+				transport: settingsManager.getTransport(),
 				timeoutMs: provider.timeoutMs ?? (idle === 0 ? 2147483647 : idle),
 				maxRetryDelayMs: provider.maxRetryDelayMs,
 				...(provider.maxRetries === undefined ? {} : { maxRetries: provider.maxRetries }),
 			};
 		},
+		// The reference app waits for a compaction instead of summarizing beside the running turn (#143): no background
+		// compaction. Threshold, manual and overflow compaction stay the SDK's, on pi's own compaction settings.
 		get compaction() {
-			return settingsManager.getCompactionSettings();
+			return { ...settingsManager.getCompactionSettings(), backgroundTokens: 0 };
 		},
 		get retry() {
 			return settingsManager.getRetrySettings();

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

@@ -1,5 +1,6 @@
+import { isAbsolute, join, resolve } from "node:path";
 import { defineExtension,                   section } from "@earendil-works/pi-durable";
-import { getAgentDir } from "entwurf-pi-dist:config.js";
+import { CONFIG_DIR_NAME, 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";
@@ -19,6 +20,29 @@ const CONTRIBUTIONS = {
 /** pi's section order; `buildSystemPromptSections()` omits the ones without content. */
 const KEYS = ["preamble", "tools", "rules", "docs", "project_context", "skills", "cwd"]         ;
 
+/** An entry pi reads as a pattern, not a path: an override or a glob. */
+const PATTERN = /^[!+-]|[*?]/u;
+
+/**
+ * The `skills` setting with each scope's relative entries read against that scope's own directory, as pi resolves
+ * them: the project's against the session directory's `.pi`, the global ones against the agent directory, the
+ * project's first. Read against the conversation's directory, a relative entry names another place. Absolute, `~`
+ * and pattern entries go on unchanged.
+ */
+function scopedSkillPaths(settings                 , agentDir        , projectCwd        )           {
+	const against = (entries                               , base        )           =>
+		(entries ?? []).map((entry) => {
+			const path = entry.trim();
+			return path === "" || isAbsolute(path) || path === "~" || path.startsWith("~/") || PATTERN.test(path)
+				? entry
+				: resolve(base, path);
+		});
+	return [
+		...against(settings.getProjectSettings().skills, join(projectCwd, CONFIG_DIR_NAME)),
+		...against(settings.getGlobalSettings().skills, agentDir),
+	];
+}
+
 /**
  * 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.
@@ -31,7 +55,12 @@ export function createPiPrompt(settings                 , fallbackCwd        ) {
 			const agentDir = getAgentDir();
 			found = {
 				contextFiles: loadProjectContextFiles({ cwd, agentDir }),
-				skills: loadSkills({ cwd, agentDir, skillPaths: settings.getSkillPaths(), includeDefaults: true }).skills,
+				skills: loadSkills({
+					cwd,
+					agentDir,
+					skillPaths: scopedSkillPaths(settings, agentDir, fallbackCwd),
+					includeDefaults: true,
+				}).skills,
 			};
 			resources.set(cwd, found);
 		}

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

@@ -90,6 +90,8 @@ const context = BACKGROUND_CONTEXT;
                                      
 	                      
 	                                   
+	                                                                                         
+	                          
 	                                                                                                                 
 	                                           
 	                                                                                                           
@@ -143,10 +145,17 @@ function titleOf(entry                         )                     {
 }
 
 export async function openDurable(options                     = {})                             {
-	if (options.model !== undefined && options.continueSession) {
+	if (options.model !== undefined && (options.continueSession || options.session !== undefined)) {
 		throw new Error("An explicit model applies only to a new session, not to a continued one");
 	}
-	const location = await selectSession(options.cwd ?? process.cwd(), options.continueSession ?? false);
+	if (options.continueSession && options.session !== undefined) {
+		throw new Error("A chosen session and the newest one are two different sessions; name one");
+	}
+	const location = await selectSession(
+		options.cwd ?? process.cwd(),
+		options.continueSession ?? false,
+		options.session,
+	);
 	const envs = new ExecutionEnvs(location.cwd);
 	let harness                     ;
 	try {

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

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readdir, realpath } from "node:fs/promises";
+                                             
+import { mkdir, readdir, realpath, stat } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import lockfile from "proper-lockfile";
 import { getAgentDir } from "entwurf-pi-dist:config.js";
@@ -14,8 +15,31 @@ import { getAgentDir } from "entwurf-pi-dist:config.js";
 	                         
  
 
-/** A new session for `cwd`, or its newest one with `continueSession`. */
-export async function selectSession(cwdInput        , continueSession         )                           {
+/** One session of a directory as its files show it (#143): nothing in it is opened. */
+                               
+	           
+	                  
+	                                        
+	                  
+	                                                                                          
+	                     
+	                                                
+	                       
+ 
+
+const SESSION_NAME = /^\d{13}-[0-9a-f-]{36}$/u;
+
+/** A path's stat, or undefined when nothing is there; any other failure is thrown, never read as absence. */
+async function statIfPresent(path        )                             {
+	try {
+		return await stat(path);
+	} catch (error) {
+		if ((error                         ).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function sessionRoot(cwdInput        )                                         {
 	const cwd = await realpath(resolve(cwdInput));
 	const root = join(
 		getAgentDir(),
@@ -23,14 +47,60 @@ export async function selectSession(cwdInput        , continueSession         )
 		"durable-sessions",
 		createHash("sha256").update(cwd).digest("hex").slice(0, 24),
 	);
+	return { cwd, root };
+}
+
+/** The sessions of `cwd`, most recently written first. Reads names, file times and locks; creates nothing. */
+export async function listSessions(cwdInput        )                          {
+	const { root } = await sessionRoot(cwdInput);
+	let entries          ;
+	try {
+		entries = await readdir(root, { withFileTypes: true });
+	} catch (error) {
+		if ((error                         ).code === "ENOENT") return [];
+		throw error;
+	}
+	const sessions                 = [];
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !SESSION_NAME.test(entry.name)) continue;
+		const directory = join(root, entry.name);
+		let lastWriteAt                    ;
+		for (const file of ["session.sqlite", "session.sqlite-wal"]) {
+			const mtime = (await statIfPresent(join(directory, file)))?.mtimeMs;
+			if (mtime !== undefined && (lastWriteAt === undefined || mtime > lastWriteAt)) lastWriteAt = mtime;
+		}
+		sessions.push({
+			id: entry.name,
+			directory,
+			createdAt: Number(entry.name.slice(0, 13)),
+			...(lastWriteAt === undefined ? {} : { lastWriteAt }),
+			openElsewhere: await lockfile.check(directory, { realpath: false }),
+		});
+	}
+	return sessions.sort((a, b) => (b.lastWriteAt ?? b.createdAt) - (a.lastWriteAt ?? a.createdAt));
+}
+
+/** A new session for `cwd`, its newest one with `continueSession`, or the existing one named by `sessionId`. */
+export async function selectSession(
+	cwdInput        ,
+	continueSession         ,
+	sessionId         ,
+)                           {
+	const { cwd, root } = await sessionRoot(cwdInput);
 	await mkdir(root, { recursive: true });
 
 	let directory        ;
 	let created = false;
-	if (continueSession) {
+	if (sessionId !== undefined) {
+		const chosen = SESSION_NAME.test(sessionId) ? join(root, sessionId) : undefined;
+		if (chosen === undefined || !(await statIfPresent(chosen))?.isDirectory()) {
+			throw new Error(`No durable session ${sessionId} exists for ${cwd}`);
+		}
+		directory = chosen;
+	} else if (continueSession) {
 		const entries = await readdir(root, { withFileTypes: true });
 		const newest = entries
-			.filter((entry) => entry.isDirectory() && /^\d{13}-[0-9a-f-]{36}$/u.test(entry.name))
+			.filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
 			.map((entry) => entry.name)
 			.sort()
 			.at(-1);

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

@@ -113,6 +113,29 @@ class ListSelector extends Container                      {
 	}
 }
 
+/**
+ * Choose one of the sessions `--resume` lists (#143) before any of them opens: the /agents list on a screen of its
+ * own, stopped before the session's TUI starts. Resolves the chosen value, or undefined when cancelled.
+ */
+export function pickDurableSession(title        , items              )                              {
+	initTheme();
+	const ui = new TuiAltScreen(new ProcessTerminal(), false, getAgentDir());
+	setKeybindings(KeybindingsManager.create());
+	return new Promise((resolve) => {
+		let done = false;
+		const finish = (value                    )       => {
+			if (done) return;
+			done = true;
+			ui.stop();
+			resolve(value);
+		};
+		const selector = new ListSelector(title, items, finish, () => finish(undefined));
+		ui.addChild(selector);
+		ui.setFocus(selector);
+		ui.start();
+	});
+}
+
 /** The summary that replaced earlier context: collapsed to one line until expanded. */
 class CompactionComponent extends Box {
 	         #summary        ;

package/pi/pi-durable/overlay/upstream-pin.json

@@ -70,32 +70,32 @@
 			{
 				"name": "runtime.js",
 				"source": "pi/pi-durable/src/experimental/durable/runtime.ts",
-				"blob": "36c352291620ab86184172a1b4a0df4562ab9581",
-				"sha256": "60c2965eadbdbbe78fce1b7eeb89d97eb3104a30b7d58ebca87009d2e9118403"
+				"blob": "75d7bf2b4fdc36aa775f73f9d7f3de8659f19187",
+				"sha256": "725757156580ad2a2d170c790440763371bb8035052a0c6caae6af5159d4718f"
 			},
 			{
 				"name": "tui.js",
 				"source": "pi/pi-durable/src/experimental/durable/tui.ts",
-				"blob": "dab99cd4778ae1db7f062e64db2d0c068f7e342d",
-				"sha256": "0f9ebaf8fbb2a532ccd1a7198e1a25533a99720b5fedbf03f42d5c381db3abc5"
+				"blob": "eb5e2ec4e98919cd3ff4f81f166eb52afe6555af",
+				"sha256": "a1b0d9d9358c5b54ac0974de84068b7792669171917ebd7b7351374ed625c9c5"
 			},
 			{
 				"name": "harness-setup.js",
 				"source": "pi/pi-durable/src/experimental/durable/harness-setup.ts",
-				"blob": "4d6a4be5333ebb8e0f17eac1987f18ea35a91fc7",
-				"sha256": "712b630145dc6f5c655a85b01b1e20299c962542e63c5494d2202bb7bf414a15"
+				"blob": "36a622ec6d5dccda828ffaceaf74ce8ec241e39d",
+				"sha256": "efb06ae25258fbbab5b28f8a9bbb50956c7ebfd77a5ed23b065706f662e70ba3"
 			},
 			{
 				"name": "prompt.js",
 				"source": "pi/pi-durable/src/experimental/durable/prompt.ts",
-				"blob": "8e2f5d5273fba58da8b314766956ed62951c3814",
-				"sha256": "ff1ff765fa313e5cb1c3d7537c901c23adb0562ee433bd050fd35eb3d892134c"
+				"blob": "0e99ff64214c44986c1c2259490e401898659fd5",
+				"sha256": "15870ea4c9cb465395d70189be4f1480c48544d724bd9fc3b0e6650f17226c0f"
 			},
 			{
 				"name": "sessions.js",
 				"source": "pi/pi-durable/src/experimental/durable/sessions.ts",
-				"blob": "34f9ceeeaeaf874f7478d56115da2e4f726c6a85",
-				"sha256": "1bd1a04ece66f5ab3ca22860c64dba9abc848334d11a27a9afe543f1365c7254"
+				"blob": "eed4b3ca51c6f5a3bab8106adaf0062f3f7d5b56",
+				"sha256": "668373feadabcf13bd4dd7431e5429b7d7376c47c367e4b15353c57cb8711892"
 			},
 			{
 				"name": "subagent.js",

package/pi-extensions/meta-bridge-pi-durable.ts

@@ -113,6 +113,7 @@ import {
 	defaultMetaReceiversDir,
 	defaultMetaSendersDir,
 	defaultMetaSessionsDir,
+	listAllMetaIdentitiesDir,
 	readAddressableMetaIdentity,
 	readMetaReceiverMarker,
 	readMetaSenderMarker,
@@ -125,6 +126,25 @@ import {
 /** The backend id this contact mints under. */
 export const PI_DURABLE_BACKEND = "pi-durable" as const;
 
+/**
+ * The garden ids the record store holds for these durable sessions (#143 `--resume`), read only: a session no record
+ * names is absent, and an unreadable record is counted, never guessed.
+ */
+export function piDurableGardenIds(
+	nativeSessionIds: readonly string[],
+	sessionsDir: string = defaultMetaSessionsDir(),
+): { gardens: Map<string, string>; unreadable: number } {
+	const wanted = new Set(nativeSessionIds);
+	const { identities, errors } = listAllMetaIdentitiesDir(sessionsDir);
+	const gardens = new Map<string, string>();
+	for (const identity of identities) {
+		if (identity.backend === PI_DURABLE_BACKEND && wanted.has(identity.nativeSessionId)) {
+			gardens.set(identity.nativeSessionId, identity.gardenId);
+		}
+	}
+	return { gardens, unreadable: errors.length };
+}
+
 /** The durable Extension's name, owned exactly. */
 export const PI_DURABLE_EXTENSION_NAME = "entwurf";