@agimon-ai/po-core 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/src/services/{serverFacet → serverHost}/index.mjs

@@ -1,5 +1,5 @@
-//#region src/services/serverFacet/index.ts
-function createDoomServerHost(options) {
+//#region src/services/serverHost/index.ts
+function createPoServerHost(options) {
 	const { scope, context } = options;
 	const notice = (message) => context.onNotice(message);
 	const mounts = [];
@@ -18,7 +18,7 @@ function createDoomServerHost(options) {
 			return noop;
 		}
 		if (mounts.find((mount) => mount.basePath === api.basePath) !== void 0) {
-			notice(`package API '${api.basePath}' is skipped: another facet already claims it.`);
+			notice(`package API '${api.basePath}' is skipped: another package already claims it.`);
 			return noop;
 		}
 		let handler;
@@ -94,7 +94,7 @@ function createDoomServerHost(options) {
 			return noop;
 		}
 		if (channels.some((mount) => mount.channel.frameType === channel.frameType)) {
-			notice(`hub channel '${channel.frameType}' is skipped: another facet already claims it.`);
+			notice(`hub channel '${channel.frameType}' is skipped: another package already claims it.`);
 			return noop;
 		}
 		let source;
@@ -192,6 +192,6 @@ function createDoomServerHost(options) {
 	};
 }
 //#endregion
-export { createDoomServerHost };
+export { createPoServerHost };
 
 //# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/serverHost/index.ts"],"sourcesContent":["/**\n * The server host a package registers through at one scope level.\n *\n * DESIGN PATTERNS:\n * - One mount table per level. Every package registers through this service, so\n *   the level has a single ordered record of what is mounted and under what.\n * - Base paths are first-come. A collision is reported and skipped, so one\n *   misdeclared package cannot take a server down.\n * - Handlers are started lazily on first mount and closed on dispose, so a\n *   package that registers and immediately unwinds leaves nothing running.\n *\n * AVOID:\n * - Letting a throwing `start` escape. A package whose API cannot start is\n *   reported and skipped; the remaining packages still mount.\n * - Reaching for node:*. The host owns the listener; this only owns the table.\n */\n\nimport type { PoHubChannel, PoHubChannelHost, PoHubChannelSource } from '../../schemas/hubChannel';\nimport type { PoApi, PoApiContext, PoApiHandler, PoApiScope } from '../../schemas/packageApi';\nimport type { PoPluginRegistry } from '../../schemas/pluginProtocol';\nimport type { PoServerHostService, PoServerRegistration } from '../../schemas/serverPlugin';\n\ninterface MountedApi {\n  readonly basePath: string;\n  readonly handler: PoApiHandler;\n}\n\ninterface MountedChannel {\n  readonly channel: PoHubChannel;\n  readonly source?: PoHubChannelSource;\n  readonly registration?: PoServerRegistration;\n}\n\nexport interface CreatePoServerHostOptions {\n  scope: PoApiScope;\n  context: PoApiContext;\n  /** Required when packages may register live channels. */\n  channelHost?: PoHubChannelHost;\n  /** Supplies a channel-specific host when one host serves multiple channels. */\n  channelHostFor?: (channel: PoHubChannel) => PoHubChannelHost;\n  /** Delegates channel mounting to an owner of the canonical channel table. */\n  mountChannel?: (channel: PoHubChannel) => PoServerRegistration;\n  /** Shared exact-scope dispatch table, owned by the server composition. */\n  pluginRegistry?: PoPluginRegistry;\n  /** Called when an API mount table entry appears or disappears. */\n  onChange?: (mounted: readonly string[]) => void;\n  /** Called when a channel mount table entry appears or disappears. */\n  onChannelsChange?: (mounted: readonly string[]) => void;\n}\n\n/** The mount table a server host exposes to its packages, plus the router's read side. */\nexport interface PoServerHost extends PoServerHostService {\n  /** The handler owning a base path, for the router that dispatches to it. */\n  handlerFor(basePath: string): PoApiHandler | undefined;\n  /** Close every mounted handler and empty the table. */\n  dispose(): void;\n}\n\nexport function createPoServerHost(options: CreatePoServerHostOptions): PoServerHost {\n  const { scope, context } = options;\n  const notice = (message: string): void => context.onNotice(message);\n  const mounts: MountedApi[] = [];\n  const channels: MountedChannel[] = [];\n  const methods = new Set<() => void>();\n  let disposed = false;\n\n  const changed = (): void => options.onChange?.(mounts.map((mount) => mount.basePath));\n  const channelsChanged = (): void => options.onChannelsChange?.(channels.map((mount) => mount.channel.frameType));\n\n  const noop: PoServerRegistration = { mounted: false, dispose: () => undefined };\n\n  const registerApi = (api: PoApi): PoServerRegistration => {\n    if (disposed) {\n      notice(`package API '${api.basePath}' is skipped: the server host is already disposed.`);\n      return noop;\n    }\n    const holder = mounts.find((mount) => mount.basePath === api.basePath);\n    if (holder !== undefined) {\n      notice(`package API '${api.basePath}' is skipped: another package already claims it.`);\n      return noop;\n    }\n    let handler: PoApiHandler;\n    try {\n      handler = api.start(context);\n    } catch (error) {\n      notice(`package API '${api.basePath}' did not start (${String(error)}); it is skipped.`);\n      return noop;\n    }\n    const mount: MountedApi = { basePath: api.basePath, handler };\n    mounts.push(mount);\n    changed();\n    let released = false;\n    return {\n      mounted: true,\n      dispose: () => {\n        if (released) return;\n        released = true;\n        const index = mounts.indexOf(mount);\n        if (index >= 0) mounts.splice(index, 1);\n        try {\n          handler.close();\n        } catch (error) {\n          notice(`package API '${mount.basePath}' did not close cleanly (${String(error)}).`);\n        }\n        changed();\n      },\n    };\n  };\n\n  const registerChannel = (channel: PoHubChannel): PoServerRegistration => {\n    if (disposed) {\n      notice(`hub channel '${channel.frameType}' is skipped: the server host is already disposed.`);\n      return noop;\n    }\n    if (options.mountChannel !== undefined) {\n      let registration: PoServerRegistration;\n      try {\n        registration = options.mountChannel(channel);\n      } catch (error) {\n        notice(`hub channel '${channel.frameType}' did not mount (${String(error)}); it is skipped.`);\n        return noop;\n      }\n      if (registration.mounted !== true) return registration;\n      const mount: MountedChannel = { channel, registration };\n      channels.push(mount);\n      channelsChanged();\n      let released = false;\n      return {\n        mounted: true,\n        dispose: () => {\n          if (released) return;\n          released = true;\n          const index = channels.indexOf(mount);\n          if (index >= 0) channels.splice(index, 1);\n          try {\n            registration.dispose();\n          } catch (error) {\n            notice(`hub channel '${channel.frameType}' did not close cleanly (${String(error)}).`);\n          }\n          channelsChanged();\n        },\n      };\n    }\n    const channelHost = options.channelHostFor?.(channel) ?? options.channelHost;\n    if (!channelHost) {\n      notice(`hub channel '${channel.frameType}' is skipped: this server host has no channel capability.`);\n      return noop;\n    }\n    if (channels.some((mount) => mount.channel.frameType === channel.frameType)) {\n      notice(`hub channel '${channel.frameType}' is skipped: another package already claims it.`);\n      return noop;\n    }\n    let source: PoHubChannelSource;\n    try {\n      source = channel.start(channelHost);\n    } catch (error) {\n      notice(`hub channel '${channel.frameType}' did not start (${String(error)}); it is skipped.`);\n      return noop;\n    }\n    const mount: MountedChannel = { channel, source };\n    channels.push(mount);\n    channelsChanged();\n    let released = false;\n    return {\n      mounted: true,\n      dispose: () => {\n        if (released) return;\n        released = true;\n        const index = channels.indexOf(mount);\n        if (index >= 0) channels.splice(index, 1);\n        try {\n          source.close();\n        } catch (error) {\n          notice(`hub channel '${channel.frameType}' did not close cleanly (${String(error)}).`);\n        }\n        channelsChanged();\n      },\n    };\n  };\n\n  const registerMethod: PoServerHostService['registerMethod'] = (definition, handler) => {\n    if (disposed || !options.pluginRegistry) {\n      notice(\n        `plugin method '${definition.service}.${definition.method}' is skipped: this host has no plugin dispatcher.`,\n      );\n      return noop;\n    }\n    const mount =\n      scope === 'global'\n        ? { scope: 'global' as const }\n        : scope === 'workspace' && context.workspaceId\n          ? { scope: 'workspace' as const, workspaceId: context.workspaceId }\n          : scope === 'session' && context.sessionId\n            ? { scope: 'session' as const, sessionId: context.sessionId }\n            : undefined;\n    if (!mount) {\n      notice(`plugin method '${definition.service}.${definition.method}' is skipped: this host has no mount identity.`);\n      return noop;\n    }\n    try {\n      const release = options.pluginRegistry.register(mount, definition, handler);\n      let released = false;\n      const dispose = () => {\n        if (released) return;\n        released = true;\n        methods.delete(dispose);\n        release();\n      };\n      methods.add(dispose);\n      return { mounted: true, dispose };\n    } catch (error) {\n      notice(`plugin method '${definition.service}.${definition.method}' did not mount (${String(error)}).`);\n      return noop;\n    }\n  };\n\n  return {\n    scope,\n    context,\n    registerApi,\n    registerChannel,\n    registerMethod,\n    mounted: () => mounts.map((mount) => mount.basePath),\n    mountedChannels: () => channels.map((mount) => mount.channel.frameType),\n    handlerFor: (basePath) => mounts.find((mount) => mount.basePath === basePath)?.handler,\n    dispose: () => {\n      if (disposed) return;\n      disposed = true;\n      for (const release of [...methods].reverse()) release();\n      for (const mount of channels.splice(0).reverse()) {\n        try {\n          if (mount.registration !== undefined) mount.registration.dispose();\n          else mount.source?.close();\n        } catch (error) {\n          notice(`hub channel '${mount.channel.frameType}' did not close cleanly (${String(error)}).`);\n        }\n      }\n      for (const mount of mounts.splice(0).reverse()) {\n        try {\n          mount.handler.close();\n        } catch (error) {\n          notice(`package API '${mount.basePath}' did not close cleanly (${String(error)}).`);\n        }\n      }\n      channelsChanged();\n      changed();\n    },\n  };\n}\n"],"mappings":"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"}

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

@@ -1,5 +1,6 @@
 const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
-const require_runtimePiSettings = require("../../../runtimePiSettings.cjs");
+const require_core = require("../piSettings/core.cjs");
+require("../../../runtimePiSettings.cjs");
 const require_contextDetailStore = require("../../../contextDetailStore.cjs");
 const require_sessionFiles = require("../../constants/sessionFiles.cjs");
 let node_crypto = require("node:crypto");
@@ -15,7 +16,7 @@ node_path = require_runtime.__toESM(node_path, 1);
 * two files with the same name apart and lets the original name survive. The
 * directory is owner-only because an attachment is whatever the user dropped in.
 */
-const DIRECTORY_NAME = "doom-attachments";
+const DIRECTORY_NAME = "po-attachments";
 const PRIVATE_DIRECTORY_MODE = 448;
 const PRIVATE_FILE_MODE = 384;
 const MAX_NAME_BYTES = 200;
@@ -25,7 +26,7 @@ const RETENTION_MS = 6048e5;
 function sessionAttachmentRoot(sessionId, environment = process.env) {
 	const directory = require_contextDetailStore.safeName(sessionId);
 	if (directory === "" || directory === "." || directory === "..") throw new Error("This session id cannot hold attachments.");
-	return node_path.default.join(require_runtimePiSettings.piAgentDirectory(environment), DIRECTORY_NAME, directory);
+	return node_path.default.join(require_core.piAgentDirectory(environment), DIRECTORY_NAME, directory);
 }
 /**
 * One plain file name: no separators or control characters, and no leading dot, so

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

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["safeName","path","piAgentDirectory","fs","randomUUID","SESSION_FILE_CONTENT_TYPES"],"sources":["../../../../src/services/sessionAttachments/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { SESSION_FILE_CONTENT_TYPES, SESSION_FILE_DEFAULT_CONTENT_TYPE } from '../../constants/sessionFiles';\nimport { safeName } from '../contextDetailStore';\nimport { piAgentDirectory } from '../piSettings';\n\n/**\n * Where composer attachments live on the host, so a tool can be handed one by path.\n *\n * Each upload gets its own random directory under the session's root, which keeps\n * two files with the same name apart and lets the original name survive. The\n * directory is owner-only because an attachment is whatever the user dropped in.\n */\n\nconst DIRECTORY_NAME = 'doom-attachments';\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst PRIVATE_FILE_MODE = 0o600;\nconst MAX_NAME_BYTES = 200;\nconst FALLBACK_NAME = 'file';\nconst RETENTION_MS = 7 * 24 * 60 * 60 * 1000;\n\nexport interface SessionAttachment {\n  path: string;\n  name: string;\n  size: number;\n  mimeType: string;\n}\n\n/** Throws for an id whose directory would be the attachment root itself or its parent. */\nexport function sessionAttachmentRoot(\n  sessionId: string,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): string {\n  const directory = safeName(sessionId);\n  if (directory === '' || directory === '.' || directory === '..')\n    throw new Error('This session id cannot hold attachments.');\n  return path.join(piAgentDirectory(environment), DIRECTORY_NAME, directory);\n}\n\n/**\n * One plain file name: no separators or control characters, and no leading dot, so\n * an attachment is never hidden and never `.` or `..`. Cut on a code point boundary\n * to fit common file-name limits.\n */\nfunction attachmentName(name: string): string {\n  // oxlint-disable-next-line no-control-regex -- stripping control characters is the point\n  const plain = name.replace(/[\\u0000-\\u001f\\u007f/\\\\]/gu, '').replace(/^\\.+/u, '');\n  let fitted = '';\n  for (const character of plain) {\n    if (Buffer.byteLength(fitted + character) > MAX_NAME_BYTES) break;\n    fitted += character;\n  }\n  return fitted === '' ? FALLBACK_NAME : fitted;\n}\n\n/** Best effort: a sweep that cannot read or remove a directory leaves it for the next write. */\nasync function sweepExpired(root: string): Promise<void> {\n  const cutoff = Date.now() - RETENTION_MS;\n  let sessions: fs.Dirent[];\n  try {\n    sessions = await fs.promises.readdir(root, { withFileTypes: true });\n  } catch {\n    return;\n  }\n  for (const session of sessions) {\n    if (!session.isDirectory()) continue;\n    const sessionDirectory = path.join(root, session.name);\n    let uploads: fs.Dirent[];\n    try {\n      uploads = await fs.promises.readdir(sessionDirectory, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const upload of uploads) {\n      if (!upload.isDirectory()) continue;\n      const uploadDirectory = path.join(sessionDirectory, upload.name);\n      try {\n        if ((await fs.promises.lstat(uploadDirectory)).mtimeMs < cutoff)\n          await fs.promises.rm(uploadDirectory, { recursive: true, force: true });\n      } catch {\n        // Left for the next sweep.\n      }\n    }\n  }\n}\n\n/** Stores one attachment and returns where it landed. Written through a temporary file, then renamed. */\nexport async function writeSessionAttachment(\n  sessionId: string,\n  name: string,\n  bytes: Uint8Array,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): Promise<SessionAttachment> {\n  const root = sessionAttachmentRoot(sessionId, environment);\n  const fileName = attachmentName(name);\n  await fs.promises.mkdir(root, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });\n  await sweepExpired(path.dirname(root));\n  const directory = path.join(root, randomUUID());\n  await fs.promises.mkdir(directory, { mode: PRIVATE_DIRECTORY_MODE });\n  const target = path.join(directory, fileName);\n  const temporary = path.join(directory, `.${randomUUID()}.tmp`);\n  try {\n    await fs.promises.writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });\n    await fs.promises.rename(temporary, target);\n  } catch (error) {\n    await fs.promises.rm(directory, { recursive: true, force: true });\n    throw error;\n  }\n  return {\n    path: target,\n    name: fileName,\n    size: bytes.byteLength,\n    mimeType: SESSION_FILE_CONTENT_TYPES[path.extname(fileName).toLowerCase()] ?? SESSION_FILE_DEFAULT_CONTENT_TYPE,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["safeName","path","piAgentDirectory","fs","randomUUID","SESSION_FILE_CONTENT_TYPES"],"sources":["../../../../src/services/sessionAttachments/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { SESSION_FILE_CONTENT_TYPES, SESSION_FILE_DEFAULT_CONTENT_TYPE } from '../../constants/sessionFiles';\nimport { safeName } from '../contextDetailStore';\nimport { piAgentDirectory } from '../piSettings';\nimport type { SessionAttachment } from './type';\n\n/**\n * Where composer attachments live on the host, so a tool can be handed one by path.\n *\n * Each upload gets its own random directory under the session's root, which keeps\n * two files with the same name apart and lets the original name survive. The\n * directory is owner-only because an attachment is whatever the user dropped in.\n */\n\nconst DIRECTORY_NAME = 'po-attachments';\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst PRIVATE_FILE_MODE = 0o600;\nconst MAX_NAME_BYTES = 200;\nconst FALLBACK_NAME = 'file';\nconst RETENTION_MS = 7 * 24 * 60 * 60 * 1000;\n\nexport type { SessionAttachment } from './type';\n\n/** Throws for an id whose directory would be the attachment root itself or its parent. */\nexport function sessionAttachmentRoot(\n  sessionId: string,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): string {\n  const directory = safeName(sessionId);\n  if (directory === '' || directory === '.' || directory === '..')\n    throw new Error('This session id cannot hold attachments.');\n  return path.join(piAgentDirectory(environment), DIRECTORY_NAME, directory);\n}\n\n/**\n * One plain file name: no separators or control characters, and no leading dot, so\n * an attachment is never hidden and never `.` or `..`. Cut on a code point boundary\n * to fit common file-name limits.\n */\nfunction attachmentName(name: string): string {\n  // oxlint-disable-next-line no-control-regex -- stripping control characters is the point\n  const plain = name.replace(/[\\u0000-\\u001f\\u007f/\\\\]/gu, '').replace(/^\\.+/u, '');\n  let fitted = '';\n  for (const character of plain) {\n    if (Buffer.byteLength(fitted + character) > MAX_NAME_BYTES) break;\n    fitted += character;\n  }\n  return fitted === '' ? FALLBACK_NAME : fitted;\n}\n\n/** Best effort: a sweep that cannot read or remove a directory leaves it for the next write. */\nasync function sweepExpired(root: string): Promise<void> {\n  const cutoff = Date.now() - RETENTION_MS;\n  let sessions: fs.Dirent[];\n  try {\n    sessions = await fs.promises.readdir(root, { withFileTypes: true });\n  } catch {\n    return;\n  }\n  for (const session of sessions) {\n    if (!session.isDirectory()) continue;\n    const sessionDirectory = path.join(root, session.name);\n    let uploads: fs.Dirent[];\n    try {\n      uploads = await fs.promises.readdir(sessionDirectory, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const upload of uploads) {\n      if (!upload.isDirectory()) continue;\n      const uploadDirectory = path.join(sessionDirectory, upload.name);\n      try {\n        if ((await fs.promises.lstat(uploadDirectory)).mtimeMs < cutoff)\n          await fs.promises.rm(uploadDirectory, { recursive: true, force: true });\n      } catch {\n        // Left for the next sweep.\n      }\n    }\n  }\n}\n\n/** Stores one attachment and returns where it landed. Written through a temporary file, then renamed. */\nexport async function writeSessionAttachment(\n  sessionId: string,\n  name: string,\n  bytes: Uint8Array,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): Promise<SessionAttachment> {\n  const root = sessionAttachmentRoot(sessionId, environment);\n  const fileName = attachmentName(name);\n  await fs.promises.mkdir(root, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });\n  await sweepExpired(path.dirname(root));\n  const directory = path.join(root, randomUUID());\n  await fs.promises.mkdir(directory, { mode: PRIVATE_DIRECTORY_MODE });\n  const target = path.join(directory, fileName);\n  const temporary = path.join(directory, `.${randomUUID()}.tmp`);\n  try {\n    await fs.promises.writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });\n    await fs.promises.rename(temporary, target);\n  } catch (error) {\n    await fs.promises.rm(directory, { recursive: true, force: true });\n    throw error;\n  }\n  return {\n    path: target,\n    name: fileName,\n    size: bytes.byteLength,\n    mimeType: SESSION_FILE_CONTENT_TYPES[path.extname(fileName).toLowerCase()] ?? SESSION_FILE_DEFAULT_CONTENT_TYPE,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,MAAM,iBAAiB;AACvB,MAAM,yBAAyB;AAC/B,MAAM,oBAAoB;AAC1B,MAAM,iBAAiB;AACvB,MAAM,gBAAgB;AACtB,MAAM,eAAe;;AAKrB,SAAgB,sBACd,WACA,cAA4D,QAAQ,KAC5D;CACR,MAAM,YAAYA,2BAAAA,SAAS,SAAS;CACpC,IAAI,cAAc,MAAM,cAAc,OAAO,cAAc,MACzD,MAAM,IAAI,MAAM,0CAA0C;CAC5D,OAAOC,UAAAA,QAAK,KAAKC,aAAAA,iBAAiB,WAAW,GAAG,gBAAgB,SAAS;AAC3E;;;;;;AAOA,SAAS,eAAe,MAAsB;CAE5C,MAAM,QAAQ,KAAK,QAAQ,8BAA8B,EAAE,CAAC,CAAC,QAAQ,SAAS,EAAE;CAChF,IAAI,SAAS;CACb,KAAK,MAAM,aAAa,OAAO;EAC7B,IAAI,OAAO,WAAW,SAAS,SAAS,IAAI,gBAAgB;EAC5D,UAAU;CACZ;CACA,OAAO,WAAW,KAAK,gBAAgB;AACzC;;AAGA,eAAe,aAAa,MAA6B;CACvD,MAAM,SAAS,KAAK,IAAI,IAAI;CAC5B,IAAI;CACJ,IAAI;EACF,WAAW,MAAMC,QAAAA,QAAG,SAAS,QAAQ,MAAM,EAAE,eAAe,KAAK,CAAC;CACpE,QAAQ;EACN;CACF;CACA,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,CAAC,QAAQ,YAAY,GAAG;EAC5B,MAAM,mBAAmBF,UAAAA,QAAK,KAAK,MAAM,QAAQ,IAAI;EACrD,IAAI;EACJ,IAAI;GACF,UAAU,MAAME,QAAAA,QAAG,SAAS,QAAQ,kBAAkB,EAAE,eAAe,KAAK,CAAC;EAC/E,QAAQ;GACN;EACF;EACA,KAAK,MAAM,UAAU,SAAS;GAC5B,IAAI,CAAC,OAAO,YAAY,GAAG;GAC3B,MAAM,kBAAkBF,UAAAA,QAAK,KAAK,kBAAkB,OAAO,IAAI;GAC/D,IAAI;IACF,KAAK,MAAME,QAAAA,QAAG,SAAS,MAAM,eAAe,EAAA,CAAG,UAAU,QACvD,MAAMA,QAAAA,QAAG,SAAS,GAAG,iBAAiB;KAAE,WAAW;KAAM,OAAO;IAAK,CAAC;GAC1E,QAAQ,CAER;EACF;CACF;AACF;;AAGA,eAAsB,uBACpB,WACA,MACA,OACA,cAA4D,QAAQ,KACxC;CAC5B,MAAM,OAAO,sBAAsB,WAAW,WAAW;CACzD,MAAM,WAAW,eAAe,IAAI;CACpC,MAAMA,QAAAA,QAAG,SAAS,MAAM,MAAM;EAAE,WAAW;EAAM,MAAM;CAAuB,CAAC;CAC/E,MAAM,aAAaF,UAAAA,QAAK,QAAQ,IAAI,CAAC;CACrC,MAAM,YAAYA,UAAAA,QAAK,KAAK,OAAA,GAAMG,YAAAA,WAAAA,CAAW,CAAC;CAC9C,MAAMD,QAAAA,QAAG,SAAS,MAAM,WAAW,EAAE,MAAM,uBAAuB,CAAC;CACnE,MAAM,SAASF,UAAAA,QAAK,KAAK,WAAW,QAAQ;CAC5C,MAAM,YAAYA,UAAAA,QAAK,KAAK,WAAW,KAAA,GAAIG,YAAAA,WAAAA,CAAW,EAAE,KAAK;CAC7D,IAAI;EACF,MAAMD,QAAAA,QAAG,SAAS,UAAU,WAAW,OAAO;GAAE,MAAM;GAAmB,MAAM;EAAK,CAAC;EACrF,MAAMA,QAAAA,QAAG,SAAS,OAAO,WAAW,MAAM;CAC5C,SAAS,OAAO;EACd,MAAMA,QAAAA,QAAG,SAAS,GAAG,WAAW;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;EAChE,MAAM;CACR;CACA,OAAO;EACL,MAAM;EACN,MAAM;EACN,MAAM,MAAM;EACZ,UAAUE,qBAAAA,2BAA2BJ,UAAAA,QAAK,QAAQ,QAAQ,CAAC,CAAC,YAAY,MAAA;CAC1E;AACF"}

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

@@ -1,10 +1,5 @@
+import { SessionAttachment } from "./type.mjs";
 //#region src/services/sessionAttachments/index.d.ts
-export interface SessionAttachment {
-  path: string;
-  name: string;
-  size: number;
-  mimeType: string;
-}
 /** Stores one attachment and returns where it landed. Written through a temporary file, then renamed. */
 export declare function writeSessionAttachment(sessionId: string, name: string, bytes: Uint8Array, environment?: Readonly<Record<string, string | undefined>>): Promise<SessionAttachment>;
 //#endregion

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/sessionAttachments/index.ts"],"mappings":";iBAuBiB;EACf;EACA;EACA;EACA;;;wBA8DoB,uBACpB,mBACA,cACA,OAAO,YACP,cAAa,SAAS,sCACrB,QAAQ"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/sessionAttachments/index.ts"],"mappings":";;;wBAqFsB,uBACpB,mBACA,cACA,OAAO,YACP,cAAa,SAAS,sCACrB,QAAQ"}

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

