world-model-optimizer 0.2.0__py3-none-any.whl

wmo/harness/vendor/pi-agent/src/harness/session/session.ts

@@ -0,0 +1,267 @@
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { AgentMessage } from "../../types.ts";
+import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage } from "../messages.ts";
+import type {
+	ActiveToolsChangeEntry,
+	BranchSummaryEntry,
+	CompactionEntry,
+	CustomEntry,
+	CustomMessageEntry,
+	LabelEntry,
+	MessageEntry,
+	ModelChangeEntry,
+	SessionContext,
+	SessionInfoEntry,
+	SessionMetadata,
+	SessionStorage,
+	SessionTreeEntry,
+	ThinkingLevelChangeEntry,
+} from "../types.ts";
+import { SessionError } from "../types.ts";
+
+export function buildSessionContext(pathEntries: SessionTreeEntry[]): SessionContext {
+	let thinkingLevel = "off";
+	let model: { provider: string; modelId: string } | null = null;
+	let activeToolNames: string[] | null = null;
+	let compaction: CompactionEntry | null = null;
+
+	for (const entry of pathEntries) {
+		if (entry.type === "thinking_level_change") {
+			thinkingLevel = entry.thinkingLevel;
+		} else if (entry.type === "model_change") {
+			model = { provider: entry.provider, modelId: entry.modelId };
+		} else if (entry.type === "message" && entry.message.role === "assistant") {
+			model = { provider: entry.message.provider, modelId: entry.message.model };
+		} else if (entry.type === "active_tools_change") {
+			activeToolNames = [...entry.activeToolNames];
+		} else if (entry.type === "compaction") {
+			compaction = entry;
+		}
+	}
+
+	const messages: AgentMessage[] = [];
+	const appendMessage = (entry: SessionTreeEntry) => {
+		if (entry.type === "message") {
+			messages.push(entry.message as AgentMessage);
+		} else if (entry.type === "custom_message") {
+			messages.push(
+				createCustomMessage(
+					entry.customType,
+					entry.content as string | (TextContent | ImageContent)[],
+					entry.display,
+					entry.details,
+					entry.timestamp,
+				),
+			);
+		} else if (entry.type === "branch_summary" && entry.summary) {
+			messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+		}
+	};
+
+	if (compaction) {
+		messages.push(createCompactionSummaryMessage(compaction.summary, compaction.tokensBefore, compaction.timestamp));
+		const compactionIdx = pathEntries.findIndex((e) => e.type === "compaction" && e.id === compaction.id);
+		let foundFirstKept = false;
+		for (let i = 0; i < compactionIdx; i++) {
+			const entry = pathEntries[i]!;
+			if (entry.id === compaction.firstKeptEntryId) foundFirstKept = true;
+			if (foundFirstKept) appendMessage(entry);
+		}
+		for (let i = compactionIdx + 1; i < pathEntries.length; i++) {
+			appendMessage(pathEntries[i]!);
+		}
+	} else {
+		for (const entry of pathEntries) {
+			appendMessage(entry);
+		}
+	}
+
+	return { messages, thinkingLevel, model, activeToolNames };
+}
+
+export class Session<TMetadata extends SessionMetadata = SessionMetadata> {
+	private storage: SessionStorage<TMetadata>;
+
+	constructor(storage: SessionStorage<TMetadata>) {
+		this.storage = storage;
+	}
+
+	getMetadata(): Promise<TMetadata> {
+		return this.storage.getMetadata();
+	}
+
+	getStorage(): SessionStorage<TMetadata> {
+		return this.storage;
+	}
+
+	getLeafId(): Promise<string | null> {
+		return this.storage.getLeafId();
+	}
+
+	getEntry(id: string): Promise<SessionTreeEntry | undefined> {
+		return this.storage.getEntry(id);
+	}
+
+	getEntries(): Promise<SessionTreeEntry[]> {
+		return this.storage.getEntries();
+	}
+
+	async getBranch(fromId?: string): Promise<SessionTreeEntry[]> {
+		const leafId = fromId ?? (await this.storage.getLeafId());
+		return this.storage.getPathToRoot(leafId);
+	}
+
+	async buildContext(): Promise<SessionContext> {
+		return buildSessionContext(await this.getBranch());
+	}
+
+	getLabel(id: string): Promise<string | undefined> {
+		return this.storage.getLabel(id);
+	}
+
+	async getSessionName(): Promise<string | undefined> {
+		const entries = await this.storage.findEntries("session_info");
+		return entries[entries.length - 1]?.name?.trim() || undefined;
+	}
+
+	private async appendTypedEntry<TEntry extends SessionTreeEntry>(entry: TEntry): Promise<string> {
+		await this.storage.appendEntry(entry);
+		return entry.id;
+	}
+
+	async appendMessage(message: AgentMessage): Promise<string> {
+		return this.appendTypedEntry({
+			type: "message",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			message,
+		} satisfies MessageEntry);
+	}
+
+	async appendThinkingLevelChange(thinkingLevel: string): Promise<string> {
+		return this.appendTypedEntry({
+			type: "thinking_level_change",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			thinkingLevel,
+		} satisfies ThinkingLevelChangeEntry);
+	}
+
+	async appendModelChange(provider: string, modelId: string): Promise<string> {
+		return this.appendTypedEntry({
+			type: "model_change",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			provider,
+			modelId,
+		} satisfies ModelChangeEntry);
+	}
+
+	async appendActiveToolsChange(activeToolNames: string[]): Promise<string> {
+		return this.appendTypedEntry({
+			type: "active_tools_change",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			activeToolNames: [...activeToolNames],
+		} satisfies ActiveToolsChangeEntry);
+	}
+
+	async appendCompaction<T = unknown>(
+		summary: string,
+		firstKeptEntryId: string,
+		tokensBefore: number,
+		details?: T,
+		fromHook?: boolean,
+	): Promise<string> {
+		return this.appendTypedEntry({
+			type: "compaction",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			summary,
+			firstKeptEntryId,
+			tokensBefore,
+			details,
+			fromHook,
+		} satisfies CompactionEntry<T>);
+	}
+
+	async appendCustomEntry(customType: string, data?: unknown): Promise<string> {
+		return this.appendTypedEntry({
+			type: "custom",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			customType,
+			data,
+		} satisfies CustomEntry);
+	}
+
+	async appendCustomMessageEntry<T = unknown>(
+		customType: string,
+		content: string | (TextContent | ImageContent)[],
+		display: boolean,
+		details?: T,
+	): Promise<string> {
+		return this.appendTypedEntry({
+			type: "custom_message",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			customType,
+			content,
+			display,
+			details,
+		} satisfies CustomMessageEntry<T>);
+	}
+
+	async appendLabel(targetId: string, label: string | undefined): Promise<string> {
+		if (!(await this.storage.getEntry(targetId))) {
+			throw new SessionError("not_found", `Entry ${targetId} not found`);
+		}
+		return this.appendTypedEntry({
+			type: "label",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			targetId,
+			label,
+		} satisfies LabelEntry);
+	}
+
+	async appendSessionName(name: string): Promise<string> {
+		const sanitizedName = name.replace(/[\r\n]+/g, " ").trim();
+		return this.appendTypedEntry({
+			type: "session_info",
+			id: await this.storage.createEntryId(),
+			parentId: await this.storage.getLeafId(),
+			timestamp: new Date().toISOString(),
+			name: sanitizedName,
+		} satisfies SessionInfoEntry);
+	}
+
+	async moveTo(
+		entryId: string | null,
+		summary?: { summary: string; details?: unknown; fromHook?: boolean },
+	): Promise<string | undefined> {
+		if (entryId !== null && !(await this.storage.getEntry(entryId))) {
+			throw new SessionError("not_found", `Entry ${entryId} not found`);
+		}
+		await this.storage.setLeafId(entryId);
+		if (!summary) return undefined;
+		return this.appendTypedEntry({
+			type: "branch_summary",
+			id: await this.storage.createEntryId(),
+			parentId: entryId,
+			timestamp: new Date().toISOString(),
+			fromId: entryId ?? "root",
+			summary: summary.summary,
+			details: summary.details,
+			fromHook: summary.fromHook,
+		} satisfies BranchSummaryEntry);
+	}
+}

