ocsmarttools 0.1.2

package/src/lib/result-shaper.ts

@@ -0,0 +1,237 @@
+import type { AdvToolsSettings } from "./plugin-config.js";
+import type { ResultStore } from "./result-store.js";
+
+type ShapeParams = {
+  toolName: string;
+  value: unknown;
+  settings: AdvToolsSettings;
+  maxChars?: number;
+  store?: ResultStore;
+  allowStore?: boolean;
+};
+
+const PRIORITY_KEYS = [
+  "status",
+  "error",
+  "message",
+  "summary",
+  "title",
+  "name",
+  "url",
+  "id",
+  "query",
+  "count",
+  "results",
+  "items",
+  "text",
+  "content",
+  "output",
+  "data",
+];
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function clipMiddle(value: string, keep: number): { truncated: boolean; text: string } {
+  if (value.length <= keep) {
+    return { truncated: false, text: value };
+  }
+  const budget = Math.max(60, keep);
+  const head = Math.floor(budget * 0.7);
+  const tail = Math.max(0, budget - head - 8);
+  return {
+    truncated: true,
+    text: `${value.slice(0, head)}\n...snip...\n${value.slice(value.length - tail)}`,
+  };
+}
+
+function summarizeString(value: string, maxLen: number): unknown {
+  const clipped = clipMiddle(value, maxLen);
+  if (!clipped.truncated) {
+    return value;
+  }
+  return {
+    truncated: true,
+    chars: value.length,
+    preview: clipped.text,
+  };
+}
+
+function summarizeValue(params: {
+  value: unknown;
+  depth: number;
+  maxDepth: number;
+  sampleItems: number;
+  maxString: number;
+  objectKeys: number;
+}): unknown {
+  const { value, depth, maxDepth, sampleItems, maxString, objectKeys } = params;
+  if (value == null || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return summarizeString(value, maxString);
+  }
+  if (Array.isArray(value)) {
+    if (depth >= maxDepth) {
+      return { type: "array", length: value.length, sample: value.slice(0, Math.min(sampleItems, value.length)) };
+    }
+    const sample = value.slice(0, Math.min(sampleItems, value.length)).map((item) =>
+      summarizeValue({
+        value: item,
+        depth: depth + 1,
+        maxDepth,
+        sampleItems,
+        maxString,
+        objectKeys,
+      }),
+    );
+    return {
+      type: "array",
+      length: value.length,
+      sample,
+      omitted: Math.max(0, value.length - sample.length),
+    };
+  }
+  const obj = asRecord(value);
+  const keys = Object.keys(obj);
+  const prioritized = PRIORITY_KEYS.filter((k) => keys.includes(k));
+  const rest = keys.filter((k) => !prioritized.includes(k)).sort((a, b) => a.localeCompare(b));
+  const selected = [...prioritized, ...rest].slice(0, objectKeys);
+
+  if (depth >= maxDepth) {
+    return {
+      type: "object",
+      keys: selected,
+      omittedKeys: Math.max(0, keys.length - selected.length),
+    };
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const key of selected) {
+    out[key] = summarizeValue({
+      value: obj[key],
+      depth: depth + 1,
+      maxDepth,
+      sampleItems,
+      maxString,
+      objectKeys,
+    });
+  }
+  if (keys.length > selected.length) {
+    out._omittedKeys = keys.length - selected.length;
+  }
+  return out;
+}
+
+function shapeWebSearch(value: unknown, sampleItems: number): unknown {
+  const obj = asRecord(value);
+  const resultsRaw = Array.isArray(obj.results) ? obj.results : [];
+  const results = resultsRaw.slice(0, Math.min(sampleItems, resultsRaw.length)).map((entry) => {
+    const r = asRecord(entry);
+    const desc = typeof r.description === "string" ? clipMiddle(r.description, 320).text : undefined;
+    return {
+      title: typeof r.title === "string" ? r.title : undefined,
+      url: typeof r.url === "string" ? r.url : undefined,
+      description: desc,
+    };
+  });
+  return {
+    query: typeof obj.query === "string" ? obj.query : undefined,
+    count: typeof obj.count === "number" ? obj.count : resultsRaw.length,
+    results,
+    omittedResults: Math.max(0, resultsRaw.length - results.length),
+  };
+}
+
+function shapeWebFetch(value: unknown): unknown {
+  const obj = asRecord(value);
+  const textCandidate =
+    typeof obj.text === "string"
+      ? obj.text
+      : typeof obj.content === "string"
+        ? obj.content
+        : typeof obj.markdown === "string"
+          ? obj.markdown
+          : undefined;
+  return {
+    url: typeof obj.url === "string" ? obj.url : undefined,
+    title: typeof obj.title === "string" ? obj.title : undefined,
+    text: typeof textCandidate === "string" ? summarizeString(textCandidate, 4000) : undefined,
+  };
+}
+
+function enforceHardLimit(value: unknown, maxChars: number): unknown {
+  const serialized = JSON.stringify(value);
+  if (!serialized || serialized.length <= maxChars) {
+    return value;
+  }
+  const clipped = clipMiddle(serialized, Math.max(200, maxChars - 80));
+  return {
+    truncated: true,
+    originalChars: serialized.length,
+    maxChars,
+    preview: clipped.text,
+  };
+}
+
+export function shapeToolResult(params: ShapeParams): unknown {
+  const maxChars = Math.max(500, Math.min(500000, Math.trunc(params.maxChars ?? params.settings.maxResultChars)));
+  const serialized = JSON.stringify(params.value);
+  if (!serialized || serialized.length <= maxChars) {
+    return params.value;
+  }
+
+  let summary: unknown;
+  if (params.toolName === "web_search") {
+    summary = shapeWebSearch(params.value, params.settings.resultSampleItems);
+  } else if (params.toolName === "web_fetch") {
+    summary = shapeWebFetch(params.value);
+  } else {
+    summary = summarizeValue({
+      value: params.value,
+      depth: 0,
+      maxDepth: 3,
+      sampleItems: params.settings.resultSampleItems,
+      maxString: 2000,
+      objectKeys: 18,
+    });
+  }
+
+  let handleMeta:
+    | {
+        handle: string;
+        ttlSec: number;
+        expiresAt: number;
+      }
+    | undefined;
+  if (params.allowStore !== false && params.settings.storeLargeResults && params.store) {
+    handleMeta = params.store.put({
+      value: params.value,
+      ttlSec: params.settings.resultStoreTtlSec,
+      toolName: params.toolName,
+    });
+  }
+
+  const shaped = {
+    reduced: true,
+    strategy: "adaptive-shape-v1",
+    tool: params.toolName,
+    originalChars: serialized.length,
+    maxChars,
+    ...(handleMeta
+      ? {
+          handle: handleMeta.handle,
+          handleTtlSec: handleMeta.ttlSec,
+          handleExpiresAt: new Date(handleMeta.expiresAt).toISOString(),
+        }
+      : {}),
+    summary,
+  };
+
+  return enforceHardLimit(shaped, maxChars);
+}
+

