@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10-11

package/src/bridges/eval-environment-schemas.ts

@@ -0,0 +1,52 @@
+import type { EvalSchemaResult } from "./schema-bridge.ts";
+
+export type NamedEvalSchema = Extract<EvalSchemaResult, { readonly name: string }>;
+
+/**
+ * The on-demand documentation for package environments and isolated cells (`tool_schema("eval:environments")` and
+ * `tool_schema("eval:isolation")`). Like the other virtual entries they are never listed, never run anything, and add
+ * nothing to the eval prompt or input schema. Every magic, code and message named here is the one the source emits.
+ */
+export const environmentsEntry: NamedEvalSchema = {
+	name: "eval:environments",
+	description: [
+		"Host magic cells: a cell whose first code line (blank and comment lines skipped) is one of these runs on the host, in the language kernel's queue, so it orders with ordinary cells and a queued one is removed by stop like any queued cell. A magic followed by more code is refused: put it on its own cell, then run the code that uses it in the next cell.",
+		"py: %pip install <requirements ...> installs into the session's environment (a trailing backslash continues the line). Result: installed <packages> into <mode> (revision <n>); already-imported modules stay cached until reset.",
+		"js: %bun add <packages ...> or %npm add <packages ...> (install is accepted as a synonym of add). Result: added <packages> with <installer> into <mode>[ (revision <n>)]; already-imported modules stay cached until reset. A package the project's own node_modules still shadows is named with environment_resolution_conflict in the result.",
+		"py and js: %environment managed | project selects where installs go. managed (the default) uses per-session revisions under the session's artifacts directory (or environments.managedRoot) and never touches project files; project installs into the session directory (py: .senpi/python-packages; js: the project root).",
+		"py and js: %load <file> runs a local file as a cell, read when its turn comes in the queue, with the file's name in tracebacks; definitions persist like any cell. It accepts a path relative to the session directory, local:// or file://, reads files up to 8 MiB and never fetches remote URLs.",
+		"Installs pause the run budget like a bridge call, stream the installer's output into the cell, detach past the foreground window like any cell, and are stopped by stop.",
+		'js and py: packages.install(manager, requirements, {timeout?}) runs the same install as a call instead of a magic: manager "pip" in a Python cell, "bun" or "npm" in a JavaScript cell; requirements is a non-empty string or a non-empty list of non-empty strings, and timeout is a positive number of seconds (default 600; py spells it packages.install("pip", [...], timeout=...)). pip receives the requirement list as separate arguments, never re-split; a js package spec cannot contain whitespace. It drives the same session environment the magic uses, returns that install\'s receipt (py: manager, mode, root, revision, requested, resolved, changed; js: installer, mode, revision, added, shadowed) and is cancelled by stop like a magic install. Unlike the magic, the installer\'s output is not streamed into the cell: the receipt is the result, and a failure carries the installer\'s stderr tail.',
+		"Install failures are cell errors that start with their code: environment_install_failed (an argument the host rejects: an unknown manager, an empty requirement list, a bun/npm requirement with whitespace or a non-positive timeout; or an installer failure, with the installer's stderr tail. A JS options value that is not an object, or a Python timeout that float() cannot convert, fails earlier in the cell with a plain TypeError or ValueError), environment_install_timeout (a packages.install() still running after its timeout, default 600 s, was stopped), environment_install_cancelled (stopped before or during the install), environment_installer_unavailable (no interpreter or no pip; no JavaScript package environment in this session; neither bun nor npm on PATH, or the chosen one missing; the installer failed to start; installs turned off with environments.autoProvision: false; or pip asked of a session with no Python interpreter, or bun/npm asked of a Python cell), environment_resolution_conflict (py: pip reported a dependency conflict). A %load failure, and a magic refused because more code follows it, are plain cell errors without a code.",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			"%pip": { description: "py: %pip install <requirements ...>" },
+			"%bun": { description: "js: %bun add <packages ...>" },
+			"%npm": { description: "js: %npm add <packages ...>" },
+			"%environment": { enum: ["managed", "project"] },
+			"%load": { description: "py and js: %load <path | local://... | file://...>" },
+			"packages.install": {
+				description: "js and py: packages.install(manager, requirements, {timeout?}) (py: timeout=...)",
+			},
+		},
+	},
+};
+
+export const isolationEntry: NamedEvalSchema = {
+	name: "eval:isolation",
+	description: [
+		"isolate: true runs one JavaScript cell in a fresh QuickJS sandbox instead of the persistent kernel. It is available only when sandbox.enabled is on in the codemode settings; only then does the eval input schema carry the isolate field. An older senpi drops the field and would run the code as an ordinary cell, so check this entry before relying on it.",
+		'Requests are refused with eval_isolate_invalid when sandbox cells are turned off, when language is not "js", when isolate is not a boolean, with reset: true (a sandbox cell always starts fresh), or when eval runs through a proxy that cannot isolate a cell.',
+		"An isolated cell shares nothing with the kernel. Its globals are print, display, text, image, console, exit, tool.<name>(args) (also reachable as tools), ALL_TOOLS (the names and descriptions of the tools it may call), load and store. Its tool calls go through the host, so permission hooks still apply, and tool calls still pending when the script settles are aborted. The store is rejected: load returns nothing and store fails with eval_isolate_no_state.",
+		"Limits: sandbox.timeoutSeconds (default 300) and sandbox.memoryMb (default 64; SENPI_CODEMODE_SANDBOX_MEMORY_MB overrides it). The result's runtime names quickjs and its version, with isolation sandbox.",
+		"Failures start with their code: eval_isolate_timeout, eval_isolate_aborted, eval_isolate_memory_limit, eval_isolate_unresolved_promise (the script ended with a promise still pending), eval_isolate_no_state, eval_isolate_unavailable (the sandbox itself failed: it could not load, or its worker crashed, exited or lost its output; if that happened after the script started, tool calls the cell made may already have run, so check their effects before retrying).",
+	].join("\n"),
+	parameters: {
+		type: "object",
+		properties: {
+			isolate: { type: "boolean", description: 'true with language: "js" runs the cell in a fresh sandbox' },
+		},
+	},
+};

