slidev-addon-agent 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Bromann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# `slidev-addon-agent`
+
+Slidev addon components and a wrapper CLI for agent-powered slide authoring.
+
+## Setup
+
+### Prerequisites
+
+- Slidev: `@slidev/cli` and `vue` (peer dependencies).
+- LangGraph: `@langchain/langgraph` for the deep agent runtime.
+- Chat model: install one of `@langchain/openai`, `@langchain/anthropic`, or `@langchain/google`, and set the matching API key in the environment your LangGraph server uses.
+- Optional screenshot verification: install `playwright-chromium` in the Slidev project so the agent can export PNGs and visually review rendered slides.
+
+### Install
+
+In your Slidev project (or LangGraph app that bundles the agent):
+
+```bash
+# base setup
+pnpm add slidev-addon-agent @slidev/cli vue @langchain/langgraph
+# LLM provider
+pnpm add @langchain/openai   # or @langchain/anthropic / @langchain/google
+# optional: PNG screenshot verification during slide review
+pnpm add -D playwright-chromium
+```
+
+Add the addon to your Slidev project and render the components from root layer files:
+
+```vue
+<!-- global-top.vue -->
+<template>
+  <SlidevAgentSidebar v-if="!$nav.isPresenter" />
+</template>
+```
+
+```vue
+<!-- custom-nav-controls.vue -->
+<template>
+  <SlidevAgentNavButton v-if="!$nav.isPresenter" />
+</template>
+```
+
+### Agent environment variables
+
+The deep agent uses your project directory as the filesystem root (virtualMode) and bundled Slidev skills when those paths are reachable. Set these in `.env` (or your LangGraph deployment) for the **server** that runs the graph:
+
+| Variable | Purpose |
+| ---------- | --------- |
+| `SLIDEV_AGENT_MODEL` | Model id, e.g. `openai:gpt-5.4`, `anthropic:claude-sonnet-4-6`. |
+| `SLIDEV_AGENT_REVIEW_MODEL` | Optional override for screenshot review; defaults to `SLIDEV_AGENT_MODEL` and should be a vision-capable model. |
+| `SLIDEV_AGENT_SYSTEM_PROMPT` | Replaces the default system prompt when set. |
+| `SLIDEV_AGENT_ROOT_DIR` | Filesystem root for deck files (defaults to `process.cwd()`). |
+| `SLIDEV_AGENT_SKILLS_PATH` | Comma-separated extra skill directories (POSIX paths relative to the backend root). |
+| `SLIDEV_AGENT_DISABLE_LANGGRAPH` | Set to `1` to skip spawning `langgraph dev` alongside Slidev when using `slidev-agent dev`. |

package/agent/constants.ts

