ocsmarttools 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to `ocsmarttools` are documented here.
+
+## [0.1.2] - 2026-02-22
+
+### Added
+- Lightweight metrics tracking for tool invocations: success/failure/timeout, latency, shaped-result rate, and approximate token savings.
+- Chat and CLI stats commands (`/ocsmarttools stats`, `/ocsmarttools stats reset`, `openclaw ocsmarttools stats`, `openclaw ocsmarttools stats reset`).
+
+### Changed
+- `tool_search` now tries live gateway registry endpoints first and falls back to policy/static catalog automatically.
+- Added `toolSearch.useLiveRegistry` and `toolSearch.liveTimeoutMs` config options.
+
+## [0.1.1] - 2026-02-22
+
+### Added
+- `version` commands in chat and CLI (`/ocsmarttools version`, `openclaw ocsmarttools version`).
+- Version control scripts in `package.json` (`version:show`, `version:bump:*`, `release:check`).
+- `CHANGELOG.md` for release notes tracking.
+
+### Changed
+- `setup` default mode now aligns with zero-touch defaults (`standard`).
+
+### Fixed
+- Blocked `tool_dispatch` from dispatching internal orchestration tools (`tool_dispatch`, `tool_batch`) to avoid nested orchestration loops.
+
+## [0.1.0] - 2026-02-22
+
+### Added
+- Provider-agnostic tool orchestration tools: `tool_search`, `tool_dispatch`, `tool_batch`, `tool_result_get`.
+- Zero-touch auto-bootstrap on plugin start.
+- Chat and CLI setup/status/mode/config commands.
+- Help commands in chat and CLI.
+- Adaptive large-result shaping with handle-based retrieval.

package/README.md

