feat(tokenjuice): bundle the native adapter

[vincentkoc]

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: OpenClaw had the new embedded-extension seam, but no bundled tokenjuice plugin. The earlier "install tokenjuice as an OpenClaw plugin" route was the wrong UX and the wrong packaging boundary.
• Why it matters: users should enable a bundled tokenjuice plugin, not install a second OpenClaw plugin package, and the bundled extension should import tokenjuice like any other third-party runtime dependency.
• What changed: kept the new registerEmbeddedExtensionFactory(...) seam, added a bundled extensions/tokenjuice plugin that imports tokenjuice/openclaw through a local runtime boundary, and added labeler/lockfile/test coverage for that bundled plugin.
• What did NOT change (scope boundary): no docs/config followup in this PR beyond the SDK seam docs already on the branch, and no sync tool_result_persist fallback.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related feat(openclaw): export the embedded adapter vincentkoc/tokenjuice#25
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: N/A
• Missing detection / guardrail: N/A
• Contributing context (if known): N/A

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/pi-embedded-runner.extensions.test.ts, extensions/tokenjuice/index.test.ts, extensions/tokenjuice/manifest.test.ts
• Scenario the test should lock in: OpenClaw exposes the embedded factory seam, the bundled tokenjuice plugin registers through it, and the bundled package metadata stays wired for staged runtime dependencies.
• Why this is the smallest reliable guardrail: it covers the new core seam plus the new bundled plugin boundary without needing a full gateway boot in CI.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

• OpenClaw now ships a bundled tokenjuice plugin that can be enabled instead of installed as a separate plugin package.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before:
[user installs tokenjuice package] -> [tries to install it again as an OpenClaw plugin] -> [blocked / wrong boundary]

After:
[OpenClaw ships bundled tokenjuice plugin] -> [user enables plugin]
  -> [bundled plugin imports tokenjuice/openclaw]
  -> [embedded runner invokes tokenjuice factory]
  -> [exec tool results are compacted]

Security Impact (required)

• New permissions/capabilities? (Yes/No): Yes
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): Yes
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation:
  • This adds a bundled plugin-owned compaction path for already-trusted OpenClaw plugins. The core seam stays generic and the tokenjuice runtime import lives in a narrow bundled extension package.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 + pnpm
• Model/provider: openai / gpt-5.4
• Integration/channel (if any): OpenClaw plugin loader + Pi embedded runner
• Relevant config (redacted): temporary smoke config with plugins.entries.tokenjuice.enabled=true

Steps

1. Build the tokenjuice worktree so its tokenjuice/openclaw export exists in dist.
2. Symlink that tokenjuice worktree into extensions/tokenjuice/node_modules/tokenjuice so the bundled plugin resolves the new export through a normal package import path.
3. Load only the bundled tokenjuice plugin, build embedded extension factories, and invoke the tool_result handler with a git status exec result.

Expected

• The bundled tokenjuice plugin loads, registers one embedded extension factory, and rewrites the exec result.

Actual

• That is what happened; the live smoke returned compacted git status output plus tokenjuice metadata.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: pnpm test:serial extensions/tokenjuice/index.test.ts extensions/tokenjuice/manifest.test.ts src/agents/pi-embedded-runner.extensions.test.ts; real bundled-plugin smoke through loadOpenClawPlugins(...) + buildEmbeddedExtensionFactories(...) using the tokenjuice worktree through a normal package import path.
• Edge cases checked: opt-in manifest default; staged runtime dependency manifest; loader registration of the bundled factory; actual compacted tool_result output.
• What you did not verify: pnpm check:changed still fails on unrelated existing typecheck issues in src/docs/clawhub-plugin-docs.test.ts, src/gateway/reconnect-gating.test.ts, src/i18n/registry.test.ts, src/ui-app-settings.agents-files-refresh.test.ts, extensions/qa-lab/web/src/main.ts, and extensions/qqbot/src/bridge/setup/finalize.ts.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: the current published tokenjuice@0.6.0 does not expose tokenjuice/openclaw yet.
  • Mitigation: the bundled plugin depends on tokenjuice@^0.6.0, so once the tokenjuice release from feat(openclaw): export the embedded adapter vincentkoc/tokenjuice#25 lands, bundled runtime dependency staging can resolve the new export without another architecture change.

AI Assistance

• AI-assisted in description
• Testing: fully tested

[aisle-research-bot]

🔒 Aisle Security Analysis

We found 1 potential security issue(s) in this PR:

#	Severity	Title
1	🟠 High	Arbitrary code execution via untrusted npm_execpath in runtime deps installer

1. 🟠 Arbitrary code execution via untrusted npm_execpath in runtime deps installer

Property	Value
Severity	High
CWE	CWE-78
Location	src/plugins/bundled-runtime-deps.ts:457-475

Description

