---

summary: "Python and JavaScript code-mode extension with persistent logical state for bounded multi-operation Pi calls." read_when:

• "Installing, operating, reviewing, or extending pi-eval-kernel."
• "Comparing code-mode execution with native Pi tool calls or subagent workflows." system4d: container: "One model-visible eval tool backed by disposable language workers, persistent logical state, and an explicit host capability registry." compass: "Reduce repetitive tool-call overhead without claiming arbitrary Pi-tool invocation or sandboxing." engine: "Confirm code -> execute in worker -> route explicit capability calls -> aggregate one result." fog: "Arbitrary code has invoking-user authority; registry admission governs the host bridge, not the whole language runtime."

---

@tryinget/pi-eval-kernel

pi-eval-kernel adds an eval tool with disposable Python and JavaScript workers plus host-persisted JSON state by default. An explicit engine: "persistent" option keeps one Python worker in-process across calls; JavaScript remains disposable. One model-visible call can run a bounded program, issue concurrent calls through an explicit package-owned capability registry, and return one aggregated result.

It does not replace Bash by default and does not claim to invoke arbitrary active Pi tools.

Current capability

• persistent JSON-compatible state for Python and JavaScript across eval calls in the current Pi session;
• Python final-expression results and JavaScript explicit return results;
• bounded wall-clock timeout and abort-driven worker termination;
• disposable protocol brokers with bounded frames, runtime message validation, and host-finalized result commit;
• opt-in persistent Python with one bounded broker transport, serialized evals, and no host state round-trip;
• captured stdout/stderr and 50 KiB model-visible output limit;
• explicit capability metadata with read, process, write, network, or orchestration effect classes;
• default host capabilities:
  • read_text — bounded UTF-8 reads inside ctx.cwd;
  • list_directory — direct-child listing inside ctx.cwd;
  • run_process — executable + argument-array invocation without a shell;
• concurrent capability calls inside either language;
• confirmation before each eval by default;
• non-interactive execution denied by default;
• /code-mode status and /eval-reset lifecycle commands.

Examples

Python

files = tool.parallel([
    ("read_text", {"path": "src/a.ts"}),
    ("read_text", {"path": "src/b.ts"}),
], max_workers=4)

{"line_counts": [item["totalLines"] for item in files]}

Python capability calls are synchronous. tool.<name>(input) is shorthand for tool.call(name, input).

JavaScript

const files = await tool.parallel([
  { name: "read_text", input: { path: "src/a.ts" } },
  { name: "read_text", input: { path: "src/b.ts" } },
], 4);

state.runs = (state.runs ?? 0) + 1;
return { runs: state.runs, lineCounts: files.map((file) => file.totalLines) };

JavaScript capability calls return promises and must be awaited.

Capability adapters

Other owned packages can compose with code mode without exposing arbitrary registered Pi handlers:

import {
  createCodeModeExtension,
  type CodeModeCapability,
} from "@tryinget/pi-eval-kernel/runtime";

const dispatchCapability: CodeModeCapability = {
  name: "dispatch_review",
  description: "Dispatch one governed read-only review through the owning runtime.",
  effect: "orchestration",
  execute: async (input, context) => {
    // Delegate to the owner package's public execution runtime.
    // Preserve its validation, cancellation, receipts, and result contract.
  },
};

export default createCodeModeExtension({
  capabilities: [dispatchCapability],
  allowedCapabilityEffects: ["read", "process", "orchestration"],
});

An adapter must call the owner package's public runtime rather than copy its logic or invoke private registered-tool handlers.

Security boundary

Code runs in child processes with the invoking user's permissions. This is not a security sandbox.

• Each model-issued eval requires UI confirmation by default.
• Non-interactive calls fail closed unless the embedding extension explicitly sets allowNonInteractive: true.
• Registry effect admission controls only tool.* host bridge calls.
• Python can import standard-library modules and access the operating system directly.
• The JavaScript VM context narrows ambient globals but is not treated as a hostile-code isolation boundary.
• Activating this package is equivalent to granting the model a general local-code execution surface.

See Security model.

Persistent state and reset

• The default engine: "disposable" keeps Python and JavaScript state in a host-committed JSON-compatible state object and starts a fresh worker for each eval.
• Disposable serialized state has a hard 1,000,000-byte limit; an oversized or non-JSON state fails the eval and leaves the previous committed state intact.
• Ordinary Python globals and JavaScript lexical bindings do not survive the disposable worker boundary.
• Opt-in engine: "persistent" keeps the Python state dictionary inside one long-lived worker without a host serialization round-trip. JavaScript remains disposable in this mode.
• Native Windows (win32) rejects the persistent engine before spawning a broker. It does not downgrade to disposable execution; persistent worker-tree lifecycle support remains unavailable until native termination behavior is verified.
• /eval-reset invalidates the lifecycle generation, terminates the exact active or idle worker, waits for that broker to die and for the previously queued eval tail to settle, then returns. Prior queued evals reject.
• Session shutdown performs the same drain and exact retirement, permanently closes the runtime, and rejects new work.
• Persistent Python cancellation first uses SIGINT and retains the worker only when the worker proves that interrupt was handled. Fatal protocol, timeout-escalation, or unexpected-exit paths retire the exact old broker before a fresh worker can spawn; the first result from that replacement reports kernelReused: false.

Install and activate

From the package directory:

npm install
npm run check
pi install /home/tryinget/ai-society/softwareco/owned/pi-extensions/packages/pi-eval-kernel

Then run /reload in Pi and verify with a real eval call. Installation/reload is intentionally separate from package validation.

Development

npm install
npm run test:unit
npm run check
npm run release:check

From the monorepo root:

bash ./scripts/package-quality-gate.sh ci packages/pi-eval-kernel
node ./scripts/pi-host-compatibility-canary.mjs run \
  --profile current \
  --scenario code-mode-extension-factory-contract

Pi host packages remain optional peers rather than persistent package dev dependencies. The root canary temporarily materializes its exact host contract, compiles the extension factory against the real ExtensionAPI, and then restores the lockfile-declared host-package absence. This keeps ordinary npm ci and npm audit free of vulnerabilities inherited only from a published host shrinkwrap.

The full release check packs and installs the tarball into isolated TMPDIR-backed Pi/npm state, then executes one JavaScript and one Python eval through Pi. It needs Pi authentication and reuses the operator's configured default provider/model unless PI_TEST_DEFAULT_PROVIDER, PI_TEST_DEFAULT_MODEL, and optionally PI_TEST_ENABLED_MODELS select another authenticated model. Use release:check:quick only when an artifact-only check is intentionally sufficient.

Known boundary

Pi 0.83.0 does not expose a governed pi.invokeTool(name, args) API to coding-agent extensions. Consequently, this package uses an explicit capability registry and owner-runtime adapters. It does not bypass Pi internals to call arbitrary third-party tools.

Architecture: Code-mode architecture.