ocsmarttools 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `ocsmarttools` are documented here.
 
+## [0.1.4] - 2026-02-22
+
+### Changed
+- Broadened peer compatibility range to `openclaw >=2026.2.19` for easier installs across existing instances.
+
+### Fixed
+- Routing policy sync is now fail-safe on restricted/read-only environments (never breaks plugin startup).
+- Setup/config flows now return clear messages when routing sync is skipped due to filesystem permissions/path issues.
+
+## [0.1.3] - 2026-02-22
+
+### Added
+- Plugin-native auto-routing guide sync for `AGENTS.md` with managed markers, enabled by default (`autoInjectRoutingGuide`).
+- New chat and CLI sync commands (`/ocsmarttools sync`, `openclaw ocsmarttools sync`) to re-apply routing guidance instantly.
+
+### Changed
+- `setup` now re-syncs the managed routing guide automatically.
+- Added `autoInjectRoutingGuide` to config schema, status, config output, and editable keys.
+
+### Fixed
+- Removed CLI registration conflict by making `stats reset` a subcommand under `stats`.
+
 ## [0.1.2] - 2026-02-22
 
 ### Added

package/README.md

@@ -23,6 +23,10 @@ flowchart LR
 
 ## Install
 
+Compatibility:
+- OpenClaw: `>=2026.2.19`
+- Works with existing installed instances (no core patch required)
+
 ### npm
 
 ```bash
@@ -43,7 +47,8 @@ openclaw gateway restart
 
 1. Install + enable + restart.
 2. Done. The plugin auto-bootstraps and starts working in background.
-3. Optional check:
+3. It also auto-manages an OCSmartTools routing block in `AGENTS.md` (unless disabled).
+4. Optional check:
 
 ```text
 /ocsmarttools status
@@ -66,6 +71,7 @@ Model note:
 | `/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 sync` | Re-applies the auto-managed routing policy block in `AGENTS.md` |
 | `/ocsmarttools config` | Shows effective plugin config |
 | `/ocsmarttools config keys` | Lists editable config keys |
 | `/ocsmarttools config set <key> <value>` | Updates one config key with validation |
@@ -82,6 +88,7 @@ Model note:
 | `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 sync` | Re-applies the auto-managed routing policy block in `AGENTS.md` |
 | `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 |
@@ -96,6 +103,8 @@ Model note:
 /ocsmarttools config set storeLargeResults true
 /ocsmarttools config set toolSearch.useLiveRegistry true
 /ocsmarttools config set toolSearch.liveTimeoutMs 1500
+/ocsmarttools config set autoInjectRoutingGuide true
+/ocsmarttools config set autoInjectRoutingGuide false
 /ocsmarttools config reset maxResultChars
 /ocsmarttools stats
 ```
@@ -143,6 +152,7 @@ If your instance uses strict `tools.allow`, include:
 ## Safety and Limits
 
 - `ocsmarttools` does not bypass OpenClaw tool policy.
