@botbotgo/agent-harness 0.0.56 → 0.0.57

package/README.md

@@ -1,15 +1,42 @@
+<p align="center">
+  <img src="./docs/assets/readme-icon.png" width="120" alt="botbotgo runtime icon" />
+</p>
+
+<p align="center">
+  <img src="./docs/assets/readme-banner.png" alt="botbotgo runtime banner" />
+</p>
+
 # @botbotgo/agent-harness
 
+<p align="center">
+  <strong>A workspace-shaped runtime for agent systems that need to keep running after the demo.</strong>
+</p>
+
+<p align="center">
+  <strong>botbotgo</strong> is the brand. <strong>agent-harness</strong> is the product.
+</p>
+
+<p align="center">
+  <a href="https://botbotgo.github.io/agent-harness/">Product website</a>
+  (static page in <code>docs/</code>, publish with GitHub Pages)
+</p>
+
 ## Product Overview
 
 `@botbotgo/agent-harness` is a workspace-shaped application runtime for real agent products.
 
 It is not a new agent framework. It is the runtime layer around LangChain v1 and DeepAgents that turns one workspace into one operable application runtime.
 
+The point is simple:
+
+- Codex, Claude Code, and Cursor are products for people using agents
+- LangChain v1 and DeepAgents are frameworks for defining agent execution semantics
+- `agent-harness` is the runtime product layer for shipping, operating, recovering, and governing multi-agent applications
+
 The product boundary is strict:
 
 - LangChain v1 and DeepAgents own agent execution semantics
-- `agent-harness` owns application-level orchestration and lifecycle management stays in the harness
+- application-level orchestration and lifecycle management stays in the harness
 
 That means:
 
@@ -39,6 +66,27 @@ Boundary documents live in:
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
 
+## Why This Exists
+
+Most agent demos stop at execution.
+
+Real products need a runtime that can answer harder questions:
+
+- Where do runs live?
+- How are approvals resolved?
+- What survives process restart?
+- How do you inspect threads and events without exposing raw backend state?
+- How do you swap backend implementations without rewriting the product model?
+
+`agent-harness` is the layer that answers those questions without turning your application API into a mirror of LangChain v1 or DeepAgents.
+
+## What Makes It Different
+
+- It treats `runs`, `threads`, `approvals`, `events`, and recovery as product concepts
+- It keeps checkpoint resume system-managed instead of promoting checkpoint internals into the primary API
+- It lets YAML own assembly complexity while code keeps a tiny surface
+- It goes deep on runtime concerns that upstream libraries do not fully productize
+
 ## Quick Start
 
 Install:
