@agimon-ai/po 0.0.0-alpha.0

package/dist/src/cli/router.cjs

@@ -0,0 +1,57 @@
+//#region src/cli/router.ts
+/**
+* Top-level argv routing for the `po` binary.
+*
+* Deliberately tiny and dependency-free. It answers two questions before any
+* command module loads: which subcommand was named, and whether this run only
+* wants help or a version. Everything else, including the harness options and
+* the Pi passthrough, stays with `parseHarnessArgs`, which already knows the
+* harness vocabulary and forwards what it does not own.
+*/
+/** Subcommands that parse their own arguments instead of passing them to Pi. */
+const KNOWN_COMMANDS = [
+	"init",
+	"sync",
+	"api-export",
+	"compat",
+	"doctor"
+];
+const HELP_FLAGS = ["--help", "-h"];
+const VERSION_FLAGS = ["--version", "-v"];
+/** Everything after this belongs to a provider or to Pi, never to po. */
+const PASSTHROUGH_SEPARATOR = "--";
+/**
+* The named subcommand, or undefined when this run is a Pi invocation.
+*
+* Reads argv[0] only. A token later in the line is a flag value or prompt text,
+* never a command, so scanning further would let `po --profile sync` look
+* like a sync.
+*/
+function routeCommand(args) {
+	const first = args[0];
+	return first !== void 0 && KNOWN_COMMANDS.includes(first) ? first : void 0;
+}
+/**
+* Whether this run asks for help or a version, before the passthrough boundary.
+*
+* The scan stops at the first bare `--` so a provider's own `--help` reaches
+* the provider rather than printing po's help and exiting.
+*/
+function informationalRequest(args) {
+	for (const argument of args) {
+		if (argument === PASSTHROUGH_SEPARATOR) return void 0;
+		if (HELP_FLAGS.includes(argument)) return "help";
+		if (VERSION_FLAGS.includes(argument)) return "version";
+	}
+}
+/** Convenience for a subcommand that only needs to know whether to print help. */
+function wantsHelp(args) {
+	return informationalRequest(args) === "help";
+}
+//#endregion
+exports.KNOWN_COMMANDS = KNOWN_COMMANDS;
+exports.informationalRequest = informationalRequest;
+exports.routeCommand = routeCommand;
+exports.wantsHelp = wantsHelp;
+
+//# sourceMappingURL=router.cjs.map

package/dist/src/cli/router.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.cjs","names":[],"sources":["../../../src/cli/router.ts"],"sourcesContent":["/**\n * Top-level argv routing for the `po` binary.\n *\n * Deliberately tiny and dependency-free. It answers two questions before any\n * command module loads: which subcommand was named, and whether this run only\n * wants help or a version. Everything else, including the harness options and\n * the Pi passthrough, stays with `parseHarnessArgs`, which already knows the\n * harness vocabulary and forwards what it does not own.\n */\n\n/** Subcommands that parse their own arguments instead of passing them to Pi. */\nexport const KNOWN_COMMANDS = ['init', 'sync', 'api-export', 'compat', 'doctor'] as const;\n\nexport type KnownCommand = (typeof KNOWN_COMMANDS)[number];\n\nconst HELP_FLAGS = ['--help', '-h'];\nconst VERSION_FLAGS = ['--version', '-v'];\n/** Everything after this belongs to a provider or to Pi, never to po. */\nconst PASSTHROUGH_SEPARATOR = '--';\n\n/**\n * The named subcommand, or undefined when this run is a Pi invocation.\n *\n * Reads argv[0] only. A token later in the line is a flag value or prompt text,\n * never a command, so scanning further would let `po --profile sync` look\n * like a sync.\n */\nexport function routeCommand(args: readonly string[]): KnownCommand | undefined {\n  const first = args[0];\n  return first !== undefined && (KNOWN_COMMANDS as readonly string[]).includes(first)\n    ? (first as KnownCommand)\n    : undefined;\n}\n\n/**\n * Whether this run asks for help or a version, before the passthrough boundary.\n *\n * The scan stops at the first bare `--` so a provider's own `--help` reaches\n * the provider rather than printing po's help and exiting.\n */\nexport function informationalRequest(args: readonly string[]): 'help' | 'version' | undefined {\n  for (const argument of args) {\n    if (argument === PASSTHROUGH_SEPARATOR) return undefined;\n    if (HELP_FLAGS.includes(argument)) return 'help';\n    if (VERSION_FLAGS.includes(argument)) return 'version';\n  }\n  return undefined;\n}\n\n/** Convenience for a subcommand that only needs to know whether to print help. */\nexport function wantsHelp(args: readonly string[]): boolean {\n  return informationalRequest(args) === 'help';\n}\n"],"mappings":";;;;;;;;;;;AAWA,MAAa,iBAAiB;CAAC;CAAQ;CAAQ;CAAc;CAAU;AAAQ;AAI/E,MAAM,aAAa,CAAC,UAAU,IAAI;AAClC,MAAM,gBAAgB,CAAC,aAAa,IAAI;;AAExC,MAAM,wBAAwB;;;;;;;;AAS9B,SAAgB,aAAa,MAAmD;CAC9E,MAAM,QAAQ,KAAK;CACnB,OAAO,UAAU,KAAA,KAAc,eAAqC,SAAS,KAAK,IAC7E,QACD,KAAA;AACN;;;;;;;AAQA,SAAgB,qBAAqB,MAAyD;CAC5F,KAAK,MAAM,YAAY,MAAM;EAC3B,IAAI,aAAa,uBAAuB,OAAO,KAAA;EAC/C,IAAI,WAAW,SAAS,QAAQ,GAAG,OAAO;EAC1C,IAAI,cAAc,SAAS,QAAQ,GAAG,OAAO;CAC/C;AAEF;;AAGA,SAAgB,UAAU,MAAkC;CAC1D,OAAO,qBAAqB,IAAI,MAAM;AACxC"}

package/dist/src/cli/router.d.mts

@@ -0,0 +1,32 @@
+//#region src/cli/router.d.ts
+/**
+ * Top-level argv routing for the `po` binary.
+ *
+ * Deliberately tiny and dependency-free. It answers two questions before any
+ * command module loads: which subcommand was named, and whether this run only
+ * wants help or a version. Everything else, including the harness options and
+ * the Pi passthrough, stays with `parseHarnessArgs`, which already knows the
+ * harness vocabulary and forwards what it does not own.
+ */
+/** Subcommands that parse their own arguments instead of passing them to Pi. */
+export declare const KNOWN_COMMANDS: readonly ['init', 'sync', 'api-export', 'compat', 'doctor'];
+export type KnownCommand = (typeof KNOWN_COMMANDS)[number];
+/**
+ * The named subcommand, or undefined when this run is a Pi invocation.
+ *
+ * Reads argv[0] only. A token later in the line is a flag value or prompt text,
+ * never a command, so scanning further would let `po --profile sync` look
+ * like a sync.
+ */
+export declare function routeCommand(args: readonly string[]): KnownCommand | undefined;
+/**
+ * Whether this run asks for help or a version, before the passthrough boundary.
+ *
+ * The scan stops at the first bare `--` so a provider's own `--help` reaches
+ * the provider rather than printing po's help and exiting.
+ */
+export declare function informationalRequest(args: readonly string[]): 'help' | 'version' | undefined;
+/** Convenience for a subcommand that only needs to know whether to print help. */
+export declare function wantsHelp(args: readonly string[]): boolean;
+//#endregion
+//# sourceMappingURL=router.d.mts.map

package/dist/src/cli/router.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../../src/cli/router.ts"],"mappings":";;;;;;;;;;;qBAWa;YAED,uBAAuB;;;;;;;;wBAcnB,aAAa,0BAA0B;;;;;;;wBAavC,qBAAqB;;wBAUrB,UAAU"}

package/dist/src/cli/router.mjs

