@cydm/pie 1.0.6 → 1.0.7

package/README.md

@@ -4,8 +4,6 @@
 
 It gives you a terminal-first agent experience out of the box, while staying modular enough to embed into other runtimes and products. Pie is designed for teams that want a small surface area, strong defaults, persistent sessions, tool use, and a clean path from CLI usage to deeper integration.
 
-Pie is heavily inspired by `pi`, while evolving in its own direction around modularity, embeddability, and a compact developer-facing workflow.
-
 Pie is developed by [cydream](https://cydream.tech).
 
 ## Why Pie
@@ -22,6 +20,8 @@ Pie is developed by [cydream](https://cydream.tech).
 npm install -g @cydm/pie
 ```
 
+Pie supports Node.js 20 and newer. Release builds are validated with npm's lockfile workflow (`npm ci`) so dependency resolution is reproducible.
+
 ## Quick Start
 
 Set an API key for the provider you want to use:
@@ -38,6 +38,71 @@ You can also configure defaults in:
 - `~/.pie/models.json`
 - `~/.pie/config.json` for legacy-compatible defaults
 
+Minimal `~/.pie/models.json`:
+
+```json
+{
+  "profiles": {
+    "cy-gpt": {
+      "api": "openai-completions",
+      "baseUrl": "https://token.magicshell.ai/v1",
+      "apiKey": "YOUR_API_KEY",
+      "models": [
+        {
+          "id": "gpt-5.4",
+          "name": "GPT 5.4",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 128000,
+          "maxTokens": 16384,
+          "cost": {
+            "input": 0,
+            "output": 0,
+            "cacheRead": 0,
+            "cacheWrite": 0
+          }
+        }
+      ]
+    }
+  },
+  "defaults": {
+    "provider": "cy-gpt",
+    "modelId": "gpt-5.4"
+  }
+}
+```
+
+Required profile fields:
+
+- `api`
+- `baseUrl`
+- `apiKey` or `apiKeyEnv`
+- `models`
+
+Required model fields:
+
+- `id`
+- `input`
+- `cost`
+- `contextWindow`
+- `maxTokens`
+
+Validate the file explicitly:
+
+```bash
+pie models validate
+pie models validate --path /abs/path/to/models.json
+```
+
+Generate a starter template:
+
+```bash
+pie models init
+pie models init --stdout
+```
+
+For editor auto-complete and validation, you can also point the optional `"$schema"` field in your local `models.json` at your installed `@cydm/pie/models.schema.json` file.
+
 Start Pie in interactive mode:
 
 ```bash
@@ -113,6 +178,10 @@ Pie uses a hierarchical slash-command menu. The current built-in commands includ
 
 | Command | Description |
 | --- | --- |
+| `pie doctor [--json]` | Diagnose local config, model setup, writable paths, browser automation, and Unity bridge hints |
+| `pie models init` | Create a starter `~/.pie/models.json` |
+| `pie models validate` | Validate `~/.pie/models.json` |
+| `pie permissions` | Explain tool and shell safety defaults |
 | `/sessions/compact` | Summarize history and create a compact checkpoint |
 | `/sessions/new` | Start a new session |
 | `/sessions/resume` | Resume a different session |
@@ -130,9 +199,9 @@ Pie uses a hierarchical slash-command menu. The current built-in commands includ
 | `/skills/use` | Use a skill |
 | `/skills/reload` | Reload skills from disk |
 | `/tools/subagent` | Spawn a subagent for a task |
-| `/debugs/cache-test` | Test context caching |
-| `/debugs/context` | Dump raw context for debugging |
-| `/debugs/package` | Dump raw request and response payloads |
+| `/debugs/cache-test` | Run provider cache diagnostics with a dedicated 2-request probe |
+| `/debugs/context` | Append a context summary to `~/.pie/logs/pie-cli.log` |
+| `/debugs/package` | Append a package summary to `~/.pie/logs/pie-cli.log` |
 
 Pie can also load extension-provided commands at runtime.
 
@@ -158,6 +227,55 @@ Pie supports Markdown-based skills and built-in extensions.
 
 That is part of what makes Pie embeddable: the CLI is only one interface on top of a broader agent toolkit.
 
+## Browser Tools
+
+The built-in `browser-tools` skill uses Microsoft's Playwright CLI for visible browser automation. Its runtime dependencies ship with the CLI; do not run `npm install` inside the skill directory.
+
+Resolve the skill resource and run Playwright commands:
+
+```bash
+node <resolvedPath for browser-tools/playwright-cli.js> open https://example.com
+node <resolvedPath for browser-tools/playwright-cli.js> snapshot
+node <resolvedPath for browser-tools/playwright-cli.js> screenshot
+node <resolvedPath for browser-tools/playwright-cli.js> console
+node <resolvedPath for browser-tools/playwright-cli.js> network
+```
+
+If Playwright's Chromium browser is not installed, run:
+
+```bash
+node <resolvedPath for browser-tools/playwright-cli.js> install-browser chromium
+```
+
+Run `pie doctor` to check whether Playwright CLI and its browser runtime are discoverable.
+
+## Web Search
+
+Pie exposes a canonical `web_search` tool for public web research, current information, online documentation, and internet inspiration. Workspace search remains separate: use `grep_text`, `find_files`, and `list_dir` for local repository content.
+
+`web_search` uses provider-native web search where supported. It does not scrape DuckDuckGo or fall back to `bash` with `curl` or Python HTTP scripts. If the current provider/model cannot perform native web search, the tool returns a clear unavailable result with provider/configuration details.
+
+Use `web_fetch` after search when the agent needs to read a specific URL, documentation page, changelog, issue, or PDF. `web_fetch` follows redirects, extracts readable text/markdown, returns citation anchors and extraction diagnostics, and reports `requires_browser` for JavaScript-heavy pages instead of pretending the content was read.
+
+## Permissions
+
+Pie's default tools operate from the current workspace. File tools are workspace-scoped, `~/.pie` is allowlisted for Pie configuration/session support, and shell commands return structured timeout/truncation/error details. The canonical shell tool is still named `bash` for compatibility; on Windows `shell:auto` uses PowerShell, and callers can explicitly request `bash`, `powershell`, or `cmd`. High-risk shell commands require confirmation outside YOLO mode. `/settings/yolo` relaxes filesystem sandbox directory restrictions and should only be used in trusted workspaces. `pie permissions` prints the current policy-derived safety summary.
+
+## Code Intelligence
+
+`code_intel` provides read-only JS/TS diagnostics, definition, references, symbols, and hover. CLI uses the TypeScript language service by default and falls back to lightweight text analysis only when the TypeScript service cannot start. Unity uses a Node sidecar contract for TypeScript intelligence so the PuerTS bundle does not import Node-only parser dependencies.
+
+## Diagnostics
+
+Use:
+
+```bash
+pie doctor
+pie doctor --json
+```
+
+Doctor checks Node/npm, model configuration, API key availability, writable Pie data paths, Playwright browser readiness, Unity bridge hints, and runtime log location. User-facing errors stay concise; detailed debugging goes to `~/.pie/logs/pie-cli.log` and session trace artifacts.
+
 ## Output Modes
 
 For non-interactive usage, Pie supports structured output options:
@@ -179,12 +297,36 @@ For the best multiline editing experience, use a terminal with good modified-key
 ## Development
 
 ```bash
-cd products/cli
-npm install
-npm run build
-npm run test:offline
+npm ci
+npm run verify:quality
+npm run verify:release
+npm run verify:browser
+npm run verify:terminal:matrix
 ```
 
+Use `npm run verify:agent` when model credentials are available and you want the real daily agent gate.
+Use `npm run verify:agent:nightly` and `npm run verify:unity:reliability` before release candidates that claim real-provider or Unity reliability.
+Set `PIE_REAL_BROWSER=1` when you want `verify:browser` to open a real browser session instead of only checking the Playwright CLI contract.
+
+## Publishing
+
+Publish `@cydm/pie` from the monorepo root.
+
+Set the npm token first:
+
+```bash
+npm config set //registry.npmjs.org/:_authToken <YOUR_TOKEN>
+```
+
+Then publish:
+
+```bash
+npm run verify:release
+npm publish --workspace products/cli --access public
+```
+
+If the package version already exists on npm, bump `products/cli/package.json` first.
+
 ## License
 
 MIT

package/dist/builtin/extensions/ask-user/index.js

@@ -1,9 +1,8 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
   createAskUserCapability
-} from "../../../chunks/chunk-TBJ25UWB.js";
-import "../../../chunks/chunk-MWFBYJOI.js";
-import "../../../chunks/chunk-RID3574D.js";
+} from "../../../chunks/chunk-BHNULR7U.js";
+import "../../../chunks/chunk-A5JSJAPK.js";
 import "../../../chunks/chunk-TG2EQLX2.js";
 
 // builtin/extensions/ask-user/index.ts

