hoomanjs 1.0.0

package/src/core/prompts/static/memory.md

@@ -0,0 +1,39 @@
+## Memory
+
+You have access to long-term memory tools.
+
+### Retrieval (search_memory)
+
+- Use memory when the current request may depend on past interactions, preferences, or ongoing tasks
+- Especially use it for:
+  - follow-ups ("last time", "previously", "continue")
+  - user-specific preferences or history
+  - long-running tasks or projects
+- Do NOT search memory for simple, self-contained questions
+
+### Storage (store_memory)
+
+- Only store information that is:
+  - reusable across conversations
+  - specific to the user (preferences, facts, goals, tasks)
+- Good examples:
+  - "User prefers TypeScript"
+  - "User is building a CV SaaS"
+- Do NOT store:
+  - one-off questions
+  - temporary context
+  - obvious or generic information
+
+### Updates (update_memory)
+
+- If new information corrects or refines an existing memory, update it instead of creating a new one
+
+### Archival (archive_memory)
+
+- If a memory becomes irrelevant, outdated, or incorrect, archive it instead of deleting
+
+### General Rules
+
+- Avoid redundant or duplicate memory
+- Keep memory concise and compressed
+- Prioritize current context over memory if they conflict

package/src/core/prompts/static/shell.md

@@ -0,0 +1,34 @@
+## Shell
+
+You have access to a `shell` tool for local command execution.
+
+### When To Use It
+
+- Use `shell` when executing a local command is the most direct or reliable way to inspect, verify, or operate on the environment
+- Especially use it for:
+  - running project scripts, builds, tests, and CLIs
+  - checking system or repository state
+  - executing multiple related shell commands in sequence
+  - gathering output that is easier to obtain from the command line than from reasoning alone
+- Do NOT use `shell` when the answer can be given directly without execution
+- Do NOT use `shell` for destructive or risky commands unless they are clearly necessary and appropriate
+
+### How To Use It
+
+- Prefer the smallest command that answers the question
+- Use `work_dir` when the command should run in a specific directory
+- Use sequential commands for dependent steps
+- Use `parallel` only for independent commands
+- Set sensible timeouts for commands that may hang or run for a long time
+- Use `ignore_errors` only when partial success is acceptable
+
+### Safety
+
+- Avoid commands that delete, overwrite, or broadly modify files unless required
+- Prefer inspection and verification before making changes
+- Be careful with package managers, process control, and commands that affect the wider system
+
+### Goal
+
+- Use the shell to improve accuracy and efficiency
+- Keep command usage targeted, minimal, and relevant to the task

package/src/core/prompts/static/skills.md

@@ -0,0 +1,19 @@
+## Skills
+
+You may have **skills management tools** (install, list, search, delete) and a dynamic **Available skills** section elsewhere in the system prompt listing installed skills (title from the skills CLI) with absolute paths to each `SKILL.md`.
+
+### When to use a skill during this turn
+
+- When the user's goal, stack, or workflow clearly matches a listed skill (same product, API, or task family), treat that skill as the preferred playbook before improvising.
+- When you are unsure but a skill's title plausibly fits the task, open its `SKILL.md` using the **absolute path** from the Available skills list and skim it; if it helps, follow it for the rest of the turn.
+- Prefer **reading** `SKILL.md` over guessing conventions (naming, CLI flags, safety steps) that the skill is meant to encode.
+- Do **not** load or follow skills that are unrelated to the current request, and do not treat the catalog listing as mandatory background reading for every reply.
+
+### Coordination with tools
+
+- Use **filesystem** tools to read `SKILL.md` at the given path when you need full instructions.
+- Use **skills management** tools when the user wants to discover, install, or remove skills from the public catalog or local sources—not for ordinary coding that does not involve skills.
+
+### Goal
+
+Apply skills **selectively**: improve quality and consistency when a skill applies, and avoid extra I/O or scope when none do.

package/src/core/prompts/static/thinking.md

@@ -0,0 +1,27 @@
+## Thinking
+
+You have access to a `think` tool for structured multi-step reasoning.
+
+### When To Use It
+
+- Use `think` when the task is complex, ambiguous, or likely benefits from deliberate multi-step planning
+- Especially use it for:
+  - designing or comparing implementation approaches
+  - debugging non-obvious failures
+  - breaking down large tasks into clear steps
+  - revising an earlier conclusion after new evidence appears
+  - exploring alternative branches before committing to a solution
+- Do NOT use `think` for simple, direct, or single-step requests
+
+### How To Use It
+
+- Start with a reasonable estimate for `totalThoughts`
+- Set `nextThoughtNeeded` to `true` while analysis is still in progress
+- Use revision fields when reconsidering earlier reasoning
+- Use branch fields when exploring alternative approaches
+- Only set `nextThoughtNeeded` to `false` when you have reached a satisfactory conclusion
+
+### Goal
+
+- Use the tool to improve reasoning quality, not to create unnecessary overhead
+- Prefer concise, useful thought steps over verbose internal narration

