Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/tokenjuice/README.md

@@ -0,0 +1,35 @@
+# @openclaw/tokenjuice
+
+Official Tokenjuice output compaction plugin for OpenClaw.
+
+Tokenjuice compacts noisy `exec` and `bash` tool results after commands run, before the result is fed back into the active agent session. It does not rewrite commands, rerun commands, or change exit codes.
+
+## Install
+
+```bash
+openclaw plugins install @openclaw/tokenjuice
+```
+
+Restart the Gateway after installing or updating the plugin.
+
+## Enable
+
+```bash
+openclaw config set plugins.entries.tokenjuice.enabled true
+```
+
+Equivalent:
+
+```bash
+openclaw plugins enable tokenjuice
+```
+
+## Docs
+
+- https://docs.openclaw.ai/tools/tokenjuice
+
+## Package
+
+- Plugin id: `tokenjuice`
+- Package: `@openclaw/tokenjuice`
+- Minimum OpenClaw host: `2026.5.28`

extensions/tokenjuice/index.test.ts

@@ -0,0 +1,225 @@
+// Tokenjuice tests cover index plugin behavior.
+import fs from "node:fs";
+import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { tokenjuiceFactory, createTokenjuiceOpenClawEmbeddedExtension } = vi.hoisted(() => {
+  const tokenjuiceFactoryLocal = vi.fn();
+  const createTokenjuiceOpenClawEmbeddedExtensionLocal = vi.fn(() => tokenjuiceFactoryLocal);
+  return {
+    tokenjuiceFactory: tokenjuiceFactoryLocal,
+    createTokenjuiceOpenClawEmbeddedExtension: createTokenjuiceOpenClawEmbeddedExtensionLocal,
+  };
+});
+
+vi.mock("./runtime-api.js", () => ({
+  createTokenjuiceOpenClawEmbeddedExtension,
+}));
+
+import plugin from "./index.js";
+import { createTokenjuiceAgentToolResultMiddleware } from "./tool-result-middleware.js";
+
+describe("tokenjuice plugin", () => {
+  beforeEach(() => {
+    createTokenjuiceOpenClawEmbeddedExtension.mockClear();
+    tokenjuiceFactory.mockClear();
+  });
+
+  it("is opt-in by default", () => {
+    const manifest = JSON.parse(
+      fs.readFileSync(new URL("./openclaw.plugin.json", import.meta.url), "utf8"),
+    ) as { enabledByDefault?: unknown };
+
+    expect(manifest.enabledByDefault).toBeUndefined();
+  });
+
+  it("registers tokenjuice tool result middleware for OpenClaw and Codex runtimes", () => {
+    const registerAgentToolResultMiddleware = vi.fn();
+
+    plugin.register(
+      createTestPluginApi({
+        id: "tokenjuice",
+        name: "tokenjuice",
+        source: "test",
+        config: {},
+        pluginConfig: {},
+        runtime: {} as never,
+        registerAgentToolResultMiddleware,
+      }),
+    );
+
+    expect(createTokenjuiceOpenClawEmbeddedExtension).toHaveBeenCalledTimes(1);
+    expect(tokenjuiceFactory).toHaveBeenCalledTimes(1);
+    const registration = registerAgentToolResultMiddleware.mock.calls[0];
+    expect(typeof registration?.[0]).toBe("function");
+    expect(registration?.[1]).toEqual({ runtimes: ["openclaw", "codex"] });
+  });
+
+  it("synthesises exec fields when bash provides metadata-only details (no status)", async () => {
+    let received:
+      | {
+          details: unknown;
+        }
+      | undefined;
+    tokenjuiceFactory.mockImplementationOnce(
+      (api: { on: (event: string, handler: unknown) => void }) => {
+        api.on("tool_result", async (event: typeof received) => {
+          received = event;
+        });
+      },
+    );
+
+    const middleware = createTokenjuiceAgentToolResultMiddleware();
+    await middleware(
+      {
+        toolCallId: "tool-call-tokenjuice-bash-meta",
+        toolName: "bash",
+        args: { command: "cat /tmp/out.txt", workdir: "/tmp/openclaw-tokenjuice-test" },
+        result: {
+          content: [{ type: "text", text: "file contents\n" }],
+          details: {
+            truncation: { reason: "max_bytes" },
+            fullOutputPath: "/tmp/out.txt",
+          },
+        },
+        isError: false,
+      },
+      { runtime: "openclaw" },
+    );
+
+    expect(received?.details).toMatchObject({
+      status: "completed",
+      aggregated: "file contents\n",
+      exitCode: 0,
+      truncation: { reason: "max_bytes" },
+      fullOutputPath: "/tmp/out.txt",
+    });
+  });
+
+  it("passes through bash details that already have a status field unchanged", async () => {
+    let received:
+      | {
+          details: unknown;
+        }
+      | undefined;
+    tokenjuiceFactory.mockImplementationOnce(
+      (api: { on: (event: string, handler: unknown) => void }) => {
+        api.on("tool_result", async (event: typeof received) => {
+          received = event;
+        });
+      },
+    );
+
+    const existingDetails = {
+      status: "completed",
+      aggregated: "pre-built output",
+      exitCode: 0,
+      cwd: "/existing/cwd",
+    };
+
+    const middleware = createTokenjuiceAgentToolResultMiddleware();
+    await middleware(
+      {
+        toolCallId: "tool-call-tokenjuice-bash-existing",
+        toolName: "bash",
+        args: { command: "echo hi", workdir: "/tmp" },
+        result: {
+          content: [{ type: "text", text: "hi\n" }],
+          details: existingDetails,
+        },
+        isError: false,
+      },
+      { runtime: "openclaw" },
+    );
+
+    expect(received?.details).toBe(existingDetails);
+  });
+
+  it.each([
+    ["exit code", { exitCode: 7 }, "failed", 7],
+    ["success flag", { success: false }, "failed", 1],
+    ["ok flag", { ok: false }, "failed", 1],
+    ["timeout flag", { timedOut: true }, "failed", 1],
+    ["error value", { error: "command failed" }, "failed", 1],
+    ["successful exit code", { exitCode: 0 }, "completed", 0],
+    ["successful flag", { success: true }, "completed", 0],
+  ])(
+    "adds a canonical status while preserving bash details with a %s",
+    async (_label, existingDetails, status, exitCode) => {
+      let received:
+        | {
+            details: unknown;
+          }
+        | undefined;
+      tokenjuiceFactory.mockImplementationOnce(
+        (api: { on: (event: string, handler: unknown) => void }) => {
+          api.on("tool_result", async (event: typeof received) => {
+            received = event;
+          });
+        },
+      );
+
+      const middleware = createTokenjuiceAgentToolResultMiddleware();
+      await middleware(
+        {
+          toolCallId: "tool-call-tokenjuice-bash-terminal",
+          toolName: "bash",
+          args: { command: "exit 7", workdir: "/tmp" },
+          result: {
+            content: [{ type: "text", text: "failed\n" }],
+            details: existingDetails,
+          },
+          isError: false,
+        },
+        { runtime: "openclaw" },
+      );
+
+      expect(received?.details).toMatchObject({
+        ...existingDetails,
+        status,
+        exitCode,
+      });
+    },
+  );
+
+  it("normalizes bash results without details before passing them to tokenjuice", async () => {
+    let received:
+      | {
+          toolName: string;
+          input: Record<string, unknown>;
+          content: unknown;
+          details: unknown;
+          isError?: boolean;
+        }
+      | undefined;
+    tokenjuiceFactory.mockImplementationOnce(
+      (api: { on: (event: string, handler: unknown) => void }) => {
+        api.on("tool_result", async (event: typeof received) => {
+          received = event;
+          return { content: [{ type: "text", text: "compacted" }] };
+        });
+      },
+    );
+
+    const middleware = createTokenjuiceAgentToolResultMiddleware();
+    const result = await middleware(
+      {
+        toolCallId: "tool-call-tokenjuice-bash",
+        toolName: "bash",
+        args: { command: "printf 'hello\\n'", workdir: "/tmp/openclaw-tokenjuice-test" },
+        result: { content: [{ type: "text", text: "hello\n" }], details: undefined },
+        isError: false,
+      },
+      { runtime: "openclaw" },
+    );
+
+    expect(received?.toolName).toBe("bash");
+    expect(received?.details).toMatchObject({
+      status: "completed",
+      aggregated: "hello\n",
+      exitCode: 0,
+    });
+    expect(received?.details).not.toHaveProperty("cwd");
+    expect(result?.result.content).toEqual([{ type: "text", text: "compacted" }]);
+  });
+});

