ocsmarttools 0.1.2

package/src/lib/invoke.ts

@@ -0,0 +1,202 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export type InvokeParams = {
+  tool: string;
+  args?: Record<string, unknown>;
+  action?: string;
+  sessionKey?: string;
+  channel?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+export type InvokeResult = {
+  ok: boolean;
+  status: number;
+  latencyMs: number;
+  result?: unknown;
+  error?: {
+    type?: string;
+    message: string;
+    details?: unknown;
+  };
+};
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function resolveGatewayPort(cfg: OpenClawConfig): number {
+  const root = cfg as Record<string, unknown>;
+  const gateway = asObj(root.gateway);
+  const raw = gateway.port;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+    return Math.trunc(raw);
+  }
+  const envPort = process.env.OPENCLAW_GATEWAY_PORT;
+  if (envPort && Number.isFinite(Number(envPort))) {
+    return Number(envPort);
+  }
+  return 18789;
+}
+
+function resolveBearer(cfg: OpenClawConfig): string | undefined {
+  const root = cfg as Record<string, unknown>;
+  const gateway = asObj(root.gateway);
+  const auth = asObj(gateway.auth);
+  const mode = typeof auth.mode === "string" ? auth.mode : "token";
+
+  if (mode === "none") {
+    return undefined;
+  }
+
+  const token = typeof auth.token === "string" ? auth.token.trim() : "";
+  if (token) {
+    return token;
+  }
+
+  const password = typeof auth.password === "string" ? auth.password.trim() : "";
+  if (password) {
+    return password;
+  }
+
+  const envToken = (process.env.OPENCLAW_GATEWAY_TOKEN ?? "").trim();
+  if (envToken) {
+    return envToken;
+  }
+
+  const envPassword = (process.env.OPENCLAW_GATEWAY_PASSWORD ?? "").trim();
+  if (envPassword) {
+    return envPassword;
+  }
+
+  return undefined;
+}
+
+export async function invokeToolViaGateway(cfg: OpenClawConfig, params: InvokeParams): Promise<InvokeResult> {
+  const startedAtMs = Date.now();
+  const port = resolveGatewayPort(cfg);
+  const url = `http://127.0.0.1:${port}/tools/invoke`;
+  const bearer = resolveBearer(cfg);
+  const timeoutMs =
+    typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs)
+      ? Math.max(0, Math.min(1800000, Math.trunc(params.timeoutMs)))
+      : 0;
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  if (bearer) {
+    headers.Authorization = `Bearer ${bearer}`;
+  }
+  if (params.channel) {
+    headers["x-openclaw-message-channel"] = params.channel;
+  }
+  if (params.accountId) {
+    headers["x-openclaw-account-id"] = params.accountId;
+  }
+
+  const body = {
+    tool: params.tool,
+    action: params.action,
+    args: params.args ?? {},
+    sessionKey: params.sessionKey,
+  };
+
+  let response: Response;
+  const controller = new AbortController();
+  const abortFromParent = () => controller.abort();
+  if (params.signal) {
+    if (params.signal.aborted) {
+      return {
+        ok: false,
+        status: 0,
+        latencyMs: Date.now() - startedAtMs,
+        error: {
+          type: "aborted",
+          message: "tool invoke aborted",
+        },
+      };
+    }
+    params.signal.addEventListener("abort", abortFromParent, { once: true });
+  }
+  const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    if (params.signal) {
+      params.signal.removeEventListener("abort", abortFromParent);
+    }
+    if (controller.signal.aborted) {
+      const reason = params.signal?.aborted ? "aborted" : "timeout";
+      return {
+        ok: false,
+        status: 0,
+        latencyMs: Date.now() - startedAtMs,
+        error: {
+          type: reason,
+          message: reason === "timeout" ? "tool invoke request timed out" : "tool invoke aborted",
+        },
+      };
+    }
+    return {
+      ok: false,
+      status: 0,
+      latencyMs: Date.now() - startedAtMs,
+      error: {
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+  if (timer) {
+    clearTimeout(timer);
+  }
+  if (params.signal) {
+    params.signal.removeEventListener("abort", abortFromParent);
+  }
+
+  const text = await response.text();
+  let parsed: unknown = undefined;
+  try {
+    parsed = text ? JSON.parse(text) : undefined;
+  } catch {
+    parsed = { raw: text };
+  }
+
+  const obj = asObj(parsed);
+
+  if (!response.ok) {
+    const errObj = asObj(obj.error);
+    return {
+      ok: false,
+      status: response.status,
+      latencyMs: Date.now() - startedAtMs,
+      error: {
+        type: typeof errObj.type === "string" ? errObj.type : undefined,
+        message:
+          (typeof errObj.message === "string" && errObj.message) ||
+          `Tool invoke failed with status ${response.status}`,
+        details: obj,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: response.status,
+    latencyMs: Date.now() - startedAtMs,
+    result: obj.result,
+  };
+}

package/src/lib/metrics-store.ts

@@ -0,0 +1,177 @@
+export type InvocationOutcome = "success" | "failure" | "timeout";
+
+export type InvocationMetric = {
+  tool: string;
+  outcome: InvocationOutcome;
+  latencyMs: number;
+  originalChars?: number;
+  returnedChars?: number;
+  shaped?: boolean;
+};
+
+type ToolCounters = {
+  calls: number;
+  success: number;
+  failure: number;
+  timeout: number;
+  shaped: number;
+};
+
+export type MetricsSnapshot = {
+  startedAt: string;
+  totalCalls: number;
+  success: number;
+  failure: number;
+  timeout: number;
+  successRate: number;
+  timeoutRate: number;
+  avgLatencyMs: number;
+  p95LatencyApproxMs: number;
+  shapedResults: number;
+  shapedRateOnSuccess: number;
+  originalChars: number;
+  returnedChars: number;
+  charsSaved: number;
+  charReductionRate: number;
+  estimatedTokensSaved: number;
+  topTools: Array<{
+    tool: string;
+    calls: number;
+    success: number;
+    failure: number;
+    timeout: number;
+    shaped: number;
+  }>;
+};
+
+function clampRate(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  if (value > 1) {
+    return 1;
+  }
+  return value;
+}
+
+export class MetricsStore {
+  private startedAtMs = Date.now();
+  private totalCalls = 0;
+  private success = 0;
+  private failure = 0;
+  private timeout = 0;
+  private shapedResults = 0;
+  private originalChars = 0;
+  private returnedChars = 0;
+  private latencyTotalMs = 0;
+  private readonly latencyRing: number[] = [];
+  private readonly latencyRingSize = 512;
+  private readonly perTool = new Map<string, ToolCounters>();
+
+  record(metric: InvocationMetric): void {
+    this.totalCalls += 1;
+    this.latencyTotalMs += Math.max(0, Math.trunc(metric.latencyMs));
+
+    this.latencyRing.push(Math.max(0, Math.trunc(metric.latencyMs)));
+    if (this.latencyRing.length > this.latencyRingSize) {
+      this.latencyRing.shift();
+    }
+
+    if (metric.outcome === "success") {
+      this.success += 1;
+    } else if (metric.outcome === "timeout") {
+      this.timeout += 1;
+    } else {
+      this.failure += 1;
+    }
+
+    if (metric.shaped) {
+      this.shapedResults += 1;
+    }
+
+    if (typeof metric.originalChars === "number" && Number.isFinite(metric.originalChars)) {
+      this.originalChars += Math.max(0, Math.trunc(metric.originalChars));
+    }
+    if (typeof metric.returnedChars === "number" && Number.isFinite(metric.returnedChars)) {
+      this.returnedChars += Math.max(0, Math.trunc(metric.returnedChars));
+    }
+
+    const tool = metric.tool.trim() || "unknown";
+    const bucket = this.perTool.get(tool) ?? {
+      calls: 0,
+      success: 0,
+      failure: 0,
+      timeout: 0,
+      shaped: 0,
+    };
+    bucket.calls += 1;
+    if (metric.outcome === "success") {
+      bucket.success += 1;
+    } else if (metric.outcome === "timeout") {
+      bucket.timeout += 1;
+    } else {
+      bucket.failure += 1;
+    }
+    if (metric.shaped) {
+      bucket.shaped += 1;
+    }
+    this.perTool.set(tool, bucket);
+  }
+
+  reset(): void {
+    this.startedAtMs = Date.now();
+    this.totalCalls = 0;
+    this.success = 0;
+    this.failure = 0;
+    this.timeout = 0;
+    this.shapedResults = 0;
+    this.originalChars = 0;
+    this.returnedChars = 0;
+    this.latencyTotalMs = 0;
+    this.latencyRing.length = 0;
+    this.perTool.clear();
+  }
+
+  snapshot(topN = 5): MetricsSnapshot {
+    const total = this.totalCalls;
+    const successRate = total > 0 ? this.success / total : 0;
+    const timeoutRate = total > 0 ? this.timeout / total : 0;
+    const avgLatencyMs = total > 0 ? this.latencyTotalMs / total : 0;
+
+    const sortedLatency = [...this.latencyRing].sort((a, b) => a - b);
+    const p95Index = sortedLatency.length > 0
+      ? Math.min(sortedLatency.length - 1, Math.floor(sortedLatency.length * 0.95))
+      : 0;
+    const p95LatencyApproxMs = sortedLatency.length > 0 ? sortedLatency[p95Index] : 0;
+
+    const shapedRateOnSuccess = this.success > 0 ? this.shapedResults / this.success : 0;
+    const charsSaved = Math.max(0, this.originalChars - this.returnedChars);
+    const charReductionRate = this.originalChars > 0 ? charsSaved / this.originalChars : 0;
+    const estimatedTokensSaved = Math.round(charsSaved / 4);
+
+    const topTools = [...this.perTool.entries()]
+      .map(([tool, c]) => ({ tool, ...c }))
+      .sort((a, b) => b.calls - a.calls || a.tool.localeCompare(b.tool))
+      .slice(0, Math.max(1, topN));
+
+    return {
+      startedAt: new Date(this.startedAtMs).toISOString(),
+      totalCalls: total,
+      success: this.success,
+      failure: this.failure,
+      timeout: this.timeout,
+      successRate: clampRate(successRate),
+      timeoutRate: clampRate(timeoutRate),
+      avgLatencyMs,
+      p95LatencyApproxMs,
+      shapedResults: this.shapedResults,
+      shapedRateOnSuccess: clampRate(shapedRateOnSuccess),
+      originalChars: this.originalChars,
+      returnedChars: this.returnedChars,
+      charsSaved,
+      charReductionRate: clampRate(charReductionRate),
+      estimatedTokensSaved,
+      topTools,
+    };
+  }
+}

package/src/lib/plugin-config.ts

@@ -0,0 +1,143 @@
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export type AdvToolsMode = "safe" | "standard";
+
+export type AdvToolsSettings = {
+  enabled: boolean;
+  mode: AdvToolsMode;
+  maxSteps: number;
+  maxForEach: number;
+  maxResultChars: number;
+  invokeTimeoutMs: number;
+  storeLargeResults: boolean;
+  resultStoreTtlSec: number;
+  resultSampleItems: number;
+  requireSandbox: boolean;
+  denyControlPlane: boolean;
+  toolSearch: {
+    enabled: boolean;
+    defaultLimit: number;
+    useLiveRegistry: boolean;
+    liveTimeoutMs: number;
+  };
+};
+
+export const DEFAULT_SETTINGS: AdvToolsSettings = {
+  enabled: true,
+  mode: "standard",
+  maxSteps: 25,
+  maxForEach: 20,
+  maxResultChars: 40000,
+  invokeTimeoutMs: 0,
+  storeLargeResults: true,
+  resultStoreTtlSec: 1800,
+  resultSampleItems: 8,
+  requireSandbox: false,
+  denyControlPlane: true,
+  toolSearch: {
+    enabled: true,
+    defaultLimit: 8,
+    useLiveRegistry: true,
+    liveTimeoutMs: 1500,
+  },
+};
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asBool(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+function asMode(value: unknown, fallback: AdvToolsMode): AdvToolsMode {
+  return value === "safe" || value === "standard" ? value : fallback;
+}
+
+export function resolveSettings(api: OpenClawPluginApi, cfg: OpenClawConfig = api.config): AdvToolsSettings {
+  const plugins = asObj((cfg as Record<string, unknown>).plugins);
+  const entries = asObj(plugins.entries);
+  const entry = asObj(entries[api.id]);
+  const pluginCfg = asObj(entry.config ?? api.pluginConfig);
+  const ts = asObj(pluginCfg.toolSearch);
+
+  return {
+    enabled: asBool(pluginCfg.enabled, DEFAULT_SETTINGS.enabled),
+    mode: asMode(pluginCfg.mode, DEFAULT_SETTINGS.mode),
+    maxSteps: asInt(pluginCfg.maxSteps, DEFAULT_SETTINGS.maxSteps, 1, 200),
+    maxForEach: asInt(pluginCfg.maxForEach, DEFAULT_SETTINGS.maxForEach, 1, 200),
+    maxResultChars: asInt(pluginCfg.maxResultChars, DEFAULT_SETTINGS.maxResultChars, 500, 500000),
+    invokeTimeoutMs: asInt(pluginCfg.invokeTimeoutMs, DEFAULT_SETTINGS.invokeTimeoutMs, 0, 1800000),
+    storeLargeResults: asBool(pluginCfg.storeLargeResults, DEFAULT_SETTINGS.storeLargeResults),
+    resultStoreTtlSec: asInt(
+      pluginCfg.resultStoreTtlSec,
+      DEFAULT_SETTINGS.resultStoreTtlSec,
+      60,
+      86400,
+    ),
+    resultSampleItems: asInt(
+      pluginCfg.resultSampleItems,
+      DEFAULT_SETTINGS.resultSampleItems,
+      1,
+      50,
+    ),
+    requireSandbox: asBool(pluginCfg.requireSandbox, DEFAULT_SETTINGS.requireSandbox),
+    denyControlPlane: asBool(pluginCfg.denyControlPlane, DEFAULT_SETTINGS.denyControlPlane),
+    toolSearch: {
+      enabled: asBool(ts.enabled, DEFAULT_SETTINGS.toolSearch.enabled),
+      defaultLimit: asInt(ts.defaultLimit, DEFAULT_SETTINGS.toolSearch.defaultLimit, 1, 50),
+      useLiveRegistry: asBool(ts.useLiveRegistry, DEFAULT_SETTINGS.toolSearch.useLiveRegistry),
+      liveTimeoutMs: asInt(ts.liveTimeoutMs, DEFAULT_SETTINGS.toolSearch.liveTimeoutMs, 250, 10000),
+    },
+  };
+}
+
+export function deepCloneConfig<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+export async function writeConfig(api: OpenClawPluginApi, cfg: OpenClawConfig): Promise<void> {
+  await api.runtime.config.writeConfigFile(cfg);
+}
+
+export function ensurePluginEntry(cfg: OpenClawConfig, pluginId: string): {
+  pluginsObj: Record<string, unknown>;
+  entriesObj: Record<string, unknown>;
+  entryObj: Record<string, unknown>;
+} {
+  const root = cfg as Record<string, unknown>;
+  const pluginsObj = asObj(root.plugins);
+  root.plugins = pluginsObj;
+
+  const entriesObj = asObj(pluginsObj.entries);
+  pluginsObj.entries = entriesObj;
+
+  const entryObj = asObj(entriesObj[pluginId]);
+  entriesObj[pluginId] = entryObj;
+
+  return { pluginsObj, entriesObj, entryObj };
+}
+
+export function mergeUniqueStrings(items: unknown[], additions: string[]): string[] {
+  const merged = new Set<string>();
+  for (const item of items) {
+    if (typeof item === "string" && item.trim()) {
+      merged.add(item.trim());
+    }
+  }
+  for (const item of additions) {
+    if (item.trim()) {
+      merged.add(item.trim());
+    }
+  }
+  return [...merged];
+}

package/src/lib/refs.ts

@@ -0,0 +1,68 @@
+function normalizePath(pathExpr: string): string[] {
+  const trimmed = pathExpr.trim().replace(/^\$/, "");
+  const bracketToDot = trimmed
+    .replace(/\[(\d+)\]/g, ".$1")
+    .replace(/\[['\"]([^'\"]+)['\"]\]/g, ".$1");
+  return bracketToDot.split(".").filter(Boolean);
+}
+
+export function readPath(root: unknown, pathExpr: string): unknown {
+  const parts = normalizePath(pathExpr);
+  let cursor: unknown = root;
+  for (const part of parts) {
+    if (cursor === null || cursor === undefined) {
+      return undefined;
+    }
+    if (typeof cursor !== "object") {
+      return undefined;
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+function stringifyTemplateValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+export function resolveValueTemplates(value: unknown, context: Record<string, unknown>): unknown {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+
+    if (trimmed.startsWith("$") && !trimmed.includes(" ") && !trimmed.includes("{{")) {
+      return readPath(context, trimmed);
+    }
+
+    if (!value.includes("{{")) {
+      return value;
+    }
+
+    return value.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_match, group) => {
+      const resolved = readPath(context, String(group));
+      return stringifyTemplateValue(resolved);
+    });
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => resolveValueTemplates(entry, context));
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = resolveValueTemplates(v, context);
+  }
+  return out;
+}