package/src/core/prompts/system.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "handlebars";
+import type { Config } from "../config.ts";
+import type { Toolkit } from "../toolkit.ts";
+import { toolkitAtLeast } from "../toolkit.ts";
+
+/** Bundled markdown next to this module (`prompts/static/`). */
+const STATIC_PROMPT_FILES = [
+  "identity.md",
+  "ltm.md",
+  "thinking.md",
+  "filesystem.md",
+  "fetch.md",
+  "shell.md",
+  "skills.md",
+] as const;
+
+const SECTION_BREAK = "\n\n---\n\n";
+
+/**
+ * Loads `prompts/static/*.md` from the package, then `instructions.md` from disk,
+ * concatenates them, and renders with Handlebars using `context`.
+ */
+export class System {
+  private readonly path: string;
+  private readonly config: Config;
+  private readonly toolkit: Toolkit;
+  private data = "";
+
+  public constructor(path: string, config: Config, toolkit: Toolkit) {
+    this.path = path;
+    this.config = config;
+    this.toolkit = toolkit;
+  }
+
+  private staticPromptFiles(): readonly (typeof STATIC_PROMPT_FILES)[number][] {
+    return STATIC_PROMPT_FILES.filter((file) => {
+      switch (file) {
+        case "ltm.md":
+          return this.config.ltm.enabled;
+        case "filesystem.md":
+        case "thinking.md":
+        case "shell.md":
+          return toolkitAtLeast(this.toolkit, "full");
+        case "skills.md":
+          return this.toolkit === "max";
+        default:
+          return true;
+      }
+    });
+  }
+
+  private readBundledStaticPrompts(): string {
+    const dir = join(dirname(fileURLToPath(import.meta.url)), "static");
+    const parts: string[] = [];
+    for (const file of this.staticPromptFiles()) {
+      const full = join(dir, file);
+      if (!existsSync(full)) {
+        continue;
+      }
+      const text = readFileSync(full, "utf8").trim();
+      if (text.length > 0) {
+        parts.push(text);
+      }
+    }
+    return parts.join("\n\n");
+  }
+
+  private readRawText(): string {
+    const instructions = existsSync(this.path)
+      ? readFileSync(this.path, "utf8").trim()
+      : "";
+    const bundled = this.readBundledStaticPrompts();
+
+    const blocks: string[] = [];
+    if (bundled.length > 0) {
+      blocks.push(bundled);
+    }
+    if (instructions.length > 0) {
+      blocks.push(instructions);
+    }
+    if (blocks.length === 0) {
+      return "";
+    }
+    return blocks.join(SECTION_BREAK);
+  }
+
+  get content(): string {
+    return this.data;
+  }
+
+  /** Plain object for Handlebars (`{{name}}`, `{{llm.model}}`, …). */
+  private context(): Record<string, unknown> {
+    return {
+      name: this.config.name,
+      llm: this.config.llm,
+      ltm: this.config.ltm,
+      compaction: this.config.compaction,
+    };
+  }
+
+  public async reload(): Promise<void> {
+    const raw = this.readRawText();
+    const template = compile(raw);
+    this.data = template(this.context()).trim();
+  }
+}

package/src/core/skills/index.ts

@@ -0,0 +1,2 @@
+export { Registry, create as createSkillsRegistry } from "./registry.ts";
+export { create as createSkillsTools } from "./tools.ts";

package/src/core/skills/registry.ts

