ocsmarttools 0.1.2

package/src/commands/operations.ts

@@ -0,0 +1,370 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  DEFAULT_SETTINGS,
+  deepCloneConfig,
+  ensurePluginEntry,
+  mergeUniqueStrings,
+  resolveSettings,
+  type AdvToolsMode,
+  writeConfig,
+} from "../lib/plugin-config.js";
+import type { MetricsStore } from "../lib/metrics-store.js";
+
+const ADVTOOLS_TOOL_NAMES = ["tool_search", "tool_dispatch", "tool_batch", "tool_result_get"];
+type ConfigKind = "boolean" | "integer" | "enum";
+type ConfigSpec =
+  | { kind: "boolean" }
+  | { kind: "integer"; min: number; max: number }
+  | { kind: "enum"; values: string[] };
+
+const CONFIG_SPECS: Record<string, ConfigSpec> = {
+  enabled: { kind: "boolean" },
+  mode: { kind: "enum", values: ["safe", "standard"] },
+  maxSteps: { kind: "integer", min: 1, max: 200 },
+  maxForEach: { kind: "integer", min: 1, max: 200 },
+  maxResultChars: { kind: "integer", min: 500, max: 500000 },
+  invokeTimeoutMs: { kind: "integer", min: 0, max: 1800000 },
+  storeLargeResults: { kind: "boolean" },
+  resultStoreTtlSec: { kind: "integer", min: 60, max: 86400 },
+  resultSampleItems: { kind: "integer", min: 1, max: 50 },
+  requireSandbox: { kind: "boolean" },
+  denyControlPlane: { kind: "boolean" },
+  "toolSearch.enabled": { kind: "boolean" },
+  "toolSearch.defaultLimit": { kind: "integer", min: 1, max: 50 },
+  "toolSearch.useLiveRegistry": { kind: "boolean" },
+  "toolSearch.liveTimeoutMs": { kind: "integer", min: 250, max: 10000 },
+};
+
+const DEFAULT_BY_KEY: Record<string, boolean | number | string> = {
+  enabled: DEFAULT_SETTINGS.enabled,
+  mode: DEFAULT_SETTINGS.mode,
+  maxSteps: DEFAULT_SETTINGS.maxSteps,
+  maxForEach: DEFAULT_SETTINGS.maxForEach,
+  maxResultChars: DEFAULT_SETTINGS.maxResultChars,
+  invokeTimeoutMs: DEFAULT_SETTINGS.invokeTimeoutMs,
+  storeLargeResults: DEFAULT_SETTINGS.storeLargeResults,
+  resultStoreTtlSec: DEFAULT_SETTINGS.resultStoreTtlSec,
+  resultSampleItems: DEFAULT_SETTINGS.resultSampleItems,
+  requireSandbox: DEFAULT_SETTINGS.requireSandbox,
+  denyControlPlane: DEFAULT_SETTINGS.denyControlPlane,
+  "toolSearch.enabled": DEFAULT_SETTINGS.toolSearch.enabled,
+  "toolSearch.defaultLimit": DEFAULT_SETTINGS.toolSearch.defaultLimit,
+  "toolSearch.useLiveRegistry": DEFAULT_SETTINGS.toolSearch.useLiveRegistry,
+  "toolSearch.liveTimeoutMs": DEFAULT_SETTINGS.toolSearch.liveTimeoutMs,
+};
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function parseBoolean(valueRaw: string): boolean | null {
+  const value = valueRaw.trim().toLowerCase();
+  if (["true", "1", "yes", "on"].includes(value)) {
+    return true;
+  }
+  if (["false", "0", "no", "off"].includes(value)) {
+    return false;
+  }
+  return null;
+}
+
+function parseConfigValue(key: string, valueRaw: string): { ok: true; value: unknown } | { ok: false; error: string } {
+  const spec = CONFIG_SPECS[key];
+  if (!spec) {
+    return { ok: false, error: `Unknown key: ${key}` };
+  }
+
+  if (spec.kind === "boolean") {
+    const parsed = parseBoolean(valueRaw);
+    if (parsed === null) {
+      return { ok: false, error: `Invalid boolean for ${key}: ${valueRaw}` };
+    }
+    return { ok: true, value: parsed };
+  }
+
+  if (spec.kind === "enum") {
+    if (!spec.values.includes(valueRaw)) {
+      return { ok: false, error: `${key} must be one of: ${spec.values.join(", ")}` };
+    }
+    return { ok: true, value: valueRaw };
+  }
+
+  const parsed = Number(valueRaw);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    return { ok: false, error: `Invalid integer for ${key}: ${valueRaw}` };
+  }
+  if (parsed < spec.min || parsed > spec.max) {
+    return {
+      ok: false,
+      error: `${key} must be between ${spec.min} and ${spec.max}`,
+    };
+  }
+  return { ok: true, value: parsed };
+}
+
+function setValueAtPath(root: Record<string, unknown>, key: string, value: unknown): void {
+  const path = key.split(".");
+  if (path.length === 1) {
+    root[path[0] as string] = value;
+    return;
+  }
+
+  let cursor = root;
+  for (let i = 0; i < path.length - 1; i += 1) {
+    const part = path[i] as string;
+    cursor[part] = asObj(cursor[part]);
+    cursor = cursor[part] as Record<string, unknown>;
+  }
+  cursor[path[path.length - 1] as string] = value;
+}
+
+function sortedKeys(): string[] {
+  return Object.keys(CONFIG_SPECS).sort((a, b) => a.localeCompare(b));
+}
+
+export function renderStatus(api: OpenClawPluginApi): string {
+  const loaded = api.runtime.config.loadConfig();
+  const s = resolveSettings(api, loaded);
+  const cfg = loaded as Record<string, unknown>;
+
+  const tools = asObj(cfg.tools);
+  const allow = Array.isArray(tools.allow)
+    ? tools.allow.filter((v): v is string => typeof v === "string")
+    : [];
+
+  const allowlistedTools = ADVTOOLS_TOOL_NAMES.filter((name) => allow.includes(name));
+
+  return [
+    "OCSmartTools Status",
+    `- plugin: ${api.id}`,
+    `- mode: ${s.mode}`,
+    `- tool_search enabled: ${s.toolSearch.enabled}`,
+    `- maxSteps: ${s.maxSteps}`,
+    `- maxForEach: ${s.maxForEach}`,
+    `- invokeTimeoutMs: ${s.invokeTimeoutMs}`,
+    `- storeLargeResults: ${s.storeLargeResults}`,
+    `- resultStoreTtlSec: ${s.resultStoreTtlSec}`,
+    `- resultSampleItems: ${s.resultSampleItems}`,
+    `- requireSandbox: ${s.requireSandbox}`,
+    `- denyControlPlane: ${s.denyControlPlane}`,
+    `- tools allowlisted (if strict policy): ${allowlistedTools.length ? allowlistedTools.join(", ") : "none"}`,
+  ].join("\n");
+}
+
+export function renderHelp(): string {
+  return [
+    "OCSmartTools Help",
+    "",
+    "Chat commands:",
+    "- /ocsmarttools version: Show installed plugin version",
+    "- /ocsmarttools help: Show this help text",
+    "- /ocsmarttools status: Show current plugin status and safety flags",
+    "- /ocsmarttools stats: Show usage/savings metrics (success/failure/timeout/latency/shaping)",
+    "- /ocsmarttools stats reset: Reset metrics window",
+    "- /ocsmarttools setup [safe|standard]: Apply recommended defaults (default: standard)",
+    "- /ocsmarttools mode <safe|standard>: Switch only the operating mode",
+    "- /ocsmarttools config: Show effective plugin config",
+    "- /ocsmarttools config keys: List editable config keys",
+    "- /ocsmarttools config set <key> <value>: Update one config key",
+    "- /ocsmarttools config reset [key]: Reset one key (or all keys) to defaults",
+    "",
+    "Examples:",
+    "- /ocsmarttools config set maxResultChars 120000",
+    "- /ocsmarttools config set storeLargeResults true",
+    "- /ocsmarttools config reset maxResultChars",
+  ].join("\n");
+}
+
+export function renderVersion(api: OpenClawPluginApi): string {
+  return `ocsmarttools version: ${api.version ?? "unknown"}`;
+}
+
+function formatPct(value: number): string {
+  return `${(Math.max(0, Math.min(1, value)) * 100).toFixed(1)}%`;
+}
+
+export function renderStats(metrics: MetricsStore): string {
+  const s = metrics.snapshot();
+  const topTools =
+    s.topTools.length > 0
+      ? s.topTools
+          .map(
+            (t) =>
+              `  - ${t.tool}: ${t.calls} calls (${t.success} ok, ${t.failure} fail, ${t.timeout} timeout, ${t.shaped} shaped)`,
+          )
+          .join("\n")
+      : "  - none";
+
+  return [
+    "OCSmartTools Stats",
+    `- windowStart: ${s.startedAt}`,
+    `- totalCalls: ${s.totalCalls}`,
+    `- success/failure/timeout: ${s.success}/${s.failure}/${s.timeout}`,
+    `- successRate: ${formatPct(s.successRate)}`,
+    `- timeoutRate: ${formatPct(s.timeoutRate)}`,
+    `- avgLatencyMs: ${s.avgLatencyMs.toFixed(1)}`,
+    `- p95LatencyApproxMs: ${s.p95LatencyApproxMs}`,
+    `- shapedResults: ${s.shapedResults}`,
+    `- shapedRateOnSuccess: ${formatPct(s.shapedRateOnSuccess)}`,
+    `- charsSaved: ${s.charsSaved.toLocaleString()}`,
+    `- charReductionRate: ${formatPct(s.charReductionRate)}`,
+    `- estimatedTokensSaved(approx chars/4): ${s.estimatedTokensSaved.toLocaleString()}`,
+    "- topTools:",
+    topTools,
+  ].join("\n");
+}
+
+export function resetStats(metrics: MetricsStore): string {
+  metrics.reset();
+  return "OCSmartTools stats reset.";
+}
+
+export function renderConfig(api: OpenClawPluginApi): string {
+  const loaded = api.runtime.config.loadConfig();
+  const s = resolveSettings(api, loaded);
+
+  return [
+    "OCSmartTools Config",
+    `- enabled: ${s.enabled}`,
+    `- mode: ${s.mode}`,
+    `- maxSteps: ${s.maxSteps}`,
+    `- maxForEach: ${s.maxForEach}`,
+    `- maxResultChars: ${s.maxResultChars}`,
+    `- invokeTimeoutMs: ${s.invokeTimeoutMs}`,
+    `- storeLargeResults: ${s.storeLargeResults}`,
+    `- resultStoreTtlSec: ${s.resultStoreTtlSec}`,
+    `- resultSampleItems: ${s.resultSampleItems}`,
+    `- requireSandbox: ${s.requireSandbox}`,
+    `- denyControlPlane: ${s.denyControlPlane}`,
+    `- toolSearch.enabled: ${s.toolSearch.enabled}`,
+    `- toolSearch.defaultLimit: ${s.toolSearch.defaultLimit}`,
+    `- toolSearch.useLiveRegistry: ${s.toolSearch.useLiveRegistry}`,
+    `- toolSearch.liveTimeoutMs: ${s.toolSearch.liveTimeoutMs}`,
+    "",
+    "Use `/ocsmarttools config keys` to see editable keys.",
+  ].join("\n");
+}
+
+export function renderConfigKeys(): string {
+  return [
+    "OCSmartTools Config Keys",
+    ...sortedKeys().map((key) => `- ${key}`),
+  ].join("\n");
+}
+
+export async function setConfigKey(
+  api: OpenClawPluginApi,
+  key: string,
+  valueRaw: string,
+): Promise<string> {
+  const parsed = parseConfigValue(key, valueRaw);
+  if (!parsed.ok) {
+    return parsed.error;
+  }
+
+  const next = deepCloneConfig(api.runtime.config.loadConfig());
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  entryObj.enabled = true;
+  const pluginCfg = asObj(entryObj.config);
+  entryObj.config = pluginCfg;
+
+  setValueAtPath(pluginCfg, key, parsed.value);
+  await writeConfig(api, next);
+
+  return `Config updated: ${key}=${JSON.stringify(parsed.value)}.`;
+}
+
+export async function resetConfig(api: OpenClawPluginApi, key?: string): Promise<string> {
+  const next = deepCloneConfig(api.runtime.config.loadConfig());
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  entryObj.enabled = true;
+  const pluginCfg = asObj(entryObj.config);
+  entryObj.config = pluginCfg;
+
+  if (!key) {
+    for (const cfgKey of sortedKeys()) {
+      setValueAtPath(pluginCfg, cfgKey, DEFAULT_BY_KEY[cfgKey]);
+    }
+    await writeConfig(api, next);
+    return "Config reset to plugin defaults.";
+  }
+
+  if (!(key in CONFIG_SPECS)) {
+    return `Unknown key: ${key}`;
+  }
+
+  setValueAtPath(pluginCfg, key, DEFAULT_BY_KEY[key]);
+  await writeConfig(api, next);
+  return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])}.`;
+}
+
+export function normalizeConfigKey(keyRaw: string): string {
+  return keyRaw.trim();
+}
+
+export function canEditConfigKey(key: string): boolean {
+  return Boolean(CONFIG_SPECS[key]);
+}
+
+export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Promise<string> {
+  const next = deepCloneConfig(api.runtime.config.loadConfig());
+  const root = next as Record<string, unknown>;
+
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  entryObj.enabled = true;
+
+  const pluginCfg = asObj(entryObj.config);
+  entryObj.config = pluginCfg;
+
+  pluginCfg.enabled = true;
+  pluginCfg.mode = mode;
+  pluginCfg.maxSteps = DEFAULT_SETTINGS.maxSteps;
+  pluginCfg.maxForEach = DEFAULT_SETTINGS.maxForEach;
+  pluginCfg.maxResultChars = DEFAULT_SETTINGS.maxResultChars;
+  pluginCfg.invokeTimeoutMs = DEFAULT_SETTINGS.invokeTimeoutMs;
+  pluginCfg.storeLargeResults = DEFAULT_SETTINGS.storeLargeResults;
+  pluginCfg.resultStoreTtlSec = DEFAULT_SETTINGS.resultStoreTtlSec;
+  pluginCfg.resultSampleItems = DEFAULT_SETTINGS.resultSampleItems;
+  pluginCfg.requireSandbox = mode === "safe";
+  pluginCfg.denyControlPlane = true;
+  pluginCfg.toolSearch = {
+    enabled: true,
+    defaultLimit: DEFAULT_SETTINGS.toolSearch.defaultLimit,
+    useLiveRegistry: DEFAULT_SETTINGS.toolSearch.useLiveRegistry,
+    liveTimeoutMs: DEFAULT_SETTINGS.toolSearch.liveTimeoutMs,
+  };
+
+  const toolsObj = asObj(root.tools);
+  root.tools = toolsObj;
+  toolsObj.allow = mergeUniqueStrings(
+    Array.isArray(toolsObj.allow) ? toolsObj.allow : [],
+    ADVTOOLS_TOOL_NAMES,
+  );
+
+  await writeConfig(api, next);
+
+  return [
+    "OCSmartTools setup applied.",
+    `- mode: ${mode}`,
+    `- ensured tools.allow includes: ${ADVTOOLS_TOOL_NAMES.join(", ")}`,
+    "- config written via runtime config writer",
+    "If your gateway does not hot-apply this change, run: openclaw gateway restart",
+  ].join("\n");
+}
+
+export async function updateMode(api: OpenClawPluginApi, mode: AdvToolsMode): Promise<string> {
+  const next = deepCloneConfig(api.runtime.config.loadConfig());
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  entryObj.enabled = true;
+
+  const pluginCfg = asObj(entryObj.config);
+  entryObj.config = pluginCfg;
+  pluginCfg.mode = mode;
+  pluginCfg.requireSandbox = mode === "safe";
+  pluginCfg.denyControlPlane = true;
+
+  await writeConfig(api, next);
+  return `Mode updated to ${mode}.`;
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { registerChatCommands } from "./commands/chat.js";
+import { registerCliCommands } from "./commands/cli.js";
+import { createToolSearchTool } from "./tools/tool-search.js";
+import { createToolDispatchTool } from "./tools/tool-dispatch.js";
+import { createToolBatchTool } from "./tools/tool-batch.js";
+import { ResultStore } from "./lib/result-store.js";
+import { createToolResultGetTool } from "./tools/tool-result-get.js";
+import { autoBootstrap } from "./lib/bootstrap.js";
+import { MetricsStore } from "./lib/metrics-store.js";
+
+const plugin = {
+  id: "ocsmarttools",
+  name: "OCSmartTools",
+  description:
+    "Provider-agnostic advanced tool helper plugin with deterministic dispatch/batch tools and adaptive large-result handling.",
+  register(api: OpenClawPluginApi) {
+    const resultStore = new ResultStore();
+    const metricsStore = new MetricsStore();
+    let pruneTimer: NodeJS.Timeout | null = null;
+
+    registerChatCommands(api, metricsStore);
+    registerCliCommands(api, metricsStore);
+
+    api.registerTool(createToolSearchTool(api) as AnyAgentTool);
+
+    api.registerTool(
+      (ctx) =>
+        createToolDispatchTool(api, {
+          sandboxed: ctx.sandboxed,
+          store: resultStore,
+          metrics: metricsStore,
+        }) as AnyAgentTool,
+    );
+
+    api.registerTool(
+      (ctx) =>
+        createToolBatchTool(api, {
+          sandboxed: ctx.sandboxed,
+          store: resultStore,
+          metrics: metricsStore,
+        }) as AnyAgentTool,
+    );
+
+    api.registerTool(createToolResultGetTool(api, resultStore) as AnyAgentTool);
+
+    api.registerService({
+      id: "ocsmarttools",
+      start: async () => {
+        const bootstrap = await autoBootstrap(api);
+        if (bootstrap.changed) {
+          api.logger.info(`[ocsmarttools] auto-bootstrap applied: ${bootstrap.notes.join(", ")}`);
+        }
+        resultStore.prune();
+        pruneTimer = setInterval(() => resultStore.prune(), 60_000);
+        api.logger.info("[ocsmarttools] service started");
+      },
+      stop: () => {
+        if (pruneTimer) {
+          clearInterval(pruneTimer);
+          pruneTimer = null;
+        }
+        resultStore.clear();
+        api.logger.info("[ocsmarttools] service stopped");
+      },
+    });
+  },
+};
+
+export default plugin;

package/src/lib/bootstrap.ts

@@ -0,0 +1,114 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  DEFAULT_SETTINGS,
+  deepCloneConfig,
+  ensurePluginEntry,
+  mergeUniqueStrings,
+  writeConfig,
+} from "./plugin-config.js";
+
+const TOOL_NAMES = ["tool_search", "tool_dispatch", "tool_batch", "tool_result_get"];
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed: boolean; notes: string[] }> {
+  const current = api.runtime.config.loadConfig();
+  const next = deepCloneConfig(current);
+  const notes: string[] = [];
+  let changed = false;
+
+  const root = next as Record<string, unknown>;
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  if (entryObj.enabled !== true) {
+    entryObj.enabled = true;
+    changed = true;
+    notes.push("enabled plugin entry");
+  }
+
+  const pluginCfg = asObj(entryObj.config);
+  if (entryObj.config !== pluginCfg) {
+    entryObj.config = pluginCfg;
+    changed = true;
+  }
+
+  const setDefault = (key: string, value: unknown) => {
+    if (pluginCfg[key] === undefined) {
+      pluginCfg[key] = value;
+      changed = true;
+      notes.push(`set default ${key}`);
+    }
+  };
+
+  setDefault("enabled", true);
+  setDefault("mode", DEFAULT_SETTINGS.mode);
+  setDefault("maxSteps", DEFAULT_SETTINGS.maxSteps);
+  setDefault("maxForEach", DEFAULT_SETTINGS.maxForEach);
+  setDefault("maxResultChars", DEFAULT_SETTINGS.maxResultChars);
+  setDefault("invokeTimeoutMs", DEFAULT_SETTINGS.invokeTimeoutMs);
+  setDefault("storeLargeResults", DEFAULT_SETTINGS.storeLargeResults);
+  setDefault("resultStoreTtlSec", DEFAULT_SETTINGS.resultStoreTtlSec);
+  setDefault("resultSampleItems", DEFAULT_SETTINGS.resultSampleItems);
+  setDefault("requireSandbox", DEFAULT_SETTINGS.requireSandbox);
+  setDefault("denyControlPlane", DEFAULT_SETTINGS.denyControlPlane);
+  if (pluginCfg.toolSearch === undefined) {
+    pluginCfg.toolSearch = {
+      enabled: DEFAULT_SETTINGS.toolSearch.enabled,
+      defaultLimit: DEFAULT_SETTINGS.toolSearch.defaultLimit,
+      useLiveRegistry: DEFAULT_SETTINGS.toolSearch.useLiveRegistry,
+      liveTimeoutMs: DEFAULT_SETTINGS.toolSearch.liveTimeoutMs,
+    };
+    changed = true;
+    notes.push("set default toolSearch");
+  } else {
+    const ts = asObj(pluginCfg.toolSearch);
+    if (pluginCfg.toolSearch !== ts) {
+      pluginCfg.toolSearch = ts;
+      changed = true;
+    }
+    if (ts.enabled === undefined) {
+      ts.enabled = DEFAULT_SETTINGS.toolSearch.enabled;
+      changed = true;
+      notes.push("set default toolSearch.enabled");
+    }
+    if (ts.defaultLimit === undefined) {
+      ts.defaultLimit = DEFAULT_SETTINGS.toolSearch.defaultLimit;
+      changed = true;
+      notes.push("set default toolSearch.defaultLimit");
+    }
+    if (ts.useLiveRegistry === undefined) {
+      ts.useLiveRegistry = DEFAULT_SETTINGS.toolSearch.useLiveRegistry;
+      changed = true;
+      notes.push("set default toolSearch.useLiveRegistry");
+    }
+    if (ts.liveTimeoutMs === undefined) {
+      ts.liveTimeoutMs = DEFAULT_SETTINGS.toolSearch.liveTimeoutMs;
+      changed = true;
+      notes.push("set default toolSearch.liveTimeoutMs");
+    }
+  }
+
+  // If the user already runs strict allowlist mode, auto-add ocsmarttools tool names.
+  const toolsObj = asObj(root.tools);
+  root.tools = toolsObj;
+  const allowRaw = toolsObj.allow;
+  if (Array.isArray(allowRaw)) {
+    const merged = mergeUniqueStrings(allowRaw, TOOL_NAMES);
+    if (
+      merged.length !== allowRaw.length ||
+      merged.some((item, index) => allowRaw[index] !== item)
+    ) {
+      toolsObj.allow = merged;
+      changed = true;
+      notes.push("extended tools.allow with ocsmarttools tools");
+    }
+  }
+
+  if (changed) {
+    await writeConfig(api, next);
+  }
+  return { changed, notes };
+}