@@ -0,0 +1,54 @@
+//#region src/cli/router.ts
+/**
+* Top-level argv routing for the `po` binary.
+*
+* Deliberately tiny and dependency-free. It answers two questions before any
+* command module loads: which subcommand was named, and whether this run only
+* wants help or a version. Everything else, including the harness options and
+* the Pi passthrough, stays with `parseHarnessArgs`, which already knows the
+* harness vocabulary and forwards what it does not own.
+*/
+/** Subcommands that parse their own arguments instead of passing them to Pi. */
+const KNOWN_COMMANDS = [
+	"init",
+	"sync",
+	"api-export",
+	"compat",
+	"doctor"
+];
+const HELP_FLAGS = ["--help", "-h"];
+const VERSION_FLAGS = ["--version", "-v"];
+/** Everything after this belongs to a provider or to Pi, never to po. */
+const PASSTHROUGH_SEPARATOR = "--";
+/**
+* The named subcommand, or undefined when this run is a Pi invocation.
+*
+* Reads argv[0] only. A token later in the line is a flag value or prompt text,
+* never a command, so scanning further would let `po --profile sync` look
+* like a sync.
+*/
+function routeCommand(args) {
+	const first = args[0];
+	return first !== void 0 && KNOWN_COMMANDS.includes(first) ? first : void 0;
+}
+/**
+* Whether this run asks for help or a version, before the passthrough boundary.
+*
+* The scan stops at the first bare `--` so a provider's own `--help` reaches
+* the provider rather than printing po's help and exiting.
+*/
+function informationalRequest(args) {
+	for (const argument of args) {
+		if (argument === PASSTHROUGH_SEPARATOR) return void 0;
+		if (HELP_FLAGS.includes(argument)) return "help";
+		if (VERSION_FLAGS.includes(argument)) return "version";
+	}
+}
+/** Convenience for a subcommand that only needs to know whether to print help. */
+function wantsHelp(args) {
+	return informationalRequest(args) === "help";
+}
+//#endregion
+export { KNOWN_COMMANDS, informationalRequest, routeCommand, wantsHelp };
+
+//# sourceMappingURL=router.mjs.map

package/dist/src/cli/router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.mjs","names":[],"sources":["../../../src/cli/router.ts"],"sourcesContent":["/**\n * Top-level argv routing for the `po` binary.\n *\n * Deliberately tiny and dependency-free. It answers two questions before any\n * command module loads: which subcommand was named, and whether this run only\n * wants help or a version. Everything else, including the harness options and\n * the Pi passthrough, stays with `parseHarnessArgs`, which already knows the\n * harness vocabulary and forwards what it does not own.\n */\n\n/** Subcommands that parse their own arguments instead of passing them to Pi. */\nexport const KNOWN_COMMANDS = ['init', 'sync', 'api-export', 'compat', 'doctor'] as const;\n\nexport type KnownCommand = (typeof KNOWN_COMMANDS)[number];\n\nconst HELP_FLAGS = ['--help', '-h'];\nconst VERSION_FLAGS = ['--version', '-v'];\n/** Everything after this belongs to a provider or to Pi, never to po. */\nconst PASSTHROUGH_SEPARATOR = '--';\n\n/**\n * The named subcommand, or undefined when this run is a Pi invocation.\n *\n * Reads argv[0] only. A token later in the line is a flag value or prompt text,\n * never a command, so scanning further would let `po --profile sync` look\n * like a sync.\n */\nexport function routeCommand(args: readonly string[]): KnownCommand | undefined {\n  const first = args[0];\n  return first !== undefined && (KNOWN_COMMANDS as readonly string[]).includes(first)\n    ? (first as KnownCommand)\n    : undefined;\n}\n\n/**\n * Whether this run asks for help or a version, before the passthrough boundary.\n *\n * The scan stops at the first bare `--` so a provider's own `--help` reaches\n * the provider rather than printing po's help and exiting.\n */\nexport function informationalRequest(args: readonly string[]): 'help' | 'version' | undefined {\n  for (const argument of args) {\n    if (argument === PASSTHROUGH_SEPARATOR) return undefined;\n    if (HELP_FLAGS.includes(argument)) return 'help';\n    if (VERSION_FLAGS.includes(argument)) return 'version';\n  }\n  return undefined;\n}\n\n/** Convenience for a subcommand that only needs to know whether to print help. */\nexport function wantsHelp(args: readonly string[]): boolean {\n  return informationalRequest(args) === 'help';\n}\n"],"mappings":";;;;;;;;;;;AAWA,MAAa,iBAAiB;CAAC;CAAQ;CAAQ;CAAc;CAAU;AAAQ;AAI/E,MAAM,aAAa,CAAC,UAAU,IAAI;AAClC,MAAM,gBAAgB,CAAC,aAAa,IAAI;;AAExC,MAAM,wBAAwB;;;;;;;;AAS9B,SAAgB,aAAa,MAAmD;CAC9E,MAAM,QAAQ,KAAK;CACnB,OAAO,UAAU,KAAA,KAAc,eAAqC,SAAS,KAAK,IAC7E,QACD,KAAA;AACN;;;;;;;AAQA,SAAgB,qBAAqB,MAAyD;CAC5F,KAAK,MAAM,YAAY,MAAM;EAC3B,IAAI,aAAa,uBAAuB,OAAO,KAAA;EAC/C,IAAI,WAAW,SAAS,QAAQ,GAAG,OAAO;EAC1C,IAAI,cAAc,SAAS,QAAQ,GAAG,OAAO;CAC/C;AAEF;;AAGA,SAAgB,UAAU,MAAkC;CAC1D,OAAO,qBAAqB,IAAI,MAAM;AACxC"}

package/dist/src/cli/server/options.cjs