@@ -0,0 +1,239 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile, rm } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import matter from "gray-matter";
+
+const execFileAsync = promisify(execFile);
+
+/** Vercel `skills` CLI package; uses latest every time. */
+const SKILLS_CLI = "skills@latest";
+/** Agent target for `skills add/list` — OpenClaw layout → `./skills/`. */
+const SKILLS_AGENT = "openclaw";
+const SKILLS_API_URL = "https://skills.sh";
+const NPX_BIN = process.platform === "win32" ? "npx.cmd" : "npx";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/**
+ * Parse name and description from a SKILL.md file's YAML frontmatter.
+ */
+function parseSkillFrontmatter(
+  content: string,
+  dirName: string,
+): { name: string; description?: string } {
+  try {
+    const { data } = matter(content);
+    const name =
+      typeof data?.name === "string" && data.name.trim()
+        ? data.name.trim()
+        : dirName;
+    const description =
+      typeof data?.description === "string" && data.description.trim()
+        ? data.description.trim()
+        : undefined;
+    return { name, description };
+  } catch {
+    return { name: dirName };
+  }
+}
+
+function stripAnsi(s: string): string {
+  return s.replace(ANSI_RE, "");
+}
+
+type SkillsListJsonRow = {
+  name: string;
+  path: string;
+  scope?: string;
+  agents?: string[];
+};
+
+export type SkillListEntry = {
+  /** Display title (skill `name` from SKILL.md) */
+  name: string;
+  /** Full description read using gray-matter */
+  description?: string;
+  /** Absolute path to the skill package root from `skills list --json`. */
+  path: string;
+};
+
+export interface SkillSearchResult {
+  name: string;
+  slug: string;
+  source: string;
+  installs: number;
+}
+
+async function runNpxSkills(
+  args: string[],
+  options: { cwd?: string; timeout?: number } = {},
+): Promise<{ stdout: string; stderr: string }> {
+  const { cwd, timeout = 300_000 } = options;
+  return execFileAsync(NPX_BIN, ["--yes", SKILLS_CLI, ...args], {
+    cwd,
+    maxBuffer: 20 * 1024 * 1024,
+    timeout,
+    env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0" },
+  });
+}
+
+/**
+ * Install / list / delete skills via the Vercel [`skills` CLI](https://github.com/vercel-labs/skills)
+ * (`npx skills`), using OpenClaw scope (`./skills/`).
+ */
+export class Registry {
+  private readonly cwd: string;
+
+  constructor(cwd: string) {
+    this.cwd = cwd;
+  }
+
+  async list(): Promise<SkillListEntry[]> {
+    let stdout: string;
+    try {
+      const r = await runNpxSkills(["list", "--json", "-a", SKILLS_AGENT], {
+        cwd: this.cwd,
+      });
+      stdout = r.stdout;
+    } catch (e) {
+      const err = e as { stderr?: string; message?: string };
+      const detail = err.stderr ?? err.message ?? String(e);
+      throw new Error(
+        `skills list failed. Is Node/npm available?\n${stripAnsi(detail)}`,
+      );
+    }
+    const text = stdout.trim();
+    if (!text) {
+      return [];
+    }
+    let rows: SkillsListJsonRow[];
+    try {
+      rows = JSON.parse(text) as SkillsListJsonRow[];
+    } catch {
+      throw new Error(
+        `Unexpected skills list output (expected JSON):\n${text.slice(0, 500)}`,
+      );
+    }
+    if (!Array.isArray(rows)) {
+      return [];
+    }
+    const entries: SkillListEntry[] = [];
+    for (const row of rows) {
+      try {
+        const folder = basename(row.path);
+        const root = isAbsolute(row.path)
+          ? resolve(row.path)
+          : resolve(this.cwd, row.path);
+        const md = resolve(join(root, "SKILL.md"));
+        const raw = await readFile(md, "utf-8");
+        const { name, description } = parseSkillFrontmatter(raw, folder);
+        entries.push({
+          name,
+          description,
+          path: md,
+        });
+      } catch {
+        continue;
+      }
+    }
+    return entries;
+  }
+
+  /**
+   * `skills add <source> -y -a openclaw --copy` — supports owner/repo, Git URLs with tree paths, local paths, etc.
+   */
+  async install(source: string): Promise<void> {
+    const raw = source.trim();
+    if (!raw) {
+      throw new Error(
+        "Enter a skill source (e.g. owner/repo or a GitHub URL).",
+      );
+    }
+    try {
+      await runNpxSkills(["add", raw, "-y", "-a", SKILLS_AGENT, "--copy"], {
+        cwd: this.cwd,
+        timeout: 600_000,
+      });
+    } catch (e) {
+      const err = e as { stderr?: string; stdout?: string; message?: string };
+      const detail = stripAnsi(
+        err.stderr || err.stdout || err.message || String(e),
+      );
+      throw new Error(`skills add failed:\n${detail}`);
+    }
+  }
+
+  /**
+   * Remove by on-disk folder name (basename of `path` from `skills list --json`).
+   *
+   * We do **not** pass `--agent` so removal matches the CLI’s universal layout behavior.
+   */
+  async delete(folder: string): Promise<void> {
+    const safe = folder.trim();
+    if (!safe || /[\\/]/.test(safe) || safe.includes("..")) {
+      throw new Error("Invalid skill name.");
+    }
+    try {
+      await runNpxSkills(["remove", safe, "-y"], { cwd: this.cwd });
+    } catch (e) {
+      const err = e as { stderr?: string; stdout?: string; message?: string };
+      const detail = stripAnsi(
+        err.stderr || err.stdout || err.message || String(e),
+      );
+      throw new Error(`skills remove failed:\n${detail}`);
+    }
+
+    await rm(join(this.cwd, "skills", safe), {
+      recursive: true,
+      force: true,
+    }).catch(() => {});
+  }
+
+  /**
+   * Search the public catalog at skills.sh (same API as the `skills` CLI `find` command).
+   */
+  async search(query: string): Promise<SkillSearchResult[]> {
+    const q = query.trim();
+    if (!q) {
+      throw new Error("Enter a search term for the skills catalog.");
+    }
+    if (q.length < 2) {
+      throw new Error("Use at least 2 characters to search.");
+    }
+    try {
+      const url = `${SKILLS_API_URL}/api/search?q=${encodeURIComponent(q)}&limit=10`;
+      const res = await fetch(url);
+      if (!res.ok) {
+        return [];
+      }
+      const data = (await res.json()) as {
+        skills: Array<{
+          id: string;
+          name: string;
+          installs: number;
+          source: string;
+        }>;
+      };
+
+      if (!Array.isArray(data.skills)) {
+        throw new Error("Skills search did not return .skills[] in response");
+      }
+
+      return data.skills
+        .map((skill) => ({
+          name: skill.name,
+          slug: skill.id,
+          source: skill.source || "",
+          installs: skill.installs,
+        }))
+        .sort((a, b) => (b.installs || 0) - (a.installs || 0));
+    } catch {
+      return [];
+    }
+  }
+}
+
+export function create(cwd: string) {
+  return new Registry(cwd);
+}

