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/llm-task/README.md

@@ -0,0 +1,98 @@
+# LLM Task (plugin)
+
+Adds an **optional** agent tool `llm-task` for running **JSON-only** LLM tasks
+(drafting, summarizing, classifying) with optional JSON Schema validation.
+
+Designed to be called from workflow engines (for example, Lobster via
+`openclaw.invoke --each`) without adding new OpenClaw code per workflow.
+
+## Enable
+
+1. Enable the plugin:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  }
+}
+```
+
+2. Allowlist the tool (it is registered with `optional: true`):
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "allow": ["llm-task"] }
+      }
+    ]
+  }
+}
+```
+
+## Config (optional)
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": {
+        "enabled": true,
+        "config": {
+          "defaultProvider": "openai",
+          "defaultModel": "gpt-5.5",
+          "defaultAuthProfileId": "main",
+          "allowedModels": ["openai/gpt-5.5"],
+          "maxTokens": 800,
+          "timeoutMs": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+`allowedModels` is an allowlist of `provider/model` strings. If set, any request
+outside the list is rejected.
+
+## Tool API
+
+### Parameters
+
+- `prompt` (string, required)
+- `input` (any, optional)
+- `schema` (object, optional JSON Schema)
+- `provider` (string, optional)
+- `model` (string, optional)
+- `thinking` (string, optional)
+- `authProfileId` (string, optional)
+- `temperature` (number, optional)
+- `maxTokens` (number, optional)
+- `timeoutMs` (number, optional)
+
+### Output
+
+Returns `details.json` containing the parsed JSON (and validates against
+`schema` when provided).
+
+## Notes
+
+- The tool is **JSON-only** and instructs the model to output only JSON
+  (no code fences, no commentary).
+- No tools are exposed to the model for this run.
+- Side effects should be handled outside this tool (for example, approvals in
+  Lobster) before calling tools that send messages/emails.
+
+## Bundled extension note
+
+This extension depends on OpenClaw internal modules (the embedded agent runner).
+It is intended to ship as a **bundled** OpenClaw extension (like `lobster`) and
+be enabled via `plugins.entries` + tool allowlists.
+
+It is **not** currently designed to be copied into
+`~/.openclaw/extensions` as a standalone plugin directory.

extensions/llm-task/api.ts

@@ -0,0 +1,7 @@
+// Llm Task API module exposes the plugin public contract.
+export { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "./src/runtime-api.js";
+export {
+  definePluginEntry,
+  type AnyAgentTool,
+  type OpenClawPluginApi,
+} from "openclaw/plugin-sdk/plugin-entry";

extensions/llm-task/index.ts

@@ -0,0 +1,34 @@
+// Llm Task plugin entrypoint registers its OpenClaw integration.
+import { optionalPositiveIntegerSchema } from "openclaw/plugin-sdk/channel-actions";
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { Type } from "typebox";
+import type { AnyAgentTool } from "./api.js";
+import { createLlmTaskTool, llmTaskToolDefinition } from "./src/llm-task-tool.js";
+
+export default defineToolPlugin({
+  id: "llm-task",
+  name: "LLM Task",
+  description: "Generic JSON-only LLM tool for structured tasks callable from workflows.",
+  configSchema: Type.Object(
+    {
+      defaultProvider: Type.Optional(Type.String()),
+      defaultModel: Type.Optional(Type.String()),
+      defaultAuthProfileId: Type.Optional(Type.String()),
+      allowedModels: Type.Optional(
+        Type.Array(Type.String(), {
+          description: "Allowlist of provider/model keys like openai/gpt-5.5.",
+        }),
+      ),
+      maxTokens: optionalPositiveIntegerSchema(),
+      timeoutMs: optionalPositiveIntegerSchema(),
+    },
+    { additionalProperties: false },
+  ),
+  tools: (tool) => [
+    tool({
+      ...llmTaskToolDefinition,
+      optional: true,
+      factory: ({ api }) => createLlmTaskTool(api) as unknown as AnyAgentTool,
+    }),
+  ],
+});

extensions/llm-task/openclaw.plugin.json

@@ -0,0 +1,49 @@
+{
+  "id": "llm-task",
+  "activation": {
+    "onStartup": true
+  },
+  "name": "LLM Task",
+  "description": "Generic JSON-only LLM tool for structured tasks callable from workflows.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "defaultProvider": {
+        "type": "string"
+      },
+      "defaultModel": {
+        "type": "string"
+      },
+      "defaultAuthProfileId": {
+        "type": "string"
+      },
+      "allowedModels": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Allowlist of provider/model keys like openai/gpt-5.2."
+      },
+      "maxTokens": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 1
+      }
+    },
+    "additionalProperties": false
+  },
+  "version": "2026.5.21",
+  "contracts": {
+    "tools": [
+      "llm-task"
+    ]
+  },
+  "toolMetadata": {
+    "llm-task": {
+      "optional": true
+    }
+  }
+}