resolveBundledRuntimeDepsNpmRunner trusts the npm_execpath environment variable if it looks like an npm-cli.js path. An attacker who can influence the environment passed into installBundledRuntimeDeps can point npm_execpath at an arbitrary absolute JS file named npm-cli.js (or .../npm/bin/npm-cli.js). The code then executes it with Node (execPath), resulting in arbitrary code execution.

Key points:

• Input: env.npm_execpath is taken from the caller-provided environment.
• Weak validation: isNpmCliPath() only checks the path suffix; it does not restrict to the Node installation directory.
• Sink: returned runner uses command: execPath and args: [npmCliPath, ...], executing the attacker-controlled script.
• createBundledRuntimeDepsInstallEnv does not remove npm_execpath, so the variable propagates into the installer environment.

Vulnerable code:

const rawNpmExecPath = ... ? env.npm_execpath : undefined;
const npmExecPath = rawNpmExecPath && isNpmCliPath(rawNpmExecPath) ? rawNpmExecPath : undefined;
...
const npmCliPath = npmCliCandidates.find((candidate) => pathImpl.isAbsolute(candidate) && existsSync(candidate));
if (npmCliPath) {
  return { command: execPath, args: [npmCliPath, ...params.npmArgs] };
}

Recommendation

Do not trust npm_execpath from the ambient environment for security-sensitive execution.

Recommended fixes (pick one):

1. Ignore npm_execpath entirely and only use vetted locations relative to process.execPath (Node’s install dir):

const npmCliCandidates = [
  pathImpl.resolve(nodeDir, "../lib/node_modules/npm/bin/npm-cli.js"),
  pathImpl.resolve(nodeDir, "node_modules/npm/bin/npm-cli.js"),
];

2. If you must allow npm_execpath, require it to be inside the resolved Node directory (or a known safe npm installation root) after realpath resolution:

import fs from "node:fs";
const real = fs.realpathSync(rawNpmExecPath);
const realNodeDir = fs.realpathSync(nodeDir);
if (!real.startsWith(realNodeDir + pathImpl.sep)) throw new Error("Untrusted npm_execpath");

Additionally, consider sanitizing the installer env:

• Remove npm_execpath from createNestedNpmInstallEnv / createBundledRuntimeDepsInstallEnv.
• Optionally strip other npm control variables (e.g., npm_config_userconfig) if they can affect execution in your threat model.

---

Analyzed PR: #69946 at commit bc8623d

_{Last updated on: 2026-04-22T07:06:17Z}

[greptile-apps]

Greptile Summary

This PR adds a public api.registerEmbeddedExtensionFactory(...) seam to the OpenClaw plugin SDK, allowing external plugins to register Pi embedded-runner extension factories without any core special-casing. The implementation follows the established compactionProviders/agentHarnesses registry pattern end-to-end: new embedded-extension-factory.ts module, full cache snapshot/restore coverage in loader.ts, noop fallback in api-builder.ts, and a focused seam test.

Confidence Score: 5/5

Safe to merge; implementation is consistent with existing plugin registry patterns and all cache paths are covered.

All findings are P2: one style suggestion about awaiting the factory call in the test (harmless since the current factory is synchronous), and a minor temp-directory cleanup omission. No logic errors, no data integrity issues, and no security concerns beyond what the existing plugin trust model already handles.

src/agents/pi-embedded-runner.extensions.test.ts — minor test hygiene (void factory call and missing tmpdir cleanup).

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/agents/pi-embedded-runner.extensions.test.ts
Line: 98-103

Comment:
**Unawaited async factory call may cause flaky assertions**

The factory result is discarded with `void`, so if any future `ExtensionFactory` is async (returns a `Promise<void>` instead of `void`), `handlers.set` won't be called before the `expect` on line 103. The test would silently pass with an empty `handlers` map since the factory type allows async. Awaiting the call makes the test robust now and safe for async factories later.

```suggestion
    await cachedFactories[0]?.({
      on(event: string, handler: Function) {
        handlers.set(event, handler);
      },
    } as never);
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/agents/pi-embedded-runner.extensions.test.ts
Line: 48

Comment:
**Temp directory not cleaned up after test**

`fs.mkdtempSync` creates a directory in the OS temp folder that is never removed. Other plugin seam tests in this codebase typically call `fs.rmSync(tmp, { recursive: true, force: true })` inside `afterEach`. This isn't a correctness issue, but it accumulates test artifacts on developer machines.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat(plugins): register embedded extensi..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c11473c734

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0d477d7385

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2a6c8b4350

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 601e8ef865

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0e903dd9c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b05d48607

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d5a72de4d6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Avoid npm installs inside source-checkout plugin roots

Restricting the missing-dependency check to installRoot here means source-checkout plugins now fall through to npm install in the plugin directory whenever <plugin>/node_modules is absent. For extensions/tokenjuice (and other workspace packages), that nested npm install fails with EUNSUPPORTEDPROTOCOL because the manifest contains workspace:* dev dependencies, so enabling the plugin can fail before it registers. This needs a source-checkout-safe install target (or a source-checkout bypass) instead of invoking npm in the workspace package root.

Useful? React with 👍 / 👎.