@@ -89,6 +137,13 @@ try {
 }
 ```
 
+If you want the shortest possible mental model:
+
+- one workspace becomes one runtime
+- YAML defines assembly and policy
+- `run(runtime, { ... })` executes requests against that runtime
+- the runtime owns lifecycle, inspection, and recovery
+
 ## Feature List
 
 - Workspace runtime for multi-agent applications
@@ -103,6 +158,13 @@ try {
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
 
+### Runtime Strengths
+
+- Stable product-facing API even when backend details evolve
+- Strong separation between public runtime contract and backend adapter contract
+- Clear YAML ownership for routing, topology, policy, and infrastructure objects
+- Better fit for long-running, approval-heavy, multi-agent products than a thin agent loop wrapper
+
 ## How To Use
 
 ### Create A Runtime

package/dist/api.d.ts

@@ -1,5 +1,7 @@
 import type { ApprovalRecord, RunOptions, ResumeOptions, RuntimeAdapterOptions, ThreadSummary, ThreadRecord, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
+import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/inventory.js";
+import type { RequirementAssessmentOptions } from "./runtime/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 type CreateAgentHarnessOptions = {
@@ -15,6 +17,11 @@ export declare function getThread(runtime: AgentHarnessRuntime, threadId: string
 export declare function deleteThread(runtime: AgentHarnessRuntime, threadId: string): Promise<boolean>;
 export declare function listApprovals(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listApprovals"]>[0]): Promise<ApprovalRecord[]>;
 export declare function getApproval(runtime: AgentHarnessRuntime, approvalId: string): Promise<ApprovalRecord | null>;
+export declare function listAgentSkills(runtime: AgentHarnessRuntime, agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
+export declare function describeInventory(runtime: AgentHarnessRuntime, options?: RequirementAssessmentOptions): {
+    workspaceRoot: string;
+    agents: InventoryAgentRecord[];
+};
 export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<import("./contracts/types.js").RunResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;
 export declare function createToolMcpServer(runtime: AgentHarnessRuntime, options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/api.js

@@ -28,6 +28,12 @@ export async function listApprovals(runtime, filter) {
 export async function getApproval(runtime, approvalId) {
     return runtime.getApproval(approvalId);
 }
+export function listAgentSkills(runtime, agentId, options) {
+    return runtime.listAgentSkills(agentId, options);
+}
+export function describeInventory(runtime, options) {
+    return runtime.describeWorkspaceInventory(options);
+}
 export async function resolveApproval(runtime, options) {
     return runtime.resume(options);
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getThread, listAgentSkills, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, getApproval, getThread, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, createAgentHarness, createToolMcpServer, deleteThread, describeInventory, getApproval, getThread, listAgentSkills, listApprovals, listThreads, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.55";
+export declare const AGENT_HARNESS_VERSION = "0.0.56";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.55";
+export const AGENT_HARNESS_VERSION = "0.0.56";

package/dist/resource/resource-impl.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { stat } from "node:fs/promises";
@@ -12,6 +12,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
 import { AGENT_HARNESS_VERSION } from "../package-version.js";
 import { isSupportedToolModulePath, loadToolModuleDefinition } from "../tool-modules.js";
+import { createRuntimeEnv } from "../runtime/support/runtime-env.js";
 import { resolveIsolatedResourceModulePath } from "./isolation.js";
 import { ensureExternalResourceSource, ensureExternalSource, isExternalSourceLocator, parseExternalSourceLocator } from "./sources.js";
 const resourceDir = path.dirname(fileURLToPath(import.meta.url));
@@ -38,6 +39,33 @@ export function resolveLocalResourceProviderEntry(currentResourceDir, resolveIns
     return candidates.at(-1) ?? path.resolve(currentResourceDir, "../../../resource-package/dist/src/index.js");
 }
 const resourceProviderEntry = resolveLocalResourceProviderEntry(resourceDir);
+function listVirtualRootEntries(rootDir) {
+    try {
+        return new Set(readdirSync(rootDir, { withFileTypes: true }).map((entry) => entry.name));
+    }
+    catch {
+        return new Set();
+    }
+}
+function normalizeVirtualExecuteCommand(command, rootDir) {
+    if (typeof command !== "string" || command.length === 0) {
+        return command;
+    }
+    const rootEntries = listVirtualRootEntries(rootDir);
+    if (rootEntries.size === 0) {
+        return command;
+    }
+    return command.replace(/(^|[\s=:(\[{,;|&])(?<quote>["']?)(?<virtualPath>\/(?:[^\s"'`;|&()<>]+))(?:\k<quote>)/g, (match, prefix, quote = "", virtualPath) => {
+        const normalizedVirtualPath = virtualPath.replace(/\/+/g, "/");
+        const segments = normalizedVirtualPath.split("/").filter((segment) => segment.length > 0);
+        const firstSegment = segments[0];
+        if (!firstSegment || !rootEntries.has(firstSegment)) {
+            return match;
+        }
+        const translatedPath = path.resolve(rootDir, ...segments);
+        return `${prefix}${quote}${translatedPath}${quote}`;
+    });
+}
 async function loadLocalResource(entry) {
     if (!existsSync(entry)) {
         return null;
@@ -70,7 +98,11 @@ class CompatibleCompositeBackend {
         const sandboxLike = defaultBackend;
         if (typeof sandboxLike.id === "string" && typeof sandboxLike.execute === "function") {
             this.id = sandboxLike.id;
-            this.execute = (command) => this.composite.execute(command);
+            const virtualCwd = typeof sandboxLike.cwd === "string" && sandboxLike.virtualMode === true ? sandboxLike.cwd : null;
+            this.execute =
+                virtualCwd
+                    ? (command) => this.composite.execute(normalizeVirtualExecuteCommand(command, virtualCwd))
+                    : (command) => this.composite.execute(command);
         }
     }
     lsInfo(filePath) {
@@ -116,6 +148,10 @@ function createInlineBackendResolver(workspace) {
             return workspace.workspaceRoot;
         };
         const createBackend = (kind, config, runtimeLike) => {
+            const configuredEnv = typeof config?.env === "object" && config.env
+                ? Object.fromEntries(Object.entries(config.env).filter((entry) => typeof entry[1] === "string"))
+                : undefined;
+            const inheritedEnv = config?.inheritEnv === false ? {} : process.env;
             switch (kind) {
                 case "LocalShellBackend": {
                     const rootDir = resolveBackendRootDir(config?.rootDir);
@@ -125,9 +161,7 @@ function createInlineBackendResolver(workspace) {
                         virtualMode: config?.virtualMode === true,
                         timeout: typeof config?.timeout === "number" ? config.timeout : undefined,
                         maxOutputBytes: typeof config?.maxOutputBytes === "number" ? config.maxOutputBytes : undefined,
-                        env: typeof config?.env === "object" && config.env
-                            ? Object.fromEntries(Object.entries(config.env).filter((entry) => typeof entry[1] === "string"))
-                            : undefined,
+                        env: createRuntimeEnv(configuredEnv, inheritedEnv),
                         inheritEnv: config?.inheritEnv !== false,
                     });
                 }
@@ -139,9 +173,7 @@ function createInlineBackendResolver(workspace) {
                         virtualMode: config?.virtualMode === false ? false : true,
                         timeout: typeof config?.timeout === "number" ? config.timeout : undefined,
                         maxOutputBytes: typeof config?.maxOutputBytes === "number" ? config.maxOutputBytes : undefined,
-                        env: typeof config?.env === "object" && config.env
-                            ? Object.fromEntries(Object.entries(config.env).filter((entry) => typeof entry[1] === "string"))
-                            : undefined,
+                        env: createRuntimeEnv(configuredEnv, inheritedEnv),
                         inheritEnv: config?.inheritEnv !== false,
                     });
                 }
@@ -318,7 +350,7 @@ export async function getOrCreateMcpClient(config) {
                     : new StdioClientTransport({
                         command: config.command ?? "",
                         args: config.args,
-                        env: config.env,
+                        env: createRuntimeEnv(config.env),
                         cwd: config.cwd,
                     });
         await client.connect(transport);

package/dist/runtime/agent-runtime-adapter.d.ts

@@ -12,6 +12,13 @@ declare class RuntimeOperationTimeoutError extends Error {
     readonly stage: "stream" | "invoke";
     constructor(operation: string, timeoutMs: number, stage?: "stream" | "invoke");
 }
+export declare function relativizeDeepAgentSkillSourcePaths(workspaceRoot: string | undefined, skillPaths: string[] | undefined): string[] | undefined;
+export declare function materializeDeepAgentSkillSourcePaths(options: {
+    workspaceRoot?: string;
+    runRoot?: string;
+    ownerId: string;
+    skillPaths?: string[];
+}): Promise<string[] | undefined>;
 export declare class AgentRuntimeAdapter {
     private readonly options;
     constructor(options?: RuntimeAdapterOptions);
@@ -26,6 +33,7 @@ export declare class AgentRuntimeAdapter {
     private resolveModel;
     private buildToolNameMapping;
     private buildAgentMessages;
+    private buildSlashCommandSkillInstruction;
     private buildInvocationRequest;
     private buildStateSnapshot;
     private buildRawModelMessages;

package/dist/runtime/agent-runtime-adapter.js

@@ -1,4 +1,6 @@
 import path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
 import { Command, MemorySaver } from "@langchain/langgraph";
 import { tool as createLangChainTool } from "@langchain/core/tools";
 import { createDeepAgent, createMemoryMiddleware, createSkillsMiddleware, createSubAgentMiddleware, FilesystemBackend, } from "deepagents";
@@ -16,6 +18,7 @@ import { wrapToolForExecution } from "./tool-hitl.js";
 import { resolveDeclaredMiddleware } from "./declared-middleware.js";
 import { extractMessageText, normalizeMessageContent } from "../utils/message-content.js";
 import { getBindingDeepAgentParams, getBindingInterruptCompatibilityRules, getBindingLangChainParams, getBindingMiddlewareConfigs, getBindingModelInit, getBindingPrimaryModel, getBindingPrimaryTools, getBindingSystemPrompt, isDeepAgentBinding, isLangChainBinding, } from "./support/compiled-binding.js";
+import { readSkillMetadata } from "./support/skill-metadata.js";
 function countConfiguredTools(binding) {
     return getBindingPrimaryTools(binding).length;
 }
@@ -52,6 +55,65 @@ function computeRemainingTimeoutMs(deadlineAt, fallbackTimeoutMs) {
 function isPlaceholderApiKey(value) {
     return typeof value === "string" && value.trim().toLowerCase() === "dummy";
 }
+export function relativizeDeepAgentSkillSourcePaths(workspaceRoot, skillPaths) {
+    if (!workspaceRoot || !skillPaths) {
+        return skillPaths;
+    }
+    return skillPaths.map((skillPath) => {
+        if (!path.isAbsolute(skillPath)) {
+            return skillPath;
+        }
+        const relative = path.relative(workspaceRoot, skillPath);
+        if (!relative || relative.startsWith("..")) {
+            return skillPath;
+        }
+        return relative.split(path.sep).join("/");
+    });
+}
+function isDeepAgentSkillDirectory(sourcePath) {
+    return existsSync(sourcePath) && statSync(sourcePath).isDirectory() && existsSync(path.join(sourcePath, "SKILL.md"));
+}
+function toWorkspaceRelativePath(workspaceRoot, targetPath) {
+    if (!workspaceRoot) {
+        return targetPath;
+    }
+    const relative = path.relative(workspaceRoot, targetPath);
+    if (!relative || relative.startsWith("..")) {
+        return targetPath;
+    }
+    return relative.split(path.sep).join("/");
+}
+export async function materializeDeepAgentSkillSourcePaths(options) {
+    const { workspaceRoot, runRoot, ownerId, skillPaths } = options;
+    if (!skillPaths) {
+        return skillPaths;
+    }
+    const materialized = relativizeDeepAgentSkillSourcePaths(workspaceRoot, skillPaths) ?? skillPaths;
+    if (!workspaceRoot || !runRoot) {
+        return materialized;
+    }
+    const sourceRoot = path.join(runRoot, "deepagent-skill-sources", ownerId);
+    let wroteSyntheticSource = false;
+    const resolvedSources = [];
+    for (const [index, sourcePath] of materialized.entries()) {
+        const absolutePath = path.isAbsolute(sourcePath) ? sourcePath : path.resolve(workspaceRoot, sourcePath);
+        if (!isDeepAgentSkillDirectory(absolutePath)) {
+            resolvedSources.push(sourcePath);
+            continue;
+        }
+        if (!wroteSyntheticSource) {
+            await rm(sourceRoot, { recursive: true, force: true });
+            await mkdir(sourceRoot, { recursive: true });
+            wroteSyntheticSource = true;
+        }
+        const skillDirectoryName = path.basename(absolutePath);
+        const syntheticSourcePath = path.join(sourceRoot, `${String(index + 1).padStart(3, "0")}-${skillDirectoryName}`);
+        await mkdir(syntheticSourcePath, { recursive: true });
+        await cp(absolutePath, path.join(syntheticSourcePath, skillDirectoryName), { recursive: true });
+        resolvedSources.push(toWorkspaceRelativePath(workspaceRoot, syntheticSourcePath));
+    }
+    return resolvedSources;
+}
 function buildAuthOmittingFetch(baseFetch = fetch) {
     return async (input, init) => {
         const sanitizedHeaders = new Headers(input instanceof Request ? input.headers : undefined);
@@ -399,11 +461,42 @@ export class AgentRuntimeAdapter {
             { role: "user", content: normalizeMessageContent(input) },
         ];
     }
-    buildInvocationRequest(history, input, options = {}) {
+    buildSlashCommandSkillInstruction(binding, input) {
+        const inputText = extractMessageText(input).trim();
+        const match = inputText.match(/^\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\s+([\s\S]*))?$/i);
+        if (!match) {
+            return undefined;
+        }
+        const invokedName = match[1].toLowerCase();
+        const argumentText = match[2]?.trim() ?? "";
+        const skillPaths = binding.deepAgentParams?.skills ?? binding.langchainAgentParams?.skills ?? [];
+        const matchedSkillPath = skillPaths.find((skillPath) => readSkillMetadata(skillPath).name.toLowerCase() === invokedName);
+        if (!matchedSkillPath) {
+            return undefined;
+        }
+        const metadata = readSkillMetadata(matchedSkillPath);
+        const skillQualifier = metadata.userInvocable === true ? "user-invocable skill" : "skill";
+        const dryRunHint = /\s--dry-run(?:\s|$)/.test(` ${argumentText} `)
+            ? "This invocation includes `--dry-run`. Perform the real fetch or inspection steps needed for dry-run output. Do not return hypothetical or mock results."
+            : undefined;
+        return [
+            `This user message is an explicit command-style invocation of the ${skillQualifier} \`${metadata.name}\`.`,
+            `Read the skill file for \`${metadata.name}\` before taking action, then follow its documented phases and constraints exactly.`,
+            `You must use the \`${metadata.name}\` skill for this request and follow its documented workflow.`,
+            `Treat everything after \`/${metadata.name}\` as the skill argument string: ${argumentText ? JSON.stringify(argumentText) : '""'}.`,
+            "Do not answer with a generic explanation of what the skill would do. Execute the skill workflow using the available tools unless the skill instructions explicitly require confirmation before acting.",
+            dryRunHint,
+        ].filter((line) => typeof line === "string" && line.length > 0).join("\n");
+    }
+    buildInvocationRequest(binding, history, input, options = {}) {
+        const userInvocableInstruction = this.buildSlashCommandSkillInstruction(binding, input);
+        const messages = this.buildAgentMessages(history, input);
         return {
             ...(options.state ?? {}),
             ...(options.files ? { files: options.files } : {}),
-            messages: this.buildAgentMessages(history, input),
+            messages: userInvocableInstruction
+                ? [{ role: "system", content: userInvocableInstruction }, ...messages]
+                : messages,
         };
     }
     buildStateSnapshot(result) {
@@ -414,11 +507,15 @@ export class AgentRuntimeAdapter {
         delete snapshot.files;
         return Object.keys(snapshot).length > 0 ? snapshot : undefined;
     }
-    buildRawModelMessages(systemPrompt, history, input) {
+    buildRawModelMessages(binding, systemPrompt, history, input) {
         const messages = [];
         if (systemPrompt) {
             messages.push({ role: "system", content: systemPrompt });
         }
+        const userInvocableInstruction = this.buildSlashCommandSkillInstruction(binding, input);
+        if (userInvocableInstruction) {
+            messages.push({ role: "system", content: userInvocableInstruction });
+        }
         messages.push(...this.buildAgentMessages(history, input));
         return messages;
     }
@@ -572,6 +669,12 @@ export class AgentRuntimeAdapter {
             ...(subagent.passthrough ?? {}),
             model: subagent.model ? (await this.resolveModel(subagent.model)) : undefined,
             tools: subagent.tools ? this.resolveTools(subagent.tools) : undefined,
+            skills: await materializeDeepAgentSkillSourcePaths({
+                workspaceRoot: binding?.harnessRuntime.workspaceRoot,
+                runRoot: binding?.harnessRuntime.runRoot,
+                ownerId: `${binding?.agent.id ?? "agent"}-${subagent.name}`,
+                skillPaths: subagent.skills,
+            }),
             interruptOn: this.compileInterruptOn(subagent.tools ?? [], subagent.interruptOn),
             responseFormat: subagent.responseFormat,
             contextSchema: subagent.contextSchema,
@@ -635,7 +738,12 @@ export class AgentRuntimeAdapter {
             interruptOn: this.resolveInterruptOn(binding),
             name: params.name,
             memory: params.memory,
-            skills: params.skills,
+            skills: await materializeDeepAgentSkillSourcePaths({
+                workspaceRoot: binding.harnessRuntime.workspaceRoot,
+                runRoot: binding.harnessRuntime.runRoot,
+                ownerId: binding.agent.id,
+                skillPaths: params.skills,
+            }),
             generalPurposeAgent: params.generalPurposeAgent,
             taskDescription: params.taskDescription,
         };
@@ -670,7 +778,7 @@ export class AgentRuntimeAdapter {
     }
     async invoke(binding, input, threadId, runId, resumePayload, history = [], options = {}) {
         const request = resumePayload === undefined
-            ? this.buildInvocationRequest(history, input, options)
+            ? this.buildInvocationRequest(binding, history, input, options)
             : new Command({ resume: resumePayload });
         let result;
         try {
@@ -683,7 +791,7 @@ export class AgentRuntimeAdapter {
             }
             const retriedBinding = this.applyStrictToolJsonInstruction(binding);
             const runnable = await this.create(retriedBinding);
-            result = (await this.withTimeout(() => runnable.invoke(this.buildInvocationRequest(history, input, options), { configurable: { thread_id: threadId }, ...(options.context ? { context: options.context } : {}) }), this.resolveBindingTimeout(retriedBinding), "agent invoke", "invoke"));
+            result = (await this.withTimeout(() => runnable.invoke(this.buildInvocationRequest(retriedBinding, history, input, options), { configurable: { thread_id: threadId }, ...(options.context ? { context: options.context } : {}) }), this.resolveBindingTimeout(retriedBinding), "agent invoke", "invoke"));
         }
         const interruptContent = Array.isArray(result.__interrupt__) && result.__interrupt__.length > 0 ? JSON.stringify(result.__interrupt__) : undefined;
         const extractedOutput = extractVisibleOutput(result);
@@ -739,7 +847,7 @@ export class AgentRuntimeAdapter {
                 // agent loop and only adds an extra model round-trip before the runnable path.
                 if (canUseDirectModelStream && typeof model.stream === "function") {
                     let emitted = false;
-                    const stream = await this.withTimeout(() => model.stream(this.buildRawModelMessages(getBindingSystemPrompt(binding), history, input)), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "model stream start", "stream");
+                    const stream = await this.withTimeout(() => model.stream(this.buildRawModelMessages(binding, getBindingSystemPrompt(binding), history, input)), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "model stream start", "stream");
                     for await (const chunk of this.iterateWithTimeout(stream, streamIdleTimeoutMs, "model stream", streamDeadlineAt, invokeTimeoutMs)) {
                         const delta = readStreamDelta(chunk);
                         if (delta) {
@@ -758,7 +866,7 @@ export class AgentRuntimeAdapter {
                 }
             }
             const runnable = await this.create(binding);
-            const request = this.buildInvocationRequest(history, input, options);
+            const request = this.buildInvocationRequest(binding, history, input, options);
             if (typeof runnable.streamEvents === "function") {
                 const events = await this.withTimeout(() => runnable.streamEvents(request, { configurable: { thread_id: threadId }, version: "v2", ...(options.context ? { context: options.context } : {}) }), computeRemainingTimeoutMs(streamDeadlineAt, invokeTimeoutMs), "agent streamEvents start", "stream");
                 const allowVisibleStreamDeltas = isLangChainBinding(binding);

package/dist/runtime/harness.d.ts

@@ -1,5 +1,7 @@
 import type { ApprovalRecord, HarnessEvent, HarnessStreamItem, MessageContent, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 import { type ToolMcpServerOptions } from "../mcp.js";
+import { type InventoryAgentRecord, type InventorySkillRecord } from "./inventory.js";
+import type { RequirementAssessmentOptions } from "./skill-requirements.js";
 export declare class AgentHarnessRuntime {
     private readonly workspace;
     private readonly runtimeAdapterOptions;
@@ -53,6 +55,11 @@ export declare class AgentHarnessRuntime {
         runId?: string;
     }): Promise<ApprovalRecord[]>;
     getApproval(approvalId: string): Promise<ApprovalRecord | null>;
+    listAgentSkills(agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
+    describeWorkspaceInventory(options?: RequirementAssessmentOptions): {
+        workspaceRoot: string;
+        agents: InventoryAgentRecord[];
+    };
     private deleteThreadCheckpoints;
     deleteThread(threadId: string): Promise<boolean>;
     createToolMcpServer(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp.js").McpServer>;

package/dist/runtime/harness.js

@@ -16,6 +16,7 @@ import { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, readCh
 import { extractMessageText, normalizeMessageContent } from "../utils/message-content.js";
 import { createToolMcpServerFromTools, serveToolsOverStdioFromHarness } from "../mcp.js";
 import { getBindingAdapterKind, getBindingPrimaryTools, getBindingStoreConfig } from "./support/compiled-binding.js";
+import { describeWorkspaceInventory, listAgentSkills as listWorkspaceAgentSkills, } from "./inventory.js";
 export class AgentHarnessRuntime {
     workspace;
     runtimeAdapterOptions;
@@ -286,6 +287,12 @@ export class AgentHarnessRuntime {
         const approval = await this.persistence.getApproval(approvalId);
         return approval ? this.toPublicApprovalRecord(approval) : null;
     }
+    listAgentSkills(agentId, options = {}) {
+        return listWorkspaceAgentSkills(this.workspace, agentId, options);
+    }
+    describeWorkspaceInventory(options = {}) {
+        return describeWorkspaceInventory(this.workspace, options);
+    }
     async deleteThreadCheckpoints(threadId) {
         const resolver = this.resolvedRuntimeAdapterOptions.checkpointerResolver;
         if (!resolver) {

package/dist/runtime/index.d.ts

@@ -6,6 +6,7 @@ export { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, mainta
 export { ManagedSqliteSaver } from "./sqlite-maintained-checkpoint-saver.js";
 export { AgentHarnessRuntime, AgentHarness } from "./harness.js";
 export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
+export { assessOpenClawRequirements, assessSkillRequirements, } from "./skill-requirements.js";
 export * from "./parsing/index.js";
 export { PolicyEngine } from "./policy-engine.js";
 export { createInMemoryStore, FileBackedStore } from "./store.js";

package/dist/runtime/index.js

@@ -6,6 +6,7 @@ export { CheckpointMaintenanceLoop, discoverCheckpointMaintenanceTargets, mainta
 export { ManagedSqliteSaver } from "./sqlite-maintained-checkpoint-saver.js";
 export { AgentHarnessRuntime, AgentHarness } from "./harness.js";
 export { describeWorkspaceInventory, findAgentBinding, listAgentSkills, listAgentTools, listAvailableAgents, listSpecialists, } from "./inventory.js";
+export { assessOpenClawRequirements, assessSkillRequirements, } from "./skill-requirements.js";
 export * from "./parsing/index.js";
 export { PolicyEngine } from "./policy-engine.js";
 export { createInMemoryStore, FileBackedStore } from "./store.js";

package/dist/runtime/inventory.d.ts

@@ -1,4 +1,6 @@
 import type { CompiledAgentBinding, WorkspaceBundle } from "../contracts/types.js";
+import type { OpenClawSkillMetadata } from "./support/skill-metadata.js";
+import { type RequirementAssessmentOptions, type SkillRequirementAssessment } from "./skill-requirements.js";
 export type InventoryToolRecord = {
     name: string;
     description: string;
@@ -9,8 +11,11 @@ export type InventorySkillRecord = {
     description?: string;
     license?: string;
     compatibility?: string;
-    metadata?: Record<string, string>;
+    metadata?: Record<string, unknown>;
     allowedTools?: string[];
+    userInvocable?: boolean;
+    openclaw?: OpenClawSkillMetadata;
+    requirements?: SkillRequirementAssessment;
 };
 export type InventoryAgentRecord = {
     id: string;
@@ -21,10 +26,10 @@ export type InventoryAgentRecord = {
 };
 export declare function findAgentBinding(workspace: WorkspaceBundle, agentId: string): CompiledAgentBinding | undefined;
 export declare function listAgentTools(workspace: WorkspaceBundle, agentId: string): InventoryToolRecord[];
-export declare function listAgentSkills(workspace: WorkspaceBundle, agentId: string): InventorySkillRecord[];
-export declare function listSpecialists(workspace: WorkspaceBundle): InventoryAgentRecord[];
-export declare function listAvailableAgents(workspace: WorkspaceBundle): InventoryAgentRecord[];
-export declare function describeWorkspaceInventory(workspace: WorkspaceBundle): {
+export declare function listAgentSkills(workspace: WorkspaceBundle, agentId: string, options?: RequirementAssessmentOptions): InventorySkillRecord[];
+export declare function listSpecialists(workspace: WorkspaceBundle, options?: RequirementAssessmentOptions): InventoryAgentRecord[];
+export declare function listAvailableAgents(workspace: WorkspaceBundle, options?: RequirementAssessmentOptions): InventoryAgentRecord[];
+export declare function describeWorkspaceInventory(workspace: WorkspaceBundle, options?: RequirementAssessmentOptions): {
     workspaceRoot: string;
     agents: InventoryAgentRecord[];
 };

package/dist/runtime/inventory.js

@@ -1,5 +1,7 @@
 import { readSkillMetadata } from "./support/skill-metadata.js";
 import { getBindingPrimaryTools } from "./support/compiled-binding.js";
+import { assessSkillRequirements, } from "./skill-requirements.js";
+import { createRuntimeEnv } from "./support/runtime-env.js";
 function listHostBindings(workspace) {
     return Array.from(workspace.bindings.values()).filter((binding) => binding.harnessRuntime.hostFacing);
 }
@@ -13,7 +15,36 @@ function dedupeTools(tools) {
     }
     return Array.from(deduped.values());
 }
-function toSkillRecords(skillPaths) {
+function readBackendRequirementOptions(binding) {
+    const backend = binding.deepAgentParams?.backend && typeof binding.deepAgentParams.backend === "object"
+        ? binding.deepAgentParams.backend
+        : undefined;
+    if (!backend) {
+        return {};
+    }
+    const backendState = typeof backend.state === "object" && backend.state
+        ? backend.state
+        : backend;
+    const env = typeof backendState.env === "object" && backendState.env
+        ? Object.fromEntries(Object.entries(backendState.env).filter((entry) => typeof entry[1] === "string"))
+        : undefined;
+    const inheritedEnv = backendState.inheritEnv === false ? {} : process.env;
+    const runtimeEnv = createRuntimeEnv(env, inheritedEnv);
+    return {
+        env: runtimeEnv,
+        path: runtimeEnv.PATH,
+    };
+}
+function mergeRequirementOptions(binding, options = {}) {
+    const fromBackend = readBackendRequirementOptions(binding);
+    return {
+        ...fromBackend,
+        ...options,
+        env: options.env ? { ...(fromBackend.env ?? {}), ...options.env } : fromBackend.env,
+        path: options.path ?? fromBackend.path,
+    };
+}
+function toSkillRecords(skillPaths, options = {}) {
     return Array.from(new Set(skillPaths)).map((skillPath) => {
         const metadata = readSkillMetadata(skillPath);
         return {
@@ -24,6 +55,9 @@ function toSkillRecords(skillPaths) {
             compatibility: metadata.compatibility,
             metadata: metadata.metadata,
             allowedTools: metadata.allowedTools,
+            userInvocable: metadata.userInvocable,
+            openclaw: metadata.openclaw,
+            requirements: assessSkillRequirements(metadata, options),
         };
     });
 }
@@ -34,38 +68,42 @@ export function listAgentTools(workspace, agentId) {
     }
     return dedupeTools(getBindingPrimaryTools(binding));
 }
-export function listAgentSkills(workspace, agentId) {
+export function listAgentSkills(workspace, agentId, options = {}) {
     const binding = findAgentBinding(workspace, agentId);
     if (!binding) {
         return [];
     }
-    return toSkillRecords(binding.deepAgentParams?.skills ?? []);
+    const resolvedOptions = mergeRequirementOptions(binding, options);
+    return toSkillRecords(binding.deepAgentParams?.skills ?? binding.langchainAgentParams?.skills ?? [], resolvedOptions);
 }
-function describeSubagent(subagent) {
+function describeSubagent(subagent, options = {}) {
     return {
         id: subagent.name,
         description: subagent.description,
         role: "specialist",
         tools: dedupeTools(subagent.tools ?? []),
-        skills: toSkillRecords(subagent.skills ?? []),
+        skills: toSkillRecords(subagent.skills ?? [], options),
     };
 }
-export function listSpecialists(workspace) {
-    return listHostBindings(workspace).flatMap((binding) => (binding.deepAgentParams?.subagents ?? []).map(describeSubagent));
+export function listSpecialists(workspace, options = {}) {
+    return listHostBindings(workspace).flatMap((binding) => {
+        const resolvedOptions = mergeRequirementOptions(binding, options);
+        return (binding.deepAgentParams?.subagents ?? []).map((subagent) => describeSubagent(subagent, resolvedOptions));
+    });
 }
-export function listAvailableAgents(workspace) {
+export function listAvailableAgents(workspace, options = {}) {
     const topLevel = listHostBindings(workspace).map((binding) => ({
         id: binding.agent.id,
         description: binding.agent.description,
         role: "host",
         tools: listAgentTools(workspace, binding.agent.id),
-        skills: listAgentSkills(workspace, binding.agent.id),
+        skills: listAgentSkills(workspace, binding.agent.id, options),
     }));
-    return [...topLevel, ...listSpecialists(workspace)];
+    return [...topLevel, ...listSpecialists(workspace, options)];
 }
-export function describeWorkspaceInventory(workspace) {
+export function describeWorkspaceInventory(workspace, options = {}) {
     return {
         workspaceRoot: workspace.workspaceRoot,
-        agents: listAvailableAgents(workspace),
+        agents: listAvailableAgents(workspace, options),
     };
 }

package/dist/runtime/skill-requirements.d.ts

@@ -0,0 +1,27 @@
+import type { OpenClawSkillMetadata, SkillMetadata } from "./support/skill-metadata.js";
+export type RequirementStatus = "satisfied" | "missing" | "unknown";
+export type RequirementCheckRecord = {
+    name: string;
+    status: RequirementStatus;
+};
+export type OpenClawRequirementAssessment = {
+    ready: boolean;
+    missing: boolean;
+    unknown: boolean;
+    bins: RequirementCheckRecord[];
+    anyBins: RequirementCheckRecord[];
+    env: RequirementCheckRecord[];
+    config: RequirementCheckRecord[];
+    primaryEnv?: RequirementCheckRecord;
+};
+export type SkillRequirementAssessment = {
+    openclaw?: OpenClawRequirementAssessment;
+};
+export type RequirementAssessmentOptions = {
+    env?: Record<string, string | undefined>;
+    path?: string;
+    availableBins?: string[];
+    config?: Record<string, unknown> | string[];
+};
+export declare function assessOpenClawRequirements(metadata: OpenClawSkillMetadata | undefined, options?: RequirementAssessmentOptions): OpenClawRequirementAssessment | undefined;
+export declare function assessSkillRequirements(metadata: SkillMetadata, options?: RequirementAssessmentOptions): SkillRequirementAssessment;

package/dist/runtime/skill-requirements.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { augmentExecutablePath } from "./support/runtime-env.js";
+function dedupe(items) {
+    return Array.from(new Set(items.filter(Boolean)));
+}
+function pathEntries(pathValue) {
+    return augmentExecutablePath(pathValue ?? process.env.PATH ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function isExecutableInPath(binName, searchPath) {
+    for (const entry of pathEntries(searchPath)) {
+        if (existsSync(path.join(entry, binName))) {
+            return true;
+        }
+    }
+    return false;
+}
+function assessNamedRequirements(names, evaluator) {
+    return dedupe(names ?? []).map((name) => ({
+        name,
+        status: evaluator(name),
+    }));
+}
+function hasConfigPath(config, dottedPath) {
+    const parts = dottedPath.split(".").filter(Boolean);
+    let cursor = config;
+    for (const part of parts) {
+        if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor) || !(part in cursor)) {
+            return false;
+        }
+        cursor = cursor[part];
+    }
+    return cursor !== undefined;
+}
+function assessConfigRequirements(names, config) {
+    if (!names || names.length === 0) {
+        return [];
+    }
+    if (!config) {
+        return dedupe(names).map((name) => ({ name, status: "unknown" }));
+    }
+    if (Array.isArray(config)) {
+        const set = new Set(config);
+        return dedupe(names).map((name) => ({
+            name,
+            status: set.has(name) ? "satisfied" : "missing",
+        }));
+    }
+    return dedupe(names).map((name) => ({
+        name,
+        status: hasConfigPath(config, name) ? "satisfied" : "missing",
+    }));
+}
+function summarizeRequirementGroups(groups) {
+    const flat = groups.flat();
+    const missing = flat.some((item) => item.status === "missing");
+    const unknown = flat.some((item) => item.status === "unknown");
+    return {
+        ready: flat.length === 0 ? true : !missing && !unknown,
+        missing,
+        unknown,
+    };
+}
+export function assessOpenClawRequirements(metadata, options = {}) {
+    if (!metadata?.requires) {
+        return undefined;
+    }
+    const availableBins = options.availableBins ? new Set(options.availableBins) : null;
+    const bins = assessNamedRequirements(metadata.requires.bins, (name) => availableBins
+        ? (availableBins.has(name) ? "satisfied" : "missing")
+        : (isExecutableInPath(name, options.path) ? "satisfied" : "missing"));
+    const anyBins = assessNamedRequirements(metadata.requires.anyBins, (name) => availableBins
+        ? (availableBins.has(name) ? "satisfied" : "missing")
+        : (isExecutableInPath(name, options.path) ? "satisfied" : "missing"));
+    const env = assessNamedRequirements(metadata.requires.env, (name) => options.env && options.env[name] ? "satisfied" : "missing");
+    const config = assessConfigRequirements(metadata.requires.config, options.config);
+    const primaryEnv = metadata.requires.primaryEnv
+        ? {
+            name: metadata.requires.primaryEnv,
+            status: (options.env && options.env[metadata.requires.primaryEnv] ? "satisfied" : "missing"),
+        }
+        : undefined;
+    const anyBinsSummary = anyBins.length === 0
+        ? []
+        : [{
+                name: anyBins.map((item) => item.name).join(" | "),
+                status: (anyBins.some((item) => item.status === "satisfied") ? "satisfied" : "missing"),
+            }];
+    const summary = summarizeRequirementGroups([
+        bins,
+        anyBinsSummary,
+        env,
+        config,
+        ...(primaryEnv ? [[primaryEnv]] : []),
+    ]);
+    return {
+        ...summary,
+        bins,
+        anyBins,
+        env,
+        config,
+        ...(primaryEnv ? { primaryEnv } : {}),
+    };
+}
+export function assessSkillRequirements(metadata, options = {}) {
+    return {
+        ...(metadata.openclaw ? { openclaw: assessOpenClawRequirements(metadata.openclaw, options) } : {}),
+    };
+}

package/dist/runtime/support/runtime-env.d.ts

@@ -0,0 +1,2 @@
+export declare function augmentExecutablePath(pathValue: string | undefined, env?: Record<string, string | undefined> | NodeJS.ProcessEnv): string;
+export declare function createRuntimeEnv(env: Record<string, string> | undefined, baseEnv?: Record<string, string | undefined> | NodeJS.ProcessEnv): Record<string, string>;

package/dist/runtime/support/runtime-env.js

@@ -0,0 +1,57 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+const COMMON_EXECUTABLE_DIRS = [
+    "/opt/homebrew/bin",
+    "/opt/homebrew/sbin",
+    "/usr/local/bin",
+    "/usr/local/sbin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+];
+function normalizeEnvRecord(env) {
+    return Object.fromEntries(Object.entries(env).filter((entry) => typeof entry[1] === "string"));
+}
+function splitPathEntries(pathValue) {
+    return (pathValue ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function discoverNvmExecutableDirs(home) {
+    const versionsRoot = path.join(home, ".nvm", "versions", "node");
+    if (!existsSync(versionsRoot)) {
+        return [];
+    }
+    return readdirSync(versionsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(versionsRoot, entry.name, "bin"));
+}
+function defaultExecutableDirs(env) {
+    const home = env.HOME ?? env.USERPROFILE ?? homedir();
+    return [
+        ...COMMON_EXECUTABLE_DIRS,
+        path.join(home, ".pyenv", "shims"),
+        path.join(home, ".asdf", "shims"),
+        ...discoverNvmExecutableDirs(home),
+    ];
+}
+export function augmentExecutablePath(pathValue, env = process.env) {
+    const deduped = new Set();
+    for (const entry of [...splitPathEntries(pathValue), ...defaultExecutableDirs(env)]) {
+        deduped.add(entry);
+    }
+    return Array.from(deduped).join(path.delimiter);
+}
+export function createRuntimeEnv(env, baseEnv = process.env) {
+    const base = normalizeEnvRecord(baseEnv);
+    const merged = {
+        ...base,
+        ...(env ?? {}),
+    };
+    const combinedPath = [base.PATH, env?.PATH].filter((value) => typeof value === "string").join(path.delimiter);
+    merged.PATH = augmentExecutablePath(combinedPath, { ...base, ...(env ?? {}) });
+    return merged;
+}

package/dist/runtime/support/skill-metadata.d.ts

@@ -3,8 +3,21 @@ export type SkillMetadata = {
     description?: string;
     license?: string;
     compatibility?: string;
-    metadata?: Record<string, string>;
+    metadata?: Record<string, unknown>;
     allowedTools?: string[];
+    userInvocable?: boolean;
+    openclaw?: OpenClawSkillMetadata;
+};
+export type OpenClawSkillRequirements = {
+    bins?: string[];
+    anyBins?: string[];
+    env?: string[];
+    config?: string[];
+    primaryEnv?: string;
+};
+export type OpenClawSkillMetadata = {
+    emoji?: string;
+    requires?: OpenClawSkillRequirements;
 };
 export declare function readSkillMetadata(skillPath: string): SkillMetadata;
 export declare function validateSkillMetadata(skillPath: string): SkillMetadata;

package/dist/runtime/support/skill-metadata.js

@@ -11,33 +11,81 @@ function parseFrontmatterSource(document) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isJsonLikeValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every((item) => isJsonLikeValue(item));
+    }
+    if (isRecord(value)) {
+        return Object.values(value).every((item) => isJsonLikeValue(item));
+    }
+    return false;
+}
 function normalizeMetadata(value, strict) {
     if (value === undefined) {
         return undefined;
     }
     if (!isRecord(value)) {
         if (strict) {
-            throw new Error("metadata must be a string key-value map");
+            throw new Error("metadata must be a JSON-like key-value map");
         }
         return undefined;
     }
     const normalized = Object.entries(value).reduce((acc, [key, item]) => {
-        if (typeof item === "string") {
+        if (isJsonLikeValue(item)) {
             acc[key] = item;
         }
         return acc;
     }, {});
     if (strict && Object.keys(normalized).length !== Object.keys(value).length) {
-        throw new Error("metadata values must all be strings");
+        throw new Error("metadata values must be JSON-like");
     }
     return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
+function normalizeStringArray(value) {
+    if (typeof value === "string") {
+        const tokens = value.split(/\s+/).filter(Boolean);
+        return tokens.length > 0 ? tokens : undefined;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const tokens = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return tokens.length > 0 ? tokens : undefined;
+}
 function toAllowedTools(value) {
-    if (typeof value !== "string") {
+    const tools = normalizeStringArray(value);
+    return tools && tools.length > 0 ? tools : undefined;
+}
+function parseOpenClawMetadata(value) {
+    if (!isRecord(value)) {
         return undefined;
     }
-    const tools = value.split(/\s+/).filter(Boolean);
-    return tools.length > 0 ? tools : undefined;
+    const requires = isRecord(value.requires) ? value.requires : undefined;
+    const normalizedRequires = {
+        ...(normalizeStringArray(requires?.bins) ? { bins: normalizeStringArray(requires?.bins) } : {}),
+        ...(normalizeStringArray(requires?.anyBins) ? { anyBins: normalizeStringArray(requires?.anyBins) } : {}),
+        ...(normalizeStringArray(requires?.env) ? { env: normalizeStringArray(requires?.env) } : {}),
+        ...(normalizeStringArray(requires?.config) ? { config: normalizeStringArray(requires?.config) } : {}),
+        ...(typeof value.primaryEnv === "string" && value.primaryEnv.trim()
+            ? { primaryEnv: value.primaryEnv.trim() }
+            : typeof requires?.primaryEnv === "string" && requires.primaryEnv.trim()
+                ? { primaryEnv: requires.primaryEnv.trim() }
+                : {}),
+    };
+    const normalized = {
+        ...(typeof value.emoji === "string" && value.emoji.trim() ? { emoji: value.emoji } : {}),
+        ...(Object.keys(normalizedRequires).length > 0 ? { requires: normalizedRequires } : {}),
+    };
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
 function parseFrontmatter(document, strict = false) {
     const source = parseFrontmatterSource(document);
@@ -55,6 +103,8 @@ function parseFrontmatter(document, strict = false) {
         compatibility: typeof parsed.compatibility === "string" ? parsed.compatibility : undefined,
         metadata: normalizeMetadata(parsed.metadata, strict),
         allowedTools: toAllowedTools(parsed["allowed-tools"]),
+        userInvocable: typeof parsed["user-invocable"] === "boolean" ? parsed["user-invocable"] : undefined,
+        openclaw: parseOpenClawMetadata(isRecord(parsed.metadata) ? parsed.metadata.openclaw : undefined),
     };
 }
 function isLegacyBuiltinSkillName(name) {
@@ -86,7 +136,7 @@ function validateMetadata(metadata, skillPath) {
         return;
     }
     if (Object.keys(metadata).length === 0) {
-        throw new Error(`Skill ${skillPath} metadata must contain string key-value pairs when provided`);
+        throw new Error(`Skill ${skillPath} metadata must contain JSON-like key-value pairs when provided`);
     }
 }
 function parseSkillMetadataFromDocument(document, skillPath, strict) {
@@ -104,6 +154,8 @@ function parseSkillMetadataFromDocument(document, skillPath, strict) {
         compatibility: parsed.compatibility,
         metadata: parsed.metadata,
         allowedTools: parsed.allowedTools,
+        userInvocable: parsed.userInvocable,
+        openclaw: parsed.openclaw,
     };
     if (strict) {
         validateSkillName(metadata.name, skillPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.56",
+  "version": "0.0.57",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -50,7 +50,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
+    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",