@@ -1,4 +1,5 @@
-import { piAgentDirectory } from "../../../runtimePiSettings.mjs";
+import { piAgentDirectory } from "../piSettings/core.mjs";
+import "../../../runtimePiSettings.mjs";
 import { safeName } from "../../../contextDetailStore.mjs";
 import { SESSION_FILE_CONTENT_TYPES } from "../../constants/sessionFiles.mjs";
 import { randomUUID } from "node:crypto";
@@ -12,7 +13,7 @@ import path from "node:path";
 * two files with the same name apart and lets the original name survive. The
 * directory is owner-only because an attachment is whatever the user dropped in.
 */
-const DIRECTORY_NAME = "doom-attachments";
+const DIRECTORY_NAME = "po-attachments";
 const PRIVATE_DIRECTORY_MODE = 448;
 const PRIVATE_FILE_MODE = 384;
 const MAX_NAME_BYTES = 200;

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

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/sessionAttachments/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { SESSION_FILE_CONTENT_TYPES, SESSION_FILE_DEFAULT_CONTENT_TYPE } from '../../constants/sessionFiles';\nimport { safeName } from '../contextDetailStore';\nimport { piAgentDirectory } from '../piSettings';\n\n/**\n * Where composer attachments live on the host, so a tool can be handed one by path.\n *\n * Each upload gets its own random directory under the session's root, which keeps\n * two files with the same name apart and lets the original name survive. The\n * directory is owner-only because an attachment is whatever the user dropped in.\n */\n\nconst DIRECTORY_NAME = 'doom-attachments';\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst PRIVATE_FILE_MODE = 0o600;\nconst MAX_NAME_BYTES = 200;\nconst FALLBACK_NAME = 'file';\nconst RETENTION_MS = 7 * 24 * 60 * 60 * 1000;\n\nexport interface SessionAttachment {\n  path: string;\n  name: string;\n  size: number;\n  mimeType: string;\n}\n\n/** Throws for an id whose directory would be the attachment root itself or its parent. */\nexport function sessionAttachmentRoot(\n  sessionId: string,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): string {\n  const directory = safeName(sessionId);\n  if (directory === '' || directory === '.' || directory === '..')\n    throw new Error('This session id cannot hold attachments.');\n  return path.join(piAgentDirectory(environment), DIRECTORY_NAME, directory);\n}\n\n/**\n * One plain file name: no separators or control characters, and no leading dot, so\n * an attachment is never hidden and never `.` or `..`. Cut on a code point boundary\n * to fit common file-name limits.\n */\nfunction attachmentName(name: string): string {\n  // oxlint-disable-next-line no-control-regex -- stripping control characters is the point\n  const plain = name.replace(/[\\u0000-\\u001f\\u007f/\\\\]/gu, '').replace(/^\\.+/u, '');\n  let fitted = '';\n  for (const character of plain) {\n    if (Buffer.byteLength(fitted + character) > MAX_NAME_BYTES) break;\n    fitted += character;\n  }\n  return fitted === '' ? FALLBACK_NAME : fitted;\n}\n\n/** Best effort: a sweep that cannot read or remove a directory leaves it for the next write. */\nasync function sweepExpired(root: string): Promise<void> {\n  const cutoff = Date.now() - RETENTION_MS;\n  let sessions: fs.Dirent[];\n  try {\n    sessions = await fs.promises.readdir(root, { withFileTypes: true });\n  } catch {\n    return;\n  }\n  for (const session of sessions) {\n    if (!session.isDirectory()) continue;\n    const sessionDirectory = path.join(root, session.name);\n    let uploads: fs.Dirent[];\n    try {\n      uploads = await fs.promises.readdir(sessionDirectory, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const upload of uploads) {\n      if (!upload.isDirectory()) continue;\n      const uploadDirectory = path.join(sessionDirectory, upload.name);\n      try {\n        if ((await fs.promises.lstat(uploadDirectory)).mtimeMs < cutoff)\n          await fs.promises.rm(uploadDirectory, { recursive: true, force: true });\n      } catch {\n        // Left for the next sweep.\n      }\n    }\n  }\n}\n\n/** Stores one attachment and returns where it landed. Written through a temporary file, then renamed. */\nexport async function writeSessionAttachment(\n  sessionId: string,\n  name: string,\n  bytes: Uint8Array,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): Promise<SessionAttachment> {\n  const root = sessionAttachmentRoot(sessionId, environment);\n  const fileName = attachmentName(name);\n  await fs.promises.mkdir(root, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });\n  await sweepExpired(path.dirname(root));\n  const directory = path.join(root, randomUUID());\n  await fs.promises.mkdir(directory, { mode: PRIVATE_DIRECTORY_MODE });\n  const target = path.join(directory, fileName);\n  const temporary = path.join(directory, `.${randomUUID()}.tmp`);\n  try {\n    await fs.promises.writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });\n    await fs.promises.rename(temporary, target);\n  } catch (error) {\n    await fs.promises.rm(directory, { recursive: true, force: true });\n    throw error;\n  }\n  return {\n    path: target,\n    name: fileName,\n    size: bytes.byteLength,\n    mimeType: SESSION_FILE_CONTENT_TYPES[path.extname(fileName).toLowerCase()] ?? SESSION_FILE_DEFAULT_CONTENT_TYPE,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAgBA,MAAM,iBAAiB;AACvB,MAAM,yBAAyB;AAC/B,MAAM,oBAAoB;AAC1B,MAAM,iBAAiB;AACvB,MAAM,gBAAgB;AACtB,MAAM,eAAe;;AAUrB,SAAgB,sBACd,WACA,cAA4D,QAAQ,KAC5D;CACR,MAAM,YAAY,SAAS,SAAS;CACpC,IAAI,cAAc,MAAM,cAAc,OAAO,cAAc,MACzD,MAAM,IAAI,MAAM,0CAA0C;CAC5D,OAAO,KAAK,KAAK,iBAAiB,WAAW,GAAG,gBAAgB,SAAS;AAC3E;;;;;;AAOA,SAAS,eAAe,MAAsB;CAE5C,MAAM,QAAQ,KAAK,QAAQ,8BAA8B,EAAE,CAAC,CAAC,QAAQ,SAAS,EAAE;CAChF,IAAI,SAAS;CACb,KAAK,MAAM,aAAa,OAAO;EAC7B,IAAI,OAAO,WAAW,SAAS,SAAS,IAAI,gBAAgB;EAC5D,UAAU;CACZ;CACA,OAAO,WAAW,KAAK,gBAAgB;AACzC;;AAGA,eAAe,aAAa,MAA6B;CACvD,MAAM,SAAS,KAAK,IAAI,IAAI;CAC5B,IAAI;CACJ,IAAI;EACF,WAAW,MAAM,GAAG,SAAS,QAAQ,MAAM,EAAE,eAAe,KAAK,CAAC;CACpE,QAAQ;EACN;CACF;CACA,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,CAAC,QAAQ,YAAY,GAAG;EAC5B,MAAM,mBAAmB,KAAK,KAAK,MAAM,QAAQ,IAAI;EACrD,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,GAAG,SAAS,QAAQ,kBAAkB,EAAE,eAAe,KAAK,CAAC;EAC/E,QAAQ;GACN;EACF;EACA,KAAK,MAAM,UAAU,SAAS;GAC5B,IAAI,CAAC,OAAO,YAAY,GAAG;GAC3B,MAAM,kBAAkB,KAAK,KAAK,kBAAkB,OAAO,IAAI;GAC/D,IAAI;IACF,KAAK,MAAM,GAAG,SAAS,MAAM,eAAe,EAAA,CAAG,UAAU,QACvD,MAAM,GAAG,SAAS,GAAG,iBAAiB;KAAE,WAAW;KAAM,OAAO;IAAK,CAAC;GAC1E,QAAQ,CAER;EACF;CACF;AACF;;AAGA,eAAsB,uBACpB,WACA,MACA,OACA,cAA4D,QAAQ,KACxC;CAC5B,MAAM,OAAO,sBAAsB,WAAW,WAAW;CACzD,MAAM,WAAW,eAAe,IAAI;CACpC,MAAM,GAAG,SAAS,MAAM,MAAM;EAAE,WAAW;EAAM,MAAM;CAAuB,CAAC;CAC/E,MAAM,aAAa,KAAK,QAAQ,IAAI,CAAC;CACrC,MAAM,YAAY,KAAK,KAAK,MAAM,WAAW,CAAC;CAC9C,MAAM,GAAG,SAAS,MAAM,WAAW,EAAE,MAAM,uBAAuB,CAAC;CACnE,MAAM,SAAS,KAAK,KAAK,WAAW,QAAQ;CAC5C,MAAM,YAAY,KAAK,KAAK,WAAW,IAAI,WAAW,EAAE,KAAK;CAC7D,IAAI;EACF,MAAM,GAAG,SAAS,UAAU,WAAW,OAAO;GAAE,MAAM;GAAmB,MAAM;EAAK,CAAC;EACrF,MAAM,GAAG,SAAS,OAAO,WAAW,MAAM;CAC5C,SAAS,OAAO;EACd,MAAM,GAAG,SAAS,GAAG,WAAW;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;EAChE,MAAM;CACR;CACA,OAAO;EACL,MAAM;EACN,MAAM;EACN,MAAM,MAAM;EACZ,UAAU,2BAA2B,KAAK,QAAQ,QAAQ,CAAC,CAAC,YAAY,MAAA;CAC1E;AACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/sessionAttachments/index.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\n\nimport { SESSION_FILE_CONTENT_TYPES, SESSION_FILE_DEFAULT_CONTENT_TYPE } from '../../constants/sessionFiles';\nimport { safeName } from '../contextDetailStore';\nimport { piAgentDirectory } from '../piSettings';\nimport type { SessionAttachment } from './type';\n\n/**\n * Where composer attachments live on the host, so a tool can be handed one by path.\n *\n * Each upload gets its own random directory under the session's root, which keeps\n * two files with the same name apart and lets the original name survive. The\n * directory is owner-only because an attachment is whatever the user dropped in.\n */\n\nconst DIRECTORY_NAME = 'po-attachments';\nconst PRIVATE_DIRECTORY_MODE = 0o700;\nconst PRIVATE_FILE_MODE = 0o600;\nconst MAX_NAME_BYTES = 200;\nconst FALLBACK_NAME = 'file';\nconst RETENTION_MS = 7 * 24 * 60 * 60 * 1000;\n\nexport type { SessionAttachment } from './type';\n\n/** Throws for an id whose directory would be the attachment root itself or its parent. */\nexport function sessionAttachmentRoot(\n  sessionId: string,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): string {\n  const directory = safeName(sessionId);\n  if (directory === '' || directory === '.' || directory === '..')\n    throw new Error('This session id cannot hold attachments.');\n  return path.join(piAgentDirectory(environment), DIRECTORY_NAME, directory);\n}\n\n/**\n * One plain file name: no separators or control characters, and no leading dot, so\n * an attachment is never hidden and never `.` or `..`. Cut on a code point boundary\n * to fit common file-name limits.\n */\nfunction attachmentName(name: string): string {\n  // oxlint-disable-next-line no-control-regex -- stripping control characters is the point\n  const plain = name.replace(/[\\u0000-\\u001f\\u007f/\\\\]/gu, '').replace(/^\\.+/u, '');\n  let fitted = '';\n  for (const character of plain) {\n    if (Buffer.byteLength(fitted + character) > MAX_NAME_BYTES) break;\n    fitted += character;\n  }\n  return fitted === '' ? FALLBACK_NAME : fitted;\n}\n\n/** Best effort: a sweep that cannot read or remove a directory leaves it for the next write. */\nasync function sweepExpired(root: string): Promise<void> {\n  const cutoff = Date.now() - RETENTION_MS;\n  let sessions: fs.Dirent[];\n  try {\n    sessions = await fs.promises.readdir(root, { withFileTypes: true });\n  } catch {\n    return;\n  }\n  for (const session of sessions) {\n    if (!session.isDirectory()) continue;\n    const sessionDirectory = path.join(root, session.name);\n    let uploads: fs.Dirent[];\n    try {\n      uploads = await fs.promises.readdir(sessionDirectory, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const upload of uploads) {\n      if (!upload.isDirectory()) continue;\n      const uploadDirectory = path.join(sessionDirectory, upload.name);\n      try {\n        if ((await fs.promises.lstat(uploadDirectory)).mtimeMs < cutoff)\n          await fs.promises.rm(uploadDirectory, { recursive: true, force: true });\n      } catch {\n        // Left for the next sweep.\n      }\n    }\n  }\n}\n\n/** Stores one attachment and returns where it landed. Written through a temporary file, then renamed. */\nexport async function writeSessionAttachment(\n  sessionId: string,\n  name: string,\n  bytes: Uint8Array,\n  environment: Readonly<Record<string, string | undefined>> = process.env,\n): Promise<SessionAttachment> {\n  const root = sessionAttachmentRoot(sessionId, environment);\n  const fileName = attachmentName(name);\n  await fs.promises.mkdir(root, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });\n  await sweepExpired(path.dirname(root));\n  const directory = path.join(root, randomUUID());\n  await fs.promises.mkdir(directory, { mode: PRIVATE_DIRECTORY_MODE });\n  const target = path.join(directory, fileName);\n  const temporary = path.join(directory, `.${randomUUID()}.tmp`);\n  try {\n    await fs.promises.writeFile(temporary, bytes, { mode: PRIVATE_FILE_MODE, flag: 'wx' });\n    await fs.promises.rename(temporary, target);\n  } catch (error) {\n    await fs.promises.rm(directory, { recursive: true, force: true });\n    throw error;\n  }\n  return {\n    path: target,\n    name: fileName,\n    size: bytes.byteLength,\n    mimeType: SESSION_FILE_CONTENT_TYPES[path.extname(fileName).toLowerCase()] ?? SESSION_FILE_DEFAULT_CONTENT_TYPE,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAiBA,MAAM,iBAAiB;AACvB,MAAM,yBAAyB;AAC/B,MAAM,oBAAoB;AAC1B,MAAM,iBAAiB;AACvB,MAAM,gBAAgB;AACtB,MAAM,eAAe;;AAKrB,SAAgB,sBACd,WACA,cAA4D,QAAQ,KAC5D;CACR,MAAM,YAAY,SAAS,SAAS;CACpC,IAAI,cAAc,MAAM,cAAc,OAAO,cAAc,MACzD,MAAM,IAAI,MAAM,0CAA0C;CAC5D,OAAO,KAAK,KAAK,iBAAiB,WAAW,GAAG,gBAAgB,SAAS;AAC3E;;;;;;AAOA,SAAS,eAAe,MAAsB;CAE5C,MAAM,QAAQ,KAAK,QAAQ,8BAA8B,EAAE,CAAC,CAAC,QAAQ,SAAS,EAAE;CAChF,IAAI,SAAS;CACb,KAAK,MAAM,aAAa,OAAO;EAC7B,IAAI,OAAO,WAAW,SAAS,SAAS,IAAI,gBAAgB;EAC5D,UAAU;CACZ;CACA,OAAO,WAAW,KAAK,gBAAgB;AACzC;;AAGA,eAAe,aAAa,MAA6B;CACvD,MAAM,SAAS,KAAK,IAAI,IAAI;CAC5B,IAAI;CACJ,IAAI;EACF,WAAW,MAAM,GAAG,SAAS,QAAQ,MAAM,EAAE,eAAe,KAAK,CAAC;CACpE,QAAQ;EACN;CACF;CACA,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,CAAC,QAAQ,YAAY,GAAG;EAC5B,MAAM,mBAAmB,KAAK,KAAK,MAAM,QAAQ,IAAI;EACrD,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,GAAG,SAAS,QAAQ,kBAAkB,EAAE,eAAe,KAAK,CAAC;EAC/E,QAAQ;GACN;EACF;EACA,KAAK,MAAM,UAAU,SAAS;GAC5B,IAAI,CAAC,OAAO,YAAY,GAAG;GAC3B,MAAM,kBAAkB,KAAK,KAAK,kBAAkB,OAAO,IAAI;GAC/D,IAAI;IACF,KAAK,MAAM,GAAG,SAAS,MAAM,eAAe,EAAA,CAAG,UAAU,QACvD,MAAM,GAAG,SAAS,GAAG,iBAAiB;KAAE,WAAW;KAAM,OAAO;IAAK,CAAC;GAC1E,QAAQ,CAER;EACF;CACF;AACF;;AAGA,eAAsB,uBACpB,WACA,MACA,OACA,cAA4D,QAAQ,KACxC;CAC5B,MAAM,OAAO,sBAAsB,WAAW,WAAW;CACzD,MAAM,WAAW,eAAe,IAAI;CACpC,MAAM,GAAG,SAAS,MAAM,MAAM;EAAE,WAAW;EAAM,MAAM;CAAuB,CAAC;CAC/E,MAAM,aAAa,KAAK,QAAQ,IAAI,CAAC;CACrC,MAAM,YAAY,KAAK,KAAK,MAAM,WAAW,CAAC;CAC9C,MAAM,GAAG,SAAS,MAAM,WAAW,EAAE,MAAM,uBAAuB,CAAC;CACnE,MAAM,SAAS,KAAK,KAAK,WAAW,QAAQ;CAC5C,MAAM,YAAY,KAAK,KAAK,WAAW,IAAI,WAAW,EAAE,KAAK;CAC7D,IAAI;EACF,MAAM,GAAG,SAAS,UAAU,WAAW,OAAO;GAAE,MAAM;GAAmB,MAAM;EAAK,CAAC;EACrF,MAAM,GAAG,SAAS,OAAO,WAAW,MAAM;CAC5C,SAAS,OAAO;EACd,MAAM,GAAG,SAAS,GAAG,WAAW;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;EAChE,MAAM;CACR;CACA,OAAO;EACL,MAAM;EACN,MAAM;EACN,MAAM,MAAM;EACZ,UAAU,2BAA2B,KAAK,QAAQ,QAAQ,CAAC,CAAC,YAAY,MAAA;CAC1E;AACF"}

package/dist/src/services/sessionAttachments/type.d.mts

@@ -0,0 +1,9 @@
+//#region src/services/sessionAttachments/type.d.ts
+export interface SessionAttachment {
+  path: string;
+  name: string;
+  size: number;
+  mimeType: string;
+}
+//#endregion
+//# sourceMappingURL=type.d.mts.map

package/dist/src/services/sessionAttachments/type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.mts","names":[],"sources":["../../../../src/services/sessionAttachments/type.ts"],"mappings":";iBAAiB;EACf;EACA;EACA;EACA"}

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

@@ -0,0 +1,96 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+const require_core = require("../piSettings/core.cjs");
+const require_docs = require("../durableSession/docs.cjs");
+const require_sessionDirectory = require("./sessionDirectory.cjs");
+let node_crypto = require("node:crypto");
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let _earendil_works_pi_durable = require("@earendil-works/pi-durable");
+let dist_interop_chordContext_mjs = require("../../../../dist/interop/chordContext.mjs");
+//#region src/services/sessionFiles/index.ts
+const PO_SESSION_TEMP_DIR = "PO_SESSION_TEMP_DIR";
+const PO_SESSION_FILES_SERVICE = "po/session-files";
+/** A host-owned path, never a client-selected root or an inherited parent session path. */
+function sessionTempDirectory(options) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(options.sessionId)) throw new Error("Invalid temporary-file session identity.");
+	if (!node_path.default.isAbsolute(options.temporaryDirectory)) throw new Error("The host temporary directory must be absolute.");
+	const namespace = (0, node_crypto.createHash)("sha256").update(options.homeDirectory).update("\0").update(require_core.poHomeDirectory(options.homeDirectory, options.environment)).digest("hex").slice(0, 24);
+	return node_path.default.join(options.temporaryDirectory, `po-${namespace}`, "sessions", options.sessionId);
+}
+/** Both the execution host and package APIs call this with their admitted session identity. */
+async function prepareSessionEnvironment(input) {
+	const environment = { ...input.environment };
+	delete environment[PO_SESSION_TEMP_DIR];
+	if (input.platform.temporaryDirectory === void 0) return Object.freeze(environment);
+	const directory = sessionTempDirectory({
+		sessionId: input.sessionId,
+		homeDirectory: input.platform.homeDirectory,
+		environment,
+		temporaryDirectory: input.platform.temporaryDirectory
+	});
+	const preparedDirectory = await require_sessionDirectory.prepareSessionDirectory(input.platform, directory);
+	return Object.freeze({
+		...environment,
+		[PO_SESSION_TEMP_DIR]: preparedDirectory
+	});
+}
+function checkedDirectories(value, sessionId) {
+	if (!value || typeof value !== "object") throw new Error("Invalid saved session output directories.");
+	const files = value;
+	const absolute = (directory) => typeof directory === "string" && !directory.includes("\0") && node_path.default.isAbsolute(directory) && node_path.default.resolve(directory) === directory;
+	if (!absolute(files.agentDirectory)) throw new Error("Invalid saved session agent directory.");
+	if (files.temporaryDirectory !== void 0) {
+		const directory = files.temporaryDirectory;
+		if (!absolute(directory) || node_path.default.basename(directory) !== sessionId || node_path.default.basename(node_path.default.dirname(directory)) !== "sessions" || !/^po-[a-f0-9]{24}$/u.test(node_path.default.basename(node_path.default.dirname(node_path.default.dirname(directory))))) throw new Error("Invalid saved session temporary directory.");
+	}
+	return {
+		agentDirectory: files.agentDirectory,
+		...files.temporaryDirectory === void 0 ? {} : { temporaryDirectory: files.temporaryDirectory }
+	};
+}
+/** Narrow server-written output metadata, without exposing a session's environment or accepting request roots. */
+async function readSessionFileDirectories(sessions, sessionId) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(sessionId)) throw new Error("Invalid session output identity.");
+	const storage = await sessions.openReadOnly(sessionId, dist_interop_chordContext_mjs.BACKGROUND_CONTEXT);
+	const session = (0, _earendil_works_pi_durable.createSession)(storage);
+	try {
+		if ((await session.snapshot(require_docs.SessionIdentityDoc, dist_interop_chordContext_mjs.BACKGROUND_CONTEXT))?.id !== sessionId) throw new Error("Saved output does not belong to this session.");
+		const metadata = await session.snapshot(require_docs.SessionMetadataDoc, dist_interop_chordContext_mjs.BACKGROUND_CONTEXT);
+		if (!metadata?.execution) return void 0;
+		const execution = JSON.parse(metadata.execution);
+		if (!execution || typeof execution !== "object" || !("files" in execution) || execution.files === void 0) return void 0;
+		return checkedDirectories(execution.files, sessionId);
+	} finally {
+		await session.close(dist_interop_chordContext_mjs.BACKGROUND_CONTEXT);
+	}
+}
+/** Explicit session removal only. Ordinary close, release and host shutdown preserve output. */
+async function removeSessionFiles(input) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(input.sessionId) || node_path.default.basename(input.artifactDirectory) !== input.sessionId) throw new Error("Invalid session output cleanup identity.");
+	const directories = input.directories === void 0 ? void 0 : checkedDirectories(input.directories, input.sessionId);
+	const removals = [require_sessionDirectory.removeSessionOutputDirectory(input.platform, input.artifactDirectory)];
+	const temporaryDirectory = directories?.temporaryDirectory ?? (input.platform.temporaryDirectory === void 0 ? void 0 : sessionTempDirectory({
+		sessionId: input.sessionId,
+		homeDirectory: input.platform.homeDirectory,
+		environment: input.environment,
+		temporaryDirectory: input.platform.temporaryDirectory
+	}));
+	if (temporaryDirectory !== void 0) {
+		const originalBase = node_path.default.dirname(node_path.default.dirname(node_path.default.dirname(temporaryDirectory)));
+		removals.push(require_sessionDirectory.removeSessionDirectory({
+			...input.platform,
+			temporaryDirectory: originalBase
+		}, temporaryDirectory));
+	}
+	const failures = (await Promise.allSettled(removals)).filter((result) => result.status === "rejected").map((result) => result.reason);
+	if (failures.length > 0) throw new AggregateError(failures, `Session '${input.sessionId}' output cleanup failed`);
+}
+//#endregion
+exports.PO_SESSION_FILES_SERVICE = PO_SESSION_FILES_SERVICE;
+exports.PO_SESSION_TEMP_DIR = PO_SESSION_TEMP_DIR;
+exports.prepareSessionEnvironment = prepareSessionEnvironment;
+exports.readSessionFileDirectories = readSessionFileDirectories;
+exports.removeSessionFiles = removeSessionFiles;
+exports.sessionTempDirectory = sessionTempDirectory;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["path","createHash","poHomeDirectory","prepareSessionDirectory","BACKGROUND_CONTEXT","createSession","SessionIdentityDoc","SessionMetadataDoc","removeSessionOutputDirectory","removeSessionDirectory"],"sources":["../../../../src/services/sessionFiles/index.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport path from 'node:path';\n\nimport { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';\nimport { createSession } from '@earendil-works/pi-durable';\n\nimport type { PoPlatform, PoSessionStorageService } from '../../schemas/platform';\nimport { SessionIdentityDoc, SessionMetadataDoc } from '../durableSession/docs';\nimport { poHomeDirectory } from '../piSettings/core';\nimport { prepareSessionDirectory, removeSessionDirectory, removeSessionOutputDirectory } from './sessionDirectory';\n\nexport const PO_SESSION_TEMP_DIR = 'PO_SESSION_TEMP_DIR';\nexport const PO_SESSION_FILES_SERVICE = 'po/session-files';\n\nexport interface PoSessionFiles {\n  readonly temporaryDirectory: string;\n}\n\nexport interface SessionTempDirectoryOptions {\n  readonly sessionId: string;\n  readonly homeDirectory: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n  readonly temporaryDirectory: string;\n}\n\n/** A host-owned path, never a client-selected root or an inherited parent session path. */\nexport function sessionTempDirectory(options: SessionTempDirectoryOptions): string {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(options.sessionId)) throw new Error('Invalid temporary-file session identity.');\n  if (!path.isAbsolute(options.temporaryDirectory)) throw new Error('The host temporary directory must be absolute.');\n  const namespace = createHash('sha256')\n    .update(options.homeDirectory)\n    .update('\\0')\n    .update(poHomeDirectory(options.homeDirectory, options.environment))\n    .digest('hex')\n    .slice(0, 24);\n  return path.join(options.temporaryDirectory, `po-${namespace}`, 'sessions', options.sessionId);\n}\n\n/** Both the execution host and package APIs call this with their admitted session identity. */\nexport async function prepareSessionEnvironment(input: {\n  readonly platform: PoPlatform;\n  readonly sessionId: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n}): Promise<Readonly<Record<string, string | undefined>>> {\n  const environment = { ...input.environment };\n  // A child must never inherit its parent's browsable directory. Older embedders may lack this capability.\n  delete environment[PO_SESSION_TEMP_DIR];\n  if (input.platform.temporaryDirectory === undefined) return Object.freeze(environment);\n  const directory = sessionTempDirectory({\n    sessionId: input.sessionId,\n    homeDirectory: input.platform.homeDirectory,\n    environment,\n    temporaryDirectory: input.platform.temporaryDirectory,\n  });\n  // ponytail: resumption uses the same host temp base; pinning across host temp changes needs durable session metadata.\n  const preparedDirectory = await prepareSessionDirectory(input.platform, directory);\n  return Object.freeze({ ...environment, [PO_SESSION_TEMP_DIR]: preparedDirectory });\n}\n\nexport interface PoSessionFileDirectories {\n  readonly agentDirectory: string;\n  readonly temporaryDirectory?: string;\n}\n\nfunction checkedDirectories(value: unknown, sessionId: string): PoSessionFileDirectories {\n  if (!value || typeof value !== 'object') throw new Error('Invalid saved session output directories.');\n  const files = value as Record<string, unknown>;\n  const absolute = (directory: unknown): directory is string =>\n    typeof directory === 'string' &&\n    !directory.includes('\\0') &&\n    path.isAbsolute(directory) &&\n    path.resolve(directory) === directory;\n  if (!absolute(files.agentDirectory)) throw new Error('Invalid saved session agent directory.');\n  if (files.temporaryDirectory !== undefined) {\n    const directory = files.temporaryDirectory;\n    if (\n      !absolute(directory) ||\n      path.basename(directory) !== sessionId ||\n      path.basename(path.dirname(directory)) !== 'sessions' ||\n      !/^po-[a-f0-9]{24}$/u.test(path.basename(path.dirname(path.dirname(directory))))\n    )\n      throw new Error('Invalid saved session temporary directory.');\n  }\n  return {\n    agentDirectory: files.agentDirectory,\n    ...(files.temporaryDirectory === undefined ? {} : { temporaryDirectory: files.temporaryDirectory as string }),\n  };\n}\n\n/** Narrow server-written output metadata, without exposing a session's environment or accepting request roots. */\nexport async function readSessionFileDirectories(\n  sessions: PoSessionStorageService,\n  sessionId: string,\n): Promise<PoSessionFileDirectories | undefined> {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(sessionId)) throw new Error('Invalid session output identity.');\n  const storage = await sessions.openReadOnly(sessionId, BACKGROUND_CONTEXT);\n  const session = createSession(storage);\n  try {\n    const identity = await session.snapshot(SessionIdentityDoc, BACKGROUND_CONTEXT);\n    if (identity?.id !== sessionId) throw new Error('Saved output does not belong to this session.');\n    const metadata = await session.snapshot(SessionMetadataDoc, BACKGROUND_CONTEXT);\n    if (!metadata?.execution) return undefined;\n    const execution: unknown = JSON.parse(metadata.execution);\n    if (!execution || typeof execution !== 'object' || !('files' in execution) || execution.files === undefined)\n      return undefined;\n    return checkedDirectories(execution.files, sessionId);\n  } finally {\n    await session.close(BACKGROUND_CONTEXT);\n  }\n}\n\n/** Explicit session removal only. Ordinary close, release and host shutdown preserve output. */\nexport async function removeSessionFiles(input: {\n  readonly platform: PoPlatform;\n  readonly sessionId: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n  /** Exact session artifact directory selected by the composition root, never by a request. */\n  readonly artifactDirectory: string;\n  /** Previously stored roots, read by the host from the session's own durable metadata. */\n  readonly directories?: PoSessionFileDirectories;\n}): Promise<void> {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(input.sessionId) || path.basename(input.artifactDirectory) !== input.sessionId)\n    throw new Error('Invalid session output cleanup identity.');\n  const directories =\n    input.directories === undefined ? undefined : checkedDirectories(input.directories, input.sessionId);\n  const removals = [removeSessionOutputDirectory(input.platform, input.artifactDirectory)];\n  const temporaryDirectory =\n    directories?.temporaryDirectory ??\n    (input.platform.temporaryDirectory === undefined\n      ? undefined\n      : sessionTempDirectory({\n          sessionId: input.sessionId,\n          homeDirectory: input.platform.homeDirectory,\n          environment: input.environment,\n          temporaryDirectory: input.platform.temporaryDirectory,\n        }));\n  if (temporaryDirectory !== undefined) {\n    const originalBase = path.dirname(path.dirname(path.dirname(temporaryDirectory)));\n    removals.push(removeSessionDirectory({ ...input.platform, temporaryDirectory: originalBase }, temporaryDirectory));\n  }\n  const results = await Promise.allSettled(removals);\n  const failures = results\n    .filter((result): result is PromiseRejectedResult => result.status === 'rejected')\n    .map((result) => result.reason);\n  if (failures.length > 0) throw new AggregateError(failures, `Session '${input.sessionId}' output cleanup failed`);\n}\n"],"mappings":";;;;;;;;;;AAWA,MAAa,sBAAsB;AACnC,MAAa,2BAA2B;;AAcxC,SAAgB,qBAAqB,SAA8C;CACjF,IAAI,CAAC,oBAAoB,KAAK,QAAQ,SAAS,GAAG,MAAM,IAAI,MAAM,0CAA0C;CAC5G,IAAI,CAACA,UAAAA,QAAK,WAAW,QAAQ,kBAAkB,GAAG,MAAM,IAAI,MAAM,gDAAgD;CAClH,MAAM,aAAA,GAAYC,YAAAA,WAAAA,CAAW,QAAQ,CAAC,CACnC,OAAO,QAAQ,aAAa,CAAC,CAC7B,OAAO,IAAI,CAAC,CACZ,OAAOC,aAAAA,gBAAgB,QAAQ,eAAe,QAAQ,WAAW,CAAC,CAAC,CACnE,OAAO,KAAK,CAAC,CACb,MAAM,GAAG,EAAE;CACd,OAAOF,UAAAA,QAAK,KAAK,QAAQ,oBAAoB,MAAM,aAAa,YAAY,QAAQ,SAAS;AAC/F;;AAGA,eAAsB,0BAA0B,OAIU;CACxD,MAAM,cAAc,EAAE,GAAG,MAAM,YAAY;CAE3C,OAAO,YAAY;CACnB,IAAI,MAAM,SAAS,uBAAuB,KAAA,GAAW,OAAO,OAAO,OAAO,WAAW;CACrF,MAAM,YAAY,qBAAqB;EACrC,WAAW,MAAM;EACjB,eAAe,MAAM,SAAS;EAC9B;EACA,oBAAoB,MAAM,SAAS;CACrC,CAAC;CAED,MAAM,oBAAoB,MAAMG,yBAAAA,wBAAwB,MAAM,UAAU,SAAS;CACjF,OAAO,OAAO,OAAO;EAAE,GAAG;GAAc,sBAAsB;CAAkB,CAAC;AACnF;AAOA,SAAS,mBAAmB,OAAgB,WAA6C;CACvF,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU,MAAM,IAAI,MAAM,2CAA2C;CACpG,MAAM,QAAQ;CACd,MAAM,YAAY,cAChB,OAAO,cAAc,YACrB,CAAC,UAAU,SAAS,IAAI,KACxBH,UAAAA,QAAK,WAAW,SAAS,KACzBA,UAAAA,QAAK,QAAQ,SAAS,MAAM;CAC9B,IAAI,CAAC,SAAS,MAAM,cAAc,GAAG,MAAM,IAAI,MAAM,wCAAwC;CAC7F,IAAI,MAAM,uBAAuB,KAAA,GAAW;EAC1C,MAAM,YAAY,MAAM;EACxB,IACE,CAAC,SAAS,SAAS,KACnBA,UAAAA,QAAK,SAAS,SAAS,MAAM,aAC7BA,UAAAA,QAAK,SAASA,UAAAA,QAAK,QAAQ,SAAS,CAAC,MAAM,cAC3C,CAAC,qBAAqB,KAAKA,UAAAA,QAAK,SAASA,UAAAA,QAAK,QAAQA,UAAAA,QAAK,QAAQ,SAAS,CAAC,CAAC,CAAC,GAE/E,MAAM,IAAI,MAAM,4CAA4C;CAChE;CACA,OAAO;EACL,gBAAgB,MAAM;EACtB,GAAI,MAAM,uBAAuB,KAAA,IAAY,CAAC,IAAI,EAAE,oBAAoB,MAAM,mBAA6B;CAC7G;AACF;;AAGA,eAAsB,2BACpB,UACA,WAC+C;CAC/C,IAAI,CAAC,oBAAoB,KAAK,SAAS,GAAG,MAAM,IAAI,MAAM,kCAAkC;CAC5F,MAAM,UAAU,MAAM,SAAS,aAAa,WAAWI,8BAAAA,kBAAkB;CACzE,MAAM,WAAA,GAAUC,2BAAAA,cAAAA,CAAc,OAAO;CACrC,IAAI;EAEF,KAAI,MADmB,QAAQ,SAASC,aAAAA,oBAAoBF,8BAAAA,kBAAkB,EAAA,EAChE,OAAO,WAAW,MAAM,IAAI,MAAM,+CAA+C;EAC/F,MAAM,WAAW,MAAM,QAAQ,SAASG,aAAAA,oBAAoBH,8BAAAA,kBAAkB;EAC9E,IAAI,CAAC,UAAU,WAAW,OAAO,KAAA;EACjC,MAAM,YAAqB,KAAK,MAAM,SAAS,SAAS;EACxD,IAAI,CAAC,aAAa,OAAO,cAAc,YAAY,EAAE,WAAW,cAAc,UAAU,UAAU,KAAA,GAChG,OAAO,KAAA;EACT,OAAO,mBAAmB,UAAU,OAAO,SAAS;CACtD,UAAU;EACR,MAAM,QAAQ,MAAMA,8BAAAA,kBAAkB;CACxC;AACF;;AAGA,eAAsB,mBAAmB,OAQvB;CAChB,IAAI,CAAC,oBAAoB,KAAK,MAAM,SAAS,KAAKJ,UAAAA,QAAK,SAAS,MAAM,iBAAiB,MAAM,MAAM,WACjG,MAAM,IAAI,MAAM,0CAA0C;CAC5D,MAAM,cACJ,MAAM,gBAAgB,KAAA,IAAY,KAAA,IAAY,mBAAmB,MAAM,aAAa,MAAM,SAAS;CACrG,MAAM,WAAW,CAACQ,yBAAAA,6BAA6B,MAAM,UAAU,MAAM,iBAAiB,CAAC;CACvF,MAAM,qBACJ,aAAa,uBACZ,MAAM,SAAS,uBAAuB,KAAA,IACnC,KAAA,IACA,qBAAqB;EACnB,WAAW,MAAM;EACjB,eAAe,MAAM,SAAS;EAC9B,aAAa,MAAM;EACnB,oBAAoB,MAAM,SAAS;CACrC,CAAC;CACP,IAAI,uBAAuB,KAAA,GAAW;EACpC,MAAM,eAAeR,UAAAA,QAAK,QAAQA,UAAAA,QAAK,QAAQA,UAAAA,QAAK,QAAQ,kBAAkB,CAAC,CAAC;EAChF,SAAS,KAAKS,yBAAAA,uBAAuB;GAAE,GAAG,MAAM;GAAU,oBAAoB;EAAa,GAAG,kBAAkB,CAAC;CACnH;CAEA,MAAM,YAAW,MADK,QAAQ,WAAW,QAAQ,EAAA,CAE9C,QAAQ,WAA4C,OAAO,WAAW,UAAU,CAAC,CACjF,KAAK,WAAW,OAAO,MAAM;CAChC,IAAI,SAAS,SAAS,GAAG,MAAM,IAAI,eAAe,UAAU,YAAY,MAAM,UAAU,wBAAwB;AAClH"}

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