package/dist/builtin/extensions/kimi-attachments/index.js

@@ -2,8 +2,8 @@ import { createRequire as __createRequire } from "node:module"; const require =
 import "../../../chunks/chunk-TG2EQLX2.js";
 
 // builtin/extensions/kimi-attachments/index.ts
-function isKimiProvider(provider) {
-  return provider === "kimi-cn" || provider === "kimi-api" || provider === "kimi";
+function isKimiAttachmentPlatform(model) {
+  return model.attachmentPlatform === "kimi" || model.filePlatform === "kimi";
 }
 function getModality(mimeType) {
   if (mimeType.startsWith("image/")) return "image";
@@ -16,7 +16,7 @@ function kimiAttachmentsExtension(ctx) {
     name: "kimi-native-attachments",
     priority: 100,
     matches(model, attachment) {
-      return isKimiProvider(model.provider) && Boolean(attachment.fileId) && getModality(attachment.mimeType) !== "file";
+      return isKimiAttachmentPlatform(model) && Boolean(attachment.fileId) && getModality(attachment.mimeType) !== "file";
     },
     async prepare(_model, attachment, prepareCtx) {
       const fileId = attachment.fileId;

package/dist/builtin/extensions/plan-mode/index.js

@@ -1,73 +1,74 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
-  PLAN_MODE_TOOL_NAMES,
+  buildExecutionReminder,
+  createExecutionStateFromPlan,
   createPlanCapability,
   extractPlanTodoItems,
   isPlanModeSafeCommand,
-  markCompletedPlanSteps
-} from "../../../chunks/chunk-TBJ25UWB.js";
-import "../../../chunks/chunk-MWFBYJOI.js";
-import "../../../chunks/chunk-RID3574D.js";
+  markCompletedPlanSteps,
+  restoreExecutionState
+} from "../../../chunks/chunk-BHNULR7U.js";
+import "../../../chunks/chunk-A5JSJAPK.js";
 import "../../../chunks/chunk-TG2EQLX2.js";
 
 // builtin/extensions/plan-mode/index.ts
 var SESSION_METADATA_KEY = "planModeEnabled";
+var EXECUTION_METADATA_KEY = "executionState";
 var planModeEnabled = false;
 var executionMode = false;
-var todoItems = [];
+function toPlanTodoItems(state) {
+  return state.steps.map((step) => ({
+    step: step.id,
+    text: step.title,
+    completed: step.status === "completed"
+  }));
+}
 function planModeExtension(ctx) {
-  ctx.log("Plan mode extension loaded");
   const capability = createPlanCapability();
   function readPersistedPlanMode() {
     return ctx.getSessionMetadata()?.[SESSION_METADATA_KEY] === true;
   }
+  function readExecutionState() {
+    return restoreExecutionState(ctx.getSessionMetadata()?.[EXECUTION_METADATA_KEY] ?? ctx.getExecutionState());
+  }
+  function writeExecutionState(state) {
+    const next = state ?? restoreExecutionState(null);
+    ctx.setSessionMetadata(EXECUTION_METADATA_KEY, next);
+    ctx.setExecutionState(next);
+    ctx.setExecutionReminder(buildExecutionReminder(next) ?? void 0);
+    return next;
+  }
   function updateStatus() {
-    if (executionMode && todoItems.length > 0) {
-      const completed = todoItems.filter((t) => t.completed).length;
-      ctx.ui.notify(`\u{1F4CB} Plan: ${completed}/${todoItems.length} completed`, "info");
+    const state = readExecutionState();
+    if (executionMode && state.steps.length > 0) {
+      const completed = state.steps.filter((step) => step.status === "completed").length;
+      ctx.ui.notify(`\u{1F4CB} Plan: ${completed}/${state.steps.length} completed`, "info");
     } else if (planModeEnabled) {
       ctx.ui.notify("\u23F8\uFE0F Plan mode active (read-only)", "info");
     }
   }
-  function getNormalModeTools() {
-    const allToolNames = ctx.getAllTools?.()?.map((tool) => tool?.name).filter((name) => typeof name === "string" && name.length > 0);
-    if (allToolNames && allToolNames.length > 0) {
-      return allToolNames;
+  function applyPlanModeState(enabled, forcePromptInjection = false) {
+    planModeEnabled = enabled;
+    if (!enabled) {
+      executionMode = false;
     }
-    return ["read", "bash", "edit", "write", "grep", "find", "ls", "ask_user_multi", "manage_todo_list"];
+    ctx.setPlanMode(enabled, { forcePromptInjection });
   }
   function togglePlanMode() {
     planModeEnabled = !planModeEnabled;
     executionMode = false;
-    todoItems = [];
+    writeExecutionState(null);
     ctx.setSessionMetadata(SESSION_METADATA_KEY, planModeEnabled);
-    ctx.setPlanMode(planModeEnabled);
-    if (planModeEnabled) {
-      ctx.setActiveTools([...PLAN_MODE_TOOL_NAMES]);
-      ctx.ui.notify(`Plan mode enabled. Available tools: ${PLAN_MODE_TOOL_NAMES.join(", ")}`);
-    } else {
-      ctx.setActiveTools(getNormalModeTools());
-      ctx.ui.notify("Plan mode disabled. Full access restored.");
-    }
-    updateStatus();
-  }
-  function applyPlanModeState(enabled, options = {}) {
-    planModeEnabled = enabled;
-    executionMode = false;
-    todoItems = [];
-    ctx.setPlanMode(enabled, { forcePromptInjection: options.forcePromptInjection });
-    ctx.setActiveTools(enabled ? [...PLAN_MODE_TOOL_NAMES] : getNormalModeTools());
-    if (options.notify) {
-      ctx.ui.notify(
-        enabled ? `Plan mode enabled. Available tools: ${PLAN_MODE_TOOL_NAMES.join(", ")}` : "Plan mode disabled. Full access restored."
-      );
-    }
+    applyPlanModeState(planModeEnabled, true);
+    ctx.ui.notify(
+      planModeEnabled ? `Plan mode enabled. Available tools: ${ctx.getActiveTools().join(", ")}` : "Plan mode disabled. Full access restored."
+    );
     updateStatus();
   }
   ctx.registerCommand({
     path: capability.commands?.[0]?.path ?? ["tools", "plan"],
     description: capability.commands?.[0]?.description ?? "Toggle plan mode (read-only exploration)",
-    handler: async (_ctx) => {
+    handler: async () => {
       togglePlanMode();
     }
   });
@@ -91,78 +92,75 @@ Command: ${command}`,
   });
   ctx.on("agent:start", async () => {
     const persisted = readPersistedPlanMode();
-    if (persisted !== planModeEnabled) {
-      applyPlanModeState(persisted);
-    }
-    if (planModeEnabled) {
-      ctx.log("[plan-mode] Injecting plan mode context");
-    }
+    applyPlanModeState(persisted);
+    writeExecutionState(readExecutionState());
   });
   ctx.on("session:changed", async () => {
     const enabled = readPersistedPlanMode();
-    applyPlanModeState(enabled, { forcePromptInjection: enabled });
+    applyPlanModeState(enabled, enabled);
+    writeExecutionState(readExecutionState());
   });
   ctx.on("turn:end", async (event) => {
-    if (!executionMode || todoItems.length === 0) return;
+    const state = readExecutionState();
+    if (!executionMode || state.steps.length === 0) return;
     const message = event.message;
-    if (message?.role === "assistant" && Array.isArray(message.content)) {
-      const text = message.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
-      if (markCompletedPlanSteps(text, todoItems) > 0) {
-        updateStatus();
-      }
-    }
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) return;
+    const text = message.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+    const todoItems = toPlanTodoItems(state);
+    if (markCompletedPlanSteps(text, todoItems) <= 0) return;
+    const nextState = createExecutionStateFromPlan(todoItems);
+    writeExecutionState(nextState);
+    updateStatus();
   });
   ctx.on("agent:end", async (event) => {
-    if (executionMode && todoItems.length > 0) {
-      if (todoItems.every((t) => t.completed)) {
-        const completedList = todoItems.map((t) => `\u2713 ${t.text}`).join("\n");
+    const state = readExecutionState();
+    if (executionMode && state.steps.length > 0) {
+      if (state.steps.every((step) => step.status === "completed")) {
+        const completedList = state.steps.map((step) => `\u2713 ${step.title}`).join("\n");
         ctx.ui.notify(`**Plan Complete!** \u2713
 
 ${completedList}`, "info");
         executionMode = false;
-        todoItems = [];
-        ctx.setActiveTools(getNormalModeTools());
+        writeExecutionState(null);
       }
       return;
     }
     if (!planModeEnabled || !ctx.hasUI) return;
     const messages = event.messages || [];
     const lastAssistant = [...messages].reverse().find(
-      (m) => m.role === "assistant" && Array.isArray(m.content)
+      (message) => message.role === "assistant" && Array.isArray(message.content)
     );
-    if (lastAssistant) {
-      const text = lastAssistant.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
-      const extracted = extractPlanTodoItems(text);
-      if (extracted.length > 0) {
-        todoItems = extracted;
-      }
-    }
-    if (todoItems.length > 0) {
-      const todoListText = todoItems.map((t) => `${t.step}. \u2610 ${t.text}`).join("\n");
-      ctx.ui.notify(`**Plan Steps (${todoItems.length}):**
+    if (!lastAssistant) return;
+    const text = lastAssistant.content.filter((item) => item.type === "text").map((item) => item.text).join("\n");
+    const extracted = extractPlanTodoItems(text);
+    if (extracted.length === 0) return;
+    const extractedState = writeExecutionState(createExecutionStateFromPlan(extracted));
+    const todoListText = extractedState.steps.map((step) => `${step.id}. \u2610 ${step.title}`).join("\n");
+    ctx.ui.notify(`**Plan Steps (${extractedState.steps.length}):**
 ${todoListText}`, "info");
-      const choice = await ctx.ui.select("Plan mode - what next?", [
-        todoItems.length > 0 ? "Execute the plan (track progress)" : "Execute the plan",
-        "Stay in plan mode",
-        "Refine the plan"
-      ]);
-      if (choice?.startsWith("Execute")) {
-        planModeEnabled = false;
-        executionMode = todoItems.length > 0;
-        ctx.setSessionMetadata(SESSION_METADATA_KEY, false);
-        ctx.setPlanMode(false);
-        ctx.setActiveTools(getNormalModeTools());
-        updateStatus();
-        const execMessage = todoItems.length > 0 ? `Execute the plan. Start with: ${todoItems[0].text}. Mark completed steps with [DONE:n] in your response.` : "Execute the plan you just created.";
-        ctx.sendUserMessage(execMessage);
-      } else if (choice === "Refine the plan") {
-        const refinement = await ctx.ui.editor("Refine the plan:", "");
-        if (refinement?.trim()) {
-          ctx.sendUserMessage(refinement.trim());
-        }
+    const choice = await ctx.ui.select("Plan mode - what next?", [
+      "Execute the plan (track progress)",
+      "Stay in plan mode",
+      "Refine the plan"
+    ]);
+    if (choice?.startsWith("Execute")) {
+      planModeEnabled = false;
+      executionMode = extractedState.steps.length > 0;
+      ctx.setSessionMetadata(SESSION_METADATA_KEY, false);
+      ctx.setPlanMode(false);
+      updateStatus();
+      const execMessage = extractedState.steps.length > 0 ? `Execute the plan. Start with: ${extractedState.steps[0].title}. Mark completed steps with [DONE:n] in your response.` : "Execute the plan you just created.";
+      ctx.sendUserMessage(execMessage);
+      return;
+    }
+    if (choice === "Refine the plan") {
+      const refinement = await ctx.ui.editor("Refine the plan:", "");
+      if (refinement?.trim()) {
+        ctx.sendUserMessage(refinement.trim());
       }
     }
   });
+  ctx.log("Plan mode extension loaded");
 }
 export {
   planModeExtension as default

package/dist/builtin/extensions/subagent/index.js

@@ -1,13 +1,15 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
   createCliHostCapabilities
-} from "../../../chunks/chunk-JYBXCEJJ.js";
+} from "../../../chunks/chunk-GDTN4UPJ.js";
 import {
+  createReadResourceCapability,
+  createReadSkillCapability,
+  createResolveResourceCapability,
   createSharedFileSystemTools,
   createSubagentCapability
-} from "../../../chunks/chunk-TBJ25UWB.js";
-import "../../../chunks/chunk-MWFBYJOI.js";
-import "../../../chunks/chunk-RID3574D.js";
+} from "../../../chunks/chunk-BHNULR7U.js";
+import "../../../chunks/chunk-A5JSJAPK.js";
 import "../../../chunks/chunk-TG2EQLX2.js";
 
 // builtin/extensions/subagent/index.ts
@@ -34,7 +36,7 @@ function subagentExtension(ctx) {
   let model = ctx.model;
   if (!model) {
     model = {
-      id: process.env.PIE_MODEL_ID || "kimi-cn/kimi-k2.5",
+      id: process.env.PIE_MODEL_ID || "kimi-api/kimi-k2.5",
       name: "Default Model",
       reasoning: false,
       input: ["text"],
@@ -56,12 +58,75 @@ function subagentExtension(ctx) {
     log: (message) => ctx.log(message),
     notify: ctx.hasUI ? (message, type) => ctx.ui.notify(message, type) : void 0,
     debugLog,
+    resolveModelClass: (modelClass) => ctx.resolveModelClass?.(modelClass),
     createRuntimeTools: () => {
-      const skillsDir = path.join(os.homedir(), ".pie", "skills");
-      const fsOptions = ctx.yoloMode ? { allowlistedDirs: ["/"] } : { allowlistedDirs: [skillsDir] };
+      const parentRuntimeTools = ctx.getRuntimeTools?.();
+      if (Array.isArray(parentRuntimeTools) && parentRuntimeTools.length > 0) {
+        return parentRuntimeTools.filter((tool) => tool?.name !== "spawn_subagents_parallel");
+      }
+      const configDir = path.join(os.homedir(), ".pie");
+      const fsOptions = ctx.yoloMode ? { allowlistedDirs: ["/"] } : { allowlistedDirs: [configDir] };
       const fsTools = createSharedFileSystemTools(ctx.cwd, fsOptions);
+      const readSkillTool = createReadSkillCapability({
+        resolveSkill(name) {
+          const skill = skills.find((entry) => entry.name === name);
+          if (!skill || !skill.filePath) {
+            return null;
+          }
+          const content = skill.content ?? fs.readFileSync(skill.filePath, "utf8");
+          return {
+            name: skill.name,
+            content,
+            resources: skill.resourceRefs
+          };
+        }
+      }).tool;
+      const readResourceTool = createReadResourceCapability({
+        resolveResource(owner, resourcePath) {
+          const skill = skills.find((entry) => entry.name === owner);
+          if (!skill) {
+            return null;
+          }
+          const trimmed = String(resourcePath || "").trim().replace(/\\/g, "/");
+          if (!trimmed || trimmed.startsWith("/") || /^[A-Za-z]:\//.test(trimmed)) {
+            return null;
+          }
+          const segments = trimmed.split("/").filter(Boolean);
+          if (segments.some((segment) => segment === "..")) {
+            return null;
+          }
+          const absolutePath = path.resolve(skill.baseDir, ...segments);
+          const relativePath = path.relative(skill.baseDir, absolutePath).replace(/\\/g, "/");
+          if (relativePath.startsWith("../") || relativePath === ".." || !fs.existsSync(absolutePath)) {
+            return null;
+          }
+          return {
+            owner: skill.name,
+            path: trimmed.replace(/^\.\/+/, ""),
+            content: fs.readFileSync(absolutePath, "utf8")
+          };
+        }
+      }).tool;
+      const resolveResourceTool = createResolveResourceCapability({
+        resolveResource(owner, resourcePath) {
+          const skill = skills.find((entry) => entry.name === owner);
+          if (!skill) return null;
+          const trimmed = String(resourcePath || "").trim().replace(/\\/g, "/");
+          if (!trimmed || trimmed.startsWith("/") || /^[A-Za-z]:\//.test(trimmed)) return null;
+          const segments = trimmed.split("/").filter(Boolean);
+          if (segments.some((segment) => segment === "..")) return null;
+          const absolutePath = path.resolve(skill.baseDir, ...segments);
+          const relativePath = path.relative(skill.baseDir, absolutePath).replace(/\\/g, "/");
+          if (relativePath.startsWith("../") || relativePath === ".." || !fs.existsSync(absolutePath)) return null;
+          return {
+            owner: skill.name,
+            path: trimmed.replace(/^\.\/+/, ""),
+            resolvedPath: absolutePath
+          };
+        }
+      }).tool;
       const cliHostCapabilities = createCliHostCapabilities(ctx.cwd);
-      return [...fsTools, ...cliHostCapabilities.tools];
+      return [...fsTools, readSkillTool, readResourceTool, resolveResourceTool, ...cliHostCapabilities.tools];
     }
   });
   for (const tool of capability.tools) {