extensions/llm-task/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@openclaw/llm-task",
+  "version": "2026.6.11",
+  "private": true,
+  "description": "OpenClaw JSON-only LLM task plugin",
+  "type": "module",
+  "dependencies": {
+    "typebox": "1.3.3"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/llm-task/src/llm-task-tool.test.ts

@@ -0,0 +1,346 @@
+// Llm Task tests cover llm task tool plugin behavior.
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../api.js", async () => {
+  const actual = await vi.importActual<typeof import("../api.js")>("../api.js");
+  return {
+    ...actual,
+    resolvePreferredOpenClawTmpDir: () => "/tmp",
+  };
+});
+
+afterAll(() => {
+  vi.doUnmock("../api.js");
+  vi.resetModules();
+});
+
+import { createLlmTaskTool } from "./llm-task-tool.js";
+
+const runEmbeddedAgent = vi.fn(async () => ({
+  meta: { startedAt: Date.now() },
+  payloads: [{ text: "{}" }],
+}));
+
+const resolveThinkingPolicy = vi.fn(() => ({
+  levels: [
+    { id: "off", label: "off" },
+    { id: "minimal", label: "minimal" },
+    { id: "low", label: "low" },
+    { id: "medium", label: "medium" },
+    { id: "high", label: "high" },
+  ],
+}));
+
+const normalizeThinkingLevel = vi.fn((raw?: string | null) => {
+  const value = raw?.trim().toLowerCase();
+  if (!value) {
+    return undefined;
+  }
+  if (value === "on") {
+    return "low";
+  }
+  if (["off", "minimal", "low", "medium", "high", "xhigh", "adaptive", "max"].includes(value)) {
+    return value;
+  }
+  return undefined;
+});
+
+function fakeApi(overrides: any = {}) {
+  return {
+    id: "llm-task",
+    name: "llm-task",
+    source: "test",
+    config: {
+      agents: { defaults: { workspace: "/tmp", model: { primary: "openai/gpt-5.5" } } },
+    },
+    pluginConfig: {},
+    runtime: {
+      version: "test",
+      agent: {
+        defaults: { provider: "openai", model: "gpt-5.5" },
+        runEmbeddedAgent,
+        resolveThinkingPolicy,
+        normalizeThinkingLevel,
+      },
+    },
+    logger: { debug() {}, info() {}, warn() {}, error() {} },
+    registerTool() {},
+    ...overrides,
+  };
+}
+
+function mockEmbeddedRunJson(payload: unknown) {
+  (runEmbeddedAgent as any).mockResolvedValueOnce({
+    meta: {},
+    payloads: [{ text: JSON.stringify(payload) }],
+  });
+}
+
+function resetRunnerMocks() {
+  runEmbeddedAgent.mockReset();
+  runEmbeddedAgent.mockImplementation(async () => ({
+    meta: { startedAt: Date.now() },
+    payloads: [{ text: "{}" }],
+  }));
+  resolveThinkingPolicy.mockClear();
+  normalizeThinkingLevel.mockClear();
+}
+
+async function executeEmbeddedRun(input: Record<string, unknown>) {
+  const tool = createLlmTaskTool(fakeApi());
+  await tool.execute("id", input);
+  return (runEmbeddedAgent as any).mock.calls[0]?.[0];
+}
+
+describe("llm-task tool (json-only)", () => {
+  beforeEach(() => {
+    resetRunnerMocks();
+  });
+
+  it("returns parsed json", async () => {
+    (runEmbeddedAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: "bar" }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi());
+    const res = await tool.execute("id", { prompt: "return foo" });
+    expect((res as any).details.json).toEqual({ foo: "bar" });
+  });
+
+  it("strips fenced json", async () => {
+    (runEmbeddedAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: '```json\n{"ok":true}\n```' }],
+    });
+    const tool = createLlmTaskTool(fakeApi());
+    const res = await tool.execute("id", { prompt: "return ok" });
+    expect((res as any).details.json).toEqual({ ok: true });
+  });
+
+  it("validates schema", async () => {
+    (runEmbeddedAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: "bar" }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi());
+    const schema = {
+      type: "object",
+      properties: { foo: { type: "string" } },
+      required: ["foo"],
+      additionalProperties: false,
+    };
+    const res = await tool.execute("id", { prompt: "return foo", schema });
+    expect((res as any).details.json).toEqual({ foo: "bar" });
+  });
+
+  it("validates caller schemas with repeated $id independently across calls", async () => {
+    const tool = createLlmTaskTool(fakeApi());
+    (runEmbeddedAgent as any)
+      .mockResolvedValueOnce({
+        meta: {},
+        payloads: [{ text: JSON.stringify({ foo: "bar" }) }],
+      })
+      .mockResolvedValueOnce({
+        meta: {},
+        payloads: [{ text: JSON.stringify({ count: 1 }) }],
+      });
+
+    await expect(
+      tool.execute("id", {
+        prompt: "return foo",
+        schema: {
+          $id: "https://example.test/llm-task-result",
+          type: "object",
+          properties: { foo: { type: "string" } },
+          required: ["foo"],
+          additionalProperties: false,
+        },
+      }),
+    ).resolves.toEqual({
+      content: [{ type: "text", text: '{\n  "foo": "bar"\n}' }],
+      details: { json: { foo: "bar" }, provider: "openai", model: "gpt-5.5" },
+    });
+
+    await expect(
+      tool.execute("id", {
+        prompt: "return count",
+        schema: {
+          $id: "https://example.test/llm-task-result",
+          type: "object",
+          properties: { count: { type: "number" } },
+          required: ["count"],
+          additionalProperties: false,
+        },
+      }),
+    ).resolves.toEqual({
+      content: [{ type: "text", text: '{\n  "count": 1\n}' }],
+      details: { json: { count: 1 }, provider: "openai", model: "gpt-5.5" },
+    });
+  });
+
+  it("throws on invalid json", async () => {
+    (runEmbeddedAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: "not-json" }],
+    });
+    const tool = createLlmTaskTool(fakeApi());
+    await expect(tool.execute("id", { prompt: "x" })).rejects.toThrow(/invalid json/i);
+  });
+
+  it("throws on schema mismatch", async () => {
+    (runEmbeddedAgent as any).mockResolvedValueOnce({
+      meta: {},
+      payloads: [{ text: JSON.stringify({ foo: 1 }) }],
+    });
+    const tool = createLlmTaskTool(fakeApi());
+    const schema = { type: "object", properties: { foo: { type: "string" } }, required: ["foo"] };
+    await expect(tool.execute("id", { prompt: "x", schema })).rejects.toThrow(/match schema/i);
+  });
+
+  it("passes provider/model overrides to embedded runner", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({
+      prompt: "x",
+      provider: "anthropic",
+      model: "claude-4-sonnet",
+    });
+    expect(call.provider).toBe("anthropic");
+    expect(call.model).toBe("claude-4-sonnet");
+  });
+
+  it("accepts model overrides that already include the selected provider prefix", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({
+      prompt: "x",
+      provider: "anthropic",
+      model: "anthropic/claude-4-sonnet",
+    });
+    expect(call.provider).toBe("anthropic");
+    expect(call.model).toBe("claude-4-sonnet");
+  });
+
+  it("resolves configured model aliases before dispatching the embedded run", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const tool = createLlmTaskTool(
+      fakeApi({
+        config: {
+          agents: {
+            defaults: {
+              workspace: "/tmp",
+              model: { primary: "anthropic/claude-sonnet-4-6" },
+              models: {
+                "google/gemini-3-flash-preview": { alias: "gemini-flash" },
+              },
+            },
+          },
+        },
+      }),
+    );
+
+    await tool.execute("id", { prompt: "x", model: "gemini-flash" });
+
+    const call = (runEmbeddedAgent as any).mock.calls[0]?.[0];
+    expect(call.provider).toBe("google");
+    expect(call.model).toBe("gemini-3-flash-preview");
+  });
+
+  it("passes thinking override to embedded runner", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({ prompt: "x", thinking: "high" });
+    expect(call.thinkLevel).toBe("high");
+    expect(resolveThinkingPolicy).toHaveBeenCalledWith({
+      provider: "openai",
+      model: "gpt-5.5",
+    });
+  });
+
+  it("normalizes thinking aliases", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({ prompt: "x", thinking: "on" });
+    expect(call.thinkLevel).toBe("low");
+  });
+
+  it("throws on invalid thinking level", async () => {
+    const tool = createLlmTaskTool(fakeApi());
+    await expect(tool.execute("id", { prompt: "x", thinking: "banana" })).rejects.toThrow(
+      /invalid thinking level/i,
+    );
+    expect(runEmbeddedAgent).not.toHaveBeenCalled();
+  });
+
+  it("throws on unsupported xhigh thinking level", async () => {
+    const tool = createLlmTaskTool(fakeApi());
+    await expect(tool.execute("id", { prompt: "x", thinking: "xhigh" })).rejects.toThrow(
+      /not supported/i,
+    );
+  });
+
+  it("does not pass thinkLevel when thinking is omitted", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({ prompt: "x" });
+    expect(call.thinkLevel).toBeUndefined();
+  });
+
+  it("enforces allowedModels", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const tool = createLlmTaskTool(
+      fakeApi({ pluginConfig: { allowedModels: ["openai/gpt-5.5"] } }),
+    );
+    await expect(
+      tool.execute("id", { prompt: "x", provider: "anthropic", model: "claude-4-sonnet" }),
+    ).rejects.toThrow(/not allowed/i);
+  });
+
+  it("disables tools for embedded run", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({ prompt: "x" });
+    expect(call.disableTools).toBe(true);
+  });
+
+  it("rejects malformed numeric run options before dispatch", async () => {
+    const tool = createLlmTaskTool(fakeApi());
+
+    await expect(tool.execute("id", { prompt: "x", temperature: Number.NaN })).rejects.toThrow(
+      "temperature must be a finite number",
+    );
+    await expect(tool.execute("id", { prompt: "x", maxTokens: 0 })).rejects.toThrow(
+      "maxTokens must be a positive integer",
+    );
+    await expect(tool.execute("id", { prompt: "x", timeoutMs: "4096.5" })).rejects.toThrow(
+      "timeoutMs must be a positive integer",
+    );
+    expect(runEmbeddedAgent).not.toHaveBeenCalled();
+  });
+
+  it("passes valid numeric run options before dispatch", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({
+      prompt: "x",
+      temperature: 0.2,
+      maxTokens: 512,
+      timeoutMs: 10_000,
+    });
+
+    expect(call.timeoutMs).toBe(10_000);
+    expect(call.streamParams).toEqual({
+      temperature: 0.2,
+      maxTokens: 512,
+    });
+  });
+
+  it("normalizes numeric string run options before dispatch", async () => {
+    mockEmbeddedRunJson({ ok: true });
+    const call = await executeEmbeddedRun({
+      prompt: "x",
+      temperature: "0.2",
+      maxTokens: "512",
+      timeoutMs: "10000",
+    });
+
+    expect(call.timeoutMs).toBe(10_000);
+    expect(call.streamParams).toEqual({
+      temperature: 0.2,
+      maxTokens: 512,
+    });
+  });
+});