+- Routing policy is auto-injected into `AGENTS.md` with managed markers; it can be re-synced via `/ocsmarttools sync`.
 - `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.

package/openclaw.plugin.json

@@ -8,6 +8,7 @@
     "properties": {
       "enabled": { "type": "boolean" },
       "mode": { "type": "string", "enum": ["safe", "standard"] },
+      "autoInjectRoutingGuide": { "type": "boolean" },
       "maxSteps": { "type": "integer", "minimum": 1, "maximum": 200 },
       "maxForEach": { "type": "integer", "minimum": 1, "maximum": 200 },
       "maxResultChars": { "type": "integer", "minimum": 500, "maximum": 500000 },
@@ -31,6 +32,7 @@
   },
   "uiHints": {
     "mode": { "label": "Mode" },
+    "autoInjectRoutingGuide": { "label": "Auto Inject Routing Guide" },
     "maxSteps": { "label": "Max Steps", "advanced": true },
     "maxForEach": { "label": "Max ForEach", "advanced": true },
     "maxResultChars": { "label": "Max Result Chars", "advanced": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocsmarttools",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Provider-agnostic advanced tool orchestration plugin for OpenClaw with search, dispatch, and batching",
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "openclaw": ">=2026.2.21"
+    "openclaw": ">=2026.2.19"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

package/src/commands/chat.ts

@@ -12,6 +12,7 @@ import {
   resetStats,
   resetConfig,
   setConfigKey,
+  syncManagedRouting,
   updateMode,
 } from "./operations.js";
 import type { AdvToolsMode } from "../lib/plugin-config.js";
@@ -72,6 +73,10 @@ export function registerChatCommands(api: OpenClawPluginApi, metrics: MetricsSto
           return { text: await updateMode(api, mode) };
         }
 
+        if (cmd === "sync") {
+          return { text: await syncManagedRouting(api) };
+        }
+
         if (cmd === "config") {
           const action = (parts[1] ?? "get").toLowerCase();
           if (action === "get") {
@@ -106,6 +111,7 @@ export function registerChatCommands(api: OpenClawPluginApi, metrics: MetricsSto
               "/ocsmarttools config keys",
               "/ocsmarttools config set <key> <value>",
               "/ocsmarttools config reset [key]",
+              "/ocsmarttools sync",
             ].join("\n"),
           };
         }

package/src/commands/cli.ts

@@ -10,6 +10,7 @@ import {
   resetStats,
   resetConfig,
   setConfigKey,
+  syncManagedRouting,
   updateMode,
 } from "./operations.js";
 import type { AdvToolsMode } from "../lib/plugin-config.js";
@@ -52,16 +53,13 @@ export function registerCliCommands(api: OpenClawPluginApi, metrics: MetricsStor
           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")
+      const statsCmd = adv.command("stats").description("Show usage/savings metrics");
+      statsCmd.action(() => {
+        // eslint-disable-next-line no-console
+        console.log(renderStats(metrics));
+      });
+      statsCmd
+        .command("reset")
         .description("Reset usage/savings metrics window")
         .action(() => {
           // eslint-disable-next-line no-console
@@ -91,6 +89,15 @@ export function registerCliCommands(api: OpenClawPluginApi, metrics: MetricsStor
           console.log(text);
         });
 
+      adv
+        .command("sync")
+        .description("Re-apply auto-managed routing policy to AGENTS.md")
+        .action(async () => {
+          const text = await syncManagedRouting(api);
+          // eslint-disable-next-line no-console
+          console.log(text);
+        });
+
       adv
         .command("config")
         .description("Show effective plugin config")

package/src/commands/operations.ts

@@ -9,6 +9,7 @@ import {
   writeConfig,
 } from "../lib/plugin-config.js";
 import type { MetricsStore } from "../lib/metrics-store.js";
+import { syncRoutingGuide } from "../lib/routing-guide.js";
 
 const ADVTOOLS_TOOL_NAMES = ["tool_search", "tool_dispatch", "tool_batch", "tool_result_get"];
 type ConfigKind = "boolean" | "integer" | "enum";
@@ -20,6 +21,7 @@ type ConfigSpec =
 const CONFIG_SPECS: Record<string, ConfigSpec> = {
   enabled: { kind: "boolean" },
   mode: { kind: "enum", values: ["safe", "standard"] },
+  autoInjectRoutingGuide: { kind: "boolean" },
   maxSteps: { kind: "integer", min: 1, max: 200 },
   maxForEach: { kind: "integer", min: 1, max: 200 },
   maxResultChars: { kind: "integer", min: 500, max: 500000 },
@@ -38,6 +40,7 @@ const CONFIG_SPECS: Record<string, ConfigSpec> = {
 const DEFAULT_BY_KEY: Record<string, boolean | number | string> = {
   enabled: DEFAULT_SETTINGS.enabled,
   mode: DEFAULT_SETTINGS.mode,
+  autoInjectRoutingGuide: DEFAULT_SETTINGS.autoInjectRoutingGuide,
   maxSteps: DEFAULT_SETTINGS.maxSteps,
   maxForEach: DEFAULT_SETTINGS.maxForEach,
   maxResultChars: DEFAULT_SETTINGS.maxResultChars,
@@ -140,6 +143,7 @@ export function renderStatus(api: OpenClawPluginApi): string {
     "OCSmartTools Status",
     `- plugin: ${api.id}`,
     `- mode: ${s.mode}`,
+    `- autoInjectRoutingGuide: ${s.autoInjectRoutingGuide}`,
     `- tool_search enabled: ${s.toolSearch.enabled}`,
     `- maxSteps: ${s.maxSteps}`,
     `- maxForEach: ${s.maxForEach}`,
@@ -165,6 +169,7 @@ export function renderHelp(): string {
     "- /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 sync: Re-apply auto-managed routing policy to AGENTS.md",
     "- /ocsmarttools config: Show effective plugin config",
     "- /ocsmarttools config keys: List editable config keys",
     "- /ocsmarttools config set <key> <value>: Update one config key",
@@ -229,6 +234,7 @@ export function renderConfig(api: OpenClawPluginApi): string {
     "OCSmartTools Config",
     `- enabled: ${s.enabled}`,
     `- mode: ${s.mode}`,
+    `- autoInjectRoutingGuide: ${s.autoInjectRoutingGuide}`,
     `- maxSteps: ${s.maxSteps}`,
     `- maxForEach: ${s.maxForEach}`,
     `- maxResultChars: ${s.maxResultChars}`,
@@ -273,6 +279,13 @@ export async function setConfigKey(
   setValueAtPath(pluginCfg, key, parsed.value);
   await writeConfig(api, next);
 
+  if (key === "autoInjectRoutingGuide" && parsed.value === true) {
+    const sync = await syncRoutingGuide(api, next);
+    if (sync.error) {
+      return `Config updated: ${key}=${JSON.stringify(parsed.value)} (routing sync skipped: ${sync.error}).`;
+    }
+  }
+
   return `Config updated: ${key}=${JSON.stringify(parsed.value)}.`;
 }
 
@@ -288,6 +301,12 @@ export async function resetConfig(api: OpenClawPluginApi, key?: string): Promise
       setValueAtPath(pluginCfg, cfgKey, DEFAULT_BY_KEY[cfgKey]);
     }
     await writeConfig(api, next);
+    if (DEFAULT_SETTINGS.autoInjectRoutingGuide) {
+      const sync = await syncRoutingGuide(api, next);
+      if (sync.error) {
+        return `Config reset to plugin defaults (routing sync skipped: ${sync.error}).`;
+      }
+    }
     return "Config reset to plugin defaults.";
   }
 
@@ -297,6 +316,12 @@ export async function resetConfig(api: OpenClawPluginApi, key?: string): Promise
 
   setValueAtPath(pluginCfg, key, DEFAULT_BY_KEY[key]);
   await writeConfig(api, next);
+  if (key === "autoInjectRoutingGuide" && DEFAULT_BY_KEY[key] === true) {
+    const sync = await syncRoutingGuide(api, next);
+    if (sync.error) {
+      return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])} (routing sync skipped: ${sync.error}).`;
+    }
+  }
   return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])}.`;
 }
 
@@ -320,6 +345,7 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
 
   pluginCfg.enabled = true;
   pluginCfg.mode = mode;
+  pluginCfg.autoInjectRoutingGuide = true;
   pluginCfg.maxSteps = DEFAULT_SETTINGS.maxSteps;
   pluginCfg.maxForEach = DEFAULT_SETTINGS.maxForEach;
   pluginCfg.maxResultChars = DEFAULT_SETTINGS.maxResultChars;
@@ -344,10 +370,16 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   );
 
   await writeConfig(api, next);
+  const sync = await syncRoutingGuide(api, next);
+  const syncLine = sync.error
+    ? `- routing guide sync skipped: ${sync.error}`
+    : `- routing guide ${sync.changed ? "synced" : "already up to date"} (${sync.filePath ?? "AGENTS.md"})`;
 
   return [
     "OCSmartTools setup applied.",
     `- mode: ${mode}`,
+    "- autoInjectRoutingGuide: true",
+    syncLine,
     `- 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",