wmo/harness/vendor/pi-agent/src/harness/session/uuid.ts

@@ -0,0 +1,54 @@
+let lastTimestamp = -Infinity;
+let sequence = 0;
+
+function fillRandomBytes(bytes: Uint8Array): void {
+	const crypto = globalThis.crypto;
+	if (crypto?.getRandomValues) {
+		crypto.getRandomValues(bytes);
+		return;
+	}
+	for (let i = 0; i < bytes.length; i++) {
+		bytes[i] = Math.floor(Math.random() * 256);
+	}
+}
+
+export function uuidv7(): string {
+	const random = new Uint8Array(16);
+	fillRandomBytes(random);
+	const timestamp = Date.now();
+
+	if (timestamp > lastTimestamp) {
+		sequence = random[6] * 0x1000000 + random[7] * 0x10000 + random[8] * 0x100 + random[9];
+		lastTimestamp = timestamp;
+	} else {
+		sequence = (sequence + 1) >>> 0;
+		if (sequence === 0) {
+			lastTimestamp++;
+		}
+	}
+
+	const bytes = new Uint8Array(16);
+	bytes[0] = (lastTimestamp / 0x10000000000) & 0xff;
+	bytes[1] = (lastTimestamp / 0x100000000) & 0xff;
+	bytes[2] = (lastTimestamp / 0x1000000) & 0xff;
+	bytes[3] = (lastTimestamp / 0x10000) & 0xff;
+	bytes[4] = (lastTimestamp / 0x100) & 0xff;
+	bytes[5] = lastTimestamp & 0xff;
+	bytes[6] = 0x70 | ((sequence >>> 28) & 0x0f);
+	bytes[7] = (sequence >>> 20) & 0xff;
+	bytes[8] = 0x80 | ((sequence >>> 14) & 0x3f);
+	bytes[9] = (sequence >>> 6) & 0xff;
+	bytes[10] = ((sequence & 0x3f) << 2) | (random[10] & 0x03);
+	bytes[11] = random[11];
+	bytes[12] = random[12];
+	bytes[13] = random[13];
+	bytes[14] = random[14];
+	bytes[15] = random[15];
+
+	return formatUuid(bytes);
+}
+
+function formatUuid(bytes: Uint8Array): string {
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+	return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}

