@klarkxy/dsh-session-manager 0.5.0 → 0.5.1

package/lib/index.js

@@ -7,8 +7,12 @@ import { deriveEventMessage, foldSurface, isAppendSurfaceEvent } from "@deepseek
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { SessionQueryError, SessionSearchCursor } from "@deepseek-ai/dsh-session-query";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { lstat, mkdir, realpath } from "node:fs/promises";
-import { join } from "node:path";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 //#region src/contracts.ts
 /** Shared names and bounds for cross-session discovery. */
@@ -535,57 +539,89 @@ async function callLlmText(llm, request) {
 	request.signal.throwIfAborted();
 	const live = () => request.isCurrent?.() !== false && !request.signal.aborted;
 	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
-	const effort = request.route.reasoningEffort?.trim();
-	const prepared = await llm.prepareCall({
+	const started = Date.now();
+	const logBase = {
+		plugin: request.plugin,
+		feature: request.feature ?? null,
 		provider: request.route.provider,
 		model: request.route.model,
-		...effort ? { reasoningEffort: ReasoningEffortId(effort) } : {},
-		...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {}
-	}, request.signal, request.configure);
-	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
-	const maxTokens = request.maxTokens === void 0 ? prepared.config.maxTokens : Math.min(request.maxTokens, prepared.config.maxTokens ?? request.maxTokens);
-	const options = {
-		provider: prepared.config.provider,
-		model: prepared.config.model,
-		...prepared.config.reasoningEffort ? { reasoningEffort: prepared.config.reasoningEffort } : {},
-		...maxTokens !== void 0 ? { maxTokens } : {},
-		...prepared.config.temperature !== void 0 ? { temperature: prepared.config.temperature } : {},
-		...prepared.config.stop ? { stop: [...prepared.config.stop] } : {},
-		system: request.system,
-		messages: [createUserMessage({
-			source: producerMessageSource(request.plugin),
-			content: [{
-				type: "text",
-				text: buildAuxiliaryUserText(request)
-			}]
-		})],
-		signal: request.signal,
-		...request.purpose ? { purpose: request.purpose } : {},
-		...request.sessionId ? { sessionId: request.sessionId } : {}
+		purpose: request.purpose ?? null,
+		sessionId: request.sessionId ?? null
 	};
-	const assembler = await readStream(prepared.stream(options), request.signal, live);
-	if (request.signal.aborted || assembler.finish.kind === "aborted") throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
-	if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
-	if (assembler.finish.kind === "error") {
-		const code = assembler.finish.failure.code;
-		throw Object.assign(new Error(assembler.finish.failure.message || "模型调用失败。"), { code });
+	request.logger?.debug("llm.call.started", "Auxiliary model call started.", logBase);
+	try {
+		const effort = request.route.reasoningEffort?.trim();
+		const prepared = await llm.prepareCall({
+			provider: request.route.provider,
+			model: request.route.model,
+			...effort ? { reasoningEffort: ReasoningEffortId(effort) } : {},
+			...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {}
+		}, request.signal, request.configure);
+		if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+		const maxTokens = request.maxTokens === void 0 ? prepared.config.maxTokens : Math.min(request.maxTokens, prepared.config.maxTokens ?? request.maxTokens);
+		const options = {
+			provider: prepared.config.provider,
+			model: prepared.config.model,
+			...prepared.config.reasoningEffort ? { reasoningEffort: prepared.config.reasoningEffort } : {},
+			...maxTokens !== void 0 ? { maxTokens } : {},
+			...prepared.config.temperature !== void 0 ? { temperature: prepared.config.temperature } : {},
+			...prepared.config.stop ? { stop: [...prepared.config.stop] } : {},
+			system: request.system,
+			messages: [createUserMessage({
+				source: producerMessageSource(request.plugin),
+				content: [{
+					type: "text",
+					text: buildAuxiliaryUserText(request)
+				}]
+			})],
+			signal: request.signal,
+			...request.purpose ? { purpose: request.purpose } : {},
+			...request.sessionId ? { sessionId: request.sessionId } : {}
+		};
+		const assembler = await readStream(prepared.stream(options), request.signal, live);
+		if (request.signal.aborted || assembler.finish.kind === "aborted") throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+		if (!live()) throw Object.assign(/* @__PURE__ */ new Error("调用已取消。"), { name: "AbortError" });
+		if (assembler.finish.kind === "error") {
+			const code = assembler.finish.failure.code;
+			throw Object.assign(new Error(assembler.finish.failure.message || "模型调用失败。"), { code });
+		}
+		if (assembler.blocks().some((block) => block.type === "tool-call") || assembler.finish.kind === "tool-calls") throw new Error("这次调用不使用工具。");
+		if (assembler.finish.kind !== "stop") throw new Error("模型调用未完成。");
+		const usage = assembler.usage;
+		request.logger?.debug("llm.call.completed", "Auxiliary model call completed.", {
+			...logBase,
+			provider: prepared.config.provider,
+			model: prepared.config.model,
+			durationMs: Date.now() - started,
+			...usage?.inputTokens !== void 0 ? { inputTokens: usage.inputTokens } : {},
+			...usage?.outputTokens !== void 0 ? { outputTokens: usage.outputTokens } : {},
+			...usage?.totalTokens !== void 0 ? { totalTokens: usage.totalTokens } : {}
+		});
+		return {
+			text: joinText(assembler),
+			provider: prepared.config.provider,
+			model: prepared.config.model,
+			...usage ? {
+				inputTokens: usage.inputTokens,
+				outputTokens: usage.outputTokens,
+				...usage.totalTokens !== void 0 ? { totalTokens: usage.totalTokens } : {},
+				...usage.cacheReadTokens !== void 0 ? { cacheReadTokens: usage.cacheReadTokens } : {},
+				...usage.cacheWriteTokens !== void 0 ? { cacheWriteTokens: usage.cacheWriteTokens } : {},
+				...usage.reasoningTokens !== void 0 ? { reasoningTokens: usage.reasoningTokens } : {}
+			} : {}
+		};
+	} catch (error) {
+		const durationMs = Date.now() - started;
+		if (request.signal.aborted || error instanceof Error && error.name === "AbortError") request.logger?.debug("llm.call.cancelled", "Auxiliary model call cancelled.", {
+			...logBase,
+			durationMs
+		});
+		else request.logger?.warn("llm.call.failed", "Auxiliary model call failed.", error, {
+			...logBase,
+			durationMs
+		});
+		throw error;
 	}
-	if (assembler.blocks().some((block) => block.type === "tool-call") || assembler.finish.kind === "tool-calls") throw new Error("这次调用不使用工具。");
-	if (assembler.finish.kind !== "stop") throw new Error("模型调用未完成。");
-	const usage = assembler.usage;
-	return {
-		text: joinText(assembler),
-		provider: prepared.config.provider,
-		model: prepared.config.model,
-		...usage ? {
-			inputTokens: usage.inputTokens,
-			outputTokens: usage.outputTokens,
-			...usage.totalTokens !== void 0 ? { totalTokens: usage.totalTokens } : {},
-			...usage.cacheReadTokens !== void 0 ? { cacheReadTokens: usage.cacheReadTokens } : {},
-			...usage.cacheWriteTokens !== void 0 ? { cacheWriteTokens: usage.cacheWriteTokens } : {},
-			...usage.reasoningTokens !== void 0 ? { reasoningTokens: usage.reasoningTokens } : {}
-		} : {}
-	};
 }
 //#endregion
 //#region src/turns.ts
@@ -3638,12 +3674,648 @@ function num(args, key) {
 	return typeof value === "number" ? value : void 0;
 }
 //#endregion
+//#region ../dsh-plugin-kit/src/log-shared.ts
+const PLUGIN_LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fault"
+];
+const DEFAULT_PLUGIN_LOG_LEVEL = "info";
+const PLUGIN_LOG_MAX_MESSAGE_CHARS = 16e3;
+const SOURCE_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const EVENT_RE = /^[a-z][a-z0-9._-]{0,127}$/;
+const CONTEXT_KEY_RE = /^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/;
+const SECRET_KEY_RE = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|bearer|authorization|cookie|set[_-]?cookie|nonce|credential|private[_-]?key|password|secret|app[_-]?secret|client[_-]?secret|z_c0|d_c0)$/i;
+const CHAT_PAYLOAD_RE = /"role"\s*:\s*"(?:system|user|assistant|tool)"|"(?:messages|content|prompt|input_text|input_image|image_url)"\s*:\s*[\[{"']/i;
+const CREDENTIAL_BODY_RE = /-----BEGIN (?:RSA |EC |OPENSSH |PRIVATE )?PRIVATE KEY-----|"type"\s*:\s*"service_account"|credentials\.json|\.dsh[/\\](?:credentials|auth)/i;
+const AUTH_HEADER_RE = /\b(Authorization|Proxy-Authorization|Cookie|Set-Cookie)\s*:\s*[^\r\n]*/gi;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._\-+=/]{8,}/g;
+const SECRET_FIELD_RE = /(["']?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|bearer|authorization|cookie|set-cookie|nonce|credential|private[_-]?key|password|secret|app[_-]?secret|client[_-]?secret|password|z_c0|d_c0)["']?\s*[:=]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,&;}]+)/gi;
+const SECRET_QUERY_RE = /([?&](?:token|api[_-]?key|key|secret|password|bootstrap|code|sig|signature|credential|password)=)[^\s&#"']+/gi;
+const URL_CREDENTIAL_RE = /\b(https?:\/\/)[^\s/:@]+:[^\s/@]+@/gi;
+const BOOTSTRAP_RE = /\/bootstrap\/[^\s"'?&#]+/gi;
+const KNOWN_TOKEN_RE = /\b(?:sk-[A-Za-z0-9_-]{10,}|gh[pousr]_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,}|tvly-[A-Za-z0-9_-]{10,}|AKIA[0-9A-Z]{16})\b/g;
+const PATH_RE = /(?:[A-Za-z]:\\|\\\\)[^\s"'`<>|]+|(?:\/(?:home|Users|tmp|var|root)\/|~\/)[^\s"'`<>|]+/g;
+function isPluginLogLevel(value) {
+	return typeof value === "string" && PLUGIN_LOG_LEVELS.includes(value);
+}
+function pluginLogLevelEnabled(level, minimum) {
+	return PLUGIN_LOG_LEVELS.indexOf(level) >= PLUGIN_LOG_LEVELS.indexOf(minimum);
+}
+function normalizePluginLogSource(raw) {
+	const stripped = String(raw || "").trim().replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+	const bounded = (/^[a-z]/.test(stripped) ? stripped : `p-${stripped}`).slice(0, 64).replace(/-+$/g, "");
+	return SOURCE_RE.test(bounded) ? bounded : "dsh-plugin";
+}
+function normalizePluginLogEvent(raw) {
+	const cleaned = String(raw || "").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z]+/, "").slice(0, 128);
+	return EVENT_RE.test(cleaned) ? cleaned : "plugin.event";
+}
+/**
+* Parse a level specification like `debug` or `dsh-zhihu=debug,dsh-dot:warn,info`.
+* Source-specific rules win over a bare fallback level.
+*/
+function parsePluginLogLevel(spec, source, fallback = DEFAULT_PLUGIN_LOG_LEVEL) {
+	if (!spec || typeof spec !== "string") return fallback;
+	const normalizedSource = source ? normalizePluginLogSource(source) : void 0;
+	let wildcard;
+	for (const token of spec.split(",").map((part) => part.trim()).filter(Boolean)) {
+		const lowered = token.toLowerCase();
+		if (isPluginLogLevel(lowered)) {
+			wildcard = lowered;
+			continue;
+		}
+		const match = /^([^=:]+)[=:]([a-z]+)$/i.exec(token);
+		if (!match) continue;
+		const target = match[1].trim();
+		const candidate = match[2].trim().toLowerCase();
+		if (!isPluginLogLevel(candidate)) continue;
+		if (target === "*") {
+			wildcard = candidate;
+			continue;
+		}
+		if (normalizedSource && normalizePluginLogSource(target) === normalizedSource) return candidate;
+	}
+	return wildcard ?? fallback;
+}
+function sanitizePluginLogText(text, maxChars = PLUGIN_LOG_MAX_MESSAGE_CHARS) {
+	if (!text) return "";
+	if (CREDENTIAL_BODY_RE.test(text)) return "[omitted credential material]";
+	if (CHAT_PAYLOAD_RE.test(text)) return "[omitted chat payload]";
+	return truncateLogText(text.replace(AUTH_HEADER_RE, "$1: [redacted]").replace(BEARER_RE, "Bearer [redacted]").replace(SECRET_FIELD_RE, (full, prefix) => {
+		const value = full.slice(prefix.length);
+		if (value.startsWith("\"")) return `${prefix}"[redacted]"`;
+		if (value.startsWith("'")) return `${prefix}'[redacted]'`;
+		return `${prefix}[redacted]`;
+	}).replace(SECRET_QUERY_RE, "$1[redacted]").replace(URL_CREDENTIAL_RE, "$1[redacted]@").replace(BOOTSTRAP_RE, "/bootstrap/[redacted]").replace(KNOWN_TOKEN_RE, "[redacted]").replace(PATH_RE, "[path]"), maxChars);
+}
+function sanitizePluginLogContext(input) {
+	if (!input) return void 0;
+	const output = {};
+	for (const [key, value] of Object.entries(input).slice(0, 32)) {
+		if (value === void 0 || !CONTEXT_KEY_RE.test(key)) continue;
+		if (typeof value === "number" && !Number.isFinite(value)) continue;
+		if (SECRET_KEY_RE.test(key)) {
+			output[key] = "[redacted]";
+			continue;
+		}
+		output[key] = typeof value === "string" ? sanitizePluginLogText(value, 1e3) : value;
+	}
+	if (!Object.keys(output).length) return void 0;
+	if (JSON.stringify(output).length <= 8e3) return output;
+	return {
+		omitted: true,
+		reason: "Diagnostic context exceeded its size limit."
+	};
+}
+function sanitizePluginLogError(error) {
+	if (error === void 0) return void 0;
+	const row = error && typeof error === "object" ? error : {};
+	const rawMessage = typeof row.message === "string" ? row.message : String(error);
+	const result = {
+		name: typeof row.name === "string" && row.name.trim() ? truncateLogText(row.name.trim(), 100) : "Error",
+		message: sanitizePluginLogText(rawMessage) || "Unknown error"
+	};
+	if (typeof row.stack === "string" && row.stack.trim()) result.stack = sanitizePluginLogText(row.stack, 24e3);
+	if (typeof row.code === "string" && /^[A-Za-z0-9_./:-]{1,100}$/.test(row.code)) result.code = row.code;
+	else if (typeof row.code === "number" && Number.isFinite(row.code)) result.code = String(row.code);
+	return result;
+}
+function mergePluginLogContext(base, extra) {
+	if (!base) return extra;
+	if (!extra) return base;
+	return {
+		...base,
+		...extra
+	};
+}
+function buildPluginLogEntry(input, meta) {
+	const entry = {
+		version: 1,
+		at: meta.at.toISOString(),
+		level: isPluginLogLevel(input.level) ? input.level : "info",
+		source: normalizePluginLogSource(meta.source),
+		surface: meta.surface,
+		...meta.profile ? { profile: meta.profile } : {},
+		event: normalizePluginLogEvent(input.event),
+		message: sanitizePluginLogText(input.message || "No diagnostic message was provided.", PLUGIN_LOG_MAX_MESSAGE_CHARS),
+		...meta.pid !== void 0 ? { pid: meta.pid } : {}
+	};
+	const context = sanitizePluginLogContext(mergePluginLogContext(meta.correlation, input.context));
+	if (context) entry.context = context;
+	const error = sanitizePluginLogError(input.error);
+	if (error) entry.error = error;
+	return entry;
+}
+function createChildPluginLogger(parent, bound) {
+	return {
+		get source() {
+			return parent.source;
+		},
+		get file() {
+			return parent.file;
+		},
+		get lastWriteError() {
+			return parent.lastWriteError;
+		},
+		debug: (event, message, context) => parent.debug(event, message, mergePluginLogContext(bound, context)),
+		info: (event, message, context) => parent.info(event, message, mergePluginLogContext(bound, context)),
+		warn: (event, message, error, context) => parent.warn(event, message, error, mergePluginLogContext(bound, context)),
+		error: (event, message, error, context) => parent.error(event, message, error, mergePluginLogContext(bound, context)),
+		fault: (event, message, error, context) => parent.fault(event, message, error, mergePluginLogContext(bound, context)),
+		write: (input) => parent.write({
+			...input,
+			context: mergePluginLogContext(bound, input.context)
+		}),
+		child: (next) => createChildPluginLogger(parent, mergePluginLogContext(bound, next) ?? {})
+	};
+}
+function truncateLogText(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	const marker = "[truncated]\n";
+	if (maxChars <= 12) return text.slice(0, Math.max(0, maxChars));
+	return `${marker}${text.slice(-(maxChars - 12))}`;
+}
+const PROFILE_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+const ARCHIVE_RE = /^[a-z][a-z0-9-]{0,63}\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}\.\d{3}Z\.\d+\.\d+\.jsonl$/;
+const correlationStorage = new AsyncLocalStorage();
+const processFileLoggers = /* @__PURE__ */ new Map();
+let operationSequence = 0;
+function safeProfileName(profile) {
+	const trimmed = String(profile ?? "").trim();
+	if (PROFILE_RE.test(trimmed)) return trimmed.toLowerCase();
+	const cleaned = trimmed.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+	return cleaned && PROFILE_RE.test(cleaned) ? cleaned : "default";
+}
+function pluginLogDirectory(home, profile = "default") {
+	return join(resolve(home), "logs", "plugins", safeProfileName(profile));
+}
+function resolveHostLogTarget(ctx, options = {}) {
+	const env = options.env ?? process.env;
+	if (options.directory?.trim()) {
+		const dir = resolve(options.directory.trim());
+		return {
+			directory: dir,
+			anchor: dir,
+			...options.profile ? { profile: safeProfileName(options.profile) } : {}
+		};
+	}
+	if (options.home?.trim()) {
+		const home = resolve(options.home.trim());
+		const profile = safeProfileName(options.profile);
+		return {
+			directory: pluginLogDirectory(home, profile),
+			anchor: home,
+			profile
+		};
+	}
+	if (env.DSH_PLUGIN_LOG_DIR?.trim()) {
+		const dir = resolve(env.DSH_PLUGIN_LOG_DIR.trim());
+		return {
+			directory: dir,
+			anchor: dir,
+			...options.profile ? { profile: safeProfileName(options.profile) } : {}
+		};
+	}
+	const host = ctx && typeof ctx === "object" ? ctx : void 0;
+	let profileCtx;
+	try {
+		profileCtx = host?.get?.("profileContext", false);
+	} catch {
+		try {
+			profileCtx = host?.get?.("profileContext");
+		} catch {
+			profileCtx = void 0;
+		}
+	}
+	if (typeof profileCtx?.home === "string" && profileCtx.home.trim() && typeof profileCtx.dir === "string" && profileCtx.dir.trim()) {
+		const home = resolve(profileCtx.home.trim());
+		const dir = resolve(profileCtx.dir.trim());
+		if (isInside(home, dir)) {
+			const profile = safeProfileName(typeof profileCtx.name === "string" ? profileCtx.name : basename(dir));
+			return {
+				directory: pluginLogDirectory(home, profile),
+				anchor: home,
+				profile
+			};
+		}
+	}
+	if (!Boolean(env.VITEST || env.NODE_TEST_CONTEXT) && typeof host?.baseUrl === "string" && host.baseUrl.trim()) {
+		const basePath = pathFromBaseUrl(host.baseUrl);
+		const configuredHome = resolve((env.DSH_HOME?.trim() || join(homedir(), ".dsh")).trim());
+		const profilesRoot = join(configuredHome, "profiles");
+		if (basePath && isInside(profilesRoot, basePath) && !samePath(profilesRoot, basePath)) {
+			const firstSegment = basePath.slice(profilesRoot.length).replace(/^[/\\]+/, "").split(/[/\\]/)[0];
+			if (firstSegment) {
+				const profile = safeProfileName(firstSegment);
+				return {
+					directory: pluginLogDirectory(configuredHome, profile),
+					anchor: configuredHome,
+					profile
+				};
+			}
+		}
+	}
+	return {
+		directory: null,
+		anchor: null,
+		...options.profile ? { profile: safeProfileName(options.profile) } : {}
+	};
+}
+/**
+* Synchronous, append-only rotating JSONL logger modeled on DSH Spaces
+* diagnostics: 7-day or 100 MiB active rotation, 7-day / 100 MiB archive
+* retention, secret and path redaction, and non-throwing write resilience.
+*/
+var RotatingPluginLogger = class {
+	source;
+	file;
+	lastError = null;
+	size = 0;
+	openedAt = 0;
+	initialized = false;
+	writing = false;
+	sequence = 0;
+	loggedWriteFailure = false;
+	recent = [];
+	directory;
+	anchor;
+	profile;
+	minimum;
+	now;
+	pid;
+	maxFileBytes;
+	maxArchiveBytes;
+	maxAgeMs;
+	recentLimit;
+	constructor(source, options = {}) {
+		this.source = normalizePluginLogSource(source);
+		const env = options.env ?? process.env;
+		const resolved = options.directory !== void 0 || options.home !== void 0 ? resolveHostLogTarget(void 0, options) : {
+			directory: null,
+			anchor: options.anchor ?? null,
+			profile: options.profile
+		};
+		this.directory = resolved.directory;
+		this.anchor = options.anchor ?? resolved.anchor;
+		this.profile = options.profile ?? resolved.profile;
+		this.file = this.directory ? join(this.directory, `${this.source}.jsonl`) : null;
+		this.minimum = options.minimumLevel ?? parsePluginLogLevel(env.DSH_PLUGIN_LOG_LEVEL, this.source, "info");
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+		this.pid = options.pid ?? process.pid;
+		this.maxFileBytes = options.maxFileBytes ?? 104857600;
+		this.maxArchiveBytes = options.maxArchiveBytes ?? 104857600;
+		this.maxAgeMs = options.maxAgeMs ?? 6048e5;
+		this.recentLimit = Math.max(1, options.recentLimit ?? 200);
+	}
+	get lastWriteError() {
+		return this.lastError;
+	}
+	recentEntries(limit = this.recentLimit) {
+		return this.recent.slice(-Math.max(0, limit));
+	}
+	debug(event, message, context) {
+		return this.write({
+			level: "debug",
+			event,
+			message,
+			...context ? { context } : {}
+		});
+	}
+	info(event, message, context) {
+		return this.write({
+			level: "info",
+			event,
+			message,
+			...context ? { context } : {}
+		});
+	}
+	warn(event, message, error, context) {
+		return this.write({
+			level: "warn",
+			event,
+			message,
+			...error !== void 0 ? { error } : {},
+			...context ? { context } : {}
+		});
+	}
+	error(event, message, error, context) {
+		return this.write({
+			level: "error",
+			event,
+			message,
+			...error !== void 0 ? { error } : {},
+			...context ? { context } : {}
+		});
+	}
+	fault(event, message, error, context) {
+		return this.write({
+			level: "fault",
+			event,
+			message,
+			...error !== void 0 ? { error } : {},
+			...context ? { context } : {}
+		});
+	}
+	child(context) {
+		return createChildPluginLogger(this, context);
+	}
+	write(input) {
+		if (!pluginLogLevelEnabled(input.level, this.minimum) || this.writing) return false;
+		const at = this.now();
+		let entry;
+		let line;
+		try {
+			entry = buildPluginLogEntry(input, {
+				at,
+				source: this.source,
+				surface: "host",
+				profile: this.profile,
+				pid: this.pid,
+				correlation: correlationStorage.getStore()
+			});
+			line = `${JSON.stringify(entry)}\n`;
+		} catch {
+			return false;
+		}
+		this.pushRecent(entry);
+		if (!this.directory || !this.file) return true;
+		this.writing = true;
+		try {
+			this.openManagedDirectory();
+			this.prepare(at);
+			if (this.size > 0 && (this.size + Buffer.byteLength(line) > this.maxFileBytes || at.getTime() - this.openedAt >= this.maxAgeMs)) this.rotate(at);
+			appendFileSync(this.file, line, {
+				encoding: "utf8",
+				mode: 384
+			});
+			this.size += Buffer.byteLength(line);
+			this.prune(at);
+			this.lastError = null;
+			this.loggedWriteFailure = false;
+			return true;
+		} catch (error) {
+			const detail = sanitizePluginLogText(error instanceof Error ? error.message : String(error), 500);
+			this.lastError = `The plugin diagnostic log could not be written: ${detail}`;
+			this.initialized = false;
+			if (!this.loggedWriteFailure) {
+				this.loggedWriteFailure = true;
+				try {
+					process.stderr.write(`DSH Plugin (${this.source}): ${this.lastError}. The original operation continues unchanged.\n`);
+				} catch {}
+			}
+			return false;
+		} finally {
+			this.writing = false;
+		}
+	}
+	pushRecent(entry) {
+		this.recent.push(entry);
+		const overflow = this.recent.length - this.recentLimit;
+		if (overflow > 0) this.recent.splice(0, overflow);
+	}
+	prepare(at) {
+		if (this.initialized || !this.file) return;
+		this.openManagedDirectory();
+		const stat = this.regularFile(this.file);
+		this.size = stat?.size ?? 0;
+		const stamps = stat ? [stat.birthtimeMs, stat.mtimeMs].filter((value) => value > 0) : [];
+		this.openedAt = stamps.length ? Math.min(...stamps) : at.getTime();
+		this.initialized = true;
+	}
+	rotate(at) {
+		if (!this.directory || !this.file) return;
+		const stamp = at.toISOString().replace(/:/g, "-");
+		const name = `${this.source}.${stamp}.${this.pid}.${this.sequence++}.jsonl`;
+		if (!ARCHIVE_RE.test(name)) throw new Error("Diagnostic log archive name is invalid.");
+		const archive = join(this.directory, name);
+		if (lexists(archive)) throw new Error("Diagnostic log archive already exists.");
+		try {
+			renameSync(this.file, archive);
+		} catch (error) {
+			if (error.code === "ENOENT") {
+				this.size = 0;
+				this.openedAt = at.getTime();
+				return;
+			}
+			throw error;
+		}
+		this.size = 0;
+		this.openedAt = at.getTime();
+	}
+	rotateStaleActive(at) {
+		if (!this.file) return;
+		const stat = this.regularFile(this.file);
+		if (!stat || stat.size === 0) return;
+		if (at.getTime() - stat.mtimeMs < this.maxAgeMs) return;
+		this.rotate(at);
+	}
+	prune(at) {
+		if (!this.directory) return;
+		this.rotateStaleActive(at);
+		const archives = [];
+		let total = 0;
+		for (const name of readdirSync(this.directory)) {
+			if (!ARCHIVE_RE.test(name) || !name.startsWith(`${this.source}.`)) continue;
+			const file = join(this.directory, name);
+			const stat = lstatSync(file);
+			if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Diagnostic log archive is not a regular file.");
+			if (at.getTime() - stat.mtimeMs >= this.maxAgeMs) {
+				try {
+					unlinkSync(file);
+				} catch {}
+				continue;
+			}
+			archives.push({
+				name,
+				size: stat.size,
+				mtime: stat.mtimeMs
+			});
+			total += stat.size;
+		}
+		archives.sort((left, right) => left.mtime - right.mtime || left.name.localeCompare(right.name));
+		while (total > this.maxArchiveBytes && archives.length) {
+			const oldest = archives.shift();
+			try {
+				unlinkSync(join(this.directory, oldest.name));
+			} catch {}
+			total -= oldest.size;
+		}
+	}
+	openManagedDirectory() {
+		if (!this.directory) return;
+		if (this.anchor) {
+			if ((existsSync(this.anchor) ? lstatSync(this.anchor) : void 0)?.isSymbolicLink()) throw new Error("Diagnostic log anchor cannot be a symbolic link.");
+		}
+		mkdirSync(this.directory, {
+			recursive: true,
+			mode: 448
+		});
+		const stat = lstatSync(this.directory);
+		if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Diagnostic log directory is not a real directory.");
+		const realDir = realpathSync(this.directory);
+		if (this.anchor) {
+			if (!isInside(realpathSync(this.anchor), realDir)) throw new Error("Diagnostic log directory escaped its managed root.");
+		}
+	}
+	regularFile(file) {
+		try {
+			const stat = lstatSync(file);
+			if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Diagnostic log is not a regular file.");
+			const expected = join(realpathSync(dirname(file)), basename(file));
+			if (!samePath(realpathSync(file), expected)) throw new Error("Diagnostic log path could not be verified.");
+			return stat;
+		} catch (error) {
+			if (error.code === "ENOENT") return void 0;
+			throw error;
+		}
+	}
+};
+function createPluginLogger(ctxOrSource, maybeSource, maybeOptions) {
+	const hasCtx = typeof ctxOrSource !== "string";
+	const ctx = hasCtx ? ctxOrSource : void 0;
+	const source = hasCtx ? String(maybeSource ?? "dsh-plugin") : ctxOrSource;
+	const options = (hasCtx ? maybeOptions : maybeSource) ?? {};
+	const normalized = normalizePluginLogSource(source);
+	const target = resolveHostLogTarget(ctx, options);
+	let backing;
+	if (Boolean(target.directory && options.minimumLevel === void 0 && options.now === void 0 && options.pid === void 0 && options.maxFileBytes === void 0 && options.maxArchiveBytes === void 0 && options.maxAgeMs === void 0) && target.directory) {
+		const key = resolve(target.directory, `${normalized}.jsonl`);
+		let shared = processFileLoggers.get(key);
+		if (!shared) {
+			shared = new RotatingPluginLogger(normalized, {
+				...options,
+				directory: target.directory,
+				anchor: target.anchor,
+				profile: target.profile
+			});
+			processFileLoggers.set(key, shared);
+		}
+		backing = shared;
+	} else backing = new RotatingPluginLogger(normalized, {
+		...options,
+		...target.directory ? {
+			directory: target.directory,
+			anchor: target.anchor
+		} : {},
+		...target.profile ? { profile: target.profile } : {}
+	});
+	if (options.forwardHostWarnError === false || !ctx || typeof ctx !== "object") return backing;
+	return wrapWithHostForwarding(backing, ctx);
+}
+function wrapWithHostForwarding(backing, host) {
+	const forward = (input) => {
+		if (input.level !== "warn" && input.level !== "error" && input.level !== "fault") return;
+		try {
+			const hostLogger = host.logger;
+			if (!hostLogger) return;
+			const detail = input.error instanceof Error ? `${input.message} (${input.error.message})` : input.error !== void 0 ? `${input.message} (${String(input.error)})` : input.message;
+			const text = sanitizePluginLogText(`${backing.source} [${input.event}]: ${detail}`, 1e3);
+			if (input.level === "warn") {
+				if (typeof hostLogger.warn === "function") hostLogger.warn(text);
+			} else if (typeof hostLogger.error === "function") hostLogger.error(text);
+			else if (typeof hostLogger.warn === "function") hostLogger.warn(text);
+		} catch {}
+	};
+	const wrapped = {
+		get source() {
+			return backing.source;
+		},
+		get file() {
+			return backing.file;
+		},
+		get lastWriteError() {
+			return backing.lastWriteError;
+		},
+		debug: (event, message, context) => backing.debug(event, message, context),
+		info: (event, message, context) => backing.info(event, message, context),
+		warn: (event, message, error, context) => {
+			const wrote = backing.warn(event, message, error, context);
+			forward({
+				level: "warn",
+				event,
+				message,
+				error,
+				context
+			});
+			return wrote;
+		},
+		error: (event, message, error, context) => {
+			const wrote = backing.error(event, message, error, context);
+			forward({
+				level: "error",
+				event,
+				message,
+				error,
+				context
+			});
+			return wrote;
+		},
+		fault: (event, message, error, context) => {
+			const wrote = backing.fault(event, message, error, context);
+			forward({
+				level: "fault",
+				event,
+				message,
+				error,
+				context
+			});
+			return wrote;
+		},
+		write: (input) => {
+			const wrote = backing.write(input);
+			forward(input);
+			return wrote;
+		},
+		child: (context) => createChildPluginLogger(wrapped, context)
+	};
+	return wrapped;
+}
+function nextPluginOperationId(prefix = "op") {
+	return `${normalizePluginLogSource(prefix)}-${process.pid}-${++operationSequence}`;
+}
+function withPluginLogContext(context, action) {
+	const merged = mergePluginLogContext(correlationStorage.getStore(), context) ?? {};
+	return correlationStorage.run(merged, action);
+}
+function lexists(file) {
+	try {
+		lstatSync(file);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+function pathFromBaseUrl(baseUrl) {
+	try {
+		return baseUrl.includes("://") ? resolve(fileURLToPath(baseUrl)) : resolve(baseUrl);
+	} catch {
+		return null;
+	}
+}
+function samePath(left, right) {
+	const a = resolve(left);
+	const b = resolve(right);
+	return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function isInside(root, target) {
+	const rootResolved = resolve(root);
+	const targetResolved = resolve(target);
+	if (samePath(rootResolved, targetResolved)) return true;
+	const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
+	return process.platform === "win32" ? targetResolved.toLowerCase().startsWith(prefix.toLowerCase()) : targetResolved.startsWith(prefix);
+}
+//#endregion
 //#region ../dsh-plugin-kit/src/host-rpc.ts
 /** The shared authenticated HTTP boundary. Each plugin still owns its RPC envelope semantics. */
 function registerHostRpcTransport(ctx, channel, dispatch, options = {}) {
 	const bodyLimit = options.maxBodyBytes ?? 65536;
 	if (!Number.isSafeInteger(bodyLimit) || bodyLimit <= 0) throw new Error("Invalid RPC body limit");
 	const isEndpoint = options.isEndpoint ?? ((endpoint) => /^[a-z.]+$/.test(endpoint));
+	const log = options.logger;
 	return ctx.webServer.register({
 		kind: "prefix",
 		path: channel,
@@ -3654,29 +4326,54 @@ function registerHostRpcTransport(ctx, channel, dispatch, options = {}) {
 				else res.writeHead(status);
 				res.end(override ?? options.errorBody?.(status, error) ?? (status === 500 ? "rpc request failed" : ""));
 			};
+			let endpoint = "";
 			try {
 				if (typeof ctx.connection.requestRejection !== "function") {
+					log?.error("rpc.admission.unavailable", "Host RPC admission policy is unavailable.", void 0, {
+						channel,
+						status: 503
+					});
 					reject(503);
 					return;
 				}
 				const rejection = ctx.connection.requestRejection(req);
 				if (rejection !== void 0) {
+					log?.warn("rpc.admission.rejected", "Host RPC request rejected by connection policy.", void 0, {
+						channel,
+						status: rejection
+					});
 					reject(rejection);
 					return;
 				}
 				const pathname = new URL(req.url ?? "/", "http://dsh.internal").pathname;
-				const endpoint = pathname.startsWith(`${channel}/`) ? pathname.slice(channel.length + 1) : "";
+				endpoint = pathname.startsWith(`${channel}/`) ? pathname.slice(channel.length + 1) : "";
 				if (req.method !== "POST" || !isEndpoint(endpoint)) {
+					log?.debug("rpc.route.rejected", "Host RPC route or method rejected.", {
+						channel,
+						endpoint: endpoint || null,
+						method: req.method ?? null,
+						status: 404
+					});
 					reject(404);
 					return;
 				}
 				const contentType = String(req.headers["content-type"] ?? "").split(";", 1)[0]?.trim();
 				if ((options.caseInsensitiveContentType ? contentType.toLowerCase() : contentType) !== "application/json") {
+					log?.debug("rpc.content-type.rejected", "Host RPC content-type rejected.", {
+						channel,
+						endpoint,
+						status: 415
+					});
 					reject(415);
 					return;
 				}
 				const guarded = options.beforeBody?.(req, endpoint);
 				if (guarded) {
+					log?.debug("rpc.guard.rejected", "Host RPC request rejected before body read.", {
+						channel,
+						endpoint,
+						status: guarded.status
+					});
 					reject(guarded.status, void 0, guarded.body);
 					return;
 				}
@@ -3690,6 +4387,11 @@ function registerHostRpcTransport(ctx, channel, dispatch, options = {}) {
 					const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
 					size += buffer.length;
 					if (size > bodyLimit) {
+						log?.warn("rpc.body.too-large", "Host RPC request exceeded body limit.", void 0, {
+							channel,
+							endpoint,
+							maxBodyBytes: bodyLimit
+						});
 						reject(413);
 						req.destroy();
 						return;
@@ -3700,11 +4402,26 @@ function registerHostRpcTransport(ctx, channel, dispatch, options = {}) {
 				try {
 					body = JSON.parse(Buffer.concat(chunks).toString("utf8") || (options.emptyBodyAsNull ? "null" : ""));
 				} catch {
+					log?.debug("rpc.body.invalid-json", "Host RPC request body is not valid JSON.", {
+						channel,
+						endpoint,
+						status: 400
+					});
 					reject(400);
 					return;
 				}
-				await dispatch(endpoint, body, controller.signal, res);
+				if (log) await withPluginLogContext({
+					rpcChannel: channel,
+					rpcEndpoint: endpoint,
+					operationId: nextPluginOperationId("rpc")
+				}, () => dispatch(endpoint, body, controller.signal, res));
+				else await dispatch(endpoint, body, controller.signal, res);
 			} catch (error) {
+				log?.error("rpc.dispatch.failed", "Unhandled host RPC handler error.", error, {
+					channel,
+					endpoint: endpoint || null,
+					status: 500
+				});
 				reject(500, error);
 			}
 		}
@@ -3725,19 +4442,41 @@ function sendHostRpcResponse(response, rpcId, result, noStore = true) {
 }
 /** Safe host RPC registration. Missing requestRejection fails closed. */
 function registerHostRpc(ctx, channel, call, options = {}) {
+	const log = options.logger;
 	return registerHostRpcTransport(ctx, channel, async (endpoint, body, signal, res) => {
 		if (!body || typeof body !== "object" || Array.isArray(body)) {
+			log?.debug("rpc.envelope.invalid", "Host RPC envelope must be a JSON object.", {
+				channel,
+				endpoint
+			});
 			res.writeHead(400);
 			res.end();
 			return;
 		}
 		const request = body;
 		if (request.type !== "client-request" || request.method !== endpoint || typeof request.rpcId !== "string" || options.requirePayload && !Object.hasOwn(request, "payload")) {
+			log?.debug("rpc.envelope.invalid", "Host RPC envelope failed validation.", {
+				channel,
+				endpoint
+			});
 			res.writeHead(400);
 			res.end();
 			return;
 		}
+		const started = Date.now();
 		const raw = await call(endpoint, request.payload, signal);
+		const durationMs = Date.now() - started;
+		if (raw.ok) log?.debug("rpc.call.completed", "Host RPC call succeeded.", {
+			channel,
+			endpoint,
+			durationMs
+		});
+		else log?.warn("rpc.call.error", "Host RPC call returned an application error.", void 0, {
+			channel,
+			endpoint,
+			code: raw.error?.code ?? null,
+			durationMs
+		});
 		const result = raw.ok ? raw : {
 			...raw,
 			error: {
@@ -4794,7 +5533,9 @@ function registerSessionManagerRpc(root, transport, config, models, modelStore,
 * A populated per-record tree is authoritative; the retained legacy source
 * is an initial backup, not a current-data rollback after subsequent writes.
 */
-async function openCompatibleDomain(open, spec) {
+async function openCompatibleDomain(open, spec, options) {
+	const log = options?.logger;
+	const domainName = options?.domainName ?? (typeof spec.name === "string" ? spec.name : "plugin-domain");
 	const perRecord = {
 		...spec,
 		layout: "per-record"
@@ -4806,7 +5547,13 @@ async function openCompatibleDomain(open, spec) {
 	} finally {
 		if (!populated) await domain.close();
 	}
-	if (populated) return domain;
+	if (populated) {
+		log?.debug("domain.opened", "Opened populated per-record storage domain.", {
+			domain: domainName,
+			version: spec.version
+		});
+		return domain;
+	}
 	let mismatch;
 	for (const version of /* @__PURE__ */ new Set([spec.version, ...spec.compatibleVersions ?? []])) try {
 		await (await open({
@@ -4815,11 +5562,26 @@ async function openCompatibleDomain(open, spec) {
 			version,
 			compatibleVersions: []
 		})).close();
+		log?.info("domain.probed", "Opened storage domain after legacy probe.", {
+			domain: domainName,
+			probedVersion: version,
+			targetVersion: spec.version
+		});
 		return open(perRecord);
 	} catch (error) {
-		if (!error || typeof error !== "object" || !("code" in error) || error.code !== "version-mismatch") throw error;
+		if (!error || typeof error !== "object" || !("code" in error) || error.code !== "version-mismatch") {
+			log?.error("domain.open-failed", "Storage domain open failed during legacy probe.", error, {
+				domain: domainName,
+				probedVersion: version
+			});
+			throw error;
+		}
 		mismatch = error;
 	}
+	log?.error("domain.version-mismatch", "Storage domain version is incompatible.", mismatch, {
+		domain: domainName,
+		targetVersion: spec.version
+	});
 	throw mismatch;
 }
 //#endregion
@@ -5117,7 +5879,13 @@ function setSharedModel(state, ctx, input, expectedRevision) {
 	if ((Boolean(row.provider) || Boolean(row.model)) && !modelRouteOverride(normalized)) return Promise.reject(/* @__PURE__ */ new Error("Invalid model route"));
 	const commit = state.tail.then(async () => {
 		if (state.closed || !state.domain) throw new Error("Auxiliary model settings are unloading; retry in a moment");
-		if (expectedRevision !== state.data.revision) throw conflictError("Auxiliary model settings changed; reload and retry");
+		if (expectedRevision !== state.data.revision) {
+			createPluginLogger(ctx, "dsh-plugin-kit", { forwardHostWarnError: false }).warn("auxiliary-model.conflict", "Auxiliary model update rejected due to revision conflict.", void 0, {
+				expectedRevision: Number(expectedRevision),
+				currentRevision: state.data.revision
+			});
+			throw conflictError("Auxiliary model settings changed; reload and retry");
+		}
 		const next = {
 			revision: state.data.revision + 1,
 			model: modelRouteOverride(normalized) ?? null
@@ -5127,6 +5895,11 @@ function setSharedModel(state, ctx, input, expectedRevision) {
 			model: next.model
 		});
 		state.data = next;
+		createPluginLogger(ctx, "dsh-plugin-kit", { forwardHostWarnError: false }).info("auxiliary-model.updated", "Updated global auxiliary model default.", {
+			revision: next.revision,
+			provider: next.model?.provider ?? null,
+			model: next.model?.model ?? null
+		});
 		notifyModelSettingsChanged(ctx.root, AUXILIARY_MODEL_NS, next.revision);
 		return next;
 	});
@@ -5134,6 +5907,7 @@ function setSharedModel(state, ctx, input, expectedRevision) {
 	return commit;
 }
 function initScope(state, ctx, scope) {
+	const log = createPluginLogger(ctx, "dsh-plugin-kit", { forwardHostWarnError: false });
 	const generation = ++state.generation;
 	let disposed = false;
 	scope.effect(() => () => {
@@ -5165,6 +5939,11 @@ function initScope(state, ctx, scope) {
 		};
 		state.error = void 0;
 		state.available = true;
+		log.info("auxiliary-model.opened", "Shared auxiliary model store opened.", {
+			generation,
+			revision: state.data.revision,
+			hasModel: Boolean(state.data.model)
+		});
 		scope.effect(() => registerModelSettings(scope, {
 			ns: AUXILIARY_MODEL_NS,
 			title: {
@@ -5248,7 +6027,10 @@ function initScope(state, ctx, scope) {
 					message: `Unknown endpoint: ${endpoint}`
 				}
 			};
-		}, { isEndpoint: (endpoint) => /^[a-z.]+$/.test(endpoint) }));
+		}, {
+			isEndpoint: (endpoint) => /^[a-z.]+$/.test(endpoint),
+			logger: log
+		}));
 		createModelSettingsChanges(scope, AUXILIARY_MODEL_CHANGES_IDENTITY, AUXILIARY_MODEL_NS);
 		scope.effect(() => () => {
 			if (state.generation === generation) {
@@ -5257,6 +6039,8 @@ function initScope(state, ctx, scope) {
 			}
 		});
 	})().catch((error) => {
+		if (error && typeof error === "object" && error[RECOVERABLE]) log.debug("auxiliary-model.superseded", "Shared auxiliary model init superseded during open.", { generation });
+		else log.error("auxiliary-model.init-failed", "Shared auxiliary model store failed to open.", error, { generation });
 		if (error && typeof error === "object") error.auxGeneration = generation;
 		if (state.generation === generation) {
 			state.available = false;
@@ -5280,6 +6064,7 @@ function teardown(state, ctx) {
 			try {
 				await state.fiber?.dispose();
 			} catch (error) {
+				createPluginLogger(ctx, "dsh-plugin-kit", { forwardHostWarnError: false }).fault("auxiliary-model.dispose-failed", "Shared auxiliary model owner fiber failed to dispose.", error);
 				try {
 					ctx.logger?.warn("auxiliary-model: fiber dispose failed", error);
 				} catch {}