@botbotgo/agent-harness 0.0.55 → 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:
 
@@ -18,13 +45,7 @@ That means:
 - runtime lifecycle stays stable even if backend implementations change
 - backend internals stay behind adapters
 
-The repository also keeps two boundary documents current:
-
-- `docs/upstream-feature-matrix.md`
-- `docs/product-boundary.md`
-- `docs/feature-checklist.md`
-
-What the runtime provides:
+The runtime provides:
 
 - `createAgentHarness(workspaceRoot)`, `run(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
@@ -32,6 +53,40 @@ What the runtime provides:
 - local `resources/tools/` and `resources/skills/` discovery
 - persisted threads, runs, approvals, events, queue state, and recovery metadata
 
+The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit defaults for the important runtime and agent knobs so teams can start from concrete config instead of reverse-engineering adapter behavior from source.
+
+The default rule is:
+
+- if LangChain v1 or DeepAgents already has the feature, map it in YAML and adapt it internally
+- do not add a new public runtime API unless the problem is truly runtime-owned
+
+Boundary documents live in:
+
+- `docs/upstream-feature-matrix.md`
+- `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:
@@ -82,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
@@ -96,13 +158,12 @@ try {
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
 
-## Design Notes
+### Runtime Strengths
 
-- `agent-harness` is not a third agent framework
-- LangChain v1 and DeepAgents own agent execution semantics
-- `agent-harness` owns workspace assembly, runtime lifecycle, approvals, inspection, recovery, and operations
-- when upstream already has the feature, prefer passthrough or light YAML adaptation over a new harness abstraction
-- when a feature can be expressed in YAML, prefer YAML over expanding the public API
+- 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
 
@@ -114,7 +175,7 @@ import { AgentHarnessRuntime, createAgentHarness } from "@botbotgo/agent-harness
 const runtime: AgentHarnessRuntime = await createAgentHarness("/absolute/path/to/workspace");
 ```
 
-`createAgentHarness(...)` loads one workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
+`createAgentHarness(...)` loads the workspace, resolves `resources/`, initializes persistence under `runRoot`, and starts runtime maintenance.
 
 ### Run A Request
 
@@ -138,7 +199,7 @@ const result = await run(runtime, {
 });
 ```
 
-`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and a compact text `output`. Richer upstream results remain available through `outputContent`, `contentBlocks`, and `structuredResponse` without expanding the main facade.
+`run(runtime, { ... })` creates or continues a persisted thread and returns `threadId`, `runId`, `state`, and compact text `output`. Richer upstream result shapes stay available through `outputContent`, `contentBlocks`, and `structuredResponse`.
 
 Use `invocation` as the runtime-facing request envelope:
 
@@ -177,7 +238,7 @@ const result = await run(runtime, {
 });
 ```
 
-`subscribe(...)` is a read-only observer surface over stored lifecycle events.
+`subscribe(...)` is the read-only observer surface over stored lifecycle events.
 
 The runtime event stream includes:
 
@@ -213,9 +274,11 @@ if (approval) {
 }
 ```
 
-These methods return runtime-facing records, not raw persistence or backend checkpoint objects.
+These methods return runtime-facing records, not raw checkpoint or backend objects.
+
+### Expose And Consume MCP
 
-### Bridge MCP Servers Into Agents
+Bridge MCP servers into agents:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -232,9 +295,7 @@ spec:
         args: ["./mcp-browser-server.mjs"]
 ```
 
-The runtime discovers MCP tools, filters them through agent configuration, and exposes them like other tools.
-
-### Expose Runtime Tools As An MCP Server
+Expose harness tools as an MCP server:
 
 ```ts
 import { createToolMcpServer, serveToolsOverStdio } from "@botbotgo/agent-harness";
@@ -256,7 +317,7 @@ await stop(runtime);
 Use Kubernetes-style YAML:
 
 - collection files use `apiVersion`, plural `kind`, and `spec: []`
-- single-object files use `apiVersion`, singular `kind`, `metadata`, and `spec`
+- singleton files use `apiVersion`, singular `kind`, `metadata`, and `spec`
 
 Core workspace files:
 
@@ -274,19 +335,17 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
-There are three configuration layers:
+There are three main configuration layers:
 
 - runtime policy in `config/workspace.yaml`
 - reusable object catalogs in `config/*.yaml`
 - agent assembly in `config/agents/*.yaml`
 
-The repository-owned default config layer is intentionally full-shaped. The shipped YAML keeps explicit default values for the main runtime knobs so teams can start from concrete config instead of reconstructing adapter defaults from code.
-
 ### `config/workspace.yaml`
 
-Use this file for runtime-level policy shared by the whole workspace.
+Use this file for workspace-wide runtime policy.
 
-Primary fields:
+Important fields:
 
 - `runRoot`
 - `concurrency.maxConcurrentRuns`
@@ -299,13 +358,36 @@ Primary fields:
 - `recovery.resumeResumingRunsOnStartup`
 - `recovery.maxRecoveryAttempts`
 
-If `runRoot` is omitted, the runtime defaults to `<workspace-root>/run-data`.
+`recovery.resumeResumingRunsOnStartup` keeps checkpoint resume a runtime-owned lifecycle behavior instead of exposing checkpoint orchestration as public API.
+
+Example:
+
+```yaml
+apiVersion: agent-harness/v1alpha1
+kind: Runtime
+metadata:
+  name: default
+spec:
+  runRoot: ./.agent
+  concurrency:
+    maxConcurrentRuns: 3
+  routing:
+    defaultAgentId: orchestra
+    modelRouting: false
+  maintenance:
+    checkpoints:
+      enabled: true
+  recovery:
+    enabled: true
+    resumeResumingRunsOnStartup: true
+    maxRecoveryAttempts: 3
+```
 
 ### `config/agent-context.md`
 
-Use this file for shared bootstrap context loaded into agents at construction time.
+Use this file for shared bootstrap memory loaded at agent construction time.
 
-Put stable project context here. Do not use it as mutable long-term memory.
+Keep stable project context here. Treat it as startup context, not mutable long-term memory.
 
 ### `config/models.yaml`
 
@@ -354,7 +436,7 @@ spec:
 
 ### `config/backends.yaml`
 
-Use reusable DeepAgent backend presets so filesystem and long-term memory topology stays in YAML instead of application code:
+Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -377,9 +459,7 @@ spec:
 
 Use this file for reusable tool objects.
 
-Supported tool families in the built-in runtime include function tools, backend tools, MCP tools, provider-native tools, and bundles.
-
-Provider-native tools are declared in YAML and resolved directly to upstream provider tool factories.
+Built-in tool families include function tools, backend tools, MCP tools, bundles, and provider-native tools. Provider-native tools are declared in YAML and resolved directly to upstream factories.
 
 ### `config/mcp.yaml`
 
@@ -387,16 +467,14 @@ Use this file for named MCP server presets.
 
 ### `config/agents/*.yaml`
 
-Agents are always declared with `kind: Agent` and `spec.execution.backend`.
+Agents always use `kind: Agent` plus `spec.execution.backend`.
 
-Use two nested sections inside each agent:
+Use two nested sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`
 - `spec.execution` for upstream execution semantics and adapter-facing config
 
-This keeps the public product model small while letting LangChain v1 and DeepAgents concepts pass through with minimal translation.
-
-Example lightweight host:
+Example direct host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -420,11 +498,15 @@ spec:
       store:
         ref: store/default
       interruptOn: {}
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
       middleware: []
       systemPrompt: Answer simple requests directly.
 ```
 
-Example main execution host:
+Example orchestra host:
 
 ```yaml
 apiVersion: agent-harness/v1alpha1
@@ -453,36 +535,29 @@ spec:
       interruptOn: {}
       middleware: []
       generalPurposeAgent: true
-      taskDescription: Complete delegated sidecar work and return concise results.
+      taskDescription: Complete delegated sidecar work and return concise results without bloating the parent context.
 ```
 
-For backend-specific agent options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
-
-### `resources/`
-
-Use `resources/` for executable local extensions:
-
-- `resources/tools/` for tool modules
-- `resources/skills/` for SKILL packages
-
-Tool modules are discovered from `resources/tools/*.js`, `resources/tools/*.mjs`, and `resources/tools/*.cjs`.
+For backend-specific options, prefer the upstream concept directly inside `spec.execution.config`. Upstream feature coverage is tracked in [docs/upstream-feature-matrix.md](docs/upstream-feature-matrix.md).
 
 ## Design Notes
 
+- `agent-harness` is not a third agent framework
 - public runtime contract stays generic and small
 - application-level orchestration and lifecycle management stays in the harness
 - upstream LangChain v1 and DeepAgents concepts should be expressed as directly as possible in YAML
-- recovery, approvals, threads, runs, and events are runtime concepts, not backend-specific escape hatches
-- backend implementation details should stay internal unless product requirements force exposure
-- new LangChain v1 or DeepAgents public config should land in YAML passthrough and compatibility tests before adding new public runtime APIs
+- when a feature can be expressed in YAML, prefer YAML over expanding the public API
+- recovery, approvals, threads, runs, and events are runtime concepts, not backend escape hatches
+- new LangChain v1 or DeepAgents config should land in YAML mapping and tests before adding public runtime APIs
 
-In short: `agent-harness` is a public runtime contract generic enough to survive backend changes, while the deep execution semantics stay upstream.
+In short, the product model stays stable while the execution semantics remain upstream-owned.
 
 ## API Summary
 
 Primary exports:
 
 - `createAgentHarness`
+- `AgentHarnessRuntime`
 - `run`
 - `resolveApproval`
 - `subscribe`

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/config/agents/direct.yaml

@@ -46,7 +46,25 @@ spec:
         ref: store/default
       # Upstream execution feature: no declarative HITL tool routing by default.
       interruptOn: {}
+      # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.
+      # This only becomes active when `middleware` includes `{ kind: filesystem }`, or when
+      # automatic upstream middleware such as skills or memory need a filesystem backend.
+      # Keep the default root inside the workspace so file-aware middleware stays bounded.
+      filesystem:
+        rootDir: .
+        virtualMode: true
+        maxFileSizeMb: 10
       # Upstream execution feature: no extra declarative middleware beyond the runtime's automatic injections.
+      # Common upstream middleware kinds that this harness can compile directly from YAML:
+      # - `filesystem`
+      # - `patchToolCalls`
+      # - `summarization`
+      # - `dynamicSystemPrompt`
+      # - `humanInTheLoop`
+      # - `todoList`
+      # - `pii`, `piiRedaction`
+      #
+      # Keep the default empty so the lightweight direct host stays minimal.
       middleware: []
       # Upstream execution feature: system prompt for the lightweight direct-response host.
       # This prompt should keep the agent focused on:

package/dist/config/agents/orchestra.yaml

@@ -66,6 +66,16 @@ spec:
       # Upstream execution feature: no extra declarative HITL rules by default.
       interruptOn: {}
       # Upstream execution feature: no extra declarative middleware beyond upstream deepagents defaults by default.
+      # Common upstream middleware kinds that this harness can compile directly from YAML:
+      # - `patchToolCalls`
+      # - `summarization`
+      # - `dynamicSystemPrompt`
+      # - `humanInTheLoop`
+      # - `todoList`
+      # - `pii`, `piiRedaction`
+      #
+      # DeepAgents already includes its own filesystem, planning, subagent, and memory semantics.
+      # Keep this list empty unless you are intentionally adding extra upstream middleware on top.
       middleware: []
       # Upstream execution feature: keep the built-in general-purpose subagent enabled.
       generalPurposeAgent: true

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.54";
+export declare const AGENT_HARNESS_VERSION = "0.0.56";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.54";
+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;