wmo/harness/vendor/pi-agent/src/harness/skills.ts

@@ -0,0 +1,375 @@
+import ignore from "ignore";
+import { parse } from "yaml";
+import { type ExecutionEnv, type FileInfo, type Result, type Skill, toError } from "./types.ts";
+
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"];
+
+type IgnoreMatcher = ReturnType<typeof ignore>;
+
+export type SkillDiagnosticCode =
+	| "file_info_failed"
+	| "list_failed"
+	| "read_failed"
+	| "parse_failed"
+	| "invalid_metadata";
+
+/** Warning produced while loading skills. */
+export interface SkillDiagnostic {
+	/** Diagnostic severity. Currently only warnings are emitted. */
+	type: "warning";
+	/** Stable diagnostic code. */
+	code: SkillDiagnosticCode;
+	/** Human-readable diagnostic message. */
+	message: string;
+	/** Path associated with the diagnostic. */
+	path: string;
+}
+
+interface SkillFrontmatter {
+	name?: string;
+	description?: string;
+	"disable-model-invocation"?: boolean;
+	[key: string]: unknown;
+}
+
+/** Format a skill invocation prompt, optionally appending additional user instructions. */
+export function formatSkillInvocation(skill: Skill, additionalInstructions?: string): string {
+	const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${dirnameEnvPath(skill.filePath)}.\n\n${skill.content}\n</skill>`;
+	return additionalInstructions ? `${skillBlock}\n\n${additionalInstructions}` : skillBlock;
+}
+
+/**
+ * Load skills from one or more directories.
+ *
+ * Traverses directories recursively, loads `SKILL.md` files, loads direct root `.md` files as skills, honors ignore files,
+ * and returns diagnostics for invalid skill files. Missing input directories are skipped.
+ */
+export async function loadSkills(
+	env: ExecutionEnv,
+	dirs: string | string[],
+): Promise<{ skills: Skill[]; diagnostics: SkillDiagnostic[] }> {
+	const skills: Skill[] = [];
+	const diagnostics: SkillDiagnostic[] = [];
+	for (const dir of Array.isArray(dirs) ? dirs : [dirs]) {
+		const rootInfoResult = await env.fileInfo(dir);
+		if (!rootInfoResult.ok) {
+			if (rootInfoResult.error.code !== "not_found") {
+				diagnostics.push({
+					type: "warning",
+					code: "file_info_failed",
+					message: rootInfoResult.error.message,
+					path: dir,
+				});
+			}
+			continue;
+		}
+		const rootInfo = rootInfoResult.value;
+		if ((await resolveKind(env, rootInfo, diagnostics)) !== "directory") continue;
+		const result = await loadSkillsFromDirInternal(env, rootInfo.path, true, ignore(), rootInfo.path);
+		skills.push(...result.skills);
+		diagnostics.push(...result.diagnostics);
+	}
+	return { skills, diagnostics };
+}
+
+/**
+ * Load skills from source-tagged directories.
+ *
+ * Source values are preserved exactly and attached to every loaded skill and diagnostic. The agent package does not
+ * interpret source values; applications define their own provenance shape.
+ */
+export async function loadSourcedSkills<TSource, TSkill extends Skill = Skill>(
+	env: ExecutionEnv,
+	inputs: Array<{ path: string; source: TSource }>,
+	mapSkill?: (skill: Skill, source: TSource) => TSkill,
+): Promise<{
+	skills: Array<{ skill: TSkill; source: TSource }>;
+	diagnostics: Array<SkillDiagnostic & { source: TSource }>;
+}> {
+	const skills: Array<{ skill: TSkill; source: TSource }> = [];
+	const diagnostics: Array<SkillDiagnostic & { source: TSource }> = [];
+	for (const input of inputs) {
+		const result = await loadSkills(env, input.path);
+		for (const skill of result.skills) {
+			skills.push({ skill: mapSkill ? mapSkill(skill, input.source) : (skill as TSkill), source: input.source });
+		}
+		for (const diagnostic of result.diagnostics) diagnostics.push({ ...diagnostic, source: input.source });
+	}
+	return { skills, diagnostics };
+}
+
+async function loadSkillsFromDirInternal(
+	env: ExecutionEnv,
+	dir: string,
+	includeRootFiles: boolean,
+	ignoreMatcher: IgnoreMatcher,
+	rootDir: string,
+): Promise<{ skills: Skill[]; diagnostics: SkillDiagnostic[] }> {
+	const skills: Skill[] = [];
+	const diagnostics: SkillDiagnostic[] = [];
+
+	const dirInfoResult = await env.fileInfo(dir);
+	if (!dirInfoResult.ok) {
+		if (dirInfoResult.error.code !== "not_found") {
+			diagnostics.push({
+				type: "warning",
+				code: "file_info_failed",
+				message: dirInfoResult.error.message,
+				path: dir,
+			});
+		}
+		return { skills, diagnostics };
+	}
+	const dirInfo = dirInfoResult.value;
+	if ((await resolveKind(env, dirInfo, diagnostics)) !== "directory") return { skills, diagnostics };
+
+	await addIgnoreRules(env, ignoreMatcher, dir, rootDir, diagnostics);
+
+	const entriesResult = await env.listDir(dir);
+	if (!entriesResult.ok) {
+		diagnostics.push({ type: "warning", code: "list_failed", message: entriesResult.error.message, path: dir });
+		return { skills, diagnostics };
+	}
+	const entries = entriesResult.value;
+
+	for (const entry of entries) {
+		if (entry.name !== "SKILL.md") continue;
+		const fullPath = entry.path;
+		const kind = await resolveKind(env, entry, diagnostics);
+		if (kind !== "file") continue;
+		const relPath = relativeEnvPath(rootDir, fullPath);
+		if (ignoreMatcher.ignores(relPath)) continue;
+
+		const result = await loadSkillFromFile(env, fullPath);
+		if (result.skill) skills.push(result.skill);
+		diagnostics.push(...result.diagnostics);
+		return { skills, diagnostics };
+	}
+
+	for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+		if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+		const fullPath = entry.path;
+		const kind = await resolveKind(env, entry, diagnostics);
+		if (!kind) continue;
+
+		const relPath = relativeEnvPath(rootDir, fullPath);
+		const ignorePath = kind === "directory" ? `${relPath}/` : relPath;
+		if (ignoreMatcher.ignores(ignorePath)) continue;
+
+		if (kind === "directory") {
+			const result = await loadSkillsFromDirInternal(env, fullPath, false, ignoreMatcher, rootDir);
+			skills.push(...result.skills);
+			diagnostics.push(...result.diagnostics);
+			continue;
+		}
+
+		if (kind !== "file" || !includeRootFiles || !entry.name.endsWith(".md")) continue;
+		const result = await loadSkillFromFile(env, fullPath);
+		if (result.skill) skills.push(result.skill);
+		diagnostics.push(...result.diagnostics);
+	}
+
+	return { skills, diagnostics };
+}
+
+async function addIgnoreRules(
+	env: ExecutionEnv,
+	ig: IgnoreMatcher,
+	dir: string,
+	rootDir: string,
+	diagnostics: SkillDiagnostic[],
+): Promise<void> {
+	const relativeDir = relativeEnvPath(rootDir, dir);
+	const prefix = relativeDir ? `${relativeDir}/` : "";
+
+	for (const filename of IGNORE_FILE_NAMES) {
+		const ignorePath = joinEnvPath(dir, filename);
+		const info = await env.fileInfo(ignorePath);
+		if (!info.ok) {
+			if (info.error.code !== "not_found") {
+				diagnostics.push({
+					type: "warning",
+					code: "file_info_failed",
+					message: info.error.message,
+					path: ignorePath,
+				});
+			}
+			continue;
+		}
+		if (info.value.kind !== "file") continue;
+		const content = await env.readTextFile(ignorePath);
+		if (!content.ok) {
+			diagnostics.push({ type: "warning", code: "read_failed", message: content.error.message, path: ignorePath });
+			continue;
+		}
+		const patterns = content.value
+			.split(/\r?\n/)
+			.map((line) => prefixIgnorePattern(line, prefix))
+			.filter((line): line is string => Boolean(line));
+		if (patterns.length > 0) ig.add(patterns);
+	}
+}
+
+function prefixIgnorePattern(line: string, prefix: string): string | null {
+	const trimmed = line.trim();
+	if (!trimmed) return null;
+	if (trimmed.startsWith("#") && !trimmed.startsWith("\\#")) return null;
+
+	let pattern = line;
+	let negated = false;
+	if (pattern.startsWith("!")) {
+		negated = true;
+		pattern = pattern.slice(1);
+	} else if (pattern.startsWith("\\!")) {
+		pattern = pattern.slice(1);
+	}
+	if (pattern.startsWith("/")) pattern = pattern.slice(1);
+	const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+	return negated ? `!${prefixed}` : prefixed;
+}
+
+async function loadSkillFromFile(
+	env: ExecutionEnv,
+	filePath: string,
+): Promise<{ skill: Skill | null; diagnostics: SkillDiagnostic[] }> {
+	const diagnostics: SkillDiagnostic[] = [];
+	const rawContent = await env.readTextFile(filePath);
+	if (!rawContent.ok) {
+		diagnostics.push({ type: "warning", code: "read_failed", message: rawContent.error.message, path: filePath });
+		return { skill: null, diagnostics };
+	}
+
+	const parsed = parseFrontmatter<SkillFrontmatter>(rawContent.value);
+	if (!parsed.ok) {
+		diagnostics.push({ type: "warning", code: "parse_failed", message: parsed.error.message, path: filePath });
+		return { skill: null, diagnostics };
+	}
+
+	const { frontmatter, body } = parsed.value;
+	const skillDir = dirnameEnvPath(filePath);
+	const parentDirName = basenameEnvPath(skillDir);
+	const description = typeof frontmatter.description === "string" ? frontmatter.description : undefined;
+
+	for (const error of validateDescription(description)) {
+		diagnostics.push({ type: "warning", code: "invalid_metadata", message: error, path: filePath });
+	}
+
+	const frontmatterName = typeof frontmatter.name === "string" ? frontmatter.name : undefined;
+	const name = frontmatterName || parentDirName;
+	for (const error of validateName(name, parentDirName)) {
+		diagnostics.push({ type: "warning", code: "invalid_metadata", message: error, path: filePath });
+	}
+
+	if (!description || description.trim() === "") {
+		return { skill: null, diagnostics };
+	}
+
+	return {
+		skill: {
+			name,
+			description,
+			content: body,
+			filePath,
+			disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+		},
+		diagnostics,
+	};
+}
+
+function validateName(name: string, parentDirName: string): string[] {
+	const errors: string[] = [];
+	if (name !== parentDirName) errors.push(`name "${name}" does not match parent directory "${parentDirName}"`);
+	if (name.length > MAX_NAME_LENGTH) errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+	if (!/^[a-z0-9-]+$/.test(name)) {
+		errors.push("name contains invalid characters (must be lowercase a-z, 0-9, hyphens only)");
+	}
+	if (name.startsWith("-") || name.endsWith("-")) errors.push("name must not start or end with a hyphen");
+	if (name.includes("--")) errors.push("name must not contain consecutive hyphens");
+	return errors;
+}
+
+function validateDescription(description: string | undefined): string[] {
+	const errors: string[] = [];
+	if (!description || description.trim() === "") {
+		errors.push("description is required");
+	} else if (description.length > MAX_DESCRIPTION_LENGTH) {
+		errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+	}
+	return errors;
+}
+
+function parseFrontmatter<T extends Record<string, unknown>>(
+	content: string,
+): Result<{ frontmatter: T; body: string }, Error> {
+	try {
+		const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+		if (!normalized.startsWith("---")) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const endIndex = normalized.indexOf("\n---", 3);
+		if (endIndex === -1) return { ok: true, value: { frontmatter: {} as T, body: normalized } };
+		const yamlString = normalized.slice(4, endIndex);
+		const body = normalized.slice(endIndex + 4).trim();
+		return { ok: true, value: { frontmatter: (parse(yamlString) ?? {}) as T, body } };
+	} catch (error) {
+		return { ok: false, error: toError(error) };
+	}
+}
+
+async function resolveKind(
+	env: ExecutionEnv,
+	info: FileInfo,
+	diagnostics: SkillDiagnostic[],
+): Promise<"file" | "directory" | undefined> {
+	if (info.kind === "file" || info.kind === "directory") return info.kind;
+	const canonicalPath = await env.canonicalPath(info.path);
+	if (!canonicalPath.ok) {
+		if (canonicalPath.error.code !== "not_found") {
+			diagnostics.push({
+				type: "warning",
+				code: "file_info_failed",
+				message: canonicalPath.error.message,
+				path: info.path,
+			});
+		}
+		return undefined;
+	}
+	const target = await env.fileInfo(canonicalPath.value);
+	if (!target.ok) {
+		if (target.error.code !== "not_found") {
+			diagnostics.push({
+				type: "warning",
+				code: "file_info_failed",
+				message: target.error.message,
+				path: info.path,
+			});
+		}
+		return undefined;
+	}
+	return target.value.kind === "file" || target.value.kind === "directory" ? target.value.kind : undefined;
+}
+
+function joinEnvPath(base: string, child: string): string {
+	return `${base.replace(/\/+$/, "")}/${child.replace(/^\/+/, "")}`;
+}
+
+function dirnameEnvPath(path: string): string {
+	const normalized = path.replace(/\/+$/, "");
+	const slashIndex = normalized.lastIndexOf("/");
+	return slashIndex <= 0 ? "/" : normalized.slice(0, slashIndex);
+}
+
+function basenameEnvPath(path: string): string {
+	const normalized = path.replace(/\/+$/, "");
+	const slashIndex = normalized.lastIndexOf("/");
+	return slashIndex === -1 ? normalized : normalized.slice(slashIndex + 1);
+}
+
+function relativeEnvPath(root: string, path: string): string {
+	const normalizedRoot = root.replace(/\/+$/, "");
+	const normalizedPath = path.replace(/\/+$/, "");
+	if (normalizedPath === normalizedRoot) return "";
+	return normalizedPath.startsWith(`${normalizedRoot}/`)
+		? normalizedPath.slice(normalizedRoot.length + 1)
+		: normalizedPath.replace(/^\/+/, "");
+}