@@ -368,3 +400,19 @@ export async function updateMode(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   await writeConfig(api, next);
   return `Mode updated to ${mode}.`;
 }
+
+export async function syncManagedRouting(api: OpenClawPluginApi): Promise<string> {
+  const loaded = api.runtime.config.loadConfig();
+  const settings = resolveSettings(api, loaded);
+  if (!settings.autoInjectRoutingGuide) {
+    return "Routing guide sync skipped: autoInjectRoutingGuide=false.";
+  }
+  const result = await syncRoutingGuide(api, loaded);
+  if (result.error) {
+    return `Routing guide sync skipped: ${result.error}`;
+  }
+  if (!result.changed) {
+    return `Routing guide already up to date (${result.filePath ?? "AGENTS.md"}).`;
+  }
+  return `Routing guide synced (${result.filePath ?? "AGENTS.md"}).`;
+}

package/src/lib/bootstrap.ts

@@ -6,6 +6,7 @@ import {
   mergeUniqueStrings,
   writeConfig,
 } from "./plugin-config.js";
+import { syncRoutingGuide } from "./routing-guide.js";
 
 const TOOL_NAMES = ["tool_search", "tool_dispatch", "tool_batch", "tool_result_get"];
 
@@ -45,6 +46,7 @@ export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed:
 
   setDefault("enabled", true);
   setDefault("mode", DEFAULT_SETTINGS.mode);
+  setDefault("autoInjectRoutingGuide", DEFAULT_SETTINGS.autoInjectRoutingGuide);
   setDefault("maxSteps", DEFAULT_SETTINGS.maxSteps);
   setDefault("maxForEach", DEFAULT_SETTINGS.maxForEach);
   setDefault("maxResultChars", DEFAULT_SETTINGS.maxResultChars);
@@ -110,5 +112,19 @@ export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed:
   if (changed) {
     await writeConfig(api, next);
   }
+
+  const routingGuideEnabled =
+    typeof pluginCfg.autoInjectRoutingGuide === "boolean"
+      ? pluginCfg.autoInjectRoutingGuide
+      : DEFAULT_SETTINGS.autoInjectRoutingGuide;
+  if (routingGuideEnabled) {
+    const sync = await syncRoutingGuide(api, next);
+    if (sync.error) {
+      notes.push(`routing guide skipped: ${sync.error}`);
+    } else if (sync.changed) {
+      notes.push(`synced routing guide (${sync.filePath ?? "AGENTS.md"})`);
+    }
+  }
+
   return { changed, notes };
 }

