ocsmarttools 0.1.2

package/src/tools/tool-batch.ts

@@ -0,0 +1,374 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { resolveSettings } from "../lib/plugin-config.js";
+import { invokeToolViaGateway } from "../lib/invoke.js";
+import type { ResultStore } from "../lib/result-store.js";
+import { shapeToolResult } from "../lib/result-shaper.js";
+import { resolveValueTemplates } from "../lib/refs.js";
+import type { MetricsStore } from "../lib/metrics-store.js";
+
+const CONTROL_PLANE = new Set(["gateway", "cron"]);
+
+type BatchStepCall = {
+  type?: "call";
+  id?: string;
+  tool: string;
+  action?: string;
+  args?: Record<string, unknown>;
+  sessionKey?: string;
+  channel?: string;
+  accountId?: string;
+  timeoutMs?: number;
+};
+
+type BatchStepForEach = {
+  type: "foreach";
+  id?: string;
+  items: unknown;
+  as?: string;
+  call: BatchStepCall;
+};
+
+type BatchStep = BatchStepCall | BatchStepForEach;
+
+export const ToolBatchSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    steps: {
+      type: "array",
+      description: "Array of call/foreach steps.",
+      items: { type: "object" },
+      minItems: 1,
+      maxItems: 200,
+    },
+    sessionKey: { type: "string" },
+    channel: { type: "string" },
+    accountId: { type: "string" },
+    maxSteps: { type: "number", minimum: 1, maximum: 200 },
+    maxForEach: { type: "number", minimum: 1, maximum: 200 },
+    timeoutMs: { type: "number", minimum: 0, maximum: 1800000 },
+  },
+  required: ["steps"],
+};
+
+function normalizeStepId(candidate: unknown, index: number, existing: Set<string>): string {
+  const base = typeof candidate === "string" && candidate.trim() ? candidate.trim() : `step_${index + 1}`;
+  if (!existing.has(base)) {
+    existing.add(base);
+    return base;
+  }
+  let seq = 2;
+  while (existing.has(`${base}_${seq}`)) {
+    seq += 1;
+  }
+  const id = `${base}_${seq}`;
+  existing.add(id);
+  return id;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function parseSteps(raw: unknown): BatchStep[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter((entry) => entry && typeof entry === "object") as BatchStep[];
+}
+
+async function runCall(params: {
+  api: OpenClawPluginApi;
+  config: Record<string, unknown>;
+  settings: ReturnType<typeof resolveSettings>;
+  step: BatchStepCall;
+  context: Record<string, unknown>;
+  defaults: { sessionKey?: string; channel?: string; accountId?: string; timeoutMs?: number };
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  sandboxed?: boolean;
+  store?: ResultStore;
+  metrics?: MetricsStore;
+}) {
+  const { api, config, settings, step, context, defaults, sandboxed } = params;
+
+  const resolvedTool = resolveValueTemplates(step.tool, context);
+  const toolName = typeof resolvedTool === "string" ? resolvedTool.trim() : "";
+  if (!toolName) {
+    return { ok: false, error: "call step missing tool" };
+  }
+
+  if (toolName === "tool_batch") {
+    return { ok: false, error: "tool_batch cannot recursively dispatch itself" };
+  }
+
+  if (settings.requireSandbox && sandboxed === false) {
+    return { ok: false, error: "call blocked: sandbox required by plugin mode" };
+  }
+
+  if (settings.denyControlPlane && CONTROL_PLANE.has(toolName)) {
+    return { ok: false, error: `call blocked for control-plane tool: ${toolName}` };
+  }
+
+  const resolvedArgs = resolveValueTemplates(step.args ?? {}, context);
+  const args = asRecord(resolvedArgs);
+
+  const resolvedAction = resolveValueTemplates(step.action, context);
+  const action = typeof resolvedAction === "string" && resolvedAction.trim() ? resolvedAction.trim() : undefined;
+
+  const resolvedSessionKey = resolveValueTemplates(step.sessionKey, context);
+  const sessionKey =
+    typeof resolvedSessionKey === "string" && resolvedSessionKey.trim()
+      ? resolvedSessionKey.trim()
+      : defaults.sessionKey;
+
+  const resolvedChannel = resolveValueTemplates(step.channel, context);
+  const channel =
+    typeof resolvedChannel === "string" && resolvedChannel.trim()
+      ? resolvedChannel.trim()
+      : defaults.channel;
+
+  const resolvedAccountId = resolveValueTemplates(step.accountId, context);
+  const accountId =
+    typeof resolvedAccountId === "string" && resolvedAccountId.trim()
+      ? resolvedAccountId.trim()
+      : defaults.accountId;
+  const resolvedTimeoutMs = resolveValueTemplates(step.timeoutMs, context);
+  const timeoutMs =
+    typeof resolvedTimeoutMs === "number" && Number.isFinite(resolvedTimeoutMs)
+      ? Math.trunc(resolvedTimeoutMs)
+      : defaults.timeoutMs ?? settings.invokeTimeoutMs;
+
+  const invoke = await invokeToolViaGateway(config, {
+    tool: toolName,
+    action,
+    args,
+    sessionKey,
+    channel,
+    accountId,
+    timeoutMs,
+    signal: params.signal,
+  });
+
+  if (!invoke.ok) {
+    params.metrics?.record({
+      tool: toolName,
+      outcome: invoke.error?.type === "timeout" ? "timeout" : "failure",
+      latencyMs: invoke.latencyMs,
+    });
+    return {
+      ok: false,
+      status: invoke.status,
+      tool: toolName,
+      error: invoke.error,
+    };
+  }
+
+  const shaped = shapeToolResult({
+    toolName,
+    value: invoke.result,
+    settings,
+    store: params.store,
+  });
+  const jsonChars = (value: unknown): number => {
+    try {
+      const serialized = JSON.stringify(value);
+      return serialized ? serialized.length : 0;
+    } catch {
+      return 0;
+    }
+  };
+  const isShaped = (value: unknown): boolean => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const obj = value as Record<string, unknown>;
+    return obj.reduced === true || typeof obj.handle === "string";
+  };
+  params.metrics?.record({
+    tool: toolName,
+    outcome: "success",
+    latencyMs: invoke.latencyMs,
+    shaped: isShaped(shaped),
+    originalChars: jsonChars(invoke.result),
+    returnedChars: jsonChars(shaped),
+  });
+
+  return {
+    ok: true,
+    status: invoke.status,
+    tool: toolName,
+    result: shaped,
+  };
+}
+
+export function createToolBatchTool(
+  api: OpenClawPluginApi,
+  options?: { sandboxed?: boolean; store?: ResultStore; metrics?: MetricsStore },
+): AnyAgentTool {
+  return {
+    name: "tool_batch",
+    label: "Tool Batch",
+    description:
+      "Run a bounded sequence of tool calls with deterministic call/foreach steps and template refs.",
+    parameters: ToolBatchSchema,
+    async execute(_toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal) {
+      const loaded = api.runtime.config.loadConfig();
+      const settings = resolveSettings(api, loaded);
+      if (!settings.enabled) {
+        return jsonResult({
+          ok: false,
+          error: "ocsmarttools plugin config is disabled.",
+        });
+      }
+
+      const steps = parseSteps(params?.steps);
+      if (steps.length === 0) {
+        return jsonResult({ ok: false, error: "steps array is required" });
+      }
+
+      const requestedMaxSteps =
+        typeof params?.maxSteps === "number" && Number.isFinite(params.maxSteps)
+          ? Math.trunc(params.maxSteps)
+          : settings.maxSteps;
+      const maxSteps = Math.max(1, Math.min(200, requestedMaxSteps));
+
+      const requestedMaxForEach =
+        typeof params?.maxForEach === "number" && Number.isFinite(params.maxForEach)
+          ? Math.trunc(params.maxForEach)
+          : settings.maxForEach;
+      const maxForEach = Math.max(1, Math.min(200, requestedMaxForEach));
+
+      if (steps.length > maxSteps) {
+        return jsonResult({
+          ok: false,
+          error: `steps exceed maxSteps (${steps.length} > ${maxSteps})`,
+        });
+      }
+
+      const defaults = {
+        sessionKey:
+          typeof params?.sessionKey === "string" && params.sessionKey.trim()
+            ? params.sessionKey.trim()
+            : undefined,
+        channel:
+          typeof params?.channel === "string" && params.channel.trim() ? params.channel.trim() : undefined,
+        accountId:
+          typeof params?.accountId === "string" && params.accountId.trim()
+            ? params.accountId.trim()
+            : undefined,
+        timeoutMs:
+          typeof params?.timeoutMs === "number" && Number.isFinite(params.timeoutMs)
+            ? Math.trunc(params.timeoutMs)
+            : settings.invokeTimeoutMs,
+      };
+
+      const stepOutputs: Record<string, unknown> = {};
+      const ordered: Array<{ id: string; output: unknown }> = [];
+      const ids = new Set<string>();
+
+      for (const [index, stepRaw] of steps.entries()) {
+        const step = asRecord(stepRaw);
+        const type = typeof step.type === "string" ? step.type : "call";
+        const stepId = normalizeStepId(step.id, index, ids);
+
+        const contextBase: Record<string, unknown> = {
+          steps: stepOutputs,
+          index,
+        };
+
+        if (type === "foreach") {
+          const asName = typeof step.as === "string" && step.as.trim() ? step.as.trim() : "item";
+          const resolvedItems = resolveValueTemplates(step.items, contextBase);
+          if (!Array.isArray(resolvedItems)) {
+            stepOutputs[stepId] = {
+              ok: false,
+              error: "foreach.items must resolve to an array",
+            };
+            ordered.push({ id: stepId, output: stepOutputs[stepId] });
+            continue;
+          }
+
+          const subset = resolvedItems.slice(0, maxForEach);
+          const results: unknown[] = [];
+          let failures = 0;
+
+          const callSpec = asRecord(step.call) as BatchStepCall;
+
+          for (let i = 0; i < subset.length; i += 1) {
+            const item = subset[i];
+            const context = {
+              ...contextBase,
+              item,
+              index: i,
+              vars: {
+                [asName]: item,
+              },
+            };
+            const itemResult = await runCall({
+              api,
+              config: loaded,
+              settings,
+              step: callSpec,
+              context,
+              defaults,
+              signal: signal as AbortSignal | undefined,
+              sandboxed: options?.sandboxed,
+              store: options?.store,
+              metrics: options?.metrics,
+            });
+            if (!itemResult.ok) {
+              failures += 1;
+            }
+            results.push(itemResult);
+          }
+
+          stepOutputs[stepId] = {
+            ok: failures === 0,
+            type: "foreach",
+            itemCount: subset.length,
+            failures,
+            results,
+          };
+          ordered.push({ id: stepId, output: stepOutputs[stepId] });
+          continue;
+        }
+
+        const callStep = step as unknown as BatchStepCall;
+        const output = await runCall({
+          api,
+          config: loaded,
+          settings,
+          step: callStep,
+          context: contextBase,
+          defaults,
+          signal: signal as AbortSignal | undefined,
+          sandboxed: options?.sandboxed,
+          store: options?.store,
+          metrics: options?.metrics,
+        });
+        stepOutputs[stepId] = output;
+        ordered.push({ id: stepId, output });
+      }
+
+      const failed = ordered.filter((step) => {
+        const out = asRecord(step.output);
+        return out.ok === false;
+      }).length;
+
+      return jsonResult({
+        ok: failed === 0,
+        summary: {
+          totalSteps: ordered.length,
+          failedSteps: failed,
+          maxSteps,
+          maxForEach,
+        },
+        steps: ordered,
+      });
+    },
+  } as AnyAgentTool;
+}

