@agimon-ai/po-core 0.0.0-alpha.0

package/dist/src/services/openSessionRegistry/index.cjs

@@ -0,0 +1,134 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+let node_fs = require("node:fs");
+node_fs = require_runtime.__toESM(node_fs, 1);
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+//#region src/services/openSessionRegistry/index.ts
+const REGISTRY_FILE = "open-sessions.json";
+const DIRECTORY_MODE = 448;
+const FILE_MODE = 384;
+/** The id becomes a journal filename, so it is constrained exactly as SQLite storage constrains it. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalText(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* Reads one entry, or nothing.
+*
+* The file is editable by hand and its session id is joined into a journal
+* path, so it is a trust boundary rather than trusted state this process wrote.
+* A bad entry is dropped instead of narrowing the whole file to nothing. A legacy
+* `artifact` (the worktree's pinned sync generation) is ignored: sessions compose live.
+*/
+function parseRecord(value) {
+	if (!isRecord(value)) return void 0;
+	const { sessionId, workspaceId, cwd, name, createdAt } = value;
+	if (typeof sessionId !== "string" || !SESSION_ID_PATTERN.test(sessionId)) return void 0;
+	if (typeof workspaceId !== "string" || workspaceId === "") return void 0;
+	if (typeof cwd !== "string" || !node_path.default.isAbsolute(cwd)) return void 0;
+	if (typeof name !== "string" || typeof createdAt !== "string") return void 0;
+	const parentSessionId = optionalText(value.parentSessionId);
+	const sessionProvenance = optionalText(value.sessionProvenance);
+	const repoRoot = optionalText(value.repoRoot);
+	const groupingRoot = optionalText(value.groupingRoot);
+	if (value.repoRoot !== void 0 && (!repoRoot || !node_path.default.isAbsolute(repoRoot))) return void 0;
+	if (value.groupingRoot !== void 0 && (!groupingRoot || !node_path.default.isAbsolute(groupingRoot))) return void 0;
+	return {
+		sessionId,
+		workspaceId,
+		cwd,
+		...repoRoot === void 0 ? {} : { repoRoot },
+		...groupingRoot === void 0 ? {} : { groupingRoot },
+		name,
+		createdAt,
+		...parentSessionId === void 0 ? {} : { parentSessionId },
+		...sessionProvenance === void 0 ? {} : { sessionProvenance }
+	};
+}
+/**
+* The sessions the cockpit had open, so a server restart can offer them back.
+*
+* Journals already survive a restart; what does not is the knowledge of which
+* of them were open rather than merely finished. Without that, a restart either
+* loses every session or revives every thread ever recorded.
+*/
+function createOpenSessionRegistry(options) {
+	const notice = options.onNotice ?? (() => {});
+	const filePath = node_path.default.join(options.directory, REGISTRY_FILE);
+	const load = () => {
+		let raw;
+		try {
+			raw = node_fs.default.readFileSync(filePath, "utf8");
+		} catch {
+			return [];
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`open sessions at ${filePath} are not valid JSON; none will be restored`);
+			return [];
+		}
+		if (!Array.isArray(parsed)) {
+			notice(`open sessions at ${filePath} are not a list; none will be restored`);
+			return [];
+		}
+		const records = [];
+		for (const entry of parsed) {
+			const record = parseRecord(entry);
+			if (record === void 0) notice(`open sessions at ${filePath} contain an unusable entry; skipping it`);
+			else records.push(record);
+		}
+		return records;
+	};
+	let current = load();
+	const persist = (next) => {
+		const temporary = `${filePath}.${String(process.pid)}.tmp`;
+		try {
+			node_fs.default.mkdirSync(options.directory, {
+				recursive: true,
+				mode: DIRECTORY_MODE
+			});
+			const descriptor = node_fs.default.openSync(temporary, "w", FILE_MODE);
+			try {
+				node_fs.default.writeFileSync(descriptor, `${JSON.stringify(next, void 0, 2)}\n`);
+				node_fs.default.fsyncSync(descriptor);
+			} finally {
+				node_fs.default.closeSync(descriptor);
+			}
+			node_fs.default.renameSync(temporary, filePath);
+			current = next;
+			return true;
+		} catch (error) {
+			notice(`${filePath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				node_fs.default.rmSync(temporary, { force: true });
+			} catch {}
+			return false;
+		}
+	};
+	return {
+		list: () => current,
+		add(record) {
+			if (!SESSION_ID_PATTERN.test(record.sessionId)) throw new Error(`Invalid session id '${record.sessionId}'.`);
+			for (const directory of [
+				record.cwd,
+				record.repoRoot,
+				record.groupingRoot
+			]) if (directory !== void 0 && !node_path.default.isAbsolute(directory)) throw new Error("Session directories must be absolute.");
+			return persist([...current.filter((held) => held.sessionId !== record.sessionId), record]);
+		},
+		remove(sessionId) {
+			const next = current.filter((held) => held.sessionId !== sessionId);
+			if (next.length === current.length) return;
+			persist(next);
+		}
+	};
+}
+//#endregion
+exports.createOpenSessionRegistry = createOpenSessionRegistry;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/openSessionRegistry/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["path","fs"],"sources":["../../../../src/services/openSessionRegistry/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nconst REGISTRY_FILE = 'open-sessions.json';\nconst DIRECTORY_MODE = 0o700;\nconst FILE_MODE = 0o600;\n/** The id becomes a journal filename, so it is constrained exactly as SQLite storage constrains it. */\nconst SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;\n\n/** One cockpit session the server had open, enough to reopen its journal by id. */\nexport interface OpenSessionRecord {\n  sessionId: string;\n  workspaceId: string;\n  cwd: string;\n  /** Child checkout root, distinct from the parent grouping root for worktrees. */\n  repoRoot?: string;\n  /** Parent workspace path used only to restore the workspace identity. */\n  groupingRoot?: string;\n  name: string;\n  createdAt: string;\n  parentSessionId?: string;\n  sessionProvenance?: string;\n}\n\nexport interface OpenSessionRegistry {\n  list(): readonly OpenSessionRecord[];\n  /** True only after the record is durably published. */\n  add(record: OpenSessionRecord): boolean;\n  remove(sessionId: string): void;\n}\n\nexport interface OpenSessionRegistryOptions {\n  /** Directory holding the `sessions` journal folder, so the registry sits beside what it points at. */\n  directory: string;\n  onNotice?: (message: string) => void;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction optionalText(value: unknown): string | undefined {\n  return typeof value === 'string' && value !== '' ? value : undefined;\n}\n\n/**\n * Reads one entry, or nothing.\n *\n * The file is editable by hand and its session id is joined into a journal\n * path, so it is a trust boundary rather than trusted state this process wrote.\n * A bad entry is dropped instead of narrowing the whole file to nothing. A legacy\n * `artifact` (the worktree's pinned sync generation) is ignored: sessions compose live.\n */\nfunction parseRecord(value: unknown): OpenSessionRecord | undefined {\n  if (!isRecord(value)) return undefined;\n  const { sessionId, workspaceId, cwd, name, createdAt } = value;\n  if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) return undefined;\n  if (typeof workspaceId !== 'string' || workspaceId === '') return undefined;\n  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return undefined;\n  if (typeof name !== 'string' || typeof createdAt !== 'string') return undefined;\n  const parentSessionId = optionalText(value.parentSessionId);\n  const sessionProvenance = optionalText(value.sessionProvenance);\n  const repoRoot = optionalText(value.repoRoot);\n  const groupingRoot = optionalText(value.groupingRoot);\n  if (value.repoRoot !== undefined && (!repoRoot || !path.isAbsolute(repoRoot))) return undefined;\n  if (value.groupingRoot !== undefined && (!groupingRoot || !path.isAbsolute(groupingRoot))) return undefined;\n  return {\n    sessionId,\n    workspaceId,\n    cwd,\n    ...(repoRoot === undefined ? {} : { repoRoot }),\n    ...(groupingRoot === undefined ? {} : { groupingRoot }),\n    name,\n    createdAt,\n    ...(parentSessionId === undefined ? {} : { parentSessionId }),\n    ...(sessionProvenance === undefined ? {} : { sessionProvenance }),\n  };\n}\n\n/**\n * The sessions the cockpit had open, so a server restart can offer them back.\n *\n * Journals already survive a restart; what does not is the knowledge of which\n * of them were open rather than merely finished. Without that, a restart either\n * loses every session or revives every thread ever recorded.\n */\nexport function createOpenSessionRegistry(options: OpenSessionRegistryOptions): OpenSessionRegistry {\n  const notice = options.onNotice ?? ((): void => {});\n  const filePath = path.join(options.directory, REGISTRY_FILE);\n\n  const load = (): OpenSessionRecord[] => {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(filePath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return [];\n    }\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Left in place rather than rewritten: a file somebody hand-edited is\n      // worth more as evidence than as something this process silently repairs.\n      notice(`open sessions at ${filePath} are not valid JSON; none will be restored`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) {\n      notice(`open sessions at ${filePath} are not a list; none will be restored`);\n      return [];\n    }\n    const records: OpenSessionRecord[] = [];\n    for (const entry of parsed) {\n      const record = parseRecord(entry);\n      if (record === undefined) notice(`open sessions at ${filePath} contain an unusable entry; skipping it`);\n      else records.push(record);\n    }\n    return records;\n  };\n\n  let current = load();\n\n  const persist = (next: OpenSessionRecord[]): boolean => {\n    const temporary = `${filePath}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(options.directory, { recursive: true, mode: DIRECTORY_MODE });\n      const descriptor = fs.openSync(temporary, 'w', FILE_MODE);\n      try {\n        fs.writeFileSync(descriptor, `${JSON.stringify(next, undefined, 2)}\\n`);\n        fs.fsyncSync(descriptor);\n      } finally {\n        fs.closeSync(descriptor);\n      }\n      // Rename rather than write in place, so a crash mid-write leaves the\n      // previous contents rather than a truncated file.\n      fs.renameSync(temporary, filePath);\n      current = next;\n      return true;\n    } catch (error) {\n      notice(`${filePath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);\n      try {\n        fs.rmSync(temporary, { force: true });\n      } catch {\n        // Nothing further to do; the temp file is inert either way.\n      }\n      return false;\n    }\n  };\n\n  return {\n    list: () => current,\n    add(record) {\n      if (!SESSION_ID_PATTERN.test(record.sessionId)) throw new Error(`Invalid session id '${record.sessionId}'.`);\n      for (const directory of [record.cwd, record.repoRoot, record.groupingRoot]) {\n        if (directory !== undefined && !path.isAbsolute(directory))\n          throw new Error('Session directories must be absolute.');\n      }\n      return persist([...current.filter((held) => held.sessionId !== record.sessionId), record]);\n    },\n    remove(sessionId) {\n      const next = current.filter((held) => held.sessionId !== sessionId);\n      if (next.length === current.length) return;\n      persist(next);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/src/services/openSessionRegistry/index.d.mts

@@ -0,0 +1,36 @@
+//#region src/services/openSessionRegistry/index.d.ts
+/** One cockpit session the server had open, enough to reopen its journal by id. */
+export interface OpenSessionRecord {
+  sessionId: string;
+  workspaceId: string;
+  cwd: string;
+  /** Child checkout root, distinct from the parent grouping root for worktrees. */
+  repoRoot?: string;
+  /** Parent workspace path used only to restore the workspace identity. */
+  groupingRoot?: string;
+  name: string;
+  createdAt: string;
+  parentSessionId?: string;
+  sessionProvenance?: string;
+}
+export interface OpenSessionRegistry {
+  list(): readonly OpenSessionRecord[];
+  /** True only after the record is durably published. */
+  add(record: OpenSessionRecord): boolean;
+  remove(sessionId: string): void;
+}
+export interface OpenSessionRegistryOptions {
+  /** Directory holding the `sessions` journal folder, so the registry sits beside what it points at. */
+  directory: string;
+  onNotice?: (message: string) => void;
+}
+/**
+ * The sessions the cockpit had open, so a server restart can offer them back.
+ *
+ * Journals already survive a restart; what does not is the knowledge of which
+ * of them were open rather than merely finished. Without that, a restart either
+ * loses every session or revives every thread ever recorded.
+ */
+export declare function createOpenSessionRegistry(options: OpenSessionRegistryOptions): OpenSessionRegistry;
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/src/services/openSessionRegistry/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/openSessionRegistry/index.ts"],"mappings":";;iBAUiB;EACf;EACA;EACA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;iBAGe;EACf,iBAAiB;;EAEjB,IAAI,QAAQ;EACZ,OAAO;;iBAGQ;;EAEf;EACA,YAAY;;;;;;;;;wBAoDE,0BAA0B,SAAS,6BAA6B"}

package/dist/src/services/openSessionRegistry/index.mjs

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+//#region src/services/openSessionRegistry/index.ts
+const REGISTRY_FILE = "open-sessions.json";
+const DIRECTORY_MODE = 448;
+const FILE_MODE = 384;
+/** The id becomes a journal filename, so it is constrained exactly as SQLite storage constrains it. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalText(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* Reads one entry, or nothing.
+*
+* The file is editable by hand and its session id is joined into a journal
+* path, so it is a trust boundary rather than trusted state this process wrote.
+* A bad entry is dropped instead of narrowing the whole file to nothing. A legacy
+* `artifact` (the worktree's pinned sync generation) is ignored: sessions compose live.
+*/
+function parseRecord(value) {
+	if (!isRecord(value)) return void 0;
+	const { sessionId, workspaceId, cwd, name, createdAt } = value;
+	if (typeof sessionId !== "string" || !SESSION_ID_PATTERN.test(sessionId)) return void 0;
+	if (typeof workspaceId !== "string" || workspaceId === "") return void 0;
+	if (typeof cwd !== "string" || !path.isAbsolute(cwd)) return void 0;
+	if (typeof name !== "string" || typeof createdAt !== "string") return void 0;
+	const parentSessionId = optionalText(value.parentSessionId);
+	const sessionProvenance = optionalText(value.sessionProvenance);
+	const repoRoot = optionalText(value.repoRoot);
+	const groupingRoot = optionalText(value.groupingRoot);
+	if (value.repoRoot !== void 0 && (!repoRoot || !path.isAbsolute(repoRoot))) return void 0;
+	if (value.groupingRoot !== void 0 && (!groupingRoot || !path.isAbsolute(groupingRoot))) return void 0;
+	return {
+		sessionId,
+		workspaceId,
+		cwd,
+		...repoRoot === void 0 ? {} : { repoRoot },
+		...groupingRoot === void 0 ? {} : { groupingRoot },
+		name,
+		createdAt,
+		...parentSessionId === void 0 ? {} : { parentSessionId },
+		...sessionProvenance === void 0 ? {} : { sessionProvenance }
+	};
+}
+/**
+* The sessions the cockpit had open, so a server restart can offer them back.
+*
+* Journals already survive a restart; what does not is the knowledge of which
+* of them were open rather than merely finished. Without that, a restart either
+* loses every session or revives every thread ever recorded.
+*/
+function createOpenSessionRegistry(options) {
+	const notice = options.onNotice ?? (() => {});
+	const filePath = path.join(options.directory, REGISTRY_FILE);
+	const load = () => {
+		let raw;
+		try {
+			raw = fs.readFileSync(filePath, "utf8");
+		} catch {
+			return [];
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			notice(`open sessions at ${filePath} are not valid JSON; none will be restored`);
+			return [];
+		}
+		if (!Array.isArray(parsed)) {
+			notice(`open sessions at ${filePath} are not a list; none will be restored`);
+			return [];
+		}
+		const records = [];
+		for (const entry of parsed) {
+			const record = parseRecord(entry);
+			if (record === void 0) notice(`open sessions at ${filePath} contain an unusable entry; skipping it`);
+			else records.push(record);
+		}
+		return records;
+	};
+	let current = load();
+	const persist = (next) => {
+		const temporary = `${filePath}.${String(process.pid)}.tmp`;
+		try {
+			fs.mkdirSync(options.directory, {
+				recursive: true,
+				mode: DIRECTORY_MODE
+			});
+			const descriptor = fs.openSync(temporary, "w", FILE_MODE);
+			try {
+				fs.writeFileSync(descriptor, `${JSON.stringify(next, void 0, 2)}\n`);
+				fs.fsyncSync(descriptor);
+			} finally {
+				fs.closeSync(descriptor);
+			}
+			fs.renameSync(temporary, filePath);
+			current = next;
+			return true;
+		} catch (error) {
+			notice(`${filePath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);
+			try {
+				fs.rmSync(temporary, { force: true });
+			} catch {}
+			return false;
+		}
+	};
+	return {
+		list: () => current,
+		add(record) {
+			if (!SESSION_ID_PATTERN.test(record.sessionId)) throw new Error(`Invalid session id '${record.sessionId}'.`);
+			for (const directory of [
+				record.cwd,
+				record.repoRoot,
+				record.groupingRoot
+			]) if (directory !== void 0 && !path.isAbsolute(directory)) throw new Error("Session directories must be absolute.");
+			return persist([...current.filter((held) => held.sessionId !== record.sessionId), record]);
+		},
+		remove(sessionId) {
+			const next = current.filter((held) => held.sessionId !== sessionId);
+			if (next.length === current.length) return;
+			persist(next);
+		}
+	};
+}
+//#endregion
+export { createOpenSessionRegistry };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/openSessionRegistry/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/openSessionRegistry/index.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nconst REGISTRY_FILE = 'open-sessions.json';\nconst DIRECTORY_MODE = 0o700;\nconst FILE_MODE = 0o600;\n/** The id becomes a journal filename, so it is constrained exactly as SQLite storage constrains it. */\nconst SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;\n\n/** One cockpit session the server had open, enough to reopen its journal by id. */\nexport interface OpenSessionRecord {\n  sessionId: string;\n  workspaceId: string;\n  cwd: string;\n  /** Child checkout root, distinct from the parent grouping root for worktrees. */\n  repoRoot?: string;\n  /** Parent workspace path used only to restore the workspace identity. */\n  groupingRoot?: string;\n  name: string;\n  createdAt: string;\n  parentSessionId?: string;\n  sessionProvenance?: string;\n}\n\nexport interface OpenSessionRegistry {\n  list(): readonly OpenSessionRecord[];\n  /** True only after the record is durably published. */\n  add(record: OpenSessionRecord): boolean;\n  remove(sessionId: string): void;\n}\n\nexport interface OpenSessionRegistryOptions {\n  /** Directory holding the `sessions` journal folder, so the registry sits beside what it points at. */\n  directory: string;\n  onNotice?: (message: string) => void;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction optionalText(value: unknown): string | undefined {\n  return typeof value === 'string' && value !== '' ? value : undefined;\n}\n\n/**\n * Reads one entry, or nothing.\n *\n * The file is editable by hand and its session id is joined into a journal\n * path, so it is a trust boundary rather than trusted state this process wrote.\n * A bad entry is dropped instead of narrowing the whole file to nothing. A legacy\n * `artifact` (the worktree's pinned sync generation) is ignored: sessions compose live.\n */\nfunction parseRecord(value: unknown): OpenSessionRecord | undefined {\n  if (!isRecord(value)) return undefined;\n  const { sessionId, workspaceId, cwd, name, createdAt } = value;\n  if (typeof sessionId !== 'string' || !SESSION_ID_PATTERN.test(sessionId)) return undefined;\n  if (typeof workspaceId !== 'string' || workspaceId === '') return undefined;\n  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) return undefined;\n  if (typeof name !== 'string' || typeof createdAt !== 'string') return undefined;\n  const parentSessionId = optionalText(value.parentSessionId);\n  const sessionProvenance = optionalText(value.sessionProvenance);\n  const repoRoot = optionalText(value.repoRoot);\n  const groupingRoot = optionalText(value.groupingRoot);\n  if (value.repoRoot !== undefined && (!repoRoot || !path.isAbsolute(repoRoot))) return undefined;\n  if (value.groupingRoot !== undefined && (!groupingRoot || !path.isAbsolute(groupingRoot))) return undefined;\n  return {\n    sessionId,\n    workspaceId,\n    cwd,\n    ...(repoRoot === undefined ? {} : { repoRoot }),\n    ...(groupingRoot === undefined ? {} : { groupingRoot }),\n    name,\n    createdAt,\n    ...(parentSessionId === undefined ? {} : { parentSessionId }),\n    ...(sessionProvenance === undefined ? {} : { sessionProvenance }),\n  };\n}\n\n/**\n * The sessions the cockpit had open, so a server restart can offer them back.\n *\n * Journals already survive a restart; what does not is the knowledge of which\n * of them were open rather than merely finished. Without that, a restart either\n * loses every session or revives every thread ever recorded.\n */\nexport function createOpenSessionRegistry(options: OpenSessionRegistryOptions): OpenSessionRegistry {\n  const notice = options.onNotice ?? ((): void => {});\n  const filePath = path.join(options.directory, REGISTRY_FILE);\n\n  const load = (): OpenSessionRecord[] => {\n    let raw: string;\n    try {\n      raw = fs.readFileSync(filePath, 'utf8');\n    } catch {\n      // No file is the normal first run, so this is not worth a notice.\n      return [];\n    }\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      // Left in place rather than rewritten: a file somebody hand-edited is\n      // worth more as evidence than as something this process silently repairs.\n      notice(`open sessions at ${filePath} are not valid JSON; none will be restored`);\n      return [];\n    }\n    if (!Array.isArray(parsed)) {\n      notice(`open sessions at ${filePath} are not a list; none will be restored`);\n      return [];\n    }\n    const records: OpenSessionRecord[] = [];\n    for (const entry of parsed) {\n      const record = parseRecord(entry);\n      if (record === undefined) notice(`open sessions at ${filePath} contain an unusable entry; skipping it`);\n      else records.push(record);\n    }\n    return records;\n  };\n\n  let current = load();\n\n  const persist = (next: OpenSessionRecord[]): boolean => {\n    const temporary = `${filePath}.${String(process.pid)}.tmp`;\n    try {\n      fs.mkdirSync(options.directory, { recursive: true, mode: DIRECTORY_MODE });\n      const descriptor = fs.openSync(temporary, 'w', FILE_MODE);\n      try {\n        fs.writeFileSync(descriptor, `${JSON.stringify(next, undefined, 2)}\\n`);\n        fs.fsyncSync(descriptor);\n      } finally {\n        fs.closeSync(descriptor);\n      }\n      // Rename rather than write in place, so a crash mid-write leaves the\n      // previous contents rather than a truncated file.\n      fs.renameSync(temporary, filePath);\n      current = next;\n      return true;\n    } catch (error) {\n      notice(`${filePath} could not be saved: ${error instanceof Error ? error.message : String(error)}`);\n      try {\n        fs.rmSync(temporary, { force: true });\n      } catch {\n        // Nothing further to do; the temp file is inert either way.\n      }\n      return false;\n    }\n  };\n\n  return {\n    list: () => current,\n    add(record) {\n      if (!SESSION_ID_PATTERN.test(record.sessionId)) throw new Error(`Invalid session id '${record.sessionId}'.`);\n      for (const directory of [record.cwd, record.repoRoot, record.groupingRoot]) {\n        if (directory !== undefined && !path.isAbsolute(directory))\n          throw new Error('Session directories must be absolute.');\n      }\n      return persist([...current.filter((held) => held.sessionId !== record.sessionId), record]);\n    },\n    remove(sessionId) {\n      const next = current.filter((held) => held.sessionId !== sessionId);\n      if (next.length === current.length) return;\n      persist(next);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/src/services/packageApiHarness/index.cjs

@@ -0,0 +1,36 @@
+const require_packageApi = require("../../schemas/packageApi.cjs");
+//#region src/services/packageApiHarness/index.ts
+const DEFAULT_SCOPE = "global";
+const DEFAULT_CWD = "/repo";
+/** Any origin will do: the host routes on path, and a Request needs an absolute URL. */
+const ORIGIN = "http://host";
+function mountPackageApi(api, options = {}) {
+	const scope = options.scope ?? DEFAULT_SCOPE;
+	const notices = [];
+	const mountPath = `${require_packageApi.DOOM_API_ROUTE_PREFIX}/${api.basePath}`;
+	const context = {
+		scope,
+		...scope === "session" ? {
+			sessionId: options.sessionId ?? "test-session",
+			cwd: options.cwd ?? DEFAULT_CWD
+		} : {},
+		...options.directEvents ? { directEvents: options.directEvents } : {},
+		onNotice: (message) => notices.push(message)
+	};
+	const handler = api.start(context);
+	return {
+		mountPath,
+		notices,
+		async fetch(path, init) {
+			const url = new URL(path, ORIGIN);
+			if (url.pathname !== mountPath && !url.pathname.startsWith(`${mountPath}/`)) return new Response(`No package API is mounted at ${url.pathname}.`, { status: 404 });
+			url.pathname = url.pathname.slice(mountPath.length) || "/";
+			return handler.fetch(new Request(url, init));
+		},
+		close: () => handler.close()
+	};
+}
+//#endregion
+exports.mountPackageApi = mountPackageApi;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/packageApiHarness/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["DOOM_API_ROUTE_PREFIX"],"sources":["../../../../src/services/packageApiHarness/index.ts"],"sourcesContent":["import type { DoomDirectEventBus } from '../../schemas/hubChannel';\nimport {\n  type DoomApi,\n  type DoomApiContext,\n  type DoomApiHandler,\n  DOOM_API_ROUTE_PREFIX,\n  type DoomApiScope,\n} from '../../schemas/packageApi';\n\n/**\n * A package's HTTP surface, mounted the way a host mounts it.\n *\n * A package tests its routes by calling its Hono app directly, which proves the\n * routes but not the mount: the host serves them under\n * `/api/plugins/<basePath>` and strips that prefix before the app sees the\n * request. A package whose routes are written absolute passes its own suite and\n * answers nothing in a running cockpit.\n *\n * This mounts the declared `DoomApi` the same way, so a test asks for the URL a\n * browser would ask for. Plain `Request` and `Response`; no HTTP framework and\n * no server.\n */\n\nexport interface MountPackageApiOptions {\n  scope?: DoomApiScope;\n  sessionId?: string;\n  cwd?: string;\n  directEvents?: DoomDirectEventBus;\n}\n\nexport interface MountedPackageApi {\n  /** Where the host mounted it, for building a URL the way a client does. */\n  readonly mountPath: string;\n  /** What the API reported to its host; a package that notices nothing leaves this empty. */\n  readonly notices: readonly string[];\n  /**\n   * Fetches one path.\n   *\n   * The path is host-absolute, so it carries the mount the client would send:\n   * `/api/plugins/workflow/runs/repo/blog-4`. A path outside the mount is a 404\n   * from this, exactly as it is from the host.\n   */\n  fetch(path: string, init?: RequestInit): Promise<Response>;\n  close(): void;\n}\n\nconst DEFAULT_SCOPE: DoomApiScope = 'global';\nconst DEFAULT_CWD = '/repo';\n/** Any origin will do: the host routes on path, and a Request needs an absolute URL. */\nconst ORIGIN = 'http://host';\n\nexport function mountPackageApi(api: DoomApi, options: MountPackageApiOptions = {}): MountedPackageApi {\n  const scope = options.scope ?? DEFAULT_SCOPE;\n  const notices: string[] = [];\n  const mountPath = `${DOOM_API_ROUTE_PREFIX}/${api.basePath}`;\n  const context: DoomApiContext = {\n    scope,\n    // A session-scoped host knows both; a hub-scoped one knows neither, and an\n    // API that reads them anyway should see the same undefined it would there.\n    ...(scope === 'session' ? { sessionId: options.sessionId ?? 'test-session', cwd: options.cwd ?? DEFAULT_CWD } : {}),\n    ...(options.directEvents ? { directEvents: options.directEvents } : {}),\n    onNotice: (message) => notices.push(message),\n  };\n  const handler: DoomApiHandler = api.start(context);\n\n  return {\n    mountPath,\n    notices,\n    async fetch(path, init) {\n      const url = new URL(path, ORIGIN);\n      if (url.pathname !== mountPath && !url.pathname.startsWith(`${mountPath}/`)) {\n        return new Response(`No package API is mounted at ${url.pathname}.`, { status: 404 });\n      }\n      // The host strips its own mount, so a package declares '/runs/:id' and\n      // never repeats where it was mounted.\n      url.pathname = url.pathname.slice(mountPath.length) || '/';\n      return handler.fetch(new Request(url, init));\n    },\n    close: () => handler.close(),\n  };\n}\n"],"mappings":";;AA8CA,MAAM,gBAA8B;AACpC,MAAM,cAAc;;AAEpB,MAAM,SAAS;AAEf,SAAgB,gBAAgB,KAAc,UAAkC,CAAC,GAAsB;CACrG,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,UAAoB,CAAC;CAC3B,MAAM,YAAY,GAAGA,mBAAAA,sBAAsB,GAAG,IAAI;CAClD,MAAM,UAA0B;EAC9B;EAGA,GAAI,UAAU,YAAY;GAAE,WAAW,QAAQ,aAAa;GAAgB,KAAK,QAAQ,OAAO;EAAY,IAAI,CAAC;EACjH,GAAI,QAAQ,eAAe,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;EACrE,WAAW,YAAY,QAAQ,KAAK,OAAO;CAC7C;CACA,MAAM,UAA0B,IAAI,MAAM,OAAO;CAEjD,OAAO;EACL;EACA;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,MAAM,IAAI,IAAI,MAAM,MAAM;GAChC,IAAI,IAAI,aAAa,aAAa,CAAC,IAAI,SAAS,WAAW,GAAG,UAAU,EAAE,GACxE,OAAO,IAAI,SAAS,gCAAgC,IAAI,SAAS,IAAI,EAAE,QAAQ,IAAI,CAAC;GAItF,IAAI,WAAW,IAAI,SAAS,MAAM,UAAU,MAAM,KAAK;GACvD,OAAO,QAAQ,MAAM,IAAI,QAAQ,KAAK,IAAI,CAAC;EAC7C;EACA,aAAa,QAAQ,MAAM;CAC7B;AACF"}

package/dist/src/services/packageApiHarness/index.d.mts

@@ -0,0 +1,40 @@
+import { DoomDirectEventBus } from "../../schemas/hubChannel.mjs";
+import { DoomApi, DoomApiScope } from "../../schemas/packageApi.mjs";
+//#region src/services/packageApiHarness/index.d.ts
+/**
+ * A package's HTTP surface, mounted the way a host mounts it.
+ *
+ * A package tests its routes by calling its Hono app directly, which proves the
+ * routes but not the mount: the host serves them under
+ * `/api/plugins/<basePath>` and strips that prefix before the app sees the
+ * request. A package whose routes are written absolute passes its own suite and
+ * answers nothing in a running cockpit.
+ *
+ * This mounts the declared `DoomApi` the same way, so a test asks for the URL a
+ * browser would ask for. Plain `Request` and `Response`; no HTTP framework and
+ * no server.
+ */
+export interface MountPackageApiOptions {
+  scope?: DoomApiScope;
+  sessionId?: string;
+  cwd?: string;
+  directEvents?: DoomDirectEventBus;
+}
+export interface MountedPackageApi {
+  /** Where the host mounted it, for building a URL the way a client does. */
+  readonly mountPath: string;
+  /** What the API reported to its host; a package that notices nothing leaves this empty. */
+  readonly notices: readonly string[];
+  /**
+   * Fetches one path.
+   *
+   * The path is host-absolute, so it carries the mount the client would send:
+   * `/api/plugins/workflow/runs/repo/blog-4`. A path outside the mount is a 404
+   * from this, exactly as it is from the host.
+   */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+  close(): void;
+}
+export declare function mountPackageApi(api: DoomApi, options?: MountPackageApiOptions): MountedPackageApi;
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/src/services/packageApiHarness/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/packageApiHarness/index.ts"],"mappings":";;;;;;;;;;;;;;;;iBAuBiB;EACf,QAAQ;EACR;EACA;EACA,eAAe;;iBAGA;;WAEN;;WAEA;;;;;;;;EAQT,MAAM,cAAc,OAAO,cAAc,QAAQ;EACjD;;wBAQc,gBAAgB,KAAK,SAAS,UAAS,yBAA8B"}

package/dist/src/services/packageApiHarness/index.mjs

@@ -0,0 +1,36 @@
+import { DOOM_API_ROUTE_PREFIX } from "../../schemas/packageApi.mjs";
+//#region src/services/packageApiHarness/index.ts
+const DEFAULT_SCOPE = "global";
+const DEFAULT_CWD = "/repo";
+/** Any origin will do: the host routes on path, and a Request needs an absolute URL. */
+const ORIGIN = "http://host";
+function mountPackageApi(api, options = {}) {
+	const scope = options.scope ?? DEFAULT_SCOPE;
+	const notices = [];
+	const mountPath = `${DOOM_API_ROUTE_PREFIX}/${api.basePath}`;
+	const context = {
+		scope,
+		...scope === "session" ? {
+			sessionId: options.sessionId ?? "test-session",
+			cwd: options.cwd ?? DEFAULT_CWD
+		} : {},
+		...options.directEvents ? { directEvents: options.directEvents } : {},
+		onNotice: (message) => notices.push(message)
+	};
+	const handler = api.start(context);
+	return {
+		mountPath,
+		notices,
+		async fetch(path, init) {
+			const url = new URL(path, ORIGIN);
+			if (url.pathname !== mountPath && !url.pathname.startsWith(`${mountPath}/`)) return new Response(`No package API is mounted at ${url.pathname}.`, { status: 404 });
+			url.pathname = url.pathname.slice(mountPath.length) || "/";
+			return handler.fetch(new Request(url, init));
+		},
+		close: () => handler.close()
+	};
+}
+//#endregion
+export { mountPackageApi };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/packageApiHarness/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/packageApiHarness/index.ts"],"sourcesContent":["import type { DoomDirectEventBus } from '../../schemas/hubChannel';\nimport {\n  type DoomApi,\n  type DoomApiContext,\n  type DoomApiHandler,\n  DOOM_API_ROUTE_PREFIX,\n  type DoomApiScope,\n} from '../../schemas/packageApi';\n\n/**\n * A package's HTTP surface, mounted the way a host mounts it.\n *\n * A package tests its routes by calling its Hono app directly, which proves the\n * routes but not the mount: the host serves them under\n * `/api/plugins/<basePath>` and strips that prefix before the app sees the\n * request. A package whose routes are written absolute passes its own suite and\n * answers nothing in a running cockpit.\n *\n * This mounts the declared `DoomApi` the same way, so a test asks for the URL a\n * browser would ask for. Plain `Request` and `Response`; no HTTP framework and\n * no server.\n */\n\nexport interface MountPackageApiOptions {\n  scope?: DoomApiScope;\n  sessionId?: string;\n  cwd?: string;\n  directEvents?: DoomDirectEventBus;\n}\n\nexport interface MountedPackageApi {\n  /** Where the host mounted it, for building a URL the way a client does. */\n  readonly mountPath: string;\n  /** What the API reported to its host; a package that notices nothing leaves this empty. */\n  readonly notices: readonly string[];\n  /**\n   * Fetches one path.\n   *\n   * The path is host-absolute, so it carries the mount the client would send:\n   * `/api/plugins/workflow/runs/repo/blog-4`. A path outside the mount is a 404\n   * from this, exactly as it is from the host.\n   */\n  fetch(path: string, init?: RequestInit): Promise<Response>;\n  close(): void;\n}\n\nconst DEFAULT_SCOPE: DoomApiScope = 'global';\nconst DEFAULT_CWD = '/repo';\n/** Any origin will do: the host routes on path, and a Request needs an absolute URL. */\nconst ORIGIN = 'http://host';\n\nexport function mountPackageApi(api: DoomApi, options: MountPackageApiOptions = {}): MountedPackageApi {\n  const scope = options.scope ?? DEFAULT_SCOPE;\n  const notices: string[] = [];\n  const mountPath = `${DOOM_API_ROUTE_PREFIX}/${api.basePath}`;\n  const context: DoomApiContext = {\n    scope,\n    // A session-scoped host knows both; a hub-scoped one knows neither, and an\n    // API that reads them anyway should see the same undefined it would there.\n    ...(scope === 'session' ? { sessionId: options.sessionId ?? 'test-session', cwd: options.cwd ?? DEFAULT_CWD } : {}),\n    ...(options.directEvents ? { directEvents: options.directEvents } : {}),\n    onNotice: (message) => notices.push(message),\n  };\n  const handler: DoomApiHandler = api.start(context);\n\n  return {\n    mountPath,\n    notices,\n    async fetch(path, init) {\n      const url = new URL(path, ORIGIN);\n      if (url.pathname !== mountPath && !url.pathname.startsWith(`${mountPath}/`)) {\n        return new Response(`No package API is mounted at ${url.pathname}.`, { status: 404 });\n      }\n      // The host strips its own mount, so a package declares '/runs/:id' and\n      // never repeats where it was mounted.\n      url.pathname = url.pathname.slice(mountPath.length) || '/';\n      return handler.fetch(new Request(url, init));\n    },\n    close: () => handler.close(),\n  };\n}\n"],"mappings":";;AA8CA,MAAM,gBAA8B;AACpC,MAAM,cAAc;;AAEpB,MAAM,SAAS;AAEf,SAAgB,gBAAgB,KAAc,UAAkC,CAAC,GAAsB;CACrG,MAAM,QAAQ,QAAQ,SAAS;CAC/B,MAAM,UAAoB,CAAC;CAC3B,MAAM,YAAY,GAAG,sBAAsB,GAAG,IAAI;CAClD,MAAM,UAA0B;EAC9B;EAGA,GAAI,UAAU,YAAY;GAAE,WAAW,QAAQ,aAAa;GAAgB,KAAK,QAAQ,OAAO;EAAY,IAAI,CAAC;EACjH,GAAI,QAAQ,eAAe,EAAE,cAAc,QAAQ,aAAa,IAAI,CAAC;EACrE,WAAW,YAAY,QAAQ,KAAK,OAAO;CAC7C;CACA,MAAM,UAA0B,IAAI,MAAM,OAAO;CAEjD,OAAO;EACL;EACA;EACA,MAAM,MAAM,MAAM,MAAM;GACtB,MAAM,MAAM,IAAI,IAAI,MAAM,MAAM;GAChC,IAAI,IAAI,aAAa,aAAa,CAAC,IAAI,SAAS,WAAW,GAAG,UAAU,EAAE,GACxE,OAAO,IAAI,SAAS,gCAAgC,IAAI,SAAS,IAAI,EAAE,QAAQ,IAAI,CAAC;GAItF,IAAI,WAAW,IAAI,SAAS,MAAM,UAAU,MAAM,KAAK;GACvD,OAAO,QAAQ,MAAM,IAAI,QAAQ,KAAK,IAAI,CAAC;EAC7C;EACA,aAAa,QAAQ,MAAM;CAC7B;AACF"}

package/dist/src/services/packageResource/index.cjs

@@ -0,0 +1,54 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+let node_url = require("node:url");
+//#region src/services/packageResource/index.ts
+/**
+* Absolute path of a file shipped by the calling package.
+*
+* Anchored on the nearest ancestor holding a `package.json`, which is the only
+* sentinel that is correct from `src/` and from `dist/` alike. Counting levels
+* with a fixed `new URL('../../..', import.meta.url)` is not: a bundled entry
+* sits at a different depth than its source, so the walk lands outside the
+* package and every read misses.
+*
+* `moduleUrl` is required on purpose. A default of `import.meta.url` resolves to
+* this package rather than the caller's, which is a silently wrong answer.
+*/
+function packageResourcePath(moduleUrl, file) {
+	let directory = node_path.default.dirname((0, node_url.fileURLToPath)(moduleUrl));
+	for (;;) {
+		if ((0, node_fs.existsSync)(node_path.default.join(directory, "package.json"))) {
+			const candidate = node_path.default.join(directory, file);
+			return (0, node_fs.existsSync)(candidate) ? candidate : void 0;
+		}
+		const parent = node_path.default.dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
+	}
+}
+/**
+* Text of a file shipped by the calling package, or `''` when it is not there.
+*
+* Empty rather than a placeholder, and never a throw. A context resource's text
+* is pasted into the system prompt, so `'(resource unavailable: README.md)'` is
+* a string the model pays for and may act on; `''` is dropped by the prompt
+* composer instead. A throw is worse still: it propagates out of resource
+* resolution and fails the whole prompt build.
+*/
+async function readPackageResource(moduleUrl, file) {
+	const resolved = packageResourcePath(moduleUrl, file);
+	if (resolved === void 0) return "";
+	try {
+		return await (0, node_fs_promises.readFile)(resolved, "utf8");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+exports.packageResourcePath = packageResourcePath;
+exports.readPackageResource = readPackageResource;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/packageResource/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["path","fileURLToPath","existsSync","readFile"],"sources":["../../../../src/services/packageResource/index.ts"],"sourcesContent":["import { existsSync } from 'node:fs';\nimport { readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/**\n * Absolute path of a file shipped by the calling package.\n *\n * Anchored on the nearest ancestor holding a `package.json`, which is the only\n * sentinel that is correct from `src/` and from `dist/` alike. Counting levels\n * with a fixed `new URL('../../..', import.meta.url)` is not: a bundled entry\n * sits at a different depth than its source, so the walk lands outside the\n * package and every read misses.\n *\n * `moduleUrl` is required on purpose. A default of `import.meta.url` resolves to\n * this package rather than the caller's, which is a silently wrong answer.\n */\nexport function packageResourcePath(moduleUrl: string | URL, file: string): string | undefined {\n  let directory = path.dirname(fileURLToPath(moduleUrl));\n  for (;;) {\n    if (existsSync(path.join(directory, 'package.json'))) {\n      const candidate = path.join(directory, file);\n      return existsSync(candidate) ? candidate : undefined;\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) return undefined;\n    directory = parent;\n  }\n}\n\n/**\n * Text of a file shipped by the calling package, or `''` when it is not there.\n *\n * Empty rather than a placeholder, and never a throw. A context resource's text\n * is pasted into the system prompt, so `'(resource unavailable: README.md)'` is\n * a string the model pays for and may act on; `''` is dropped by the prompt\n * composer instead. A throw is worse still: it propagates out of resource\n * resolution and fails the whole prompt build.\n */\nexport async function readPackageResource(moduleUrl: string | URL, file: string): Promise<string> {\n  const resolved = packageResourcePath(moduleUrl, file);\n  if (resolved === undefined) return '';\n  try {\n    return await readFile(resolved, 'utf8');\n  } catch {\n    return '';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAiBA,SAAgB,oBAAoB,WAAyB,MAAkC;CAC7F,IAAI,YAAYA,UAAAA,QAAK,SAAA,GAAQC,SAAAA,cAAAA,CAAc,SAAS,CAAC;CACrD,SAAS;EACP,KAAA,GAAIC,QAAAA,WAAAA,CAAWF,UAAAA,QAAK,KAAK,WAAW,cAAc,CAAC,GAAG;GACpD,MAAM,YAAYA,UAAAA,QAAK,KAAK,WAAW,IAAI;GAC3C,QAAA,GAAOE,QAAAA,WAAAA,CAAW,SAAS,IAAI,YAAY,KAAA;EAC7C;EACA,MAAM,SAASF,UAAAA,QAAK,QAAQ,SAAS;EACrC,IAAI,WAAW,WAAW,OAAO,KAAA;EACjC,YAAY;CACd;AACF;;;;;;;;;;AAWA,eAAsB,oBAAoB,WAAyB,MAA+B;CAChG,MAAM,WAAW,oBAAoB,WAAW,IAAI;CACpD,IAAI,aAAa,KAAA,GAAW,OAAO;CACnC,IAAI;EACF,OAAO,OAAA,GAAMG,iBAAAA,SAAAA,CAAS,UAAU,MAAM;CACxC,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/src/services/packageResource/index.d.mts

@@ -0,0 +1,26 @@
+//#region src/services/packageResource/index.d.ts
+/**
+ * Absolute path of a file shipped by the calling package.
+ *
+ * Anchored on the nearest ancestor holding a `package.json`, which is the only
+ * sentinel that is correct from `src/` and from `dist/` alike. Counting levels
+ * with a fixed `new URL('../../..', import.meta.url)` is not: a bundled entry
+ * sits at a different depth than its source, so the walk lands outside the
+ * package and every read misses.
+ *
+ * `moduleUrl` is required on purpose. A default of `import.meta.url` resolves to
+ * this package rather than the caller's, which is a silently wrong answer.
+ */
+export declare function packageResourcePath(moduleUrl: string | URL, file: string): string | undefined;
+/**
+ * Text of a file shipped by the calling package, or `''` when it is not there.
+ *
+ * Empty rather than a placeholder, and never a throw. A context resource's text
+ * is pasted into the system prompt, so `'(resource unavailable: README.md)'` is
+ * a string the model pays for and may act on; `''` is dropped by the prompt
+ * composer instead. A throw is worse still: it propagates out of resource
+ * resolution and fails the whole prompt build.
+ */
+export declare function readPackageResource(moduleUrl: string | URL, file: string): Promise<string>;
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/src/services/packageResource/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/packageResource/index.ts"],"mappings":";;;;;;;;;;;;;wBAiBgB,oBAAoB,oBAAoB,KAAK;;;;;;;;;;wBAsBvC,oBAAoB,oBAAoB,KAAK,eAAe"}

package/dist/src/services/packageResource/index.mjs

@@ -0,0 +1,51 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/services/packageResource/index.ts
+/**
+* Absolute path of a file shipped by the calling package.
+*
+* Anchored on the nearest ancestor holding a `package.json`, which is the only
+* sentinel that is correct from `src/` and from `dist/` alike. Counting levels
+* with a fixed `new URL('../../..', import.meta.url)` is not: a bundled entry
+* sits at a different depth than its source, so the walk lands outside the
+* package and every read misses.
+*
+* `moduleUrl` is required on purpose. A default of `import.meta.url` resolves to
+* this package rather than the caller's, which is a silently wrong answer.
+*/
+function packageResourcePath(moduleUrl, file) {
+	let directory = path.dirname(fileURLToPath(moduleUrl));
+	for (;;) {
+		if (existsSync(path.join(directory, "package.json"))) {
+			const candidate = path.join(directory, file);
+			return existsSync(candidate) ? candidate : void 0;
+		}
+		const parent = path.dirname(directory);
+		if (parent === directory) return void 0;
+		directory = parent;
+	}
+}
+/**
+* Text of a file shipped by the calling package, or `''` when it is not there.
+*
+* Empty rather than a placeholder, and never a throw. A context resource's text
+* is pasted into the system prompt, so `'(resource unavailable: README.md)'` is
+* a string the model pays for and may act on; `''` is dropped by the prompt
+* composer instead. A throw is worse still: it propagates out of resource
+* resolution and fails the whole prompt build.
+*/
+async function readPackageResource(moduleUrl, file) {
+	const resolved = packageResourcePath(moduleUrl, file);
+	if (resolved === void 0) return "";
+	try {
+		return await readFile(resolved, "utf8");
+	} catch {
+		return "";
+	}
+}
+//#endregion
+export { packageResourcePath, readPackageResource };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/packageResource/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/packageResource/index.ts"],"sourcesContent":["import { existsSync } from 'node:fs';\nimport { readFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/**\n * Absolute path of a file shipped by the calling package.\n *\n * Anchored on the nearest ancestor holding a `package.json`, which is the only\n * sentinel that is correct from `src/` and from `dist/` alike. Counting levels\n * with a fixed `new URL('../../..', import.meta.url)` is not: a bundled entry\n * sits at a different depth than its source, so the walk lands outside the\n * package and every read misses.\n *\n * `moduleUrl` is required on purpose. A default of `import.meta.url` resolves to\n * this package rather than the caller's, which is a silently wrong answer.\n */\nexport function packageResourcePath(moduleUrl: string | URL, file: string): string | undefined {\n  let directory = path.dirname(fileURLToPath(moduleUrl));\n  for (;;) {\n    if (existsSync(path.join(directory, 'package.json'))) {\n      const candidate = path.join(directory, file);\n      return existsSync(candidate) ? candidate : undefined;\n    }\n    const parent = path.dirname(directory);\n    if (parent === directory) return undefined;\n    directory = parent;\n  }\n}\n\n/**\n * Text of a file shipped by the calling package, or `''` when it is not there.\n *\n * Empty rather than a placeholder, and never a throw. A context resource's text\n * is pasted into the system prompt, so `'(resource unavailable: README.md)'` is\n * a string the model pays for and may act on; `''` is dropped by the prompt\n * composer instead. A throw is worse still: it propagates out of resource\n * resolution and fails the whole prompt build.\n */\nexport async function readPackageResource(moduleUrl: string | URL, file: string): Promise<string> {\n  const resolved = packageResourcePath(moduleUrl, file);\n  if (resolved === undefined) return '';\n  try {\n    return await readFile(resolved, 'utf8');\n  } catch {\n    return '';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,SAAgB,oBAAoB,WAAyB,MAAkC;CAC7F,IAAI,YAAY,KAAK,QAAQ,cAAc,SAAS,CAAC;CACrD,SAAS;EACP,IAAI,WAAW,KAAK,KAAK,WAAW,cAAc,CAAC,GAAG;GACpD,MAAM,YAAY,KAAK,KAAK,WAAW,IAAI;GAC3C,OAAO,WAAW,SAAS,IAAI,YAAY,KAAA;EAC7C;EACA,MAAM,SAAS,KAAK,QAAQ,SAAS;EACrC,IAAI,WAAW,WAAW,OAAO,KAAA;EACjC,YAAY;CACd;AACF;;;;;;;;;;AAWA,eAAsB,oBAAoB,WAAyB,MAA+B;CAChG,MAAM,WAAW,oBAAoB,WAAW,IAAI;CACpD,IAAI,aAAa,KAAA,GAAW,OAAO;CACnC,IAAI;EACF,OAAO,MAAM,SAAS,UAAU,MAAM;CACxC,QAAQ;EACN,OAAO;CACT;AACF"}