better-dsh 0.0.0 → 0.2.2-a

package/lib/kernel-env-hxaihi9C.js

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+//#region src/kernel-env.ts
+const execFileAsync = promisify(execFile);
+/** The installed package root (where `lib/` and `src/` live): the default home of the managed venv. */
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+/** The config value meaning "no explicit interpreter — auto-manage a venv". */
+const AUTO_PYTHON_SENTINEL = "python3";
+/** Preferred CPython version for a managed venv. */
+const DEFAULT_KERNEL_PYTHON_VERSION = "3.11";
+/** Pinned, tested `ipykernel` version (2026-09-02 tested value; upgrade = explicit change + regression). */
+const IPYKERNEL_VERSION = "7.3.0";
+/** Pinned, tested `dill` version. */
+const DILL_VERSION = "0.4.1";
+/** A probe that never imports user modules and reports exactly what we need. */
+const PROBE_CODE = [
+	"import json, sys",
+	"r = {\"version\": sys.version.split()[0], \"ipykernel\": False, \"dill\": False}",
+	"try:",
+	"    import ipykernel  # noqa: F401",
+	"    r[\"ipykernel\"] = True",
+	"except Exception:",
+	"    pass",
+	"try:",
+	"    import dill  # noqa: F401",
+	"    r[\"dill\"] = True",
+	"except Exception:",
+	"    pass",
+	"print(json.dumps(r))"
+].join("\n");
+async function probePython(python) {
+	try {
+		const { stdout } = await execFileAsync(python, ["-c", PROBE_CODE], { timeout: 15e3 });
+		const parsed = JSON.parse(stdout.trim());
+		return {
+			version: typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "unknown",
+			ipykernel: parsed.ipykernel === true,
+			dill: parsed.dill === true
+		};
+	} catch {
+		return null;
+	}
+}
+/** The venv interpreter path for this platform. */
+function venvPythonPath(venvDir) {
+	return process.platform === "win32" ? join(venvDir, "Scripts", "python.exe") : join(venvDir, "bin", "python");
+}
+async function commandExists(cmd) {
+	try {
+		await execFileAsync(cmd, ["--version"], { timeout: 1e4 });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Tool-cache env for uv: caches live NEXT TO the venv (plugin territory), so a read-only home can never block provisioning. */
+function uvToolEnv(venvDir) {
+	const cacheDir = join(dirname(venvDir), ".uv-cache");
+	return {
+		...process.env,
+		UV_CACHE_DIR: cacheDir,
+		UV_PYTHON_INSTALL_DIR: join(cacheDir, "python"),
+		UV_LINK_MODE: "copy"
+	};
+}
+/** uv venv arguments (pure; unit-tested). */
+function uvVenvArgs(venvDir, pythonVersion) {
+	return [
+		"venv",
+		venvDir,
+		"--python",
+		pythonVersion
+	];
+}
+/** python3 -m venv fallback arguments (pure; cache-free by construction). */
+function venvFallbackArgs(venvDir) {
+	return [
+		"-m",
+		"venv",
+		venvDir
+	];
+}
+/** uv pip install arguments with pinned versions (pure; unit-tested). */
+function uvInstallArgs(python) {
+	return [
+		"pip",
+		"install",
+		"--python",
+		python,
+		"--quiet",
+		`ipykernel==${IPYKERNEL_VERSION}`,
+		`dill==${DILL_VERSION}`
+	];
+}
+/** pip install arguments with pinned versions for the venv interpreter (pure). */
+function pipInstallArgs() {
+	return [
+		"-m",
+		"pip",
+		"install",
+		"--quiet",
+		"--disable-pip-version-check",
+		`ipykernel==${IPYKERNEL_VERSION}`,
+		`dill==${DILL_VERSION}`
+	];
+}
+/** Create the venv (when absent) and return its interpreter path. */
+async function createVenv(venvDir, pythonVersion) {
+	const python = venvPythonPath(venvDir);
+	if (existsSync(python)) return python;
+	if (await commandExists("uv")) {
+		mkdirSync(join(dirname(venvDir), ".uv-cache"), { recursive: true });
+		await execFileAsync("uv", uvVenvArgs(venvDir, pythonVersion), {
+			timeout: 12e4,
+			env: uvToolEnv(venvDir)
+		});
+	} else await execFileAsync("python3", venvFallbackArgs(venvDir), { timeout: 12e4 });
+	return python;
+}
+/** Install pinned `ipykernel` + `dill` into the venv interpreter. */
+async function installDeps(python, venvDir) {
+	if (await commandExists("uv")) await execFileAsync("uv", uvInstallArgs(python), {
+		timeout: 18e4,
+		env: uvToolEnv(venvDir)
+	});
+	else await execFileAsync(python, pipInstallArgs(), { timeout: 18e4 });
+}
+/** Provision (or repair) the managed venv so it has `ipykernel` + `dill`. */
+async function ensureVenv(venvDir, pythonVersion, log) {
+	const python = venvPythonPath(venvDir);
+	const existing = existsSync(python) ? await probePython(python) : null;
+	if (existing?.ipykernel === true && existing.dill === true) return python;
+	await createVenv(venvDir, pythonVersion);
+	if (!existsSync(python)) throw new Error(`dashr-repl: managed kernel venv was not created at ${venvDir} (no interpreter at ${python})`);
+	log?.("info", `dashr-repl: provisioning kernel venv at ${venvDir} (ipykernel + dill)`);
+	await installDeps(python, venvDir);
+	return python;
+}
+/**
+* Resolve the kernel interpreter, provisioning a managed venv when no
+* explicit interpreter is configured. Throws when the resolved interpreter
+* cannot run `ipykernel`; a missing `dill` only disables snapshots (warned).
+*/
+async function resolveKernelEnv(options = {}) {
+	const log = options.log;
+	const explicit = options.python !== void 0 && options.python !== "" && options.python !== AUTO_PYTHON_SENTINEL ? options.python : void 0;
+	if (explicit !== void 0) {
+		const probe$1 = await probePython(explicit);
+		if (probe$1 === null) throw new Error(`dashr-repl: kernel python ${JSON.stringify(explicit)} could not be executed — check the path`);
+		if (!probe$1.ipykernel) throw new Error(`dashr-repl: kernel python ${JSON.stringify(explicit)} has no ipykernel — install it (pip install ipykernel) or set python to a managed venv`);
+		if (!probe$1.dill) log?.("warn", `dashr-repl: kernel python ${JSON.stringify(explicit)} has no dill — namespace snapshots are DISABLED (install it: pip install dill)`);
+		return {
+			python: explicit,
+			managed: false,
+			venvDir: void 0,
+			dill: probe$1.dill,
+			ipykernel: true,
+			version: probe$1.version
+		};
+	}
+	const venvDir = options.venvDir ?? join(PACKAGE_ROOT, ".venv-kernel");
+	const python = venvPythonPath(venvDir);
+	if (options.autoInstall === false) {
+		const probe$1 = await probePython(python);
+		if (probe$1 === null || !probe$1.ipykernel) throw new Error(`dashr-repl: managed kernel venv is missing or incomplete at ${venvDir} — run 'npm run kernel:venv' in the dashr package, or set kernelAutoInstall: true (or python to a prepared interpreter)`);
+		if (!probe$1.dill) log?.("warn", `dashr-repl: kernel venv at ${venvDir} has no dill — namespace snapshots are DISABLED (run 'npm run kernel:venv' to reinstall)`);
+		return {
+			python,
+			managed: true,
+			venvDir,
+			dill: probe$1.dill,
+			ipykernel: true,
+			version: probe$1.version
+		};
+	}
+	const resolved = await ensureVenv(venvDir, options.pythonVersion ?? DEFAULT_KERNEL_PYTHON_VERSION, log);
+	const probe = await probePython(resolved);
+	if (probe === null || !probe.ipykernel) throw new Error(`dashr-repl: managed kernel venv at ${venvDir} still has no ipykernel after provisioning — check uv/python3-venv availability and retry`);
+	if (!probe.dill) log?.("warn", `dashr-repl: managed kernel venv at ${venvDir} has no dill after provisioning — namespace snapshots are DISABLED`);
+	return {
+		python: resolved,
+		managed: true,
+		venvDir,
+		dill: probe.dill,
+		ipykernel: true,
+		version: probe.version
+	};
+}
+
+//#endregion
+export { PACKAGE_ROOT as a, uvInstallArgs as c, venvFallbackArgs as d, IPYKERNEL_VERSION as i, uvToolEnv as l, DEFAULT_KERNEL_PYTHON_VERSION as n, pipInstallArgs as o, DILL_VERSION as r, resolveKernelEnv as s, AUTO_PYTHON_SENTINEL as t, uvVenvArgs as u };

package/lib/kernel-env.d.ts

@@ -0,0 +1,80 @@
+//#region src/kernel-env.d.ts
+/**
+ * Kernel environment resolution and provisioning.
+ *
+ * The runtime OWNS the interpreter it spawns: it never trusts a bare
+ * `python3` on the PATH, because that interpreter may lack `ipykernel`
+ * (hard failure — the kernel cannot start) or `dill` (snapshot capability —
+ * silently degrading to no snapshots). Instead it resolves one of two
+ * environments:
+ *
+ * - **Explicit** — `config.python` names a real interpreter (a path, or any
+ *   name other than the bare-`python3` sentinel the default/patch produce).
+ *   It is probed, and a missing `ipykernel` is a loud error while a missing
+ *   `dill` is a loud warning (snapshots disabled).
+ * - **Managed** — no explicit interpreter: the runtime provisions a venv
+ *   UNDER THE PACKAGE (`<packageRoot>/.venv-kernel`, or `config.kernelEnvDir`)
+ *   with `ipykernel` + `dill`, installing it on first use when
+ *   `config.kernelAutoInstall` is on. The venv lives beside the package, NOT
+ *   in `/tmp` (the pre-v0.1.9 dangling-symlink failure mode), so it survives
+ *   the host's tmp reaper and the process restart.
+ *
+ * Provisioning uses `uv` when available (fast, can fetch the pinned CPython
+ * version), falling back to `python3 -m venv` + `ensurepip`. It is idempotent:
+ * a complete venv is reused untouched; a partial one is repaired.
+ * @module dashr/kernel-env
+ */
+/** The installed package root (where `lib/` and `src/` live): the default home of the managed venv. */
+declare const PACKAGE_ROOT: string;
+/** The config value meaning "no explicit interpreter — auto-manage a venv". */
+declare const AUTO_PYTHON_SENTINEL = "python3";
+/** Preferred CPython version for a managed venv. */
+declare const DEFAULT_KERNEL_PYTHON_VERSION = "3.11";
+/** Pinned, tested `ipykernel` version (2026-09-02 tested value; upgrade = explicit change + regression). */
+declare const IPYKERNEL_VERSION = "7.3.0";
+/** Pinned, tested `dill` version. */
+declare const DILL_VERSION = "0.4.1";
+interface KernelEnv {
+  /** Absolute path to the interpreter to spawn (`-m ipykernel_launcher`). */
+  python: string;
+  /** True when this runtime provisioned a venv (vs an explicit interpreter). */
+  managed: boolean;
+  /** The managed venv root, when {@link managed}. */
+  venvDir: string | undefined;
+  /** True when `dill` is importable — snapshot capability is available. */
+  dill: boolean;
+  /** True when `ipykernel` is importable (a hard requirement). */
+  ipykernel: boolean;
+  /** The interpreter's reported version, e.g. `3.11.15`. */
+  version: string;
+}
+interface ResolveKernelEnvOptions {
+  /** `config.python`; the bare sentinel (or absent) selects a managed venv. */
+  python?: string;
+  /** Managed venv directory; defaults to `<packageRoot>/.venv-kernel`. */
+  venvDir?: string;
+  /** Preferred CPython version for the managed venv. */
+  pythonVersion?: string;
+  /** Provision the managed venv when missing/incomplete (default true). */
+  autoInstall?: boolean;
+  /** Logger callback (info on provisioning, warn on degraded snapshot). */
+  log?: (level: 'info' | 'warn', message: string) => void;
+}
+/** Tool-cache env for uv: caches live NEXT TO the venv (plugin territory), so a read-only home can never block provisioning. */
+declare function uvToolEnv(venvDir: string): NodeJS.ProcessEnv;
+/** uv venv arguments (pure; unit-tested). */
+declare function uvVenvArgs(venvDir: string, pythonVersion: string): string[];
+/** python3 -m venv fallback arguments (pure; cache-free by construction). */
+declare function venvFallbackArgs(venvDir: string): string[];
+/** uv pip install arguments with pinned versions (pure; unit-tested). */
+declare function uvInstallArgs(python: string): string[];
+/** pip install arguments with pinned versions for the venv interpreter (pure). */
+declare function pipInstallArgs(): string[];
+/**
+ * Resolve the kernel interpreter, provisioning a managed venv when no
+ * explicit interpreter is configured. Throws when the resolved interpreter
+ * cannot run `ipykernel`; a missing `dill` only disables snapshots (warned).
+ */
+declare function resolveKernelEnv(options?: ResolveKernelEnvOptions): Promise<KernelEnv>;
+//#endregion
+export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, KernelEnv, PACKAGE_ROOT, ResolveKernelEnvOptions, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };

package/lib/kernel-env.js

@@ -0,0 +1,3 @@
+import { a as PACKAGE_ROOT, c as uvInstallArgs, d as venvFallbackArgs, i as IPYKERNEL_VERSION, l as uvToolEnv, n as DEFAULT_KERNEL_PYTHON_VERSION, o as pipInstallArgs, r as DILL_VERSION, s as resolveKernelEnv, t as AUTO_PYTHON_SENTINEL, u as uvVenvArgs } from "./kernel-env-hxaihi9C.js";
+
+export { AUTO_PYTHON_SENTINEL, DEFAULT_KERNEL_PYTHON_VERSION, DILL_VERSION, IPYKERNEL_VERSION, PACKAGE_ROOT, pipInstallArgs, resolveKernelEnv, uvInstallArgs, uvToolEnv, uvVenvArgs, venvFallbackArgs };

package/lib/py-sdk-BCaOGYz7.d.ts

@@ -0,0 +1,125 @@
+//#region src/py-sdk.d.ts
+/**
+ * DASHR kernel SDK codegen — Python flavor, cell edition.
+ *
+ * The pure projection from one calling scope's visible tool schemas to the
+ * Python SDK text the model programs against inside `eval` cells. The
+ * type-rendering machinery is ported from `@deepseek-ai/dsh-tools`
+ * `py-types.ts` (0.1.0-rc.6) per blueprint §7.4, deliberately slimmed to
+ * DASHR's single-language, stateful surface:
+ *
+ * - The usage instructions are OURS, not upstream's: upstream promises a
+ *   one-shot program ("runs as the body of an async function", value-less
+ *   between calls), while a DASHR cell runs on a PERSISTENT kernel whose
+ *   variables, imports, and definitions survive across `eval` calls.
+ *   The prose here must never state the throwaway contract.
+ * - No language table and no context-free renderer: DASHR renders Python
+ *   only, and object shapes always render through the named-`TypedDict`
+ *   path this module owns. (Upstream's exported `jsonSchemaToPy` degrades
+ *   every object to `dict[str, Any]`; reusing it would lose the shape.)
+ * - The bare-identifier rule, `camelCase` derivation, class-name capping
+ *   and collision suffixing, `typing` import emission, and the
+ *   deterministic lexicographic member order are ported near-verbatim: the
+ *   parseability invariants (NFKC stability, reserved words, unprintable
+ *   escapes, bracket-nesting cap) exist because the emitted block is the
+ *   model's ONLY declaration of the tools, and a syntax error in it poisons
+ *   the whole mode.
+ * - renders one `tool.<name>(args) -> Output` member per tool — no `Tools`
+ *   protocol and no `tools` singleton — matching the kernel's `tool`
+ *   object holder. Which names may render as members is decided by
+ *   {@link isFlatBindableName}, the one policy the renderer and the bridge
+ *   share.
+ * @module dashr-repl/py-sdk
+ */
+/**
+ * One tool as the SDK renderer sees it: the model-facing schema
+ * (name/description/parameters) plus the tool's canonical output schema.
+ * The caller (the presentation plugin) excludes `eval` itself and reads
+ * both through the tool registry's public projection APIs.
+ */
+interface DASHRSdkSchema {
+  /** Tool name as registered (may be exotic; the renderer routes non-bindable names to not-callable comments). */
+  readonly name: string;
+  /** Tool description, rendered as the method docstring. */
+  readonly description: string;
+  /** Validated JSON-Schema node for the arguments object. */
+  readonly parameters: unknown;
+  /** Validated JSON-Schema node for the canonical output value. */
+  readonly output: unknown;
+}
+/**
+ * Whether a tool name can be emitted AND bound as a `tool` member — the ONE
+ * policy shared by this renderer and the bridge's binding
+ * loop (src/index.ts), so the catalog never promises a name the kernel does
+ * not bind. Strictly narrower than the runtime's validation: the
+ * language-portable identifier subset (`[A-Za-z_][A-Za-z0-9_]*`, ASCII — a
+ * non-ASCII XID name is legal CPython but not portable, so the runtime
+ * refuses it as a binding global and the catalog must not teach it), minus
+ * every portable reserved word (ECMAScript ∪ Python — `type` and `match`
+ * are legal Python but reserved on the seam), minus the seam's reserved
+ * binding globals (`console`, dunders), minus underscore-leading names
+ * (kernel-shim prefix plus the call-site hazards; not callable as taught
+ * flat globals). The runtime's `validateBindings` remains the authoritative
+ * backstop: everything this accepts, it accepts.
+ */
+declare function isFlatBindableName(name: string): boolean;
+/**
+ * Render the `dashr:tool-catalog` prompt section body from the registry
+ * schemas: the cell-flavored usage instructions above, the
+ * `ToolCallError` declaration, one named `TypedDict` per tool argument or
+ * output object (and per nested object), and one
+ * `tool.<name>(args: XArgs) -> XOutput` member per visible tool — no `Tools`
+ * protocol, no `tools` singleton, every tool is a member of the `tool`
+ * object exactly as the kernel binds it — inside one fenced
+ * ```python block. The `typing` import line lists exactly the symbols the
+ * render used (and is omitted entirely when none are).
+ *
+ * Deterministic — tools are emitted in lexicographic name order and class
+ * declarations precede the function that references them in that same
+ * order (nested classes before the parent that references them), so an
+ * unchanged tool set produces byte-identical text across assemblies.
+ *
+ * Non-bindable names (reserved, exotic, or underscore-leading) render as
+ * comment lines: they are registered upstream but NOT callable from cells,
+ * and the comment keeps the signature and description visible instead of
+ * silently dropping the tool.
+ * @param schemas - the calling scope's visible tools (caller excludes
+ *   `eval` and the masked delegation names).
+ * @returns the complete section body.
+ */
+declare function renderToolsSdkPy(schemas: readonly DASHRSdkSchema[]): string;
+/**
+ * The `dashr:tool-catalog` section's presentation mode (design D4):
+ * `'signatures'` renders one compact declaration line per visible tool
+ * (the omp code-mode shape: `name(args: {…})` per line, argument and output
+ * sketches abbreviated to depth 2 — the default, chosen for low-tier model
+ * robustness); `'convention'` renders the one-sentence calling convention
+ * alone (zero repetition, the A/B deployment experiment's other arm).
+ * Both modes keep the output contract (each tool's canonical JSON output
+ * shape) and the non-flat-name exception; neither presents a REPL binding
+ * listing — the declaration lines themselves are the authoritative surface.
+ */
+type ReplBridgeCatalogMode = 'signatures' | 'convention';
+/** The deployed presentation mode; flip to `'convention'` to ship arm A. */
+declare const REPL_BRIDGE_CATALOG_MODE: ReplBridgeCatalogMode;
+/**
+ * Render the `dashr:tool-catalog` prompt section body as the REPL bridge
+ * instructions (design D4/D5): the scripting-pad positioning and the
+ * calling convention above, then — in the default `'signatures'` mode —
+ * one compact declaration line per visible tool
+ * (`tool.<name>(args: {…}) -> <output shape>`, omp code-mode shape with
+ * the output contract kept), inside one fenced ```python block.
+ * Non-bindable names (reserved, exotic, underscore-leading) are omitted
+ * from the lines; the convention sentence above states that limit once.
+ *
+ * Deterministic — lines are emitted in lexicographic name order, so an
+ * unchanged tool set produces byte-identical text across assemblies.
+ * @param schemas - the calling scope's visible tools (the caller already
+ *   excluded the transport and the wire-masked names).
+ * @param mode - override the deployed {@link REPL_BRIDGE_CATALOG_MODE}
+ *   (the two render states; tests exercise both).
+ * @returns the complete section body.
+ */
+declare function renderReplBridgeInstructions(schemas: readonly DASHRSdkSchema[], mode?: ReplBridgeCatalogMode): string;
+//#endregion
+export { renderReplBridgeInstructions as a, isFlatBindableName as i, REPL_BRIDGE_CATALOG_MODE as n, renderToolsSdkPy as o, ReplBridgeCatalogMode as r, DASHRSdkSchema as t };