@@ -0,0 +1,71 @@
+require("../../builders/server/sessionArguments.cjs");
+//#region src/cli/server/options.ts
+const TOKEN_FILE_OPTION = "--auth-token-file";
+const WEB_OPTION = "--web";
+const NAME_OPTION = "--name";
+const SESSION_ID_OPTION = "--session-id";
+const AGENT_SEPARATOR = "--";
+const DEFAULT_WEB_PORT = 7533;
+const DEFAULT_SESSION_NAME = "untitled";
+const SERVE_USAGE = `po-server ${TOKEN_FILE_OPTION} <file> [--no-session] [${NAME_OPTION} <name>] [${SESSION_ID_OPTION} <id>] [${WEB_OPTION} [port]] [${AGENT_SEPARATOR} <agent arguments>]`;
+/**
+* Parses the server's own arguments, leaving the agent's untouched.
+*
+* The token is read from a file rather than a flag because command arguments are visible to other local processes.
+*/
+function parseServeOptions(argv) {
+	let noSession = false;
+	let tokenFile;
+	let webPort = DEFAULT_WEB_PORT;
+	let sessionName;
+	let sessionId;
+	const agentArgs = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--no-session") {
+			noSession = true;
+			continue;
+		}
+		if (argument === AGENT_SEPARATOR) {
+			agentArgs.push(...argv.slice(index + 1));
+			break;
+		}
+		if (argument === WEB_OPTION) {
+			const value = argv[index + 1];
+			if (value !== void 0 && /^\d+$/u.test(value)) {
+				const parsed = Number.parseInt(value, 10);
+				if (parsed < 1 || parsed > 65535) throw new Error(`${WEB_OPTION} expects a port number, received "${value}".`);
+				webPort = parsed;
+				index += 1;
+			} else webPort = DEFAULT_WEB_PORT;
+			continue;
+		}
+		if (argument === TOKEN_FILE_OPTION || argument === NAME_OPTION || argument === SESSION_ID_OPTION) {
+			const value = argv[index + 1];
+			if (value === void 0 || value.startsWith("-")) throw new Error(`${argument} requires a value.`);
+			if (argument === TOKEN_FILE_OPTION) tokenFile = value;
+			else if (argument === NAME_OPTION) sessionName = value;
+			else {
+				if (value.includes("/")) throw new Error(`${SESSION_ID_OPTION} must not contain "/".`);
+				sessionId = value;
+			}
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown option ${argument}. Usage: ${SERVE_USAGE}`);
+	}
+	if (!tokenFile) throw new Error(`${TOKEN_FILE_OPTION} is required. Usage: ${SERVE_USAGE}`);
+	return {
+		...noSession ? { noSession: true } : {},
+		tokenFile,
+		agentArgs,
+		webPort,
+		sessionName: sessionName ?? DEFAULT_SESSION_NAME,
+		sessionId
+	};
+}
+//#endregion
+exports.SERVE_USAGE = SERVE_USAGE;
+exports.parseServeOptions = parseServeOptions;
+
+//# sourceMappingURL=options.cjs.map

package/dist/src/cli/server/options.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.cjs","names":[],"sources":["../../../../src/cli/server/options.ts"],"sourcesContent":["import type { ServeOptions } from '../../builders/server/types';\nexport type { ServeOptions } from '../../builders/server/types';\nexport {\n  resolveSessionIdentity,\n  relaunchAgentArgs,\n  type SessionIdentity,\n} from '../../builders/server/sessionArguments';\nconst TOKEN_FILE_OPTION = '--auth-token-file';\nconst WEB_OPTION = '--web';\nconst NAME_OPTION = '--name';\nconst SESSION_ID_OPTION = '--session-id';\nconst AGENT_SEPARATOR = '--';\nconst DEFAULT_WEB_PORT = 7533;\nconst DEFAULT_SESSION_NAME = 'untitled';\n\nexport const SERVE_USAGE = `po-server ${TOKEN_FILE_OPTION} <file> [--no-session] [${NAME_OPTION} <name>] [${SESSION_ID_OPTION} <id>] [${WEB_OPTION} [port]] [${AGENT_SEPARATOR} <agent arguments>]`;\n\n/**\n * Parses the server's own arguments, leaving the agent's untouched.\n *\n * The token is read from a file rather than a flag because command arguments are visible to other local processes.\n */\nexport function parseServeOptions(argv: readonly string[]): ServeOptions {\n  let noSession = false;\n  let tokenFile: string | undefined;\n  let webPort = DEFAULT_WEB_PORT;\n  let sessionName: string | undefined;\n  let sessionId: string | undefined;\n  const agentArgs: string[] = [];\n\n  for (let index = 0; index < argv.length; index += 1) {\n    const argument = argv[index];\n    if (argument === '--no-session') {\n      noSession = true;\n      continue;\n    }\n    if (argument === AGENT_SEPARATOR) {\n      agentArgs.push(...argv.slice(index + 1));\n      break;\n    }\n    if (argument === WEB_OPTION) {\n      // The port is optional, so only consume the next token when it reads as\n      // one; otherwise it belongs to whatever flag follows.\n      const value = argv[index + 1];\n      if (value !== undefined && /^\\d+$/u.test(value)) {\n        const parsed = Number.parseInt(value, 10);\n        if (parsed < 1 || parsed > 65535) throw new Error(`${WEB_OPTION} expects a port number, received \"${value}\".`);\n        webPort = parsed;\n        index += 1;\n      } else {\n        webPort = DEFAULT_WEB_PORT;\n      }\n      continue;\n    }\n    if (argument === TOKEN_FILE_OPTION || argument === NAME_OPTION || argument === SESSION_ID_OPTION) {\n      const value = argv[index + 1];\n      if (value === undefined || value.startsWith('-')) throw new Error(`${argument} requires a value.`);\n      if (argument === TOKEN_FILE_OPTION) tokenFile = value;\n      else if (argument === NAME_OPTION) sessionName = value;\n      else {\n        if (value.includes('/')) throw new Error(`${SESSION_ID_OPTION} must not contain \"/\".`);\n        sessionId = value;\n      }\n      index += 1;\n      continue;\n    }\n    throw new Error(`Unknown option ${argument}. Usage: ${SERVE_USAGE}`);\n  }\n\n  if (!tokenFile) throw new Error(`${TOKEN_FILE_OPTION} is required. Usage: ${SERVE_USAGE}`);\n  return {\n    ...(noSession ? { noSession: true } : {}),\n    tokenFile,\n    agentArgs,\n    webPort,\n    sessionName: sessionName ?? DEFAULT_SESSION_NAME,\n    sessionId,\n  };\n}\n"],"mappings":";;AAOA,MAAM,oBAAoB;AAC1B,MAAM,aAAa;AACnB,MAAM,cAAc;AACpB,MAAM,oBAAoB;AAC1B,MAAM,kBAAkB;AACxB,MAAM,mBAAmB;AACzB,MAAM,uBAAuB;AAE7B,MAAa,cAAc,aAAa,kBAAkB,0BAA0B,YAAY,YAAY,kBAAkB,UAAU,WAAW,YAAY,gBAAgB;;;;;;AAO/K,SAAgB,kBAAkB,MAAuC;CACvE,IAAI,YAAY;CAChB,IAAI;CACJ,IAAI,UAAU;CACd,IAAI;CACJ,IAAI;CACJ,MAAM,YAAsB,CAAC;CAE7B,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;EACnD,MAAM,WAAW,KAAK;EACtB,IAAI,aAAa,gBAAgB;GAC/B,YAAY;GACZ;EACF;EACA,IAAI,aAAa,iBAAiB;GAChC,UAAU,KAAK,GAAG,KAAK,MAAM,QAAQ,CAAC,CAAC;GACvC;EACF;EACA,IAAI,aAAa,YAAY;GAG3B,MAAM,QAAQ,KAAK,QAAQ;GAC3B,IAAI,UAAU,KAAA,KAAa,SAAS,KAAK,KAAK,GAAG;IAC/C,MAAM,SAAS,OAAO,SAAS,OAAO,EAAE;IACxC,IAAI,SAAS,KAAK,SAAS,OAAO,MAAM,IAAI,MAAM,GAAG,WAAW,oCAAoC,MAAM,GAAG;IAC7G,UAAU;IACV,SAAS;GACX,OACE,UAAU;GAEZ;EACF;EACA,IAAI,aAAa,qBAAqB,aAAa,eAAe,aAAa,mBAAmB;GAChG,MAAM,QAAQ,KAAK,QAAQ;GAC3B,IAAI,UAAU,KAAA,KAAa,MAAM,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,GAAG,SAAS,mBAAmB;GACjG,IAAI,aAAa,mBAAmB,YAAY;QAC3C,IAAI,aAAa,aAAa,cAAc;QAC5C;IACH,IAAI,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,MAAM,GAAG,kBAAkB,uBAAuB;IACrF,YAAY;GACd;GACA,SAAS;GACT;EACF;EACA,MAAM,IAAI,MAAM,kBAAkB,SAAS,WAAW,aAAa;CACrE;CAEA,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,GAAG,kBAAkB,uBAAuB,aAAa;CACzF,OAAO;EACL,GAAI,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;EACvC;EACA;EACA;EACA,aAAa,eAAe;EAC5B;CACF;AACF"}

package/dist/src/cli/server/options.mjs

@@ -0,0 +1,70 @@
+import "../../builders/server/sessionArguments.mjs";
+//#region src/cli/server/options.ts
+const TOKEN_FILE_OPTION = "--auth-token-file";
+const WEB_OPTION = "--web";
+const NAME_OPTION = "--name";
+const SESSION_ID_OPTION = "--session-id";
+const AGENT_SEPARATOR = "--";
+const DEFAULT_WEB_PORT = 7533;
+const DEFAULT_SESSION_NAME = "untitled";
+const SERVE_USAGE = `po-server ${TOKEN_FILE_OPTION} <file> [--no-session] [${NAME_OPTION} <name>] [${SESSION_ID_OPTION} <id>] [${WEB_OPTION} [port]] [${AGENT_SEPARATOR} <agent arguments>]`;
+/**
+* Parses the server's own arguments, leaving the agent's untouched.
+*
+* The token is read from a file rather than a flag because command arguments are visible to other local processes.
+*/
+function parseServeOptions(argv) {
+	let noSession = false;
+	let tokenFile;
+	let webPort = DEFAULT_WEB_PORT;
+	let sessionName;
+	let sessionId;
+	const agentArgs = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (argument === "--no-session") {
+			noSession = true;
+			continue;
+		}
+		if (argument === AGENT_SEPARATOR) {
+			agentArgs.push(...argv.slice(index + 1));
+			break;
+		}
+		if (argument === WEB_OPTION) {
+			const value = argv[index + 1];
+			if (value !== void 0 && /^\d+$/u.test(value)) {
+				const parsed = Number.parseInt(value, 10);
+				if (parsed < 1 || parsed > 65535) throw new Error(`${WEB_OPTION} expects a port number, received "${value}".`);
+				webPort = parsed;
+				index += 1;
+			} else webPort = DEFAULT_WEB_PORT;
+			continue;
+		}
+		if (argument === TOKEN_FILE_OPTION || argument === NAME_OPTION || argument === SESSION_ID_OPTION) {
+			const value = argv[index + 1];
+			if (value === void 0 || value.startsWith("-")) throw new Error(`${argument} requires a value.`);
+			if (argument === TOKEN_FILE_OPTION) tokenFile = value;
+			else if (argument === NAME_OPTION) sessionName = value;
+			else {
+				if (value.includes("/")) throw new Error(`${SESSION_ID_OPTION} must not contain "/".`);
+				sessionId = value;
+			}
+			index += 1;
+			continue;
+		}
+		throw new Error(`Unknown option ${argument}. Usage: ${SERVE_USAGE}`);
+	}
+	if (!tokenFile) throw new Error(`${TOKEN_FILE_OPTION} is required. Usage: ${SERVE_USAGE}`);
+	return {
+		...noSession ? { noSession: true } : {},
+		tokenFile,
+		agentArgs,
+		webPort,
+		sessionName: sessionName ?? DEFAULT_SESSION_NAME,
+		sessionId
+	};
+}
+//#endregion
+export { SERVE_USAGE, parseServeOptions };
+
+//# sourceMappingURL=options.mjs.map

