@byfriends/agent-core 0.1.0

package/dist/store-DhTph1cB.mjs

@@ -0,0 +1,813 @@
+import { createHash } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { APIConnectionError, APIStatusError, APITimeoutError, ChatProviderError } from "@byfriends/kosong";
+import { appendFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { z } from "zod";
+//#region src/errors/codes.ts
+/**
+* Error codes for Byf Core's public error protocol.
+*
+* `ErrorCodes` is the source of truth for every code Byf Core may emit.
+* Downstream consumers (SDK, RPC clients, telemetry, agent-facing docs)
+* should depend on these string values rather than on class identity.
+*
+* Codes follow `domain.reason`. Adding a code is a minor change; renaming
+* or removing one is a major change.
+*/
+const ErrorCodes = {
+	CONFIG_INVALID: "config.invalid",
+	SESSION_NOT_FOUND: "session.not_found",
+	SESSION_ALREADY_EXISTS: "session.already_exists",
+	SESSION_ID_INVALID: "session.id_invalid",
+	SESSION_ID_REQUIRED: "session.id_required",
+	SESSION_ID_EMPTY: "session.id_empty",
+	SESSION_TITLE_EMPTY: "session.title_empty",
+	SESSION_STATE_NOT_FOUND: "session.state_not_found",
+	SESSION_STATE_INVALID: "session.state_invalid",
+	SESSION_FORK_ACTIVE_TURN: "session.fork_active_turn",
+	SESSION_EXPORT_NOT_FOUND: "session.export_not_found",
+	SESSION_EXPORT_MISSING_VERSION: "session.export_missing_version",
+	SESSION_CLOSED: "session.closed",
+	SESSION_PERMISSION_MODE_INVALID: "session.permission_mode_invalid",
+	SESSION_THINKING_EMPTY: "session.thinking_empty",
+	SESSION_MODEL_EMPTY: "session.model_empty",
+	SESSION_PLAN_MODE_INVALID: "session.plan_mode_invalid",
+	SESSION_APPROVAL_HANDLER_ERROR: "session.approval_handler_error",
+	SESSION_QUESTION_HANDLER_ERROR: "session.question_handler_error",
+	SESSION_INIT_FAILED: "session.init_failed",
+	AGENT_NOT_FOUND: "agent.not_found",
+	TURN_AGENT_BUSY: "turn.agent_busy",
+	MODEL_NOT_CONFIGURED: "model.not_configured",
+	MODEL_CONFIG_INVALID: "model.config_invalid",
+	AUTH_LOGIN_REQUIRED: "auth.login_required",
+	CONTEXT_OVERFLOW: "context.overflow",
+	LOOP_MAX_STEPS_EXCEEDED: "loop.max_steps_exceeded",
+	PROVIDER_API_ERROR: "provider.api_error",
+	PROVIDER_RATE_LIMIT: "provider.rate_limit",
+	PROVIDER_AUTH_ERROR: "provider.auth_error",
+	PROVIDER_CONNECTION_ERROR: "provider.connection_error",
+	SKILL_NOT_FOUND: "skill.not_found",
+	SKILL_TYPE_UNSUPPORTED: "skill.type_unsupported",
+	SKILL_NAME_EMPTY: "skill.name_empty",
+	RECORDS_WRITE_FAILED: "records.write_failed",
+	COMPACTION_FAILED: "compaction.failed",
+	BACKGROUND_TASK_ID_EMPTY: "background.task_id_empty",
+	MCP_SERVER_NOT_FOUND: "mcp.server_not_found",
+	MCP_SERVER_DISABLED: "mcp.server_disabled",
+	MCP_STARTUP_FAILED: "mcp.startup_failed",
+	MCP_TOOL_NAME_COLLISION: "mcp.tool_name_collision",
+	REQUEST_INVALID: "request.invalid",
+	REQUEST_WORK_DIR_REQUIRED: "request.work_dir_required",
+	REQUEST_PROMPT_INPUT_EMPTY: "request.prompt_input_empty",
+	SHELL_GIT_BASH_NOT_FOUND: "shell.git_bash_not_found",
+	NOT_IMPLEMENTED: "not_implemented",
+	INTERNAL: "internal"
+};
+const BYF_ERROR_INFO = {
+	"config.invalid": {
+		title: "Invalid configuration",
+		retryable: false,
+		public: true,
+		action: "Check config.toml and provider/model settings."
+	},
+	"session.not_found": {
+		title: "Session not found",
+		retryable: false,
+		public: true,
+		action: "Check the session id or list available sessions."
+	},
+	"session.already_exists": {
+		title: "Session already exists",
+		retryable: false,
+		public: true,
+		action: "Use a different session id or remove the existing session first."
+	},
+	"session.id_invalid": {
+		title: "Invalid session id",
+		retryable: false,
+		public: true,
+		action: "Use a session id without path-traversal characters."
+	},
+	"session.id_required": {
+		title: "Session id required",
+		retryable: false,
+		public: true,
+		action: "Provide a session id when calling this method."
+	},
+	"session.id_empty": {
+		title: "Session id is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty session id."
+	},
+	"session.title_empty": {
+		title: "Session title is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty session title."
+	},
+	"session.state_not_found": {
+		title: "Session state missing",
+		retryable: false,
+		public: true,
+		action: "The session directory is corrupted or missing state.json."
+	},
+	"session.state_invalid": {
+		title: "Session state invalid",
+		retryable: false,
+		public: true,
+		action: "The session state.json is corrupted; remove the session or repair the file."
+	},
+	"session.fork_active_turn": {
+		title: "Cannot fork session during active turn",
+		retryable: true,
+		public: true,
+		action: "Wait for the active turn to complete before forking."
+	},
+	"session.export_not_found": {
+		title: "Session export directory missing",
+		retryable: false,
+		public: true,
+		action: "The session has not been persisted to disk yet."
+	},
+	"session.export_missing_version": {
+		title: "Export version is missing",
+		retryable: false,
+		public: true,
+		action: "Provide a version when exporting the session."
+	},
+	"session.closed": {
+		title: "Session is closed",
+		retryable: false,
+		public: true,
+		action: "Create a new session."
+	},
+	"session.permission_mode_invalid": {
+		title: "Invalid permission mode",
+		retryable: false,
+		public: true,
+		action: "Use one of: yolo / manual / auto."
+	},
+	"session.thinking_empty": {
+		title: "Thinking value is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty thinking option."
+	},
+	"session.model_empty": {
+		title: "Model is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty model identifier."
+	},
+	"session.plan_mode_invalid": {
+		title: "Invalid plan mode",
+		retryable: false,
+		public: true,
+		action: "Provide a boolean plan mode."
+	},
+	"session.approval_handler_error": {
+		title: "Approval handler threw",
+		retryable: false,
+		public: true,
+		action: "Inspect the SDK approval handler for an unhandled exception."
+	},
+	"session.question_handler_error": {
+		title: "Question handler threw",
+		retryable: false,
+		public: true,
+		action: "Inspect the SDK question handler for an unhandled exception."
+	},
+	"session.init_failed": {
+		title: "Session init failed",
+		retryable: false,
+		public: false,
+		action: "Review the init failure details and try again."
+	},
+	"agent.not_found": {
+		title: "Agent not found",
+		retryable: false,
+		public: true,
+		action: "Check the agent id or list available agents."
+	},
+	"turn.agent_busy": {
+		title: "Agent is busy",
+		retryable: true,
+		public: true,
+		action: "Wait for the current turn to finish or steer it."
+	},
+	"model.not_configured": {
+		title: "No model configured",
+		retryable: false,
+		public: true,
+		action: "Set a default model in config.toml or via setModel."
+	},
+	"model.config_invalid": {
+		title: "Invalid model configuration",
+		retryable: false,
+		public: true,
+		action: "Check the model and provider entries in config.toml."
+	},
+	"auth.login_required": {
+		title: "Login required",
+		retryable: false,
+		public: true,
+		action: "Run the login flow for the provider before retrying."
+	},
+	"context.overflow": {
+		title: "Context window overflow",
+		retryable: true,
+		public: true,
+		action: "Compact the conversation or start a new session."
+	},
+	"loop.max_steps_exceeded": {
+		title: "Turn exceeded max steps",
+		retryable: false,
+		public: true,
+		action: "Increase loop_control.max_steps_per_turn or split the task."
+	},
+	"provider.api_error": {
+		title: "Provider API error",
+		retryable: false,
+		public: true,
+		action: "Inspect details.statusCode / details.requestId; check provider status."
+	},
+	"provider.rate_limit": {
+		title: "Provider rate limit",
+		retryable: true,
+		public: true,
+		action: "Retry after a delay or reduce request frequency."
+	},
+	"provider.auth_error": {
+		title: "Provider authentication error",
+		retryable: false,
+		public: true,
+		action: "Re-authenticate with the provider."
+	},
+	"provider.connection_error": {
+		title: "Provider connection error",
+		retryable: true,
+		public: true,
+		action: "Check network connectivity and retry."
+	},
+	"skill.not_found": {
+		title: "Skill not found",
+		retryable: false,
+		public: true,
+		action: "List available skills via the skill registry."
+	},
+	"skill.type_unsupported": {
+		title: "Skill type not supported",
+		retryable: false,
+		public: true,
+		action: "Only inline skills can be activated by the user."
+	},
+	"skill.name_empty": {
+		title: "Skill name is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty skill name."
+	},
+	"records.write_failed": {
+		title: "Failed to write records",
+		retryable: true,
+		public: true,
+		action: "Check disk space and permissions on the session directory."
+	},
+	"compaction.failed": {
+		title: "Compaction failed",
+		retryable: false,
+		public: true,
+		action: "Inspect logs and consider increasing compaction limits."
+	},
+	"background.task_id_empty": {
+		title: "Background task id is empty",
+		retryable: false,
+		public: true,
+		action: "Provide a non-empty task id."
+	},
+	"mcp.server_not_found": {
+		title: "MCP server not found",
+		retryable: false,
+		public: true,
+		action: "List configured MCP servers and check the requested name."
+	},
+	"mcp.server_disabled": {
+		title: "MCP server is disabled",
+		retryable: false,
+		public: true,
+		action: "Enable the MCP server entry in config before reconnecting."
+	},
+	"mcp.startup_failed": {
+		title: "MCP server startup failed",
+		retryable: true,
+		public: true,
+		action: "Inspect the MCP server log or call reconnect once the server is healthy."
+	},
+	"mcp.tool_name_collision": {
+		title: "MCP tool name collision",
+		retryable: false,
+		public: true,
+		action: "Rename one of the colliding MCP tools or servers so their qualified names are unique."
+	},
+	"request.invalid": {
+		title: "Invalid request",
+		retryable: false,
+		public: true,
+		action: "Check the input shape matches the API contract."
+	},
+	"request.work_dir_required": {
+		title: "workDir is required",
+		retryable: false,
+		public: true,
+		action: "Provide workDir in the request payload."
+	},
+	"request.prompt_input_empty": {
+		title: "Prompt input is empty",
+		retryable: false,
+		public: true,
+		action: "Provide non-empty prompt input."
+	},
+	"shell.git_bash_not_found": {
+		title: "Git Bash not found",
+		retryable: false,
+		public: true,
+		action: "Install Git for Windows from https://gitforwindows.org/ or set BYF_SHELL_PATH to a bash.exe."
+	},
+	not_implemented: {
+		title: "Not implemented",
+		retryable: false,
+		public: true,
+		action: "This feature is not implemented yet."
+	},
+	internal: {
+		title: "Internal error",
+		retryable: false,
+		public: true,
+		action: "Inspect logs or report the issue with diagnostics."
+	}
+};
+//#endregion
+//#region src/errors/classes.ts
+/**
+* The single Byf error class.
+*
+* Discrimination is always by `code`. Cross-process consumers receive
+* `ByfErrorPayload` and must branch on `code` rather than class identity.
+*/
+var ByfError = class extends Error {
+	code;
+	details;
+	cause;
+	constructor(code, message, options = {}) {
+		super(message);
+		this.name = "ByfError";
+		this.code = code;
+		this.details = options.details;
+		this.cause = options.cause;
+	}
+};
+//#endregion
+//#region src/errors/serialize.ts
+/** Type guard for ByfError. */
+function isByfError(error) {
+	return error instanceof ByfError;
+}
+/**
+* Build a ByfErrorPayload directly from a code + message (no Error instance
+* needed). Use this for synthetic error events that are signaled, not thrown
+* -- e.g. "turn busy" or "compaction failed". `retryable` is filled from
+* BYF_ERROR_INFO so callers cannot drift out of sync with the registry.
+*/
+function makeErrorPayload(code, message, options) {
+	return {
+		code,
+		message,
+		name: options?.name,
+		details: options?.details,
+		retryable: BYF_ERROR_INFO[code].retryable
+	};
+}
+/**
+* Normalize any value into a ByfErrorPayload.
+*
+* Recognized errors:
+* - `ByfError`: passthrough.
+* - `APIStatusError`: 429 -> rate_limit, 401 -> auth_error, otherwise -> api_error.
+* - `APIConnectionError` / `APITimeoutError`: connection_error.
+* - `ChatProviderError`: api_error.
+* - Heuristic "Model not set" / "Provider not set" messages: model.not_configured.
+*
+* Anything else collapses to `internal`. We never echo `cause` or stack on
+* the wire.
+*/
+function toByfErrorPayload(error) {
+	if (isByfError(error)) return {
+		code: error.code,
+		message: error.message,
+		name: error.name,
+		details: error.details,
+		retryable: BYF_ERROR_INFO[error.code].retryable
+	};
+	if (error instanceof APIStatusError) {
+		const code = error.statusCode === 429 ? ErrorCodes.PROVIDER_RATE_LIMIT : error.statusCode === 401 ? ErrorCodes.PROVIDER_AUTH_ERROR : ErrorCodes.PROVIDER_API_ERROR;
+		return {
+			code,
+			message: error.message,
+			name: error.name,
+			details: {
+				statusCode: error.statusCode,
+				requestId: error.requestId
+			},
+			retryable: BYF_ERROR_INFO[code].retryable
+		};
+	}
+	if (error instanceof APIConnectionError || error instanceof APITimeoutError) return {
+		code: ErrorCodes.PROVIDER_CONNECTION_ERROR,
+		message: error.message,
+		name: error.name,
+		retryable: BYF_ERROR_INFO[ErrorCodes.PROVIDER_CONNECTION_ERROR].retryable
+	};
+	if (error instanceof ChatProviderError) return {
+		code: ErrorCodes.PROVIDER_API_ERROR,
+		message: error.message,
+		name: error.name,
+		retryable: BYF_ERROR_INFO[ErrorCodes.PROVIDER_API_ERROR].retryable
+	};
+	if (error instanceof Error) {
+		if (error.message === "Model not set" || error.message === "Provider not set") return {
+			code: ErrorCodes.MODEL_NOT_CONFIGURED,
+			message: error.message,
+			name: error.name,
+			retryable: BYF_ERROR_INFO[ErrorCodes.MODEL_NOT_CONFIGURED].retryable
+		};
+		return {
+			code: ErrorCodes.INTERNAL,
+			message: error.message,
+			name: error.name,
+			retryable: BYF_ERROR_INFO[ErrorCodes.INTERNAL].retryable
+		};
+	}
+	return {
+		code: ErrorCodes.INTERNAL,
+		message: String(error),
+		retryable: BYF_ERROR_INFO[ErrorCodes.INTERNAL].retryable
+	};
+}
+/**
+* Rehydrate a ByfErrorPayload into a ByfError. Used by SDK boundary code
+* receiving errors over RPC to re-surface them with a real class so
+* in-process consumers can still use `instanceof`.
+*/
+function fromByfErrorPayload(payload) {
+	return new ByfError(payload.code, payload.message, { details: payload.details });
+}
+//#endregion
+//#region src/session/store/session-index.ts
+function sessionIndexPath(homeDir) {
+	return join(homeDir, "session_index.jsonl");
+}
+async function appendSessionIndexEntry(homeDir, entry) {
+	const indexPath = sessionIndexPath(homeDir);
+	await mkdir(dirname(indexPath), {
+		recursive: true,
+		mode: 448
+	});
+	await appendFile(indexPath, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+async function readSessionIndex(homeDir, sessionsDir) {
+	let raw;
+	try {
+		raw = await readFile(sessionIndexPath(homeDir), "utf-8");
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+	const result = /* @__PURE__ */ new Map();
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		const entry = parseIndexLine(trimmed);
+		if (entry === void 0) continue;
+		const sessionDir = resolve(entry.sessionDir);
+		if (!isAbsolute(entry.sessionDir)) continue;
+		if (!isAbsolute(entry.workDir)) continue;
+		if (!isPathInside(sessionsDir, sessionDir)) continue;
+		if (basename(sessionDir) !== entry.sessionId) continue;
+		result.set(entry.sessionId, {
+			sessionId: entry.sessionId,
+			sessionDir,
+			workDir: resolve(entry.workDir)
+		});
+	}
+	return result;
+}
+function parseIndexLine(line) {
+	try {
+		const parsed = JSON.parse(line);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const entry = parsed;
+		if (typeof entry.sessionId !== "string" || typeof entry.sessionDir !== "string" || typeof entry.workDir !== "string") return;
+		return {
+			sessionId: entry.sessionId,
+			sessionDir: entry.sessionDir,
+			workDir: entry.workDir
+		};
+	} catch {
+		return;
+	}
+}
+function isPathInside(parent, child) {
+	const rel = relative(resolve(parent), resolve(child));
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+//#endregion
+//#region src/utils/workdir-slug.ts
+const MAX_WORKDIR_SLUG_LENGTH = 40;
+function slugifyWorkDirName(name) {
+	const slug = name.toLowerCase().replaceAll(/[^a-z0-9._-]+/g, "-").replaceAll(/^-+|-+$/g, "").slice(0, MAX_WORKDIR_SLUG_LENGTH).replaceAll(/^-+|-+$/g, "");
+	return slug === "" || slug === "." || slug === ".." ? "workspace" : slug;
+}
+//#endregion
+//#region src/session/store/workdir-key.ts
+const WORKDIR_KEY_PREFIX = "wd_";
+const HASH_LENGTH = 12;
+function normalizeWorkDir(workDir) {
+	return resolve(workDir);
+}
+function encodeWorkDirKey(workDir) {
+	const normalized = normalizeWorkDir(workDir);
+	return `${WORKDIR_KEY_PREFIX}${slugifyWorkDirName(basename(normalized))}_${createHash("sha256").update(normalized).digest("hex").slice(0, HASH_LENGTH)}`;
+}
+//#endregion
+//#region src/session/store/session-store.ts
+const SessionSummaryStateSchema = z.object({
+	customTitle: z.string().optional(),
+	isCustomTitle: z.boolean().optional(),
+	lastPrompt: z.string().optional(),
+	title: z.string().optional(),
+	custom: z.record(z.string(), z.unknown()).optional()
+});
+var SessionStore = class {
+	homeDir;
+	sessionsDir;
+	constructor(homeDir, _options = {}) {
+		this.homeDir = homeDir;
+		this.sessionsDir = join(homeDir, "sessions");
+	}
+	sessionDirFor(input) {
+		assertSafeSessionId(input.id);
+		return join(this.sessionsDir, encodeWorkDirKey(normalizeWorkDir(input.workDir)), input.id);
+	}
+	async create(input) {
+		assertSafeSessionId(input.id);
+		const workDir = normalizeWorkDir(input.workDir);
+		if (await this.findSessionEntry(input.id) !== void 0) throw new ByfError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.id}" already exists`);
+		const dir = this.sessionDirFor({
+			id: input.id,
+			workDir
+		});
+		if (await isDirectory(dir)) throw new ByfError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.id}" already exists`);
+		await mkdir(dir, {
+			recursive: true,
+			mode: 448
+		});
+		await appendSessionIndexEntry(this.homeDir, {
+			sessionId: input.id,
+			sessionDir: dir,
+			workDir
+		});
+		return this.summaryFromDir(input.id, dir, workDir);
+	}
+	async fork(input) {
+		const source = await this.findExistingSessionEntry(input.sourceId);
+		assertSafeSessionId(input.targetId);
+		if (await this.findSessionEntry(input.targetId) !== void 0) throw new ByfError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.targetId}" already exists`);
+		const targetDir = this.sessionDirFor({
+			id: input.targetId,
+			workDir: source.workDir
+		});
+		if (await isDirectory(targetDir)) throw new ByfError(ErrorCodes.SESSION_ALREADY_EXISTS, `Session "${input.targetId}" already exists`);
+		await mkdir(dirname(targetDir), {
+			recursive: true,
+			mode: 448
+		});
+		try {
+			await cp(source.sessionDir, targetDir, {
+				recursive: true,
+				force: false,
+				errorOnExist: true
+			});
+			await this.writeForkedState(input, source.sessionDir, targetDir);
+			const summary = await this.summaryFromDir(input.targetId, targetDir, source.workDir);
+			await appendSessionIndexEntry(this.homeDir, {
+				sessionId: input.targetId,
+				sessionDir: targetDir,
+				workDir: source.workDir
+			});
+			return summary;
+		} catch (error) {
+			await rm(targetDir, {
+				recursive: true,
+				force: true
+			}).catch(() => {});
+			throw error;
+		}
+	}
+	async get(id) {
+		const entry = await this.findExistingSessionEntry(id);
+		return this.summaryFromDir(id, entry.sessionDir, entry.workDir);
+	}
+	async rename(id, title) {
+		const normalized = title.trim();
+		if (normalized.length === 0) throw new ByfError(ErrorCodes.SESSION_TITLE_EMPTY, "Session title cannot be empty");
+		const statePath = join((await this.findExistingSessionEntry(id)).sessionDir, "state.json");
+		let parsed;
+		try {
+			parsed = JSON.parse(await readFile(statePath, "utf-8"));
+		} catch (error) {
+			throw new ByfError(ErrorCodes.SESSION_STATE_NOT_FOUND, `Session "${id}" state.json was not found`, { cause: error });
+		}
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new ByfError(ErrorCodes.SESSION_STATE_INVALID, `Session "${id}" state.json is invalid`);
+		const next = {
+			...parsed,
+			title: normalized,
+			isCustomTitle: true
+		};
+		await writeFile(statePath, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+	}
+	async list(options) {
+		const workDir = normalizeWorkDir(options.workDir);
+		const bucketDir = join(this.sessionsDir, encodeWorkDirKey(workDir));
+		let entries;
+		try {
+			entries = await readdir(bucketDir, { withFileTypes: true });
+		} catch {
+			return [];
+		}
+		const sessions = [];
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const id = entry.name;
+			if (!isSafeSessionId(id)) continue;
+			const dir = join(bucketDir, id);
+			sessions.push(await this.summaryFromDir(id, dir, workDir));
+		}
+		sessions.sort(compareSessionSummary);
+		return sessions;
+	}
+	async assertDirectory(id) {
+		return (await this.findExistingSessionEntry(id)).sessionDir;
+	}
+	async findSessionEntry(id) {
+		if (!isSafeSessionId(id)) return void 0;
+		return (await readSessionIndex(this.homeDir, this.sessionsDir)).get(id);
+	}
+	async findExistingSessionEntry(id) {
+		const entry = await this.findSessionEntry(id);
+		if (entry !== void 0 && await isDirectory(entry.sessionDir)) return entry;
+		throw new ByfError(ErrorCodes.SESSION_NOT_FOUND, `Session "${id}" was not found`, { details: { sessionId: id } });
+	}
+	async writeForkedState(input, sourceDir, targetDir) {
+		const statePath = join(targetDir, "state.json");
+		let parsed;
+		try {
+			parsed = JSON.parse(await readFile(statePath, "utf-8"));
+		} catch (error) {
+			throw new ByfError(ErrorCodes.SESSION_STATE_NOT_FOUND, `Session "${input.sourceId}" state.json was not found`, { cause: error });
+		}
+		if (!isRecord(parsed)) throw new ByfError(ErrorCodes.SESSION_STATE_INVALID, `Session "${input.sourceId}" state.json is invalid`);
+		const title = normalizeForkTitle(input.title, parsed["title"]);
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const next = {
+			...parsed,
+			createdAt: now,
+			updatedAt: now,
+			title,
+			isCustomTitle: input.title === void 0 ? parsed["isCustomTitle"] === true : true,
+			forkedFrom: input.sourceId,
+			agents: rewriteAgentHomedirs(parsed["agents"], sourceDir, targetDir),
+			custom: Object.assign({}, isRecord(parsed["custom"]) ? parsed["custom"] : {}, input.metadata)
+		};
+		await writeFile(statePath, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+	}
+	async summaryFromDir(id, sessionDir, workDir) {
+		const dirStat = await stat(sessionDir);
+		const state = await readOptionalState(sessionDir);
+		const [stateInfo, wireInfo, agentsWireMtime] = await Promise.all([
+			statIfExists(join(sessionDir, "state.json")),
+			statIfExists(join(sessionDir, "wire.jsonl")),
+			latestAgentWireMtime(sessionDir)
+		]);
+		return {
+			id,
+			workDir,
+			sessionDir,
+			createdAt: timestampOrFallback(dirStat.birthtimeMs, dirStat.ctimeMs),
+			updatedAt: Math.max(dirStat.mtimeMs, stateInfo?.mtimeMs ?? 0, wireInfo?.mtimeMs ?? 0, agentsWireMtime ?? 0),
+			title: titleFromState(state),
+			lastPrompt: state?.lastPrompt,
+			metadata: metadataFromState(state)
+		};
+	}
+};
+function metadataFromState(state) {
+	if (state === void 0 || state.custom === void 0) return void 0;
+	return state.custom;
+}
+async function latestAgentWireMtime(sessionDir) {
+	const agentsDir = join(sessionDir, "agents");
+	let entries;
+	try {
+		entries = await readdir(agentsDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	let latest = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue;
+		const wireInfo = await statIfExists(join(agentsDir, entry.name, "wire.jsonl"));
+		latest = Math.max(latest, wireInfo?.mtimeMs ?? 0);
+	}
+	return latest > 0 ? latest : void 0;
+}
+function titleFromState(state) {
+	if (state === void 0) return void 0;
+	if (typeof state.isCustomTitle === "boolean" && typeof state.title === "string") return state.title;
+	if (typeof state.customTitle === "string") return state.customTitle;
+	return typeof state.title === "string" ? state.title : void 0;
+}
+async function readOptionalState(sessionDir) {
+	try {
+		const parsed = JSON.parse(await readFile(join(sessionDir, "state.json"), "utf-8"));
+		const result = SessionSummaryStateSchema.safeParse(parsed);
+		return result.success ? result.data : void 0;
+	} catch {
+		return;
+	}
+}
+function normalizeForkTitle(title, fallback) {
+	if (title !== void 0) {
+		const normalized = title.trim();
+		if (normalized.length === 0) throw new ByfError(ErrorCodes.SESSION_TITLE_EMPTY, "Session title cannot be empty");
+		return normalized;
+	}
+	return typeof fallback === "string" && fallback.trim().length > 0 ? fallback : "New Session";
+}
+function rewriteAgentHomedirs(value, sourceDir, targetDir) {
+	if (!isRecord(value)) return {};
+	const agents = {};
+	for (const [agentId, agentMeta] of Object.entries(value)) {
+		if (!isRecord(agentMeta)) {
+			agents[agentId] = agentMeta;
+			continue;
+		}
+		const homedir = agentMeta["homedir"];
+		agents[agentId] = {
+			...agentMeta,
+			homedir: typeof homedir === "string" ? remapSessionPath(homedir, sourceDir, targetDir) : homedir
+		};
+	}
+	return agents;
+}
+function remapSessionPath(value, sourceDir, targetDir) {
+	const rel = relative(sourceDir, value);
+	if (rel === "") return targetDir;
+	if (rel.startsWith("..") || isAbsolute(rel)) return value;
+	return join(targetDir, rel);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function statIfExists(path) {
+	try {
+		return await stat(path);
+	} catch {
+		return;
+	}
+}
+async function isDirectory(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function timestampOrFallback(value, fallback) {
+	return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function assertSafeSessionId(id) {
+	if (isSafeSessionId(id)) return;
+	throw new ByfError(ErrorCodes.SESSION_ID_INVALID, "Session id contains unsupported path characters");
+}
+function isSafeSessionId(id) {
+	return /^[A-Za-z0-9._-]+$/.test(id) && id !== "." && id !== "..";
+}
+function compareSessionSummary(a, b) {
+	if (a.updatedAt !== b.updatedAt) return b.updatedAt - a.updatedAt;
+	if (a.createdAt !== b.createdAt) return b.createdAt - a.createdAt;
+	if (a.id < b.id) return -1;
+	if (a.id > b.id) return 1;
+	return 0;
+}
+//#endregion
+export { fromByfErrorPayload as a, toByfErrorPayload as c, ErrorCodes as d, sessionIndexPath as i, ByfError as l, encodeWorkDirKey as n, isByfError as o, normalizeWorkDir as r, makeErrorPayload as s, SessionStore as t, BYF_ERROR_INFO as u };