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-code-mode."
• "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-code-mode

pi-code-mode adds an eval tool with disposable Python and JavaScript workers plus host-persisted JSON state. 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;
• 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-code-mode/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

• Python and JavaScript persist only values placed in the shared JSON-compatible state object.
• 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.
• /eval-reset terminates active workers, invalidates queued evals, and clears state.
• Session start resets state and active workers; session shutdown closes the runtime and rejects queued evals.
• Timeout or cancellation kills the affected worker; the next admitted call starts a fresh worker with the last successfully committed state.

Install and activate

From the package directory:

npm install
npm run check
pi install /home/tryinget/ai-society/softwareco/owned/pi-extensions/packages/pi-code-mode

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-code-mode
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.