@@ -0,0 +1,119 @@
+/**
+ * Default system prompt for the Slidev orchestrator agent.
+ * Overridden entirely when `SLIDEV_AGENT_SYSTEM_PROMPT` is set.
+ */
+export const SLIDEV_AGENT_DEFAULT_SYSTEM_PROMPT = `
+You are Slidev Agent, an expert presentation author for Slidev decks.
+
+## Skill usage
+- You have a **slidev** skill in your skills library (metadata is injected below).
+- For non-trivial slides or Slidev features (animations, code blocks, diagrams, layouts, export), read that skill's SKILL.md with read_file first, then open specific files under its references/ folder as needed instead of guessing syntax.
+
+## Core operating model
+- Your job is to create and revise deck files directly in the local Slidev project filesystem.
+- Treat the filesystem as the source of truth for deck content.
+- When asked to make deck changes, inspect current files first.
+
+## Path rule
+- Filesystem tools such as \`read_file\`, \`write_file\`, and \`edit_file\` are rooted at the agent project root, not the host machine root.
+- Use project-root-relative paths like \`/slides.md\`, \`/example/slides.md\`, or \`/pages/foo.md\`.
+- Never pass host OS paths like \`/Users/christian/.../slides.md\` to those file tools.
+
+## Authoring rules
+- Prefer editing existing files over creating many new files when possible, but do not force large amounts of content into a single giant slide file.
+- Use Slidev-compatible markdown, frontmatter, layouts, and Vue component syntax.
+- Prefer native markdown syntax over raw HTML whenever possible.
+- Only use HTML or custom Vue markup when markdown or built-in Slidev features cannot express the layout, because ad-hoc HTML is prone to missing closing tags and other render errors.
+
+## Deck shell vs. slide content
+- You edit the **deck shell** yourself, such as \`/slides.md\` imports, front matter, \`/components\`, \`/snippets\`, and shared assets.
+- You **never** write or edit slide **content** files yourself.
+- **Always** use the \`task\` tool with \`slide_generator\` to create or change slide content.
+- Any new slide file, any new slide under \`/pages\` (or similar), or any change to the markdown body of an existing slide file must go through the subagent.
+- Do not use \`write_file\`, \`edit_file\`, or equivalent on those slide bodies yourself.
+- Spawn one \`slide_generator\` task per slide file, and parallelize when the user asks for multiple slides.
+
+## Subagent coordination
+- When you spin up subagents or describe that work to the user, keep it brief but playful: warm and a little theatrical (for example, assembling a tiny slide squad, handing off to specialists, or cueing the next slide), not stiff or purely procedural.
+- Keep deck structure coherent, with a main entry file such as \`/slides.md\` and supporting slide files under \`/pages\`.
+- Use Slidev's importing-slides pattern (\`src: ./pages/file.md\`) to stitch subagent output into the main deck instead of streaming everything into one file.
+- The \`slide_generator\` subagent creates exactly one slide file per task, typically in \`/pages\`.
+- After subagents finish, you are responsible for updating \`/slides.md\` (or the entry deck) to import or embed those files correctly.
+- When multiple slides are needed, launch several \`slide_generator\` tasks in parallel rather than one long write.
+
+## Verification and navigation
+- After importing a new slide into \`slides.md\`, include its 1-based slide URL index in each \`slide_generator\` task so that the subagent can export a PNG screenshot of the rendered slide, visually review that image, and fix only clearly broken layout or readability issues before returning.
+- When revising an existing slide file that is already imported into the deck, keep its existing 1-based slide index. Editing a slide does not create a new index.
+- Only include a slide index in a \`slide_generator\` task when you know it from the fully assembled deck after imports and ordering are finalized.
+- If there is any uncertainty about the current deck length, recount from the fully assembled deck instead of guessing or clamping the index.
+- Keep that verification loop short: the \`slide_generator\` should do at most 2 screenshot review passes total, then stop and report any remaining limitation.
+- Verification is intentionally lenient: minor spacing, alignment, or stylistic polish issues are acceptable. Only treat the slide as failing review when it looks broken, unreadable, or clearly misrendered.
+- You do not run those checks yourself; render verification is the \`slide_generator\`'s responsibility.
+- When you create a new slide and know its final 1-based index in the deck, call the tool \`slidev_go_to_slide\` so the user's Slidev preview automatically jumps to that slide.
+- Only call \`slidev_go_to_slide\` after imports and ordering are finalized so you navigate to the correct page.
+
+## Final response
+- Explain major file changes briefly to the user after you finish.
+`.trim()
+
+/** Shown to the model for \`task\` tool selection (slide_generator). */
+export const SLIDEV_SLIDE_GENERATOR_SUBAGENT_DESCRIPTION = `Create or redesign exactly one Slidev slide file at a requested path so the orchestrator can parallelize multi-slide work. When the slide's URL index is known, export a PNG screenshot with Slidev and use a screenshot review tool to catch clearly broken rendering or readability issues.`
+
+/** System prompt for the slide_generator subagent. */
+export const SLIDEV_SLIDE_GENERATOR_SYSTEM_PROMPT = `
+You are a specialized Slidev slide generation subagent.
+
+## Skill usage
+- Use the **slidev** skill from your skills list: read its SKILL.md, then \`references/*.md\` for the features you implement (animations, code, diagrams, layouts).
+
+## Scope
+- Your responsibility is to create or revise exactly one slide file at the path requested by the orchestrator.
+- Produce one focused slide or imported slide fragment, not the entire deck.
+- Do not update the main deck entry file such as \`/slides.md\` unless explicitly asked; the orchestrator will stitch your slide into the deck.
+
+## Path rule
+- Filesystem tool paths are project-root-relative.
+- For \`read_file\`, \`write_file\`, and \`edit_file\`, use paths like \`/example/slides.md\` or \`/pages/foo.md\`, never host OS paths like \`/Users/...\`.
+
+## Slide design rules
+- Slide space is limited: each slide is only a fixed viewport, so packing too much onto one frame causes clutter, tiny text, or overflow.
+- Prefer native markdown over raw HTML for headings, lists, emphasis, tables, blockquotes, and simple layouts.
+- Prefer a small number of ideas per slide.
+- When you have lots of bullets, diagrams, code, or tables, split the material across multiple slides or use Slidev subslides / click-step patterns (\`v-click\` and similar) instead of one overloaded slide.
+- Avoid cramming diagrams, dense grids, and long bullet lists onto a single slide; add more slides or subslides rather than shrinking everything to fit.
+- Keep the output self-contained so it can be imported cleanly from the main deck with \`src: ./pages/...\`.
+- Use valid Slidev markdown, frontmatter, layouts, components, and animations when they improve clarity.
+- Reach for HTML or Vue markup only when markdown and built-in Slidev features are insufficient, since raw HTML often introduces missing closing tags and other brittle syntax mistakes.
+
+## Screenshot verification
+
+- When the task gives a 1-based slide index, you MUST verify the rendered slide before finishing. Do not skip only because the markdown looks fine.
+- If you are revising an existing slide file that is already imported into the deck, its slide index usually stays the same.
+- Prefer Slidev's PNG export flow over browser automation. This does not require the dev server to be open in a browser tab.
+- You have a dedicated tool named \`slidev_export_screenshot\`, which exports the requested slide to a PNG from the correct deck directory. Use that tool as the default export path instead of composing shell commands yourself.
+- You also have the tool \`slidev_review_screenshot\`, which sends the exported image to a multimodal model for actual visual review. Use that tool instead of claiming you inspected a local PNG directly in text.
+- You also have the standard \`execute\` tool. Use \`execute\` for screenshot export only as a debugging fallback if \`slidev_export_screenshot\` itself fails.
+- **Prerequisites:** \`slidev-agent\` / Slidev CLI available from the project root, and \`playwright-chromium\` installed where Slidev can resolve it. If PNG export fails because Playwright is missing, say that explicitly and ask for \`pnpm add -D playwright-chromium\`.
+- This review is a coarse quality gate, not pixel-perfect design critique. Ignore minor spacing, alignment, or aesthetic polish issues unless they make the slide look broken or hard to read.
+- Only fail verification for obvious breakage such as clipped or missing content, severe overflow, overlapping elements, unreadably tiny text, broken wrapping, or other rendering problems that materially hurt readability.
+
+Typical sequence:
+
+1. Call \`slidev_export_screenshot\` with the slide index. Omit \`outputDir\` unless you need a special project-local folder.
+2. Pass the returned PNG path to \`slidev_review_screenshot\`.
+3. Treat the review tool's result as the visual review. Focus on obvious breakage such as clipped content, severe overflow, overlapping elements, unreadably tiny text, broken wrapping, missing content, or contrast problems that make the slide hard to read.
+4. If the tool reports only minor stylistic issues, accept the slide as passing. If it reports clear breakage, revise the slide and re-run export and screenshot review at most once. Do no more than 2 screenshot review passes total, then stop and explain any remaining limitation instead of looping further.
+
+## Verification edge cases
+- Counting rule: the screenshot tool expects the slide's final 1-based URL index in the fully assembled deck. Recount after imports or ordering changes; do not assume a new file automatically means "the next slide number".
+- If \`slidev_export_screenshot\` reports that the deck has fewer slides than requested, or that it produced no PNGs, stop and report an index/import mismatch instead of retrying the same export loop.
+- Important path rule for debugging: filesystem tools and shell paths are different. For file tools, \`/pages/foo.md\` or \`/slides.md\` means a path relative to the agent project root. For \`execute\`, those same strings are interpreted as host filesystem paths and are usually wrong. If you must use \`execute\`, stay in the current deck working directory, use cwd-relative paths like \`./.slidev-agent-artifacts/...\`, and never use \`/.slidev-agent-artifacts\`, \`/pages\`, or \`pnpm --prefix /\` unless the project truly lives at filesystem root.
+- If the screenshot review tool fails because no review model is configured or the model cannot accept images, still generate the PNG and say that screenshot export succeeded but AI visual review was unavailable in this environment.
+- If the slide is not yet imported into \`slides.md\` or no slide number is given, skip screenshot verification and say so; ask the orchestrator to import it and re-invoke you with the 1-based index.
+
+## Final report
+- When finished, report the file path you touched, a concise description of the slide, and whether screenshot verification passed, was skipped, or only exported an image without visual review.
+- If you stopped because the 2-pass review limit was reached, say that explicitly.
+- If verification ran, report which slide index you checked and whether it passed.
+- If you know the index but skipped verification, say that explicitly instead of inventing a preview link.
+`.trim()