package/dist/src/cli/server/options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.mjs","names":[],"sources":["../../../../src/cli/server/options.ts"],"sourcesContent":["import type { ServeOptions } from '../../builders/server/types';\nexport type { ServeOptions } from '../../builders/server/types';\nexport {\n  resolveSessionIdentity,\n  relaunchAgentArgs,\n  type SessionIdentity,\n} from '../../builders/server/sessionArguments';\nconst TOKEN_FILE_OPTION = '--auth-token-file';\nconst WEB_OPTION = '--web';\nconst NAME_OPTION = '--name';\nconst SESSION_ID_OPTION = '--session-id';\nconst AGENT_SEPARATOR = '--';\nconst DEFAULT_WEB_PORT = 7533;\nconst DEFAULT_SESSION_NAME = 'untitled';\n\nexport const SERVE_USAGE = `po-server ${TOKEN_FILE_OPTION} <file> [--no-session] [${NAME_OPTION} <name>] [${SESSION_ID_OPTION} <id>] [${WEB_OPTION} [port]] [${AGENT_SEPARATOR} <agent arguments>]`;\n\n/**\n * Parses the server's own arguments, leaving the agent's untouched.\n *\n * The token is read from a file rather than a flag because command arguments are visible to other local processes.\n */\nexport function parseServeOptions(argv: readonly string[]): ServeOptions {\n  let noSession = false;\n  let tokenFile: string | undefined;\n  let webPort = DEFAULT_WEB_PORT;\n  let sessionName: string | undefined;\n  let sessionId: string | undefined;\n  const agentArgs: string[] = [];\n\n  for (let index = 0; index < argv.length; index += 1) {\n    const argument = argv[index];\n    if (argument === '--no-session') {\n      noSession = true;\n      continue;\n    }\n    if (argument === AGENT_SEPARATOR) {\n      agentArgs.push(...argv.slice(index + 1));\n      break;\n    }\n    if (argument === WEB_OPTION) {\n      // The port is optional, so only consume the next token when it reads as\n      // one; otherwise it belongs to whatever flag follows.\n      const value = argv[index + 1];\n      if (value !== undefined && /^\\d+$/u.test(value)) {\n        const parsed = Number.parseInt(value, 10);\n        if (parsed < 1 || parsed > 65535) throw new Error(`${WEB_OPTION} expects a port number, received \"${value}\".`);\n        webPort = parsed;\n        index += 1;\n      } else {\n        webPort = DEFAULT_WEB_PORT;\n      }\n      continue;\n    }\n    if (argument === TOKEN_FILE_OPTION || argument === NAME_OPTION || argument === SESSION_ID_OPTION) {\n      const value = argv[index + 1];\n      if (value === undefined || value.startsWith('-')) throw new Error(`${argument} requires a value.`);\n      if (argument === TOKEN_FILE_OPTION) tokenFile = value;\n      else if (argument === NAME_OPTION) sessionName = value;\n      else {\n        if (value.includes('/')) throw new Error(`${SESSION_ID_OPTION} must not contain \"/\".`);\n        sessionId = value;\n      }\n      index += 1;\n      continue;\n    }\n    throw new Error(`Unknown option ${argument}. Usage: ${SERVE_USAGE}`);\n  }\n\n  if (!tokenFile) throw new Error(`${TOKEN_FILE_OPTION} is required. Usage: ${SERVE_USAGE}`);\n  return {\n    ...(noSession ? { noSession: true } : {}),\n    tokenFile,\n    agentArgs,\n    webPort,\n    sessionName: sessionName ?? DEFAULT_SESSION_NAME,\n    sessionId,\n  };\n}\n"],"mappings":";;AAOA,MAAM,oBAAoB;AAC1B,MAAM,aAAa;AACnB,MAAM,cAAc;AACpB,MAAM,oBAAoB;AAC1B,MAAM,kBAAkB;AACxB,MAAM,mBAAmB;AACzB,MAAM,uBAAuB;AAE7B,MAAa,cAAc,aAAa,kBAAkB,0BAA0B,YAAY,YAAY,kBAAkB,UAAU,WAAW,YAAY,gBAAgB;;;;;;AAO/K,SAAgB,kBAAkB,MAAuC;CACvE,IAAI,YAAY;CAChB,IAAI;CACJ,IAAI,UAAU;CACd,IAAI;CACJ,IAAI;CACJ,MAAM,YAAsB,CAAC;CAE7B,KAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;EACnD,MAAM,WAAW,KAAK;EACtB,IAAI,aAAa,gBAAgB;GAC/B,YAAY;GACZ;EACF;EACA,IAAI,aAAa,iBAAiB;GAChC,UAAU,KAAK,GAAG,KAAK,MAAM,QAAQ,CAAC,CAAC;GACvC;EACF;EACA,IAAI,aAAa,YAAY;GAG3B,MAAM,QAAQ,KAAK,QAAQ;GAC3B,IAAI,UAAU,KAAA,KAAa,SAAS,KAAK,KAAK,GAAG;IAC/C,MAAM,SAAS,OAAO,SAAS,OAAO,EAAE;IACxC,IAAI,SAAS,KAAK,SAAS,OAAO,MAAM,IAAI,MAAM,GAAG,WAAW,oCAAoC,MAAM,GAAG;IAC7G,UAAU;IACV,SAAS;GACX,OACE,UAAU;GAEZ;EACF;EACA,IAAI,aAAa,qBAAqB,aAAa,eAAe,aAAa,mBAAmB;GAChG,MAAM,QAAQ,KAAK,QAAQ;GAC3B,IAAI,UAAU,KAAA,KAAa,MAAM,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,GAAG,SAAS,mBAAmB;GACjG,IAAI,aAAa,mBAAmB,YAAY;QAC3C,IAAI,aAAa,aAAa,cAAc;QAC5C;IACH,IAAI,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,MAAM,GAAG,kBAAkB,uBAAuB;IACrF,YAAY;GACd;GACA,SAAS;GACT;EACF;EACA,MAAM,IAAI,MAAM,kBAAkB,SAAS,WAAW,aAAa;CACrE;CAEA,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,GAAG,kBAAkB,uBAAuB,aAAa;CACzF,OAAO;EACL,GAAI,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;EACvC;EACA;EACA;EACA,aAAa,eAAe;EAC5B;CACF;AACF"}

package/dist/src/cli/server/processGuards.cjs

@@ -0,0 +1,83 @@
+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);
+let node_url = require("node:url");
+/** Longest graceful stop (telemetry flush included) before an uncaught exception exits anyway. */
+const FATAL_STOP_DEADLINE_MS = 5e3;
+const SNAPSHOT_ROOT = /(\S*?)[\\/]node_modules[\\/]\.po-snapshots[\\/]([^\\/\s:)]+)[\\/]/;
+const UPM_STORE = /[\\/]node_modules[\\/]\.upm[\\/]/;
+const PACKAGE_PATH = /[\\/]node_modules[\\/]((?:@[^\\/\s]+[\\/])?[^\\/\s:)]+)[\\/]/g;
+function packageNameAt(directory) {
+	try {
+		const manifest = JSON.parse(node_fs.default.readFileSync(node_path.default.join(directory, "package.json"), "utf8"));
+		return typeof manifest.name === "string" ? manifest.name : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Best-effort owner of an error: the Po package whose snapshot or upm store path appears
+* first in its stack. Snapshots carry their `package.json`, so their name is exact; a upm
+* path uses its innermost `node_modules/<name>` segment. Ordinary dependency frames are
+* ignored, so a library on the stack is never blamed for its caller.
+*/
+function attributePackage(error) {
+	const stack = error instanceof Error ? error.stack : void 0;
+	if (!stack) return void 0;
+	for (const line of stack.split("\n")) {
+		const snapshot = SNAPSHOT_ROOT.exec(line);
+		if (snapshot) {
+			const location = snapshot[1].replace(/^\(/, "");
+			const root = location.startsWith("file:") ? (0, node_url.fileURLToPath)(`${location}/`) : location;
+			const name = packageNameAt(node_path.default.join(root, "node_modules", ".po-snapshots", snapshot[2]));
+			if (name) return name;
+		}
+		if (!UPM_STORE.test(line)) continue;
+		const name = [...line.matchAll(PACKAGE_PATH)].map((match) => match[1]).at(-1);
+		if (name && !name.startsWith(".")) return name.replace(/\\/g, "/");
+	}
+}
+function describe(error) {
+	return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+/**
+* Keeps one bad extension from taking the server down.
+*
+* An unhandled rejection is logged with its package and the server keeps running: a
+* rejected promise has already unwound and leaves no broken state behind. An uncaught
+* exception may have interrupted any synchronous invariant, so the server stops
+* gracefully (bounded) and exits with `UNCAUGHT_EXIT_CODE`.
+*/
+function installProcessGuards(options, target = process) {
+	let fatal = false;
+	const onRejection = (reason) => {
+		const owner = attributePackage(reason);
+		options.write(`[po-server] unhandled rejection${owner ? ` from ${owner}` : ""}: ${describe(reason)}\n`);
+	};
+	const onException = (error) => {
+		const owner = attributePackage(error);
+		options.write(`[po-server] uncaught exception${owner ? ` from ${owner}` : ""}: ${describe(error)}\n`);
+		if (fatal) return;
+		fatal = true;
+		const deadline = setTimeout(() => options.exit(75), options.stopDeadlineMs ?? FATAL_STOP_DEADLINE_MS);
+		options.stop().catch((stopError) => {
+			options.write(`[po-server] stop after uncaught exception failed: ${describe(stopError)}\n`);
+		}).finally(() => {
+			clearTimeout(deadline);
+			options.exit(75);
+		});
+	};
+	target.on("unhandledRejection", onRejection);
+	target.on("uncaughtException", onException);
+	return () => {
+		target.off("unhandledRejection", onRejection);
+		target.off("uncaughtException", onException);
+	};
+}
+//#endregion
+exports.attributePackage = attributePackage;
+exports.installProcessGuards = installProcessGuards;
+
+//# sourceMappingURL=processGuards.cjs.map

package/dist/src/cli/server/processGuards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processGuards.cjs","names":["fs","path","fileURLToPath"],"sources":["../../../../src/cli/server/processGuards.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Exit code for an uncaught exception: temporary failure, so a supervisor restarts the server. */\nexport const UNCAUGHT_EXIT_CODE = 75;\n/** Longest graceful stop (telemetry flush included) before an uncaught exception exits anyway. */\nconst FATAL_STOP_DEADLINE_MS = 5_000;\n\nconst SNAPSHOT_ROOT = /(\\S*?)[\\\\/]node_modules[\\\\/]\\.po-snapshots[\\\\/]([^\\\\/\\s:)]+)[\\\\/]/;\nconst UPM_STORE = /[\\\\/]node_modules[\\\\/]\\.upm[\\\\/]/;\nconst PACKAGE_PATH = /[\\\\/]node_modules[\\\\/]((?:@[^\\\\/\\s]+[\\\\/])?[^\\\\/\\s:)]+)[\\\\/]/g;\n\nfunction packageNameAt(directory: string): string | undefined {\n  try {\n    const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8')) as { name?: unknown };\n    return typeof manifest.name === 'string' ? manifest.name : undefined;\n  } catch {\n    // Best effort: an unreadable manifest only loses the attribution.\n    return undefined;\n  }\n}\n\n/**\n * Best-effort owner of an error: the Po package whose snapshot or upm store path appears\n * first in its stack. Snapshots carry their `package.json`, so their name is exact; a upm\n * path uses its innermost `node_modules/<name>` segment. Ordinary dependency frames are\n * ignored, so a library on the stack is never blamed for its caller.\n */\nexport function attributePackage(error: unknown): string | undefined {\n  const stack = error instanceof Error ? error.stack : undefined;\n  if (!stack) return undefined;\n  for (const line of stack.split('\\n')) {\n    const snapshot = SNAPSHOT_ROOT.exec(line);\n    if (snapshot) {\n      const location = snapshot[1]!.replace(/^\\(/, '');\n      const root = location.startsWith('file:') ? fileURLToPath(`${location}/`) : location;\n      const name = packageNameAt(path.join(root, 'node_modules', '.po-snapshots', snapshot[2]!));\n      if (name) return name;\n    }\n    if (!UPM_STORE.test(line)) continue;\n    const names = [...line.matchAll(PACKAGE_PATH)].map((match) => match[1]!);\n    const name = names.at(-1);\n    if (name && !name.startsWith('.')) return name.replace(/\\\\/g, '/');\n  }\n  return undefined;\n}\n\nfunction describe(error: unknown): string {\n  return error instanceof Error ? (error.stack ?? error.message) : String(error);\n}\n\nexport interface ProcessGuardOptions {\n  readonly write: (message: string) => void;\n  /** Starts the server's graceful stop, which flushes telemetry and logs. */\n  readonly stop: () => Promise<unknown>;\n  readonly exit: (code: number) => void;\n  readonly stopDeadlineMs?: number;\n}\n\n/**\n * Keeps one bad extension from taking the server down.\n *\n * An unhandled rejection is logged with its package and the server keeps running: a\n * rejected promise has already unwound and leaves no broken state behind. An uncaught\n * exception may have interrupted any synchronous invariant, so the server stops\n * gracefully (bounded) and exits with `UNCAUGHT_EXIT_CODE`.\n */\nexport function installProcessGuards(options: ProcessGuardOptions, target: NodeJS.Process = process): () => void {\n  let fatal = false;\n  const onRejection = (reason: unknown): void => {\n    const owner = attributePackage(reason);\n    options.write(`[po-server] unhandled rejection${owner ? ` from ${owner}` : ''}: ${describe(reason)}\\n`);\n  };\n  const onException = (error: unknown): void => {\n    const owner = attributePackage(error);\n    options.write(`[po-server] uncaught exception${owner ? ` from ${owner}` : ''}: ${describe(error)}\\n`);\n    if (fatal) return;\n    fatal = true;\n    const deadline = setTimeout(\n      () => options.exit(UNCAUGHT_EXIT_CODE),\n      options.stopDeadlineMs ?? FATAL_STOP_DEADLINE_MS,\n    );\n    // Not unref'd: if the stop hangs with no other handle alive, the process must still exit 75,\n    // not drain to 0, so the supervisor restarts it.\n    void options\n      .stop()\n      .catch((stopError: unknown) => {\n        options.write(`[po-server] stop after uncaught exception failed: ${describe(stopError)}\\n`);\n      })\n      .finally(() => {\n        clearTimeout(deadline);\n        options.exit(UNCAUGHT_EXIT_CODE);\n      });\n  };\n  target.on('unhandledRejection', onRejection);\n  target.on('uncaughtException', onException);\n  return () => {\n    target.off('unhandledRejection', onRejection);\n    target.off('uncaughtException', onException);\n  };\n}\n"],"mappings":";;;;;;;AAOA,MAAM,yBAAyB;AAE/B,MAAM,gBAAgB;AACtB,MAAM,YAAY;AAClB,MAAM,eAAe;AAErB,SAAS,cAAc,WAAuC;CAC5D,IAAI;EACF,MAAM,WAAW,KAAK,MAAMA,QAAAA,QAAG,aAAaC,UAAAA,QAAK,KAAK,WAAW,cAAc,GAAG,MAAM,CAAC;EACzF,OAAO,OAAO,SAAS,SAAS,WAAW,SAAS,OAAO,KAAA;CAC7D,QAAQ;EAEN;CACF;AACF;;;;;;;AAQA,SAAgB,iBAAiB,OAAoC;CACnE,MAAM,QAAQ,iBAAiB,QAAQ,MAAM,QAAQ,KAAA;CACrD,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,KAAK,MAAM,QAAQ,MAAM,MAAM,IAAI,GAAG;EACpC,MAAM,WAAW,cAAc,KAAK,IAAI;EACxC,IAAI,UAAU;GACZ,MAAM,WAAW,SAAS,EAAE,CAAE,QAAQ,OAAO,EAAE;GAC/C,MAAM,OAAO,SAAS,WAAW,OAAO,KAAA,GAAIC,SAAAA,cAAAA,CAAc,GAAG,SAAS,EAAE,IAAI;GAC5E,MAAM,OAAO,cAAcD,UAAAA,QAAK,KAAK,MAAM,gBAAgB,iBAAiB,SAAS,EAAG,CAAC;GACzF,IAAI,MAAM,OAAO;EACnB;EACA,IAAI,CAAC,UAAU,KAAK,IAAI,GAAG;EAE3B,MAAM,OADQ,CAAC,GAAG,KAAK,SAAS,YAAY,CAAC,CAAC,CAAC,KAAK,UAAU,MAAM,EACnD,CAAC,CAAC,GAAG,EAAE;EACxB,IAAI,QAAQ,CAAC,KAAK,WAAW,GAAG,GAAG,OAAO,KAAK,QAAQ,OAAO,GAAG;CACnE;AAEF;AAEA,SAAS,SAAS,OAAwB;CACxC,OAAO,iBAAiB,QAAS,MAAM,SAAS,MAAM,UAAW,OAAO,KAAK;AAC/E;;;;;;;;;AAkBA,SAAgB,qBAAqB,SAA8B,SAAyB,SAAqB;CAC/G,IAAI,QAAQ;CACZ,MAAM,eAAe,WAA0B;EAC7C,MAAM,QAAQ,iBAAiB,MAAM;EACrC,QAAQ,MAAM,kCAAkC,QAAQ,SAAS,UAAU,GAAG,IAAI,SAAS,MAAM,EAAE,GAAG;CACxG;CACA,MAAM,eAAe,UAAyB;EAC5C,MAAM,QAAQ,iBAAiB,KAAK;EACpC,QAAQ,MAAM,iCAAiC,QAAQ,SAAS,UAAU,GAAG,IAAI,SAAS,KAAK,EAAE,GAAG;EACpG,IAAI,OAAO;EACX,QAAQ;EACR,MAAM,WAAW,iBACT,QAAQ,KAAA,EAAuB,GACrC,QAAQ,kBAAkB,sBAC5B;EAGA,QACG,KAAK,CAAC,CACN,OAAO,cAAuB;GAC7B,QAAQ,MAAM,qDAAqD,SAAS,SAAS,EAAE,GAAG;EAC5F,CAAC,CAAC,CACD,cAAc;GACb,aAAa,QAAQ;GACrB,QAAQ,KAAA,EAAuB;EACjC,CAAC;CACL;CACA,OAAO,GAAG,sBAAsB,WAAW;CAC3C,OAAO,GAAG,qBAAqB,WAAW;CAC1C,aAAa;EACX,OAAO,IAAI,sBAAsB,WAAW;EAC5C,OAAO,IAAI,qBAAqB,WAAW;CAC7C;AACF"}

package/dist/src/cli/server/processGuards.mjs

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Longest graceful stop (telemetry flush included) before an uncaught exception exits anyway. */
+const FATAL_STOP_DEADLINE_MS = 5e3;
+const SNAPSHOT_ROOT = /(\S*?)[\\/]node_modules[\\/]\.po-snapshots[\\/]([^\\/\s:)]+)[\\/]/;
+const UPM_STORE = /[\\/]node_modules[\\/]\.upm[\\/]/;
+const PACKAGE_PATH = /[\\/]node_modules[\\/]((?:@[^\\/\s]+[\\/])?[^\\/\s:)]+)[\\/]/g;
+function packageNameAt(directory) {
+	try {
+		const manifest = JSON.parse(fs.readFileSync(path.join(directory, "package.json"), "utf8"));
+		return typeof manifest.name === "string" ? manifest.name : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Best-effort owner of an error: the Po package whose snapshot or upm store path appears
+* first in its stack. Snapshots carry their `package.json`, so their name is exact; a upm
+* path uses its innermost `node_modules/<name>` segment. Ordinary dependency frames are
+* ignored, so a library on the stack is never blamed for its caller.
+*/
+function attributePackage(error) {
+	const stack = error instanceof Error ? error.stack : void 0;
+	if (!stack) return void 0;
+	for (const line of stack.split("\n")) {
+		const snapshot = SNAPSHOT_ROOT.exec(line);
+		if (snapshot) {
+			const location = snapshot[1].replace(/^\(/, "");
+			const root = location.startsWith("file:") ? fileURLToPath(`${location}/`) : location;
+			const name = packageNameAt(path.join(root, "node_modules", ".po-snapshots", snapshot[2]));
+			if (name) return name;
+		}
+		if (!UPM_STORE.test(line)) continue;
+		const name = [...line.matchAll(PACKAGE_PATH)].map((match) => match[1]).at(-1);
+		if (name && !name.startsWith(".")) return name.replace(/\\/g, "/");
+	}
+}
+function describe(error) {
+	return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+/**
+* Keeps one bad extension from taking the server down.
+*
+* An unhandled rejection is logged with its package and the server keeps running: a
+* rejected promise has already unwound and leaves no broken state behind. An uncaught
+* exception may have interrupted any synchronous invariant, so the server stops
+* gracefully (bounded) and exits with `UNCAUGHT_EXIT_CODE`.
+*/
+function installProcessGuards(options, target = process) {
+	let fatal = false;
+	const onRejection = (reason) => {
+		const owner = attributePackage(reason);
+		options.write(`[po-server] unhandled rejection${owner ? ` from ${owner}` : ""}: ${describe(reason)}\n`);
+	};
+	const onException = (error) => {
+		const owner = attributePackage(error);
+		options.write(`[po-server] uncaught exception${owner ? ` from ${owner}` : ""}: ${describe(error)}\n`);
+		if (fatal) return;
+		fatal = true;
+		const deadline = setTimeout(() => options.exit(75), options.stopDeadlineMs ?? FATAL_STOP_DEADLINE_MS);
+		options.stop().catch((stopError) => {
+			options.write(`[po-server] stop after uncaught exception failed: ${describe(stopError)}\n`);
+		}).finally(() => {
+			clearTimeout(deadline);
+			options.exit(75);
+		});
+	};
+	target.on("unhandledRejection", onRejection);
+	target.on("uncaughtException", onException);
+	return () => {
+		target.off("unhandledRejection", onRejection);
+		target.off("uncaughtException", onException);
+	};
+}
+//#endregion
+export { attributePackage, installProcessGuards };
+
+//# sourceMappingURL=processGuards.mjs.map

package/dist/src/cli/server/processGuards.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processGuards.mjs","names":[],"sources":["../../../../src/cli/server/processGuards.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Exit code for an uncaught exception: temporary failure, so a supervisor restarts the server. */\nexport const UNCAUGHT_EXIT_CODE = 75;\n/** Longest graceful stop (telemetry flush included) before an uncaught exception exits anyway. */\nconst FATAL_STOP_DEADLINE_MS = 5_000;\n\nconst SNAPSHOT_ROOT = /(\\S*?)[\\\\/]node_modules[\\\\/]\\.po-snapshots[\\\\/]([^\\\\/\\s:)]+)[\\\\/]/;\nconst UPM_STORE = /[\\\\/]node_modules[\\\\/]\\.upm[\\\\/]/;\nconst PACKAGE_PATH = /[\\\\/]node_modules[\\\\/]((?:@[^\\\\/\\s]+[\\\\/])?[^\\\\/\\s:)]+)[\\\\/]/g;\n\nfunction packageNameAt(directory: string): string | undefined {\n  try {\n    const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8')) as { name?: unknown };\n    return typeof manifest.name === 'string' ? manifest.name : undefined;\n  } catch {\n    // Best effort: an unreadable manifest only loses the attribution.\n    return undefined;\n  }\n}\n\n/**\n * Best-effort owner of an error: the Po package whose snapshot or upm store path appears\n * first in its stack. Snapshots carry their `package.json`, so their name is exact; a upm\n * path uses its innermost `node_modules/<name>` segment. Ordinary dependency frames are\n * ignored, so a library on the stack is never blamed for its caller.\n */\nexport function attributePackage(error: unknown): string | undefined {\n  const stack = error instanceof Error ? error.stack : undefined;\n  if (!stack) return undefined;\n  for (const line of stack.split('\\n')) {\n    const snapshot = SNAPSHOT_ROOT.exec(line);\n    if (snapshot) {\n      const location = snapshot[1]!.replace(/^\\(/, '');\n      const root = location.startsWith('file:') ? fileURLToPath(`${location}/`) : location;\n      const name = packageNameAt(path.join(root, 'node_modules', '.po-snapshots', snapshot[2]!));\n      if (name) return name;\n    }\n    if (!UPM_STORE.test(line)) continue;\n    const names = [...line.matchAll(PACKAGE_PATH)].map((match) => match[1]!);\n    const name = names.at(-1);\n    if (name && !name.startsWith('.')) return name.replace(/\\\\/g, '/');\n  }\n  return undefined;\n}\n\nfunction describe(error: unknown): string {\n  return error instanceof Error ? (error.stack ?? error.message) : String(error);\n}\n\nexport interface ProcessGuardOptions {\n  readonly write: (message: string) => void;\n  /** Starts the server's graceful stop, which flushes telemetry and logs. */\n  readonly stop: () => Promise<unknown>;\n  readonly exit: (code: number) => void;\n  readonly stopDeadlineMs?: number;\n}\n\n/**\n * Keeps one bad extension from taking the server down.\n *\n * An unhandled rejection is logged with its package and the server keeps running: a\n * rejected promise has already unwound and leaves no broken state behind. An uncaught\n * exception may have interrupted any synchronous invariant, so the server stops\n * gracefully (bounded) and exits with `UNCAUGHT_EXIT_CODE`.\n */\nexport function installProcessGuards(options: ProcessGuardOptions, target: NodeJS.Process = process): () => void {\n  let fatal = false;\n  const onRejection = (reason: unknown): void => {\n    const owner = attributePackage(reason);\n    options.write(`[po-server] unhandled rejection${owner ? ` from ${owner}` : ''}: ${describe(reason)}\\n`);\n  };\n  const onException = (error: unknown): void => {\n    const owner = attributePackage(error);\n    options.write(`[po-server] uncaught exception${owner ? ` from ${owner}` : ''}: ${describe(error)}\\n`);\n    if (fatal) return;\n    fatal = true;\n    const deadline = setTimeout(\n      () => options.exit(UNCAUGHT_EXIT_CODE),\n      options.stopDeadlineMs ?? FATAL_STOP_DEADLINE_MS,\n    );\n    // Not unref'd: if the stop hangs with no other handle alive, the process must still exit 75,\n    // not drain to 0, so the supervisor restarts it.\n    void options\n      .stop()\n      .catch((stopError: unknown) => {\n        options.write(`[po-server] stop after uncaught exception failed: ${describe(stopError)}\\n`);\n      })\n      .finally(() => {\n        clearTimeout(deadline);\n        options.exit(UNCAUGHT_EXIT_CODE);\n      });\n  };\n  target.on('unhandledRejection', onRejection);\n  target.on('uncaughtException', onException);\n  return () => {\n    target.off('unhandledRejection', onRejection);\n    target.off('uncaughtException', onException);\n  };\n}\n"],"mappings":";;;;AAOA,MAAM,yBAAyB;AAE/B,MAAM,gBAAgB;AACtB,MAAM,YAAY;AAClB,MAAM,eAAe;AAErB,SAAS,cAAc,WAAuC;CAC5D,IAAI;EACF,MAAM,WAAW,KAAK,MAAM,GAAG,aAAa,KAAK,KAAK,WAAW,cAAc,GAAG,MAAM,CAAC;EACzF,OAAO,OAAO,SAAS,SAAS,WAAW,SAAS,OAAO,KAAA;CAC7D,QAAQ;EAEN;CACF;AACF;;;;;;;AAQA,SAAgB,iBAAiB,OAAoC;CACnE,MAAM,QAAQ,iBAAiB,QAAQ,MAAM,QAAQ,KAAA;CACrD,IAAI,CAAC,OAAO,OAAO,KAAA;CACnB,KAAK,MAAM,QAAQ,MAAM,MAAM,IAAI,GAAG;EACpC,MAAM,WAAW,cAAc,KAAK,IAAI;EACxC,IAAI,UAAU;GACZ,MAAM,WAAW,SAAS,EAAE,CAAE,QAAQ,OAAO,EAAE;GAC/C,MAAM,OAAO,SAAS,WAAW,OAAO,IAAI,cAAc,GAAG,SAAS,EAAE,IAAI;GAC5E,MAAM,OAAO,cAAc,KAAK,KAAK,MAAM,gBAAgB,iBAAiB,SAAS,EAAG,CAAC;GACzF,IAAI,MAAM,OAAO;EACnB;EACA,IAAI,CAAC,UAAU,KAAK,IAAI,GAAG;EAE3B,MAAM,OADQ,CAAC,GAAG,KAAK,SAAS,YAAY,CAAC,CAAC,CAAC,KAAK,UAAU,MAAM,EACnD,CAAC,CAAC,GAAG,EAAE;EACxB,IAAI,QAAQ,CAAC,KAAK,WAAW,GAAG,GAAG,OAAO,KAAK,QAAQ,OAAO,GAAG;CACnE;AAEF;AAEA,SAAS,SAAS,OAAwB;CACxC,OAAO,iBAAiB,QAAS,MAAM,SAAS,MAAM,UAAW,OAAO,KAAK;AAC/E;;;;;;;;;AAkBA,SAAgB,qBAAqB,SAA8B,SAAyB,SAAqB;CAC/G,IAAI,QAAQ;CACZ,MAAM,eAAe,WAA0B;EAC7C,MAAM,QAAQ,iBAAiB,MAAM;EACrC,QAAQ,MAAM,kCAAkC,QAAQ,SAAS,UAAU,GAAG,IAAI,SAAS,MAAM,EAAE,GAAG;CACxG;CACA,MAAM,eAAe,UAAyB;EAC5C,MAAM,QAAQ,iBAAiB,KAAK;EACpC,QAAQ,MAAM,iCAAiC,QAAQ,SAAS,UAAU,GAAG,IAAI,SAAS,KAAK,EAAE,GAAG;EACpG,IAAI,OAAO;EACX,QAAQ;EACR,MAAM,WAAW,iBACT,QAAQ,KAAA,EAAuB,GACrC,QAAQ,kBAAkB,sBAC5B;EAGA,QACG,KAAK,CAAC,CACN,OAAO,cAAuB;GAC7B,QAAQ,MAAM,qDAAqD,SAAS,SAAS,EAAE,GAAG;EAC5F,CAAC,CAAC,CACD,cAAc;GACb,aAAa,QAAQ;GACrB,QAAQ,KAAA,EAAuB;EACjC,CAAC;CACL;CACA,OAAO,GAAG,sBAAsB,WAAW;CAC3C,OAAO,GAAG,qBAAqB,WAAW;CAC1C,aAAa;EACX,OAAO,IAAI,sBAAsB,WAAW;EAC5C,OAAO,IAAI,qBAAqB,WAAW;CAC7C;AACF"}

package/dist/src/cli/server/run.cjs

@@ -0,0 +1,69 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+const require_harnessOptions = require("../harnessOptions.cjs");
+const require_index = require("../../composition/poHomeMigration/index.cjs");
+const require_runtime$1 = require("../../builders/server/runtime.cjs");
+const require_options = require("./options.cjs");
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let node_os = require("node:os");
+node_os = require_runtime.__toESM(node_os, 1);
+let _agimon_ai_po_core_piSettings = require("@agimon-ai/po-core/piSettings");
+//#region src/cli/server/run.ts
+/** Removes Po's leftover entries from Pi's default user agent directory, once per server start. */
+function removeLegacyPiIntegration(homeDirectory) {
+	try {
+		for (const removed of (0, _agimon_ai_po_core_piSettings.removePoPiSettings)(node_path.default.join(homeDirectory, ".pi", "agent"))) process.stderr.write(`[po-server] Removed Po's Pi entry: ${removed}\n`);
+	} catch (error) {
+		process.stderr.write(`[po-server] Could not remove Po's Pi entries: ${error instanceof Error ? error.message : String(error)}\n`);
+	}
+}
+/**
+* Registers this host, then deletes `~/.pi/.po` once no older host can be using it.
+* Never fatal: a failure here leaves the old directory for the next start.
+*/
+function registerAndRetireLegacyHome(homeDirectory, environment) {
+	const poHome = (0, _agimon_ai_po_core_piSettings.poHomeDirectory)(homeDirectory, environment);
+	let release = () => void 0;
+	try {
+		release = require_index.registerPoHost(poHome);
+		const retired = require_index.retireLegacyPoHome(homeDirectory, poHome);
+		if (retired.status === "removed") process.stderr.write("[po-server] Removed the old ~/.pi/.po directory.\n");
+		if (retired.status === "deferred") process.stderr.write(`[po-server] Kept ~/.pi/.po for now: ${retired.reason}\n`);
+	} catch (error) {
+		process.stderr.write(`[po-server] Could not retire ~/.pi/.po: ${error instanceof Error ? error.message : String(error)}\n`);
+	}
+	return release;
+}
+async function runServer(args, stopSignal) {
+	const options = require_options.parseServeOptions(args);
+	const environment = Object.freeze({ ...process.env });
+	const homeDirectory = environment.HOME ?? node_os.default.homedir();
+	removeLegacyPiIntegration(homeDirectory);
+	const releaseHost = registerAndRetireLegacyHome(homeDirectory, environment);
+	const controller = new AbortController();
+	const stop = () => controller.abort();
+	process.on("SIGINT", stop);
+	process.on("SIGTERM", stop);
+	process.on("disconnect", stop);
+	stopSignal?.addEventListener("abort", stop, { once: true });
+	if (stopSignal?.aborted) stop();
+	try {
+		return await require_runtime$1.runServerRuntime(options, {
+			cwd: process.cwd(),
+			environment,
+			signal: controller.signal,
+			resolveHarnessOptions: require_harnessOptions.resolveHarnessOptions,
+			notice: (message) => void process.stderr.write(`[po-server] ${message}\n`)
+		});
+	} finally {
+		process.off("SIGINT", stop);
+		process.off("SIGTERM", stop);
+		process.off("disconnect", stop);
+		stopSignal?.removeEventListener("abort", stop);
+		releaseHost();
+	}
+}
+//#endregion
+exports.runServer = runServer;
+
+//# sourceMappingURL=run.cjs.map

package/dist/src/cli/server/run.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.cjs","names":["removePoPiSettings","path","poHomeDirectory","registerPoHost","retireLegacyPoHome","parseServeOptions","os","runServerRuntime"],"sources":["../../../../src/cli/server/run.ts"],"sourcesContent":["import os from 'node:os';\nimport path from 'node:path';\n\nimport { poHomeDirectory, removePoPiSettings } from '@agimon-ai/po-core/piSettings';\n\nimport { runServerRuntime } from '../../builders/server/runtime';\nimport { registerPoHost, retireLegacyPoHome } from '../../composition/poHomeMigration';\nimport { resolveHarnessOptions } from '../harnessOptions';\nimport { parseServeOptions } from './options';\n\n/** Removes Po's leftover entries from Pi's default user agent directory, once per server start. */\nfunction removeLegacyPiIntegration(homeDirectory: string): void {\n  try {\n    for (const removed of removePoPiSettings(path.join(homeDirectory, '.pi', 'agent'))) {\n      process.stderr.write(`[po-server] Removed Po's Pi entry: ${removed}\\n`);\n    }\n  } catch (error) {\n    process.stderr.write(\n      `[po-server] Could not remove Po's Pi entries: ${error instanceof Error ? error.message : String(error)}\\n`,\n    );\n  }\n}\n\n/**\n * Registers this host, then deletes `~/.pi/.po` once no older host can be using it.\n * Never fatal: a failure here leaves the old directory for the next start.\n */\nfunction registerAndRetireLegacyHome(homeDirectory: string, environment: NodeJS.ProcessEnv): () => void {\n  const poHome = poHomeDirectory(homeDirectory, environment);\n  let release = (): void => undefined;\n  try {\n    release = registerPoHost(poHome);\n    const retired = retireLegacyPoHome(homeDirectory, poHome);\n    if (retired.status === 'removed') process.stderr.write('[po-server] Removed the old ~/.pi/.po directory.\\n');\n    if (retired.status === 'deferred') process.stderr.write(`[po-server] Kept ~/.pi/.po for now: ${retired.reason}\\n`);\n  } catch (error) {\n    process.stderr.write(\n      `[po-server] Could not retire ~/.pi/.po: ${error instanceof Error ? error.message : String(error)}\\n`,\n    );\n  }\n  return release;\n}\n\nexport async function runServer(\n  args: readonly string[],\n  /** Aborting stops the server gracefully, as a termination signal does. */\n  stopSignal?: AbortSignal,\n): Promise<number> {\n  const options = parseServeOptions(args);\n  const environment = Object.freeze({ ...process.env });\n  const homeDirectory = environment.HOME ?? os.homedir();\n  removeLegacyPiIntegration(homeDirectory);\n  const releaseHost = registerAndRetireLegacyHome(homeDirectory, environment);\n  const controller = new AbortController();\n  const stop = () => controller.abort();\n  process.on('SIGINT', stop);\n  process.on('SIGTERM', stop);\n  // An IPC parent owns this server's lifetime. Its channel closes even when the\n  // parent is killed before it can forward a termination signal.\n  process.on('disconnect', stop);\n  stopSignal?.addEventListener('abort', stop, { once: true });\n  if (stopSignal?.aborted) stop();\n  try {\n    return await runServerRuntime(options, {\n      cwd: process.cwd(),\n      environment,\n      signal: controller.signal,\n      resolveHarnessOptions,\n      notice: (message) => void process.stderr.write(`[po-server] ${message}\\n`),\n    });\n  } finally {\n    process.off('SIGINT', stop);\n    process.off('SIGTERM', stop);\n    process.off('disconnect', stop);\n    stopSignal?.removeEventListener('abort', stop);\n    releaseHost();\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAS,0BAA0B,eAA6B;CAC9D,IAAI;EACF,KAAK,MAAM,YAAA,GAAWA,8BAAAA,mBAAAA,CAAmBC,UAAAA,QAAK,KAAK,eAAe,OAAO,OAAO,CAAC,GAC/E,QAAQ,OAAO,MAAM,sCAAsC,QAAQ,GAAG;CAE1E,SAAS,OAAO;EACd,QAAQ,OAAO,MACb,iDAAiD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GAC1G;CACF;AACF;;;;;AAMA,SAAS,4BAA4B,eAAuB,aAA4C;CACtG,MAAM,UAAA,GAASC,8BAAAA,gBAAAA,CAAgB,eAAe,WAAW;CACzD,IAAI,gBAAsB,KAAA;CAC1B,IAAI;EACF,UAAUC,cAAAA,eAAe,MAAM;EAC/B,MAAM,UAAUC,cAAAA,mBAAmB,eAAe,MAAM;EACxD,IAAI,QAAQ,WAAW,WAAW,QAAQ,OAAO,MAAM,oDAAoD;EAC3G,IAAI,QAAQ,WAAW,YAAY,QAAQ,OAAO,MAAM,uCAAuC,QAAQ,OAAO,GAAG;CACnH,SAAS,OAAO;EACd,QAAQ,OAAO,MACb,2CAA2C,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GACpG;CACF;CACA,OAAO;AACT;AAEA,eAAsB,UACpB,MAEA,YACiB;CACjB,MAAM,UAAUC,gBAAAA,kBAAkB,IAAI;CACtC,MAAM,cAAc,OAAO,OAAO,EAAE,GAAG,QAAQ,IAAI,CAAC;CACpD,MAAM,gBAAgB,YAAY,QAAQC,QAAAA,QAAG,QAAQ;CACrD,0BAA0B,aAAa;CACvC,MAAM,cAAc,4BAA4B,eAAe,WAAW;CAC1E,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,aAAa,WAAW,MAAM;CACpC,QAAQ,GAAG,UAAU,IAAI;CACzB,QAAQ,GAAG,WAAW,IAAI;CAG1B,QAAQ,GAAG,cAAc,IAAI;CAC7B,YAAY,iBAAiB,SAAS,MAAM,EAAE,MAAM,KAAK,CAAC;CAC1D,IAAI,YAAY,SAAS,KAAK;CAC9B,IAAI;EACF,OAAO,MAAMC,kBAAAA,iBAAiB,SAAS;GACrC,KAAK,QAAQ,IAAI;GACjB;GACA,QAAQ,WAAW;GACnB,uBAAA,uBAAA;GACA,SAAS,YAAY,KAAK,QAAQ,OAAO,MAAM,eAAe,QAAQ,GAAG;EAC3E,CAAC;CACH,UAAU;EACR,QAAQ,IAAI,UAAU,IAAI;EAC1B,QAAQ,IAAI,WAAW,IAAI;EAC3B,QAAQ,IAAI,cAAc,IAAI;EAC9B,YAAY,oBAAoB,SAAS,IAAI;EAC7C,YAAY;CACd;AACF"}