@sigrun/ext-codemode 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-10-27
+### Changed
+- Re-released through CI trusted publishing; this version carries SLSA
+  provenance. No functional change from 0.1.0.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+### Added
+- Renamed to `@sigrun/ext-codemode` for the 0.1.0 release (repo stays
+  `sigrun-ai/sigrun-ext-codemode`): published package metadata
+  (`publishConfig` access/provenance), host modules moved to
+  `peerDependencies` mirrored in `devDependencies` at exact `1.3.0`
+  (`quickjs-wasi` remains the one runtime dependency), and a manifest
+  hygiene check wired into `npm test`.
+- sigrun loader-contract wrapper over pi-durable's `createCodemodeExtension`:
+  a `CodemodeSandbox` pinned `timeoutMs: 300_000` / `memoryLimitBytes: 256 MiB`
+  at construction, MCP-config-driven namespaces (`SIGRUN_MCP_CONFIG` →
+  `~/.config/sigrun/mcp.json; snapshot semantics), and the installed-not-offered
+  notice section.
+- Boot canary (`scripts/canary.mjs`): wasm resolution + a real harness
+  `return 1+1`, fail-loud exit 1 — the image entry pre-step.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @sigrun/ext-codemode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The codemode extension for sigrun (pi-durable): the `codemode` tool —
+model-written JavaScript run in a QuickJS sandbox, whose script survives
+a restart — installed via upstream's
+`createCodemodeExtension` (`@earendil-works/pi-durable/codemode`) with
+sigrun's config and prompt additions.
+
+The sigrun extension-package contract: the default export is a factory
+taking no arguments, returning `{ extension }`.
+
+## What the factory does
+
+1. Reads the MCP namespace snapshot ONCE from the same config
+   sigrun-ext-mcp reads: `SIGRUN_MCP_CONFIG` env override →
+   `~/.config/sigrun/mcp.json`. One `CodemodeNamespace` per enabled
+   server, `prefix: "<server>/"`. Absent file → empty namespaces (the
+   codemode tool + section still ship). A bad file warns at factory time
+   (best-effort) and installs un-namespaced rather than throwing — a bad
+   config must not cost the model its codemode tool.
+2. Builds the QuickJS sandbox (`CodemodeSandbox` from
+   `@earendil-works/pi-codemode`) with pinned constructor options:
+   `timeoutMs: 300_000`, `memoryLimitBytes: 256 MiB`.
+3. Wraps upstream's `createCodemodeExtension({ sandbox, namespaces })`
+   with a companion `codemode_notice` section (below).
+
+Config fields read per server entry (the sigrun-ext-mcp shapes,
+duplicated here because that package is not npm-published): `enabled` /
+`disabled` (either false means off), `exposure`
+(`"codemode"` default | `"deferred"` | `"direct"` | `"hidden"`, plus the
+pi alias `"codemode-deferred"`), and `toolExposure` overrides. A server
+resolving fully `hidden` (server default `hidden` and every override
+`hidden`) is excluded from the snapshot — hidden tools never register,
+so nothing scripts can call remains. Per-tool `hidden` resolution is
+sigrun-ext-mcp's job at registration time; this snapshot only groups by
+prefix, and hidden tools never reach `agent.callable` to be grouped.
+
+### The deadline (verified against pi-codemode 1.2.0)
+
+The sandbox constructor's `timeoutMs` governs the plain
+`sandbox.execute()` surface. The durable codemode tool path
+(`sandbox.start()`) takes its deadline from the script's own first line:
+
+```js
+// @options: {"timeout_ms": 60000}
+while (true) {}
+```
+
+A script without an options line has NO deadline (the constructor cap
+does not apply there) — models should be prompted to set one; sigrun's
+system prompt carries that guidance. The pinned constructor options
+still bound the plain sandbox surface and document the ceiling.
+
+## The warn-if-not-offered section
+
+Upstream's `codemode` section lists script-callable tools (grouped by
+namespace) but does not know whether the `codemode` tool itself is
+model-offered. When the extension is installed yet the tool is excluded
+from a request's offered set (Settings → default tools), the companion
+`codemode_notice` section renders:
+
+> codemode scripts are available but the tool is not offered; enable it
+> via Settings → default tools
+
+When the tool is offered the section renders NOTHING (returns
+`undefined`; no tag is written) — de-duplication with upstream's listing
+by construction. Mechanism choice: a companion section rather than a
+`wrapSection` on upstream's key — the wrap could only prepend text
+around upstream's render, while the companion keys the notice to the
+not-offered condition exactly and leaves the upstream render untouched.
+Both sections are registered by the one extension this package installs,
+so the pair always travels together.
+
+## Tool naming: `<server>/<tool>` (decision, agreeing with sigrun-ext-mcp)
+
+Tools keep the `<server>/<tool>` shape rather than upstream pi's
+`mcp__<server>__<tool>`; the codemode namespaces use
+`prefix: "<server>/"`, so upstream's longest-prefix grouping renders per
+server with no renames. The same decision is recorded in
+sigrun-ext-mcp's README; the two must stay consistent.
+
+## Package replacement semantics (slice 4)
+
+Replace this package by not installing it and installing yours: the
+surface is one tool named exactly `codemode` (plus the companion
+`codemode_notice` section and the factory-time namespace snapshot), so a
+per-name replacement is trivial — uninstall ours, install the replacement
+under the same tool name. Do NOT co-install: pi-durable resolves
+cross-extension duplicate tool names last-selected-wins, so a co-installed
+replacement silently shadows the original. Sigrun's extension loader now
+makes the shadowing visible at boot (it `console.warn`s once per duplicate
+tool name, naming the extensions and the last-wins resolution), but the
+warning changes nothing: last-wins stands. Replace, don't co-install.
+
+## Dependencies
+
+`quickjs-wasi` is a REAL dependency of this package, not a transitive
+courtesy: pi-codemode's worker resolves `quickjs-wasi/quickjs.wasm`
+from disk at the first script. A re-pinned or deduped-away transitive
+copy strands the wasm file, and the first codemode call fails at runtime
+(in prod: a 500 on the first script). The canary test
+(`test/canary.spec.ts`) asserts the wasm resolves and runs
+`return 1 + 1` against the BUILT package — the same assertions Task 8
+wires into the container image build.
+
+## Development
+
+```sh
+npm install && npm test        # vitest run (includes the canary + the runaway test, last)
+npm run typecheck
+npm run build
+```
+
+The runaway-script test (`while (true) {}` with a 1s `timeout_ms`) is
+the LAST test in `test/codemode.test.ts`, so a wall-clock death on it
+still ships the rest of the suite.

package/dist/config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The codemode config snapshot: the mcp.json-derived namespace list.
+ *
+ * Reuses the MCP config RESOLUTION and the namespace-relevant parse SHAPES
+ * from sigrun-ext-mcp (rev-3 ruling accepts the duplicated parse of the
+ * config file across repos; sigrun-ext-mcp is not npm-published, so its
+ * `parseMcpConfig` cannot be imported here — the shapes are duplicated
+ * with the derivations quoted below for review parity).
+ *
+ * Resolution order (identical to sigrun-ext-mcp src/config.ts):
+ *   1. `SIGRUN_MCP_CONFIG` env override — an explicit path to an mcp.json
+ *   2. `~/.config/sigrun/mcp.json` (the sigrun config dir)
+ *
+ * What we read from each server entry:
+ *   - `serverEnabled` (mcp repo's derivation): `enabled: false` OR
+ *     `disabled: true` skips the server entirely.
+ *   - Exposure (mcp repo's shape): a server-default `exposure` word, plus
+ *     `toolExposure` overrides mapping exact tool names or `*`-patterns to
+ *     exposure words; the pi alias `codemode-deferred` normalizes to
+ *     `codemode`. A server whose tools all resolve `hidden` contributes
+ *     nothing scripts can call (hidden tools never register), so it is
+ *     excluded from the snapshot: that happens when the server default is
+ *     `hidden` and every override is `hidden` too (an exact name wins over
+ *     patterns; among patterns the first match in config order wins — so
+ *     only a fully-hidden override table leaves every tool hidden).
+ *
+ * Snapshot semantics (the spec ruling): the config is read ONCE at factory
+ * time; late or flapping servers render un-namespaced in the section until
+ * the next boot. The section BODY re-renders live from
+ * `PromptInput.agent.callable` each turn (upstream's render), so tool
+ * lists are never stale — only the namespace GROUPING is a snapshot.
+ */
+import type { CodemodeNamespace } from "@earendil-works/pi-durable/codemode";
+/** The env override the config store reads (sigrun-ext-mcp's name). */
+export declare const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
+/** The exposure words, after normalization (mcp repo's McpExposure). */
+declare const EXPOSURE_WORDS: readonly ["codemode", "deferred", "direct", "hidden"];
+type ExposureWord = (typeof EXPOSURE_WORDS)[number];
+/** One server entry as this package needs it (a subset of the mcp repo's
+ * McpServerConfig: only the namespace-relevant fields). */
+export interface McpServerEntry {
+    /** Skip this server entirely (either false means off). */
+    readonly enabled?: boolean;
+    readonly disabled?: boolean;
+    /** Server-default exposure (default "codemode"). */
+    readonly exposure?: ExposureWord;
+    /** Per-tool overrides: exact names beat `*`-patterns; first pattern wins. */
+    readonly toolExposure?: Readonly<Record<string, ExposureWord>>;
+}
+/** Resolve the config path without reading it (for diagnostics). */
+export declare function resolveMcpConfigPath(env?: NodeJS.ProcessEnv): string;
+/** Whether a configured server participates at all (mcp repo's
+ * `serverEnabled`): `enabled: false` and `disabled: true` both skip it. */
+export declare function serverEnabled(server: McpServerEntry): boolean;
+/**
+ * Read the mcp.json from the resolved path and build the namespace
+ * snapshot: one `CodemodeNamespace` per participating server with prefix
+ * `"<server>/"` (the namespace ruler: our tool-name shape is already
+ * `<server>/<tool>`, so upstream's longest-prefix grouping needs no renames).
+ *
+ * A missing file is an EMPTY namespace list (the extension still ships its
+ * codemode tool + section). An existing-but-bad file or entry warns at
+ * factory time (the spec's best-effort boot log; NOT the contract — a bad
+ * config must not cost the model its codemode tool) and the extension
+ * installs un-namespaced rather than throwing.
+ */
+export declare function loadNamespaces(env?: NodeJS.ProcessEnv): readonly CodemodeNamespace[];
+export {};

package/dist/config.js

@@ -0,0 +1,166 @@
+/**
+ * The codemode config snapshot: the mcp.json-derived namespace list.
+ *
+ * Reuses the MCP config RESOLUTION and the namespace-relevant parse SHAPES
+ * from sigrun-ext-mcp (rev-3 ruling accepts the duplicated parse of the
+ * config file across repos; sigrun-ext-mcp is not npm-published, so its
+ * `parseMcpConfig` cannot be imported here — the shapes are duplicated
+ * with the derivations quoted below for review parity).
+ *
+ * Resolution order (identical to sigrun-ext-mcp src/config.ts):
+ *   1. `SIGRUN_MCP_CONFIG` env override — an explicit path to an mcp.json
+ *   2. `~/.config/sigrun/mcp.json` (the sigrun config dir)
+ *
+ * What we read from each server entry:
+ *   - `serverEnabled` (mcp repo's derivation): `enabled: false` OR
+ *     `disabled: true` skips the server entirely.
+ *   - Exposure (mcp repo's shape): a server-default `exposure` word, plus
+ *     `toolExposure` overrides mapping exact tool names or `*`-patterns to
+ *     exposure words; the pi alias `codemode-deferred` normalizes to
+ *     `codemode`. A server whose tools all resolve `hidden` contributes
+ *     nothing scripts can call (hidden tools never register), so it is
+ *     excluded from the snapshot: that happens when the server default is
+ *     `hidden` and every override is `hidden` too (an exact name wins over
+ *     patterns; among patterns the first match in config order wins — so
+ *     only a fully-hidden override table leaves every tool hidden).
+ *
+ * Snapshot semantics (the spec ruling): the config is read ONCE at factory
+ * time; late or flapping servers render un-namespaced in the section until
+ * the next boot. The section BODY re-renders live from
+ * `PromptInput.agent.callable` each turn (upstream's render), so tool
+ * lists are never stale — only the namespace GROUPING is a snapshot.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+/** The env override the config store reads (sigrun-ext-mcp's name). */
+export const MCP_CONFIG_ENV = "SIGRUN_MCP_CONFIG";
+/** The exposure words, after normalization (mcp repo's McpExposure). */
+const EXPOSURE_WORDS = ["codemode", "deferred", "direct", "hidden"];
+/** Parse one exposure word; the pi alias normalizes to "codemode". */
+const EXPOSURE_WORD_SET = new Set(EXPOSURE_WORDS);
+function parseExposure(value, where) {
+    if (value === "codemode-deferred")
+        return "codemode";
+    if (typeof value !== "string" || !EXPOSURE_WORD_SET.has(value)) {
+        throw new Error(`${where} exposure must be one of ${EXPOSURE_WORDS.map((word) => JSON.stringify(word)).join(", ")} (or "codemode-deferred", the pi alias for "codemode")`);
+    }
+    return value;
+}
+/** Resolve the config path without reading it (for diagnostics). */
+export function resolveMcpConfigPath(env = process.env) {
+    const override = env[MCP_CONFIG_ENV];
+    if (override !== undefined && override !== "") {
+        // A relative override resolves against cwd, like sigrun's other paths.
+        return isAbsolute(override) ? override : resolve(override);
+    }
+    return resolve(homedir(), ".config", "sigrun", "mcp.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Whether a configured server participates at all (mcp repo's
+ * `serverEnabled`): `enabled: false` and `disabled: true` both skip it. */
+export function serverEnabled(server) {
+    return server.enabled !== false && server.disabled !== true;
+}
+/** Whether every tool of this server resolves `hidden`: the server default
+ * is `hidden` and no override can un-hide a tool (every override value is
+ * `hidden`; an exact name or pattern pointing elsewhere un-hides whatever
+ * it matches). Hidden tools never register, so such a server contributes
+ * nothing scripts can call and gets no namespace. */
+function serverFullyHidden(server) {
+    if ((server.exposure ?? "codemode") !== "hidden")
+        return false;
+    return Object.values(server.toolExposure ?? {}).every((word) => word === "hidden");
+}
+/**
+ * Read the mcp.json from the resolved path and build the namespace
+ * snapshot: one `CodemodeNamespace` per participating server with prefix
+ * `"<server>/"` (the namespace ruler: our tool-name shape is already
+ * `<server>/<tool>`, so upstream's longest-prefix grouping needs no renames).
+ *
+ * A missing file is an EMPTY namespace list (the extension still ships its
+ * codemode tool + section). An existing-but-bad file or entry warns at
+ * factory time (the spec's best-effort boot log; NOT the contract — a bad
+ * config must not cost the model its codemode tool) and the extension
+ * installs un-namespaced rather than throwing.
+ */
+export function loadNamespaces(env = process.env) {
+    const path = resolveMcpConfigPath(env);
+    if (!existsSync(path))
+        return [];
+    try {
+        return parseNamespaces(readFileSync(path, "utf8"), path);
+    }
+    catch (cause) {
+        console.warn(`sigrun-ext-codemode: mcp config ${path} is invalid (codemode ` +
+            `tools install un-namespaced): ${cause instanceof Error ? cause.message : String(cause)}`);
+        return [];
+    }
+}
+/** Parse and validate the config body into the namespace snapshot. */
+function parseNamespaces(text, path) {
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed) || !isRecord(parsed.servers)) {
+        throw new Error(`must be a JSON object with a "servers" object mapping names to server entries`);
+    }
+    const namespaces = [];
+    for (const [name, entry] of Object.entries(parsed.servers)) {
+        if (!isRecord(entry)) {
+            throw new Error(`server "${name}" must be an object`);
+        }
+        const server = parseServerEntry(entry, path, name);
+        if (!serverEnabled(server))
+            continue;
+        if (serverFullyHidden(server)) {
+            // The spec's best-effort boot log: hidden-only rows.
+            console.warn(`sigrun-ext-codemode: mcp server "${name}" resolves fully ` +
+                `hidden (excluded from the codemode namespaces)`);
+            continue;
+        }
+        namespaces.push({
+            name,
+            description: `MCP server ${name} (tools ${name}/<tool>, registered by sigrun-ext-mcp)`,
+            prefix: `${name}/`,
+        });
+    }
+    return namespaces;
+}
+/** Validate one server entry's namespace-relevant fields. */
+function parseServerEntry(entry, path, name) {
+    for (const field of ["enabled", "disabled"]) {
+        const value = entry[field];
+        if (value !== undefined && typeof value !== "boolean") {
+            throw new Error(`mcp config ${path}: server "${name}" ${field} must be a boolean`);
+        }
+    }
+    return {
+        ...(entry.enabled === undefined
+            ? {}
+            : { enabled: entry.enabled }),
+        ...(entry.disabled === undefined
+            ? {}
+            : { disabled: entry.disabled }),
+        ...(entry.exposure === undefined
+            ? {}
+            : {
+                exposure: parseExposure(entry.exposure, `mcp config ${path}: server "${name}"`),
+            }),
+        ...(entry.toolExposure === undefined
+            ? {}
+            : {
+                toolExposure: parseToolExposure(entry.toolExposure, path, name),
+            }),
+    };
+}
+function parseToolExposure(value, path, name) {
+    if (!isRecord(value)) {
+        throw new Error(`mcp config ${path}: server "${name}" toolExposure must be an object`);
+    }
+    const overrides = {};
+    for (const [key, exposure] of Object.entries(value)) {
+        overrides[key] = parseExposure(exposure, `mcp config ${path}: server "${name}" toolExposure "${key}"`);
+    }
+    return overrides;
+}

package/dist/extension.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The codemode extension wrapper (sigrun-ext-codemode): installs upstream's
+ * `codemode` extension (the `codemode` tool, named exactly, with
+ * `callers: ["model"]`, plus the upstream `codemode` prompt section) with
+ * our two sigrun additions:
+ *
+ * 1. The MCP namespace snapshot (src/config.ts): one `CodemodeNamespace`
+ *    per configured MCP server, prefix `"<server>/"`, read once at factory
+ *    time. The upstream section groups `agent.callable` tools by the
+ *    longest matching prefix, so sigrun's `<server>/<tool>` MCP tools
+ *    render grouped per server with no renames (the namespace ruler).
+ *
+ * 2. The warn-if-not-offered channel (the spec's corrected mechanism):
+ *    when the extension is installed but the `codemode` TOOL is not
+ *    model-offered in this request, a short companion section renders the
+ *    enable notice instead of silence. Upstream's `codemode` section
+ *    renders `undefined` when nothing is callable, and it does NOT know
+ *    whether the codemode tool itself is offered — a model whose
+ *    Settings → default tools excluded `codemode` would see MCP tools
+ *    listed as script-callable with no way to learn the tool is off. The
+ *    companion section renders NOTHING (returns undefined, so no tag is
+ *    written) whenever the tool IS offered, which de-duplicates with
+ *    upstream's listing by construction.
+ *
+ * Mechanism choice (documented for review): a `wrapSection("codemode", …)`
+ * would also work — pi-durable's `resolveAgent` applies wraps across
+ * selected extensions, and our factory owns both the wrapped section and
+ * the wrapper — but the wrap could only prepend text around upstream's
+ * render, and upstream's render already covers the offered case; the
+ * companion section keys the notice to the not-offered condition exactly,
+ * leaves the upstream render untouched, and renders undefined (absent from
+ * the prompt, no `<key>` tag written) when offered. Companion section it
+ * is. Both extensions are installed by the same factory, so the pair
+ * (upstream section + notice section) travels together.
+ */
+import { type CodemodeNamespace } from "@earendil-works/pi-durable/codemode";
+import type { CodemodeSandboxBase } from "@earendil-works/pi-codemode/portable";
+import { type Extension, type PromptInput } from "@earendil-works/pi-durable";
+/** Our companion section's key (distinct from upstream's `"codemode"`). */
+export declare const CODEMODE_NOTICE_SECTION_KEY = "codemode_notice";
+/** The enable notice, the spec's wording. */
+export declare const CODEMODE_NOT_OFFERED_NOTICE: string;
+/**
+ * The companion section render: the notice ONLY when the codemode tool
+ * is installed (one of the selected extensions registers it) yet not
+ * model-offered in this request (`agent.tools` is the offered set);
+ * `undefined` otherwise (offered, or not installed — nothing to warn
+ * about). Installation cannot be read from `agent.callable`: that set
+ * holds only tools-callable tools, and `codemode` registers with
+ * `callers: ["model"]`.
+ */
+export declare function renderCodemodeNotice(input: PromptInput): string | undefined;
+/**
+ * The sigrun codemode extension: upstream's `codemode` extension (tool +
+ * section, with our namespace snapshot) plus the companion notice section.
+ */
+export declare function createSigrunCodemodeExtension(options: {
+    /** Runs the scripts: `CodemodeSandbox` on Node. */
+    readonly sandbox: CodemodeSandboxBase;
+    /** The factory-time MCP namespace snapshot (src/config.ts). */
+    readonly namespaces?: readonly CodemodeNamespace[];
+}): Extension;

package/dist/extension.js

@@ -0,0 +1,80 @@
+/**
+ * The codemode extension wrapper (sigrun-ext-codemode): installs upstream's
+ * `codemode` extension (the `codemode` tool, named exactly, with
+ * `callers: ["model"]`, plus the upstream `codemode` prompt section) with
+ * our two sigrun additions:
+ *
+ * 1. The MCP namespace snapshot (src/config.ts): one `CodemodeNamespace`
+ *    per configured MCP server, prefix `"<server>/"`, read once at factory
+ *    time. The upstream section groups `agent.callable` tools by the
+ *    longest matching prefix, so sigrun's `<server>/<tool>` MCP tools
+ *    render grouped per server with no renames (the namespace ruler).
+ *
+ * 2. The warn-if-not-offered channel (the spec's corrected mechanism):
+ *    when the extension is installed but the `codemode` TOOL is not
+ *    model-offered in this request, a short companion section renders the
+ *    enable notice instead of silence. Upstream's `codemode` section
+ *    renders `undefined` when nothing is callable, and it does NOT know
+ *    whether the codemode tool itself is offered — a model whose
+ *    Settings → default tools excluded `codemode` would see MCP tools
+ *    listed as script-callable with no way to learn the tool is off. The
+ *    companion section renders NOTHING (returns undefined, so no tag is
+ *    written) whenever the tool IS offered, which de-duplicates with
+ *    upstream's listing by construction.
+ *
+ * Mechanism choice (documented for review): a `wrapSection("codemode", …)`
+ * would also work — pi-durable's `resolveAgent` applies wraps across
+ * selected extensions, and our factory owns both the wrapped section and
+ * the wrapper — but the wrap could only prepend text around upstream's
+ * render, and upstream's render already covers the offered case; the
+ * companion section keys the notice to the not-offered condition exactly,
+ * leaves the upstream render untouched, and renders undefined (absent from
+ * the prompt, no `<key>` tag written) when offered. Companion section it
+ * is. Both extensions are installed by the same factory, so the pair
+ * (upstream section + notice section) travels together.
+ */
+import { CODEMODE_TOOL_NAME, createCodemodeExtension, } from "@earendil-works/pi-durable/codemode";
+import { defineExtension, } from "@earendil-works/pi-durable";
+/** Our companion section's key (distinct from upstream's `"codemode"`). */
+export const CODEMODE_NOTICE_SECTION_KEY = "codemode_notice";
+/** The enable notice, the spec's wording. */
+export const CODEMODE_NOT_OFFERED_NOTICE = "codemode scripts are available but the tool is not offered; enable it " +
+    "via Settings → default tools";
+/**
+ * The companion section render: the notice ONLY when the codemode tool
+ * is installed (one of the selected extensions registers it) yet not
+ * model-offered in this request (`agent.tools` is the offered set);
+ * `undefined` otherwise (offered, or not installed — nothing to warn
+ * about). Installation cannot be read from `agent.callable`: that set
+ * holds only tools-callable tools, and `codemode` registers with
+ * `callers: ["model"]`.
+ */
+export function renderCodemodeNotice(input) {
+    const installed = input.agent.extensions.some((extension) => (extension.tools ?? []).some((tool) => tool.name === CODEMODE_TOOL_NAME));
+    if (!installed)
+        return undefined; // not installed: no lie to correct
+    const offered = input.agent.tools.some((tool) => tool.name === CODEMODE_TOOL_NAME);
+    return offered ? undefined : CODEMODE_NOT_OFFERED_NOTICE;
+}
+/**
+ * The sigrun codemode extension: upstream's `codemode` extension (tool +
+ * section, with our namespace snapshot) plus the companion notice section.
+ */
+export function createSigrunCodemodeExtension(options) {
+    const upstream = createCodemodeExtension({
+        sandbox: options.sandbox,
+        ...(options.namespaces === undefined
+            ? {}
+            : { namespaces: options.namespaces }),
+    });
+    return defineExtension({
+        ...upstream,
+        sections: [
+            ...(upstream.sections ?? []),
+            {
+                key: CODEMODE_NOTICE_SECTION_KEY,
+                render: renderCodemodeNotice,
+            },
+        ],
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * sigrun-ext-codemode: the codemode factory (the loader contract).
+ *
+ * The sigrun extension-package contract (sigrun's src/harness/loader.ts):
+ * the default export is a FACTORY TAKING NO ARGUMENTS, returning
+ * `{ extension }`. The loader calls it synchronously at boot, before
+ * `Harness.open` reads the registry.
+ *
+ * What the factory does, in order:
+ *   1. Reads the MCP namespace snapshot ONCE (src/config.ts):
+ *      `SIGRUN_MCP_CONFIG` → `~/.config/sigrun/mcp.json`; absent file →
+ *      empty namespaces (the extension still ships its codemode tool +
+ *      section); a bad file warns and installs un-namespaced.
+ *   2. Builds the QuickJS sandbox with the pinned constructor options
+ *      (timeoutMs 300_000 — pi-codemode's own default, restated so the
+ *      contract does not drift; memoryLimitBytes 256 MiB — a real cap
+ *      where the upstream default is unbounded wasm32).
+ *   3. Wraps upstream's `createCodemodeExtension({ sandbox, namespaces })`
+ *      with the companion notice section (src/extension.ts).
+ *
+ * Note on `timeoutMs` (verified against pi-codemode 1.2.0): the
+ * CONSTRUCTOR timeout governs `sandbox.execute()`; the durable codemode
+ * tool path (`sandbox.start()`) takes its deadline from the script's own
+ * `// @options: {"timeout_ms": N}` line (no options line → no deadline:
+ * the sandbox default does not apply there). The constructor cap is
+ * still the right pin: it bounds every execution of the plain sandbox
+ * surface and documents the intended ceiling.
+ *
+ * `quickjs-wasi` is a REAL dependency of this package, not a transitive
+ * courtesy: pi-codemode's worker resolves `quickjs-wasi/quickjs.wasm`
+ * from disk at the first script. A re-pinned or deduped-away transitive
+ * copy strands the wasm file and the first codemode call fails at runtime
+ * (500s in prod) — declaring it here pins the resolution to this
+ * package's own tree.
+ */
+import type { CodemodeSandboxBase } from "@earendil-works/pi-codemode/portable";
+import type { CodemodeNamespace } from "@earendil-works/pi-durable/codemode";
+import type { Extension } from "@earendil-works/pi-durable";
+/** Pinned per-execution wall-clock deadline (pi-codemode's default). */
+export declare const CODEMODE_TIMEOUT_MS = 300000;
+/** Pinned QuickJS heap cap (256 MiB; upstream default is unbounded). */
+export declare const CODEMODE_MEMORY_LIMIT_BYTES: number;
+/** What {@link createCodemodeWiring} returns (the loader contract). */
+export interface CodemodeWiring {
+    /** The extension to install into the harness registry. */
+    readonly extension: Extension;
+    /** The sandbox the extension runs scripts in (call `close()` on shutdown). */
+    readonly sandbox: CodemodeSandboxBase;
+    /** The factory-time namespace snapshot (empty without an mcp.json). */
+    readonly namespaces: readonly CodemodeNamespace[];
+    /**
+     * Close the sandbox: aborts in-flight executions and stops the worker
+     * machinery. Called by hosts on harness shutdown; a fresh factory builds
+     * a fresh sandbox, so a closed wiring is never reused.
+     */
+    close(): Promise<void>;
+}
+/**
+ * The codemode factory (the loader contract: no arguments; config resolves
+ * from the package context). Each call builds a FRESH sandbox — one
+ * wiring, one sandbox, no shared worker state across installs.
+ */
+export declare function createCodemodeWiring(): CodemodeWiring;
+/**
+ * The sigrun extension-package contract: the default export is a factory
+ * taking no arguments, returning `{ extension }`.
+ */
+declare const _default: typeof createCodemodeWiring;
+export default _default;
+export { CODEMODE_NOT_OFFERED_NOTICE, CODEMODE_NOTICE_SECTION_KEY, renderCodemodeNotice, } from "./extension.js";
+export { loadNamespaces, MCP_CONFIG_ENV, resolveMcpConfigPath, serverEnabled, } from "./config.js";
+export type { McpServerEntry } from "./config.js";