package/src/core/skills/tools.ts

@@ -0,0 +1,80 @@
+import { tool } from "@strands-agents/sdk";
+import type { JSONValue } from "@strands-agents/sdk";
+import { z } from "zod";
+import type { Registry } from "./registry.ts";
+
+function toJsonValue(value: unknown): JSONValue {
+  return JSON.parse(JSON.stringify(value)) as JSONValue;
+}
+
+export function create(registry: Registry) {
+  return [
+    tool({
+      name: "list_skills",
+      description:
+        "List currently installed skills available to the local agent.",
+      inputSchema: z.object({}),
+      callback: async () => {
+        const skills = await registry.list();
+        return toJsonValue({
+          count: skills.length,
+          skills,
+        });
+      },
+    }),
+    tool({
+      name: "search_skills",
+      description:
+        "Search the public skills catalog for skills matching a query.",
+      inputSchema: z.object({
+        query: z
+          .string()
+          .min(2)
+          .describe("Search query for the public skills catalog."),
+      }),
+      callback: async (input) => {
+        const results = await registry.search(input.query);
+        return toJsonValue({
+          count: results.length,
+          results,
+        });
+      },
+    }),
+    tool({
+      name: "install_skill",
+      description:
+        "Install a skill from a source such as owner/repo, a GitHub URL, or a local path.",
+      inputSchema: z.object({
+        source: z
+          .string()
+          .min(1)
+          .describe("Skill source to install (repo, URL, or local path)."),
+      }),
+      callback: async (input) => {
+        await registry.install(input.source);
+        return toJsonValue({
+          installed: true,
+          source: input.source,
+        });
+      },
+    }),
+    tool({
+      name: "delete_skill",
+      description:
+        "Delete an installed skill by its folder name under the local skills directory.",
+      inputSchema: z.object({
+        folder: z
+          .string()
+          .min(1)
+          .describe("Installed skill folder name to remove."),
+      }),
+      callback: async (input) => {
+        await registry.delete(input.folder);
+        return toJsonValue({
+          deleted: true,
+          folder: input.folder,
+        });
+      },
+    }),
+  ];
+}

package/src/core/toolkit.ts

@@ -0,0 +1,13 @@
+export const TOOLKITS = ["lite", "full", "max"] as const;
+
+export type Toolkit = (typeof TOOLKITS)[number];
+
+const TOOLKIT_RANK: Record<Toolkit, number> = {
+  lite: 0,
+  full: 1,
+  max: 2,
+};
+
+export function toolkitAtLeast(actual: Toolkit, minimum: Toolkit): boolean {
+  return TOOLKIT_RANK[actual] >= TOOLKIT_RANK[minimum];
+}