package/src/lib/result-store.ts

@@ -0,0 +1,72 @@
+import crypto from "node:crypto";
+
+type Entry = {
+  value: unknown;
+  createdAt: number;
+  expiresAt: number;
+  toolName?: string;
+};
+
+const DEFAULT_MAX_ENTRIES = 512;
+
+export type StoredResultMeta = {
+  handle: string;
+  ttlSec: number;
+  expiresAt: number;
+};
+
+export class ResultStore {
+  private readonly data = new Map<string, Entry>();
+
+  constructor(private readonly maxEntries: number = DEFAULT_MAX_ENTRIES) {}
+
+  put(params: { value: unknown; ttlSec: number; toolName?: string }): StoredResultMeta {
+    const now = Date.now();
+    const ttlSec = Math.max(60, Math.min(86400, Math.floor(params.ttlSec)));
+    const handle = `rs_${crypto.randomUUID().replace(/-/g, "").slice(0, 24)}`;
+    const expiresAt = now + ttlSec * 1000;
+
+    this.prune(now);
+    if (this.data.size >= this.maxEntries) {
+      const oldestKey = this.data.keys().next().value as string | undefined;
+      if (oldestKey) {
+        this.data.delete(oldestKey);
+      }
+    }
+
+    this.data.set(handle, {
+      value: params.value,
+      createdAt: now,
+      expiresAt,
+      toolName: params.toolName,
+    });
+
+    return { handle, ttlSec, expiresAt };
+  }
+
+  get(handle: string): { ok: true; value: unknown; toolName?: string; expiresAt: number } | { ok: false } {
+    const entry = this.data.get(handle);
+    if (!entry) {
+      return { ok: false };
+    }
+    const now = Date.now();
+    if (entry.expiresAt <= now) {
+      this.data.delete(handle);
+      return { ok: false };
+    }
+    return { ok: true, value: entry.value, toolName: entry.toolName, expiresAt: entry.expiresAt };
+  }
+
+  prune(nowMs = Date.now()): void {
+    for (const [key, value] of this.data.entries()) {
+      if (value.expiresAt <= nowMs) {
+        this.data.delete(key);
+      }
+    }
+  }
+
+  clear(): void {
+    this.data.clear();
+  }
+}
+