@@ -0,0 +1,33 @@
+import { PoPlatform, PoSessionStorageService } from "../../schemas/platform.mjs";
+//#region src/services/sessionFiles/index.d.ts
+export declare const PO_SESSION_TEMP_DIR = "PO_SESSION_TEMP_DIR";
+export declare const PO_SESSION_FILES_SERVICE = "po/session-files";
+export interface PoSessionFiles {
+  readonly temporaryDirectory: string;
+}
+export interface SessionTempDirectoryOptions {
+  readonly sessionId: string;
+  readonly homeDirectory: string;
+  readonly environment: Readonly<Record<string, string | undefined>>;
+  readonly temporaryDirectory: string;
+}
+/** A host-owned path, never a client-selected root or an inherited parent session path. */
+export declare function sessionTempDirectory(options: SessionTempDirectoryOptions): string;
+export interface PoSessionFileDirectories {
+  readonly agentDirectory: string;
+  readonly temporaryDirectory?: string;
+}
+/** Narrow server-written output metadata, without exposing a session's environment or accepting request roots. */
+export declare function readSessionFileDirectories(sessions: PoSessionStorageService, sessionId: string): Promise<PoSessionFileDirectories | undefined>;
+/** Explicit session removal only. Ordinary close, release and host shutdown preserve output. */
+export declare function removeSessionFiles(input: {
+  readonly platform: PoPlatform;
+  readonly sessionId: string;
+  readonly environment: Readonly<Record<string, string | undefined>>;
+  /** Exact session artifact directory selected by the composition root, never by a request. */
+  readonly artifactDirectory: string;
+  /** Previously stored roots, read by the host from the session's own durable metadata. */
+  readonly directories?: PoSessionFileDirectories;
+}): Promise<void>;
+//#endregion
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../src/services/sessionFiles/index.ts"],"mappings":";;qBAWa;qBACA;iBAEI;WACN;;iBAGM;WACN;WACA;WACA,aAAa,SAAS;WACtB;;;wBAIK,qBAAqB,SAAS;iBAiC7B;WACN;WACA;;;wBA6BW,2BACpB,UAAU,yBACV,oBACC,QAAQ;;wBAmBW,mBAAmB;WAC9B,UAAU;WACV;WACA,aAAa,SAAS;;WAEtB;;WAEA,cAAc;IACrB"}

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