package/agent/deck-context.ts

@@ -0,0 +1,67 @@
+import fs from "node:fs"
+import path from "node:path"
+
+import { env } from "../lib/env.js"
+
+type PackageJsonWithScripts = {
+  scripts?: Record<string, unknown>
+}
+
+export function normalizeProjectRelativePath(filePath: string) {
+  const normalized = filePath.replaceAll(path.sep, "/").replace(/^\/+/, "")
+  return normalized || "."
+}
+
+function readPackageJson(packageJsonPath: string): PackageJsonWithScripts | null {
+  try {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as PackageJsonWithScripts
+  }
+  catch {
+    return null
+  }
+}
+
+export function readPackageScript(rootDir: string, scriptName: string) {
+  const packageJson = readPackageJson(path.join(rootDir, "package.json"))
+  const script = packageJson?.scripts?.[scriptName]
+  return typeof script === "string" && script.trim() ? script.trim() : null
+}
+
+export function extractWorkingDirFromScript(script: string) {
+  const pnpmDirMatch = script.match(/(?:^|\s)pnpm\s+(?:--dir|-C)\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))/)
+  const cdMatch = script.match(/(?:^|\s)cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&]+))/)
+  const workingDir = pnpmDirMatch?.[1] || pnpmDirMatch?.[2] || pnpmDirMatch?.[3] || cdMatch?.[1] || cdMatch?.[2] || cdMatch?.[3]
+  return workingDir ? normalizeProjectRelativePath(workingDir) : null
+}
+
+export type SlidevDeckExecutionContext = {
+  rootDir: string
+  configuredEntry: string
+  deckDir: string
+  deckHostDir: string
+  entryPath: string
+  rootExportScript: string | null
+}
+
+export function resolveDeckExecutionContext(rootDir: string): SlidevDeckExecutionContext {
+  const configuredEntry = normalizeProjectRelativePath(env(process.env, "SLIDEV_AGENT_ENTRY", "slides.md"))
+  const configuredEntryDir = path.posix.dirname(configuredEntry)
+  const rootExportScript = readPackageScript(rootDir, "export")
+  const inferredDeckDir = rootExportScript ? extractWorkingDirFromScript(rootExportScript) : null
+  const deckDir = configuredEntryDir !== "." ? configuredEntryDir : inferredDeckDir || "."
+  const deckHostDir = deckDir === "."
+    ? rootDir
+    : path.resolve(rootDir, deckDir)
+  const entryPath = configuredEntryDir !== "."
+    ? path.resolve(rootDir, configuredEntry)
+    : path.resolve(deckHostDir, configuredEntry)
+
+  return {
+    rootDir,
+    configuredEntry,
+    deckDir,
+    deckHostDir,
+    entryPath,
+    rootExportScript,
+  }
+}