package/src/lib/tool-catalog.ts

@@ -0,0 +1,339 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export type ToolEntry = {
+  name: string;
+  group: string;
+  description: string;
+  paramsHint?: string;
+  source: "builtin" | "policy" | "live";
+};
+
+const BUILTIN: ToolEntry[] = [
+  { name: "exec", group: "runtime", description: "Run shell commands.", paramsHint: "{ command }", source: "builtin" },
+  { name: "bash", group: "runtime", description: "Alias for exec in many contexts.", paramsHint: "{ command }", source: "builtin" },
+  { name: "process", group: "runtime", description: "Manage background command sessions.", paramsHint: "{ action, sessionId? }", source: "builtin" },
+  { name: "read", group: "fs", description: "Read files.", paramsHint: "{ path }", source: "builtin" },
+  { name: "write", group: "fs", description: "Write files.", paramsHint: "{ path, content }", source: "builtin" },
+  { name: "edit", group: "fs", description: "Patch file text by replacement.", paramsHint: "{ path, oldText, newText }", source: "builtin" },
+  { name: "apply_patch", group: "fs", description: "Apply unified-style file patch.", paramsHint: "{ input }", source: "builtin" },
+  { name: "sessions_list", group: "sessions", description: "List sessions.", paramsHint: "{ ... }", source: "builtin" },
+  { name: "sessions_history", group: "sessions", description: "Read session history.", paramsHint: "{ sessionKey? }", source: "builtin" },
+  { name: "sessions_send", group: "sessions", description: "Send to another session.", paramsHint: "{ ... }", source: "builtin" },
+  { name: "sessions_spawn", group: "sessions", description: "Spawn subagent session.", paramsHint: "{ prompt, ... }", source: "builtin" },
+  { name: "session_status", group: "sessions", description: "Show current session status.", paramsHint: "{}", source: "builtin" },
+  { name: "memory_search", group: "memory", description: "Search memory snippets.", paramsHint: "{ query }", source: "builtin" },
+  { name: "memory_get", group: "memory", description: "Read memory entries.", paramsHint: "{ key }", source: "builtin" },
+  { name: "web_search", group: "web", description: "Search the web.", paramsHint: "{ query }", source: "builtin" },
+  { name: "web_fetch", group: "web", description: "Fetch and extract web page content.", paramsHint: "{ url }", source: "builtin" },
+  { name: "browser", group: "ui", description: "Browser automation.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "canvas", group: "ui", description: "Canvas/artifact rendering actions.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "cron", group: "automation", description: "Manage scheduled jobs.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "gateway", group: "automation", description: "Gateway control-plane actions.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "message", group: "messaging", description: "Message actions across channels.", paramsHint: "{ action, ... }", source: "builtin" },
+  { name: "nodes", group: "nodes", description: "Invoke node-side capabilities.", paramsHint: "{ action, ... }", source: "builtin" },
+];
+
+const GROUP_NAMES = new Set([
+  "group:runtime",
+  "group:fs",
+  "group:sessions",
+  "group:memory",
+  "group:web",
+  "group:ui",
+  "group:automation",
+  "group:messaging",
+  "group:nodes",
+  "group:openclaw",
+  "group:plugins",
+]);
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+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;
+}
+
+function extractToolsFromPayload(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+  const obj = asObj(payload);
+  if (Array.isArray(obj.tools)) {
+    return obj.tools;
+  }
+  const resultObj = asObj(obj.result);
+  if (Array.isArray(resultObj.tools)) {
+    return resultObj.tools;
+  }
+  if (Array.isArray(obj.result)) {
+    return obj.result as unknown[];
+  }
+  return [];
+}
+
+function normalizeLiveToolEntry(value: unknown): ToolEntry | null {
+  const obj = asObj(value);
+  const name = typeof obj.name === "string" ? obj.name.trim() : "";
+  if (!name) {
+    return null;
+  }
+  const group = typeof obj.group === "string" && obj.group.trim() ? obj.group.trim() : "live";
+  const description =
+    typeof obj.description === "string" && obj.description.trim()
+      ? obj.description.trim()
+      : "Tool discovered from live gateway registry.";
+  const hasParameters = obj.parameters !== undefined || obj.schema !== undefined || obj.input_schema !== undefined;
+
+  return {
+    name,
+    group,
+    description,
+    paramsHint: hasParameters ? "Runtime schema available." : undefined,
+    source: "live",
+  };
+}
+
+async function fetchLiveToolsFromGateway(
+  cfg: OpenClawConfig,
+  timeoutMs: number,
+): Promise<ToolEntry[]> {
+  const port = resolveGatewayPort(cfg);
+  const base = `http://127.0.0.1:${port}`;
+  const bearer = resolveBearer(cfg);
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (bearer) {
+    headers.Authorization = `Bearer ${bearer}`;
+  }
+
+  const attempts: Array<{ method: "GET" | "POST"; path: string; body?: unknown }> = [
+    { method: "GET", path: "/tools" },
+    { method: "GET", path: "/tools/list" },
+    { method: "GET", path: "/gateway/tools" },
+    { method: "POST", path: "/tools/list", body: {} },
+  ];
+
+  for (const attempt of attempts) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(250, timeoutMs));
+    try {
+      const response = await fetch(`${base}${attempt.path}`, {
+        method: attempt.method,
+        headers,
+        body: attempt.method === "POST" ? JSON.stringify(attempt.body ?? {}) : undefined,
+        signal: controller.signal,
+      });
+      const text = await response.text();
+      if (!response.ok) {
+        continue;
+      }
+      let parsed: unknown = undefined;
+      try {
+        parsed = text ? JSON.parse(text) : undefined;
+      } catch {
+        parsed = undefined;
+      }
+
+      const rawTools = extractToolsFromPayload(parsed);
+      if (!rawTools.length) {
+        continue;
+      }
+      const normalized = rawTools
+        .map((tool) => normalizeLiveToolEntry(tool))
+        .filter((tool): tool is ToolEntry => Boolean(tool));
+      if (normalized.length) {
+        return normalized;
+      }
+    } catch {
+      // Fallback to next endpoint.
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return [];
+}
+
+function gatherPolicyTools(cfg: OpenClawConfig): string[] {
+  const out = new Set<string>();
+
+  const root = cfg as Record<string, unknown>;
+  const tools = asObj(root.tools);
+  const agents = asObj(root.agents);
+  const defaults = asObj(agents.defaults);
+  const list = asArray(agents.list);
+
+  const collect = (arr: unknown) => {
+    for (const item of asArray(arr)) {
+      if (typeof item !== "string") {
+        continue;
+      }
+      const name = item.trim();
+      if (!name || name.includes("*") || GROUP_NAMES.has(name.toLowerCase())) {
+        continue;
+      }
+      out.add(name);
+    }
+  };
+
+  collect(tools.allow);
+  collect(defaults?.tools && asObj(defaults.tools).allow);
+  for (const agent of list) {
+    const a = asObj(agent);
+    const at = asObj(a.tools);
+    collect(at.allow);
+  }
+
+  return [...out];
+}
+
+export function buildCatalog(cfg: OpenClawConfig): ToolEntry[] {
+  const map = new Map<string, ToolEntry>();
+  for (const tool of BUILTIN) {
+    map.set(tool.name, tool);
+  }
+  for (const toolName of gatherPolicyTools(cfg)) {
+    if (!map.has(toolName)) {
+      map.set(toolName, {
+        name: toolName,
+        group: "plugin",
+        description: "Tool discovered from allowlist/policy configuration.",
+        paramsHint: "See tool schema at runtime.",
+        source: "policy",
+      });
+    }
+  }
+  return [...map.values()];
+}
+
+export async function buildCatalogWithLive(params: {
+  cfg: OpenClawConfig;
+  useLiveRegistry: boolean;
+  liveTimeoutMs: number;
+}): Promise<{
+  catalog: ToolEntry[];
+  source: "live" | "fallback" | "mixed";
+  liveCount: number;
+}> {
+  const { cfg, useLiveRegistry, liveTimeoutMs } = params;
+  const fallbackCatalog = buildCatalog(cfg);
+  if (!useLiveRegistry) {
+    return {
+      catalog: fallbackCatalog,
+      source: "fallback",
+      liveCount: 0,
+    };
+  }
+
+  const liveTools = await fetchLiveToolsFromGateway(cfg, liveTimeoutMs);
+  if (!liveTools.length) {
+    return {
+      catalog: fallbackCatalog,
+      source: "fallback",
+      liveCount: 0,
+    };
+  }
+
+  const merged = new Map<string, ToolEntry>();
+  for (const tool of fallbackCatalog) {
+    merged.set(tool.name, tool);
+  }
+  for (const tool of liveTools) {
+    merged.set(tool.name, tool);
+  }
+
+  return {
+    catalog: [...merged.values()],
+    source: merged.size === liveTools.length ? "live" : "mixed",
+    liveCount: liveTools.length,
+  };
+}
+
+function score(query: string, entry: ToolEntry): number {
+  const q = query.toLowerCase();
+  const n = entry.name.toLowerCase();
+  const d = entry.description.toLowerCase();
+  const g = entry.group.toLowerCase();
+
+  let s = 0;
+  if (n === q) s += 100;
+  if (n.startsWith(q)) s += 50;
+  if (n.includes(q)) s += 30;
+  if (g.includes(q)) s += 15;
+  if (d.includes(q)) s += 10;
+
+  for (const token of q.split(/\s+/).filter(Boolean)) {
+    if (n.includes(token)) s += 12;
+    if (d.includes(token)) s += 4;
+  }
+  return s;
+}
+
+export function searchCatalog(params: {
+  catalog: ToolEntry[];
+  query: string;
+  limit: number;
+  group?: string;
+}): ToolEntry[] {
+  const { catalog, query, limit, group } = params;
+  const normalizedGroup = group?.trim().toLowerCase();
+  const filtered = normalizedGroup
+    ? catalog.filter((entry) => entry.group.toLowerCase() === normalizedGroup)
+    : catalog;
+
+  const q = query.trim();
+  if (!q) {
+    return filtered.slice(0, limit);
+  }
+
+  return filtered
+    .map((entry) => ({ entry, score: score(q, entry) }))
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+    .slice(0, limit)
+    .map((item) => item.entry);
+}