pindeck 2.9.0 → 3.0.0-beta.2

package/lib/agent-process.mjs

@@ -0,0 +1,53 @@
+/* JSON-line subprocess transport. Requests and notifications never outlive their process. */
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+export class AgentProcess {
+  constructor({ binary, args, cwd, env, onMessage = () => {}, onExit = () => {}, onStderr = () => {} }) {
+    Object.assign(this, { onMessage, onExit });
+    this.pending = new Map(); this.seq = 0; this.closed = false; this.stderr = '';
+    this.proc = spawn(binary, args, { cwd, env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.exited = new Promise(resolve => this.proc.once('close', resolve).once('error', () => this.proc.pid === undefined && resolve()));
+    readline.createInterface({ input: this.proc.stdout }).on('line', line => {
+      if (this.closed) return;
+      let m; try { m = JSON.parse(line); } catch { return; }
+      const id = m.type === 'control_response' ? m.response?.request_id : m.id;
+      const pending = this.pending.get(id);
+      if (pending && (m.type === 'control_response' || !m.method)) {
+        this.pending.delete(id); clearTimeout(pending.timer);
+        const err = m.error || (m.response?.subtype === 'error' && m.response.error);
+        if (err) pending.reject(new Error(err.message || String(err)));
+        else pending.resolve(m.type === 'control_response' ? m.response.response : m.result);
+      } else this.onMessage(m);
+    });
+    this.proc.stderr.on('data', d => { this.stderr = (this.stderr + d).slice(-2000); onStderr(String(d)); });
+    this.proc.stdin.on('error', e => this.end(e));
+    this.proc.on('error', e => this.end(e));
+    this.proc.on('exit', (code, signal) => this.end(new Error(`Agent stopped (${signal || code}). ${this.stderr.trim()}`)));
+  }
+  write(value) { if (this.closed) throw new Error('Agent is not running.'); this.proc.stdin.write(JSON.stringify(value) + '\n'); }
+  request(method, params, { claude = false, timeout = 30000 } = {}) {
+    const id = claude ? `pindeck-${++this.seq}` : ++this.seq;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Agent timed out: ${method}`)); }, timeout);
+      this.pending.set(id, { resolve, reject, timer });
+      try { this.write(claude ? { type: 'control_request', request_id: id, request: { subtype: method, ...params } } : { id, method, params }); }
+      catch (e) { clearTimeout(timer); this.pending.delete(id); reject(e); }
+    });
+  }
+  end(error) {
+    if (this.closed) return;
+    this.closed = true;
+    for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); }
+    this.pending.clear(); this.onExit(error);
+  }
+  /* End of input first (the CLI finishes and exits), SIGTERM after 1.5 s, SIGKILL after 4 s.
+     Resolves once the process has exited, so shutdown can wait for it. */
+  stop() {
+    this.end(new Error('Agent stopped.'));
+    const proc = this.proc;
+    if (proc.exitCode !== null || proc.signalCode !== null || proc.pid === undefined) return Promise.resolve();
+    proc.stdin.end();
+    const term = setTimeout(() => proc.kill('SIGTERM'), 1500), kill = setTimeout(() => proc.kill('SIGKILL'), 4000);
+    return this.exited.finally(() => { clearTimeout(term); clearTimeout(kill); });
+  }
+}

package/lib/agent-tools.mjs

@@ -0,0 +1,108 @@
+/* All Codex writes pass through this host-owned bridge, never through a shell. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeAtomic } from './deck-files.mjs';
+const exec = promisify(execFile);
+const text = value => ({ type: 'inputText', text: String(value) });
+const schema = properties => ({ type: 'object', properties, additionalProperties: false });
+const str = { type: 'string' };
+export const renderedImagePath = result => result.match(/^(.+\.png) \(\d+ × \d+ px\)/m)?.[1];
+export const deckTools = [
+  { type: 'function', name: 'pindeck_read', description: 'Read a deck text file, attached image, screenshot, or PDF page. For PDFs supply a 1-based page; returns page text and its rendered image. For text use offset to read beyond the first 120000 characters.', inputSchema: { ...schema({ path: str, page: { type: 'integer', minimum: 1 }, offset: { type: 'integer', minimum: 0 } }), required: ['path'] } },
+  { type: 'function', name: 'pindeck_edit', description: 'Replace one exact unique text occurrence in a file of the deck folder: the deck file, theme.css or another of its files. Read the file first. brand.css, vendor/, .git/ and other decks in the folder are locked.', inputSchema: { ...schema({ path: str, oldText: str, newText: str }), required: ['path', 'oldText', 'newText'] } },
+  { type: 'function', name: 'pindeck_write', description: 'Create a new file in the deck folder (missing folders are created), or replace all of an existing one. Prefer pindeck_edit for changes to existing files. The same files are locked as for pindeck_edit.', inputSchema: { ...schema({ path: str, content: str }), required: ['path', 'content'] } },
+  { type: 'function', name: 'pindeck_command', description: 'Run a PinDeck command: layout, shot, slides, pdf, or pdf-figure. Pass individual arguments in an array, never a shell command. Use pindeck_read on returned image paths.', inputSchema: { ...schema({ command: { enum: ['layout', 'shot', 'slides', 'pdf', 'pdf-figure'] }, args: { type: 'array', items: str, maxItems: 100 } }), required: ['command', 'args'] } },
+];
+/* Codex may read the deck, screenshots, attached PDFs and asset roots, and write any file of the deck folder
+   except the locked ones: the same rules as Claude's --allowedTools / --disallowedTools. locked: patterns
+   such as brand.css or vendor/** (or a function returning them, as the other decks in the folder change);
+   env: an object or a function (the server's address is known only once it listens). */
+export function createDeckTools({ deckDir, readDirs = [], cliFile, env, pdfTextFile, locked = ['brand.css', 'vendor/**', '.git/**'] }) {
+  const deck = fs.realpathSync(deckDir);
+  // looked up when used: the state folders (screenshots, attachments) are created once the server listens
+  const roots = () => [deck, ...readDirs.flatMap(d => { try { return [fs.realpathSync(d)]; } catch { return []; } })];
+  const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+  const envNow = () => (typeof env === 'function' ? env() : env);
+  const isLocked = rel => (typeof locked === 'function' ? locked() : locked)
+    .some(p => p.endsWith('/**') ? rel === p.slice(0, -3) || rel.startsWith(p.slice(0, -2)) : rel === p);
+  function checked(file, write = false) {
+    if (typeof file !== 'string' || !file || file.includes('\0')) throw new Error('Invalid file path.');
+    const full = path.resolve(deck, file);
+    if (write) {
+      const rel = path.relative(deck, full).split(path.sep).join('/');
+      if (!rel || !inside(deck, full)) throw new Error('Only files inside the deck folder can be edited.');
+      if (isLocked(rel)) throw new Error(`${rel} is locked: it cannot be edited in PinDeck.`);
+    }
+    // Check every component, including missing-file parents, to reject symlink escapes.
+    let existing = full;
+    while (!fs.existsSync(existing)) { const parent = path.dirname(existing); if (parent === existing) throw new Error('Missing file.'); existing = parent; }
+    const real = fs.realpathSync(existing);
+    if (!(write ? [deck] : roots()).some(root => inside(root, real)) || (write && real !== existing)) throw new Error('File is outside the permitted directories or is a symlink.');
+    if (write && fs.existsSync(full) && (fs.lstatSync(full).isSymbolicLink() || fs.statSync(full).nlink !== 1)) throw new Error('Linked files cannot be edited.');
+    return full;
+  }
+  async function command(name, args, signal) {
+    if (!['layout', 'shot', 'slides', 'pdf', 'pdf-figure'].includes(name) || !Array.isArray(args) || args.length > 100 || args.some(a => typeof a !== 'string' || a.length > 4096 || a.includes('\0'))) throw new Error('Invalid PinDeck command.');
+    if (name === 'pdf-figure') {
+      checked(args[0]);
+      // Host renderer can create figures: disallow symlinked output directories too.
+      const figures = path.join(deck, 'figures');
+      if (fs.existsSync(figures) && fs.realpathSync(figures) !== figures) throw new Error('Linked figures directory is not allowed.');
+      for (const a of args.slice(2).filter(a => /^figures\//.test(a))) {
+        const full = path.resolve(deck, a);
+        if (!inside(figures, full) || (fs.existsSync(full) && (fs.lstatSync(full).isSymbolicLink() || fs.statSync(full).nlink !== 1))) throw new Error('Linked or invalid output file.');
+      }
+    }
+    const { stdout } = await exec(process.execPath, [cliFile, name, ...args], { cwd: deck, env: { ...process.env, ...envNow() }, signal, timeout: 120000, maxBuffer: 2 * 1024 * 1024 });
+    return stdout;
+  }
+  async function read(file, page, offset, signal) {
+    const full = checked(file), ext = path.extname(full).toLowerCase();
+    if (ext === '.pdf') {
+      if (!Number.isInteger(page) || page < 1) throw new Error('Specify a PDF page number, starting at 1.');
+      const result = await command('pdf-figure', [full, String(page)], signal);
+      const png = renderedImagePath(result);
+      if (!png) throw new Error('PDF renderer did not return an image path.');
+      let words = '';
+      if (process.platform === 'darwin' && pdfTextFile) {
+        try { words = (await exec('/usr/bin/osascript', ['-l', 'JavaScript', pdfTextFile, full, String(page)], { signal, timeout: 30000, maxBuffer: 1024 * 1024 })).stdout; }
+        catch (e) { if (signal?.aborted) throw e; words = 'Text extraction unavailable; inspect the page image.'; }
+      }
+      return [text(words), ...await read(png, undefined, 0, signal)];
+    }
+    if (!fs.statSync(full).isFile()) throw new Error('Read a file, not a directory.');
+    if (fs.statSync(full).size > 12 * 1024 * 1024) throw new Error('File exceeds the 12 MB read limit.');
+    const data = fs.readFileSync(full);
+    const mime = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[ext];
+    if (mime) return [{ type: 'inputImage', imageUrl: `data:${mime};base64,${data.toString('base64')}` }];
+    if (!['.html', '.htm', '.css', '.md', '.txt', '.svg', '.json', '.js', '.mjs', '.csv'].includes(ext)) throw new Error('Read supports text, PNG/JPEG/WebP/GIF images, and rendered PDF pages. Audio is embedded by path, not transcribed.');
+    const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
+    return [text(data.toString('utf8').slice(start, start + 120000))];
+  }
+  return async (name, args, signal) => {
+    signal?.throwIfAborted();
+    if (name === 'pindeck_read') return read(args.path, args.page, args.offset, signal);
+    if (name === 'pindeck_command') return [text(await command(args.command, args.args, signal))];
+    if (name === 'pindeck_edit') {
+      const full = checked(args.path, true);
+      if (typeof args.oldText !== 'string' || !args.oldText || typeof args.newText !== 'string' || args.newText.length > 2e6) throw new Error('Supply nonempty oldText and replacement text.');
+      const old = fs.readFileSync(full, 'utf8');
+      if (old.indexOf(args.oldText) < 0 || old.indexOf(args.oldText) !== old.lastIndexOf(args.oldText)) throw new Error('oldText must match exactly once. Re-read the file.');
+      signal?.throwIfAborted();
+      writeAtomic(full, old.replace(args.oldText, () => args.newText));
+      return [text('Edited ' + path.relative(deck, full))];
+    }
+    if (name === 'pindeck_write') {
+      const full = checked(args.path, true);
+      if (typeof args.content !== 'string' || args.content.length > 2e6) throw new Error('Supply the file content as text (at most 2 MB).');
+      if (fs.existsSync(full) && !fs.statSync(full).isFile()) throw new Error('That path is a folder, not a file.');
+      signal?.throwIfAborted();
+      fs.mkdirSync(path.dirname(full), { recursive: true });
+      writeAtomic(full, args.content);
+      return [text('Wrote ' + path.relative(deck, full))];
+    }
+    throw new Error('Unknown PinDeck tool.');
+  };
+}

package/lib/capabilities.mjs

@@ -1,8 +1,9 @@
 /* What this server can do on this machine, decided once on the backend and used everywhere: the editor
-   (status), the API (refusals before any side effect), the CLI (its error text) and Claude's system prompt.
+   (status), the API (refusals before any side effect), the CLI (its error text) and the assistant's system prompt.
 
-   macOS: everything, as before. Linux (beta): editing, the chat and live reload. Features that need macOS
-   (PDFKit, PowerPoint/Keynote, afconvert) are off with a reason. Chrome features (screenshots, headless
+   macOS: everything, as before. Linux (beta): editing, the chat, live reload and the PowerPoint import;
+   pictures of PDF pages with Poppler, pictures of PowerPoint slides with LibreOffice and Poppler, and
+   waveforms of non-WAV audio with ffmpeg, each when installed, else off with a reason. Chrome features (screenshots, headless
    layout, PDF export) work on Linux as on macOS when Chrome or Chromium is found; PINDECK_LINUX_CHROME=0
    turns them off. Each entry is { available, reason }: reason says why not, in plain words. */
 
@@ -51,6 +52,9 @@ export function detectCapabilities({ platform = process.platform, env = process.
   const claude = findExecutable(claudeBin, { env });
   caps.claude = claude.path ? on() : off(`Claude Code is not available on the server (${claude.reason}). ` +
     `Install and log in to the claude CLI there, or set CLAUDE_BIN. Editing by hand still works.`);
+  const codex = findExecutable(env.CODEX_BIN || "codex", { env });
+  caps.codex = codex.path ? on() : off(`OpenAI Codex is not available on the server (${codex.reason}). ` +
+    `Install and log in to the codex CLI there, or set CODEX_BIN. Editing by hand still works.`);
 
   let chrome = null, chromeWhy = "";
   if (env.CHROME_BIN) {
@@ -71,11 +75,16 @@ export function detectCapabilities({ platform = process.platform, env = process.
   caps.headlessLayout = chromeCap;
   caps.pdfExport = chromeCap;
 
-  caps.pdfPages = mac ? on() : off("Rendering PDF pages to pictures needs macOS (PDFKit). Attached PDFs can still be read.");
-  caps.pptxImport = mac ? on() : off("PowerPoint import is not available on Linux in this beta.");
-  caps.pptxPictures = mac && OFFICE_APPS.some((a) => fs.existsSync(a)) ? on()
-    : off(mac ? "Pictures of PowerPoint slides need PowerPoint or Keynote." : "Pictures of PowerPoint slides need macOS with PowerPoint or Keynote.");
-  caps.audioConvert = mac ? on() : off("Waveforms for audio other than WAV need macOS (afconvert).");
+  // Linux: Poppler renders PDF pages, LibreOffice exports PowerPoint slides to PDF, ffmpeg decodes audio
+  const has = (name) => !!findExecutable(name, { env }).path;
+  const poppler = has("pdftoppm") && has("pdfinfo"), soffice = has("soffice") || has("libreoffice");
+  caps.pdfPages = mac || poppler ? on()
+    : off("Pictures of PDF pages need Poppler on the server (pdftoppm and pdfinfo; install poppler-utils). Attached PDFs can still be read.");
+  caps.pptxImport = on();   // the import itself reads the .pptx file: no other program needed
+  caps.pptxPictures = mac ? (OFFICE_APPS.some((a) => fs.existsSync(a)) ? on() : off("Pictures of PowerPoint slides need PowerPoint or Keynote."))
+    : soffice && poppler ? on()
+    : off("Pictures of PowerPoint slides need LibreOffice (soffice) and Poppler (pdftoppm, pdfinfo) on the server.");
+  caps.audioConvert = mac || has("ffmpeg") ? on() : off("Waveforms for audio other than WAV need ffmpeg on the server.");
   return caps;
 }
 

package/lib/claude.mjs

@@ -1,75 +1,42 @@
-/* A long-running Claude Code process in stream-json mode.
-
-   One process serves the whole chat: messages are written to stdin as JSON lines,
-   events come back on stdout. It runs under the user's normal Claude login. */
-
-import { spawn } from "node:child_process";
-import readline from "node:readline";
-
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+import { AgentProcess } from './agent-process.mjs';
+import { normalizeModels } from './models.mjs';
+/* A long-running Claude Code process in stream-json mode. One process serves the whole chat; it runs under
+   the user's normal Claude login. env may be a function: the server's address is known only once it listens. */
 export class ClaudeSession {
-  constructor({ cwd, args, env, onEvent, onExit, onStderr }) {
-    Object.assign(this, { cwd, args, env, onEvent, onExit, onStderr });
-    this.proc = null;
-    this.sessionId = null;
-    this.reqId = 0;
-  }
-
-  get running() { return !!this.proc; }
-
-  start(resumeId) {
-    const args = ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose",
-      ...(typeof this.args === "function" ? this.args() : this.args), ...(resumeId ? ["--resume", resumeId] : [])];
-    const proc = spawn(process.env.CLAUDE_BIN || "claude", args, {
-      cwd: this.cwd, env: { ...process.env, ...(typeof this.env === "function" ? this.env() : this.env) }, stdio: ["pipe", "pipe", "pipe"],
-    });
-    this.proc = proc;
-    readline.createInterface({ input: proc.stdout }).on("line", (line) => {
-      if (this.proc !== proc && this.proc) return;   // a stopped process that is still talking
-      if (!line.trim()) return;
-      let ev;
-      try { ev = JSON.parse(line); } catch { return; }
-      if (ev.session_id) this.sessionId = ev.session_id;
-      this.onEvent(ev);
+  constructor(options) { Object.assign(this, options); this.transport = null; this.sessionId = null; }
+  get running() { return !!this.transport && !this.transport.closed; }
+  async start(resumeId) {
+    if (this.running) return;
+    this.stopped = false;
+    const env = typeof this.env === 'function' ? this.env() : this.env;
+    try {
+      const { stdout } = await exec(process.env.CLAUDE_BIN || 'claude', ['auth', 'status', '--json'],
+        { env: { ...process.env, ...env }, timeout: 15000, maxBuffer: 65536 });
+      if (!JSON.parse(stdout).loggedIn) throw new Error('Not signed in.');
+    } catch (e) { throw new Error(e.code === 'ENOENT' ? 'Claude CLI is not installed (or set CLAUDE_BIN).' : 'Claude is not signed in. Run claude auth login, then refresh models.'); }
+    if (this.stopped) throw new Error('Agent stopped.');
+    const transport = new AgentProcess({ binary: process.env.CLAUDE_BIN || 'claude', cwd: this.cwd, env,
+      args: ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+        ...(typeof this.args === 'function' ? this.args() : this.args || []), ...(resumeId ? ['--resume', resumeId] : [])],
+      onStderr: this.onStderr,
+      onMessage: ev => {
+        if (this.transport !== transport) return;
+        if (ev.type === 'control_request') { transport.write({ type: 'control_response', response: { subtype: 'success', request_id: ev.request_id,
+          response: { behavior: 'deny', message: 'This tool is outside PinDeck permissions.' } } }); return; }
+        if (ev.session_id) this.sessionId = ev.session_id;
+        this.onEvent?.(ev);
+      },
+      onExit: error => { if (this.transport === transport) this.onExit?.(error); },
     });
-    proc.stderr.on("data", (d) => this.onStderr?.(String(d)));
-    proc.stdin.on("error", () => {});   // writing to a process that has died: its exit is reported below
-    // a process that could not start (no `claude` on the PATH) reports an error and never exits
-    let ended = false;
-    const end = (code, signal) => {
-      if (ended) return;
-      ended = true;
-      // stale: a newer process has been started since (model change, new chat); its turn is not ours to end
-      const stale = this.proc !== proc && this.proc !== null;
-      if (this.proc === proc) this.proc = null;
-      this.onExit(code, signal, { stale });
-    };
-    proc.on("error", (err) => { this.onStderr?.(String(err)); if (proc.pid === undefined) end(null, null); });
-    proc.on("exit", end);
-    proc.exited = new Promise((resolve) => proc.once("close", resolve).once("error", () => proc.pid === undefined && resolve()));
-  }
-
-  send(content) {
-    this.#write({ type: "user", message: { role: "user", content } });
-  }
-
-  interrupt() {
-    this.#write({ type: "control_request", request_id: `int-${++this.reqId}`, request: { subtype: "interrupt" } });
-  }
-
-  /* End of input first (Claude Code finishes and exits), SIGTERM after 1.5 s, SIGKILL after 4 s.
-     Resolves once the process has exited, so shutdown can wait for it. */
-  stop() {
-    if (!this.proc) return Promise.resolve();
-    const p = this.proc;
-    this.proc = null;
-    p.stdin.end();
-    const term = setTimeout(() => p.kill("SIGTERM"), 1500);
-    const kill = setTimeout(() => p.kill("SIGKILL"), 4000);
-    return p.exited.finally(() => { clearTimeout(term); clearTimeout(kill); });
-  }
-
-  #write(obj) {
-    if (!this.proc) throw new Error("Claude Code is not running");
-    this.proc.stdin.write(JSON.stringify(obj) + "\n");
+    this.transport = transport;
+    try { const init = await transport.request('initialize', {}, { claude: true }); this.models = normalizeModels('claude', init?.models); }
+    catch (e) { this.stop(); throw e; }
   }
+  async send(content) { this.transport.write({ type: 'user', message: { role: 'user', content } }); }
+  async interrupt() { if (this.running) await this.transport.request('interrupt', {}, { claude: true, timeout: 5000 }); }
+  /* Resolves once the process has exited, so shutdown can wait for it. */
+  stop() { this.stopped = true; const t = this.transport; this.transport = null; return t ? t.stop() : Promise.resolve(); }
 }

package/lib/codex.mjs

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import { AgentProcess } from './agent-process.mjs';
+import { normalizeModels } from './models.mjs';
+import { deckTools } from './agent-tools.mjs';
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export const CODEX_CONFIG = {
+  'features.shell_tool': false, 'features.unified_exec': false, 'features.js_repl': false,
+  'features.apps': false, 'features.plugins': false, 'features.multi_agent': false,
+  'features.hooks': false, 'features.memory_tool': false, 'features.shell_snapshot': false,
+  'web_search': 'disabled', 'project_doc_max_bytes': 0, 'notify': [],
+};
+const toml = value => JSON.stringify(value);
+const withoutNull = value => Array.isArray(value) ? value.map(withoutNull) : value && typeof value === 'object'
+  ? Object.fromEntries(Object.entries(value).filter(([, v]) => v != null).map(([k,v]) => [k, withoutNull(v)])) : value;
+export class CodexSession {
+  constructor(options) { Object.assign(this, options); this.transport = null; this.sessionId = null; this.turnId = null; this.controller = null; }
+  get running() { return !!this.transport && !this.transport.closed; }
+  async connect() {
+    if (this.running) return;
+    const transport = new AgentProcess({ binary: process.env.CODEX_BIN || 'codex', cwd: this.cwd,
+      args: ['app-server', ...Object.entries(CODEX_CONFIG).flatMap(([k,v]) => ['-c', `${k}=${toml(v)}`])],
+      onStderr: this.onStderr,
+      onMessage: m => { if (this.transport === transport) this.message(m).catch(e => this.onStderr?.(String(e))); },
+      onExit: error => { if (this.transport === transport) { this.controller?.abort(); this.onExit?.(error); } },
+    });
+    this.transport = transport;
+    try {
+      await transport.request('initialize', { clientInfo: { name: 'pindeck', version: VERSION }, capabilities: { experimentalApi: true } });
+      transport.write({ method: 'initialized', params: {} });
+      const auth = await transport.request('account/read', { refreshToken: false });
+      if (auth.requiresOpenaiAuth && !auth.account) throw new Error('Codex is not signed in. Run codex login, then refresh models.');
+      this.models = []; let cursor;
+      do { const list = await transport.request('model/list', { includeHidden: false, ...(cursor ? { cursor } : {}) });
+        this.models.push(...normalizeModels('codex', list.data)); cursor = list.nextCursor;
+      } while (cursor);
+    } catch (e) { this.stop(); throw e; }
+  }
+  async start(resumeId) {
+    await this.connect();
+    try {
+      const { config = {} } = await this.transport.request('config/read', { includeLayers: false, cwd: this.cwd });
+      // Disable inherited connectors and hooks before starting any thread. No configuration files are changed.
+      const overrides = { ...CODEX_CONFIG };
+      overrides.mcp_servers = Object.fromEntries(Object.entries(config.mcp_servers || {}).map(([name, value]) => [name, { ...value, enabled: false }]));
+      overrides.plugins = Object.fromEntries(Object.entries(config.plugins || {}).map(([name, value]) => [name, { ...value, enabled: false }]));
+      overrides.hooks = Object.fromEntries(Object.entries(config.hooks || {}).map(([name, value]) => [name, Array.isArray(value) ? [] : value]));
+      const opts = typeof this.settings === 'function' ? this.settings() : this.settings;
+      const params = { cwd: this.cwd, model: opts.model, modelProvider: 'openai',
+        approvalPolicy: 'never', sandbox: 'read-only', config: withoutNull(overrides),
+        developerInstructions: this.instructions, ...(resumeId ? { threadId: resumeId } : { dynamicTools: deckTools }) };
+      const result = await this.transport.request(resumeId ? 'thread/resume' : 'thread/start', params);
+      this.sessionId = result.thread.id;
+      this.onEvent?.({ type: 'system', subtype: 'init', session_id: this.sessionId, model: result.model || opts.model });
+    } catch (e) { this.stop(); throw e; }
+  }
+  async send(content) {
+    if (!this.sessionId || this.controller) throw new Error('Codex is not ready for another turn.');
+    const opts = typeof this.settings === 'function' ? this.settings() : this.settings;
+    this.controller = new AbortController(); this.turnId = null; this.cancelRequested = false;
+    try {
+      const result = await this.transport.request('turn/start', { threadId: this.sessionId, input: content,
+        model: opts.model, ...(opts.effort ? { effort: opts.effort } : {}),
+        approvalPolicy: 'never', sandboxPolicy: { type: 'readOnly', networkAccess: false } });
+      this.turnId = result.turn.id;
+      if (this.cancelRequested) await this.interrupt();
+    } catch (e) { this.controller?.abort(); this.controller = null; throw e; }
+  }
+  async message(m) {
+    const p = m.params || {};
+    if (m.id !== undefined && m.method) {
+      let result;
+      if (m.method === 'item/tool/call') {
+        try {
+          if (!this.controller || this.controller.signal.aborted || p.threadId !== this.sessionId || (this.turnId && p.turnId !== this.turnId)) throw new Error('Inactive turn.');
+          const signal = this.controller.signal;
+          const items = await this.tools(p.tool, p.arguments, signal);
+          signal.throwIfAborted(); result = { success: true, contentItems: items };
+        } catch (e) { result = { success: false, contentItems: [{ type: 'inputText', text: e.message }] }; }
+      } else if (m.method.includes('requestApproval') && m.method.includes('permissions')) result = { permissions: {}, scope: 'turn' };
+      else if (m.method.includes('requestApproval')) result = { decision: 'decline' };
+      else if (m.method.includes('elicitation')) result = { action: 'decline', content: null };
+      else if (m.method.includes('requestUserInput')) result = { answers: {} };
+      else { this.transport?.write({ id: m.id, error: { code: -32601, message: 'Unsupported request' } }); return; }
+      if (this.running) this.transport.write({ id: m.id, result });
+      return;
+    }
+    if (p.threadId !== this.sessionId || !this.controller) return;
+    const eventTurnId = p.turnId || p.turn?.id;
+    if (eventTurnId && this.turnId && eventTurnId !== this.turnId) return;
+    if (m.method === 'turn/started') this.turnId = p.turn.id;
+    const item = p.item;
+    if (m.method === 'item/completed' && item?.type === 'agentMessage') this.onEvent?.({ type: 'assistant', message: { content: [{ type: 'text', text: item.text }] } });
+    if (m.method === 'item/started' && item?.type === 'dynamicToolCall') this.onEvent?.({ type: 'assistant', message: { content: [{ type: 'tool_use', id: item.id, name: item.tool, input: item.arguments }] } });
+    if (m.method === 'item/completed' && item?.type === 'dynamicToolCall' && item.success === false) this.onEvent?.({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: item.id, is_error: true, content: (item.contentItems || []).map(c => ({ text: c.text || '' })) }] } });
+    if (m.method === 'turn/completed') {
+      this.controller.abort(); this.controller = null; this.turnId = null;
+      this.onEvent?.({ type: 'result', subtype: p.turn.status === 'completed' ? 'success' : 'error',
+        is_error: p.turn.status !== 'completed', result: p.turn.error?.message || (p.turn.status === 'interrupted' ? 'Stopped.' : p.turn.status) });
+    }
+  }
+  async interrupt() {
+    this.cancelRequested = true; this.controller?.abort();
+    if (this.turnId && this.running) await this.transport.request('turn/interrupt', { threadId: this.sessionId, turnId: this.turnId });
+  }
+  stop() { this.controller?.abort(); this.controller = null; const t = this.transport; this.transport = null; return t ? t.stop() : Promise.resolve(); }
+}

package/lib/deck-files.mjs

@@ -54,3 +54,41 @@ export function revision(dir, files) {
   }
   return h.digest("hex").slice(0, 16);
 }
+
+/* The deck's files for undo: every file a turn may change, with its content (bigger files: only size and
+   time, too large to keep a copy of). Hidden files and folders (.git), node_modules, and the vendor/ and
+   export/ folders are left out; so are symlinks, which point elsewhere. */
+const SKIP_TOP = new Set(["vendor", "export", "node_modules"]);
+export const KEEP_BYTES = 2 * 1024 * 1024;
+export function scanFiles(dir, maxBytes = KEEP_BYTES) {
+  const files = new Map();
+  const walk = (rel) => {
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (rel || !SKIP_TOP.has(e.name)) walk(r); continue; }
+      if (!e.isFile()) continue;
+      try {
+        const st = fs.statSync(path.join(dir, r));
+        files.set(r, { size: st.size, mtimeMs: st.mtimeMs, data: st.size <= maxBytes ? fs.readFileSync(path.join(dir, r)) : null });
+      } catch {}
+    }
+  };
+  walk("");
+  return files;
+}
+
+/* What changed between two scans: { rel: { before, after } } with the content on each side (null: the
+   file did not exist), and the files that changed but are too large to keep a copy of. */
+export function scanChanges(before, after) {
+  const changed = {}, tooLarge = [];
+  for (const rel of new Set([...before.keys(), ...after.keys()])) {
+    const b = before.get(rel), a = after.get(rel);
+    if (b && a && b.size === a.size && (b.data && a.data ? b.data.equals(a.data) : b.mtimeMs === a.mtimeMs)) continue;
+    if ((b && !b.data) || (a && !a.data)) { tooLarge.push(rel); continue; }
+    changed[rel] = { before: b ? b.data : null, after: a ? a.data : null };
+  }
+  return { changed, tooLarge };
+}

package/lib/frameworks.mjs

@@ -0,0 +1,41 @@
+/* Which slide framework a deck uses. PinDeck edits reveal.js decks: <section> slides inside an element
+   with class "slides" (inside <div class="reveal">). Other frameworks are recognised by their markup and
+   scripts, so the user gets a clear "not supported (yet)" before PinDeck changes anything, instead of an
+   editor without slides. Only tags and scripts are looked at, never the slides' text, so a talk that
+   mentions "impress.js" is not taken for one. */
+
+import { parse, findSlides } from "./eids.mjs";
+
+const OTHERS = [   // name, markers; the first match wins (Marp before bespoke.js, which it is built on)
+  ["Marp", /\bmarpit\b|bespoke-marp|data-marpit|marp-cli/i],
+  ["Slidev", /slidev/i],
+  ["impress.js", /id=["']impress["']|impress(\.min)?\.js/i],
+  ["remark", /remark(-latest)?(\.min)?\.js|remark\.create\s*\(/i],
+  ["Spectacle", /<script[^>]+src=["'][^"']*spectacle/i],
+  ["Shower", /class=["'][^"']*\bshower\b|shower-core/i],
+  ["deck.js", /deck-container|deck\.core(\.min)?\.js/i],
+  ["bespoke.js", /bespoke(\.min)?\.js|bespoke\.from\s*\(/i],
+];
+
+/* Tags and script contents only: the slides' text could name any framework */
+const markup = (html) => [...String(html).matchAll(/<script\b[^>]*>[\s\S]*?<\/script>|<[^>]+>/gi)].map((m) => m[0]).join("\n");
+
+/* { name, supported }: reveal.js decks are supported, including one without slides yet */
+export function detectFramework(html) {
+  if (findSlides(parse(html)).length) return { name: "reveal.js", supported: true };
+  const tags = markup(html);
+  const other = OTHERS.find(([, re]) => re.test(tags));
+  if (other) return { name: other[0], supported: false };
+  if (/class=["'][^"']*\breveal\b/i.test(tags) || /Reveal\.initialize\s*\(/.test(tags)) return { name: "reveal.js", supported: true };
+  return { name: null, supported: false };
+}
+
+/* The message for a deck PinDeck cannot edit, or null */
+export function unsupportedMessage(html, file) {
+  const fw = detectFramework(html);
+  if (fw.supported) return null;
+  const what = fw.name ? `${file} is a ${fw.name} deck.` :
+    `${file} has no reveal.js slides (a <div class="reveal"> with <div class="slides"> holding <section> slides).`;
+  return `${what} PinDeck works with reveal.js decks only for now; other frameworks may follow. ` +
+    `Nothing was changed.`;
+}

package/lib/instructions.mjs

@@ -0,0 +1,74 @@
+/* The deck's own instructions for Claude (CLAUDE.md, AGENTS.md), with @path imports expanded.
+
+   PinDeck does not load CLAUDE.md files from parent folders the way Claude Code does: those are usually
+   written for coding work PinDeck's Claude cannot do (tests, commits, package managers), they change
+   with where the deck happens to sit, and on a shared server a parent folder may be writable by others.
+   A deck pulls in shared rules explicitly instead: "Follow @../shared/STYLE.md" includes that file.
+
+   An import is "@" followed by a path (relative to the file it is in, absolute, or ~/...), at the start
+   of a line or after a space or "(". It is expanded only when that path is a text file: an e-mail address
+   or an @mention stays as it is. Imports in code spans and code blocks are left alone. Included files may
+   import others, up to 5 levels deep; each file is included once (no cycles), and all included text
+   together is limited to 200 KB. The imported text follows the file that imports it. */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const MAX_DEPTH = 5, MAX_BYTES = 200_000;
+
+/* Apply fn to the text outside code: fenced blocks (``` or ~~~) and `code spans` stay as they are */
+function outsideCode(text, fn) {
+  let fence = null;
+  return text.split("\n").map((line) => {
+    const f = /^\s*(```|~~~)/.exec(line);
+    if (f) { fence = fence ? (fence === f[1] ? null : fence) : f[1]; return line; }
+    if (fence) return line;
+    return line.split(/(`+[^`]*`+)/).map((part, i) => (i % 2 ? part : fn(part))).join("");
+  }).join("\n");
+}
+
+const resolveRef = (ref, dir) => (ref === "~" || ref.startsWith("~/") ? path.join(os.homedir(), ref.slice(1))
+  : path.resolve(dir, ref));
+
+function readText(file) {
+  try {
+    if (!fs.statSync(file).isFile()) return null;
+    const buf = fs.readFileSync(file);
+    return buf.includes(0) ? null : buf.toString("utf8");
+  } catch { return null; }
+}
+
+function expand(file, text, depth, seen, budget) {
+  const dir = path.dirname(file), found = [];
+  const body = outsideCode(text, (part) => part.replace(/(^|[\s(])@([^\s`()<>"']+)/g, (m, pre, raw) => {
+    const ref = raw.replace(/[.,:;!?]+$/, ""), tail = raw.slice(ref.length);   // "see @STYLE.md." ends a sentence
+    const abs = resolveRef(ref, dir);
+    const content = readText(abs);
+    if (content == null) return m;   // not a file: an e-mail address, an @mention, a typo
+    let real = abs;
+    try { real = fs.realpathSync(abs); } catch {}
+    const note = (why) => `${pre}${ref} (${why})${tail}`;
+    if (seen.has(real)) return note("included once, above or below");
+    if (depth >= MAX_DEPTH) return note("not included: imports nested too deep");
+    if (Buffer.byteLength(content) > budget.left) return note("not included: imported files over 200 KB in all");
+    budget.left -= Buffer.byteLength(content);
+    seen.add(real);
+    found.push({ ref, abs, content });
+    return note("included below");
+  }));
+  const parts = [body.trim()];
+  for (const imp of found) {
+    parts.push(`### ${imp.ref} (included by ${path.basename(file)})\n` + expand(imp.abs, imp.content, depth + 1, seen, budget));
+  }
+  return parts.filter(Boolean).join("\n\n");
+}
+
+/* A deck instruction file with its imports, or null when it is missing or empty */
+export function readInstructions(file) {
+  const text = readText(file);
+  if (text == null || !text.trim()) return null;
+  let real = file;
+  try { real = fs.realpathSync(file); } catch {}
+  return expand(file, text, 0, new Set([real]), { left: MAX_BYTES });
+}