Add bundled optional llm-task tool (JSON-only) for workflows

Summary

This PR adds a new bundled Clawdbot extension llm-task that registers an optional agent tool named llm-task.

The tool provides a generic, composable JSON-only LLM capability intended for orchestration engines (notably Lobster workflows via clawd.invoke) so users can build new workflows without requiring new Clawdbot code per workflow.

Motivation

Lobster is a workflow/orchestration runtime. It can fetch/transform/approve/act, but it cannot “think” unless it can call back into an LLM capability.

We want a stable boundary where:

• Lobster pipelines remain composable and local-first
• Clawdbot owns model auth, provider selection, and policy
• New workflows can be created by composing pipeline primitives + a single generic “LLM task” primitive

What’s included

• New bundled extension at extensions/llm-task/
  • clawdbot.plugin.json manifest
  • index.ts registers the tool with { optional: true }
  • src/llm-task-tool.ts tool implementation
  • src/llm-task-tool.test.ts unit tests
  • README.md usage + configuration

Tool interface

Tool name: llm-task (optional tool; disabled by default)

Parameters

• prompt (string, required): instruction for the task
• input (any, optional): input payload for the task
• schema (object, optional): JSON Schema to validate returned JSON
• provider (string, optional)
• model (string, optional)
• authProfileId (string, optional)
• temperature (number, optional)
• maxTokens (number, optional)
• timeoutMs (number, optional)

Output

• Returns parsed JSON in details.json
• If schema is provided, validates output via Ajv and throws on mismatch.

Design decisions

JSON-only (no freeform)

The tool is intentionally JSON-only to be composable and validateable.

Bundled extension (like lobster)

llm-task uses the embedded agent runner (runEmbeddedPiAgent) which is a Clawdbot internal module.

Therefore this is intended to ship as a bundled extension (same model as Lobster) and be enabled via plugins.entries + tool allowlists.

Model selection

• Supports explicit provider + model override
• Defaults to agent config (agents.defaults.model.primary) unless overridden
• Supports plugin-config allowlist allowedModels (e.g. openai-codex/gpt-5.2)

Security / threat model

Primary threats

1. Prompt injection from untrusted content passed into input (emails/web/etc.)
2. Tool misuse: downstream workflows using model output to trigger side effects
3. Credential exfiltration: model asked to output secrets

Mitigations present in this PR

• JSON-only contract: tool prompts the model to output only JSON (no markdown/commentary). Output must parse as JSON.
• Schema validation (optional): workflows can enforce strict shape/type constraints; tool errors on mismatch.
• No side effects in llm-task: the tool only returns structured data.
• Allowlist/opt-in:
  • plugin must be enabled: plugins.entries.llm-task.enabled=true
  • tool must be allowlisted: agents.list[].tools.allow includes llm-task
• Model allowlist (optional): plugins.entries.llm-task.config.allowedModels to constrain where untrusted inputs can be sent.

Recommended workflow-level protections (caller responsibility)

• Insert approve checkpoints before any side-effecting step (email sending, posting, shell exec, etc.).
• Treat llm-task output as untrusted unless validated.
• Use strict schemas and conservative downstream logic.

Usage

Enable llm-task

{
  "plugins": {
    "entries": {
      "llm-task": {
        "enabled": true
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "allow": [
            "llm-task"
          ]
        }
      }
    ]
  }
}

Lobster → clawd.invoke → llm-task

clawd.invoke --tool llm-task --action json --args-json '{
  "prompt": "Given the input email, return an object with keys intent and draft.",
  "input": {
    "subject": "Hello",
    "body": "Can you help?"
  },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"],
    "additionalProperties": false
  }
}'

Security note (update)

• llm-task now runs the embedded agent in LLM-only mode (disableTools: true). No agent tools are registered for the run, so tool calls cannot trigger side effects. Includes unit tests.