Supply chain
How Luna sources third-party code, what installing it pulls in, and how dependencies are updated. The CI checks that enforce this are listed in CI security, and how a vulnerability in a dependency is rated, fixed or accepted is in Vulnerability management.
What installing Luna pulls in
Runtime dependencies (dependencies in package.json): quickjs-wasi. It is pinned to an
exact version, resolved through package-lock.json, and the workflow sandbox checks the digest
of its WebAssembly module before every run (Workflow sandbox).
@earendil-works/pi-coding-agent, @earendil-works/pi-ai, @earendil-works/pi-tui and typebox
are peer dependencies that pi itself provides, and everything else is dev-only.
tests/clean-install-smoke.ts installs the packed artefact and fails when its dependencies are
not exactly the list above, each pinned to an exact version. Every pi package that an extension or a
test imports must be a peer dependency, and each @earendil-works/* peer is also a dev dependency
pinned to the tested pi version, so the suite resolves it by declaration and not because pi happens
to depend on it (tests/pi-host-peers-smoke.ts).
A release is a vX.Y.Z tag of the public repository, pushed by an operator; the release
workflow's gate runs the whole of ci.yml and security.yml for the release commit
(tests/release-workflow-smoke.ts), but a tag is the release whether or not that workflow is run
(Releasing). pi clones the tag and runs npm install --omit=dev --legacy-peer-deps
in the clone (as for every git package; pi 1.4.0's package manager), so npm installs the runtime
dependency and does not install peer dependencies there. pi's extension loader resolves
@earendil-works/pi-coding-agent, pi-ai, pi-tui and typebox imports in extensions to its
own copies. Both behaviours are pi's; no test in this repository pins them. Everything comes from
the public npm registry at the lockfile's pinned, integrity-checked versions.
If npm delivery is switched on, every version will also carry npm provenance, so
npm audit signatures can verify where it was built.
Vendored code
Twelve extensions under packages/extensions/third_party/ adapt upstream code. Each has a
SOURCE.md recording its upstream, what was changed and when, and THIRD_PARTY_NOTICES.md
(generated from them by node packages/core/gen-notices.ts; npm run verify fails on drift)
carries the licence text and credits. The notice for pi's own example extensions is the upstream MIT
licence with its copyright holder and year.
External sources (packages/core/sources.json)
External pi packages are pinned to an exact version and reviewed before enabling. They are
reference mode: the installer registers each one as its own pi package at the pinned version
when a selected profile includes it. None is bundled into the Luna package. The review text in
sources.json records what each one does, and which newer versions were evaluated and why they
were not adopted.
| Package | Version | In a profile? | Native or opaque parts | Notes |
|---|---|---|---|---|
pi-lens |
4.4.4 | balanced, long-horizon, self-improving, engagement | @ast-grep/napi (native .node), @ast-grep/cli platform binary and tree-sitter WASM |
MIT; Node >=22.19.0. Diagnostics on edit plus 13 pi tools, with exact firewall policy entries. See registration review below. |
pi-readseek |
0.4.26 | long-horizon, self-improving, engagement, lite | @jarkkojs/readseek native CLI and xxhash-wasm |
MIT. Hash-anchored reads and edits. 0.12.0 replaces the tool surface with 16 new tools beside the built-ins, takes @path rule files the firewall's path checks do not see, and was not adopted. |
pi-lean-ctx |
3.11.4 | none (opt-in) | The external lean-ctx Rust CLI, not bundled |
Apache-2.0. Registers extra shell, read and edit tools that the firewall does not classify as shell and secret-guard does not inspect. Installed by install.ts --all only when its CLI is on PATH. Its vendored MCP client bundle is built from @modelcontextprotocol/sdk 1.32, which audit tools cannot see. |
The container image installs pi-mcp-adapter@6.0.0 (and pi) at build time with npm ci
--ignore-scripts from packages/container/tools/package-lock.json, and the overlay
(packages/container/overlays/pi/settings.json) registers that baked copy by path, so nothing is
fetched from npm at start; validate-engagement-env.sh checks the pins agree. See the review below.
pi-mcp-adapter review
The pin is based on the unpacked 6.0.0 tarball, an npm install of it, and the adapter loaded into
pi 1.4.0 in the built container image. This check was run by hand; no test in Luna loads the
adapter (packages/container/README.md describes what the image configures).
- Manifest and install. MIT, Node >=20, one pi extension (
index.ts) and api-mcp-adapterCLI. The package's only lifecycle script isprepack, which npm does not run on install, and no package in its dependency tree has an install script.npm auditand OSV report nothing on the installed tree. - Native and remote parts.
@napi-rs/keyring(a platform.nodebinary) holds OAuth and API keys in the operating system credential store;recheck4.6.0-beta.3 brings a platform binary and a JAR as optional dependencies, as it did in 2.8.0.@typesafe-ai/sdkis the client for Jev semantic tool search onapi.typesafe.ai, used only with an API key; the overlay setsjev: false. Executor (executor.sh) support runs only for a server configured as one. - Peer ranges. pi-ai
^0.84.1 || … || ^1.0.0, pi-tui, typebox and zod are peers, so the adapter runs on pi's own copies. 2.8.0 installed its own pi-ai, pi-tui and typebox as dependencies, which pi 1.4.0 warns can bypass the host's copies. From 2.21.1 to 5.0.0 the pi-ai peer range excludes pi 1.x, and 2.20.0 to 5.1.0 pin@modelcontextprotocol/client2.0.0, which GHSA-6qxp-vccf-f47h affects (fixed in 2.2.0; the adapter pins 2.3.1 from 5.2.0). - Tools and firewall. By default 6.0.0 registers, beside the
mcpproxy, anmcp__<server>proxy per server and a deferredmcp__<server>__<tool>tool per server tool, and runs eachmcpcall as a nested call to that tool. In the image with the 2.8.0 settings, every MCP call was then blocked byengagement-governance's MCP-only mode, and thesettingsblock in Pi'smcp.jsonwas ignored. The overlay therefore moves tomcp-adapter.jsonand the image setsPI_MCP_CONFIG_MODE=exclusiveandMCP_DIRECT_TOOLS=__none__; with them the tool surface ismcpalone, as with 2.8.0, andmcpcalls to both bundled servers succeed with and without MCP-only mode. Luna's tool firewall has no entry formcpormcp__*, so both are unknown tools and ask. It treats a project's.pi/mcp-adapter.json, which 3.0.0 and later read, as a safety-control file, as it does.pi/mcp.json(tests/firewall-shell-smoke.ts). - Behaviour changes since 2.8.0. 3.0.0 starts project-defined servers only after project trust
and per-server approval (the image reads no project MCP files at all), and renames the adapter's
own config file to
mcp-adapter.json. 5.0.0 turns Pi's built-in MCP off in Pi's settings on first start, which the overlay already does. Themcptool'sargsfield takes a JSON string, as in 2.8.0, and the governance and memory tools keep their<server>_<tool>names, soengagement/tool-policy.jsonis unchanged.
Native-binary risk is contained by exact version pins, reference (not bundle) mode, and the
review field per source. A Luna release that changes a pin moves companions on the next
/update.
Companion downloads at run time
pi-lens fetches missing linters, formatters, scanners and language servers on demand, as npm
installs of unpinned latest packages or GitHub release downloads. That happens inside the pi
process, where the firewall sees no tool call, and outside the pinned, checksum-verified set
above. The tool firewall therefore sets PI_LENS_DISABLE_LSP_INSTALL=1 and
PI_LENS_DISABLE_TOOL_INSTALL=1 when it loads. Only an explicit 0 turns installs back on;
any other value, such as an empty string, true or yes, is set to 1, because pi-lens disables
installs only on exactly 1 (tests/tool-firewall-smoke.ts). Tools already on PATH or in ~/.pi-lens/tools keep working.
The pinned pi-lens 4.4.4 honours both switches, including managed tool refreshes
(dist/index.js:31908, :32844, :32968, :33057, :37129, :80154 in that package).
tests/tool-firewall-smoke.ts pins Luna's defaults and preserves explicit operator values.
It tests Luna, not the companion's implementation of those switches.
These switches do not disable missing tree-sitter grammar downloads. Those have a separate
project-trust gate (dist/index.js:56547) and check SHA-256 only when the grammar has a matching
manifest entry (:53837). Vendored grammars refuse a download fallback. This is not a promise
of an offline companion; no test in Luna executes these download paths.
pi-lens registration review
The pin is based on static inspection of the unpacked 3.8.63 and 4.4.4 packages. Neither
package was executed or imported for this review, so loading in a real TUI, provider-backed
write/edit hooks and dependency installation are not validated here. The packages register
pi tools from dist/index.js:717 (3.8.63) and dist/index.js:149051 (4.4.4), the latter
combining always-active and situational tools before registration at :149180. Configuration
can disable tools; situational tools can be activated for subsequent turns.
Every tool in the 4.4.4 pi registration loop has an exact entry in both copies of the shipped
firewall policy. The table records the policy risk class and benign-input tier. An ask
entry produces the firewall's unknown_exec effect at high tier, regardless of a benign
preview input; read and discovery entries produce read at low tier. Credential paths raise
read helpers to high. tests/tool-firewall-smoke.ts pins all 13 identities, classes, tiers,
real tool_call decisions and credential-path blocks; tests/firewall-shell-smoke.ts also
pins path-array handling and the new analysisRoot field. The table's line references are
inside 4.4.4's dist/index.js.
| Tool | Policy risk class / underlying effect | Tier | Decision | Definition |
|---|---|---|---|---|
ast_grep_search |
read_only: structural search, including dump mode |
low | allow | :144109 |
ast_grep_outline |
read_only: syntax outline |
low | allow | :144606 |
ast_grep_replace |
file_write: structural replacement |
high | ask | :143705 |
lsp_navigation |
code_exec: includes mutations and server commands |
high | ask | :145564 |
lens_diagnostics |
read_only: diagnostics, including active scans |
low | allow | :141559 |
lens_diagnostic_mark (new) |
file_write: can insert suppression comments |
high | ask | :143287 |
symbol_search (new) |
read_only: indexed identifier search |
low | allow | :146791 |
module_report |
read_only: source module report |
low | allow | :146332 |
project_report (new) |
read_only: project graph report |
low | allow | :146655 |
read_symbol |
read_only: symbol body |
low | allow | :146445 |
read_enclosing |
read_only: enclosing symbol body |
low | allow | :146532 |
effective_config (new) |
read_only: redacted configuration provenance |
low | allow | :146737 |
pi_lens_activate_tools (new) |
tool_discovery: activates registered situational tools |
low | allow | :139317 |
The new explicit path inputs are symbol_search.paths, effective_config.file and
lens_diagnostic_mark.filePath; existing firewall fields cover them. lens_diagnostics
adds analysisRoot alongside path and paths; the firewall checks all three. The new
project_report and activator accept no paths. read_symbol adds an optional kind selector,
covered by Luna's adapter. Mutation helpers require approval for every call; the firewall
also checks lsp_navigation.newFilePath and the paths of ast_grep_replace and
lens_diagnostic_mark as write targets (tests/firewall-shell-smoke.ts). Activation grants no authority to
execute the activated tools; their individual calls still pass through the firewall.
Removed pi registrations are ast_grep_dump and ast_dump (3.8.63
dist/tools/ast-dump.js:104 and :107) and standalone lsp_diagnostics
(dist/tools/lsp-diagnostics.js:142). Dump is now a search option, and LSP diagnostics route
through lens_diagnostics (4.4.4 dist/index.js:141727). Older policy names are retained
for other reviewed companion surfaces; an entry is not evidence that 4.4.4 registers it.
The MCP registry is separate (dist/index.js:5352) and does not register extra pi tools.
Commands retained from 3.8.63 are lens-toggle, lens-context-toggle, lens-widget-toggle,
lens-tdi, lens-health, lens-tools and lens-allow-edit (3.8.63 dist/index.js:425,
:434, :443, :476, :509, :625, :698; 4.4.4 dist/index.js:148733, :148740,
:148747, :148765, :148820, :148972, :149038). lens-booboo is removed
(3.8.63 :460); lens-map and lens-perf are added (4.4.4 :148797, :148954).
Hooks retained are resources_discover, session_start, tool_call, tool_result,
turn_start, agent_end, turn_end, session_shutdown and context (3.8.63
dist/index.js:748, :761, :896, :1544, :1574, :1578, :1607, :1680, :1695;
4.4.4 dist/index.js:149184, :149207, :149518, :149602, :149641, :149743,
:149882, :150034, :150204). session_before_fork is removed (3.8.63 :887);
session_tree, tool_execution_end and conditional agent_settled are added (4.4.4
:149492, :149612, :150019). These hooks still run inside pi: the firewall does not
sandbox a companion's code or its diagnostic subprocesses, and a read-only policy class
is not process isolation. Active diagnostic scans can launch configured local analysers.
The profile JSON selects the companion as a whole: balanced includes pi-lens and has
no per-tool filter. Installer filters scope Luna's own extensions/skills/prompts, not
a separately registered companion's tools. No Luna test claims a diagnostics-only pi-lens
surface in balanced. The policy decisions above apply wherever its tools are exposed.
4.4.4's manifest is MIT (package.json:92), has native ast-grep dependencies (:128), and
optional web-tree-sitter and jiti (:152); runtime TypeScript is no longer a direct
dependency. It has no preinstall, install or postinstall script. Its source prepare
hook builds, downloads core grammars, sets up git hooks, stamps a lock and warms the loader
(:20); it is not a registry tarball install hook. The ast-grep CLI dependency still needs
a platform binary lifecycle step (dist/index.js:34523); this review did not inspect
or execute dependency tarballs. Native and WASM components remain opaque supply-chain risk.
The earlier pi 1.3 host-dependency warning applies to 3.8.63's pi-tui and typebox
dependencies (package.json:77). In the supplied 4.4.4 manifest they are optional peers:
pi-tui="*", pi-coding-agent="*", typebox="^1.0.0" (package.json:136). The typebox
range still differs from pi's recommended "*", but pi 1.3's
collectExtensionPackageWarnings checks host packages in dependencies, so this manifest
does not meet that warning condition. This was checked against the installed pi loader's
source; no TUI compatibility claim is made.
Evaluating a candidate
Read its tarball (npm pack <name>@<version>, then inspect package.json for pi entries,
peer ranges, dependencies, scripts and licence). If it loads into pi, install it into a scratch
PI_CODING_AGENT_DIR with pi install npm:<name>@<version> and start pi in a terminal to see what
it registers and whether it degrades cleanly. Record the result in review. Do not adopt a
version on the strength of its changelog.
Audit status
CI fails on a high or critical npm audit advisory in any lockfile, on an invalid registry
signature or attestation (npm audit signatures), on any OSV-Scanner finding in the tree and, for
pull requests, on a new dependency with a high-severity advisory (CI security).
The dev tree includes mermaid and jsdom, used only by npm run docs:mermaid to check that the
documentation's diagrams parse; they are never installed by a user of Luna.
Findings that no available update clears (the autonomy image's Debian packages, the upstream gitleaks binary CI runs, vendored bundles audit tools cannot see) are recorded, with their owner, mitigation and review trigger, in the risk-acceptance register.
Update policy
One policy covers every dependency the repository pins.
- Lockfiles everywhere. Every npm tree has a committed lockfile installed with
npm ci --ignore-scripts: the root, the MCP servers underpackages/container/mcp-servers/, and the pi tool trees the autonomy and container images install from (packages/autonomy/image/tools/,packages/container/tools/). The docs toolchain isrequirements-docs.txt, compiled with hashes and installed with--require-hashes. Base images are pinned by digest in theirFROMlines, CI scanner images by digest and downloaded binaries by SHA-256. The Android build's Gradle wrapper is validated against the checksum Gradle publishes. A new manifest without Dependabot and OSV coverage failstests/scan-coverage-smoke.ts; a lockfile entry outside the registry, without a sha512 hash or with an unreviewed install script failsnpm run security:lockfile. - Not locked: the autonomy image's language tools are pinned global installs (locking them surfaces advisories with no upstream fix), and a companion's own dependency tree is resolved by npm at install time (Companion installs).
- Cadence and cooldown. Dependabot proposes grouped updates weekly for actions, npm, pip,
Docker and Gradle, and waits 7 days after a release before proposing it
(
.github/dependabot.yml): most malicious versions are found and pulled within days. A security update for an advisory is proposed without waiting for the weekly run when Dependabot security updates are on (Repository settings). - Every update is a reviewed pull request gated like any other change; an action bump also follows the allowed-actions procedure.
- Held by hand, not by Dependabot: pi minor and major releases (the
pi-compatlanes look at a new pi first, and moving the pin or the floor is a reviewed change with the whole suite's evidence; pi versions), and TypeScript majors. TypeScript 7 is not adopted: it has no stable compiler API forpackages/core/eval/harness.tsand ships notsserver. - The pi peer floor (
peerDependencies) moves only with a whole-suite run at the new floor. - Companions in
packages/core/sources.jsonchange only through a review of the candidate's tarball, recorded in itsreviewentry with the integrity pin (Evaluating a candidate). - A runtime dependency is added only together with the list at the top of this page
(
tests/clean-install-smoke.ts).
Lockfile integrity
npm run security:lockfile (packages/core/lockfile-check.ts, part of CI) fails when a package
in package-lock.json resolves from anywhere but https://registry.npmjs.org, lacks a sha512
integrity hash, or declares an install script that is not on its reviewed allowlist. CI installs
with --ignore-scripts, so even allowlisted scripts never run there.
Companion installs
install.ts installs each companion in packages/core/sources.json with pi install, which runs
npm install in pi's npm root (<agent dir>/npm, or <project>/.pi/npm for a project install).
Each entry names an exact version and the package's sha512 integrity; the companion's install
runs with npm_config_ignore_scripts=true, so no lifecycle script in its dependency tree runs,
unless the entry records a reviewed allowInstallScripts reason (none does). After each install
the installer compares the integrity npm recorded for the companion in that root's
package-lock.json with the pin; a difference removes the package again and fails the install.
tests/companion-integrity-smoke.ts pins each rule.
Not covered: the pin is the companion's own tarball, not its dependency tree, which npm resolves
at install time; a root with no lockfile entry for the companion is a warning, not a failure; and
pi update or a manual pi install bypasses these checks. pi-lens's @ast-grep/cli dependency
has an install step that is skipped as a result; its launcher script falls back without it and
prints a warning (seen in a static review of the package; no Luna test runs it).
pi versions
Luna supports @earendil-works/pi-coding-agent 0.85.1 and newer (its peerDependencies
floor) on Node 22.19 or newer, which is pi's own requirement. The dev dependency pins the version
the whole suite is tested against, 1.4.0. CI's pi-compat matrix runs the check suite at the
floor, 0.85.1, and at the last pi 0.x release, 0.99.2; both must pass. The lane installs
pi-coding-agent, pi-ai and pi-tui at its version over the pinned tree. All three are named
because npm would otherwise keep the pinned copy at the root or, when the pinned copy does not
satisfy the new pi's range, nest the new copy under pi and prune the root one, so a native import
from the repository root finds no package (tests/pi-host-peers-smoke.ts checks the install step
names every @earendil-works/* peer). Type checking and
lint run only against the pin, because they read pi's type declarations and older releases export
fewer type names; the extensions load as erased TypeScript, so the rest of the suite is what
establishes that an older pi works. npm run verify follows the same rule: when the installed pi
is not the pinned version, its type-check step prints SKIP: installed pi X is not the pinned Y
instead of running tsc, and when either version cannot be read it runs tsc as before
(tests/new-extension-smoke.ts, which runs verify on a fresh scaffold in each pi-compat lane).
When a pi
release newer than the pin is under review, it runs there as an advisory lane first: its failure
is the signal to review before the pin moves. Moving the pin or the floor is a reviewed change;
Dependabot does not bump pi minors or TypeScript majors.
The TypeScript compiler is pinned exactly at 6.0.3, the newest release typescript-eslint
supports (its peer range is >=4.8.4 <6.1.0). TypeScript 7 is not used. Its 7.0.2 package exports
only lib/version.cjs (a version string) at ., plus experimental ./unstable/* entry points: there
is no stable compiler API, so ts.transpileModule in packages/core/eval/harness.ts cannot run on it.
It also ships no tsserver, only tsc.
pi 1.x no longer publishes a shrinkwrap, so its own dependencies are hoisted beside it instead of
nested under it, and since 1.2 before_agent_start also fires for runs an extension starts with a
custom message; such an event carries no prompt, and Luna's handlers treat only a user prompt
as the operator's request. pi's extension documentation states that calls a tool makes through
ctx.executeTool(), as codemode and tool search do, go through the same tool_call and
tool_result handlers as model-issued calls; nothing in this repository tests nested calls yet.
One feature needs a newer pi than the floor and degrades without an error on older ones. The effort
wake-chain cap needs pi 1.2.0 or newer, the first release whose before_agent_start reports a
messageType; below it a workflow's completion message never starts a counted turn, so the cap
is never reached (tests/effort-standing-smoke.ts, at the pin). The progress-guard nudge reaches
the looping run on every supported pi: from 0.87.0 pi appends the entries a turn_end handler
returns, and below it the guard steers the same hidden message into the run
(tests/progress-guard-agsix-smoke.ts).
pi 0.99 changed its distribution (the runtime is bundled) and its tool-call and overflow internals. The suite's runtime pins were made to follow pi's own behaviour rather than its source layout, and the results at each version are recorded in the release notes for the beta.