package/src/tools/tool-dispatch.ts

@@ -0,0 +1,157 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { resolveSettings } from "../lib/plugin-config.js";
+import { invokeToolViaGateway } from "../lib/invoke.js";
+import type { ResultStore } from "../lib/result-store.js";
+import { shapeToolResult } from "../lib/result-shaper.js";
+import type { MetricsStore } from "../lib/metrics-store.js";
+
+const CONTROL_PLANE = new Set(["gateway", "cron"]);
+const INTERNAL_LOOP_TOOLS = new Set(["tool_dispatch", "tool_batch"]);
+
+export const ToolDispatchSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    tool: { type: "string", description: "Tool name to invoke." },
+    action: { type: "string", description: "Optional action helper for tools using action patterns." },
+    args: { type: "object", description: "Tool arguments object." },
+    sessionKey: { type: "string" },
+    channel: { type: "string" },
+    accountId: { type: "string" },
+    timeoutMs: { type: "number", minimum: 0, maximum: 1800000 },
+  },
+  required: ["tool"],
+};
+
+export function createToolDispatchTool(
+  api: OpenClawPluginApi,
+  options?: { sandboxed?: boolean; store?: ResultStore; metrics?: MetricsStore },
+): AnyAgentTool {
+  const jsonChars = (value: unknown): number => {
+    try {
+      const serialized = JSON.stringify(value);
+      return serialized ? serialized.length : 0;
+    } catch {
+      return 0;
+    }
+  };
+
+  const isShaped = (value: unknown): boolean => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return false;
+    }
+    const obj = value as Record<string, unknown>;
+    return obj.reduced === true || typeof obj.handle === "string";
+  };
+
+  return {
+    name: "tool_dispatch",
+    label: "Tool Dispatch",
+    description:
+      "Invoke a single tool through Gateway /tools/invoke with normal OpenClaw policy enforcement.",
+    parameters: ToolDispatchSchema,
+    async execute(_toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal) {
+      const loaded = api.runtime.config.loadConfig();
+      const settings = resolveSettings(api, loaded);
+      if (!settings.enabled) {
+        return jsonResult({
+          ok: false,
+          error: "ocsmarttools plugin config is disabled.",
+        });
+      }
+      const toolName = typeof params?.tool === "string" ? params.tool.trim() : "";
+
+      if (!toolName) {
+        return jsonResult({ ok: false, error: "tool is required" });
+      }
+
+      if (INTERNAL_LOOP_TOOLS.has(toolName)) {
+        return jsonResult({
+          ok: false,
+          error: `Dispatch blocked for internal orchestration tool: ${toolName}`,
+        });
+      }
+
+      if (settings.requireSandbox && options?.sandboxed === false) {
+        return jsonResult({
+          ok: false,
+          error: "Dispatch blocked: plugin requires sandboxed execution in current mode.",
+        });
+      }
+
+      if (settings.denyControlPlane && CONTROL_PLANE.has(toolName)) {
+        return jsonResult({
+          ok: false,
+          error: `Dispatch blocked in ${settings.mode} mode for control-plane tool: ${toolName}`,
+        });
+      }
+
+      const args = params?.args;
+      const safeArgs = args && typeof args === "object" && !Array.isArray(args) ? args : {};
+      const action = typeof params?.action === "string" ? params.action.trim() : undefined;
+      const sessionKey =
+        typeof params?.sessionKey === "string" && params.sessionKey.trim()
+          ? params.sessionKey.trim()
+          : undefined;
+      const channel =
+        typeof params?.channel === "string" && params.channel.trim() ? params.channel.trim() : undefined;
+      const accountId =
+        typeof params?.accountId === "string" && params.accountId.trim()
+          ? params.accountId.trim()
+          : undefined;
+      const requestedTimeoutMs =
+        typeof params?.timeoutMs === "number" && Number.isFinite(params.timeoutMs)
+          ? Math.trunc(params.timeoutMs)
+          : settings.invokeTimeoutMs;
+
+      const result = await invokeToolViaGateway(loaded, {
+        tool: toolName,
+        action,
+        args: safeArgs as Record<string, unknown>,
+        sessionKey,
+        channel,
+        accountId,
+        timeoutMs: requestedTimeoutMs,
+        signal: signal as AbortSignal | undefined,
+      });
+
+      if (!result.ok) {
+        options?.metrics?.record({
+          tool: toolName,
+          outcome: result.error?.type === "timeout" ? "timeout" : "failure",
+          latencyMs: result.latencyMs,
+        });
+        return jsonResult({
+          ok: false,
+          status: result.status,
+          error: result.error,
+        });
+      }
+
+      const shaped = shapeToolResult({
+        toolName,
+        value: result.result,
+        settings,
+        store: options?.store,
+      });
+      const originalChars = jsonChars(result.result);
+      const returnedChars = jsonChars(shaped);
+      options?.metrics?.record({
+        tool: toolName,
+        outcome: "success",
+        latencyMs: result.latencyMs,
+        shaped: isShaped(shaped),
+        originalChars,
+        returnedChars,
+      });
+
+      return jsonResult({
+        ok: true,
+        status: result.status,
+        tool: toolName,
+        result: shaped,
+      });
+    },
+  } as AnyAgentTool;
+}