package/dist/index.js

@@ -0,0 +1,68 @@
+/**
+ * sigrun-ext-codemode: the codemode factory (the loader contract).
+ *
+ * The sigrun extension-package contract (sigrun's src/harness/loader.ts):
+ * the default export is a FACTORY TAKING NO ARGUMENTS, returning
+ * `{ extension }`. The loader calls it synchronously at boot, before
+ * `Harness.open` reads the registry.
+ *
+ * What the factory does, in order:
+ *   1. Reads the MCP namespace snapshot ONCE (src/config.ts):
+ *      `SIGRUN_MCP_CONFIG` → `~/.config/sigrun/mcp.json`; absent file →
+ *      empty namespaces (the extension still ships its codemode tool +
+ *      section); a bad file warns and installs un-namespaced.
+ *   2. Builds the QuickJS sandbox with the pinned constructor options
+ *      (timeoutMs 300_000 — pi-codemode's own default, restated so the
+ *      contract does not drift; memoryLimitBytes 256 MiB — a real cap
+ *      where the upstream default is unbounded wasm32).
+ *   3. Wraps upstream's `createCodemodeExtension({ sandbox, namespaces })`
+ *      with the companion notice section (src/extension.ts).
+ *
+ * Note on `timeoutMs` (verified against pi-codemode 1.2.0): the
+ * CONSTRUCTOR timeout governs `sandbox.execute()`; the durable codemode
+ * tool path (`sandbox.start()`) takes its deadline from the script's own
+ * `// @options: {"timeout_ms": N}` line (no options line → no deadline:
+ * the sandbox default does not apply there). The constructor cap is
+ * still the right pin: it bounds every execution of the plain sandbox
+ * surface and documents the intended ceiling.
+ *
+ * `quickjs-wasi` is a REAL dependency of this package, not a transitive
+ * courtesy: pi-codemode's worker resolves `quickjs-wasi/quickjs.wasm`
+ * from disk at the first script. A re-pinned or deduped-away transitive
+ * copy strands the wasm file and the first codemode call fails at runtime
+ * (500s in prod) — declaring it here pins the resolution to this
+ * package's own tree.
+ */
+import { CodemodeSandbox } from "@earendil-works/pi-codemode";
+import { loadNamespaces } from "./config.js";
+import { createSigrunCodemodeExtension } from "./extension.js";
+/** Pinned per-execution wall-clock deadline (pi-codemode's default). */
+export const CODEMODE_TIMEOUT_MS = 300_000;
+/** Pinned QuickJS heap cap (256 MiB; upstream default is unbounded). */
+export const CODEMODE_MEMORY_LIMIT_BYTES = 256 * 1024 * 1024;
+/**
+ * The codemode factory (the loader contract: no arguments; config resolves
+ * from the package context). Each call builds a FRESH sandbox — one
+ * wiring, one sandbox, no shared worker state across installs.
+ */
+export function createCodemodeWiring() {
+    const namespaces = loadNamespaces();
+    const sandbox = new CodemodeSandbox({
+        timeoutMs: CODEMODE_TIMEOUT_MS,
+        memoryLimitBytes: CODEMODE_MEMORY_LIMIT_BYTES,
+    });
+    const extension = createSigrunCodemodeExtension({ sandbox, namespaces });
+    return {
+        extension,
+        sandbox,
+        namespaces,
+        close: () => sandbox.close(),
+    };
+}
+/**
+ * The sigrun extension-package contract: the default export is a factory
+ * taking no arguments, returning `{ extension }`.
+ */
+export default createCodemodeWiring;
+export { CODEMODE_NOT_OFFERED_NOTICE, CODEMODE_NOTICE_SECTION_KEY, renderCodemodeNotice, } from "./extension.js";
+export { loadNamespaces, MCP_CONFIG_ENV, resolveMcpConfigPath, serverEnabled, } from "./config.js";

package/package.json

@@ -1,6 +1,59 @@
 {
-  "name": "@sigrun/ext-codemode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@sigrun/ext-codemode",
+	"version": "0.1.1",
+	"description": "Codemode extension for sigrun (pi-durable): the `codemode` tool \u2014 model-written JavaScript in a QuickJS sandbox, with MCP-server tools namespaced as script-callable tools",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/ext-codemode && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"quickjs-wasi": "3.6.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "1.3.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-codemode": "1.3.0",
+		"@earendil-works/pi-durable": "1.3.0"
+	},
+	"devDependencies": {
+		"@earendil-works/chord": "1.3.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-codemode": "1.3.0",
+		"@earendil-works/pi-durable": "1.3.0",
+		"@types/node": "^26.6.4",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-ext-codemode.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-ext-codemode/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-ext-codemode#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	}
+}