@@ -0,0 +1,89 @@
+import { poHomeDirectory } from "../piSettings/core.mjs";
+import { SessionIdentityDoc, SessionMetadataDoc } from "../durableSession/docs.mjs";
+import { prepareSessionDirectory, removeSessionDirectory, removeSessionOutputDirectory } from "./sessionDirectory.mjs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { createSession } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+//#region src/services/sessionFiles/index.ts
+const PO_SESSION_TEMP_DIR = "PO_SESSION_TEMP_DIR";
+const PO_SESSION_FILES_SERVICE = "po/session-files";
+/** A host-owned path, never a client-selected root or an inherited parent session path. */
+function sessionTempDirectory(options) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(options.sessionId)) throw new Error("Invalid temporary-file session identity.");
+	if (!path.isAbsolute(options.temporaryDirectory)) throw new Error("The host temporary directory must be absolute.");
+	const namespace = createHash("sha256").update(options.homeDirectory).update("\0").update(poHomeDirectory(options.homeDirectory, options.environment)).digest("hex").slice(0, 24);
+	return path.join(options.temporaryDirectory, `po-${namespace}`, "sessions", options.sessionId);
+}
+/** Both the execution host and package APIs call this with their admitted session identity. */
+async function prepareSessionEnvironment(input) {
+	const environment = { ...input.environment };
+	delete environment[PO_SESSION_TEMP_DIR];
+	if (input.platform.temporaryDirectory === void 0) return Object.freeze(environment);
+	const directory = sessionTempDirectory({
+		sessionId: input.sessionId,
+		homeDirectory: input.platform.homeDirectory,
+		environment,
+		temporaryDirectory: input.platform.temporaryDirectory
+	});
+	const preparedDirectory = await prepareSessionDirectory(input.platform, directory);
+	return Object.freeze({
+		...environment,
+		[PO_SESSION_TEMP_DIR]: preparedDirectory
+	});
+}
+function checkedDirectories(value, sessionId) {
+	if (!value || typeof value !== "object") throw new Error("Invalid saved session output directories.");
+	const files = value;
+	const absolute = (directory) => typeof directory === "string" && !directory.includes("\0") && path.isAbsolute(directory) && path.resolve(directory) === directory;
+	if (!absolute(files.agentDirectory)) throw new Error("Invalid saved session agent directory.");
+	if (files.temporaryDirectory !== void 0) {
+		const directory = files.temporaryDirectory;
+		if (!absolute(directory) || path.basename(directory) !== sessionId || path.basename(path.dirname(directory)) !== "sessions" || !/^po-[a-f0-9]{24}$/u.test(path.basename(path.dirname(path.dirname(directory))))) throw new Error("Invalid saved session temporary directory.");
+	}
+	return {
+		agentDirectory: files.agentDirectory,
+		...files.temporaryDirectory === void 0 ? {} : { temporaryDirectory: files.temporaryDirectory }
+	};
+}
+/** Narrow server-written output metadata, without exposing a session's environment or accepting request roots. */
+async function readSessionFileDirectories(sessions, sessionId) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(sessionId)) throw new Error("Invalid session output identity.");
+	const storage = await sessions.openReadOnly(sessionId, BACKGROUND_CONTEXT);
+	const session = createSession(storage);
+	try {
+		if ((await session.snapshot(SessionIdentityDoc, BACKGROUND_CONTEXT))?.id !== sessionId) throw new Error("Saved output does not belong to this session.");
+		const metadata = await session.snapshot(SessionMetadataDoc, BACKGROUND_CONTEXT);
+		if (!metadata?.execution) return void 0;
+		const execution = JSON.parse(metadata.execution);
+		if (!execution || typeof execution !== "object" || !("files" in execution) || execution.files === void 0) return void 0;
+		return checkedDirectories(execution.files, sessionId);
+	} finally {
+		await session.close(BACKGROUND_CONTEXT);
+	}
+}
+/** Explicit session removal only. Ordinary close, release and host shutdown preserve output. */
+async function removeSessionFiles(input) {
+	if (!/^[a-zA-Z0-9_-]+$/u.test(input.sessionId) || path.basename(input.artifactDirectory) !== input.sessionId) throw new Error("Invalid session output cleanup identity.");
+	const directories = input.directories === void 0 ? void 0 : checkedDirectories(input.directories, input.sessionId);
+	const removals = [removeSessionOutputDirectory(input.platform, input.artifactDirectory)];
+	const temporaryDirectory = directories?.temporaryDirectory ?? (input.platform.temporaryDirectory === void 0 ? void 0 : sessionTempDirectory({
+		sessionId: input.sessionId,
+		homeDirectory: input.platform.homeDirectory,
+		environment: input.environment,
+		temporaryDirectory: input.platform.temporaryDirectory
+	}));
+	if (temporaryDirectory !== void 0) {
+		const originalBase = path.dirname(path.dirname(path.dirname(temporaryDirectory)));
+		removals.push(removeSessionDirectory({
+			...input.platform,
+			temporaryDirectory: originalBase
+		}, temporaryDirectory));
+	}
+	const failures = (await Promise.allSettled(removals)).filter((result) => result.status === "rejected").map((result) => result.reason);
+	if (failures.length > 0) throw new AggregateError(failures, `Session '${input.sessionId}' output cleanup failed`);
+}
+//#endregion
+export { PO_SESSION_FILES_SERVICE, PO_SESSION_TEMP_DIR, prepareSessionEnvironment, readSessionFileDirectories, removeSessionFiles, sessionTempDirectory };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/sessionFiles/index.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\nimport path from 'node:path';\n\nimport { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';\nimport { createSession } from '@earendil-works/pi-durable';\n\nimport type { PoPlatform, PoSessionStorageService } from '../../schemas/platform';\nimport { SessionIdentityDoc, SessionMetadataDoc } from '../durableSession/docs';\nimport { poHomeDirectory } from '../piSettings/core';\nimport { prepareSessionDirectory, removeSessionDirectory, removeSessionOutputDirectory } from './sessionDirectory';\n\nexport const PO_SESSION_TEMP_DIR = 'PO_SESSION_TEMP_DIR';\nexport const PO_SESSION_FILES_SERVICE = 'po/session-files';\n\nexport interface PoSessionFiles {\n  readonly temporaryDirectory: string;\n}\n\nexport interface SessionTempDirectoryOptions {\n  readonly sessionId: string;\n  readonly homeDirectory: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n  readonly temporaryDirectory: string;\n}\n\n/** A host-owned path, never a client-selected root or an inherited parent session path. */\nexport function sessionTempDirectory(options: SessionTempDirectoryOptions): string {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(options.sessionId)) throw new Error('Invalid temporary-file session identity.');\n  if (!path.isAbsolute(options.temporaryDirectory)) throw new Error('The host temporary directory must be absolute.');\n  const namespace = createHash('sha256')\n    .update(options.homeDirectory)\n    .update('\\0')\n    .update(poHomeDirectory(options.homeDirectory, options.environment))\n    .digest('hex')\n    .slice(0, 24);\n  return path.join(options.temporaryDirectory, `po-${namespace}`, 'sessions', options.sessionId);\n}\n\n/** Both the execution host and package APIs call this with their admitted session identity. */\nexport async function prepareSessionEnvironment(input: {\n  readonly platform: PoPlatform;\n  readonly sessionId: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n}): Promise<Readonly<Record<string, string | undefined>>> {\n  const environment = { ...input.environment };\n  // A child must never inherit its parent's browsable directory. Older embedders may lack this capability.\n  delete environment[PO_SESSION_TEMP_DIR];\n  if (input.platform.temporaryDirectory === undefined) return Object.freeze(environment);\n  const directory = sessionTempDirectory({\n    sessionId: input.sessionId,\n    homeDirectory: input.platform.homeDirectory,\n    environment,\n    temporaryDirectory: input.platform.temporaryDirectory,\n  });\n  // ponytail: resumption uses the same host temp base; pinning across host temp changes needs durable session metadata.\n  const preparedDirectory = await prepareSessionDirectory(input.platform, directory);\n  return Object.freeze({ ...environment, [PO_SESSION_TEMP_DIR]: preparedDirectory });\n}\n\nexport interface PoSessionFileDirectories {\n  readonly agentDirectory: string;\n  readonly temporaryDirectory?: string;\n}\n\nfunction checkedDirectories(value: unknown, sessionId: string): PoSessionFileDirectories {\n  if (!value || typeof value !== 'object') throw new Error('Invalid saved session output directories.');\n  const files = value as Record<string, unknown>;\n  const absolute = (directory: unknown): directory is string =>\n    typeof directory === 'string' &&\n    !directory.includes('\\0') &&\n    path.isAbsolute(directory) &&\n    path.resolve(directory) === directory;\n  if (!absolute(files.agentDirectory)) throw new Error('Invalid saved session agent directory.');\n  if (files.temporaryDirectory !== undefined) {\n    const directory = files.temporaryDirectory;\n    if (\n      !absolute(directory) ||\n      path.basename(directory) !== sessionId ||\n      path.basename(path.dirname(directory)) !== 'sessions' ||\n      !/^po-[a-f0-9]{24}$/u.test(path.basename(path.dirname(path.dirname(directory))))\n    )\n      throw new Error('Invalid saved session temporary directory.');\n  }\n  return {\n    agentDirectory: files.agentDirectory,\n    ...(files.temporaryDirectory === undefined ? {} : { temporaryDirectory: files.temporaryDirectory as string }),\n  };\n}\n\n/** Narrow server-written output metadata, without exposing a session's environment or accepting request roots. */\nexport async function readSessionFileDirectories(\n  sessions: PoSessionStorageService,\n  sessionId: string,\n): Promise<PoSessionFileDirectories | undefined> {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(sessionId)) throw new Error('Invalid session output identity.');\n  const storage = await sessions.openReadOnly(sessionId, BACKGROUND_CONTEXT);\n  const session = createSession(storage);\n  try {\n    const identity = await session.snapshot(SessionIdentityDoc, BACKGROUND_CONTEXT);\n    if (identity?.id !== sessionId) throw new Error('Saved output does not belong to this session.');\n    const metadata = await session.snapshot(SessionMetadataDoc, BACKGROUND_CONTEXT);\n    if (!metadata?.execution) return undefined;\n    const execution: unknown = JSON.parse(metadata.execution);\n    if (!execution || typeof execution !== 'object' || !('files' in execution) || execution.files === undefined)\n      return undefined;\n    return checkedDirectories(execution.files, sessionId);\n  } finally {\n    await session.close(BACKGROUND_CONTEXT);\n  }\n}\n\n/** Explicit session removal only. Ordinary close, release and host shutdown preserve output. */\nexport async function removeSessionFiles(input: {\n  readonly platform: PoPlatform;\n  readonly sessionId: string;\n  readonly environment: Readonly<Record<string, string | undefined>>;\n  /** Exact session artifact directory selected by the composition root, never by a request. */\n  readonly artifactDirectory: string;\n  /** Previously stored roots, read by the host from the session's own durable metadata. */\n  readonly directories?: PoSessionFileDirectories;\n}): Promise<void> {\n  if (!/^[a-zA-Z0-9_-]+$/u.test(input.sessionId) || path.basename(input.artifactDirectory) !== input.sessionId)\n    throw new Error('Invalid session output cleanup identity.');\n  const directories =\n    input.directories === undefined ? undefined : checkedDirectories(input.directories, input.sessionId);\n  const removals = [removeSessionOutputDirectory(input.platform, input.artifactDirectory)];\n  const temporaryDirectory =\n    directories?.temporaryDirectory ??\n    (input.platform.temporaryDirectory === undefined\n      ? undefined\n      : sessionTempDirectory({\n          sessionId: input.sessionId,\n          homeDirectory: input.platform.homeDirectory,\n          environment: input.environment,\n          temporaryDirectory: input.platform.temporaryDirectory,\n        }));\n  if (temporaryDirectory !== undefined) {\n    const originalBase = path.dirname(path.dirname(path.dirname(temporaryDirectory)));\n    removals.push(removeSessionDirectory({ ...input.platform, temporaryDirectory: originalBase }, temporaryDirectory));\n  }\n  const results = await Promise.allSettled(removals);\n  const failures = results\n    .filter((result): result is PromiseRejectedResult => result.status === 'rejected')\n    .map((result) => result.reason);\n  if (failures.length > 0) throw new AggregateError(failures, `Session '${input.sessionId}' output cleanup failed`);\n}\n"],"mappings":"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"}

package/dist/src/services/sessionFiles/sessionDirectory.cjs

@@ -0,0 +1,66 @@
+const require_runtime = require("../../../_virtual/_rolldown/runtime.cjs");
+let node_os = require("node:os");
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+//#region src/services/sessionFiles/sessionDirectory.ts
+/** Validate every Po-owned ancestor. OS temp itself may be shared. */
+async function checkedSessionDirectory(platform, directory, create) {
+	const base = await (0, node_fs_promises.realpath)(platform.temporaryDirectory);
+	const relative = node_path.default.relative(platform.temporaryDirectory, directory);
+	if (!relative || relative.startsWith("..") || node_path.default.isAbsolute(relative)) throw new Error("Unsafe session temp root.");
+	let current = base;
+	const uid = (0, node_os.userInfo)().uid;
+	for (const segment of relative.split(node_path.default.sep)) {
+		current = node_path.default.join(current, segment);
+		if (create) try {
+			await (0, node_fs_promises.mkdir)(current, { mode: 448 });
+		} catch (error) {
+			if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+		}
+		const info = await (0, node_fs_promises.lstat)(current);
+		if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid || (info.mode & 63) !== 0) throw new Error("Unsafe session temporary directory.");
+		if (await (0, node_fs_promises.realpath)(current) !== current) throw new Error("Session temporary directory changed during access.");
+	}
+	return current;
+}
+async function prepareSessionDirectory(platform, directory) {
+	return checkedSessionDirectory(platform, directory, true);
+}
+/** Remove only an existing session temp tree, never creating missing cleanup targets. */
+async function removeSessionDirectory(platform, directory) {
+	try {
+		const checked = await checkedSessionDirectory(platform, directory, false);
+		await (0, node_fs_promises.rm)(checked, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+	}
+}
+/** Persistent output roots may contain symlinks as files, but the owned root and parent must not redirect removal. */
+async function removeSessionOutputDirectory(_platform, directory) {
+	try {
+		const parent = node_path.default.dirname(directory);
+		for (const target of [parent, directory]) {
+			const info = await (0, node_fs_promises.lstat)(target);
+			if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe session output cleanup target.");
+		}
+		const realParent = await (0, node_fs_promises.realpath)(parent);
+		const realDirectory = await (0, node_fs_promises.realpath)(directory);
+		if (realDirectory !== node_path.default.join(realParent, node_path.default.basename(directory))) throw new Error("Session output cleanup target changed during access.");
+		await (0, node_fs_promises.rm)(realDirectory, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+	}
+}
+//#endregion
+exports.prepareSessionDirectory = prepareSessionDirectory;
+exports.removeSessionDirectory = removeSessionDirectory;
+exports.removeSessionOutputDirectory = removeSessionOutputDirectory;
+
+//# sourceMappingURL=sessionDirectory.cjs.map

package/dist/src/services/sessionFiles/sessionDirectory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionDirectory.cjs","names":["realpath","path","userInfo","mkdir","lstat","rm"],"sources":["../../../../src/services/sessionFiles/sessionDirectory.ts"],"sourcesContent":["import { lstat, mkdir, realpath, rm } from 'node:fs/promises';\nimport { userInfo } from 'node:os';\nimport path from 'node:path';\n\nimport type { PoPlatform } from '../../schemas/platform';\n\n/** Validate every Po-owned ancestor. OS temp itself may be shared. */\nasync function checkedSessionDirectory(platform: PoPlatform, directory: string, create: boolean): Promise<string> {\n  const base = await realpath(platform.temporaryDirectory!);\n  const relative = path.relative(platform.temporaryDirectory!, directory);\n  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Unsafe session temp root.');\n  let current = base;\n  const uid = userInfo().uid;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    if (create) {\n      try {\n        await mkdir(current, { mode: 0o700 });\n      } catch (error) {\n        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) throw error;\n      }\n    }\n    const info = await lstat(current);\n    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid || (info.mode & 0o077) !== 0)\n      throw new Error('Unsafe session temporary directory.');\n    if ((await realpath(current)) !== current) throw new Error('Session temporary directory changed during access.');\n  }\n  return current;\n}\n\nexport async function prepareSessionDirectory(platform: PoPlatform, directory: string): Promise<string> {\n  return checkedSessionDirectory(platform, directory, true);\n}\n\n/** Remove only an existing session temp tree, never creating missing cleanup targets. */\nexport async function removeSessionDirectory(platform: PoPlatform, directory: string): Promise<void> {\n  try {\n    const checked = await checkedSessionDirectory(platform, directory, false);\n    await rm(checked, { recursive: true, force: true });\n  } catch (error) {\n    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;\n  }\n}\n\n/** Persistent output roots may contain symlinks as files, but the owned root and parent must not redirect removal. */\nexport async function removeSessionOutputDirectory(_platform: PoPlatform, directory: string): Promise<void> {\n  try {\n    const parent = path.dirname(directory);\n    for (const target of [parent, directory]) {\n      const info = await lstat(target);\n      if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Unsafe session output cleanup target.');\n    }\n    const realParent = await realpath(parent);\n    const realDirectory = await realpath(directory);\n    if (realDirectory !== path.join(realParent, path.basename(directory)))\n      throw new Error('Session output cleanup target changed during access.');\n    await rm(realDirectory, { recursive: true, force: true });\n  } catch (error) {\n    if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error;\n  }\n}\n"],"mappings":";;;;;;;AAOA,eAAe,wBAAwB,UAAsB,WAAmB,QAAkC;CAChH,MAAM,OAAO,OAAA,GAAMA,iBAAAA,SAAAA,CAAS,SAAS,kBAAmB;CACxD,MAAM,WAAWC,UAAAA,QAAK,SAAS,SAAS,oBAAqB,SAAS;CACtE,IAAI,CAAC,YAAY,SAAS,WAAW,IAAI,KAAKA,UAAAA,QAAK,WAAW,QAAQ,GAAG,MAAM,IAAI,MAAM,2BAA2B;CACpH,IAAI,UAAU;CACd,MAAM,OAAA,GAAMC,QAAAA,SAAAA,CAAS,CAAC,CAAC;CACvB,KAAK,MAAM,WAAW,SAAS,MAAMD,UAAAA,QAAK,GAAG,GAAG;EAC9C,UAAUA,UAAAA,QAAK,KAAK,SAAS,OAAO;EACpC,IAAI,QACF,IAAI;GACF,OAAA,GAAME,iBAAAA,MAAAA,CAAM,SAAS,EAAE,MAAM,IAAM,CAAC;EACtC,SAAS,OAAO;GACd,IAAI,EAAE,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,WAAW,MAAM;EACrF;EAEF,MAAM,OAAO,OAAA,GAAMC,iBAAAA,MAAAA,CAAM,OAAO;EAChC,IAAI,CAAC,KAAK,YAAY,KAAK,KAAK,eAAe,KAAK,KAAK,QAAQ,QAAQ,KAAK,OAAO,QAAW,GAC9F,MAAM,IAAI,MAAM,qCAAqC;EACvD,IAAK,OAAA,GAAMJ,iBAAAA,SAAAA,CAAS,OAAO,MAAO,SAAS,MAAM,IAAI,MAAM,oDAAoD;CACjH;CACA,OAAO;AACT;AAEA,eAAsB,wBAAwB,UAAsB,WAAoC;CACtG,OAAO,wBAAwB,UAAU,WAAW,IAAI;AAC1D;;AAGA,eAAsB,uBAAuB,UAAsB,WAAkC;CACnG,IAAI;EACF,MAAM,UAAU,MAAM,wBAAwB,UAAU,WAAW,KAAK;EACxE,OAAA,GAAMK,iBAAAA,GAAAA,CAAG,SAAS;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;CACpD,SAAS,OAAO;EACd,IAAI,EAAE,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,WAAW,MAAM;CACrF;AACF;;AAGA,eAAsB,6BAA6B,WAAuB,WAAkC;CAC1G,IAAI;EACF,MAAM,SAASJ,UAAAA,QAAK,QAAQ,SAAS;EACrC,KAAK,MAAM,UAAU,CAAC,QAAQ,SAAS,GAAG;GACxC,MAAM,OAAO,OAAA,GAAMG,iBAAAA,MAAAA,CAAM,MAAM;GAC/B,IAAI,CAAC,KAAK,YAAY,KAAK,KAAK,eAAe,GAAG,MAAM,IAAI,MAAM,uCAAuC;EAC3G;EACA,MAAM,aAAa,OAAA,GAAMJ,iBAAAA,SAAAA,CAAS,MAAM;EACxC,MAAM,gBAAgB,OAAA,GAAMA,iBAAAA,SAAAA,CAAS,SAAS;EAC9C,IAAI,kBAAkBC,UAAAA,QAAK,KAAK,YAAYA,UAAAA,QAAK,SAAS,SAAS,CAAC,GAClE,MAAM,IAAI,MAAM,sDAAsD;EACxE,OAAA,GAAMI,iBAAAA,GAAAA,CAAG,eAAe;GAAE,WAAW;GAAM,OAAO;EAAK,CAAC;CAC1D,SAAS,OAAO;EACd,IAAI,EAAE,iBAAiB,SAAS,UAAU,SAAS,MAAM,SAAS,WAAW,MAAM;CACrF;AACF"}