@code-yeongyu/senpi-codemode 2026.10.10-5 → 2026.10.10-8

package/CHANGELOG.md

@@ -12,6 +12,38 @@
 
 ### Removed
 
+## [2026.10.10-8] - 2026-10-08
+
+### Breaking Changes
+
+### Added
+
+- `packages.install(manager, requirements, {timeout?})` in JavaScript and Python cells installs through the same session environment as `%pip install` / `%bun add` / `%npm add` and returns the install receipt; a stop cancels it and the timeout (600 seconds by default) fails it with `environment_install_timeout`.
+
+- `tool_schema("eval:environments")` and `tool_schema("eval:isolation")` document the package magics (`%pip`, `%bun`/`%npm`, `%environment`, `%load`) and isolated cells on demand, with the error codes each one raises. Nothing is added to the eval prompt or its input schema.
+
+### Changed
+
+### Fixed
+
+- The eval timing benchmark's spike retry no longer waits for a load at or above its own refusal ceiling: the settle target is capped at 70, so a run whose calm load was near 80 cannot start its retries straight into another spike and burn them all in seconds. On a host whose normal load is above 70, each retry now waits the full 15 minutes and then retries anyway; the attempt's own spike checks still decide what is kept. ([#2922](https://github.com/code-yeongyu/senpi/issues/2922))
+
+- The eval timing benchmark no longer throws away a whole multi-block run when the host's 1-minute load goes over 80 partway through: only the block that saw the spike is discarded and re-run (up to 3 retries, each after the load has fallen back under 70). A runtime failure in the same block is never discarded with the spike. A block that spikes on every attempt is labelled, making the run inconclusive rather than refused, and the other blocks still report. Re-run blocks are listed in the JSON report's `retriedBlocks`. ([#2909](https://github.com/code-yeongyu/senpi/issues/2909))
+
+### Removed
+
+## [2026.10.10-6] - 2026-10-07
+
+### Breaking Changes
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Removed
+
 ## [2026.10.10-5] - 2026-10-07
 
 ### Breaking Changes

package/README.md

@@ -363,7 +363,8 @@ options object and asynchronous helpers are `await`-able.
 | `write(path, content)` | Creates parent directories and writes text. `local://` paths persist in the session artifact root. |
 | `env(key?, value?)` | Reads all kernel environment values, one value, or sets one value. Includes the session's `PI_*` values (see [Session environment](#session-environment)). |
 | `tool.<name>(args)` | Invokes an active Senpi tool through the normal `pi.executeTool` pipeline and returns `{ text, images?, details?, hasError? }` in every kernel; image blocks arrive as `images[i] = { mimeType, dataBase64 }`. |
-| `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. |
+| `packages.install(manager, requirements, {timeout?})` (js, py) | The `%pip install` (py, manager `"pip"`) or `%bun add` / `%npm add` (js, `"bun"` / `"npm"`) installer as a call: same session environment, receipt (`py`: manager, mode, root, revision, requested, resolved, changed; `js`: installer, mode, revision, added, shadowed), cancellation by `stop` and `environment_install_*` codes; `timeout` defaults to 600 seconds and fails with `environment_install_timeout`. Python: `packages.install("pip", [...], timeout=...)`. |
+| `tool_schema(name?)` | Returns a tool's parameter schema without calling it; omit `name` to list tool names. Five virtual entries document codemode itself on demand and are never listed: `eval:wait`, `eval:helpers`, `eval:kernel-tools`, `eval:environments` (the `%pip`, `%bun`/`%npm`, `%environment` and `%load` magics, their results and error codes) and `eval:isolation` (`isolate: true` cells, their limits and error codes). |
 | `require(specifier)`, `createRequire(path)` (js) | CommonJS loading inside a cell, resolved like `import`: builtins (with or without `node:`), relative files and JSON from the cell's directory, bare packages from the session's project and then its managed package environment (`%bun add`/`%npm add`). A missing module raises the runtime's own `MODULE_NOT_FOUND` error. Like Node's `require`, it carries `require.resolve` (the same lookup the call uses, so both name the same copy; builtins resolve to the runtime's own id), `require.resolve.paths` and `require.cache` (the runtime's CommonJS cache). |
 | `tool(fn, metadata?)` (js) | Registers a named function as a kernel tool for in-process children. `metadata.name` registers it under that name instead of the function's; arguments are still passed in the function's parameter order. |
 | `tool.defined()` / `tool.undefine(name)` (js) | List the kernel tools this kernel defines (sorted), and remove one (`true` if it existed). A descriptor taken before `undefine` can no longer be invoked. Both names are reserved: a kernel tool can't be registered as `defined` or `undefine` (`reserved_tool_name`), and a host tool with either name is shadowed in the `tool` namespace, so it can't be called from a JavaScript cell. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.10-5",
+	"version": "2026.10.10-8",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -33,15 +33,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10-5",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.10-8",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.10-5"
+		"@code-yeongyu/senpi": "2026.10.10-8"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.10-5"
+		"@code-yeongyu/senpi": "2026.10.10-8"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/reserved.ts

@@ -15,6 +15,8 @@ export const RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__" as const;
 export const RESERVED_HANDLE_SEND_TOOL = "__handle_send__" as const;
 /** `handle(node).control.cancel()`: idempotent for its epoch; a successor run is never touched. */
 export const RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__" as const;
+/** In-cell `packages.install(manager, requirements, {timeout?})`: the `%pip` / `%bun` / `%npm` installer as a call. */
+export const RESERVED_PACKAGES_INSTALL_TOOL = "__packages_install__" as const;
 /** Canonical oh-my-pi eval-timeout pause operation. */
 export const TIMEOUT_PAUSE_OP = "timeout-pause" as const;
 /** Canonical oh-my-pi eval-timeout resume operation. */

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

@@ -0,0 +1,48 @@
+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.",
+		"Install failures are cell errors that start with their code: environment_install_failed (a bad argument or an installer failure, with the installer's stderr tail), 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; or installs turned off with environments.autoProvision: false), 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://...>" },
+		},
+	},
+};
+
+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/environments/packages-install.ts

@@ -0,0 +1,98 @@
+import type { JsEnvironments, JsInstallReceipt } from "./js-environments.ts";
+import type { InstallReceipt } from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import type { PythonEnvironments } from "./python-environments.ts";
+
+export interface PackagesInstallEnvironments {
+	readonly python?: PythonEnvironments;
+	readonly js?: JsEnvironments;
+}
+
+export const PACKAGES_INSTALL_DEFAULT_TIMEOUT_SECONDS = 600;
+
+interface PackagesInstallRequest {
+	readonly manager: "pip" | "bun" | "npm";
+	readonly requirements: readonly string[];
+	readonly timeoutSeconds: number;
+}
+
+function invalid(message: string): EnvironmentError {
+	return new EnvironmentError("environment_install_failed", `packages.install(): ${message}`);
+}
+
+function parseRequest(args: unknown): PackagesInstallRequest {
+	if (typeof args !== "object" || args === null) throw invalid("expected (manager, requirements, {timeout?})");
+	const manager = "manager" in args ? args.manager : undefined;
+	if (manager !== "pip" && manager !== "bun" && manager !== "npm") {
+		throw invalid('manager must be "pip" (Python) or "bun" / "npm" (JavaScript)');
+	}
+	const raw = "requirements" in args ? args.requirements : undefined;
+	const list = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : undefined;
+	if (
+		list === undefined ||
+		list.length === 0 ||
+		!list.every((item) => typeof item === "string" && item.trim() !== "")
+	) {
+		throw invalid("requirements must be a non-empty string or a non-empty list of non-empty strings");
+	}
+	const timeout = "timeout" in args ? args.timeout : undefined;
+	if (timeout !== undefined && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) {
+		throw invalid("timeout must be a positive number of seconds");
+	}
+	return {
+		manager,
+		requirements: list.map((item: string) => item.trim()),
+		timeoutSeconds: timeout ?? PACKAGES_INSTALL_DEFAULT_TIMEOUT_SECONDS,
+	};
+}
+
+function jsArguments(requirements: readonly string[]): string {
+	for (const requirement of requirements) {
+		if (/\s/.test(requirement)) throw invalid(`a package spec cannot contain whitespace: ${requirement}`);
+	}
+	return requirements.join(" ");
+}
+
+/**
+ * `packages.install(manager, requirements, {timeout?})`: the in-cell form of `%pip install` / `%bun add` /
+ * `%npm add`. It drives the same session environment the magic cells use and returns its receipt; a stop of the
+ * owning cell cancels it (environment_install_cancelled), and the timeout fails it with environment_install_timeout.
+ * pip receives the requirement list as separate arguments, never re-split. The installer's output is not streamed
+ * into the cell: the receipt is the result, and a failure carries the installer's stderr tail.
+ */
+export async function runPackagesInstall(
+	args: unknown,
+	environments: PackagesInstallEnvironments,
+	signal: AbortSignal | undefined,
+): Promise<InstallReceipt | JsInstallReceipt> {
+	const request = parseRequest(args);
+	const { python, js } = environments;
+	const manager = request.manager;
+	let install: ((signal: AbortSignal) => Promise<InstallReceipt | JsInstallReceipt>) | undefined;
+	if (manager === "pip") {
+		if (python !== undefined) install = (signal) => python.install(request.requirements, signal);
+	} else if (js !== undefined) {
+		install = (signal) => js.install(jsArguments(request.requirements), signal, undefined, manager);
+	}
+	if (install === undefined) {
+		throw new EnvironmentError(
+			"environment_installer_unavailable",
+			manager === "pip"
+				? "pip installs need this session to have a Python interpreter"
+				: "bun/npm installs run only in a JavaScript cell",
+		);
+	}
+	const timeout = AbortSignal.timeout(request.timeoutSeconds * 1_000);
+	const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+	try {
+		return await install(combined);
+	} catch (error) {
+		if (timeout.aborted && !(signal?.aborted ?? false)) {
+			throw new EnvironmentError(
+				"environment_install_timeout",
+				`the install did not finish within ${request.timeoutSeconds}s and was stopped`,
+			);
+		}
+		throw error;
+	}
+}

package/src/environments/py-environment.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { assertInstalledInRevision, assertNoEditableInstalls } from "./editable-check.ts";
-import { parsePipRequirements, runPipInstall } from "./py-installer.ts";
+import { normalizePipInstall, parsePipRequirements, runPipInstall } from "./py-installer.ts";
 import { publishNextRevision, type Revision } from "./revision-store.ts";
 
 const execFileAsync = promisify(execFile);
@@ -40,12 +40,16 @@ export async function installPythonPackages(input: {
 	readonly base: string;
 	readonly mode: EnvironmentMode;
 	readonly interpreter: string;
-	readonly requirements: string;
+	/** `%pip` argument text, or the requirement list `packages.install()` passes without re-parsing. */
+	readonly requirements: string | readonly string[];
 	readonly cwd: string;
 	readonly signal: AbortSignal;
 	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
 }): Promise<InstallReceipt> {
-	const requested = parsePipRequirements(input.requirements);
+	const requested =
+		typeof input.requirements === "string"
+			? parsePipRequirements(input.requirements)
+			: normalizePipInstall(["install", ...input.requirements]);
 	let stdout = "";
 	const { revision } = await publishNextRevision(
 		input.base,

package/src/environments/py-installer.ts

@@ -125,7 +125,11 @@ export function splitShellWords(text: string, posix = process.platform !== "win3
 }
 
 export function parsePipRequirements(text: string): string[] {
-	const args = splitShellWords(text);
+	return normalizePipInstall(splitShellWords(text));
+}
+
+/** `%pip` words already split (`["install", ...]`): `packages.install()` passes its list as-is, so nothing is re-quoted. */
+export function normalizePipInstall(args: readonly string[]): string[] {
 	const command = args[0] === "install" ? args.slice(1) : undefined;
 	if (command === undefined) {
 		throw new EnvironmentError("environment_install_failed", "only `%pip install <requirements>` is supported");

package/src/environments/python-environments.ts

@@ -47,7 +47,7 @@ export class PythonEnvironments {
 	}
 
 	async install(
-		requirements: string,
+		requirements: string | readonly string[],
 		signal: AbortSignal,
 		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
 	): Promise<InstallReceipt> {

package/src/extension/bridge-tool-call.ts

@@ -19,7 +19,10 @@ export interface BridgeToolCallRequest {
 // and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
 // { content } shape left python cells unable to reach tool.read image blocks.
 export async function routeBridgeToolCall(
-	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings" | "handles">,
+	options: Pick<
+		CreateCodemodeSessionManagerOptions,
+		"executeTool" | "listTools" | "settings" | "handles" | "environments"
+	>,
 	request: BridgeToolCallRequest,
 	evalHandleHost?: EvalHandleHost,
 ): Promise<unknown> {
@@ -39,5 +42,6 @@ export async function routeBridgeToolCall(
 		marshalToolResult,
 		...(options.handles === undefined ? {} : { handles: options.handles }),
 		...(evalHandleHost === undefined ? {} : { evalHandleHost }),
+		...(options.environments === undefined ? {} : { environments: options.environments }),
 	});
 }

package/src/extension/runtime-factory.ts

@@ -92,6 +92,15 @@ export async function createRuntime(
 	const sessionEnv = { ...sessionEnvironmentFrom(ctx), ...bundledBunPathEntry() };
 	const configuredPoolWidth = settings.parallelPoolWidth;
 	const parallelPoolWidth = Number.isFinite(configuredPoolWidth) ? Math.max(1, Math.trunc(configuredPoolWidth)) : 1;
+	const pythonEnvironments =
+		availability.py.detected.ok && enabledLanguages.py
+			? new PythonEnvironments({
+					artifactsDir: artifacts.dir,
+					cwd: ctx.cwd,
+					interpreter: availability.py.detected.path,
+					settings,
+				})
+			: undefined;
 	const manager = await create({
 		sessionId,
 		ownerSessionId: ctx.sessionManager.getSessionId(),
@@ -104,6 +113,7 @@ export async function createRuntime(
 		listTools: () => pi.getAllTools(),
 		complete,
 		...(handles === undefined ? {} : { handles }),
+		...(pythonEnvironments === undefined ? {} : { environments: { python: pythonEnvironments } }),
 	});
 	return {
 		sessionId,
@@ -127,16 +137,7 @@ export async function createRuntime(
 			env: { ...process.env, ...sessionEnv },
 			settings,
 		}),
-		...(availability.py.detected.ok && enabledLanguages.py
-			? {
-					pythonEnvironments: new PythonEnvironments({
-						artifactsDir: artifacts.dir,
-						cwd: ctx.cwd,
-						interpreter: availability.py.detected.path,
-						settings,
-					}),
-				}
-			: {}),
+		...(pythonEnvironments === undefined ? {} : { pythonEnvironments }),
 	};
 }
 

package/src/extension/session-manager-contract.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
@@ -42,4 +43,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
 	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
 	readonly handles?: HandleRegistry;
+	/** The Python environment `packages.install("pip", ...)` reaches from a Python cell over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }

package/src/kernels/js/worker-runtime.js

@@ -162,6 +162,17 @@ export class JsWorkerRuntime {
 			return isPlainObject(opts) && opts.handle === true ? handles.handle(value) : value;
 		};
 		globalThis.wait = async (list, options) => await handles.wait(list, options);
+		// The `%bun add` / `%npm add` installer as a call: same environment, receipt, cancellation and codes (senpi row 38).
+		globalThis.packages = Object.freeze({
+			install: async (manager, requirements, options = {}) => {
+				if (!isPlainObject(options)) throw new TypeError("packages.install(): options must be an object, e.g. { timeout: 120 }");
+				return await this.#callTool("__packages_install__", {
+					manager,
+					requirements,
+					...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+				});
+			},
+		});
 		globalThis.handle = value => handles.handle(value);
 		globalThis.tool = createToolNamespace(
 			(fn, metadata) => this.#tools.define(fn, metadata),

package/src/kernels/py/prelude.py

@@ -61,6 +61,7 @@ RESERVED_HANDLE_STATUS_TOOL = "__handle_status__"
 RESERVED_HANDLE_OUTPUT_TOOL = "__handle_output__"
 RESERVED_HANDLE_SEND_TOOL = "__handle_send__"
 RESERVED_HANDLE_CANCEL_TOOL = "__handle_cancel__"
+RESERVED_PACKAGES_INSTALL_TOOL = "__packages_install__"
 TIMEOUT_PAUSE_OP = "timeout-pause"
 TIMEOUT_RESUME_OP = "timeout-resume"
 
@@ -1162,6 +1163,27 @@ def tool_schema(name: str | None = None) -> Any:
     )
 
 
+class _Packages:
+    """packages.install(manager, requirements, *, timeout=600): the %pip installer as a call; returns its receipt."""
+
+    __slots__ = ()
+
+    def install(self, manager: str, requirements: Any, *, timeout: float | None = None) -> Any:
+        args: dict[str, Any] = {"manager": manager, "requirements": requirements}
+        if timeout is not None:
+            args["timeout"] = timeout
+        # A long install must not hit the 60 s socket cap; the host bounds it by the timeout (600 s by default).
+        socket_timeout = (600 if timeout is None else float(timeout)) + _WAIT_SOCKET_GRACE_SECONDS
+        return bridge_post(
+            "/call",
+            {"callId": f"py-{uuid.uuid4()}", "toolName": RESERVED_PACKAGES_INSTALL_TOOL, "args": args},
+            socket_timeout=socket_timeout,
+        )
+
+
+packages = _Packages()
+
+
 def output(
     *ids: str,
     format: str = "raw",
@@ -1789,6 +1811,7 @@ USER_NS.update(
         "workpool": workpool,
         "output": output,
         "tool_schema": tool_schema,
+        "packages": packages,
         "wait": wait,
         "handle": handle,
         "__senpi_magic": _magic,

package/src/tool/cell-handler.ts

@@ -14,6 +14,7 @@ import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import {
@@ -54,6 +55,8 @@ export interface CellBridgeRuntime {
 	readonly handles?: HandleRegistry;
 	/** Absolute wall-clock deadline of this cell; a completion handle it creates is bounded by it. */
 	readonly hardDeadlineMs?: number;
+	/** A JS cell's session environment for `packages.install()`; Python cells reach theirs over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }
 
 export class CellHandler {

package/src/tool/cell-reserved-dispatch.ts

@@ -29,6 +29,7 @@ export function reservedDispatchContext(
 		marshalToolResult,
 		...(runtime.handles === undefined ? {} : { handles: runtime.handles }),
 		...(host === undefined ? {} : { evalHandleHost: host }),
+		...(runtime.environments === undefined ? {} : { environments: runtime.environments }),
 	};
 }
 

package/src/tool/run-eval-cell.ts

@@ -9,6 +9,8 @@ import {
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import { resolveSandbox } from "../config/feature-settings.ts";
 import { DEFAULT_FOREGROUND_WINDOW_SECONDS, defaultCodemodeSettings } from "../config/settings.ts";
+import type { JsEnvironments } from "../environments/js-environments.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import {
 	KERNEL_TOOLS_CAPABILITIES,
 	type KernelToolsCapability,
@@ -241,6 +243,7 @@ async function executeCell(
 				...(kernelTools === undefined ? {} : { kernelTools }),
 				...(options.handles === undefined ? {} : { handles: options.handles }),
 				hardDeadlineMs: cell.startedAtMs + cell.hardLimitSeconds * 1_000,
+				...cellEnvironments(invocation.input.language, options),
 			});
 			handler = activeHandler;
 			cellManager.bindKernel(
@@ -364,3 +367,14 @@ function kernelToolsFor(kernel: EvalKernel): KernelToolsCapability | undefined {
 		invoke: (request, options) => withTools.invokeKernelTool(request, options),
 	} satisfies ExtensionKernelTools;
 }
+
+// Only JS cells call tools in-process; a Python cell reaches packages.install() over the bridge, whose session manager
+// holds the same Python environment its magics use.
+function cellEnvironments(
+	language: string,
+	options: { readonly jsEnvironments?: JsEnvironments },
+): { readonly environments?: PackagesInstallEnvironments } {
+	if (language === "js" && options.jsEnvironments !== undefined)
+		return { environments: { js: options.jsEnvironments } };
+	return {};
+}