extensions/tokenjuice/index.ts

@@ -0,0 +1,14 @@
+// Tokenjuice plugin entrypoint registers its OpenClaw integration.
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createTokenjuiceAgentToolResultMiddleware } from "./tool-result-middleware.js";
+
+export default definePluginEntry({
+  id: "tokenjuice",
+  name: "tokenjuice",
+  description: "Compacts exec and bash tool results with tokenjuice reducers.",
+  register(api) {
+    api.registerAgentToolResultMiddleware(createTokenjuiceAgentToolResultMiddleware(), {
+      runtimes: ["openclaw", "codex"],
+    });
+  },
+});

extensions/tokenjuice/manifest.test.ts

@@ -0,0 +1,31 @@
+// Tokenjuice tests cover manifest plugin behavior.
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+
+type TokenjuicePackageManifest = {
+  dependencies?: Record<string, string>;
+};
+
+type TokenjuicePluginManifest = {
+  contracts?: {
+    agentToolResultMiddleware?: string[];
+  };
+};
+
+describe("tokenjuice package manifest", () => {
+  it("keeps runtime dependencies in the package manifest", () => {
+    const packageJson = JSON.parse(
+      fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"),
+    ) as TokenjuicePackageManifest;
+
+    expect(packageJson.dependencies?.tokenjuice).toBe("0.8.1");
+  });
+
+  it("declares runtime-neutral tool result middleware ownership in the manifest contract", () => {
+    const manifest = JSON.parse(
+      fs.readFileSync(new URL("./openclaw.plugin.json", import.meta.url), "utf8"),
+    ) as TokenjuicePluginManifest;
+
+    expect(manifest.contracts?.agentToolResultMiddleware).toEqual(["openclaw", "codex"]);
+  });
+});

