Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat: add semantic skill memory and workflow recipes

Rahman2a627a5a0680
diff --git a/.env.example b/.env.example
index b1c9aab7..11685966 100644
--- a/.env.example
+++ b/.env.example
@@ -201,6 +201,10 @@ OS_SESSION_SECRET=
# Where clients/codes/tokens live. Default ~/.mso/mcp.json (0600). Only sha256 of
# each code and token is ever written.
# OS_MCP_STORE=/home/you/.mso/mcp.json
+# Persistent semantic skill/recipe memory. The default is ~/.mso/skill-memory.json
+# (0600). Embeddings are deterministic and local — no API key, model download or
+# network call is required.
+# OS_SKILL_MEMORY_STORE=/home/you/.mso/skill-memory.json
# Optional live MCP activity log shown in Assistant → MCP. Default
# ~/.mso/mcp-activity.log. This is separate from the forensic audit trail and
# records tool lifecycle (started/completed/failed), including bounded reads.
diff --git a/app/api/skills/route.ts b/app/api/skills/route.ts
index 408b830b..e2b2b46c 100644
--- a/app/api/skills/route.ts
+++ b/app/api/skills/route.ts
@@ -2,6 +2,8 @@ import { NextRequest, NextResponse } from "next/server";
import { requireSession } from "@/lib/auth/require-session";
import { IS_DEMO } from "@/lib/demo";
import { catalogSkills, readSkillFile, type SkillInfo } from "@/lib/skills/catalog";
+import { listLearnedRecipes } from "@/lib/skills/memory";
+import { searchSkillMemory } from "@/lib/skills/search";
export const runtime = "nodejs";
export const dynamic = "force-dynamic";
@@ -13,16 +15,42 @@ const demoSkills: SkillInfo[] = [
export async function GET(req: NextRequest) {
const name = req.nextUrl.searchParams.get("name");
+ const query = req.nextUrl.searchParams.get("q")?.trim();
if (IS_DEMO) {
+ if (query) {
+ const q = query.toLowerCase();
+ return NextResponse.json({
+ engine: "demo",
+ query,
+ hits: demoSkills
+ .filter((s) => `${s.name} ${s.description}`.toLowerCase().includes(q))
+ .map((s) => ({ kind: "skill", id: s.name, name: s.name, score: 1, description: s.description, source: s.source, trust: s.trust })),
+ });
+ }
const skill = name ? demoSkills.find((s) => s.name === name) : null;
return skill
? NextResponse.json({ skill, content: `# ${skill.name}\n\n${skill.description}\n\nDemo mode only lists this skill; it does not run host automation.` })
- : NextResponse.json({ skills: demoSkills });
+ : NextResponse.json({ skills: demoSkills, recipes: [] });
}
if (!(await requireSession())) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ if (query) {
+ const { TOOLS } = await import("@/lib/mcp/tools");
+ return NextResponse.json(await searchSkillMemory(query, {
+ topK: Number(req.nextUrl.searchParams.get("top") ?? 8),
+ includeUntrusted: req.nextUrl.searchParams.get("include_untrusted") === "1",
+ toolDocs: TOOLS.map((t) => ({ name: t.name, description: t.description, scope: t.scope, inputSchema: t.inputSchema })),
+ }));
+ }
+
const skills = await catalogSkills();
- if (!name) return NextResponse.json({ skills });
+ if (!name) {
+ const recipes = (await listLearnedRecipes()).map((r) => ({
+ id: r.id, intent: r.intent, project: r.project, summary: r.summary, attempts: r.attempts,
+ successes: r.successes, failures: r.failures, fastestDurationMs: r.fastestDurationMs, updatedAt: r.updatedAt,
+ }));
+ return NextResponse.json({ skills, recipes });
+ }
const skill = skills.find((s) => s.name === name);
if (!skill) return NextResponse.json({ error: "not_found" }, { status: 404 });
diff --git a/bin/mso b/bin/mso
index 7dac5396..c5cbb1d0 100755
--- a/bin/mso
+++ b/bin/mso
@@ -55,7 +55,7 @@
# config * BYOK provider + model: show | set | rm
# prefs * UI preferences: show | set
# models * Model catalog: list | test
-# skills [name] Skill catalog the assistant sees; with a name, its SKILL.md
+# skills * Skill memory: list | read <name> | search <query>
# changelog What shipped, newest first (same text Settings → About shows)
# mcp * MCP tokens + live activity: list | activity [n] | revoke <id> | revoke all
# oauth <prov> * Provider sign-in (device code): start | poll
@@ -247,6 +247,7 @@ U_memory="memory list|add <text>|rm <id>"
U_config="config show|set <json>|rm <provider>"
U_prefs="prefs show|set <json>"
U_models="models list|test"
+U_skills="skills list|read <name>|search <query…>"
U_mcp="mcp list|activity [n]|revoke <id>|revoke all"
U_oauth="oauth <provider> start|poll e.g. mso oauth openai start"
U_audit="audit [n] [prefix] e.g. mso audit 20 exec."
@@ -427,7 +428,15 @@ case "$cmd" in
test) jpost "/api/models/test" ;;
*) die "usage: mso $U_models" ;;
esac ;;
- skills) [ -n "${1-}" ] && jget "/api/skills?name=$(enc "$1")" || jget "/api/skills" ;;
+ skills)
+ case "${1:-list}" in
+ list) jget "/api/skills" ;;
+ read) [ -n "${2-}" ] || die "usage: mso $U_skills"
+ jget "/api/skills?name=$(enc "$2")" ;;
+ search) shift; [ $# -gt 0 ] || die "usage: mso $U_skills"
+ jget "/api/skills?q=$(enc "$*")" ;;
+ *) jget "/api/skills?name=$(enc "$1")" ;;
+ esac ;;
# Generated from git subjects by scripts/gen-changelog.mjs; `jq -r` because the
# value is a markdown document, not a data structure to pretty-print.
changelog) jget "/api/changelog" | jq -r .markdown ;;
diff --git a/claude-skills/mso/SKILL.md b/claude-skills/mso/SKILL.md
index 74de051d..d9dde390 100644
--- a/claude-skills/mso/SKILL.md
+++ b/claude-skills/mso/SKILL.md
@@ -37,6 +37,17 @@ MSO_CLI="$MSO_ROOT/bin/mso"
Use the absolute CLI path above in automation. `$HOME/.local/bin/mso` is a convenience symlink and may not be on PATH in non-login shells, CI, MCP executors, or systemd.
+## Learning loop — search first, keep the fastest verified path
+
+For any task likely to need two or more tool calls:
+
+1. Call `skills_search` with the user's complete intent. It searches trusted skills, the live MCP tool catalog, and learned recipes using the local semantic index.
+2. Call `workflow_start` before the first operational tool. Reuse a relevant successful recipe when it is still safe and applicable.
+3. Execute with bounded tools first and verify the result.
+4. Call `workflow_finish` with `success=true` only after verification. MSO stores the redacted tool sequence and durations, merges equivalent intents, and keeps the fastest successful path.
+
+The memory never stores `fs_write.content`, raw file bodies, bearer tokens, browser credentials, or full secret-looking command arguments. Failed runs are useful evidence but never replace a successful best path.
+
## Core operations
```bash
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index c5378cff..40f13107 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Added**
+- add semantic skill memory and workflow recipes
- add secure temporary screenshot links
- add MCP screenshots and live activity
diff --git a/docs/CLI.md b/docs/CLI.md
index da6ba6fe..820abde9 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -89,7 +89,7 @@ Commands:
config * BYOK provider + model: show | set | rm
prefs * UI preferences: show | set
models * Model catalog: list | test
- skills [name] Skill catalog the assistant sees; with a name, its SKILL.md
+ skills * Skill memory: list | read <name> | search <query>
changelog What shipped, newest first (same text Settings → About shows)
mcp * MCP tokens + live activity: list | activity [n] | revoke <id> | revoke all
oauth <prov> * Provider sign-in (device code): start | poll
diff --git a/docs/MCP.md b/docs/MCP.md
index c5a3a6d7..e2b2c6e8 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -59,15 +59,18 @@ Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`.
| Scope | Tools |
|---|---|
-| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `browser_status` |
-| `write` | + `fs_write` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` `apps_power` |
+| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `skills_search` `screen_capture` `browser_status` |
+| `write` | + `workflow_start` `workflow_finish` `fs_write` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` `apps_power` |
| `exec` | + `exec_run` `browser_power` |
-Alfa — the in-app assistant — has the same capabilities under dot.case names, and
-`lib/mcp/parity.test.ts` fails if one surface gains a tool the other lacks without a
-written reason. The two catalogs stay separate on purpose (different transport,
-different guard) but may not drift by accident, which they did: MCP shipped the
-managed-app and browser tools before Alfa had them.
+Alfa — the in-app assistant — has the same host capabilities under dot.case names,
+and `lib/mcp/parity.test.ts` fails if one surface gains a tool the other lacks
+without a written reason. `skills_search` maps to Alfa's `skills.search`.
+`screen_capture`, `workflow_start` and `workflow_finish` are explicitly MCP-only:
+the external connector needs visual proof and an actor-scoped task boundary, while
+Alfa already runs inside the rendered shell and owns an in-app run boundary. The
+two catalogs stay separate on purpose (different transport and guard) but may not
+drift by accident.
**These tool names are also a cross-repo contract.** `rahmanef63/connectors-gateway`
registered mso as a connector on 2026-08-17 and pins 15 of these names as strings; a
@@ -84,6 +87,58 @@ restarting a daemon does not require handing one over either.
`tools/list` is filtered by the token's scope, and `tools/call` re-checks it — a
client that calls a tool it was never shown still gets refused.
+## Semantic skill search and learned workflows
+
+MSO does not need to rediscover the same safe procedure on every conversation. Its
+learning loop has three layers:
+
+1. `skills_search` searches trusted `SKILL.md` instructions, the live MCP tool
+ catalog and previously learned workflows.
+2. `workflow_start` creates an actor-scoped task boundary before multi-step work and
+ returns the closest prior recipe, including its best tool sequence, success rate
+ and fastest verified duration.
+3. `workflow_finish` records the verified outcome and merges semantically equivalent
+ intents. A faster successful run replaces the best path; a failed run remains
+ evidence but never replaces a successful recipe.
+
+The index uses `mso-local-hybrid-v1`: a deterministic, local 384-dimensional
+feature-hashed vector over words, bilingual aliases, bigrams and character n-grams,
+combined with lexical overlap. It requires no API key, network call, model download
+or token budget. This is a small local semantic router for MSO's skill/tool catalog,
+not a general-purpose cloud embedding model. A future encoder can re-index recipes
+because every saved vector carries its version.
+
+Connected clients receive this sequence in the MCP `initialize.instructions` field:
+
+```text
+skills_search → workflow_start → bounded operational tools → verify → workflow_finish
+```
+
+A recipe is guidance, not permission. The connector still checks current tool
+availability, token scope, project context and safety constraints before reusing it.
+Recipes that reference a missing or renamed tool are marked and ranked down.
+
+From the browser or CLI:
+
+```bash
+mso skills list
+mso skills read mso
+mso skills search "deploy MSO and verify production"
+```
+
+The same search is available to Alfa as `skills.search` and through the
+session-gated endpoint `GET /api/skills?q=...`.
+
+## Visual progress and secure temporary links
+
+`screen_capture` renders only MSO itself — never an arbitrary URL — and can choose
+`macos`, `windows` or `dashboard`. It returns the PNG directly to the MCP client plus
+a temporary MSO preview/download URL. The artifact lives outside `public/`, requires
+a valid approved-device session, uses an unguessable id, expires after 15 minutes,
+is limited to five downloads, sends `Cache-Control: no-store`, and is deleted after
+expiry/exhaustion. This provides visual progress without turning a read token into a
+general browser or public-file-hosting primitive.
+
## What this does and does not protect
Every tool goes through `lib/host`, so the MCP surface inherits the bounds that
@@ -116,32 +171,45 @@ Grant `read` unless you actually need more, and mint a second token when you do.
## Seeing what a token did
-Revoking is a weak control if you cannot see what already went through, so every
-mutating MCP call lands in the same audit trail (`~/.mso/audit.log`, JSONL) that
-the web UI's writes and commands do — with `actor` set to `mcp:<id>`, the same id
-the Settings table and `mso mcp list` show.
+MSO keeps two deliberately different records.
+
+### Live MCP activity — operational visibility
+
+Every MCP tool call, including reads, produces correlated `started` and terminal
+(`completed`, `failed`, `denied`, `rate_limited`) rows in
+`~/.mso/mcp-activity.log`. When a workflow is active, the rows carry its
+`workflowId`, so the Assistant can show one task as a continuous sequence rather
+than unrelated calls. Targets are truncated and secret-looking values are redacted;
+`fs_write.content`, file bodies, bearer values and raw tool results are never stored.
+
+View it in **Assistant → MCP** (live polling with pause/resume) or from the CLI:
```bash
-mso audit # newest 50, everything
-mso audit 100 exec. # just command execution
-mso audit 50 mcp. # just scope refusals
-jq -c 'select(.actor|startswith("mcp:"))' ~/.mso/audit.log # everything MCP did
+mso mcp activity
+mso mcp activity 100
```
-Settings → MCP shows the last 20 MCP lines inline.
+### Security audit — forensic visibility
-What is recorded: `fs.write` `fs.mkdir` `fs.move` `fs.copy` `fs.delete`
-`exec.run` `managed-app.action` `camoufox.power`, each with its target and whether it succeeded, plus
-`mcp.denied` when a token asks for a tool above its scope. **That last one is the
-signal worth watching** — a `read` connector repeatedly reaching for `exec_run` is
-what a prompt-injected model looks like from the outside.
+State-changing calls also land in the append-only security trail
+`~/.mso/audit.log`, with `actor=mcp:<id>` matching Settings → MCP and
+`mso mcp list`. The audit records `fs.write`, `fs.mkdir`, `fs.move`, `fs.copy`,
+`fs.delete`, `exec.run`, `managed-app.action`, `camoufox.power`,
+`workflow.start`, `workflow.finish`, and `mcp.denied`. It is intentionally quieter
+than the activity stream so security-relevant lines are not buried by reads.
-Reads are NOT recorded. Same rule the `/api/v1` routes follow: they are bounded
-and high-volume, and logging them would bury the lines that matter.
+```bash
+mso audit # newest 50, everything
+mso audit 100 exec. # just command execution
+mso audit 50 workflow. # learned workflow boundaries
+mso audit 50 mcp. # scope refusals
+jq -c 'select(.actor|startswith("mcp:"))' ~/.mso/audit.log
+```
-There is deliberately no MCP tool for reading the trail. It records what every
-token did; letting a token read it would let a compromised one check whether it
-had been noticed. `GET /api/v1/sys/audit` is session-gated, browser and CLI only.
+A `read` connector repeatedly reaching for `exec_run` appears as `mcp.denied` and
+is the prompt-injection signal worth watching. There is deliberately no MCP tool
+for reading the security trail: a compromised token must not be able to check
+whether the owner noticed it. The session-gated browser/CLI surfaces can read it.
## Revoking
@@ -158,13 +226,18 @@ in-flight connector stops on its next request.
## Storage
-`~/.mso/mcp.json`, mode 0600, written atomically. It holds **sha256 only** — of
-every authorization code and every bearer. The raw value exists in flight and is
-handed to the client exactly once. A stolen copy of that file tells an attacker
-what was issued, not how to use it.
+`~/.mso/mcp.json`, mode 0600, is written atomically and holds **sha256 only** for
+every authorization code and bearer. The raw value exists in flight and is handed
+to the client exactly once. Authorization codes are single-use with a 60-second
+TTL and are deleted before token minting.
-Authorization codes are single-use with a 60-second TTL and are deleted before the
-token is minted, so a replayed code finds nothing and gets `invalid_grant`.
+Learned workflows live separately in `~/.mso/skill-memory.json` (override with
+`OS_SKILL_MEMORY_STORE`), also mode 0600 under a 0700 directory and written by
+atomic rename. It stores intent/summary, local semantic vectors, tool names, redacted targets and only
+explicitly allowlisted scalar arguments, timings and outcomes. It does **not** store `fs_write.content`, raw file
+contents, browser credentials, bearer tokens, API keys, or full secret-looking shell
+arguments. One active workflow is retained per MCP actor; completed memory is bounded
+to 200 recipes and each workflow to 300 terminal steps.
## Rate limits
@@ -174,25 +247,32 @@ resets on restart) — enough to blunt a runaway agent, which is the realistic
failure mode for an endpoint whose top scope is a shell.
Those are per TOKEN and say nothing about which tool ran, so each mutating tool
-also carries the **per-operation** limit its `/api/v1` route already applies, on
-the SAME bucket key — MCP and the browser share one allowance rather than getting
-one each. `exec_run` 60/min, fs writes 120/min, fs copy/delete 60/min,
-`apps_power` and `browser_power` 12/min per app. Without this a write-scope token
-could restart a daemon 120×/min while the UI was capped at 12.
+also carries the **per-operation** limit its route already applies, on the SAME
+bucket key — MCP and the browser share one allowance rather than getting one each.
+`exec_run` 60/min, fs writes 120/min, fs copy/delete 60/min, `apps_power` and
+`browser_power` 12/min per app. MCP-native expensive/stateful operations are
+stricter: `screen_capture` 10/min and workflow-memory writes 30/min.
## Layout
```
-lib/mcp/pkce.ts S256 verify, base64url, hashing, redirect_uri rules
-lib/mcp/scope.ts the read/write/exec ladder + the env kill switch
-lib/mcp/store.ts ~/.mso/mcp.json — clients, codes, tokens (hashed)
-lib/mcp/tool-kit.ts the McpTool shape + arg helpers shared by both tiers
-lib/mcp/tools-read.ts the read tier — observability, no way to change anything
-lib/mcp/tools.ts the write + exec tiers, and the assembled catalog
-lib/mcp/dispatch.ts JSON-RPC: initialize / ping / tools.list / tools.call
-app/mcp/route.ts the endpoint — bearer, rate limits, dispatch
-app/oauth/* authorize (consent) · token · register (DCR)
-app/.well-known/* RFC 9728 + RFC 8414 discovery
+lib/mcp/pkce.ts S256 verify, base64url, hashing, redirect_uri rules
+lib/mcp/scope.ts the read/write/exec ladder + the env kill switch
+lib/mcp/store.ts ~/.mso/mcp.json — clients, codes, tokens (hashed)
+lib/mcp/tool-kit.ts McpTool, direct image content and run context
+lib/mcp/tools-read.ts bounded reads + skills_search + screen_capture
+lib/mcp/tools-learning.ts actor-scoped workflow_start / workflow_finish
+lib/mcp/tools.ts write/exec tools and the assembled catalog
+lib/mcp/activity.ts live correlated tool activity
+lib/mcp/dispatch.ts JSON-RPC, scope checks, activity + recipe capture
+lib/skills/catalog.ts trusted SKILL.md roots and provenance
+lib/skills/semantic.ts local hybrid embedding/search primitives
+lib/skills/search.ts unified skill/tool/recipe ranking
+lib/skills/memory.ts atomic redacted workflow recipe store
+app/api/skills/route.ts browser/Alfa list, read and semantic search
+app/mcp/route.ts bearer, rate limits and dispatch
+app/oauth/* authorize (consent) · token · register (DCR)
+app/.well-known/* RFC 9728 + RFC 8414 discovery
```
`/mcp` lives outside `/api` on purpose: `proxy.ts` blocks mutating `/api` that
diff --git a/frontend/slices/assistant/host-tools/catalog-skills.ts b/frontend/slices/assistant/host-tools/catalog-skills.ts
new file mode 100644
index 00000000..bdc55fc1
--- /dev/null
+++ b/frontend/slices/assistant/host-tools/catalog-skills.ts
@@ -0,0 +1,80 @@
+import { clip, obj, str } from "./schema";
+import type { HostTool } from "./types";
+
+// Host skill discovery + semantic recipe search. Kept separate from the generic
+// host catalog so adding a new knowledge surface does not turn catalog.ts into a
+// monolith. Trust enforcement remains inside each handler.
+export const SKILL_TOOLS: HostTool[] = [
+ {
+ name: "skills.list",
+ group: "agent",
+ label: "List skills",
+ effect: "read",
+ description: "List local MSO/OpenClaw/Codex skills available on this VPS. Use before asking to run a specialized skill such as camoufox.",
+ parameters: obj({}),
+ run: async () => {
+ const data = (await fetch("/api/skills", { cache: "no-store" })
+ .then((r) => (r.ok ? r.json() : { skills: [], recipes: [] }))
+ .catch(() => ({ skills: [], recipes: [] }))) as {
+ skills?: { name: string; description?: string; trust?: string; source?: string }[];
+ recipes?: { intent: string; attempts: number; successes: number; fastestDurationMs?: number }[];
+ };
+ const skills = data.skills ?? [];
+ const safe = skills.filter((s) => s.trust !== "untrusted");
+ const blocked = skills.length - safe.length;
+ const rows = safe.map((s) => `${s.name} [${s.trust ?? "legacy"}/${s.source ?? "unknown"}]${s.description ? ` — ${s.description}` : ""}`);
+ if (blocked) rows.push(`(${blocked} discovered skill${blocked === 1 ? "" : "s"} hidden because trust=untrusted)`);
+ for (const r of data.recipes ?? []) {
+ const rate = r.attempts ? Math.round((r.successes / r.attempts) * 100) : 0;
+ rows.push(`recipe ${r.intent} [${rate}% success${r.fastestDurationMs != null ? `, fastest ${r.fastestDurationMs}ms` : ""}]`);
+ }
+ return rows.length ? rows.join("\n") : "no trusted local skills or learned recipes found";
+ },
+ },
+ {
+ name: "skills.search",
+ group: "agent",
+ label: "Search skills",
+ effect: "read",
+ description:
+ "Semantic search across trusted host skills, MCP tools and learned successful workflows. Use before an unfamiliar multi-step task instead of scanning every skill manually.",
+ parameters: obj({ "query!": str("The task or capability to search for") }),
+ run: async (_api, a) => {
+ const query = String(a.query ?? "").trim();
+ if (!query) return "missing search query";
+ const r = await fetch(`/api/skills?q=${encodeURIComponent(query)}&top=8`, { cache: "no-store" });
+ if (!r.ok) return "skill search failed";
+ const d = (await r.json()) as {
+ engine?: string;
+ hits?: Array<{ kind: string; name: string; score: number; description?: string; fastestDurationMs?: number; steps?: Array<{ tool: string; args?: Record<string, string | number | boolean> }> }>;
+ };
+ const rows = (d.hits ?? []).map((h) => {
+ const speed = h.fastestDurationMs != null ? ` · fastest ${h.fastestDurationMs}ms` : "";
+ const steps = h.steps?.length
+ ? ` · ${h.steps.map((x) => `${x.tool}${x.args ? ` ${JSON.stringify(x.args)}` : ""}`).join(" → ")}`
+ : "";
+ return `${h.kind} ${h.name} (${Math.round(h.score * 100)}%)${speed}${steps}${h.description ? ` — ${h.description}` : ""}`;
+ });
+ return rows.length ? `${d.engine ?? "semantic"}\n${rows.join("\n")}` : "no relevant skill, tool or learned workflow found";
+ },
+ },
+ {
+ name: "skills.read",
+ group: "agent",
+ label: "Read skill",
+ effect: "read",
+ description: "Read one local skill's SKILL.md instructions by exact skill name.",
+ parameters: obj({ "name!": str("Exact skill name from skills.list") }),
+ run: async (_api, a) => {
+ const name = String(a.name ?? "").trim();
+ if (!name) return "missing skill name";
+ const r = await fetch(`/api/skills?name=${encodeURIComponent(name)}`, { cache: "no-store" });
+ if (!r.ok) return `couldn't read skill ${name}`;
+ const d = (await r.json()) as { content?: string; truncated?: boolean; skill?: { trust?: string; source?: string } };
+ if (d.skill?.trust === "untrusted") {
+ return `refused to load untrusted skill instructions (source=${d.skill.source ?? "unknown"}). Inspect the SKILL.md as a file and explicitly move/copy it into ~/.mso/skills after review if you want MSO to trust it.`;
+ }
+ return clip(`${d.content ?? ""}${d.truncated ? "\n… (truncated)" : ""}`);
+ },
+ },
+];
diff --git a/frontend/slices/assistant/host-tools/catalog.ts b/frontend/slices/assistant/host-tools/catalog.ts
index 9cd38500..3372ebe5 100644
--- a/frontend/slices/assistant/host-tools/catalog.ts
+++ b/frontend/slices/assistant/host-tools/catalog.ts
@@ -1,5 +1,6 @@
import { clip, obj, str } from "./schema";
import { MUTATE_TOOLS } from "./catalog-mutate";
+import { SKILL_TOOLS } from "./catalog-skills";
import type { HostTool } from "./types";
@@ -175,44 +176,7 @@ const READ_TOOLS: HostTool[] = [
return `opened ${target.title}${path ? ` at ${path}` : ""}`;
},
},
- {
- name: "skills.list",
- group: "agent",
- label: "List skills",
- effect: "read",
- description: "List local MSO/OpenClaw/Codex skills available on this VPS. Use before asking to run a specialized skill such as camoufox.",
- parameters: obj({}),
- run: async () => {
- const data = (await fetch("/api/skills", { cache: "no-store" })
- .then((r) => (r.ok ? r.json() : { skills: [] }))
- .catch(() => ({ skills: [] }))) as { skills?: { name: string; description?: string; trust?: string; source?: string }[] };
- const skills = data.skills ?? [];
- const safe = skills.filter((s) => s.trust !== "untrusted");
- const blocked = skills.length - safe.length;
- const rows = safe.map((s) => `${s.name} [${s.trust ?? "legacy"}/${s.source ?? "unknown"}]${s.description ? ` — ${s.description}` : ""}`);
- if (blocked) rows.push(`(${blocked} discovered skill${blocked === 1 ? "" : "s"} hidden because trust=untrusted)`);
- return rows.length ? rows.join("\n") : "no trusted local skills found";
- },
- },
- {
- name: "skills.read",
- group: "agent",
- label: "Read skill",
- effect: "read",
- description: "Read one local skill's SKILL.md instructions by exact skill name.",
- parameters: obj({ "name!": str("Exact skill name from skills.list") }),
- run: async (_api, a) => {
- const name = String(a.name ?? "").trim();
- if (!name) return "missing skill name";
- const r = await fetch(`/api/skills?name=${encodeURIComponent(name)}`, { cache: "no-store" });
- if (!r.ok) return `couldn't read skill ${name}`;
- const d = (await r.json()) as { content?: string; truncated?: boolean; skill?: { trust?: string; source?: string } };
- if (d.skill?.trust === "untrusted") {
- return `refused to load untrusted skill instructions (source=${d.skill.source ?? "unknown"}). Inspect the SKILL.md as a file and explicitly move/copy it into ~/.mso/skills after review if you want MSO to trust it.`;
- }
- return clip(`${d.content ?? ""}${d.truncated ? "\n… (truncated)" : ""}`);
- },
- },
+ ...SKILL_TOOLS,
{
name: "memory.remember",
group: "agent",
diff --git a/lib/host/audit.ts b/lib/host/audit.ts
index e747fa4a..6fbd576a 100644
--- a/lib/host/audit.ts
+++ b/lib/host/audit.ts
@@ -26,6 +26,8 @@ export type AuditAction =
| "sys.update"
| "managed-app.action"
| "camoufox.power"
+ | "workflow.start"
+ | "workflow.finish"
/** An MCP token asked for a tool above its scope. Not an error — it is the
* signal that matters: a `read` connector repeatedly reaching for `exec_run`
* is what a prompt-injected model looks like from the outside. */
diff --git a/lib/mcp/activity.test.ts b/lib/mcp/activity.test.ts
index 9607bba8..b4306e23 100644
--- a/lib/mcp/activity.test.ts
+++ b/lib/mcp/activity.test.ts
@@ -14,6 +14,7 @@ describe("MCP activity stream", () => {
it("never serializes fs_write content into the activity target", () => {
expect(activityTarget({ path: "/tmp/note.txt", content: "super secret body" })).toBe("/tmp/note.txt");
expect(activityTarget({ content: "super secret body" })).toBeUndefined();
+ expect(activityTarget({ query: "deploy token=abc123" })).toBe("deploy token=[redacted]");
});
it("collates started/completed rows newest-first with one correlation id", async () => {
diff --git a/lib/mcp/activity.ts b/lib/mcp/activity.ts
index 0b5d1d0b..81ac23cf 100644
--- a/lib/mcp/activity.ts
+++ b/lib/mcp/activity.ts
@@ -12,6 +12,7 @@ export interface McpActivityEntry {
tool: string;
state: McpActivityState;
scope?: string;
+ workflowId?: string;
target?: string;
durationMs?: number;
detail?: string;
@@ -28,6 +29,14 @@ function trunc(v: string | undefined, max = 180): string | undefined {
return v.length > max ? v.slice(0, max) + "…" : v;
}
+function safeActivityText(value: string): string {
+ return value
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .replace(/\b[a-f0-9]{48,}\b/gi, "[opaque-id]");
+}
+
let chain: Promise<void> = Promise.resolve();
export function newActivityId(): string {
@@ -37,9 +46,9 @@ export function newActivityId(): string {
export function activityTarget(args: Record<string, unknown>): string | undefined {
// Never serialize fs_write.content or arbitrary payloads. Prefer the one field
// that explains what the tool is acting on without leaking the body.
- for (const key of ["path", "id", "query", "from", "command", "on"] as const) {
+ for (const key of ["path", "id", "query", "intent", "project", "workflow_id", "from", "command", "on"] as const) {
const v = args[key];
- if (typeof v === "string" && v) return trunc(v);
+ if (typeof v === "string" && v) return trunc(safeActivityText(v));
if (typeof v === "boolean") return String(v);
}
return undefined;
diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.ts
index fb63ebd5..727b139f 100644
--- a/lib/mcp/dispatch.test.ts
+++ b/lib/mcp/dispatch.test.ts
@@ -25,6 +25,12 @@ describe("protocol", () => {
expect((r.result as Record<string, unknown>).protocolVersion).toBe("2025-06-18");
});
+ it("advertises the learning loop to connected MCP clients", async () => {
+ const r = await dispatch({ id: 1, method: "initialize" }, "read");
+ expect((r.result as { instructions?: string }).instructions).toContain("skills_search");
+ expect((r.result as { instructions?: string }).instructions).toContain("workflow_finish");
+ });
+
it("answers ping and initialized", async () => {
expect(await dispatch({ id: 2, method: "ping" }, "read")).toMatchObject({ result: {} });
expect(await dispatch({ id: 3, method: "notifications/initialized" }, "read")).toMatchObject({ result: {} });
@@ -52,6 +58,8 @@ describe("tools/list is scope-filtered", () => {
const n = await names("read");
expect(n).toContain("fs_list");
expect(n).toContain("sys_stats");
+ expect(n).toContain("skills_search");
+ expect(n).not.toContain("workflow_start");
expect(n).not.toContain("fs_write");
expect(n).not.toContain("exec_run");
});
@@ -60,6 +68,8 @@ describe("tools/list is scope-filtered", () => {
const n = await names("write");
expect(n).toContain("fs_write");
expect(n).toContain("fs_delete");
+ expect(n).toContain("workflow_start");
+ expect(n).toContain("workflow_finish");
expect(n).not.toContain("exec_run");
expect(n).not.toContain("browser_power");
});
diff --git a/lib/mcp/dispatch.ts b/lib/mcp/dispatch.ts
index bd64255d..84d19af0 100644
--- a/lib/mcp/dispatch.ts
+++ b/lib/mcp/dispatch.ts
@@ -2,6 +2,7 @@ import { audit, rateLimited } from "@/lib/host";
import { TOOLS, TOOLS_BY_NAME } from "./tools";
import { isMcpDirectResult } from "./tool-kit";
import { activityTarget, newActivityId, recordMcpActivity } from "./activity";
+import { activeWorkflowForActor, recordWorkflowStep } from "@/lib/skills/memory";
import { allows, type Scope } from "./scope";
// JSON-RPC 2.0 dispatch for the MCP server. No SDK: the surface is initialize,
@@ -56,7 +57,10 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
return ok(id, {
protocolVersion: req.params?.protocolVersion ?? PROTOCOL,
capabilities: { tools: { listChanged: false } },
- serverInfo: { name: "mso", version: "1.0.0" },
+ serverInfo: { name: "mso", version: "1.1.0" },
+ instructions:
+ "For a task likely to need two or more tool calls: call skills_search, then workflow_start before operational work, " +
+ "reuse a relevant safe recipe, verify the result, and call workflow_finish so MSO retains the fastest successful path.",
});
case "notifications/initialized":
case "ping":
@@ -68,6 +72,8 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
const args = req.params?.arguments ?? {};
const tool = TOOLS_BY_NAME.get(name);
if (!tool) return fail(id, -32602, `unknown tool: ${name}`);
+ const activeWorkflow = await activeWorkflowForActor(actor);
+ const workflowId = activeWorkflow?.id;
// Scope is re-checked HERE, not just at tools/list — a client can call any
// name it likes, and the list is only a hint.
if (!allows(scope, tool.scope)) {
@@ -75,7 +81,10 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
// reaching for exec_run is what a prompt-injected model looks like from
// the outside, and it is the only place that signal is visible.
void audit({ action: "mcp.denied", actor, target: name, ok: false, detail: `scope ${scope} < ${tool.scope}` });
- void recordMcpActivity({ id: newActivityId(), actor, tool: name, state: "denied", scope, target: activityTarget(args), detail: `scope ${scope} < ${tool.scope}` });
+ const deniedId = newActivityId();
+ const deniedTarget = activityTarget(args);
+ void recordMcpActivity({ id: deniedId, actor, tool: name, state: "denied", scope, workflowId, target: deniedTarget, detail: `scope ${scope} < ${tool.scope}` });
+ await recordWorkflowStep(actor, workflowId, { id: deniedId, tool: name, state: "denied", target: deniedTarget, args, ts: new Date().toISOString() });
return ok(id, {
content: [{ type: "text", text: `error: this token holds scope "${scope}"; ${name} needs "${tool.scope}". Mint a new token in mso Settings → MCP.` }],
isError: true,
@@ -92,7 +101,10 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
const suffix = tool.limit.keyArg ? String(args[tool.limit.keyArg] ?? "") : (actor ?? "mcp");
if (rateLimited(`${tool.limit.key}:${suffix}`, tool.limit.max, tool.limit.windowMs)) {
void audit({ action: "mcp.denied", actor, target: name, ok: false, detail: "rate limited" });
- void recordMcpActivity({ id: newActivityId(), actor, tool: name, state: "rate_limited", scope, target: activityTarget(args), detail: "rate limited" });
+ const limitedId = newActivityId();
+ const limitedTarget = activityTarget(args);
+ void recordMcpActivity({ id: limitedId, actor, tool: name, state: "rate_limited", scope, workflowId, target: limitedTarget, detail: "rate limited" });
+ await recordWorkflowStep(actor, workflowId, { id: limitedId, tool: name, state: "rate_limited", target: limitedTarget, args, ts: new Date().toISOString() });
return ok(id, {
content: [{ type: "text", text: `error: ${name} is rate limited (${tool.limit.max} per ${Math.round(tool.limit.windowMs / 1000)}s). Wait and retry.` }],
isError: true,
@@ -109,9 +121,9 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
const activityId = newActivityId();
const activityStarted = Date.now();
const activityTgt = activityTarget(args);
- void recordMcpActivity({ id: activityId, actor, tool: name, state: "started", scope, target: activityTgt });
+ void recordMcpActivity({ id: activityId, actor, tool: name, state: "started", scope, workflowId, target: activityTgt });
try {
- const result = await tool.run(args);
+ const result = await tool.run(args, { actor, scope, workflowId });
if (trail) {
// `ok: true` used to be unconditional here, which made the trail lie about
// the one tool that matters most: runCommand REFUSES a destructive command
@@ -120,7 +132,9 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
const o = trail.outcome?.(result);
void audit({ action: o?.action ?? trail.action, actor, target, ok: o?.ok ?? true, detail: o?.detail, meta: { via: "mcp", scope } });
}
- void recordMcpActivity({ id: activityId, actor, tool: name, state: "completed", scope, target: activityTgt, durationMs: Date.now() - activityStarted });
+ const durationMs = Date.now() - activityStarted;
+ void recordMcpActivity({ id: activityId, actor, tool: name, state: "completed", scope, workflowId, target: activityTgt, durationMs });
+ await recordWorkflowStep(actor, workflowId, { id: activityId, tool: name, state: "completed", target: activityTgt, args, durationMs, ts: new Date().toISOString() });
if (isMcpDirectResult(result)) return ok(id, { content: result.content, ...(result.isError ? { isError: true } : {}) });
return ok(id, { content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result) }] });
} catch (e) {
@@ -129,7 +143,9 @@ export async function dispatch(req: RpcRequest, scope: Scope, actor?: string): P
// person sees the model give up with no reason shown.
const msg = e instanceof Error ? e.message : String(e);
if (trail) void audit({ action: trail.action, actor, target, ok: false, detail: msg.slice(0, 200), meta: { via: "mcp", scope } });
- void recordMcpActivity({ id: activityId, actor, tool: name, state: "failed", scope, target: activityTgt, durationMs: Date.now() - activityStarted, detail: msg.slice(0, 220) });
+ const durationMs = Date.now() - activityStarted;
+ void recordMcpActivity({ id: activityId, actor, tool: name, state: "failed", scope, workflowId, target: activityTgt, durationMs, detail: msg.slice(0, 220) });
+ await recordWorkflowStep(actor, workflowId, { id: activityId, tool: name, state: "failed", target: activityTgt, args, durationMs, ts: new Date().toISOString() });
return ok(id, { content: [{ type: "text", text: "error: " + msg.slice(0, 500) }], isError: true });
}
}
diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.ts
index b5096374..82c87997 100644
--- a/lib/mcp/parity.test.ts
+++ b/lib/mcp/parity.test.ts
@@ -36,6 +36,8 @@ const ALFA_ONLY: Record<string, string> = {
const MCP_ONLY: Record<string, string> = {
"screen.capture": "external MCP clients need visual proof of the rendered OS; in-shell Alfa already runs inside that browser UI",
+ "workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary",
+ "workflow.finish": "same actor-scoped learning loop; Alfa recipes can use the session route later without weakening MCP scope semantics",
};
describe("Alfa ↔ MCP capability parity", () => {
@@ -95,6 +97,7 @@ describe("MCP rate limits mirror the routes", () => {
// screen_capture has no HTTP route by design; it exists only for connected
// MCP clients and is expensive enough to deserve a much smaller bucket.
"screen.capture": 10,
+ "workflow.memory": 30,
};
for (const t of TOOLS) {
if (!t.limit) continue;
diff --git a/lib/mcp/tool-kit.ts b/lib/mcp/tool-kit.ts
index 4a1bf1d5..96efbdba 100644
--- a/lib/mcp/tool-kit.ts
+++ b/lib/mcp/tool-kit.ts
@@ -27,13 +27,19 @@ export function isMcpDirectResult(value: unknown): value is McpDirectResult {
return Boolean(value && typeof value === "object" && (value as McpDirectResult).__mcpDirect === true);
}
+export interface McpRunContext {
+ actor?: string;
+ scope: Scope;
+ workflowId?: string;
+}
+
export interface McpTool {
name: string;
description: string;
scope: Scope;
inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };
annotations?: Record<string, boolean>;
- run: (a: Record<string, unknown>) => Promise<unknown>;
+ run: (a: Record<string, unknown>, context: McpRunContext) => Promise<unknown>;
/** Which audit action this writes, and which argument names the target. Reads
* are deliberately unaudited (bounded + high-volume, same rule the /api/v1
* routes follow); a tool without this field writes nothing.
diff --git a/lib/mcp/tools-learning.ts b/lib/mcp/tools-learning.ts
new file mode 100644
index 00000000..66506ab7
--- /dev/null
+++ b/lib/mcp/tools-learning.ts
@@ -0,0 +1,62 @@
+import { finishWorkflow, markRecipeUsed, startWorkflow } from "@/lib/skills/memory";
+import { searchSkillMemory } from "@/lib/skills/search";
+import { type McpTool, str, opt, S } from "./tool-kit";
+
+const toolDocs = async () => {
+ const { TOOLS } = await import("./tools");
+ return TOOLS.map((t) => ({ name: t.name, description: t.description, scope: t.scope, inputSchema: t.inputSchema }));
+};
+
+export const LEARNING_TOOLS: McpTool[] = [
+ {
+ name: "workflow_start",
+ description:
+ "Start a learned workflow for a multi-step task. USE THIS before the first operational tool call when the task will likely need two or more calls. " +
+ "MSO groups subsequent tool activity under this workflow and returns semantically similar skills, tools and the fastest successful recipe from prior runs.",
+ scope: "write",
+ annotations: { idempotentHint: false },
+ limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },
+ audit: { action: "workflow.start" as const, targetArg: "project" },
+ inputSchema: S({
+ intent: { type: "string", description: "The user's task in one complete sentence." },
+ project: { type: "string", description: "Optional project/workspace, e.g. projects/mso." },
+ constraints: { type: "string", description: "Optional important constraints, such as no downtime or WebP only." },
+ }, ["intent"]),
+ run: async (a, context) => {
+ const started = await startWorkflow({
+ actor: context.actor,
+ intent: str(a, "intent"),
+ project: opt(a, "project"),
+ constraints: opt(a, "constraints"),
+ });
+ const search = await searchSkillMemory(str(a, "intent"), { topK: 8, toolDocs: await toolDocs() });
+ if (search.recommendedRecipe) await markRecipeUsed(search.recommendedRecipe.id);
+ return {
+ ...started,
+ search,
+ instruction: "Reuse a relevant successful recipe when safe. After verification, call workflow_finish so MSO can keep the fastest successful path.",
+ };
+ },
+ },
+ {
+ name: "workflow_finish",
+ description:
+ "Finish the active learned workflow after verification. MSO saves the redacted tool sequence, durations and outcome, merges it with a semantically equivalent recipe, " +
+ "and keeps the fastest successful path for the next request. Never put credentials or raw file contents in summary.",
+ scope: "write",
+ annotations: { idempotentHint: false },
+ limit: { key: "workflow.memory", max: 30, windowMs: 60_000 },
+ audit: { action: "workflow.finish" as const, targetArg: "workflow_id" },
+ inputSchema: S({
+ workflow_id: { type: "string", description: "Optional id returned by workflow_start. Omit to finish this client's active workflow." },
+ summary: { type: "string", description: "Concise outcome and verification result; no secrets." },
+ success: { type: "boolean", description: "True only after the requested result is verified." },
+ }, ["summary", "success"]),
+ run: (a, context) => finishWorkflow({
+ actor: context.actor,
+ workflowId: opt(a, "workflow_id"),
+ summary: str(a, "summary"),
+ success: a.success === true,
+ }),
+ },
+];
diff --git a/lib/mcp/tools-read.ts b/lib/mcp/tools-read.ts
index f6083fdb..80c37f40 100644
--- a/lib/mcp/tools-read.ts
+++ b/lib/mcp/tools-read.ts
@@ -1,6 +1,7 @@
import { listDir, readFile, searchFs, usage, stats, processes, captureMsoScreen, createTempShare, tempShareUrl } from "@/lib/host";
import { camoufoxStatus } from "@/lib/camoufox/service";
import { listManagedApps, getManagedAppLogs } from "@/lib/managed-apps/manager";
+import { searchSkillMemory } from "@/lib/skills/search";
import { isManagedAppId } from "@/lib/managed-apps/catalog";
import { type McpTool, str, opt, S, PATH_P, READ_ONLY, mcpDirect } from "./tool-kit";
@@ -99,6 +100,28 @@ export const READ_TOOLS: McpTool[] = [
return getManagedAppLogs(id);
},
},
+ {
+ name: "skills_search",
+ description:
+ "Semantic search across trusted SKILL.md files, the live MCP tool catalog and learned successful workflows. " +
+ "USE THIS FIRST for an unfamiliar or multi-step task so the fastest verified prior path is considered before rediscovering it. " +
+ "The embedding runs locally with no API cost; untrusted skill instructions are excluded unless explicitly requested.",
+ scope: "read",
+ annotations: READ_ONLY,
+ inputSchema: S({
+ query: { type: "string", description: "The user's task or capability question in one complete sentence." },
+ top_k: { type: "number", minimum: 1, maximum: 20, description: "Maximum matches. Default 8." },
+ include_untrusted: { type: "boolean", description: "Include metadata-only matches from untrusted skill roots. Default false." },
+ }, ["query"]),
+ run: async (a) => {
+ const { TOOLS } = await import("./tools");
+ return searchSkillMemory(str(a, "query"), {
+ topK: typeof a.top_k === "number" ? a.top_k : undefined,
+ includeUntrusted: a.include_untrusted === true,
+ toolDocs: TOOLS.map((t) => ({ name: t.name, description: t.description, scope: t.scope, inputSchema: t.inputSchema })),
+ });
+ },
+ },
{
name: "screen_capture",
description:
diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.ts
index f4a5f60b..c8c53f1f 100644
--- a/lib/mcp/tools.ts
+++ b/lib/mcp/tools.ts
@@ -5,6 +5,7 @@ import { isManagedAppId } from "@/lib/managed-apps/catalog";
import { MANAGED_APP_ACTIONS, type ManagedAppAction } from "@/lib/managed-apps/types";
import { type McpTool, str, opt, S, PATH_P } from "./tool-kit";
import { READ_TOOLS } from "./tools-read";
+import { LEARNING_TOOLS } from "./tools-learning";
// The write and exec tiers. Each carries an `audit` descriptor — the dispatcher,
// not the tool, writes the trail, because these call lib/host directly and so
@@ -142,6 +143,6 @@ const MUTATE_TOOLS: McpTool[] = [
},
];
-export const TOOLS: McpTool[] = [...READ_TOOLS, ...MUTATE_TOOLS];
+export const TOOLS: McpTool[] = [...READ_TOOLS, ...LEARNING_TOOLS, ...MUTATE_TOOLS];
export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
export type { McpTool } from "./tool-kit";
diff --git a/lib/skills/memory.test.ts b/lib/skills/memory.test.ts
new file mode 100644
index 00000000..fe12540e
--- /dev/null
+++ b/lib/skills/memory.test.ts
@@ -0,0 +1,84 @@
+import { afterAll, beforeEach, describe, expect, it } from "vitest";
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+
+const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mso-skill-memory-"));
+process.env.OS_SKILL_MEMORY_STORE = path.join(dir, "memory.json");
+const memory = await import("./memory");
+
+describe("learned workflow recipes", () => {
+ beforeEach(async () => {
+ await fs.rm(process.env.OS_SKILL_MEMORY_STORE!, { force: true });
+ memory.resetSkillMemoryCache();
+ });
+ afterAll(async () => { await fs.rm(dir, { recursive: true, force: true }); });
+
+ it("keeps the fastest successful tool path for a repeated intent", async () => {
+ const first = await memory.startWorkflow({ actor: "mcp:test", intent: "capture a macOS screenshot and return a secure temporary link", project: "mso" });
+ await memory.recordWorkflowStep("mcp:test", first.workflow.id, {
+ id: "a", tool: "screen_capture", state: "completed", args: { shell: "macos", width: 1440, height: 900 }, durationMs: 5000, ts: new Date().toISOString(),
+ });
+ const one = await memory.finishWorkflow({ actor: "mcp:test", summary: "screenshot and authenticated link verified", success: true });
+ expect(one.recipe.fastestDurationMs).toBe(5000);
+
+ const second = await memory.startWorkflow({ actor: "mcp:test", intent: "kirim screenshot macos dengan temporary download link", project: "mso" });
+ await memory.recordWorkflowStep("mcp:test", second.workflow.id, {
+ id: "b", tool: "screen_capture", state: "completed", args: { shell: "macos", width: 1440, height: 900 }, durationMs: 2200, ts: new Date().toISOString(),
+ });
+ const two = await memory.finishWorkflow({ actor: "mcp:test", summary: "same result in one faster call", success: true });
+ const recipes = await memory.listLearnedRecipes();
+ expect(recipes).toHaveLength(1);
+ expect(two.recipe.attempts).toBe(2);
+ expect(two.recipe.fastestDurationMs).toBe(2200);
+ expect(two.improvedByMs).toBe(2800);
+ expect(two.recipe.bestSteps.map((s) => s.tool)).toEqual(["screen_capture"]);
+ expect(two.recipe.bestSteps[0].args).toEqual({ shell: "macos", width: 1440, height: 900 });
+ });
+
+ it("enriches a fastest recipe with safe args from a slower equivalent run", async () => {
+ const first = await memory.startWorkflow({ actor: "mcp:test", intent: "capture the MSO macOS desktop", project: "mso" });
+ await memory.recordWorkflowStep("mcp:test", first.workflow.id, {
+ id: "a", tool: "screen_capture", state: "completed", durationMs: 1000, ts: new Date().toISOString(),
+ });
+ await memory.finishWorkflow({ actor: "mcp:test", summary: "captured", success: true });
+
+ const second = await memory.startWorkflow({ actor: "mcp:test", intent: "kirim screenshot desktop macos mso", project: "mso" });
+ await memory.recordWorkflowStep("mcp:test", second.workflow.id, {
+ id: "b", tool: "screen_capture", state: "completed", args: { shell: "macos", width: 1440, height: 900 },
+ durationMs: 1800, ts: new Date().toISOString(),
+ });
+ const done = await memory.finishWorkflow({ actor: "mcp:test", summary: "captured with explicit dimensions", success: true });
+ expect(done.recipe.fastestDurationMs).toBe(1000);
+ expect(done.recipe.bestSteps[0].durationMs).toBe(1000);
+ expect(done.recipe.bestSteps[0].args).toEqual({ shell: "macos", width: 1440, height: 900 });
+ });
+
+ it("stores redacted command shape rather than credential payloads", async () => {
+ const started = await memory.startWorkflow({ actor: "mcp:test", intent: "run a scoped deployment command with token=top-secret" });
+ expect(started.workflow.intent).not.toContain("top-secret");
+ await memory.recordWorkflowStep("mcp:test", started.workflow.id, {
+ id: "x", tool: "exec_run", state: "completed", durationMs: 20,
+ target: "TOKEN=super-secret npm run build && curl https://x.test?a=1&token=abc",
+ args: { command: "TOKEN=super-secret npm run build && curl https://x.test?a=1&token=abc", cwd: "/home/test/project", extra: "must-not-persist" },
+ ts: new Date().toISOString(),
+ });
+ const done = await memory.finishWorkflow({ actor: "mcp:test", summary: "verified", success: true });
+ const stored = JSON.stringify(done.recipe.bestSteps);
+ expect(stored).not.toContain("super-secret");
+ expect(stored).not.toContain("token=abc");
+ expect(stored).not.toContain("must-not-persist");
+ expect(done.recipe.bestSteps[0].args).toMatchObject({ cwd: "/home/test/project" });
+ });
+
+ it("keeps replayable allowlisted args but never write bodies", async () => {
+ const started = await memory.startWorkflow({ actor: "mcp:test", intent: "write a project note" });
+ await memory.recordWorkflowStep("mcp:test", started.workflow.id, {
+ id: "w", tool: "fs_write", state: "completed", target: "/tmp/note.md",
+ args: { path: "/tmp/note.md", content: "private body", mode: "unsafe" }, durationMs: 10, ts: new Date().toISOString(),
+ });
+ const done = await memory.finishWorkflow({ actor: "mcp:test", summary: "note verified", success: true });
+ expect(done.recipe.bestSteps[0].args).toEqual({ path: "/tmp/note.md" });
+ expect(JSON.stringify(done.recipe)).not.toContain("private body");
+ });
+});
diff --git a/lib/skills/memory.ts b/lib/skills/memory.ts
new file mode 100644
index 00000000..6fda6563
--- /dev/null
+++ b/lib/skills/memory.ts
@@ -0,0 +1,387 @@
+/* eslint-disable max-lines -- the atomic store, redaction policy and recipe merge must evolve together; splitting them would expose partially-safe persistence helpers. */
+import { randomUUID } from "crypto";
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+import { embedSkillText, hybridSemanticScore, normalizeSemanticText, SKILL_EMBEDDING_VERSION } from "./semantic";
+
+export type WorkflowStepState = "completed" | "failed" | "denied" | "rate_limited";
+
+export type WorkflowStep = {
+ id: string;
+ tool: string;
+ state: WorkflowStepState;
+ target?: string;
+ /** Replayable, explicitly allowlisted scalar arguments. Never raw payloads. */
+ args?: Record<string, string | number | boolean>;
+ durationMs?: number;
+ ts: string;
+};
+
+type WorkflowStepInput = Omit<WorkflowStep, "args"> & { args?: Record<string, unknown> };
+
+export type ActiveWorkflow = {
+ id: string;
+ actor: string;
+ intent: string;
+ project?: string;
+ constraints?: string;
+ startedAt: string;
+ steps: WorkflowStep[];
+};
+
+export type LearnedRecipe = {
+ id: string;
+ intent: string;
+ normalizedIntent: string;
+ project?: string;
+ summary: string;
+ embeddingVersion: string;
+ embedding: number[];
+ bestSteps: WorkflowStep[];
+ lastSteps: WorkflowStep[];
+ attempts: number;
+ successes: number;
+ failures: number;
+ averageDurationMs: number;
+ fastestDurationMs?: number;
+ lastDurationMs: number;
+ averageWallDurationMs: number;
+ lastWallDurationMs: number;
+ createdAt: string;
+ updatedAt: string;
+ lastUsedAt?: string;
+};
+
+type SkillMemoryStore = {
+ version: 1;
+ active: Record<string, ActiveWorkflow>;
+ recipes: Record<string, LearnedRecipe>;
+};
+
+export type FinishWorkflowResult = {
+ workflow: ActiveWorkflow;
+ recipe: LearnedRecipe;
+ currentDurationMs: number;
+ previousFastestMs?: number;
+ improvedByMs?: number;
+ improvedPct?: number;
+};
+
+const EMPTY = (): SkillMemoryStore => ({ version: 1, active: {}, recipes: {} });
+let cache: SkillMemoryStore | null = null;
+let cachePath = "";
+let writeChain: Promise<unknown> = Promise.resolve();
+
+function storePath(): string {
+ const env = process.env.OS_SKILL_MEMORY_STORE?.trim();
+ if (process.env.VITEST && !env) return path.join(os.tmpdir(), `mso-skill-memory-test-${process.pid}.json`);
+ return (env || path.join(os.homedir(), ".mso", "skill-memory.json")).replace(/^~(?=$|\/)/, os.homedir());
+}
+
+async function loadStore(): Promise<SkillMemoryStore> {
+ const file = storePath();
+ if (cache && cachePath === file) return cache;
+ let raw: string;
+ try {
+ raw = await fs.readFile(file, "utf8");
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code === "ENOENT") {
+ cache = EMPTY();
+ cachePath = file;
+ return cache;
+ }
+ throw e;
+ }
+ const parsed = JSON.parse(raw) as Partial<SkillMemoryStore>;
+ cache = {
+ version: 1,
+ active: parsed.active && typeof parsed.active === "object" ? parsed.active : {},
+ recipes: parsed.recipes && typeof parsed.recipes === "object" ? parsed.recipes : {},
+ };
+ cachePath = file;
+ return cache;
+}
+
+async function persist(store: SkillMemoryStore): Promise<void> {
+ const file = storePath();
+ const snapshot = JSON.stringify(store, null, 2);
+ const run = writeChain.then(async () => {
+ await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+ const tmp = `${file}.tmp`;
+ await fs.writeFile(tmp, snapshot, { encoding: "utf8", mode: 0o600 });
+ await fs.rename(tmp, file);
+ });
+ writeChain = run.catch(() => undefined);
+ await run;
+}
+
+function actorKey(actor?: string): string {
+ if (!actor) throw new Error("workflow memory needs an authenticated MCP actor");
+ return actor;
+}
+
+function safeMemoryText(value: string, max: number): string {
+ const out = value
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .replace(/\b[a-f0-9]{48,}\b/gi, "[opaque-id]")
+ .trim();
+ return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+function safeTarget(tool: string, target?: string): string | undefined {
+ if (!target) return undefined;
+ let out = target
+ .replace(/([?&](?:token|key|secret|password|code)=)[^&\s]+/gi, "$1[redacted]")
+ .replace(/\b(?:bearer\s+)?(?:sk|pk|ghp|mso_mcp)_[a-z0-9_-]{8,}\b/gi, "[redacted]")
+ .replace(/\b(password|token|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[redacted]");
+ if (tool === "exec_run") {
+ // Keep the command shape, not every argument. Quoted payloads and long opaque
+ // values are where credentials most often hide.
+ out = out
+ .replace(/(['"])[\s\S]*?\1/g, "[value]")
+ .replace(/\b[a-f0-9]{32,}\b/gi, "[id]")
+ .split(/\s+/)
+ .slice(0, 12)
+ .join(" ");
+ }
+ out = out.replace(new RegExp(`^${os.homedir().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`), "~");
+ return out.length > 160 ? `${out.slice(0, 160)}…` : out;
+}
+
+const SAFE_TOOL_ARGS: Record<string, readonly string[]> = {
+ fs_list: ["path", "includeHidden"],
+ fs_read: ["path"],
+ fs_search: ["query", "root"],
+ fs_usage: ["path"],
+ apps_logs: ["id"],
+ screen_capture: ["shell", "width", "height"],
+ fs_write: ["path"], // content is intentionally impossible to persist
+ fs_mkdir: ["path"],
+ fs_move: ["from", "to"],
+ fs_copy: ["from", "to"],
+ fs_delete: ["path"],
+ apps_power: ["id", "action"],
+ exec_run: ["command", "cwd"],
+ browser_power: ["on"],
+};
+
+function safeArgs(tool: string, args?: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
+ if (!args) return undefined;
+ const keys = SAFE_TOOL_ARGS[tool];
+ if (!keys) return undefined;
+ const out: Record<string, string | number | boolean> = {};
+ for (const key of keys) {
+ const value = args[key];
+ if (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))) out[key] = value;
+ else if (typeof value === "string" && value) {
+ const safe = key === "command" ? safeTarget("exec_run", value) : safeMemoryText(value, 240);
+ if (safe) out[key] = safe;
+ }
+ }
+ return Object.keys(out).length ? out : undefined;
+}
+
+function enrichBestSteps(best: WorkflowStep[], current: WorkflowStep[]): WorkflowStep[] {
+ if (best.length !== current.length || best.some((step, i) => step.tool !== current[i]?.tool)) return best;
+ return best.map((step, i) => ({
+ ...step,
+ args: step.args ?? current[i]?.args,
+ target: step.target ?? current[i]?.target,
+ }));
+}
+
+function elapsedMs(steps: WorkflowStep[], wallMs: number): number {
+ const sum = steps.reduce((n, s) => n + (s.durationMs ?? 0), 0);
+ return sum > 0 ? sum : wallMs;
+}
+
+function recipeText(intent: string, project?: string, summary?: string): string {
+ return [intent, project, summary].filter(Boolean).join("\n");
+}
+
+function closestRecipe(store: SkillMemoryStore, intent: string, project?: string): LearnedRecipe | undefined {
+ let best: { recipe: LearnedRecipe; score: number } | undefined;
+ for (const recipe of Object.values(store.recipes)) {
+ const semantic = hybridSemanticScore(recipeText(intent, project), recipeText(recipe.intent, recipe.project));
+ const exact = recipe.normalizedIntent === normalizeSemanticText(intent) ? 0.2 : 0;
+ const projectBonus = project && recipe.project && normalizeSemanticText(project) === normalizeSemanticText(recipe.project) ? 0.08 : 0;
+ const score = semantic + exact + projectBonus;
+ if (!best || score > best.score) best = { recipe, score };
+ }
+ return best && best.score >= 0.48 ? best.recipe : undefined;
+}
+
+export async function startWorkflow(input: {
+ actor?: string;
+ intent: string;
+ project?: string;
+ constraints?: string;
+}): Promise<{ workflow: ActiveWorkflow; replacedWorkflowId?: string }> {
+ const actor = actorKey(input.actor);
+ const intent = safeMemoryText(input.intent, 1000);
+ if (!intent) throw new Error("intent must be a non-empty string");
+ const store = await loadStore();
+ const replacedWorkflowId = store.active[actor]?.id;
+ const workflow: ActiveWorkflow = {
+ id: randomUUID(),
+ actor,
+ intent,
+ project: input.project ? safeMemoryText(input.project, 240) || undefined : undefined,
+ constraints: input.constraints ? safeMemoryText(input.constraints, 500) || undefined : undefined,
+ startedAt: new Date().toISOString(),
+ steps: [],
+ };
+ store.active[actor] = workflow;
+ await persist(store);
+ return { workflow, ...(replacedWorkflowId ? { replacedWorkflowId } : {}) };
+}
+
+export async function activeWorkflowForActor(actor?: string): Promise<ActiveWorkflow | null> {
+ if (!actor) return null;
+ const store = await loadStore();
+ const workflow = store.active[actor];
+ if (!workflow) return null;
+ // Ignore abandoned sessions after six hours. The next workflow_start replaces it.
+ if (Date.now() - new Date(workflow.startedAt).getTime() > 6 * 60 * 60_000) return null;
+ return workflow;
+}
+
+export async function recordWorkflowStep(actor: string | undefined, workflowId: string | undefined, step: WorkflowStepInput): Promise<void> {
+ if (!actor || !workflowId) return;
+ const store = await loadStore();
+ const workflow = store.active[actor];
+ if (!workflow || workflow.id !== workflowId) return;
+ if (["skills_search", "workflow_start", "workflow_finish"].includes(step.tool)) return;
+ workflow.steps.push({
+ ...step,
+ target: safeTarget(step.tool, step.target),
+ args: safeArgs(step.tool, step.args),
+ });
+ // A runaway client must not grow one JSON document forever.
+ if (workflow.steps.length > 300) workflow.steps.splice(0, workflow.steps.length - 300);
+ await persist(store);
+}
+
+export async function finishWorkflow(input: {
+ actor?: string;
+ workflowId?: string;
+ summary: string;
+ success: boolean;
+}): Promise<FinishWorkflowResult> {
+ const actor = actorKey(input.actor);
+ const store = await loadStore();
+ const workflow = store.active[actor];
+ if (!workflow) throw new Error("no active workflow for this MCP client — call workflow_start first");
+ if (input.workflowId && input.workflowId !== workflow.id) throw new Error("workflow_id does not match this client's active workflow");
+
+ const now = new Date();
+ const wallMs = Math.max(0, now.getTime() - new Date(workflow.startedAt).getTime());
+ const durationMs = elapsedMs(workflow.steps, wallMs);
+ const existing = closestRecipe(store, workflow.intent, workflow.project);
+ const previousFastestMs = existing?.fastestDurationMs;
+ const summary = safeMemoryText(input.summary, 1200) || (input.success ? "completed" : "failed");
+ const vector = embedSkillText(recipeText(workflow.intent, workflow.project, summary));
+ const timestamp = now.toISOString();
+
+ let recipe: LearnedRecipe;
+ if (existing) {
+ const attempts = existing.attempts + 1;
+ const successes = existing.successes + (input.success ? 1 : 0);
+ const failures = existing.failures + (input.success ? 0 : 1);
+ const faster = input.success && (existing.fastestDurationMs == null || durationMs < existing.fastestDurationMs);
+ recipe = {
+ ...existing,
+ intent: workflow.intent,
+ normalizedIntent: normalizeSemanticText(workflow.intent),
+ project: workflow.project,
+ summary,
+ embeddingVersion: SKILL_EMBEDDING_VERSION,
+ embedding: vector,
+ lastSteps: workflow.steps,
+ bestSteps: faster ? workflow.steps : (input.success ? enrichBestSteps(existing.bestSteps, workflow.steps) : existing.bestSteps),
+ attempts,
+ successes,
+ failures,
+ averageDurationMs: Math.round((existing.averageDurationMs * existing.attempts + durationMs) / attempts),
+ fastestDurationMs: input.success ? Math.min(existing.fastestDurationMs ?? durationMs, durationMs) : existing.fastestDurationMs,
+ lastDurationMs: durationMs,
+ averageWallDurationMs: Math.round((existing.averageWallDurationMs * existing.attempts + wallMs) / attempts),
+ lastWallDurationMs: wallMs,
+ updatedAt: timestamp,
+ };
+ } else {
+ recipe = {
+ id: randomUUID(),
+ intent: workflow.intent,
+ normalizedIntent: normalizeSemanticText(workflow.intent),
+ project: workflow.project,
+ summary,
+ embeddingVersion: SKILL_EMBEDDING_VERSION,
+ embedding: vector,
+ bestSteps: input.success ? workflow.steps : [],
+ lastSteps: workflow.steps,
+ attempts: 1,
+ successes: input.success ? 1 : 0,
+ failures: input.success ? 0 : 1,
+ averageDurationMs: durationMs,
+ fastestDurationMs: input.success ? durationMs : undefined,
+ lastDurationMs: durationMs,
+ averageWallDurationMs: wallMs,
+ lastWallDurationMs: wallMs,
+ createdAt: timestamp,
+ updatedAt: timestamp,
+ };
+ }
+
+ store.recipes[recipe.id] = recipe;
+ delete store.active[actor];
+ // Keep the memory bounded. Prefer recipes that worked and were used recently.
+ const recipes = Object.values(store.recipes);
+ if (recipes.length > 200) {
+ recipes
+ .sort((a, b) => {
+ const qa = a.successes * 10 - a.failures + new Date(a.lastUsedAt ?? a.updatedAt).getTime() / 1e13;
+ const qb = b.successes * 10 - b.failures + new Date(b.lastUsedAt ?? b.updatedAt).getTime() / 1e13;
+ return qa - qb;
+ })
+ .slice(0, recipes.length - 200)
+ .forEach((r) => delete store.recipes[r.id]);
+ }
+ await persist(store);
+
+ const improvedByMs = input.success && previousFastestMs != null && durationMs < previousFastestMs
+ ? previousFastestMs - durationMs
+ : undefined;
+ return {
+ workflow,
+ recipe,
+ currentDurationMs: durationMs,
+ ...(previousFastestMs != null ? { previousFastestMs } : {}),
+ ...(improvedByMs != null
+ ? { improvedByMs, improvedPct: Math.round((improvedByMs / previousFastestMs!) * 1000) / 10 }
+ : {}),
+ };
+}
+
+export async function listLearnedRecipes(): Promise<LearnedRecipe[]> {
+ const store = await loadStore();
+ return Object.values(store.recipes).sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+}
+
+export async function markRecipeUsed(id: string): Promise<void> {
+ const store = await loadStore();
+ const recipe = store.recipes[id];
+ if (!recipe) return;
+ recipe.lastUsedAt = new Date().toISOString();
+ await persist(store);
+}
+
+/** Test-only cache reset; harmless in production and avoids module-reset tricks. */
+export function resetSkillMemoryCache(): void {
+ cache = null;
+ cachePath = "";
+ writeChain = Promise.resolve();
+}
diff --git a/lib/skills/search.ts b/lib/skills/search.ts
new file mode 100644
index 00000000..b00d10d3
--- /dev/null
+++ b/lib/skills/search.ts
@@ -0,0 +1,131 @@
+import { catalogSkills, readSkillFile, type SkillInfo } from "./catalog";
+import { listLearnedRecipes, type LearnedRecipe } from "./memory";
+import { embedSkillText, hybridSemanticScore, SKILL_EMBEDDING_VERSION } from "./semantic";
+
+export type SkillSearchToolDoc = {
+ name: string;
+ description: string;
+ scope: string;
+ inputSchema?: { properties?: Record<string, unknown> };
+};
+
+export type SkillSearchHit = {
+ kind: "recipe" | "skill" | "tool";
+ id: string;
+ name: string;
+ score: number;
+ description: string;
+ source?: string;
+ trust?: string;
+ scope?: string;
+ successRate?: number;
+ fastestDurationMs?: number;
+ attempts?: number;
+ steps?: Array<{ tool: string; target?: string; args?: Record<string, string | number | boolean>; durationMs?: number }>;
+ missingTools?: string[];
+};
+
+export type SkillSearchOptions = {
+ topK?: number;
+ includeUntrusted?: boolean;
+ toolDocs?: SkillSearchToolDoc[];
+ appDir?: string;
+ homeDir?: string;
+};
+
+function skillQuality(skill: SkillInfo): number {
+ if (skill.trust === "official") return 0.09;
+ if (skill.trust === "verified") return 0.07;
+ if (skill.trust === "local") return 0.08;
+ return -0.12;
+}
+
+function recipeQuality(recipe: LearnedRecipe): number {
+ const successRate = recipe.attempts ? recipe.successes / recipe.attempts : 0;
+ const evidence = Math.min(recipe.attempts, 6) / 6;
+ return successRate * 0.13 + evidence * 0.05 + (recipe.successes > 0 ? 0.02 : 0);
+}
+
+export async function searchSkillMemory(query: string, options: SkillSearchOptions = {}): Promise<{
+ engine: string;
+ query: string;
+ hits: SkillSearchHit[];
+ recommendedRecipe?: SkillSearchHit;
+}> {
+ const q = query.trim();
+ if (!q) throw new Error("query must be a non-empty string");
+ const topK = Math.min(Math.max(Math.round(options.topK ?? 8), 1), 20);
+ const hits: SkillSearchHit[] = [];
+ const availableTools = options.toolDocs?.length ? new Set(options.toolDocs.map((t) => t.name)) : null;
+
+ const recipes = await listLearnedRecipes();
+ for (const recipe of recipes) {
+ const text = [
+ recipe.intent,
+ recipe.project,
+ recipe.summary,
+ recipe.bestSteps.map((s) => `${s.tool} ${s.target ?? ""}`).join(" "),
+ ].filter(Boolean).join("\n");
+ const raw = hybridSemanticScore(q, text, recipe.embeddingVersion === SKILL_EMBEDDING_VERSION ? recipe.embedding : embedSkillText(text));
+ const missingTools = availableTools
+ ? [...new Set(recipe.bestSteps.map((s) => s.tool).filter((tool) => !availableTools.has(tool)))]
+ : [];
+ hits.push({
+ kind: "recipe",
+ id: recipe.id,
+ name: recipe.intent,
+ score: Math.max(0, Math.min(1, raw + recipeQuality(recipe) - missingTools.length * 0.15)),
+ description: recipe.summary,
+ source: "learned",
+ trust: "local",
+ successRate: recipe.attempts ? Math.round((recipe.successes / recipe.attempts) * 1000) / 10 : 0,
+ fastestDurationMs: recipe.fastestDurationMs,
+ attempts: recipe.attempts,
+ steps: recipe.bestSteps.map((s) => ({ tool: s.tool, target: s.target, args: s.args, durationMs: s.durationMs })),
+ ...(missingTools.length ? { missingTools } : {}),
+ });
+ }
+
+ const skills = await catalogSkills({ appDir: options.appDir, homeDir: options.homeDir });
+ for (const skill of skills) {
+ if (!options.includeUntrusted && skill.trust === "untrusted") continue;
+ const content = skill.trust === "untrusted" ? "" : (await readSkillFile(skill.path))?.slice(0, 18_000) ?? "";
+ const text = `${skill.name}\n${skill.description}\n${content}`;
+ hits.push({
+ kind: "skill",
+ id: skill.name,
+ name: skill.name,
+ score: Math.max(0, Math.min(1, hybridSemanticScore(q, text) + skillQuality(skill))),
+ description: skill.description,
+ source: skill.source,
+ trust: skill.trust,
+ });
+ }
+
+ for (const tool of options.toolDocs ?? []) {
+ const params = Object.keys(tool.inputSchema?.properties ?? {}).join(" ");
+ const text = `${tool.name}\n${tool.description}\n${params}`;
+ hits.push({
+ kind: "tool",
+ id: tool.name,
+ name: tool.name,
+ score: Math.min(1, hybridSemanticScore(q, text) + 0.055),
+ description: tool.description,
+ source: "mcp",
+ trust: "official",
+ scope: tool.scope,
+ });
+ }
+
+ const sorted = hits
+ .filter((h) => h.score >= 0.04)
+ .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+ .slice(0, topK)
+ .map((h) => ({ ...h, score: Math.round(h.score * 1000) / 1000 }));
+ return {
+ engine: SKILL_EMBEDDING_VERSION,
+ query: q,
+ hits: sorted,
+ recommendedRecipe: sorted.find((h) => h.kind === "recipe" && h.score >= 0.22),
+ };
+}
diff --git a/lib/skills/semantic.test.ts b/lib/skills/semantic.test.ts
new file mode 100644
index 00000000..b69a213d
--- /dev/null
+++ b/lib/skills/semantic.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { hybridSemanticScore } from "./semantic";
+
+describe("local skill embeddings", () => {
+ it("routes Indonesian screenshot language to screen capture", () => {
+ const query = "kirim tangkapan layar macOS dan link download sementara";
+ const screenshot = hybridSemanticScore(query, "screen_capture Capture the authenticated MSO desktop and return a temporary preview download link");
+ const disk = hybridSemanticScore(query, "fs_usage Show total used and free disk bytes");
+ expect(screenshot).toBeGreaterThan(disk + 0.2);
+ });
+
+ it("connects workflow/recipe phrasing across Indonesian and English", () => {
+ const score = hybridSemanticScore("ingat cara tercepat agar task berikutnya lebih cepat", "workflow recipe skill memory fastest successful path");
+ expect(score).toBeGreaterThan(0.25);
+ });
+});
diff --git a/lib/skills/semantic.ts b/lib/skills/semantic.ts
new file mode 100644
index 00000000..b94df54f
--- /dev/null
+++ b/lib/skills/semantic.ts
@@ -0,0 +1,112 @@
+/**
+ * Small, deterministic semantic vectors for the local skill/recipe index.
+ *
+ * This is deliberately local: no API key, network call, model download or token
+ * cost. Word features, bilingual aliases and character n-grams are feature-hashed
+ * into a compact normalized vector. It is not a frontier embedding model, but it
+ * is fast, typo-tolerant and good enough to route an intent to a few dozen MSO
+ * tools/skills/recipes. The version is persisted with learned recipes so a future
+ * encoder can re-index them safely.
+ */
+export const SKILL_EMBEDDING_VERSION = "mso-local-hybrid-v1";
+export const SKILL_EMBEDDING_DIM = 384;
+
+const STOP = new Set([
+ "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "how", "i", "in", "is", "it", "of", "on", "or", "that", "the", "this", "to", "with",
+ "aku", "akan", "apa", "agar", "bisa", "buat", "dan", "dari", "di", "ini", "itu", "ke", "kita", "mau", "saya", "sekarang", "tolong", "untuk", "yang",
+]);
+
+const ALIASES: Array<[RegExp, string]> = [
+ [/\b(screen ?shot|screen capture|capture screen|tangkapan layar|gambar progress|kirim gambar)\b/g, "screen_capture visual_progress"],
+ [/\b(deploy|deployment|rebuild|build ulang|restart production|push main|rilis)\b/g, "deploy_release"],
+ [/\b(icon|ikon|logo|webp|transparent|transparan|no bg|background)\b/g, "image_asset icon_artwork"],
+ [/\b(activity|aktivitas|log activity|audit trail|sedang ngapain|progress log)\b/g, "activity_observability"],
+ [/\b(skill|skills|recipe|resep|workflow|playbook|cara tercepat|best path|memory)\b/g, "skill_memory workflow_recipe"],
+ [/\b(vps|server|cpu|ram|memory|disk|uptime|process)\b/g, "server_health"],
+ [/\b(camoufox|browser|firefox|vnc)\b/g, "camoufox_browser"],
+ [/\b(hermes)\b/g, "hermes_agent"],
+ [/\b(openclaw|open claw|lobster)\b/g, "openclaw_agent"],
+ [/\b(file|files|folder|directory|path|berkas|direktori)\b/g, "filesystem"],
+ [/\b(delete|hapus|remove|rm)\b/g, "destructive_delete"],
+ [/\b(test|tests|testing|verify|verification|cek|check)\b/g, "verify_test"],
+];
+
+export function normalizeSemanticText(text: string): string {
+ let out = text
+ .normalize("NFKD")
+ .replace(/[\u0300-\u036f]/g, "")
+ .toLowerCase()
+ .replace(/https?:\/\/\S+/g, " url ")
+ .replace(/[^a-z0-9_./-]+/g, " ")
+ .replace(/\s+/g, " ")
+ .trim();
+ for (const [re, alias] of ALIASES) out = out.replace(re, (m) => `${m} ${alias}`);
+ return out;
+}
+
+function hash32(value: string): number {
+ let h = 0x811c9dc5;
+ for (let i = 0; i < value.length; i += 1) {
+ h ^= value.charCodeAt(i);
+ h = Math.imul(h, 0x01000193);
+ }
+ return h >>> 0;
+}
+
+function add(vec: number[], feature: string, weight: number): void {
+ const h = hash32(feature);
+ const index = h % vec.length;
+ const sign = (h & 0x80000000) === 0 ? 1 : -1;
+ vec[index] += sign * weight;
+}
+
+function terms(text: string): string[] {
+ return normalizeSemanticText(text)
+ .split(" ")
+ .map((v) => v.trim())
+ .filter((v) => v.length > 1 && !STOP.has(v));
+}
+
+export function embedSkillText(text: string): number[] {
+ const vec = Array<number>(SKILL_EMBEDDING_DIM).fill(0);
+ const xs = terms(text);
+ for (let i = 0; i < xs.length; i += 1) {
+ const token = xs[i];
+ add(vec, `w:${token}`, token.includes("_") ? 2.2 : 1);
+ if (i > 0) add(vec, `b:${xs[i - 1]}_${token}`, 1.25);
+ const compact = token.replace(/[^a-z0-9_]/g, "");
+ for (const n of [3, 4]) {
+ if (compact.length < n) continue;
+ for (let j = 0; j <= compact.length - n; j += 1) add(vec, `c${n}:${compact.slice(j, j + n)}`, 0.18);
+ }
+ }
+ let norm = 0;
+ for (const v of vec) norm += v * v;
+ norm = Math.sqrt(norm);
+ if (norm > 0) for (let i = 0; i < vec.length; i += 1) vec[i] /= norm;
+ return vec;
+}
+
+export function cosineSimilarity(a: number[], b: number[]): number {
+ const n = Math.min(a.length, b.length);
+ let dot = 0;
+ for (let i = 0; i < n; i += 1) dot += a[i] * b[i];
+ return Math.max(-1, Math.min(1, dot));
+}
+
+export function lexicalSimilarity(a: string, b: string): number {
+ const aa = new Set(terms(a));
+ const bb = new Set(terms(b));
+ if (!aa.size || !bb.size) return 0;
+ let overlap = 0;
+ for (const t of aa) if (bb.has(t)) overlap += 1;
+ return overlap / Math.sqrt(aa.size * bb.size);
+}
+
+export function hybridSemanticScore(query: string, text: string, vector?: number[]): number {
+ const qv = embedSkillText(query);
+ const dv = vector ?? embedSkillText(text);
+ const cosine = Math.max(0, cosineSimilarity(qv, dv));
+ const lexical = lexicalSimilarity(query, text);
+ return Math.max(0, Math.min(1, cosine * 0.74 + lexical * 0.26));
+}
diff --git a/skills/README.md b/skills/README.md
index 5cdc5c03..681be486 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -22,3 +22,19 @@ Skill roots are intentionally read outside the normal filesystem jail, because a
## Bundled third-party skill
`camoufox-browse` comes from ClawHub (`zenaufa`, installed version 1.0.7). Its `.clawhub/origin.json` records the artifact and skill hashes. Do not edit its `SKILL.md` in place: a modification intentionally invalidates verification. Put MSO-specific policy in an official wrapper skill instead.
+
+## Semantic search and learned recipes
+
+The catalog is indexed together with the live MCP tool schemas and successful
+workflow recipes. `skills_search` / `skills.search` and `GET /api/skills?q=...` use
+the local `mso-local-hybrid-v1` encoder, so searches work across English, Indonesian
+and minor typos without a cloud embedding API. Untrusted skill instructions remain
+excluded by default.
+
+A multi-step MCP client can bracket work with `workflow_start` and
+`workflow_finish`. MSO records only redacted terminal tool steps, explicitly allowlisted scalar
+arguments, timings and the verified outcome in `~/.mso/skill-memory.json`, merges semantically equivalent
+intents, and retains the fastest successful sequence as a future recipe. Failed
+attempts remain evidence but never replace a successful path. Recipes are ranked
+with trust, semantic relevance, observed success rate, speed and current tool
+availability; they are suggestions, not permission to skip scope or approval gates.