@klarkxy/dsh-plugin-kit 0.1.0 → 0.3.0

package/lib/cli-process.js

@@ -0,0 +1,166 @@
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+//#region src/cli-process.ts
+var CliProcessError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "CliProcessError";
+	}
+};
+/** Own one process tree until it exits, including caller cancellation and protocol failure. */
+async function runCli(executable, args, options) {
+	options.signal.throwIfAborted();
+	const timed = AbortSignal.timeout(options.timeoutMs ?? 9e5);
+	const signal = AbortSignal.any([options.signal, timed]);
+	const maxBytes = options.maxOutputBytes ?? 16777216;
+	const maxLine = options.maxLineBytes ?? 8388608;
+	let child;
+	try {
+		child = (options.spawnChild ?? spawn)(executable.command, [...executable.args ?? [], ...args], {
+			cwd: options.cwd,
+			env: executable.env ?? process.env,
+			shell: false,
+			windowsHide: true,
+			detached: process.platform !== "win32",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+	} catch {
+		throw new CliProcessError("unavailable", "Unable to start the official CLI.");
+	}
+	let failure, total = 0, stderr = "", stdout = "", pending = Buffer.alloc(0);
+	const stdoutDecoder = new StringDecoder("utf8"), stderrDecoder = new StringDecoder("utf8");
+	let exited = false, exitCode = -1, stopping;
+	let lineWork = Promise.resolve();
+	const closed = new Promise((resolve) => {
+		child.once("close", (code) => {
+			exited = true;
+			exitCode = code ?? -1;
+			resolve();
+		});
+	});
+	const stop = () => stopping ??= (async () => {
+		if (exited) return;
+		const pid = child.pid;
+		if (pid && process.platform === "win32") await new Promise((resolve) => {
+			const killer = spawn("taskkill.exe", [
+				"/PID",
+				String(pid),
+				"/T",
+				"/F"
+			], {
+				windowsHide: true,
+				shell: false,
+				stdio: "ignore"
+			});
+			let timer;
+			const done = () => {
+				clearTimeout(timer);
+				resolve();
+			};
+			killer.once("error", () => {
+				child.kill();
+				done();
+			});
+			killer.once("close", done);
+			timer = setTimeout(() => {
+				killer.kill();
+				child.kill();
+				resolve();
+			}, 5e3);
+		});
+		else if (pid) try {
+			process.kill(-pid, "SIGTERM");
+		} catch {
+			child.kill();
+		}
+		else child.kill();
+		let timer;
+		await Promise.race([closed, new Promise((resolve) => {
+			timer = setTimeout(resolve, 2e3);
+		})]);
+		if (timer) clearTimeout(timer);
+		if (!exited) try {
+			pid && process.platform !== "win32" ? process.kill(-pid, "SIGKILL") : child.kill("SIGKILL");
+		} catch {}
+		await closed;
+	})();
+	const fail = (error) => {
+		failure ??= error;
+		stop();
+	};
+	const abort = () => fail(new CliProcessError(timed.aborted && !options.signal.aborted ? "timeout" : "cancelled", timed.aborted && !options.signal.aborted ? "The CLI request timed out." : "The CLI request was cancelled."));
+	signal.addEventListener("abort", abort, { once: true });
+	child.on("error", () => fail(new CliProcessError("unavailable", "Unable to start the official CLI.")));
+	child.stdin.on("error", () => {
+		if (!exited) fail(new CliProcessError("process-io", "The CLI input stream closed unexpectedly."));
+	});
+	child.stdout.on("error", () => fail(new CliProcessError("process-io", "The CLI output stream failed.")));
+	child.stderr.on("error", () => fail(new CliProcessError("process-io", "The CLI error stream failed.")));
+	const count = (chunk) => {
+		total += chunk.length;
+		if (total > maxBytes) {
+			fail(new CliProcessError("output-limit", "The CLI output exceeded its limit."));
+			return false;
+		}
+		return true;
+	};
+	const acceptLine = (line) => {
+		if (!options.onLine || !line.trim()) return;
+		child.stdout.pause();
+		lineWork = lineWork.then(async () => {
+			if (!failure) await options.onLine(line);
+		}).catch(fail).finally(() => child.stdout.resume());
+	};
+	child.stdout.on("data", (chunk) => {
+		if (failure || !count(chunk)) return;
+		if (!options.onLine) {
+			stdout += stdoutDecoder.write(chunk);
+			return;
+		}
+		pending = Buffer.concat([pending, chunk]);
+		for (;;) {
+			const end = pending.indexOf(10);
+			if (end < 0) break;
+			if (end > maxLine) {
+				fail(new CliProcessError("output-limit", "A CLI protocol frame exceeded its limit."));
+				return;
+			}
+			acceptLine(pending.subarray(0, end).toString("utf8"));
+			pending = pending.subarray(end + 1);
+		}
+		if (pending.length > maxLine) fail(new CliProcessError("output-limit", "A CLI protocol frame exceeded its limit."));
+	});
+	child.stderr.on("data", (chunk) => {
+		if (count(chunk)) stderr = (stderr + stderrDecoder.write(chunk)).slice(-16384);
+	});
+	try {
+		if (signal.aborted) abort();
+		if (!failure) child.stdin.end(options.input ?? "");
+		await closed;
+		stdout += stdoutDecoder.end();
+		stderr += stderrDecoder.end();
+		if (pending.length && !failure) acceptLine(pending.toString("utf8"));
+		await lineWork;
+		if (failure) throw failure;
+		signal.throwIfAborted();
+		return {
+			stdout,
+			stderr,
+			exitCode
+		};
+	} finally {
+		signal.removeEventListener("abort", abort);
+		if (!exited) await stop();
+		if (stopping) await stopping;
+	}
+}
+//#endregion
+export { CliProcessError, runCli };
+
+//# sourceMappingURL=cli-process.js.map

package/lib/cli-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process.js","names":[],"sources":["../src/cli-process.ts"],"sourcesContent":["import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'\nimport { StringDecoder } from 'node:string_decoder'\n\n/** A resolved executable, never a shell command or an argument string. */\nexport type CliExecutable = { command: string; args?: string[]; env?: NodeJS.ProcessEnv; displayPath: string }\nexport type CliOutput = { stdout: string; stderr: string; exitCode: number }\nexport class CliProcessError extends Error {\n  constructor(public readonly code: string, message: string) { super(message); this.name = 'CliProcessError' }\n}\nexport type CliOptions = {\n  cwd: string; signal: AbortSignal; input?: string; timeoutMs?: number;\n  maxOutputBytes?: number; maxLineBytes?: number;\n  onLine?: (line: string) => void | Promise<void>;\n  spawnChild?: typeof spawn;\n}\n\n/** Own one process tree until it exits, including caller cancellation and protocol failure. */\nexport async function runCli(executable: CliExecutable, args: string[], options: CliOptions): Promise<CliOutput> {\n  options.signal.throwIfAborted()\n  const timed = AbortSignal.timeout(options.timeoutMs ?? 900_000)\n  const signal = AbortSignal.any([options.signal, timed])\n  const maxBytes = options.maxOutputBytes ?? 16 * 1024 * 1024\n  const maxLine = options.maxLineBytes ?? 8 * 1024 * 1024\n  let child: ChildProcessWithoutNullStreams\n  try {\n    child = (options.spawnChild ?? spawn)(executable.command, [...(executable.args ?? []), ...args], {\n      cwd: options.cwd, env: executable.env ?? process.env, shell: false,\n      windowsHide: true, detached: process.platform !== 'win32', stdio: ['pipe', 'pipe', 'pipe'],\n    }) as ChildProcessWithoutNullStreams\n  } catch { throw new CliProcessError('unavailable', 'Unable to start the official CLI.') }\n  let failure: unknown, total = 0, stderr = '', stdout = '', pending = Buffer.alloc(0)\n  const stdoutDecoder = new StringDecoder('utf8'), stderrDecoder = new StringDecoder('utf8')\n  let exited = false, exitCode = -1, stopping: Promise<void> | undefined\n  let lineWork = Promise.resolve()\n  const closed = new Promise<void>(resolve => {\n    child.once('close', code => { exited = true; exitCode = code ?? -1; resolve() })\n  })\n  const stop = () => stopping ??= (async () => {\n    if (exited) return\n    const pid = child.pid\n    if (pid && process.platform === 'win32') {\n      await new Promise<void>(resolve => {\n        const killer = spawn('taskkill.exe', ['/PID', String(pid), '/T', '/F'], { windowsHide: true, shell: false, stdio: 'ignore' })\n        let timer: ReturnType<typeof setTimeout>\n        const done = () => { clearTimeout(timer); resolve() }\n        killer.once('error', () => { child.kill(); done() })\n        killer.once('close', done)\n        timer = setTimeout(() => { killer.kill(); child.kill(); resolve() }, 5_000)\n      })\n    } else if (pid) {\n      try { process.kill(-pid, 'SIGTERM') } catch { child.kill() }\n    } else child.kill()\n    let timer: ReturnType<typeof setTimeout> | undefined\n    await Promise.race([closed, new Promise<void>(resolve => { timer = setTimeout(resolve, 2_000) })])\n    if (timer) clearTimeout(timer)\n    if (!exited) {\n      try { pid && process.platform !== 'win32' ? process.kill(-pid, 'SIGKILL') : child.kill('SIGKILL') } catch { /* already exited */ }\n    }\n    await closed\n  })()\n  const fail = (error: unknown) => { failure ??= error; void stop() }\n  const abort = () => fail(new CliProcessError(timed.aborted && !options.signal.aborted ? 'timeout' : 'cancelled', timed.aborted && !options.signal.aborted ? 'The CLI request timed out.' : 'The CLI request was cancelled.'))\n  signal.addEventListener('abort', abort, { once: true })\n  child.on('error', () => fail(new CliProcessError('unavailable', 'Unable to start the official CLI.')))\n  child.stdin.on('error', () => { if (!exited) fail(new CliProcessError('process-io', 'The CLI input stream closed unexpectedly.')) })\n  child.stdout.on('error', () => fail(new CliProcessError('process-io', 'The CLI output stream failed.')))\n  child.stderr.on('error', () => fail(new CliProcessError('process-io', 'The CLI error stream failed.')))\n  const count = (chunk: Buffer) => {\n    total += chunk.length\n    if (total > maxBytes) { fail(new CliProcessError('output-limit', 'The CLI output exceeded its limit.')); return false }\n    return true\n  }\n  const acceptLine = (line: string) => {\n    if (!options.onLine || !line.trim()) return\n    child.stdout.pause()\n    lineWork = lineWork.then(async () => { if (!failure) await options.onLine!(line) }).catch(fail).finally(() => child.stdout.resume())\n  }\n  child.stdout.on('data', (chunk: Buffer) => {\n    if (failure || !count(chunk)) return\n    if (!options.onLine) { stdout += stdoutDecoder.write(chunk); return }\n    pending = Buffer.concat([pending, chunk])\n    for (;;) {\n      const end = pending.indexOf(10)\n      if (end < 0) break\n      if (end > maxLine) { fail(new CliProcessError('output-limit', 'A CLI protocol frame exceeded its limit.')); return }\n      acceptLine(pending.subarray(0, end).toString('utf8'))\n      pending = pending.subarray(end + 1)\n    }\n    if (pending.length > maxLine) fail(new CliProcessError('output-limit', 'A CLI protocol frame exceeded its limit.'))\n  })\n  child.stderr.on('data', (chunk: Buffer) => { if (count(chunk)) stderr = (stderr + stderrDecoder.write(chunk)).slice(-16_384) })\n  try {\n    if (signal.aborted) abort()\n    if (!failure) child.stdin.end(options.input ?? '')\n    await closed\n    stdout += stdoutDecoder.end(); stderr += stderrDecoder.end()\n    if (pending.length && !failure) acceptLine(pending.toString('utf8'))\n    await lineWork\n    if (failure) throw failure\n    signal.throwIfAborted()\n    return { stdout, stderr, exitCode }\n  } finally {\n    signal.removeEventListener('abort', abort)\n    if (!exited) await stop()\n    if (stopping) await stopping\n  }\n}\n"],"mappings":"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"}

package/lib/client-utils.d.ts

@@ -1,4 +1,10 @@
 //#region src/client-utils.d.ts
+/** Fixed pause for failing background reads; manual work is never replayed. */
+declare function createPluginReadGate(now?: () => number): {
+  canRead: () => boolean;
+  reset: () => void;
+  run<T>(read: () => Promise<T>): Promise<T>;
+};
 interface NativeSurfaceClient {
   sessions: {
     binding?(sessionId: string): {
@@ -48,5 +54,5 @@ declare function useNativeSeat(client: NativeSurfaceClient, props?: unknown): {
 /** Refresh on native log boundaries/reconnect/focus. Read-only settling is bounded to an observed job. */
 declare function useFeatureRefresh(client: NativeSurfaceClient, sessionId: string, refresh: () => void, working?: boolean, enabled?: boolean): void;
 //#endregion
-export { NativeSurfaceClient, selectedSessionId, useFeatureRefresh, useNativeSeat };
+export { NativeSurfaceClient, createPluginReadGate, selectedSessionId, useFeatureRefresh, useNativeSeat };
 //# sourceMappingURL=client-utils.d.ts.map

package/lib/client-utils.js

@@ -1,5 +1,29 @@
 import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 //#region src/client-utils.ts
+/** Fixed pause for failing background reads; manual work is never replayed. */
+function createPluginReadGate(now = Date.now) {
+	let pausedUntil = 0;
+	let epoch = 0;
+	return {
+		canRead: () => now() >= pausedUntil,
+		reset: () => {
+			epoch++;
+			pausedUntil = 0;
+		},
+		async run(read) {
+			const current = epoch;
+			try {
+				const value = await read();
+				if (current === epoch) pausedUntil = 0;
+				return value;
+			} catch (error) {
+				const message = error instanceof Error ? error.message : "";
+				if (current === epoch && (/(?:^|\s)transport failure for .+: HTTP (?:404|405|503)\b/.test(message) || error instanceof TypeError && /^(?:Failed to fetch|fetch failed|NetworkError when attempting to fetch resource\.?)$/i.test(message))) pausedUntil = now() + 3e4;
+				throw error;
+			}
+		}
+	};
+}
 /** The Editor retains its manuscript session separately; native DSH exposes the main-view binding. */
 function selectedSessionId(client) {
 	const workspace = client.uiWorkspace?.current;
@@ -89,6 +113,6 @@ function useFeatureRefresh(client, sessionId, refresh, working = false, enabled
 	]);
 }
 //#endregion
-export { selectedSessionId, useFeatureRefresh, useNativeSeat };
+export { createPluginReadGate, selectedSessionId, useFeatureRefresh, useNativeSeat };
 
 //# sourceMappingURL=client-utils.js.map

package/lib/client-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-utils.js","names":[],"sources":["../src/client-utils.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react'\n\nexport interface NativeSurfaceClient {\n  sessions: {\n    binding?(sessionId: string): { eventSource: { subscribe(listener: () => void): () => void } } | undefined\n  }\n  uiWorkspace: { current?: { getSnapshot(): { sessionId: string } | undefined; subscribe(listener: () => void): () => void } }\n  uiSession: { adapter: { current: { getSnapshot(): { key?: string }; subscribe(listener: () => void): () => void } } }\n  locale: { getSnapshot(): { active: string }; subscribe(listener: () => void): () => void }\n  connection?: { generation?: { subscribe(listener: () => void): () => void } }\n}\n\n/** The Editor retains its manuscript session separately; native DSH exposes the main-view binding. */\nexport function selectedSessionId(client: Pick<NativeSurfaceClient, 'uiWorkspace' | 'uiSession'>): string {\n  const workspace = client.uiWorkspace?.current\n  return workspace\n    ? workspace.getSnapshot()?.sessionId ?? ''\n    : client.uiSession.adapter.current.getSnapshot().key ?? ''\n}\n\n/**\n * Owner props are data the host composed, never a Cordis context: reading an\n * undeclared property off one throws instead of returning undefined, which\n * would crash the slot entry and abdicate its cell for good. Tolerate a\n * throwing read so a mistaken prop degrades to \"not supplied\".\n */\nfunction read(source: unknown, key: string): unknown {\n  if (source === null || typeof source !== 'object') return undefined\n  try {\n    return (source as Record<string, unknown>)[key]\n  } catch {\n    return undefined\n  }\n}\n\nfunction readString(source: unknown, key: string): string | undefined {\n  const value = read(source, key)\n  return typeof value === 'string' ? value : undefined\n}\n\n/** Owner props win; native settings only supplies close, so resolve its selected session. */\nexport function useNativeSeat(client: NativeSurfaceClient, props?: unknown) {\n  const current = useSyncExternalStore(\n    useCallback((fn: () => void) => (client.uiWorkspace?.current ?? client.uiSession.adapter.current).subscribe(fn), [client]),\n    useCallback(() => selectedSessionId(client), [client]),\n    () => '',\n  )\n  const language = useSyncExternalStore(\n    useCallback((fn: () => void) => client.locale.subscribe(fn), [client]),\n    useCallback(() => client.locale.getSnapshot().active, [client]),\n    () => 'en',\n  )\n  const sessionId = readString(props, 'sessionId') ?? readString(read(props, 'owner'), 'sessionId') ?? current\n  const requestedLocale = read(props, 'locale') ?? read(read(props, 'owner'), 'locale') ?? language\n  return { sessionId, locale: (String(requestedLocale).startsWith('zh') ? 'zh' : 'en') as 'zh' | 'en',\n    hidden: read(props, 'hidden') === true || read(read(props, 'owner'), 'hidden') === true }\n}\n\n/** Refresh on native log boundaries/reconnect/focus. Read-only settling is bounded to an observed job. */\nexport function useFeatureRefresh(\n  client: NativeSurfaceClient, sessionId: string, refresh: () => void,\n  working = false, enabled = true,\n): void {\n  const refreshRef = useRef(refresh)\n  refreshRef.current = refresh\n  useEffect(() => {\n    if (!enabled) return\n    let timer: ReturnType<typeof setTimeout> | undefined\n    const queue = () => {\n      if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return\n      clearTimeout(timer)\n      timer = setTimeout(() => refreshRef.current(), 150)\n    }\n    const source = sessionId ? client.sessions.binding?.(sessionId)?.eventSource : undefined\n    const stopEvents = source?.subscribe(queue)\n    const stopConnection = client.connection?.generation?.subscribe(queue)\n    const visibility = () => { if (document.visibilityState === 'visible') queue() }\n    window.addEventListener('focus', queue)\n    document.addEventListener('visibilitychange', visibility)\n    // Details are collapsed by default; opening an existing panel must get current state.\n    document.addEventListener('toggle', queue, true)\n    return () => {\n      clearTimeout(timer)\n      stopEvents?.(); stopConnection?.()\n      window.removeEventListener('focus', queue)\n      document.removeEventListener('visibilitychange', visibility)\n      document.removeEventListener('toggle', queue, true)\n    }\n  }, [client, sessionId, enabled])\n  useEffect(() => {\n    if (!enabled || !working) return\n    let delay = 250\n    const until = Date.now() + 300_000\n    let timer: ReturnType<typeof setTimeout>\n    const tick = () => {\n      if (Date.now() >= until) return\n      if (document.visibilityState !== 'hidden') refreshRef.current()\n      delay = Math.min(delay * 2, 2000)\n      timer = setTimeout(tick, delay)\n    }\n    timer = setTimeout(tick, delay)\n    return () => clearTimeout(timer)\n  }, [client, sessionId, working, enabled])\n}\n"],"mappings":"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"}
+{"version":3,"file":"client-utils.js","names":[],"sources":["../src/client-utils.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react'\n\n/** Fixed pause for failing background reads; manual work is never replayed. */\nexport function createPluginReadGate(now: () => number = Date.now) {\n  let pausedUntil = 0\n  let epoch = 0\n  return {\n    canRead: () => now() >= pausedUntil,\n    reset: () => { epoch++; pausedUntil = 0 },\n    async run<T>(read: () => Promise<T>): Promise<T> {\n      const current = epoch\n      try {\n        const value = await read()\n        if (current === epoch) pausedUntil = 0\n        return value\n      } catch (error) {\n        // The native Connection error is an Error with this exact HTTP text.\n        // Authentication, application failures, and cancellation stay distinct.\n        const message = error instanceof Error ? error.message : ''\n        if (current === epoch && (/(?:^|\\s)transport failure for .+: HTTP (?:404|405|503)\\b/.test(message)\n          || (error instanceof TypeError && /^(?:Failed to fetch|fetch failed|NetworkError when attempting to fetch resource\\.?)$/i.test(message)))) {\n          pausedUntil = now() + 30_000\n        }\n        throw error\n      }\n    },\n  }\n}\n\nexport interface NativeSurfaceClient {\n  sessions: {\n    binding?(sessionId: string): { eventSource: { subscribe(listener: () => void): () => void } } | undefined\n  }\n  uiWorkspace: { current?: { getSnapshot(): { sessionId: string } | undefined; subscribe(listener: () => void): () => void } }\n  uiSession: { adapter: { current: { getSnapshot(): { key?: string }; subscribe(listener: () => void): () => void } } }\n  locale: { getSnapshot(): { active: string }; subscribe(listener: () => void): () => void }\n  connection?: { generation?: { subscribe(listener: () => void): () => void } }\n}\n\n/** The Editor retains its manuscript session separately; native DSH exposes the main-view binding. */\nexport function selectedSessionId(client: Pick<NativeSurfaceClient, 'uiWorkspace' | 'uiSession'>): string {\n  const workspace = client.uiWorkspace?.current\n  return workspace\n    ? workspace.getSnapshot()?.sessionId ?? ''\n    : client.uiSession.adapter.current.getSnapshot().key ?? ''\n}\n\n/**\n * Owner props are data the host composed, never a Cordis context: reading an\n * undeclared property off one throws instead of returning undefined, which\n * would crash the slot entry and abdicate its cell for good. Tolerate a\n * throwing read so a mistaken prop degrades to \"not supplied\".\n */\nfunction read(source: unknown, key: string): unknown {\n  if (source === null || typeof source !== 'object') return undefined\n  try {\n    return (source as Record<string, unknown>)[key]\n  } catch {\n    return undefined\n  }\n}\n\nfunction readString(source: unknown, key: string): string | undefined {\n  const value = read(source, key)\n  return typeof value === 'string' ? value : undefined\n}\n\n/** Owner props win; native settings only supplies close, so resolve its selected session. */\nexport function useNativeSeat(client: NativeSurfaceClient, props?: unknown) {\n  const current = useSyncExternalStore(\n    useCallback((fn: () => void) => (client.uiWorkspace?.current ?? client.uiSession.adapter.current).subscribe(fn), [client]),\n    useCallback(() => selectedSessionId(client), [client]),\n    () => '',\n  )\n  const language = useSyncExternalStore(\n    useCallback((fn: () => void) => client.locale.subscribe(fn), [client]),\n    useCallback(() => client.locale.getSnapshot().active, [client]),\n    () => 'en',\n  )\n  const sessionId = readString(props, 'sessionId') ?? readString(read(props, 'owner'), 'sessionId') ?? current\n  const requestedLocale = read(props, 'locale') ?? read(read(props, 'owner'), 'locale') ?? language\n  return { sessionId, locale: (String(requestedLocale).startsWith('zh') ? 'zh' : 'en') as 'zh' | 'en',\n    hidden: read(props, 'hidden') === true || read(read(props, 'owner'), 'hidden') === true }\n}\n\n/** Refresh on native log boundaries/reconnect/focus. Read-only settling is bounded to an observed job. */\nexport function useFeatureRefresh(\n  client: NativeSurfaceClient, sessionId: string, refresh: () => void,\n  working = false, enabled = true,\n): void {\n  const refreshRef = useRef(refresh)\n  refreshRef.current = refresh\n  useEffect(() => {\n    if (!enabled) return\n    let timer: ReturnType<typeof setTimeout> | undefined\n    const queue = () => {\n      if (typeof document !== 'undefined' && document.visibilityState === 'hidden') return\n      clearTimeout(timer)\n      timer = setTimeout(() => refreshRef.current(), 150)\n    }\n    const source = sessionId ? client.sessions.binding?.(sessionId)?.eventSource : undefined\n    const stopEvents = source?.subscribe(queue)\n    const stopConnection = client.connection?.generation?.subscribe(queue)\n    const visibility = () => { if (document.visibilityState === 'visible') queue() }\n    window.addEventListener('focus', queue)\n    document.addEventListener('visibilitychange', visibility)\n    // Details are collapsed by default; opening an existing panel must get current state.\n    document.addEventListener('toggle', queue, true)\n    return () => {\n      clearTimeout(timer)\n      stopEvents?.(); stopConnection?.()\n      window.removeEventListener('focus', queue)\n      document.removeEventListener('visibilitychange', visibility)\n      document.removeEventListener('toggle', queue, true)\n    }\n  }, [client, sessionId, enabled])\n  useEffect(() => {\n    if (!enabled || !working) return\n    let delay = 250\n    const until = Date.now() + 300_000\n    let timer: ReturnType<typeof setTimeout>\n    const tick = () => {\n      if (Date.now() >= until) return\n      if (document.visibilityState !== 'hidden') refreshRef.current()\n      delay = Math.min(delay * 2, 2000)\n      timer = setTimeout(tick, delay)\n    }\n    timer = setTimeout(tick, delay)\n    return () => clearTimeout(timer)\n  }, [client, sessionId, working, enabled])\n}\n"],"mappings":"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"}

package/lib/contracts.d.ts

@@ -1,4 +1,5 @@
 import { ContextFormed } from "@deepseek-ai/dsh-llm";
+import { ModelRoute } from "@klarkxy/dsh-model-route";
 //#region src/contracts.d.ts
 /** Public, browser-safe contracts. Host implementations stay in their owning packages. */
 type ProducerSourceKind = `plugin:${string}`;
@@ -16,116 +17,6 @@ declare module '@deepseek-ai/dsh-llm' {
   }
 }
 declare function producerMessageSource(plugin: string): ProducerMessageSource;
-/** A concrete provider model. Features store this on their own settings page. */
-interface ModelRoute {
-  provider: string;
-  model: string;
-  reasoningEffort?: string;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-type ModelRole = 'normal' | 'weak' | 'strong' | 'fantasy';
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-type ModelTarget = {
-  kind: 'role';
-  role: ModelRole;
-} | {
-  kind: 'session';
-} | ({
-  kind: 'model';
-} & ModelRoute);
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface AiPolicy {
-  revision: number;
-  roles: Partial<Record<ModelRole, ModelRoute>>;
-  purposes: Record<string, ModelTarget>;
-  limits: {
-    concurrency: number;
-    timeoutMs: number;
-    maxInputChars: number;
-    maxOutputTokens: number;
-    maxAttempts: number;
-  };
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface PurposeSpec {
-  id: string;
-  label: string;
-  defaultTarget: ModelTarget;
-  maxOutputTokens?: number;
-  maxInputChars?: number;
-  timeoutMs?: number;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface ResolvedRoute extends ModelRoute {
-  source: 'override' | 'purpose' | 'default';
-  target: ModelTarget;
-  policyRevision: number;
-  inheritedRole?: ModelRole;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface AuxiliaryRequest {
-  purpose: string;
-  sessionId?: string;
-  input: string;
-  system: string;
-  sourceVersion: string;
-  contractVersion?: number;
-  promptVersion?: string;
-  schemaVersion?: string;
-  override?: ModelTarget;
-  signal?: AbortSignal;
-  isCurrent?: () => boolean;
-  priority?: 'interactive' | 'background';
-  insert?: {
-    maxChars: number;
-  };
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface UsageReceipt {
-  id: string;
-  plugin: string;
-  purpose: string;
-  sessionId?: string;
-  sourceVersion: string;
-  contractVersion?: number;
-  promptVersion?: string;
-  schemaVersion?: string;
-  route?: ResolvedRoute;
-  status: 'success' | 'failed' | 'cancelled' | 'superseded' | 'skipped';
-  attempts: number;
-  inputTokens?: number;
-  outputTokens?: number;
-  cost: number | null;
-  startedAt: number;
-  finishedAt: number;
-  error?: string;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface AuxiliaryResult {
-  text: string;
-  receipt: UsageReceipt;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface AiFeatureScope {
-  readonly plugin: string;
-  readonly signal: AbortSignal;
-  readonly active: boolean;
-  registerPurpose(spec: PurposeSpec): () => void;
-  run(request: AuxiliaryRequest): Promise<AuxiliaryResult>;
-  dispose(): void;
-}
-/** @deprecated Legacy call shape. Features should call host `llm` directly. */
-interface AiServices {
-  activate(plugin: string): AiFeatureScope;
-  importPurposes(migrationId: string, defaults: Record<string, ModelTarget>, roles?: AiPolicy['roles']): Promise<AiPolicy>;
-  getPolicy(): AiPolicy;
-  updatePolicy(policy: Omit<AiPolicy, 'revision'>, expectedRevision: number): Promise<AiPolicy>;
-  resolve(purpose: string, sessionId?: string, override?: ModelTarget): Promise<ResolvedRoute>;
-  purposes(): Array<PurposeSpec & {
-    plugin: string;
-  }>;
-  usage(): UsageReceipt[];
-}
 type RpcResult<T = unknown> = {
   ok: true;
   value: T;
@@ -260,6 +151,8 @@ interface SubagentSessionLike {
     readonly parentSession?: unknown;
     readonly origin?: unknown;
     readonly delegationDepth?: unknown;
+    readonly isSeeded?: unknown;
+    readonly classification?: unknown;
   };
 }
 /**
@@ -274,6 +167,69 @@ interface SubagentSessionLike {
 declare function isSubagentSession(session: unknown): boolean;
 /** Project keys come only from the host-validated session directory, never client input. */
 declare function projectIdFromCwd(cwd: string | undefined): string | undefined;
+/**
+ * Remote contribution for model-settings change notifications.
+ * Provided by `@klarkxy/dsh-model-hub` (`ModelSettingsChangesController`);
+ * subscribers degrade silently when that package is not installed.
+ * The stream carries invalidations only — `ready` is never a settings snapshot.
+ */
+declare const MODEL_SETTINGS_CHANGES_REMOTE: {
+  package: string;
+  descriptors: {
+    id: string;
+    service: string;
+    namespace: string;
+    method: string;
+    mode: "stream";
+    invocation: {
+      kind: "direct";
+    };
+    parameters: readonly [];
+    cancellation: {
+      parameter: "signal";
+    };
+  }[];
+};
+/**
+ * Repository extension: a native web provider announces that its local
+ * availability changed. Kind is `search` or `fetch`; id is the provider id.
+ * Listeners refresh management state and must not treat this as a network probe.
+ */
+declare const WEB_PROVIDER_AVAILABILITY_EVENT: "web/provider-availability-updated";
+/**
+ * Optional display metadata a provider may attach when it registers directly
+ * with `ctx.web`. Execution and credentials stay with the provider; this object
+ * is display-only and must never carry secret values.
+ */
+interface DshWebManagementDescriptor {
+  readonly id: string;
+  readonly label: string;
+  readonly description: string;
+  readonly defaultBaseURL?: string;
+  readonly credentialRef?: string;
+  /** True when the key is shared with another surface. The page must not delete it. */
+  readonly credentialShared?: boolean;
+  /** Optional notice naming the settings surface that owns a shared credential. */
+  readonly credentialHint?: string;
+  readonly billing: 'request' | 'model-and-tools' | 'none' | 'unknown';
+  /** Optional provider-supplied billing summary. */
+  readonly pricing?: string;
+  /** Public HTTPS page explaining provider charges. */
+  readonly pricingUrl?: string;
+  /** Public HTTPS page where the user can create an API key. */
+  readonly signupUrl?: string;
+  /** Plugin that owns configuration. Native providers keep their settings there. */
+  readonly configurationOwner?: string;
+  /** Explicit settings link supplied by the provider, never inferred from its id. */
+  readonly configurationUrl?: string;
+  /** Fixed legacy route migrated by a bundle-owned adapter; not used by native plugins. */
+  readonly legacyId?: string;
+}
+/**
+ * Host Creator agent-preset id (`agentPresets.composedPreset`).
+ * Plugins that gate Creator-only tools or prompt sections compare against this.
+ */
+declare const CREATOR_PRESET_ID = "cordis";
 //#endregion
-export { AiFeatureScope, AiPolicy, AiServices, AuxiliaryRequest, AuxiliaryResult, CHAT_EVENTS_SLOT, ContextKnowledge, EvidenceRef, KnowledgeKind, KnowledgeScope, MemoryMutationOptions, MemoryQuery, MemoryRecord, MemoryService, ModelRole, ModelRoute, ModelTarget, NewMemoryRecord, ProcedureKnowledge, ProducerMessageSource, ProducerSourceKind, PurposeSpec, ResolvedRoute, RpcResult, SubagentSessionLike, TaskCheckpoint, TaskContract, UsageReceipt, isSubagentSession, producerMessageSource, projectIdFromCwd };
+export { CHAT_EVENTS_SLOT, CREATOR_PRESET_ID, ContextKnowledge, DshWebManagementDescriptor, EvidenceRef, KnowledgeKind, KnowledgeScope, MODEL_SETTINGS_CHANGES_REMOTE, MemoryMutationOptions, MemoryQuery, MemoryRecord, MemoryService, type ModelRoute, NewMemoryRecord, ProcedureKnowledge, ProducerMessageSource, ProducerSourceKind, RpcResult, SubagentSessionLike, TaskCheckpoint, TaskContract, WEB_PROVIDER_AVAILABILITY_EVENT, isSubagentSession, producerMessageSource, projectIdFromCwd };
 //# sourceMappingURL=contracts.d.ts.map

package/lib/contracts.js

@@ -18,7 +18,9 @@ const CHAT_EVENTS_SLOT = "dsh-editor.chat.events";
 function isSubagentSession(session) {
 	const header = session?.header;
 	if (!header || typeof header !== "object") return false;
-	return Boolean(header.parentSession) || header.origin === "subagent" || Number(header.delegationDepth ?? 0) > 0;
+	if (header.origin === "subagent" || Number(header.delegationDepth ?? 0) > 0) return true;
+	const humanFork = header.isSeeded === true && (header.delegationDepth === void 0 || header.delegationDepth === 0) && header.origin === void 0 && (header.classification === void 0 || header.classification === "ordinary" || header.classification === "free");
+	return Boolean(header.parentSession) && !humanFork;
 }
 /** Project keys come only from the host-validated session directory, never client input. */
 function projectIdFromCwd(cwd) {
@@ -27,7 +29,37 @@ function projectIdFromCwd(cwd) {
 	if (!normalized) return void 0;
 	return normalized === "/" || /^[A-Za-z]:\/$/.test(normalized) ? normalized : normalized.replace(/\/+$/, "");
 }
+/**
+* Remote contribution for model-settings change notifications.
+* Provided by `@klarkxy/dsh-model-hub` (`ModelSettingsChangesController`);
+* subscribers degrade silently when that package is not installed.
+* The stream carries invalidations only — `ready` is never a settings snapshot.
+*/
+const MODEL_SETTINGS_CHANGES_REMOTE = {
+	package: "@klarkxy/dsh-model-hub",
+	descriptors: [{
+		id: "modelSettingsChanges/watch",
+		service: "modelSettingsChangesController",
+		namespace: "modelSettingsChanges",
+		method: "watch",
+		mode: "stream",
+		invocation: { kind: "direct" },
+		parameters: [],
+		cancellation: { parameter: "signal" }
+	}]
+};
+/**
+* Repository extension: a native web provider announces that its local
+* availability changed. Kind is `search` or `fetch`; id is the provider id.
+* Listeners refresh management state and must not treat this as a network probe.
+*/
+const WEB_PROVIDER_AVAILABILITY_EVENT = "web/provider-availability-updated";
+/**
+* Host Creator agent-preset id (`agentPresets.composedPreset`).
+* Plugins that gate Creator-only tools or prompt sections compare against this.
+*/
+const CREATOR_PRESET_ID = "cordis";
 //#endregion
-export { CHAT_EVENTS_SLOT, isSubagentSession, producerMessageSource, projectIdFromCwd };
+export { CHAT_EVENTS_SLOT, CREATOR_PRESET_ID, MODEL_SETTINGS_CHANGES_REMOTE, WEB_PROVIDER_AVAILABILITY_EVENT, isSubagentSession, producerMessageSource, projectIdFromCwd };
 
 //# sourceMappingURL=contracts.js.map

package/lib/contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { ContextFormed } from '@deepseek-ai/dsh-llm'\n\n/** Public, browser-safe contracts. Host implementations stay in their owning packages. */\nexport type ProducerSourceKind = `plugin:${string}`\nexport type ProducerMessageSource = { kind: ProducerSourceKind; plugin: string } & ContextFormed\n\n/**\n * V4 sessions persist the producing extension in `kind`; the retired generic\n * `plugin` wrapper is not admitted. Each feature plugin declares its own kind.\n */\ndeclare module '@deepseek-ai/dsh-llm' {\n  interface MessageSourceMap {\n    [kind: ProducerSourceKind]: ProducerMessageSource\n  }\n}\n\nexport function producerMessageSource(plugin: string): ProducerMessageSource {\n  return { kind: `plugin:${plugin}`, plugin }\n}\n\n/** A concrete provider model. Features store this on their own settings page. */\nexport interface ModelRoute { provider: string; model: string; reasoningEffort?: string }\n\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport type ModelRole = 'normal' | 'weak' | 'strong' | 'fantasy'\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport type ModelTarget = { kind: 'role'; role: ModelRole } | { kind: 'session' } | ({ kind: 'model' } & ModelRoute)\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface AiPolicy {\n  revision: number\n  roles: Partial<Record<ModelRole, ModelRoute>>\n  purposes: Record<string, ModelTarget>\n  limits: { concurrency: number; timeoutMs: number; maxInputChars: number; maxOutputTokens: number; maxAttempts: number }\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface PurposeSpec {\n  id: string\n  label: string\n  defaultTarget: ModelTarget\n  maxOutputTokens?: number\n  maxInputChars?: number\n  timeoutMs?: number\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface ResolvedRoute extends ModelRoute {\n  source: 'override' | 'purpose' | 'default'\n  target: ModelTarget\n  policyRevision: number\n  inheritedRole?: ModelRole\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface AuxiliaryRequest {\n  purpose: string\n  sessionId?: string\n  input: string\n  system: string\n  sourceVersion: string\n  contractVersion?: number\n  promptVersion?: string\n  schemaVersion?: string\n  override?: ModelTarget\n  signal?: AbortSignal\n  isCurrent?: () => boolean\n  priority?: 'interactive' | 'background'\n  insert?: { maxChars: number }\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface UsageReceipt {\n  id: string\n  plugin: string\n  purpose: string\n  sessionId?: string\n  sourceVersion: string\n  contractVersion?: number\n  promptVersion?: string\n  schemaVersion?: string\n  route?: ResolvedRoute\n  status: 'success' | 'failed' | 'cancelled' | 'superseded' | 'skipped'\n  attempts: number\n  inputTokens?: number\n  outputTokens?: number\n  cost: number | null\n  startedAt: number\n  finishedAt: number\n  error?: string\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface AuxiliaryResult { text: string; receipt: UsageReceipt }\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface AiFeatureScope {\n  readonly plugin: string\n  readonly signal: AbortSignal\n  readonly active: boolean\n  registerPurpose(spec: PurposeSpec): () => void\n  run(request: AuxiliaryRequest): Promise<AuxiliaryResult>\n  dispose(): void\n}\n/** @deprecated Legacy call shape. Features should call host `llm` directly. */\nexport interface AiServices {\n  activate(plugin: string): AiFeatureScope\n  importPurposes(migrationId: string, defaults: Record<string, ModelTarget>, roles?: AiPolicy['roles']): Promise<AiPolicy>\n  getPolicy(): AiPolicy\n  updatePolicy(policy: Omit<AiPolicy, 'revision'>, expectedRevision: number): Promise<AiPolicy>\n  resolve(purpose: string, sessionId?: string, override?: ModelTarget): Promise<ResolvedRoute>\n  purposes(): Array<PurposeSpec & { plugin: string }>\n  usage(): UsageReceipt[]\n}\n\nexport type RpcResult<T = unknown> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }\nexport const CHAT_EVENTS_SLOT = 'dsh-editor.chat.events'\nexport interface EvidenceRef { sessionId: string; seq: number; kind: 'user' | 'tool' | 'turn' | 'manual'; excerpt?: string }\nexport interface TaskContract {\n  id: string\n  sessionId: string\n  sourceVersion: string\n  revision: number\n  goal: string\n  deliverables: string[]\n  inScope: string[]\n  outOfScope: string[]\n  constraints: string[]\n  acceptance: string[]\n  assumptions: string[]\n  questions: string[]\n  evidence: EvidenceRef[]\n  readiness: 'pending' | 'clear-request' | 'user-confirmed' | 'disclosed-assumptions' | 'cancelled' | 'stale'\n  updatedAt: number\n}\nexport interface TaskCheckpoint {\n  id: string\n  sessionId: string\n  sourceVersion: string\n  contractVersion?: number\n  fromSeq: number\n  toSeq: number\n  revision: number\n  status: 'running' | 'completed' | 'failed' | 'cancelled'\n  items: Array<{ label: string; state: 'pending' | 'verified' | 'failed'; evidence: EvidenceRef[] }>\n  constraints: string[]\n  nextAction: string\n  createdAt: number\n}\nexport type KnowledgeScope = { kind: 'global' } | { kind: 'project'; projectId: string }\nexport type KnowledgeKind = 'preference' | 'project-fact' | 'decision' | 'vocabulary' | 'activity' | 'lesson'\n/** Descriptive context, never an executable instruction or authorization. */\nexport interface ContextKnowledge {\n  subject: string\n  domain: string\n  key: string\n  aliases: string[]\n  observedAt: number\n  /** The user's own time expression, not an inferred completion date. */\n  eventTime?: string\n  activityStatus?: 'planned' | 'in-progress' | 'blocked' | 'paused' | 'completed' | 'cancelled' | 'unknown'\n}\n/** A scoped method. Observations remain candidates until explicitly accepted. */\nexport interface ProcedureKnowledge {\n  origin: 'instruction' | 'observation'\n  goal: string\n  when: string[]\n  steps: string[]\n  avoid: string[]\n  verify: string[]\n}\nexport interface MemoryRecord {\n  id: string\n  revision: number\n  scope: KnowledgeScope\n  kind: KnowledgeKind\n  status: 'candidate' | 'active' | 'rejected' | 'superseded' | 'revoked' | 'deleted'\n  title: string\n  content: string\n  tags: string[]\n  evidence: EvidenceRef[]\n  exceptions: string[]\n  source: 'user' | 'memory' | 'dream' | 'self-improvement'\n  context?: ContextKnowledge\n  procedure?: ProcedureKnowledge\n  createdAt: number\n  updatedAt: number\n  expiresAt?: number\n  supersedes?: string[]\n  /** Exact record revisions behind a derived candidate; revalidated on adoption. */\n  basis?: Array<{ id: string; revision: number }>\n}\nexport type NewMemoryRecord = Omit<MemoryRecord, 'id' | 'revision' | 'createdAt' | 'updatedAt'>\nexport interface MemoryQuery { scope: KnowledgeScope; query?: string; kinds?: KnowledgeKind[]; statuses?: MemoryRecord['status'][]; limit?: number }\nexport interface MemoryMutationOptions { signal?: AbortSignal; isCurrent?: () => boolean }\nexport interface MemoryService {\n  list(query: MemoryQuery): Promise<MemoryRecord[]>\n  create(record: NewMemoryRecord, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  update(id: string, patch: Partial<Pick<MemoryRecord, 'title' | 'content' | 'tags' | 'exceptions' | 'status' | 'expiresAt'>>, expectedRevision: number, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  /** Explicit user promotion, persisted atomically on the same record; preserves expiry and evidence. */\n  promoteToGlobal(id: string, expectedRevision: number, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  remove(id: string, expectedRevision: number, options?: MemoryMutationOptions): Promise<void>\n  recall(query: MemoryQuery): Promise<MemoryRecord[]>\n}\n\n/**\n * The session creation metadata the host snapshots when it creates a delegated child\n * thread. Mirrors `CreateAgentOptions.meta` in `@deepseek-ai/dsh-agent`; it is durable\n * session data, so it survives a restart and needs no ancestry walk.\n */\nexport interface SubagentSessionLike {\n  readonly header?: {\n    readonly parentSession?: unknown\n    readonly origin?: unknown\n    readonly delegationDepth?: unknown\n  }\n}\n\n/**\n * True when `session` is a delegated child thread rather than a human-driven top-level\n * conversation.\n *\n * A message's `source.kind === 'user'` cannot answer this: a lead agent's dispatch prompt\n * is delivered as the child's own user message, so delegated work is indistinguishable\n * from a person typing once you only look at the message. Plugins use this to keep\n * automatic writes and derived model calls on top-level sessions.\n */\nexport function isSubagentSession(session: unknown): boolean {\n  const header = (session as SubagentSessionLike | null | undefined)?.header\n  if (!header || typeof header !== 'object') return false\n  return Boolean(header.parentSession)\n    || header.origin === 'subagent'\n    || Number(header.delegationDepth ?? 0) > 0\n}\n\n/** Project keys come only from the host-validated session directory, never client input. */\nexport function projectIdFromCwd(cwd: string | undefined): string | undefined {\n  if (typeof cwd !== 'string') return undefined\n  const normalized = cwd.trim().replaceAll('\\\\', '/')\n  if (!normalized) return undefined\n  return normalized === '/' || /^[A-Za-z]:\\/$/.test(normalized) ? normalized : normalized.replace(/\\/+$/, '')\n}\n"],"mappings":";AAgBA,SAAgB,sBAAsB,QAAuC;CAC3E,OAAO;EAAE,MAAM,UAAU;EAAU;CAAO;AAC5C;AA2FA,MAAa,mBAAmB;;;;;;;;;;AA+GhC,SAAgB,kBAAkB,SAA2B;CAC3D,MAAM,SAAU,SAAoD;CACpE,IAAI,CAAC,UAAU,OAAO,WAAW,UAAU,OAAO;CAClD,OAAO,QAAQ,OAAO,aAAa,KAC9B,OAAO,WAAW,cAClB,OAAO,OAAO,mBAAmB,CAAC,IAAI;AAC7C;;AAGA,SAAgB,iBAAiB,KAA6C;CAC5E,IAAI,OAAO,QAAQ,UAAU,OAAO,KAAA;CACpC,MAAM,aAAa,IAAI,KAAK,CAAC,CAAC,WAAW,MAAM,GAAG;CAClD,IAAI,CAAC,YAAY,OAAO,KAAA;CACxB,OAAO,eAAe,OAAO,gBAAgB,KAAK,UAAU,IAAI,aAAa,WAAW,QAAQ,QAAQ,EAAE;AAC5G"}
+{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["import type { ContextFormed } from '@deepseek-ai/dsh-llm'\nimport type { ModelRoute } from '@klarkxy/dsh-model-route'\n\n/**\n * The canonical home is @klarkxy/dsh-model-route; re-exported here so existing\n * plugin-kit consumers keep compiling.\n */\nexport type { ModelRoute }\n\n/** Public, browser-safe contracts. Host implementations stay in their owning packages. */\nexport type ProducerSourceKind = `plugin:${string}`\nexport type ProducerMessageSource = { kind: ProducerSourceKind; plugin: string } & ContextFormed\n\n/**\n * V4 sessions persist the producing extension in `kind`; the retired generic\n * `plugin` wrapper is not admitted. Each feature plugin declares its own kind.\n */\ndeclare module '@deepseek-ai/dsh-llm' {\n  interface MessageSourceMap {\n    [kind: ProducerSourceKind]: ProducerMessageSource\n  }\n}\n\nexport function producerMessageSource(plugin: string): ProducerMessageSource {\n  return { kind: `plugin:${plugin}`, plugin }\n}\n\nexport type RpcResult<T = unknown> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }\nexport const CHAT_EVENTS_SLOT = 'dsh-editor.chat.events'\nexport interface EvidenceRef { sessionId: string; seq: number; kind: 'user' | 'tool' | 'turn' | 'manual'; excerpt?: string }\nexport interface TaskContract {\n  id: string\n  sessionId: string\n  sourceVersion: string\n  revision: number\n  goal: string\n  deliverables: string[]\n  inScope: string[]\n  outOfScope: string[]\n  constraints: string[]\n  acceptance: string[]\n  assumptions: string[]\n  questions: string[]\n  evidence: EvidenceRef[]\n  readiness: 'pending' | 'clear-request' | 'user-confirmed' | 'disclosed-assumptions' | 'cancelled' | 'stale'\n  updatedAt: number\n}\nexport interface TaskCheckpoint {\n  id: string\n  sessionId: string\n  sourceVersion: string\n  contractVersion?: number\n  fromSeq: number\n  toSeq: number\n  revision: number\n  status: 'running' | 'completed' | 'failed' | 'cancelled'\n  items: Array<{ label: string; state: 'pending' | 'verified' | 'failed'; evidence: EvidenceRef[] }>\n  constraints: string[]\n  nextAction: string\n  createdAt: number\n}\nexport type KnowledgeScope = { kind: 'global' } | { kind: 'project'; projectId: string }\nexport type KnowledgeKind = 'preference' | 'project-fact' | 'decision' | 'vocabulary' | 'activity' | 'lesson'\n/** Descriptive context, never an executable instruction or authorization. */\nexport interface ContextKnowledge {\n  subject: string\n  domain: string\n  key: string\n  aliases: string[]\n  observedAt: number\n  /** The user's own time expression, not an inferred completion date. */\n  eventTime?: string\n  activityStatus?: 'planned' | 'in-progress' | 'blocked' | 'paused' | 'completed' | 'cancelled' | 'unknown'\n}\n/** A scoped method. Observations remain candidates until explicitly accepted. */\nexport interface ProcedureKnowledge {\n  origin: 'instruction' | 'observation'\n  goal: string\n  when: string[]\n  steps: string[]\n  avoid: string[]\n  verify: string[]\n}\nexport interface MemoryRecord {\n  id: string\n  revision: number\n  scope: KnowledgeScope\n  kind: KnowledgeKind\n  status: 'candidate' | 'active' | 'rejected' | 'superseded' | 'revoked' | 'deleted'\n  title: string\n  content: string\n  tags: string[]\n  evidence: EvidenceRef[]\n  exceptions: string[]\n  source: 'user' | 'memory' | 'dream' | 'self-improvement'\n  context?: ContextKnowledge\n  procedure?: ProcedureKnowledge\n  createdAt: number\n  updatedAt: number\n  expiresAt?: number\n  supersedes?: string[]\n  /** Exact record revisions behind a derived candidate; revalidated on adoption. */\n  basis?: Array<{ id: string; revision: number }>\n}\nexport type NewMemoryRecord = Omit<MemoryRecord, 'id' | 'revision' | 'createdAt' | 'updatedAt'>\nexport interface MemoryQuery { scope: KnowledgeScope; query?: string; kinds?: KnowledgeKind[]; statuses?: MemoryRecord['status'][]; limit?: number }\nexport interface MemoryMutationOptions { signal?: AbortSignal; isCurrent?: () => boolean }\nexport interface MemoryService {\n  list(query: MemoryQuery): Promise<MemoryRecord[]>\n  create(record: NewMemoryRecord, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  update(id: string, patch: Partial<Pick<MemoryRecord, 'title' | 'content' | 'tags' | 'exceptions' | 'status' | 'expiresAt'>>, expectedRevision: number, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  /** Explicit user promotion, persisted atomically on the same record; preserves expiry and evidence. */\n  promoteToGlobal(id: string, expectedRevision: number, options?: MemoryMutationOptions): Promise<MemoryRecord>\n  remove(id: string, expectedRevision: number, options?: MemoryMutationOptions): Promise<void>\n  recall(query: MemoryQuery): Promise<MemoryRecord[]>\n}\n\n/**\n * The session creation metadata the host snapshots when it creates a delegated child\n * thread. Mirrors `CreateAgentOptions.meta` in `@deepseek-ai/dsh-agent`; it is durable\n * session data, so it survives a restart and needs no ancestry walk.\n */\nexport interface SubagentSessionLike {\n  readonly header?: {\n    readonly parentSession?: unknown\n    readonly origin?: unknown\n    readonly delegationDepth?: unknown\n    readonly isSeeded?: unknown\n    readonly classification?: unknown\n  }\n}\n\n/**\n * True when `session` is a delegated child thread rather than a human-driven top-level\n * conversation.\n *\n * A message's `source.kind === 'user'` cannot answer this: a lead agent's dispatch prompt\n * is delivered as the child's own user message, so delegated work is indistinguishable\n * from a person typing once you only look at the message. Plugins use this to keep\n * automatic writes and derived model calls on top-level sessions.\n */\nexport function isSubagentSession(session: unknown): boolean {\n  const header = (session as SubagentSessionLike | null | undefined)?.header\n  if (!header || typeof header !== 'object') return false\n  if (header.origin === 'subagent' || Number(header.delegationDepth ?? 0) > 0) return true\n  // Native human forks also persist parentSession for history lineage. A fork's\n  // seeded header distinguishes it from legacy children whose parent is the\n  // only marker. Native rc.2 forks omit depth; patched hosts may persist zero.\n  // Explicit delegation and unknown metadata still keep the child guard.\n  const humanFork = header.isSeeded === true\n    && (header.delegationDepth === undefined || header.delegationDepth === 0)\n    && header.origin === undefined\n    && (header.classification === undefined || header.classification === 'ordinary' || header.classification === 'free')\n  return Boolean(header.parentSession) && !humanFork\n}\n\n/** Project keys come only from the host-validated session directory, never client input. */\nexport function projectIdFromCwd(cwd: string | undefined): string | undefined {\n  if (typeof cwd !== 'string') return undefined\n  const normalized = cwd.trim().replaceAll('\\\\', '/')\n  if (!normalized) return undefined\n  return normalized === '/' || /^[A-Za-z]:\\/$/.test(normalized) ? normalized : normalized.replace(/\\/+$/, '')\n}\n\n/**\n * Remote contribution for model-settings change notifications.\n * Provided by `@klarkxy/dsh-model-hub` (`ModelSettingsChangesController`);\n * subscribers degrade silently when that package is not installed.\n * The stream carries invalidations only — `ready` is never a settings snapshot.\n */\nexport const MODEL_SETTINGS_CHANGES_REMOTE = {\n  package: '@klarkxy/dsh-model-hub',\n  descriptors: [{\n    id: 'modelSettingsChanges/watch',\n    service: 'modelSettingsChangesController',\n    namespace: 'modelSettingsChanges',\n    method: 'watch',\n    mode: 'stream' as const,\n    invocation: { kind: 'direct' as const },\n    parameters: [] as const,\n    cancellation: { parameter: 'signal' as const },\n  }],\n}\n\n/**\n * Repository extension: a native web provider announces that its local\n * availability changed. Kind is `search` or `fetch`; id is the provider id.\n * Listeners refresh management state and must not treat this as a network probe.\n */\nexport const WEB_PROVIDER_AVAILABILITY_EVENT = 'web/provider-availability-updated' as const\n\n/**\n * Optional display metadata a provider may attach when it registers directly\n * with `ctx.web`. Execution and credentials stay with the provider; this object\n * is display-only and must never carry secret values.\n */\nexport interface DshWebManagementDescriptor {\n  readonly id: string\n  readonly label: string\n  readonly description: string\n  readonly defaultBaseURL?: string\n  readonly credentialRef?: string\n  /** True when the key is shared with another surface. The page must not delete it. */\n  readonly credentialShared?: boolean\n  /** Optional notice naming the settings surface that owns a shared credential. */\n  readonly credentialHint?: string\n  readonly billing: 'request' | 'model-and-tools' | 'none' | 'unknown'\n  /** Optional provider-supplied billing summary. */\n  readonly pricing?: string\n  /** Public HTTPS page explaining provider charges. */\n  readonly pricingUrl?: string\n  /** Public HTTPS page where the user can create an API key. */\n  readonly signupUrl?: string\n  /** Plugin that owns configuration. Native providers keep their settings there. */\n  readonly configurationOwner?: string\n  /** Explicit settings link supplied by the provider, never inferred from its id. */\n  readonly configurationUrl?: string\n  /** Fixed legacy route migrated by a bundle-owned adapter; not used by native plugins. */\n  readonly legacyId?: string\n}\n\n/**\n * Host Creator agent-preset id (`agentPresets.composedPreset`).\n * Plugins that gate Creator-only tools or prompt sections compare against this.\n */\nexport const CREATOR_PRESET_ID = 'cordis'\n"],"mappings":";AAuBA,SAAgB,sBAAsB,QAAuC;CAC3E,OAAO;EAAE,MAAM,UAAU;EAAU;CAAO;AAC5C;AAGA,MAAa,mBAAmB;;;;;;;;;;AAiHhC,SAAgB,kBAAkB,SAA2B;CAC3D,MAAM,SAAU,SAAoD;CACpE,IAAI,CAAC,UAAU,OAAO,WAAW,UAAU,OAAO;CAClD,IAAI,OAAO,WAAW,cAAc,OAAO,OAAO,mBAAmB,CAAC,IAAI,GAAG,OAAO;CAKpF,MAAM,YAAY,OAAO,aAAa,SAChC,OAAO,oBAAoB,KAAA,KAAa,OAAO,oBAAoB,MACpE,OAAO,WAAW,KAAA,MACjB,OAAO,mBAAmB,KAAA,KAAa,OAAO,mBAAmB,cAAc,OAAO,mBAAmB;CAC/G,OAAO,QAAQ,OAAO,aAAa,KAAK,CAAC;AAC3C;;AAGA,SAAgB,iBAAiB,KAA6C;CAC5E,IAAI,OAAO,QAAQ,UAAU,OAAO,KAAA;CACpC,MAAM,aAAa,IAAI,KAAK,CAAC,CAAC,WAAW,MAAM,GAAG;CAClD,IAAI,CAAC,YAAY,OAAO,KAAA;CACxB,OAAO,eAAe,OAAO,gBAAgB,KAAK,UAAU,IAAI,aAAa,WAAW,QAAQ,QAAQ,EAAE;AAC5G;;;;;;;AAQA,MAAa,gCAAgC;CAC3C,SAAS;CACT,aAAa,CAAC;EACZ,IAAI;EACJ,SAAS;EACT,WAAW;EACX,QAAQ;EACR,MAAM;EACN,YAAY,EAAE,MAAM,SAAkB;EACtC,YAAY,CAAC;EACb,cAAc,EAAE,WAAW,SAAkB;CAC/C,CAAC;AACH;;;;;;AAOA,MAAa,kCAAkC;;;;;AAoC/C,MAAa,oBAAoB"}

package/lib/domain.d.ts

@@ -0,0 +1,26 @@
+//#region src/domain.d.ts
+type PluginDomainSpec = {
+  version: number;
+  compatibleVersions?: readonly number[];
+  layout?: 'single' | 'per-record';
+  tables: Record<string, unknown>;
+  global?: never;
+};
+type PluginDomainHandle = {
+  table(name: string): {
+    entries(): IterableIterator<[unknown, unknown]>;
+  };
+  close(): Promise<void>;
+};
+/**
+ * Open table-only plugin state using the host's lossless legacy bootstrap.
+ * The JSON backend ignores compatibleVersions in single layout, and treats
+ * unsupported/malformed legacy files as absent in per-record layout. Probe
+ * an empty result so persistent settings cannot silently become defaults.
+ * A populated per-record tree is authoritative; the retained legacy source
+ * is an initial backup, not a current-data rollback after subsequent writes.
+ */
+declare function openCompatibleDomain<S extends PluginDomainSpec, D extends PluginDomainHandle>(open: (spec: S) => Promise<D>, spec: S): Promise<D>;
+//#endregion
+export { openCompatibleDomain };
+//# sourceMappingURL=domain.d.ts.map