package/src/tools/tool-result-get.ts

@@ -0,0 +1,65 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { resolveSettings } from "../lib/plugin-config.js";
+import type { ResultStore } from "../lib/result-store.js";
+import { shapeToolResult } from "../lib/result-shaper.js";
+
+export const ToolResultGetSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    handle: { type: "string", description: "Handle returned by tool_dispatch/tool_batch for large stored results." },
+    maxChars: { type: "number", minimum: 500, maximum: 500000 },
+  },
+  required: ["handle"],
+};
+
+export function createToolResultGetTool(api: OpenClawPluginApi, store: ResultStore): AnyAgentTool {
+  return {
+    name: "tool_result_get",
+    label: "Tool Result Get",
+    description: "Retrieve a previously stored large tool result by handle.",
+    parameters: ToolResultGetSchema,
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      const loaded = api.runtime.config.loadConfig();
+      const settings = resolveSettings(api, loaded);
+      if (!settings.enabled) {
+        return jsonResult({ ok: false, error: "ocsmarttools plugin config is disabled." });
+      }
+
+      const handle = typeof params.handle === "string" ? params.handle.trim() : "";
+      if (!handle) {
+        return jsonResult({ ok: false, error: "handle is required" });
+      }
+
+      const lookedUp = store.get(handle);
+      if (!lookedUp.ok) {
+        return jsonResult({
+          ok: false,
+          error: `No stored result found for handle: ${handle}`,
+        });
+      }
+
+      const maxChars =
+        typeof params.maxChars === "number" && Number.isFinite(params.maxChars)
+          ? Math.trunc(params.maxChars)
+          : settings.maxResultChars;
+
+      const shaped = shapeToolResult({
+        toolName: lookedUp.toolName ?? "tool_result_get",
+        value: lookedUp.value,
+        settings,
+        maxChars,
+        allowStore: false,
+      });
+
+      return jsonResult({
+        ok: true,
+        handle,
+        expiresAt: new Date(lookedUp.expiresAt).toISOString(),
+        result: shaped,
+      });
+    },
+  } as AnyAgentTool;
+}
+