package/src/lib/plugin-config.ts

@@ -5,6 +5,7 @@ export type AdvToolsMode = "safe" | "standard";
 export type AdvToolsSettings = {
   enabled: boolean;
   mode: AdvToolsMode;
+  autoInjectRoutingGuide: boolean;
   maxSteps: number;
   maxForEach: number;
   maxResultChars: number;
@@ -25,6 +26,7 @@ export type AdvToolsSettings = {
 export const DEFAULT_SETTINGS: AdvToolsSettings = {
   enabled: true,
   mode: "standard",
+  autoInjectRoutingGuide: true,
   maxSteps: 25,
   maxForEach: 20,
   maxResultChars: 40000,
@@ -73,6 +75,10 @@ export function resolveSettings(api: OpenClawPluginApi, cfg: OpenClawConfig = ap
   return {
     enabled: asBool(pluginCfg.enabled, DEFAULT_SETTINGS.enabled),
     mode: asMode(pluginCfg.mode, DEFAULT_SETTINGS.mode),
+    autoInjectRoutingGuide: asBool(
+      pluginCfg.autoInjectRoutingGuide,
+      DEFAULT_SETTINGS.autoInjectRoutingGuide,
+    ),
     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),

package/src/lib/routing-guide.ts

@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+const BLOCK_START = "<!-- OCSMARTTOOLS_ROUTING_START -->";
+const BLOCK_END = "<!-- OCSMARTTOOLS_ROUTING_END -->";
+
+const ROUTING_BLOCK = `${BLOCK_START}
+## OCSmartTools Routing Policy (Auto-Managed)
+
+Default objective: preserve answer quality while reducing token and latency cost.
+
+1. If tool usage is needed and result size is uncertain, use \`tool_dispatch\`.
+2. If the task needs 2+ related tool calls, use \`tool_batch\`.
+3. Use \`tool_search\` only when tool choice is unclear.
+4. Prefer compact/tool-shaped outputs; use \`tool_result_get\` only when more detail is required.
+5. Use direct native tool calls only for simple one-shot small-output actions.
+
+Common large/noisy tools: \`web_fetch\`, \`read\` (large files), \`exec\`, \`process\`, \`browser\`, \`nodes\`.
+${BLOCK_END}
+`;
+
+function asObj(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function resolveWorkspaceDir(cfg: OpenClawConfig): string {
+  const root = cfg as Record<string, unknown>;
+  const agents = asObj(root.agents);
+  const defaults = asObj(agents.defaults);
+  const configured = defaults.workspace;
+  if (typeof configured === "string" && configured.trim()) {
+    return configured.trim();
+  }
+  if (typeof process.env.OPENCLAW_WORKSPACE === "string" && process.env.OPENCLAW_WORKSPACE.trim()) {
+    return process.env.OPENCLAW_WORKSPACE.trim();
+  }
+  return path.join(os.homedir(), ".openclaw", "workspace");
+}
+
+function upsertRoutingBlock(raw: string): string {
+  const source = raw.trim()
+    ? raw
+    : "# AGENTS.md - Workspace Directives\n\nAdd local operating preferences below.\n";
+
+  const start = source.indexOf(BLOCK_START);
+  const end = source.indexOf(BLOCK_END);
+  if (start >= 0 && end > start) {
+    const before = source.slice(0, start).replace(/\s*$/, "");
+    const after = source.slice(end + BLOCK_END.length).replace(/^\s*/, "");
+    return `${before}\n\n${ROUTING_BLOCK}\n${after}`.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  }
+  const joined = `${source.replace(/\s*$/, "")}\n\n${ROUTING_BLOCK}\n`;
+  return joined.replace(/\n{3,}/g, "\n\n");
+}
+
+export async function syncRoutingGuide(api: OpenClawPluginApi, cfg: OpenClawConfig): Promise<{
+  changed: boolean;
+  filePath?: string;
+  error?: string;
+}> {
+  const workspaceDir = resolveWorkspaceDir(cfg);
+  const filePath = path.join(workspaceDir, "AGENTS.md");
+  let current = "";
+  try {
+    current = await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      return {
+        changed: false,
+        filePath,
+        error: `read failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  const next = upsertRoutingBlock(current);
+  if (next === current) {
+    return { changed: false, filePath };
+  }
+
+  try {
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await fs.writeFile(filePath, next, "utf8");
+  } catch (error) {
+    return {
+      changed: false,
+      filePath,
+      error: `write failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  api.logger.info(`[ocsmarttools] routing policy synced: ${filePath}`);
+  return { changed: true, filePath };
+}