extensions/llm-task/src/llm-task-tool.ts

@@ -0,0 +1,325 @@
+// Llm Task plugin module implements llm task tool behavior.
+import path from "node:path";
+import { buildModelAliasIndex, resolveModelRefFromString } from "openclaw/plugin-sdk/agent-runtime";
+import {
+  optionalFiniteNumberSchema,
+  optionalPositiveIntegerSchema,
+} from "openclaw/plugin-sdk/channel-actions";
+import {
+  type JsonSchemaObject,
+  validateJsonSchemaValue,
+} from "openclaw/plugin-sdk/json-schema-runtime";
+import { readFiniteNumberParam, readPositiveIntegerParam } from "openclaw/plugin-sdk/param-readers";
+import {
+  asPositiveSafeInteger,
+  normalizeOptionalString,
+} from "openclaw/plugin-sdk/string-coerce-runtime";
+import { Type } from "typebox";
+import { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "../api.js";
+import type { OpenClawPluginApi } from "../api.js";
+
+function stripCodeFences(s: string): string {
+  const trimmed = s.trim();
+  const m = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (m) {
+    return (m[1] ?? "").trim();
+  }
+  return trimmed;
+}
+
+function collectText(payloads: Array<{ text?: string; isError?: boolean }> | undefined): string {
+  const texts = (payloads ?? [])
+    .filter((p) => !p.isError && typeof p.text === "string")
+    .map((p) => p.text ?? "");
+  return texts.join("\n").trim();
+}
+
+function toModelKey(provider?: string, model?: string): string | undefined {
+  const p = provider?.trim();
+  const m = model?.trim();
+  if (!p || !m) {
+    return undefined;
+  }
+  return `${p}/${m}`;
+}
+
+function stripDuplicateProviderPrefix(provider: string | undefined, model: string | undefined) {
+  const p = provider?.trim();
+  const m = model?.trim();
+  if (!p || !m) {
+    return m || undefined;
+  }
+  const prefix = `${p}/`;
+  return m.startsWith(prefix) ? m.slice(prefix.length) : m;
+}
+
+function resolveLlmTaskModelRef(params: {
+  api: OpenClawPluginApi;
+  provider?: string;
+  rawModel?: string;
+}): { provider?: string; model?: string } {
+  const defaultProvider =
+    normalizeOptionalString(params.provider) ??
+    normalizeOptionalString(params.api.runtime.agent.defaults.provider);
+  const rawModel = normalizeOptionalString(params.rawModel);
+  if (!rawModel || !defaultProvider) {
+    return {
+      provider: params.provider,
+      model: stripDuplicateProviderPrefix(params.provider, rawModel),
+    };
+  }
+
+  const cfg = params.api.config;
+  const aliasIndex = cfg
+    ? buildModelAliasIndex({
+        cfg,
+        defaultProvider,
+      })
+    : undefined;
+  const resolved = resolveModelRefFromString({
+    cfg,
+    raw: rawModel,
+    defaultProvider,
+    aliasIndex,
+  });
+  if (!resolved) {
+    return {
+      provider: params.provider,
+      model: stripDuplicateProviderPrefix(params.provider, rawModel),
+    };
+  }
+  return resolved.ref;
+}
+
+type PluginCfg = {
+  defaultProvider?: string;
+  defaultModel?: string;
+  defaultAuthProfileId?: string;
+  allowedModels?: string[];
+  maxTokens?: number;
+  timeoutMs?: number;
+};
+
+type LlmTaskParams = {
+  prompt?: unknown;
+  input?: unknown;
+  schema?: unknown;
+  provider?: unknown;
+  model?: unknown;
+  thinking?: unknown;
+  authProfileId?: unknown;
+  temperature?: unknown;
+  maxTokens?: unknown;
+  timeoutMs?: unknown;
+};
+
+type ThinkingPolicy = ReturnType<OpenClawPluginApi["runtime"]["agent"]["resolveThinkingPolicy"]>;
+
+export const llmTaskToolDefinition = {
+  name: "llm-task",
+  label: "LLM Task",
+  description:
+    "Run a generic JSON-only LLM task and return schema-validated JSON. Designed for orchestration from Lobster workflows via openclaw.invoke.",
+  parameters: Type.Object({
+    prompt: Type.String({ description: "Task instruction for the LLM." }),
+    input: Type.Optional(Type.Unknown({ description: "Optional input payload for the task." })),
+    schema: Type.Optional(
+      Type.Unknown({ description: "Optional JSON Schema to validate the returned JSON." }),
+    ),
+    provider: Type.Optional(
+      Type.String({ description: "Provider override (e.g. openai, anthropic)." }),
+    ),
+    model: Type.Optional(Type.String({ description: "Model id override." })),
+    thinking: Type.Optional(Type.String({ description: "Thinking level override." })),
+    authProfileId: Type.Optional(Type.String({ description: "Auth profile override." })),
+    temperature: optionalFiniteNumberSchema({ description: "Best-effort temperature override." }),
+    maxTokens: optionalPositiveIntegerSchema({
+      description: "Best-effort maxTokens override.",
+    }),
+    timeoutMs: optionalPositiveIntegerSchema({ description: "Timeout for the LLM run." }),
+  }),
+};
+
+function formatThinkingPolicy(policy: ThinkingPolicy): string {
+  return policy.levels.map((level) => level.label).join(", ");
+}
+
+function supportsThinkingPolicyLevel(
+  policy: ThinkingPolicy,
+  level: ReturnType<OpenClawPluginApi["runtime"]["agent"]["normalizeThinkingLevel"]>,
+): boolean {
+  return Boolean(level) && policy.levels.some((entry) => entry.id === level);
+}
+
+export function createLlmTaskTool(api: OpenClawPluginApi) {
+  return {
+    ...llmTaskToolDefinition,
+
+    async execute(_id: string, params: LlmTaskParams) {
+      const prompt = typeof params.prompt === "string" ? params.prompt : "";
+      if (!prompt.trim()) {
+        throw new Error("prompt required");
+      }
+
+      const pluginCfg = (api.pluginConfig ?? {}) as PluginCfg;
+
+      const defaultsModel = api.config?.agents?.defaults?.model;
+      const primary =
+        typeof defaultsModel === "string"
+          ? normalizeOptionalString(defaultsModel)
+          : normalizeOptionalString(defaultsModel?.primary);
+      const primaryProvider = typeof primary === "string" ? primary.split("/")[0] : undefined;
+      const primaryModel =
+        typeof primary === "string" ? primary.split("/").slice(1).join("/") : undefined;
+
+      const requestedProvider =
+        (typeof params.provider === "string" && params.provider.trim()) ||
+        (typeof pluginCfg.defaultProvider === "string" && pluginCfg.defaultProvider.trim()) ||
+        primaryProvider ||
+        undefined;
+
+      const rawModel =
+        (typeof params.model === "string" && params.model.trim()) ||
+        (typeof pluginCfg.defaultModel === "string" && pluginCfg.defaultModel.trim()) ||
+        primaryModel ||
+        undefined;
+      const { provider: resolvedProvider, model } = resolveLlmTaskModelRef({
+        api,
+        provider: requestedProvider,
+        rawModel,
+      });
+      const provider = resolvedProvider;
+
+      const authProfileId =
+        (typeof params.authProfileId === "string" && params.authProfileId.trim()) ||
+        (typeof pluginCfg.defaultAuthProfileId === "string" &&
+          pluginCfg.defaultAuthProfileId.trim()) ||
+        undefined;
+
+      const modelKey = toModelKey(provider, model);
+      if (!provider || !model || !modelKey) {
+        throw new Error(
+          `provider/model could not be resolved (provider=${provider ?? ""}, model=${model ?? ""})`,
+        );
+      }
+
+      const allowed = Array.isArray(pluginCfg.allowedModels) ? pluginCfg.allowedModels : undefined;
+      if (allowed && allowed.length > 0 && !allowed.includes(modelKey)) {
+        throw new Error(
+          `Model not allowed by llm-task plugin config: ${modelKey}. Allowed models: ${allowed.join(", ")}`,
+        );
+      }
+
+      const thinkingRaw =
+        typeof params.thinking === "string" && params.thinking.trim() ? params.thinking : undefined;
+      let thinkLevel: ReturnType<OpenClawPluginApi["runtime"]["agent"]["normalizeThinkingLevel"]> =
+        undefined;
+      if (thinkingRaw) {
+        const thinkingPolicy = api.runtime.agent.resolveThinkingPolicy({ provider, model });
+        const thinkingLevelsHint = formatThinkingPolicy(thinkingPolicy);
+        thinkLevel = api.runtime.agent.normalizeThinkingLevel(thinkingRaw);
+        if (!thinkLevel) {
+          throw new Error(
+            `Invalid thinking level "${thinkingRaw}". Use one of: ${thinkingLevelsHint}.`,
+          );
+        }
+        if (!supportsThinkingPolicyLevel(thinkingPolicy, thinkLevel)) {
+          throw new Error(
+            `Thinking level "${thinkLevel}" is not supported for ${provider}/${model}. Use one of: ${thinkingLevelsHint}.`,
+          );
+        }
+      }
+
+      const timeoutMs =
+        readPositiveIntegerParam(params as Record<string, unknown>, "timeoutMs") ??
+        asPositiveSafeInteger(pluginCfg.timeoutMs) ??
+        30_000;
+
+      const streamParams = {
+        temperature: readFiniteNumberParam(params as Record<string, unknown>, "temperature"),
+        maxTokens:
+          readPositiveIntegerParam(params as Record<string, unknown>, "maxTokens") ??
+          asPositiveSafeInteger(pluginCfg.maxTokens),
+      };
+
+      const input = params.input;
+      let inputJson: string;
+      try {
+        inputJson = JSON.stringify(input ?? null, null, 2);
+      } catch {
+        throw new Error("input must be JSON-serializable");
+      }
+
+      const system = [
+        "You are a JSON-only function.",
+        "Return ONLY a valid JSON value.",
+        "Do not wrap in markdown fences.",
+        "Do not include commentary.",
+        "Do not call tools.",
+      ].join(" ");
+
+      const fullPrompt = `${system}\n\nTASK:\n${prompt}\n\nINPUT_JSON:\n${inputJson}\n`;
+
+      return await withTempWorkspace(
+        { rootDir: resolvePreferredOpenClawTmpDir(), prefix: "openclaw-llm-task-" },
+        async ({ dir: tmpDir }) => {
+          const sessionId = `llm-task-${Date.now()}`;
+          const sessionFile = path.join(tmpDir, "session.json");
+
+          const result = await api.runtime.agent.runEmbeddedAgent({
+            sessionId,
+            sessionFile,
+            workspaceDir: api.config?.agents?.defaults?.workspace ?? process.cwd(),
+            config: api.config,
+            prompt: fullPrompt,
+            timeoutMs,
+            runId: `llm-task-${Date.now()}`,
+            provider,
+            model,
+            authProfileId,
+            authProfileIdSource: authProfileId ? "user" : "auto",
+            thinkLevel,
+            streamParams,
+            disableTools: true,
+          });
+
+          const text = collectText(
+            typeof result === "object" && result !== null && "payloads" in result
+              ? (result as { payloads?: Array<{ text?: string; isError?: boolean }> }).payloads
+              : undefined,
+          );
+          if (!text) {
+            throw new Error("LLM returned empty output");
+          }
+
+          const raw = stripCodeFences(text);
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(raw);
+          } catch {
+            throw new Error("LLM returned invalid JSON");
+          }
+
+          const schema = params.schema;
+          if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+            const validation = validateJsonSchemaValue({
+              schema: schema as JsonSchemaObject,
+              cacheKey: "llm-task.result",
+              value: parsed,
+              cache: false,
+            });
+            if (!validation.ok) {
+              const msg = validation.errors.map((error) => error.text).join("; ") || "invalid";
+              throw new Error(`LLM JSON did not match schema: ${msg}`);
+            }
+          }
+
+          return {
+            content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
+            details: { json: parsed, provider, model },
+          };
+        },
+      );
+    },
+  };
+}

extensions/llm-task/src/runtime-api.ts

@@ -0,0 +1,2 @@
+// Llm Task API module exposes the plugin public contract.
+export { resolvePreferredOpenClawTmpDir, withTempWorkspace } from "openclaw/plugin-sdk/temp-path";

extensions/llm-task/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"
+  ]
+}