extensions/tokenjuice/npm-shrinkwrap.json

@@ -0,0 +1,39 @@
+{
+  "name": "@openclaw/tokenjuice",
+  "version": "2026.6.11",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@openclaw/tokenjuice",
+      "version": "2026.6.11",
+      "dependencies": {
+        "tokenjuice": "0.8.1"
+      },
+      "peerDependencies": {
+        "openclaw": ">=2026.6.11"
+      },
+      "peerDependenciesMeta": {
+        "openclaw": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/tokenjuice": {
+      "version": "0.8.1",
+      "resolved": "https://registry.npmjs.org/tokenjuice/-/tokenjuice-0.8.1.tgz",
+      "integrity": "sha512-/CnrgVI7zm7P4yphNe2Ypqm4vOwzdIob4ki9nRdT8P1NAOgsWGv0ciTDLly4cyAaKIhLd0H3swLNn2R5FCDpYw==",
+      "license": "MIT",
+      "bin": {
+        "tokenjuice": "dist/cli/main.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/vincentkoc"
+      }
+    }
+  }
+}

extensions/tokenjuice/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "tokenjuice",
+  "activation": {
+    "onStartup": false
+  },
+  "name": "tokenjuice",
+  "description": "Compacts exec and bash tool results with tokenjuice reducers.",
+  "contracts": {
+    "agentToolResultMiddleware": ["openclaw", "codex"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/tokenjuice/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@openclaw/tokenjuice",
+  "version": "2026.6.11",
+  "description": "OpenClaw tokenjuice exec output compaction plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "tokenjuice": "0.8.1"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.6.11"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*",
+    "openclaw": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/tokenjuice",
+      "npmSpec": "@openclaw/tokenjuice",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.5.28"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.11"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

extensions/tokenjuice/runtime-api.ts

@@ -0,0 +1,2 @@
+// Tokenjuice API module exposes the plugin public contract.
+export { createTokenjuiceOpenClawEmbeddedExtension } from "tokenjuice/openclaw";

extensions/tokenjuice/tool-result-middleware.ts

@@ -0,0 +1,154 @@
+// Tokenjuice plugin module implements tool result middleware behavior.
+import process from "node:process";
+import type {
+  AgentToolResultMiddleware,
+  AgentToolResultMiddlewareEvent,
+  OpenClawAgentToolResult,
+} from "openclaw/plugin-sdk/agent-harness";
+import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { createTokenjuiceOpenClawEmbeddedExtension } from "./runtime-api.js";
+
+type TokenjuiceToolResultHandler = (
+  event: {
+    toolName: string;
+    input: Record<string, unknown>;
+    content: OpenClawAgentToolResult["content"];
+    details: unknown;
+    isError?: boolean;
+  },
+  ctx: { cwd: string },
+) => Promise<Partial<OpenClawAgentToolResult> | void> | Partial<OpenClawAgentToolResult> | void;
+
+function readCwd(event: AgentToolResultMiddlewareEvent): string {
+  if (event.cwd?.trim()) {
+    return event.cwd;
+  }
+  const workdir = event.args.workdir;
+  if (typeof workdir === "string" && workdir.trim()) {
+    return workdir;
+  }
+  return process.cwd();
+}
+
+function readTextContent(content: OpenClawAgentToolResult["content"]): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .map((item) => {
+      if (typeof item === "string") {
+        return item;
+      }
+      if (item && typeof item === "object" && "text" in item && typeof item.text === "string") {
+        return item.text;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function readCommand(args: Record<string, unknown>): string {
+  const command = args.command;
+  return typeof command === "string" ? command : "";
+}
+
+function hasStatus(details: Record<string, unknown>): boolean {
+  const status = details.status;
+  return typeof status === "string" && status.trim() !== "";
+}
+
+function hasFailureState(
+  event: AgentToolResultMiddlewareEvent,
+  details: Record<string, unknown> | undefined,
+): boolean {
+  const exitCode = details?.exitCode;
+  return (
+    event.isError === true ||
+    details?.ok === false ||
+    details?.success === false ||
+    details?.timedOut === true ||
+    Boolean(details?.error) ||
+    (typeof exitCode === "number" && Number.isFinite(exitCode) && exitCode !== 0)
+  );
+}
+
+function normalizeDetails(
+  event: AgentToolResultMiddlewareEvent,
+  current: OpenClawAgentToolResult,
+): unknown {
+  const isExecLike = event.toolName === "exec" || event.toolName === "bash";
+  const details = isRecord(current.details) ? current.details : undefined;
+
+  if (!isExecLike || !readCommand(event.args)) {
+    return current.details;
+  }
+  // A concrete status is already canonical. Other terminal hints are preserved below
+  // while supplying only the completed/failed status Tokenjuice requires.
+  if (details && hasStatus(details)) {
+    return current.details;
+  }
+  const aggregated = readTextContent(current.content);
+  if (!aggregated.trim()) {
+    return current.details;
+  }
+  const failed = hasFailureState(event, details);
+  const existingExitCode = details?.exitCode;
+  const exitCode =
+    typeof existingExitCode === "number" && Number.isFinite(existingExitCode)
+      ? existingExitCode
+      : failed
+        ? 1
+        : 0;
+  const synthesized = {
+    status: failed ? "failed" : "completed",
+    aggregated,
+    exitCode,
+  };
+  if (!details) {
+    return synthesized;
+  }
+  return {
+    ...synthesized,
+    ...details,
+    status: synthesized.status,
+    exitCode: synthesized.exitCode,
+  };
+}
+
+export function createTokenjuiceAgentToolResultMiddleware(): AgentToolResultMiddleware {
+  const handlers: TokenjuiceToolResultHandler[] = [];
+  createTokenjuiceOpenClawEmbeddedExtension()({
+    on(event, handler) {
+      if (event === "tool_result") {
+        handlers.push(handler as TokenjuiceToolResultHandler);
+      }
+    },
+  });
+
+  return async (event) => {
+    let current = event.result;
+    for (const handler of handlers) {
+      const next = await handler(
+        {
+          toolName: event.toolName,
+          input: event.args,
+          content: current.content,
+          details: normalizeDetails(event, current),
+          isError: event.isError,
+        },
+        { cwd: readCwd(event) },
+      );
+      if (next) {
+        current = Object.assign({}, current, {
+          content: next.content ?? current.content,
+          details: next.details ?? current.details,
+        });
+      }
+    }
+    return current === event.result ? undefined : { result: current };
+  };
+}

extensions/tokenjuice/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}