package/src/tools/tool-search.ts

@@ -0,0 +1,72 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { jsonResult } from "openclaw/plugin-sdk";
+import { resolveSettings } from "../lib/plugin-config.js";
+import { buildCatalogWithLive, searchCatalog } from "../lib/tool-catalog.js";
+
+export const ToolSearchSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: { type: "string", description: "Search query for tool discovery." },
+    limit: { type: "number", minimum: 1, maximum: 50 },
+    group: { type: "string", description: "Optional group filter, e.g. web, fs, runtime." },
+  },
+  required: ["query"],
+};
+
+export function createToolSearchTool(api: OpenClawPluginApi): AnyAgentTool {
+  return {
+    name: "tool_search",
+    label: "Tool Search",
+    description: "Search available tools and return compact metadata.",
+    parameters: ToolSearchSchema,
+    async execute(_toolCallId, params) {
+      const loaded = api.runtime.config.loadConfig();
+      const settings = resolveSettings(api, loaded);
+      if (!settings.enabled) {
+        return jsonResult({
+          ok: false,
+          error: "ocsmarttools plugin config is disabled.",
+        });
+      }
+      if (!settings.toolSearch.enabled) {
+        return jsonResult({
+          ok: false,
+          error: "tool_search is disabled in plugin config.",
+        });
+      }
+
+      const query = typeof params?.query === "string" ? params.query.trim() : "";
+      if (!query) {
+        return jsonResult({ ok: false, error: "query is required" });
+      }
+
+      const requestedLimit =
+        typeof params?.limit === "number" && Number.isFinite(params.limit)
+          ? Math.trunc(params.limit)
+          : settings.toolSearch.defaultLimit;
+      const limit = Math.max(1, Math.min(50, requestedLimit));
+
+      const group = typeof params?.group === "string" ? params.group.trim() : undefined;
+
+      const built = await buildCatalogWithLive({
+        cfg: loaded,
+        useLiveRegistry: settings.toolSearch.useLiveRegistry,
+        liveTimeoutMs: settings.toolSearch.liveTimeoutMs,
+      });
+      const catalog = built.catalog;
+      const matches = searchCatalog({ catalog, query, limit, group });
+
+      return jsonResult({
+        ok: true,
+        query,
+        group: group ?? null,
+        catalogSource: built.source,
+        liveCount: built.liveCount,
+        totalCatalogSize: catalog.length,
+        count: matches.length,
+        tools: matches,
+      });
+    },
+  } as AnyAgentTool;
+}