@@ -0,0 +1,169 @@
+# OCSmartTools for OpenClaw
+
+Provider-agnostic tool orchestration for lower latency and lower token cost.
+
+`ocsmarttools` is designed to work immediately after install, with safe defaults and minimal setup.
+
+## What It Adds
+
+- `tool_search`: finds relevant tools quickly
+- `tool_dispatch`: runs one tool call through normal OpenClaw policy checks
+- `tool_batch`: runs bounded multi-step workflows (`call` + `foreach`)
+- `tool_result_get`: retrieves large stored outputs by handle
+
+## Why It Helps
+
+```mermaid
+flowchart LR
+  A["Traditional"] --> B["Model -> tool -> model -> tool"] --> C["More turns + repeated context"]
+  D["ocsmarttools"] --> E["Batch + shaped results"] --> F["Fewer turns + smaller context"]
+  C --> G["Higher cost/latency"]
+  F --> H["Lower cost/latency"]
+```
+
+## Install
+
+### npm
+
+```bash
+openclaw plugins install ocsmarttools --pin
+openclaw plugins enable ocsmarttools
+openclaw gateway restart
+```
+
+### Local folder
+
+```bash
+openclaw plugins install /absolute/path/to/OpenClaw-SmartToolCalls
+openclaw plugins enable ocsmarttools
+openclaw gateway restart
+```
+
+## Quick Start
+
+1. Install + enable + restart.
+2. Done. The plugin auto-bootstraps and starts working in background.
+3. Optional check:
+
+```text
+/ocsmarttools status
+```
+
+Model note:
+- No model setup is required in this plugin.
+- It automatically uses the model OpenClaw is already using.
+
+## Commands
+
+### Chat Commands
+
+| Command | What it does |
+|---|---|
+| `/ocsmarttools version` | Shows installed plugin version |
+| `/ocsmarttools help` | Shows simple help and examples |
+| `/ocsmarttools status` | Shows current mode, limits, and safety flags |
+| `/ocsmarttools stats` | Shows live usage metrics (success/failure/timeout, latency, shaping, savings) |
+| `/ocsmarttools stats reset` | Resets the stats window |
+| `/ocsmarttools setup [safe\|standard]` | Applies recommended defaults for the selected mode |
+| `/ocsmarttools mode <safe\|standard>` | Changes mode only |
+| `/ocsmarttools config` | Shows effective plugin config |
+| `/ocsmarttools config keys` | Lists editable config keys |
+| `/ocsmarttools config set <key> <value>` | Updates one config key with validation |
+| `/ocsmarttools config reset [key]` | Resets one key (or all keys) to defaults |
+
+### CLI Commands
+
+| Command | What it does |
+|---|---|
+| `openclaw ocsmarttools version` | Shows installed plugin version |
+| `openclaw ocsmarttools help` | Shows simple help and examples |
+| `openclaw ocsmarttools status` | Shows current mode, limits, and safety flags |
+| `openclaw ocsmarttools stats` | Shows live usage metrics (success/failure/timeout, latency, shaping, savings) |
+| `openclaw ocsmarttools stats reset` | Resets the stats window |
+| `openclaw ocsmarttools setup [safe\|standard]` | Applies recommended defaults for the selected mode |
+| `openclaw ocsmarttools mode <safe\|standard>` | Changes mode only |
+| `openclaw ocsmarttools config` | Shows effective plugin config |
+| `openclaw ocsmarttools config keys` | Lists editable config keys |
+| `openclaw ocsmarttools config set <key> <value>` | Updates one config key with validation |
+| `openclaw ocsmarttools config reset [key]` | Resets one key (or all keys) to defaults |
+
+## Common Config Actions
+
+```text
+/ocsmarttools config
+/ocsmarttools config keys
+/ocsmarttools config set maxResultChars 120000
+/ocsmarttools config set storeLargeResults true
+/ocsmarttools config set toolSearch.useLiveRegistry true
+/ocsmarttools config set toolSearch.liveTimeoutMs 1500
+/ocsmarttools config reset maxResultChars
+/ocsmarttools stats
+```
+
+Config path:
+- `plugins.entries.ocsmarttools.config`
+
+## Modes
+
+- `standard` (default): zero-touch mode, no sandbox requirement, control-plane dispatch still blocked
+- `safe`: requires sandboxed execution and blocks control-plane dispatch (`gateway`, `cron`)
+
+Setup default:
+- `/ocsmarttools setup` and `openclaw ocsmarttools setup` default to `standard`.
+
+## Recommended Defaults
+
+For mixed daily usage (research + writing + coding):
+
+- `maxResultChars`: `120000`
+- `storeLargeResults`: `true`
+- `resultStoreTtlSec`: `3600`
+- `resultSampleItems`: `10`
+
+Example:
+
+```text
+/ocsmarttools config set maxResultChars 120000
+/ocsmarttools config set resultStoreTtlSec 3600
+/ocsmarttools config set resultSampleItems 10
+```
+
+## Strict Policy Note
+
+If your instance uses strict `tools.allow`, include:
+
+```json5
+{
+  tools: {
+    allow: ["tool_search", "tool_dispatch", "tool_batch", "tool_result_get"]
+  }
+}
+```
+
+## Safety and Limits
+
+- `ocsmarttools` does not bypass OpenClaw tool policy.
+- `tool_batch` is intentionally bounded (`maxSteps`, `maxForEach`).
+- Large-result handles are in-memory and expire by TTL.
+- `tool_result_get` works only while handle is still valid.
+- `tool_search` tries live registry endpoints first, then automatically falls back to policy/static catalog.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+```
+
+## Versioning
+
+```bash
+npm run version:show
+npm run version:bump:patch
+npm run version:bump:minor
+npm run version:bump:major
+npm run release:check
+```
+
+- Version source of truth: `package.json`.
+- Release notes: `CHANGELOG.md`.

package/openclaw.plugin.json

@@ -0,0 +1,48 @@
+{
+  "id": "ocsmarttools",
+  "name": "OCSmartTools",
+  "description": "Provider-agnostic advanced tool orchestration with adaptive large-result handling and zero-touch startup.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "mode": { "type": "string", "enum": ["safe", "standard"] },
+      "maxSteps": { "type": "integer", "minimum": 1, "maximum": 200 },
+      "maxForEach": { "type": "integer", "minimum": 1, "maximum": 200 },
+      "maxResultChars": { "type": "integer", "minimum": 500, "maximum": 500000 },
+      "invokeTimeoutMs": { "type": "integer", "minimum": 0, "maximum": 1800000 },
+      "storeLargeResults": { "type": "boolean" },
+      "resultStoreTtlSec": { "type": "integer", "minimum": 60, "maximum": 86400 },
+      "resultSampleItems": { "type": "integer", "minimum": 1, "maximum": 50 },
+      "requireSandbox": { "type": "boolean" },
+      "denyControlPlane": { "type": "boolean" },
+      "toolSearch": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "defaultLimit": { "type": "integer", "minimum": 1, "maximum": 50 },
+          "useLiveRegistry": { "type": "boolean" },
+          "liveTimeoutMs": { "type": "integer", "minimum": 250, "maximum": 10000 }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "mode": { "label": "Mode" },
+    "maxSteps": { "label": "Max Steps", "advanced": true },
+    "maxForEach": { "label": "Max ForEach", "advanced": true },
+    "maxResultChars": { "label": "Max Result Chars", "advanced": true },
+    "invokeTimeoutMs": { "label": "Invoke Timeout (ms)", "advanced": true },
+    "storeLargeResults": { "label": "Store Large Results", "advanced": true },
+    "resultStoreTtlSec": { "label": "Result Store TTL (sec)", "advanced": true },
+    "resultSampleItems": { "label": "Result Sample Items", "advanced": true },
+    "requireSandbox": { "label": "Require Sandbox", "advanced": true },
+    "denyControlPlane": { "label": "Deny Control Plane", "advanced": true },
+    "toolSearch.enabled": { "label": "Enable Tool Search" },
+    "toolSearch.defaultLimit": { "label": "Tool Search Default Limit", "advanced": true },
+    "toolSearch.useLiveRegistry": { "label": "Use Live Tool Registry", "advanced": true },
+    "toolSearch.liveTimeoutMs": { "label": "Live Tool Registry Timeout (ms)", "advanced": true }
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ocsmarttools",
+  "version": "0.1.2",
+  "description": "Provider-agnostic advanced tool orchestration plugin for OpenClaw with search, dispatch, and batching",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "release:check": "npm run typecheck && npm pack --dry-run",
+    "version:show": "node -p \"require('./package.json').version\"",
+    "version:bump:patch": "npm version patch --no-git-tag-version",
+    "version:bump:minor": "npm version minor --no-git-tag-version",
+    "version:bump:major": "npm version major --no-git-tag-version"
+  },
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "tools",
+    "agent"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "openclaw": ">=2026.2.21"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@types/node": "^22.10.0"
+  }
+}

package/src/commands/chat.ts

@@ -0,0 +1,123 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  applySetup,
+  canEditConfigKey,
+  normalizeConfigKey,
+  renderConfig,
+  renderConfigKeys,
+  renderHelp,
+  renderStatus,
+  renderStats,
+  renderVersion,
+  resetStats,
+  resetConfig,
+  setConfigKey,
+  updateMode,
+} from "./operations.js";
+import type { AdvToolsMode } from "../lib/plugin-config.js";
+import type { MetricsStore } from "../lib/metrics-store.js";
+
+function parseMode(value: string | undefined): AdvToolsMode | null {
+  if (value === "safe" || value === "standard") {
+    return value;
+  }
+  return null;
+}
+
+export function registerChatCommands(api: OpenClawPluginApi, metrics: MetricsStore): void {
+  api.registerCommand({
+    name: "ocsmarttools",
+    description: "OCSmartTools setup/status helper.",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const args = (ctx.args ?? "").trim();
+      if (!args) {
+        return { text: renderHelp() };
+      }
+
+      const parts = args.split(/\s+/);
+      const cmd = parts[0]?.toLowerCase();
+
+      try {
+        if (cmd === "status") {
+          return { text: renderStatus(api) };
+        }
+
+        if (cmd === "version") {
+          return { text: renderVersion(api) };
+        }
+
+        if (cmd === "help") {
+          return { text: renderHelp() };
+        }
+
+        if (cmd === "stats") {
+          const action = (parts[1] ?? "").toLowerCase();
+          if (action === "reset") {
+            return { text: resetStats(metrics) };
+          }
+          return { text: renderStats(metrics) };
+        }
+
+        if (cmd === "setup") {
+          const mode = parseMode(parts[1]) ?? "standard";
+          return { text: await applySetup(api, mode) };
+        }
+
+        if (cmd === "mode") {
+          const mode = parseMode(parts[1]);
+          if (!mode) {
+            return { text: "Usage: /ocsmarttools mode <safe|standard>" };
+          }
+          return { text: await updateMode(api, mode) };
+        }
+
+        if (cmd === "config") {
+          const action = (parts[1] ?? "get").toLowerCase();
+          if (action === "get") {
+            return { text: renderConfig(api) };
+          }
+          if (action === "keys") {
+            return { text: renderConfigKeys() };
+          }
+          if (action === "set") {
+            const key = normalizeConfigKey(parts[2] ?? "");
+            const valueRaw = parts.slice(3).join(" ").trim();
+            if (!key || !valueRaw) {
+              return { text: "Usage: /ocsmarttools config set <key> <value>" };
+            }
+            if (!canEditConfigKey(key)) {
+              return { text: `Unknown key: ${key}. Use \`/ocsmarttools config keys\`.` };
+            }
+            return { text: await setConfigKey(api, key, valueRaw) };
+          }
+          if (action === "reset") {
+            const key = normalizeConfigKey(parts[2] ?? "");
+            if (key && !canEditConfigKey(key)) {
+              return { text: `Unknown key: ${key}. Use \`/ocsmarttools config keys\`.` };
+            }
+            return { text: await resetConfig(api, key || undefined) };
+          }
+          return {
+            text: [
+              "Usage:",
+              "/ocsmarttools config",
+              "/ocsmarttools config get",
+              "/ocsmarttools config keys",
+              "/ocsmarttools config set <key> <value>",
+              "/ocsmarttools config reset [key]",
+            ].join("\n"),
+          };
+        }
+
+        return {
+          text: "Unknown subcommand. Use `/ocsmarttools help`.",
+        };
+      } catch (error) {
+        return {
+          text: `ocsmarttools error: ${error instanceof Error ? error.message : String(error)}`,
+        };
+      }
+    },
+  });
+}