package/agent/index.ts

@@ -0,0 +1,201 @@
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { createDeepAgent, LocalShellBackend } from "deepagents"
+import { dynamicSystemPromptMiddleware } from "langchain"
+import { z } from "zod"
+
+import { createFilesystemPathGuardMiddleware } from "./middleware.js"
+import { model, env } from "../lib/env.js"
+import { slidevGoToSlide } from "../lib/headless-tools.js"
+
+import { resolveDeckExecutionContext } from "./deck-context.js"
+import { createSlidevExportScreenshotTool } from "./tools/export-tool.js"
+import { createSlidevReviewScreenshotTool } from "./tools/review-tool.js"
+import {
+  SLIDEV_AGENT_DEFAULT_SYSTEM_PROMPT,
+  SLIDEV_SLIDE_GENERATOR_SUBAGENT_DESCRIPTION,
+  SLIDEV_SLIDE_GENERATOR_SYSTEM_PROMPT,
+} from "./constants.js"
+
+type SlidevDeepAgentOptions = {
+  model?: string
+  systemPrompt?: string
+  rootDir?: string
+  virtualMode?: boolean
+  skills?: string[]
+}
+
+export const slidevAgentContextSchema = z.object({
+  currentSlide: z.object({
+    page: z.number().optional(),
+    layout: z.string().optional(),
+    route: z.string().optional(),
+    title: z.string().optional(),
+  }).optional(),
+})
+
+function resolveSystemPrompt(): string {
+  const customPrompt = env(process.env, "SLIDEV_AGENT_SYSTEM_PROMPT")
+  if (customPrompt)
+    return customPrompt
+
+  return SLIDEV_AGENT_DEFAULT_SYSTEM_PROMPT
+}
+
+function normalizeSkillPath(skillPath: string): string {
+  if (!skillPath)
+    return skillPath
+
+  const normalized = skillPath.replaceAll(path.sep, "/")
+  return normalized.startsWith("/") ? normalized : `/${normalized}`
+}
+
+function resolveSlidevSkillPaths(rootDir: string): string[] {
+  const explicitSkillsPath = env(process.env, "SLIDEV_AGENT_SKILLS_PATH")
+  if (explicitSkillsPath) {
+    return explicitSkillsPath
+      .split(",")
+      .map(entry => entry.trim())
+      .filter(Boolean)
+      .map(normalizeSkillPath)
+  }
+
+  const packagedSkillsDir = fileURLToPath(new URL("./skills", import.meta.url))
+  const relativeSkillsDir = path.relative(rootDir, packagedSkillsDir)
+
+  if (relativeSkillsDir.startsWith(".."))
+    return []
+
+  return [normalizeSkillPath(relativeSkillsDir)]
+}
+
+function buildSlideGeneratorRuntimePrompt(rootDir: string) {
+  const deckContext = resolveDeckExecutionContext(rootDir)
+  const deckHostDir = deckContext.deckHostDir
+  const entryPath = deckContext.entryPath
+  const artifactDir = path.join(deckHostDir, ".slidev-agent-artifacts", "verify-<slideIndex>")
+  const generatedImagePath = path.join(artifactDir, "<generated-file>.png")
+  const reviewImageRelativePath = deckContext.deckDir === "."
+    ? `.slidev-agent-artifacts/verify-<slideIndex>/<generated-file>.png`
+    : `${deckContext.deckDir}/.slidev-agent-artifacts/verify-<slideIndex>/<generated-file>.png`
+  const directExportCommand = [
+    `cd "${deckHostDir}"`,
+    "mkdir -p .slidev-agent-artifacts/verify-<slideIndex> &&",
+    "pnpm exec slidev-agent export",
+    "--format png",
+    "--range <slideIndex>",
+    "--per-slide",
+    "--output ./.slidev-agent-artifacts/verify-<slideIndex>",
+    "--timeout 60000",
+    "--wait 500",
+    "--scale 1",
+  ].join(" ")
+  const rootScriptExportCommand = deckContext.rootExportScript
+    ? [
+        `cd "${rootDir}"`,
+        "pnpm export --",
+        "--format png",
+        "--range <slideIndex>",
+        "--per-slide",
+        "--output ./.slidev-agent-artifacts/verify-<slideIndex>",
+        "--timeout 60000",
+        "--wait 500",
+        "--scale 1",
+      ].join(" ")
+    : null
+
+  const lines = [
+    "## Runtime deck execution context",
+    "Filesystem tools are rooted at the agent project root. Use project-relative paths like `/example/slides.md` there, never host paths like `/Users/.../example/slides.md`.",
+    `Inside \`execute\`, paths like \`/\` refer to the real host filesystem root. Do not treat \`/\` as a virtual project root.`,
+    `Agent root for this run: \`${rootDir}\`.`,
+    `Configured Slidev entry for this run: \`${entryPath}\`.`,
+    `Runnable deck package directory for exports: \`${deckHostDir}\`. Always run export there unless you are intentionally invoking a wrapper script from \`${rootDir}\`.`,
+    "For screenshot export, use the dedicated `slidev_export_screenshot` tool first instead of hand-writing shell commands.",
+    "If there is any uncertainty about the current assembled deck length after imports or reordering, recount from the fully assembled deck before choosing a validation index. Do not guess or clamp the index.",
+    "When revising an existing slide file that is already imported into the deck, its validation index usually stays the same. Do not add 1 just because you edited the file.",
+    `If you need to debug manually, this is the known-good fallback command: \`${directExportCommand}\`.`,
+    rootScriptExportCommand
+      ? `Optional root-package wrapper command: \`${rootScriptExportCommand}\`. Use it only if you specifically want the root package script.`
+      : "",
+    "The `execute` shell starts in the deck package directory already. Keep export commands cwd-relative and do not `cd /` before exporting.",
+    `Write export artifacts under \`${artifactDir}\` using a relative path like \`./.slidev-agent-artifacts/...\` or that full host path.`,
+    "Never use `/.slidev-agent-artifacts`, `pnpm --prefix /`, or any other host-root path unless the project itself actually lives at filesystem root.",
+    "Logical project paths such as `/pages/foo.md` or `/slides.md` are for filesystem tools, not shell paths. For `execute`, strip the leading slash and use cwd-relative paths instead.",
+    `When calling \`slidev_review_screenshot\`, prefer the real host PNG path \`${generatedImagePath}\`. A root-relative alternative within the agent root is \`${reviewImageRelativePath}\`.`,
+    "If screenshot export says the deck has fewer slides than requested, or says it produced no PNGs, your slide index is wrong or the slide is not imported into the final deck yet. Fix the deck/import/index mismatch before retrying.",
+    "Do not scan `/Users`, `/node_modules`, or the whole filesystem to locate Slidev once the deck context above is available.",
+  ].filter(Boolean)
+
+  return lines.join("\n")
+}
+
+export function createSlidevDeepAgent(options: SlidevDeepAgentOptions = {}) {
+  const systemPrompt = options.systemPrompt || resolveSystemPrompt()
+  const rootDir = options.rootDir
+    ? path.resolve(options.rootDir)
+    : path.resolve(env(process.env, "SLIDEV_AGENT_ROOT_DIR") || process.cwd())
+
+  const skills = options.skills || resolveSlidevSkillPaths(rootDir)
+  const filesystemPathGuardMiddleware = createFilesystemPathGuardMiddleware(rootDir)
+  const slidevExportScreenshot = createSlidevExportScreenshotTool(path.resolve(rootDir))
+  const slidevReviewScreenshot = createSlidevReviewScreenshotTool(path.resolve(rootDir))
+  const slideGeneratorSystemPrompt = [
+    SLIDEV_SLIDE_GENERATOR_SYSTEM_PROMPT,
+    buildSlideGeneratorRuntimePrompt(rootDir),
+  ].join("\n\n")
+
+  fs.mkdirSync(rootDir, { recursive: true })
+  if (!model) {
+    throw new Error("No model or API key is configured. Set `SLIDEV_AGENT_MODEL` or `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, or `OPENAI_API_KEY` to a valid API key.")
+  }
+
+  return createDeepAgent({
+    model,
+    systemPrompt,
+    tools: [
+      slidevGoToSlide,
+      slidevExportScreenshot,
+      slidevReviewScreenshot
+    ],
+    ...(skills.length > 0 ? { skills } : {}),
+    subagents: [
+      {
+        name: "slide_generator",
+        description: SLIDEV_SLIDE_GENERATOR_SUBAGENT_DESCRIPTION,
+        systemPrompt: slideGeneratorSystemPrompt,
+        middleware: [filesystemPathGuardMiddleware],
+        ...(skills.length > 0 ? { skills } : {}),
+      },
+    ],
+    contextSchema: slidevAgentContextSchema,
+    middleware: [
+      filesystemPathGuardMiddleware,
+      dynamicSystemPromptMiddleware((_state, runtime) => {
+        const context = (runtime.context ?? {}) as z.infer<typeof slidevAgentContextSchema>
+        const currentSlide = context.currentSlide
+        if (!currentSlide)
+          return ""
+
+        const details = [
+          currentSlide.page ? `Current visible slide number: ${currentSlide.page}.` : "",
+          currentSlide.layout ? `Current slide layout: ${currentSlide.layout}.` : "",
+          currentSlide.route ? `Current slide route: ${currentSlide.route}.` : "",
+          currentSlide.title ? `Current slide title: ${currentSlide.title}.` : "",
+          "Use this as strong context when the user asks to update or extend the current slide.",
+        ].filter(Boolean)
+
+        return details.join("\n")
+      }),
+    ],
+    backend: new LocalShellBackend({
+      rootDir,
+      virtualMode: options.virtualMode ?? true,
+      inheritEnv: true,
+    }),
+  })
+}
+
+export const agent = createSlidevDeepAgent()

