@matterailab/orbcode 0.2.2 → 0.2.3

package/dist/memory/loader.js

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * AGENTS.md memory loader.
+ *
+ * OrbCode's memory system mirrors Claude Code's CLAUDE.md discovery, but uses
+ * the open `AGENTS.md` filename (the cross-tool standard) instead of a
+ * vendor-specific name. Files are loaded in this order (lowest precedence
+ * first), with closer-to-cwd and higher-precedence types winning:
+ *
+ *   1. User memory:   ~/.orbcode/AGENTS.md
+ *   2. Project memory: AGENTS.md and .orbcode/AGENTS.md in cwd and every
+ *      parent directory (closer-to-cwd wins)
+ *   3. Local memory:   AGENTS.local.md in cwd and parents (highest precedence)
+ *
+ * Memory files support `@path` include directives (relative, `~/`, or
+ * absolute) to pull in other files. Includes are resolved recursively up to a
+ * small depth limit, with cycle detection.
+ */
+const MAX_INCLUDE_DEPTH = 5;
+const MAX_TOTAL_CHARS = 200_000;
+/** Read a file as UTF-8, returning undefined if it's missing or unreadable. */
+function readText(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve an @include path relative to the including file's directory. */
+function resolveInclude(ref, baseDir) {
+    if (ref.startsWith("~/"))
+        return path.join(os.homedir(), ref.slice(2));
+    if (path.isAbsolute(ref))
+        return ref;
+    return path.resolve(baseDir, ref);
+}
+/**
+ * Extract `@path` references from leaf text (not inside code spans/blocks).
+ * A simple, conservative parser: skips fenced code blocks and inline code.
+ */
+function extractIncludes(content, baseDir) {
+    const refs = [];
+    let inFence = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (/^```/.test(line.trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // Strip inline code spans before scanning for @refs.
+        const stripped = line.replace(/`[^`]*`/g, "");
+        const regex = /(?:^|\s)@((?:\.\/|~\/|\/)?[^\s]+)/g;
+        let match;
+        while ((match = regex.exec(stripped)) !== null) {
+            const ref = match[1].replace(/\\ /g, " ");
+            // Avoid matching emails, @mentions, etc.
+            if (!/^[A-Za-z0-9._~/-]/.test(ref))
+                continue;
+            refs.push(resolveInclude(ref, baseDir));
+        }
+    }
+    return refs;
+}
+/** Recursively load a memory file and all its @includes. */
+function loadWithIncludes(filePath, type, processed, depth) {
+    const real = safeRealpath(filePath);
+    if (processed.has(real) || depth >= MAX_INCLUDE_DEPTH)
+        return [];
+    const raw = readText(filePath);
+    if (raw === undefined)
+        return [];
+    processed.add(real);
+    const baseDir = path.dirname(filePath);
+    const includePaths = extractIncludes(raw, baseDir);
+    const results = [];
+    // Includes come first (so they appear before the including file's content).
+    for (const includePath of includePaths) {
+        results.push(...loadWithIncludes(includePath, type, processed, depth + 1));
+    }
+    results.push({ path: filePath, content: raw, type });
+    return results;
+}
+/** realpathSync that never throws (falls back to the input path). */
+function safeRealpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Walk from cwd up to root, collecting directories (root last). */
+function ancestorDirs(cwd) {
+    const dirs = [];
+    let current = path.resolve(cwd);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        dirs.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Load all AGENTS.md memory files, in precedence order (lowest first). The
+ * caller concatenates them in order so higher-precedence files appear last
+ * (and thus get more weight from the model).
+ */
+export function loadMemoryFiles(cwd = process.cwd()) {
+    const processed = new Set();
+    const files = [];
+    // 1. User memory (~/.orbcode/AGENTS.md)
+    files.push(...loadWithIncludes(path.join(getConfigDir(), "AGENTS.md"), "user", processed, 0));
+    // 2. Project memory (AGENTS.md + .orbcode/AGENTS.md), root -> cwd
+    for (const dir of ancestorDirs(cwd).reverse()) {
+        files.push(...loadWithIncludes(path.join(dir, "AGENTS.md"), "project", processed, 0));
+        files.push(...loadWithIncludes(path.join(dir, ".orbcode", "AGENTS.md"), "project", processed, 0));
+    }
+    // 3. Local memory (AGENTS.local.md), root -> cwd — highest precedence
+    for (const dir of ancestorDirs(cwd).reverse()) {
+        files.push(...loadWithIncludes(path.join(dir, "AGENTS.local.md"), "local", processed, 0));
+    }
+    return files;
+}
+/** Render the memory files into a single system-prompt section. */
+export function renderMemorySection(files) {
+    const valid = files.filter((f) => f.content.trim());
+    if (valid.length === 0)
+        return "";
+    const parts = [
+        "# Project & User Instructions (AGENTS.md)",
+        "",
+        "Instructions from AGENTS.md files are shown below. Adhere to these instructions; they override default behavior. Treat them as authoritative guidance from the user about this codebase.",
+        "",
+    ];
+    let total = 0;
+    for (const file of valid) {
+        if (total >= MAX_TOTAL_CHARS) {
+            parts.push("… (remaining memory files truncated to stay within context budget)");
+            break;
+        }
+        const label = labelFor(file);
+        parts.push(`## ${label}: \`${file.path}\``);
+        parts.push("");
+        parts.push(file.content.trim());
+        parts.push("");
+        total += file.content.length;
+    }
+    return parts.join("\n");
+}
+function labelFor(file) {
+    switch (file.type) {
+        case "user":
+            return "User memory";
+        case "project":
+            return "Project memory";
+        case "local":
+            return "Local memory";
+    }
+}

package/dist/memory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/prompts/system.js

@@ -1,5 +1,7 @@
 import * as os from "node:os";
 import { getShell } from "../utils/shell.js";
+import { renderMemorySection } from "../memory/loader.js";
+import { renderSkillCatalog } from "../skills/loader.js";
 // Role definition and tool guide ported verbatim from the Orbital extension
 // (agent mode roleDefinition + applyDiffToolDescription). Only the system
 // information section is adapted from the IDE to the CLI environment.
@@ -51,6 +53,18 @@ Bias towards not asking the user for help if you can find the answer yourself.
 
 Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form LINE_NUMBER|LINE_CONTENT. Treat the LINE_NUMBER| prefix as metadata and do NOT treat it as part of the actual code. LINE_NUMBER is right-aligned number padded with spaces to 6 characters.
 
+# Project & User Instructions (AGENTS.md)
+
+Your system prompt may include an "Project & User Instructions (AGENTS.md)" section. These are instructions from AGENTS.md files in the user's home directory, the project root, and parent directories. They contain project-specific guidance: build commands, code style, architecture notes, conventions. Treat them as authoritative instructions from the user about this codebase and follow them exactly. They override default behavior.
+
+# Skills
+
+Your system prompt may include an "Available Skills" section listing skills by name with a description and when-to-use hint. Skills are reusable instruction sets stored in ~/.orbcode/skills/ and .orbcode/skills/. When a task matches a skill's when-to-use condition, invoke the \`use_skill\` tool with the skill's name to load its full instructions, then follow them for the current task.
+
+# MCP Tools
+
+Tools whose names start with \`mcp__\` are provided by external MCP servers the user has configured. They work exactly like native tools — call them with the standard tool call format when the task requires their capabilities. Their descriptions and parameter schemas come from the MCP servers.
+
 CRITICAL: For any task, small or big, you will always and always use the update_todo_list tool to create the TODO list, always keep is upto date with updates to the status and updating/editing the list as needed.`;
 const toolGuide = `
 Common tool calls and explanations
@@ -373,11 +387,16 @@ function getSystemInfoSection(cwd) {
 
 The Current Workspace Directory is the directory the user launched OrbCode CLI from, and is therefore the default directory for all tool operations. Commands run in the current workspace directory unless a different cwd is passed; changing directories inside a command does not modify the workspace directory. When the user initially gives you a task, a listing of filepaths in the current workspace directory will be included in the Environment Details section. This provides an overview of the project's file structure, offering key insights into the project from directory/file names (how developers conceptualize and organize their code) and file extensions (the language used). This can also guide decision-making on which files to explore further. If you need to further explore directories such as outside the current workspace directory, you can use the list_files tool. If you pass 'true' for the recursive parameter, it will list files recursively. Otherwise, it will list files at the top level, which is better suited for generic directories where you don't necessarily need the nested structure, like the Desktop.`;
 }
-export function buildSystemPrompt(cwd) {
-    return `${roleDefinition}
-
-${toolGuide}
-
-${getSystemInfoSection(cwd)}
-`;
+export function buildSystemPrompt(cwd, options = {}) {
+    const memorySection = options.memoryFiles ? renderMemorySection(options.memoryFiles) : "";
+    const skillSection = options.skills ? renderSkillCatalog(options.skills) : "";
+    return [
+        roleDefinition,
+        toolGuide,
+        getSystemInfoSection(cwd),
+        memorySection,
+        skillSection,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
 }

package/dist/skills/loader.js

@@ -0,0 +1,132 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * Skill loader.
+ *
+ * Skills are markdown files that inject specialized instructions when the model
+ * invokes the `use_skill` tool. Discovery mirrors Claude Code's layout:
+ *
+ *   - User skills:   ~/.orbcode/skills/<name>/SKILL.md
+ *   - Project skills: .orbcode/skills/<name>/SKILL.md (in cwd and parents)
+ *
+ * Only the directory format (`<name>/SKILL.md`) is supported, matching Claude
+ * Code's current skills/ convention. Project skills override user skills on
+ * name collisions (closer-to-cwd wins).
+ */
+/** Parse a leading `---\n...---\n` YAML frontmatter block. */
+export function parseFrontmatter(raw) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!match)
+        return { frontmatter: {}, content: raw };
+    const [, yamlBlock, body] = match;
+    const frontmatter = {};
+    for (const line of yamlBlock.split(/\r?\n/)) {
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+        if (key)
+            frontmatter[key] = value;
+    }
+    return { frontmatter, content: body.trimStart() };
+}
+/** Extract a description from the first markdown paragraph if frontmatter lacks one. */
+function descriptionFromBody(content) {
+    const text = content
+        .replace(/^#+\s.*$/gm, "")
+        .replace(/```[\s\S]*?```/g, "")
+        .trim();
+    const firstPara = text.split(/\n\s*\n/)[0] ?? "";
+    return firstPara.replace(/\s+/g, " ").trim().slice(0, 160);
+}
+/** Load a single skill from a `<dir>/SKILL.md` path. */
+function loadSkill(skillDir, source) {
+    const skillFile = path.join(skillDir, "SKILL.md");
+    let raw;
+    try {
+        raw = fs.readFileSync(skillFile, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const name = path.basename(skillDir);
+    const { frontmatter, content } = parseFrontmatter(raw);
+    return {
+        name,
+        description: frontmatter.description || descriptionFromBody(content),
+        whenToUse: frontmatter.when_to_use,
+        content,
+        source,
+        dir: skillDir,
+    };
+}
+/** Load all skills from a `skills/` directory (each subdirectory is one skill). */
+function loadSkillsDir(skillsDir, source) {
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const skill = loadSkill(path.join(skillsDir, entry.name), source);
+        if (skill)
+            skills.push(skill);
+    }
+    return skills;
+}
+/** Walk from cwd up to root, collecting `.orbcode/skills` dirs (root last). */
+function projectSkillsDirs(cwd) {
+    const dirs = [];
+    let current = path.resolve(cwd);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        dirs.push(path.join(current, ".orbcode", "skills"));
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Load all skills. Project skills (closer-to-cwd) override user skills on name
+ * collisions. Returns a map keyed by skill name.
+ */
+export function loadSkills(cwd = process.cwd()) {
+    const skills = new Map();
+    // User skills first (lowest precedence).
+    for (const skill of loadSkillsDir(path.join(getConfigDir(), "skills"), "user")) {
+        skills.set(skill.name, skill);
+    }
+    // Project skills, root -> cwd so cwd wins.
+    for (const dir of projectSkillsDirs(cwd).reverse()) {
+        for (const skill of loadSkillsDir(dir, "project")) {
+            skills.set(skill.name, skill);
+        }
+    }
+    return skills;
+}
+/** Render the skill catalog for the system prompt (names + when_to_use). */
+export function renderSkillCatalog(skills) {
+    if (skills.size === 0)
+        return "";
+    const lines = ["# Available Skills", ""];
+    for (const skill of skills.values()) {
+        const when = skill.whenToUse ? ` — use when: ${skill.whenToUse}` : "";
+        lines.push(`- \`${skill.name}\`: ${skill.description}${when}`);
+    }
+    lines.push("");
+    lines.push("Use the `use_skill` tool with a `skill_name` to load a skill's full instructions.");
+    return lines.join("\n");
+}
+/** Substitute ${SKILL_DIR} in a skill's content with its directory path. */
+export function renderSkillContent(skill) {
+    return skill.content.replace(/\$\{SKILL_DIR\}/g, skill.dir);
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/executors/skills.js

@@ -0,0 +1,28 @@
+import { loadSkills, renderSkillContent } from "../../skills/loader.js";
+/**
+ * `use_skill` executor: loads a skill's full markdown instructions and returns
+ * them to the model so it can follow the skill's guidance for the current task.
+ *
+ * Skills are discovered from ~/.orbcode/skills/ and .orbcode/skills/ (see the
+ * skills loader). The model sees the catalog in the system prompt and invokes
+ * this tool with a `skill_name`.
+ */
+export async function useSkill(args, context) {
+    const skillName = String(args.skill_name ?? "").trim();
+    if (!skillName) {
+        return { text: "No skill_name provided.", isError: true };
+    }
+    const skills = loadSkills(context.cwd);
+    const skill = skills.get(skillName);
+    if (!skill) {
+        const available = [...skills.keys()].join(", ") || "(none)";
+        return {
+            text: `Skill "${skillName}" not found. Available skills: ${available}`,
+            isError: true,
+        };
+    }
+    const content = renderSkillContent(skill);
+    return {
+        text: `# Skill: ${skill.name}\n\n${content}\n\n---\nFollow this skill's instructions for the current task.`,
+    };
+}

package/dist/tools/index.js

@@ -3,6 +3,7 @@ import { fileEdit, fileWrite, multiFileEdit, readFile } from "./executors/files.
 import { listFiles } from "./executors/listFiles.js";
 import { searchFiles } from "./executors/searchFiles.js";
 import { executeCommand } from "./executors/executeCommand.js";
+import { useSkill } from "./executors/skills.js";
 import { webFetch, webSearch } from "./executors/web.js";
 export { nativeTools };
 /** Tools that modify the user's system and need approval before running. */
@@ -44,11 +45,18 @@ export function describeToolCall(toolName, args) {
             return String(args.url ?? "");
         case "update_todo_list":
             return "updating tasks";
+        case "use_skill":
+            return String(args.skill_name ?? "");
         case "ask_followup_question":
             return String(args.question ?? "");
         case "attempt_completion":
             return "task complete";
         default:
+            // MCP tools (mcp__<server>__<tool>) — show the server + tool name.
+            if (/^mcp__/.test(toolName)) {
+                const match = /^mcp__([^_]+)__(.+)$/.exec(toolName);
+                return match ? `${match[2]} (${match[1]})` : toolName;
+            }
             return toolName;
     }
 }
@@ -62,13 +70,20 @@ const executors = {
     execute_command: executeCommand,
     web_search: webSearch,
     web_fetch: webFetch,
+    use_skill: useSkill,
     update_todo_list: async (args, context) => {
         context.setTodos(String(args.todos ?? ""));
         return { text: "Todo list updated." };
     },
     // ask_followup_question and attempt_completion are handled by the agent loop.
+    // MCP tools (mcp__<server>__<tool>) are routed via the McpManager in executeTool.
 };
-export async function executeTool(toolName, args, context) {
+export async function executeTool(toolName, args, context, mcp) {
+    // MCP tools are namespaced as mcp__<server>__<tool> and routed to the manager.
+    if (mcp && mcp.hasTool(toolName)) {
+        const result = await mcp.callTool(toolName, args);
+        return { text: result.text, isError: result.isError };
+    }
     const executor = executors[toolName];
     if (!executor) {
         return { text: `Tool "${toolName}" is not available in OrbCode CLI.`, isError: true };
@@ -80,6 +95,10 @@ export async function executeTool(toolName, args, context) {
         return { text: `Tool ${toolName} failed: ${error.message}`, isError: true };
     }
 }
-export function getActiveTools() {
-    return nativeTools;
+/** Native tools plus any MCP tools from connected servers. */
+export function getActiveTools(mcp) {
+    const tools = [...nativeTools];
+    if (mcp)
+        tools.push(...mcp.getTools());
+    return tools;
 }

package/dist/tools/schemas/index.js

@@ -8,11 +8,13 @@ import listFiles from "./list_files.js";
 import { read_file_single } from "./read_file.js";
 import searchFiles from "./search_files.js";
 import updateTodoList from "./update_todo_list.js";
+import useSkill from "./use_skill.js";
 import webFetch from "./web_fetch.js";
 import webSearch from "./web_search.js";
-// Native tool schemas ported verbatim from the Orbital extension (native-tools).
-// Tools that depend on IDE-only services (codebase_search, lsp, use_skill,
-// check_past_chat_memories, browser_action, …) are not active in the CLI.
+// Native tool schemas ported from the Orbital extension. IDE-only tools
+// (codebase_search, lsp, check_past_chat_memories, browser_action, …) are not
+// active in the CLI. use_skill is now active: skills are loaded from
+// ~/.orbcode/skills/ and .orbcode/skills/ (see src/skills/loader.ts).
 export const nativeTools = [
     fileEdit,
     multiFileEdit,
@@ -24,6 +26,7 @@ export const nativeTools = [
     read_file_single,
     searchFiles,
     updateTodoList,
+    useSkill,
     webFetch,
     webSearch,
 ];

package/dist/tools/schemas/use_skill.js

@@ -2,7 +2,7 @@ export default {
     type: "function",
     function: {
         name: "use_skill",
-        description: "Use a specific skill to guide the task execution. This tool allows you to apply predefined skills stored in the workspace's .agent/skills directory. Each skill contains specialized instructions for performing specific tasks or following particular patterns.",
+        description: "Use a specific skill to guide the task execution. This tool applies predefined skills stored in ~/.orbcode/skills/ (user) and .orbcode/skills/ (project). Each skill is a directory containing a SKILL.md file with specialized instructions for performing specific tasks or following particular patterns. The available skills are listed in the 'Available Skills' section of your system prompt — invoke this tool with a skill_name from that list when the task matches a skill's when-to-use condition.",
         strict: true,
         parameters: {
             type: "object",