package/src/commands/cli.ts

@@ -0,0 +1,130 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  applySetup,
+  renderConfig,
+  renderConfigKeys,
+  renderHelp,
+  renderStatus,
+  renderStats,
+  renderVersion,
+  resetStats,
+  resetConfig,
+  setConfigKey,
+  updateMode,
+} from "./operations.js";
+import type { AdvToolsMode } from "../lib/plugin-config.js";
+import type { MetricsStore } from "../lib/metrics-store.js";
+
+function parseMode(value: string | undefined): AdvToolsMode | null {
+  if (value === "safe" || value === "standard") {
+    return value;
+  }
+  return null;
+}
+
+export function registerCliCommands(api: OpenClawPluginApi, metrics: MetricsStore): void {
+  api.registerCli(
+    ({ program }) => {
+      const adv = program.command("ocsmarttools").description("OCSmartTools plugin commands");
+      adv.addHelpCommand(false);
+
+      adv
+        .command("help")
+        .description("Show simple command guide")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderHelp());
+        });
+
+      adv
+        .command("version")
+        .description("Show installed plugin version")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderVersion(api));
+        });
+
+      adv
+        .command("status")
+        .description("Show plugin status")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderStatus(api));
+        });
+
+      adv
+        .command("stats")
+        .description("Show usage/savings metrics")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderStats(metrics));
+        });
+
+      adv
+        .command("stats reset")
+        .description("Reset usage/savings metrics window")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(resetStats(metrics));
+        });
+
+      adv
+        .command("setup [mode]")
+        .description("Apply recommended setup (default mode: standard)")
+        .action(async (modeRaw?: string) => {
+          const mode = parseMode(modeRaw) ?? "standard";
+          const text = await applySetup(api, mode);
+          // eslint-disable-next-line no-console
+          console.log(text);
+        });
+
+      adv
+        .command("mode <mode>")
+        .description("Set plugin mode")
+        .action(async (modeRaw: string) => {
+          const mode = parseMode(modeRaw);
+          if (!mode) {
+            throw new Error("mode must be one of: safe, standard");
+          }
+          const text = await updateMode(api, mode);
+          // eslint-disable-next-line no-console
+          console.log(text);
+        });
+
+      adv
+        .command("config")
+        .description("Show effective plugin config")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderConfig(api));
+        });
+
+      adv
+        .command("config keys")
+        .description("List editable plugin config keys")
+        .action(() => {
+          // eslint-disable-next-line no-console
+          console.log(renderConfigKeys());
+        });
+
+      adv
+        .command("config set <key> <value>")
+        .description("Set one plugin config key")
+        .action(async (key: string, value: string) => {
+          const text = await setConfigKey(api, key, value);
+          // eslint-disable-next-line no-console
+          console.log(text);
+        });
+
+      adv
+        .command("config reset [key]")
+        .description("Reset all plugin config to defaults or reset one key")
+        .action(async (key?: string) => {
+          const text = await resetConfig(api, key);
+          // eslint-disable-next-line no-console
+          console.log(text);
+        });
+    },
+    { commands: ["ocsmarttools"] },
+  );
+}