package/src/bridges/eval-virtual-schemas.ts

@@ -1,3 +1,4 @@
+import { environmentsEntry, isolationEntry, type NamedEvalSchema } from "./eval-environment-schemas.ts";
 import type { EvalSchemaResult } from "./schema-bridge.ts";
 
 /**
@@ -22,7 +23,7 @@ const handleRefSchema = {
 	required: ["kind", "id", "run_epoch"],
 } as const;
 
-const waitEntry: EvalSchemaResult = {
+const waitEntry: NamedEvalSchema = {
 	name: "eval:wait",
 	description: [
 		"wait(handles, {timeout?, mode?}) blocks the cell until the given handles settle (js: await wait(...); py/rb: wait(...); jl: wait(handle(node)) or wait([handle(a), handle(b)])).",
@@ -44,7 +45,7 @@ const waitEntry: EvalSchemaResult = {
 	},
 };
 
-const helpersEntry: EvalSchemaResult = {
+const helpersEntry: NamedEvalSchema = {
 	name: "eval:helpers",
 	description: [
 		"Advanced cell helpers (all four languages; js helpers are awaited).",
@@ -70,7 +71,7 @@ const helpersEntry: EvalSchemaResult = {
 	},
 };
 
-const kernelToolsEntry: EvalSchemaResult = {
+const kernelToolsEntry: NamedEvalSchema = {
 	name: "eval:kernel-tools",
 	description: [
 		"Kernel tools: functions a cell defines that in-process children can call (js and py; rb/jl answer tools_unavailable).",
@@ -90,12 +91,18 @@ const kernelToolsEntry: EvalSchemaResult = {
 	},
 };
 
-const VIRTUAL_ENTRIES: ReadonlyMap<string, EvalSchemaResult> = new Map([
+const VIRTUAL_ENTRIES: ReadonlyMap<string, EvalSchemaResult> = new Map<string, EvalSchemaResult>([
 	[waitEntry.name, waitEntry],
 	[helpersEntry.name, helpersEntry],
 	[kernelToolsEntry.name, kernelToolsEntry],
+	[environmentsEntry.name, environmentsEntry],
+	[isolationEntry.name, isolationEntry],
 ]);
 
 export function virtualEvalSchema(name: string): EvalSchemaResult | undefined {
 	return VIRTUAL_ENTRIES.get(name);
 }
+
+export function virtualEvalSchemaNames(): readonly string[] {
+	return [...VIRTUAL_ENTRIES.keys()];
+}

package/src/bridges/reserved-dispatch.ts

@@ -1,5 +1,11 @@
 import type { AgentToolResult, EvalHandleHost } from "@code-yeongyu/senpi";
-import { RESERVED_AGENT_TOOL, RESERVED_OUTPUT_TOOL, RESERVED_SCHEMA_TOOL } from "../bridge/reserved.ts";
+import {
+	RESERVED_AGENT_TOOL,
+	RESERVED_OUTPUT_TOOL,
+	RESERVED_PACKAGES_INSTALL_TOOL,
+	RESERVED_SCHEMA_TOOL,
+} from "../bridge/reserved.ts";
+import { type PackagesInstallEnvironments, runPackagesInstall } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalStatusEvent, ExecuteTool } from "../tool/types.ts";
 import { type AgentExecuteTool, runEvalAgent } from "./agent-bridge.ts";
@@ -21,6 +27,8 @@ export interface ReservedDispatchContext {
 	readonly handles?: HandleRegistry;
 	/** `ctx.evalHandleHost` at dispatch time; agent/workpool refs need it, completion refs do not. */
 	readonly evalHandleHost?: EvalHandleHost;