package/agent/middleware.ts

@@ -0,0 +1,163 @@
+import path from "node:path"
+
+import { createMiddleware, ToolMessage } from "langchain"
+
+const FILESYSTEM_TOOL_NAMES = new Set([
+  "ls",
+  "read_file",
+  "write_file",
+  "edit_file",
+  "glob",
+  "grep",
+])
+
+const SINGLE_PATH_ARG_KEYS = ["path", "file_path"] as const
+const ARRAY_PATH_ARG_KEYS = ["paths"] as const
+const HOST_ABSOLUTE_PREFIXES = [
+  "/Users/",
+  "/private/",
+  "/var/",
+  "/tmp/",
+  "/etc/",
+  "/opt/",
+  "/Volumes/",
+  "/home/",
+]
+const HOST_RELATIVE_PREFIXES = HOST_ABSOLUTE_PREFIXES.map(prefix => prefix.slice(1))
+
+function isWithinRoot(rootDir: string, candidatePath: string) {
+  const relativePath = path.relative(rootDir, candidatePath)
+  return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))
+}
+
+function toProjectRelativePath(rootDir: string, candidatePath: string) {
+  const relativePath = path.relative(rootDir, candidatePath).replaceAll(path.sep, "/")
+  return relativePath ? `/${relativePath}` : "/"
+}
+
+function looksLikeHostAbsolutePath(value: string) {
+  return HOST_ABSOLUTE_PREFIXES.some(prefix => value.startsWith(prefix))
+}
+
+function looksLikeMissingLeadingSlashHostPath(value: string) {
+  return HOST_RELATIVE_PREFIXES.some(prefix => value.startsWith(prefix))
+}
+
+function normalizeFilesystemPath(rootDir: string, rawValue: string) {
+  const value = rawValue.trim()
+  if (!value)
+    return { normalized: rawValue, error: null }
+
+  if (looksLikeHostAbsolutePath(value)) {
+    const candidatePath = path.resolve(value)
+    if (isWithinRoot(rootDir, candidatePath)) {
+      return { normalized: toProjectRelativePath(rootDir, candidatePath), error: null }
+    }
+
+    return {
+      normalized: rawValue,
+      error: [
+        `Filesystem tools are rooted at the agent project, so host absolute paths are not allowed here: ${value}`,
+        "Use a project-root-relative path such as `/slides.md`, `/pages/foo.md`, or `/example/slides.md` instead.",
+      ].join("\n"),
+    }
+  }
+
+  if (looksLikeMissingLeadingSlashHostPath(value)) {
+    const candidatePath = path.resolve(path.sep, value)
+    if (isWithinRoot(rootDir, candidatePath))
+      return { normalized: toProjectRelativePath(rootDir, candidatePath), error: null }
+
+    return {
+      normalized: rawValue,
+      error: [
+        `Filesystem tools received a host-style path instead of a project-relative path: ${value}`,
+        "Use a project-root-relative path such as `/slides.md`, `/pages/foo.md`, or `/example/slides.md` instead.",
+      ].join("\n"),
+    }
+  }
+
+  return { normalized: rawValue, error: null }
+}
+
+function toolErrorMessage(toolCallId: string | undefined, content: string) {
+  return new ToolMessage({
+    content,
+    tool_call_id: toolCallId || "",
+  })
+}
+
+export function createFilesystemPathGuardMiddleware(rootDir: string) {
+  const absoluteRootDir = path.resolve(rootDir)
+
+  return createMiddleware({
+    name: "FilesystemPathGuardMiddleware",
+    wrapToolCall: async (request, handler) => {
+      const { toolCall } = request
+      const { args: rawArgs, id: toolCallId, name: toolName } = toolCall
+
+      if (!FILESYSTEM_TOOL_NAMES.has(toolName)) {
+        return handler(request)
+      }
+
+      if (!rawArgs || typeof rawArgs !== "object" || Array.isArray(rawArgs)) {
+        return handler(request)
+      }
+
+      let changed = false
+      const nextArgs: Record<string, unknown> = { ...rawArgs as Record<string, unknown> }
+
+      for (const key of SINGLE_PATH_ARG_KEYS) {
+        const value = nextArgs[key]
+        if (typeof value !== "string")
+          continue
+
+        const { normalized, error } = normalizeFilesystemPath(absoluteRootDir, value)
+        if (error) {
+          return toolErrorMessage(toolCallId, error)
+        }
+
+        if (normalized !== value) {
+          nextArgs[key] = normalized
+          changed = true
+        }
+      }
+
+      for (const key of ARRAY_PATH_ARG_KEYS) {
+        const value = nextArgs[key]
+        if (!Array.isArray(value))
+          continue
+
+        const normalizedPaths: unknown[] = []
+        for (const entry of value) {
+          if (typeof entry !== "string") {
+            normalizedPaths.push(entry)
+            continue
+          }
+
+          const { normalized, error } = normalizeFilesystemPath(absoluteRootDir, entry)
+          if (error) {
+            return toolErrorMessage(toolCallId, error)
+          }
+
+          normalizedPaths.push(normalized)
+          if (normalized !== entry)
+            changed = true
+        }
+
+        nextArgs[key] = normalizedPaths
+      }
+
+      if (!changed)
+        return handler(request)
+
+      return handler({
+        ...request,
+        toolCall: {
+          ...toolCall,
+          args: nextArgs,
+        },
+      })
+    },
+  })
+}