+	/** The calling cell's session environments; `packages.install()` fails with environment_installer_unavailable without one. */
+	readonly environments?: PackagesInstallEnvironments;
 }
 
 class SchemaUnavailableError extends Error {
@@ -36,6 +44,7 @@ export function isReservedToolName(toolName: string): boolean {
 		toolName === RESERVED_AGENT_TOOL ||
 		toolName === RESERVED_OUTPUT_TOOL ||
 		toolName === RESERVED_SCHEMA_TOOL ||
+		toolName === RESERVED_PACKAGES_INSTALL_TOOL ||
 		isHandleToolName(toolName)
 	);
 }
@@ -66,6 +75,9 @@ export async function runReservedTool(toolName: string, context: ReservedDispatc
 			marshalToolResult: context.marshalToolResult,
 		});
 	}
+	if (toolName === RESERVED_PACKAGES_INSTALL_TOOL) {
+		return await runPackagesInstall(context.args, context.environments ?? {}, context.signal);
+	}
 	if (toolName === RESERVED_SCHEMA_TOOL) {
 		const listTools = context.listTools;
 		if (listTools === undefined) throw new SchemaUnavailableError();

package/src/config/executable-settings.json

@@ -0,0 +1,5 @@
+{
+	"projectExecutableSettings": [
+		"languages.pyInterpreter"
+	]
+}

package/src/config/project-trust.ts

@@ -0,0 +1,51 @@
+import { join } from "node:path";
+import executableSettings from "./executable-settings.json" with { type: "json" };
+import type { CodemodeSettings } from "./settings.ts";
+
+/**
+ * Settings that name an executable run at session start (an interpreter's `--version` probe, then the kernel). The
+ * one list of them lives in `executable-settings.json`, which senpi's project-trust check also reads: a project
+ * codemode file that sets any of them asks for trust. Without trust they are dropped with a warning and never run.
+ * Trust is asked only when the project's own file sets one, so a host that cannot answer still starts sessions;
+ * such a host counts as not trusting the project.
+ */
+export const PROJECT_EXECUTABLE_SETTINGS: readonly string[] = executableSettings.projectExecutableSettings;
+
+export function withoutUntrustedInterpreter<Settings extends CodemodeSettings>(
+	settings: Settings,
+	source: string | null,
+	cwd: string,
+	isProjectTrusted: (() => boolean) | undefined,
+): { readonly settings: Settings; readonly warning?: string } {
+	const projectFile = join(cwd, ".senpi", "codemode.json");
+	if (source !== projectFile) return { settings };
+	const named = PROJECT_EXECUTABLE_SETTINGS.filter((path) => valueAt(settings, path) !== undefined);
+	if (named.length === 0 || isProjectTrusted?.() === true) return { settings };
+	let trimmed: Settings = settings;
+	for (const path of named) trimmed = withoutPath(trimmed, path);
+	const list = named.map((path) => `${path} "${String(valueAt(settings, path))}"`).join(", ");
+	return {
+		settings: trimmed,
+		warning: `${list} in ${projectFile} is ignored because this project is not trusted; it was not run`,
+	};
+}
+
+function valueAt(value: unknown, path: string): unknown {
+	let current: unknown = value;
+	for (const key of path.split(".")) {
+		if (typeof current !== "object" || current === null) return undefined;
+		current = Reflect.get(current, key);
+	}
+	return current;
+}
+
+function withoutPath<T>(value: T, path: string): T {
+	const copy = structuredClone(value);
+	const keys = path.split(".");
+	const last = keys.pop();
+	let parent: unknown = copy;
+	for (const key of keys)
+		parent = typeof parent === "object" && parent !== null ? Reflect.get(parent, key) : undefined;
+	if (last !== undefined && typeof parent === "object" && parent !== null) Reflect.deleteProperty(parent, last);
+	return copy;
+}

package/src/config/settings-overrides.ts

@@ -20,6 +20,8 @@ export function resolveEnabledLanguages(
 	env: Environment = process.env,
 ): CodemodeSettings["languages"] {
 	return {
+		// Keep the non-flag keys (languages.pyInterpreter); only the four enable flags take env overrides.
+		...settings.languages,
 		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
 		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
 		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),

package/src/environments/editable-check.ts

@@ -60,7 +60,7 @@ async function refuseOutsideLinks(root: string, dir: string): Promise<void> {
 export async function assertInstalledInRevision(stdout: string, staging: string): Promise<void> {
 	const line = stdout.split("\n").find((entry) => entry.startsWith("Successfully installed "));
 	if (line === undefined) return;
-	const present = new Set((await readdir(staging).catch(() => [] as string[])).flatMap(installedName));
+	const present = new Set((await readdir(staging).catch((): string[] => [])).flatMap(installedName));
 	for (const token of line.slice("Successfully installed ".length).trim().split(/\s+/u)) {
 		const name = token.slice(0, token.lastIndexOf("-"));
 		if (!present.has(canonicalName(name))) {

package/src/environments/js-environments.ts

@@ -0,0 +1,208 @@
+import { mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import { withRootLock } from "./install-lock.ts";
+import {
+	absoluteSpec,
+	type JsInstallerChoice,
+	parseJsPackages,
+	requestedPackageName,
+	resolveJsInstaller,
+	runJsInstall,
+	withoutHostPaths,
+} from "./js-installer.ts";
+import { carryNpmrcSettings, recordedFileSpecs, seedPackageJson } from "./js-revision-files.ts";
+import { assertBuiltRevisionLinks, assertNoLinksBelow, recordedInstallSources } from "./no-links.ts";
+import { projectResolves } from "./project-resolves.ts";
+import type { EnvironmentMode } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import { mkdirPrivate, publishNextRevision, readActiveRevision } from "./revision-store.ts";
+
+/** The paths in a revision that the installer writes. */
+const INSTALLER_WRITES = [
+	"package.json",
+	"package-lock.json",
+	"bun.lock",
+	"bun.lockb",
+	"node_modules",
+	".npmrc",
+	"bunfig.toml",
+];
+
+export interface JsInstallReceipt {
+	readonly installer: "bun" | "npm";
+	readonly mode: EnvironmentMode;
+	readonly revision: number | undefined;
+	readonly added: readonly string[];
+	readonly shadowed: readonly string[];
+}
+
+export interface JsEnvironmentsOptions {
+	readonly artifactsDir: string;
+	readonly cwd: string;
+	readonly runtime: string;
+	readonly env: NodeJS.ProcessEnv;
+	readonly settings: Pick<ResolvedCodemodeSettings, "environments">;
+}
+
+export class JsEnvironments {
+	readonly #options: JsEnvironmentsOptions;
+	#mode: EnvironmentMode = "managed";
+	#packageRoot: string | undefined;
+
+	constructor(options: JsEnvironmentsOptions) {
+		this.#options = options;
+	}
+
+	get mode(): EnvironmentMode {
+		return this.#mode;
+	}
+
+	get packageRoot(): string | undefined {
+		return this.#mode === "managed" ? this.#packageRoot : undefined;
+	}
+
+	async setMode(mode: EnvironmentMode): Promise<string> {
+		this.#mode = mode;
+		if (mode === "project") return this.#options.cwd;
+		this.#packageRoot = (await readActiveRevision(this.#managedBase()))?.dir;
+		return this.#managedBase();
+	}
+
+	async install(
+		requested: string,
+		signal: AbortSignal,
+		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
+		requestedInstaller?: "bun" | "npm",
+	): Promise<JsInstallReceipt> {
+		const environments = this.#options.settings.environments;
+		if (environments?.autoProvision === false) {
+			throw new EnvironmentError(
+				"environment_installer_unavailable",
+				"installs are turned off for this project (environments.autoProvision is false)",
+			);
+		}
+		const packages = parseJsPackages(requested).map((spec) => absoluteSpec(spec, this.#options.cwd));
+		// `%bun add` and `%npm add` name their installer; the setting applies only where the magic does not.
+		const choice: JsInstallerChoice = requestedInstaller ?? environments?.js?.installer ?? "auto";
+		const { installer, command } = resolveJsInstaller(choice, this.#options.env);
+		let recordedSpecs: readonly string[] = [];
+		const run = (root: string, remove?: string) =>
+			runJsInstall({
+				installer,
+				command,
+				root,
+				packages,
+				...(remove === undefined ? {} : { remove }),
+				recordedSpecs,
+				cwd: this.#options.cwd,
+				env: this.#options.env,
+				signal,
+				...(onOutput === undefined ? {} : { onOutput }),
+			});
+		// The lock and the revision store fail with raw file system errors; they reach the cell redacted.
+		const redacted =
+			(...roots: string[]) =>
+			(error: unknown) => {
+				const raw =
+					error instanceof EnvironmentError
+						? error.message.slice(error.code.length + 2)
+						: String(error instanceof Error ? error.message : error);
+				const text = roots.reduce(
+					(message, root) => withoutHostPaths(message, { root, cwd: this.#options.cwd, packages, recordedSpecs }),
+					raw,
+				);
+				if (error instanceof EnvironmentError) throw new EnvironmentError(error.code, text);
+				// An abort while waiting for the lock or before the publish is a cancel, not a failure.
+				if (signal.aborted)
+					throw new EnvironmentError("environment_install_cancelled", `the install was cancelled: ${text}`);
+				throw new EnvironmentError("environment_install_failed", text);
+			};
+		if (this.#mode === "project") {
+			const before = await dependencyNames(this.#options.cwd);
+			const lockRoot = join(this.#options.cwd, ".senpi", "js-packages");
+			await mkdir(lockRoot, { recursive: true });
+			await withRootLock(lockRoot, async () => await run(this.#options.cwd), signal).catch(redacted(lockRoot));
+			const added = (await dependencyNames(this.#options.cwd)).filter((name) => !before.includes(name));
+			return { installer, mode: "project", revision: undefined, added, shadowed: [] };
+		}
+		let added: string[] = [];
+		const requestedBase = this.#managedBase();
+		const base = await canonicalBase(this.#managedRoot(), requestedBase).catch(redacted(requestedBase));
+		const { revision } = await publishNextRevision(
+			base,
+			async (staging) => {
+				await carryNpmrcSettings(staging);
+				await rm(join(staging, "bunfig.toml"), { recursive: true, force: true });
+				await seedPackageJson(staging);
+				// Every path the installer writes must be the revision's own, never a link out of it.
+				for (const entry of INSTALLER_WRITES) await assertNoLinksBelow(base, join(staging, entry));
+				const before = await dependencyNames(staging);
+				recordedSpecs = await recordedFileSpecs(staging);
+				// A package whose source changes kind (a directory to a tarball or registry version, or back) is removed
+				// first: bun keeps its per-file links into the old directory otherwise (#2758).
+				for (const name of await sourceKindChanges(staging, packages)) await run(staging, name);
+				await run(staging);
+				await assertBuiltRevisionLinks(staging);
+				added = (await dependencyNames(staging)).filter((name) => !before.includes(name));
+			},
+			signal,
+		).catch(redacted(base, requestedBase));
+		this.#packageRoot = revision.dir;
+		const shadowed = added.filter((name) => projectResolves(this.#options.cwd, name));
+		return { installer, mode: "managed", revision: revision.number, added, shadowed };
+	}
+
+	#managedRoot(): string {
+		return this.#options.settings.environments?.managedRoot ?? this.#options.artifactsDir;
+	}
+
+	#managedBase(): string {
+		return join(this.#managedRoot(), "environments", "js", this.#options.runtime);
+	}
+}
+
+async function dependencyNames(root: string): Promise<string[]> {
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		if (typeof manifest !== "object" || manifest === null || !("dependencies" in manifest)) return [];
+		const dependencies = manifest.dependencies;
+		return typeof dependencies === "object" && dependencies !== null ? Object.keys(dependencies) : [];
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/**
+ * Creates the managed base, checks that nothing below the managed root is a link, and returns its realpath: npm keys
+ * a linked package in its lockfile by a path relative to the prefix, and a prefix under a linked directory (macOS
+ * `/var` is a link to `/private/var`) gives keys that stop resolving once the staged revision is renamed.
+ */
+async function canonicalBase(managedRoot: string, base: string): Promise<string> {
+	await assertNoLinksBelow(managedRoot, base);
+	await mkdirPrivate(base);
+	await assertNoLinksBelow(managedRoot, base);
+	return await realpath(base);
+}
+
+/** Names among `packages` whose recorded source is a directory and is not the same directory now, or the reverse. */
+export async function sourceKindChanges(revision: string, packages: readonly string[]): Promise<string[]> {
+	const installed = new Set(await dependencyNames(revision));
+	const sources = await recordedInstallSources(revision);
+	const changed: string[] = [];
+	for (const spec of packages) {
+		const name = await requestedPackageName(spec);
+		if (name === undefined || !installed.has(name)) continue;
+		const directory = await localDirectory(spec);
+		if (directory !== sources.get(name)) changed.push(name);
+	}
+	return changed;
+}
+
+async function localDirectory(spec: string): Promise<string | undefined> {
+	const path = spec.startsWith("file:") ? spec.slice("file:".length) : spec;
+	if (!isAbsolute(path)) return undefined;
+	const resolved = await realpath(path).catch(() => undefined);
+	return resolved !== undefined && (await stat(resolved)).isDirectory() ? resolved : undefined;
+}