@monoes/monobrowse 1.0.0 → 1.0.1

package/src/browser/playbook/browser-handlers.ts

@@ -0,0 +1,449 @@
+// createBrowserHandlers — CDP-backed NodeHandler implementations for @monoes/monoplaybook.
+//
+// browser.open        — connect to Chrome CDP and open a URL
+// browser.navigate    — navigate the current tab to a URL
+// browser.click       — click an element (selector | role | text | label | placeholder)
+// browser.type        — type text into an element (keystroke-by-keystroke)
+// browser.fill        — set an input value directly (faster than type)
+// browser.select      — pick an <option> by value or visible text
+// browser.check       — check or uncheck a checkbox / radio
+// browser.hover       — hover over an element
+// browser.press       — press a key or combo (e.g. "Enter", "Ctrl+A")
+// browser.scroll      — scroll up/down/left/right by pixel amount
+// browser.wait        — wait for selector | url | load | networkidle | duration
+// browser.extract     — pull text, attribute, html, all_text, url, or title into item.data
+// browser.snapshot    — capture an accessibility tree snapshot
+// browser.screenshot  — take a screenshot (saves to file or returns base64)
+// browser.evaluate    — run arbitrary JS; result goes into item.data
+// browser.close       — drop the cached CDP connection (does not kill Chrome)
+
+import type { NodeHandler, Item } from '@monoes/monoplaybook';
+import { CdpClient } from '../cdp.js';
+import {
+  connectToTarget,
+  openUrl,
+  waitForLoad,
+  getCurrentUrl,
+  getCurrentTitle,
+} from '../browser.js';
+import {
+  clickElement,
+  fillElement,
+  typeText,
+  pressKey,
+  pressKeyCombo,
+  scrollElement,
+  hoverElement,
+  selectOption,
+  checkElement,
+  evaluateJs,
+} from '../actions.js';
+import {
+  findBySelector,
+  findByRole,
+  findByText,
+  findByLabel,
+  findByPlaceholder,
+} from '../find.js';
+import { waitFor } from '../wait.js';
+import { captureSnapshot } from '../snapshot.js';
+import { captureScreenshot } from '../screenshot.js';
+import type { ElementRef } from '../types.js';
+import { mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Shared connection state — cached per CDP port across nodes in one playbook run
+// ---------------------------------------------------------------------------
+
+interface BrowserConnection {
+  client: CdpClient;
+  sessionId: string;
+  refs: Map<string, ElementRef>;
+}
+
+const connectionCache = new Map<number, BrowserConnection>();
+
+async function getConnection(port: number): Promise<BrowserConnection> {
+  if (connectionCache.has(port)) {
+    const cached = connectionCache.get(port)!;
+    try {
+      // Lightweight liveness check — if the CDP connection has dropped, this throws
+      await cached.client.send('Runtime.evaluate', { expression: '1', returnByValue: true }, cached.sessionId);
+      return cached;
+    } catch {
+      // Stale connection — evict and reconnect below
+      connectionCache.delete(port);
+    }
+  }
+  const { client, sessionId } = await connectToTarget(port);
+  const conn: BrowserConnection = { client, sessionId, refs: new Map() };
+  connectionCache.set(port, conn);
+  return conn;
+}
+
+function releaseConnection(port: number): void {
+  connectionCache.delete(port);
+}
+
+function safeResolvePath(rawPath: string): string {
+  const cwd = process.cwd();
+  const abs = resolve(cwd, rawPath);
+  if (abs !== cwd && !abs.startsWith(cwd + '/')) {
+    throw new Error(`Path traversal blocked: "${rawPath}" resolves outside working directory`);
+  }
+  return abs;
+}
+
+// ---------------------------------------------------------------------------
+// Element resolution — locator types: selector | role | text | label | placeholder
+// ---------------------------------------------------------------------------
+
+async function findElement(
+  conn: BrowserConnection,
+  config: Record<string, unknown>,
+): Promise<ElementRef> {
+  const locator = (config['locator'] as string | undefined) ?? 'selector';
+  const value = config['value'] as string;
+  if (!value) throw new Error(`browser handler requires config.value (the element locator)`);
+
+  const { client, sessionId, refs } = conn;
+  const opts = {
+    exact: config['exact'] as boolean | undefined,
+    nth: config['nth'] as number | undefined,
+  };
+
+  let ref: ElementRef | null = null;
+  switch (locator) {
+    case 'selector':    ref = await findBySelector(client, sessionId, refs, value); break;
+    case 'role':        ref = await findByRole(client, sessionId, refs, value, opts); break;
+    case 'text':        ref = await findByText(client, sessionId, refs, value, opts); break;
+    case 'label':       ref = await findByLabel(client, sessionId, refs, value, opts); break;
+    case 'placeholder': ref = await findByPlaceholder(client, sessionId, refs, value, opts); break;
+    default: throw new Error(`Unknown locator "${locator}". Use: selector|role|text|label|placeholder`);
+  }
+
+  if (!ref) throw new Error(`Element not found: ${locator}="${value}"`);
+  return ref;
+}
+
+// Modifier bitmask used by CDP (matches DevTools protocol)
+function modifierBits(modifiers: string[]): number {
+  let bits = 0;
+  for (const m of modifiers) {
+    switch (m.toLowerCase()) {
+      case 'alt':   bits |= 1; break;
+      case 'ctrl':
+      case 'control': bits |= 2; break;
+      case 'meta':
+      case 'cmd':   bits |= 4; break;
+      case 'shift': bits |= 8; break;
+    }
+  }
+  return bits;
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+export function createBrowserHandlers(): Map<string, NodeHandler> {
+  const h = new Map<string, NodeHandler>();
+
+  // ── browser.open ──────────────────────────────────────────────────────────
+  h.set('browser.open', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const url = config['url'] as string;
+    if (!url) throw new Error('browser.open requires config.url');
+    const timeout = (config['timeoutMs'] as number | undefined) ?? 30000;
+    const condition = (config['waitUntil'] as 'load' | 'networkidle' | 'domcontentloaded' | undefined) ?? 'load';
+
+    const conn = await getConnection(port);
+    await openUrl(conn.client, conn.sessionId, url);
+    await waitForLoad(conn.client, conn.sessionId, condition, timeout);
+
+    const currentUrl = await getCurrentUrl(conn.client, conn.sessionId);
+    const title = await getCurrentTitle(conn.client, conn.sessionId);
+    return items.map(item => ({ ...item, data: { ...item.data, url: currentUrl, title, port } }));
+  });
+
+  // ── browser.navigate ──────────────────────────────────────────────────────
+  h.set('browser.navigate', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const url = config['url'] as string;
+    if (!url) throw new Error('browser.navigate requires config.url');
+    const timeout = (config['timeoutMs'] as number | undefined) ?? 30000;
+    const condition = (config['waitUntil'] as 'load' | 'networkidle' | 'domcontentloaded' | undefined) ?? 'load';
+
+    const conn = await getConnection(port);
+    await openUrl(conn.client, conn.sessionId, url);
+    await waitForLoad(conn.client, conn.sessionId, condition, timeout);
+
+    const currentUrl = await getCurrentUrl(conn.client, conn.sessionId);
+    const title = await getCurrentTitle(conn.client, conn.sessionId);
+    return items.map(item => ({ ...item, data: { ...item.data, url: currentUrl, title } }));
+  });
+
+  // ── browser.click ─────────────────────────────────────────────────────────
+  h.set('browser.click', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    await clickElement(conn.client, conn.sessionId, ref);
+    return items;
+  });
+
+  // ── browser.type ──────────────────────────────────────────────────────────
+  h.set('browser.type', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const text = config['text'] as string;
+    if (text === undefined) throw new Error('browser.type requires config.text');
+
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    if (config['clear'] !== false) {
+      await fillElement(conn.client, conn.sessionId, ref, '');
+    }
+    await typeText(conn.client, conn.sessionId, text);
+    return items;
+  });
+
+  // ── browser.fill ──────────────────────────────────────────────────────────
+  h.set('browser.fill', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const text = (config['text'] as string | undefined) ?? '';
+
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    await fillElement(conn.client, conn.sessionId, ref, text);
+    return items;
+  });
+
+  // ── browser.select ────────────────────────────────────────────────────────
+  h.set('browser.select', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const option = config['option'] as string;
+    if (!option) throw new Error('browser.select requires config.option');
+
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    await selectOption(conn.client, conn.sessionId, ref, option);
+    return items;
+  });
+
+  // ── browser.check ─────────────────────────────────────────────────────────
+  h.set('browser.check', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const checked = (config['checked'] as boolean | undefined) ?? true;
+
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    await checkElement(conn.client, conn.sessionId, ref, checked);
+    return items;
+  });
+
+  // ── browser.hover ─────────────────────────────────────────────────────────
+  h.set('browser.hover', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const conn = await getConnection(port);
+    const ref = await findElement(conn, config);
+    await hoverElement(conn.client, conn.sessionId, ref);
+    return items;
+  });
+
+  // ── browser.press ─────────────────────────────────────────────────────────
+  // Config: port, key — e.g. "Enter", "Tab", "Escape", "Ctrl+A", "Shift+Tab"
+  h.set('browser.press', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const key = config['key'] as string;
+    if (!key) throw new Error('browser.press requires config.key');
+
+    const conn = await getConnection(port);
+    if (key.includes('+')) {
+      const parts = key.split('+').map(k => k.trim());
+      const mainKey = parts[parts.length - 1];
+      const bits = modifierBits(parts.slice(0, -1));
+      // Delegate to pressKeyCombo which uses resolveKey() for correct code/key mapping
+      // (avoids KeyENTER-style bugs from naive Key${mainKey.toUpperCase()} construction)
+      await pressKeyCombo(conn.client, conn.sessionId, mainKey, bits);
+    } else {
+      await pressKey(conn.client, conn.sessionId, key);
+    }
+    return items;
+  });
+
+  // ── browser.scroll ────────────────────────────────────────────────────────
+  // Config: port, direction (up|down|left|right, default "down"), amount (px, default 300),
+  //         locator + value (optional — scroll a specific element)
+  h.set('browser.scroll', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const direction = (config['direction'] as 'up' | 'down' | 'left' | 'right' | undefined) ?? 'down';
+    const amount = (config['amount'] as number | undefined) ?? 300;
+
+    const conn = await getConnection(port);
+    const hasLocator = !!(config['value']);
+
+    if (hasLocator) {
+      const ref = await findElement(conn, config);
+      await scrollElement(conn.client, conn.sessionId, direction, amount, ref);
+    } else {
+      await scrollElement(conn.client, conn.sessionId, direction, amount);
+    }
+    return items;
+  });
+
+  // ── browser.wait ──────────────────────────────────────────────────────────
+  // Config: port, for (selector|url|load|networkidle|duration), value, timeoutMs
+  h.set('browser.wait', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const conn = await getConnection(port);
+    const waitKind = (config['for'] as string | undefined) ?? 'duration';
+    const timeout = (config['timeoutMs'] as number | undefined) ?? 30000;
+    const value = config['value'];
+
+    switch (waitKind) {
+      case 'duration':
+        await new Promise(res => setTimeout(res, (value as number | undefined) ?? 1000));
+        break;
+      case 'selector':
+        await waitFor(conn.client, conn.sessionId, { selector: value as string, timeout });
+        break;
+      case 'url':
+        await waitFor(conn.client, conn.sessionId, { url: value as string, timeout });
+        break;
+      case 'load':
+        await waitForLoad(conn.client, conn.sessionId, 'load', timeout);
+        break;
+      case 'networkidle':
+        await waitForLoad(conn.client, conn.sessionId, 'networkidle', timeout);
+        break;
+      default:
+        throw new Error(`browser.wait: unknown 'for' value: "${waitKind}". Use selector|url|load|networkidle|duration`);
+    }
+    return items;
+  });
+
+  // ── browser.extract ───────────────────────────────────────────────────────
+  // Config: port, as (text|attribute|html|all_text|url|title), locator, value,
+  //         attribute (when as=attribute), outputKey (default "extracted")
+  h.set('browser.extract', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const as = (config['as'] as string | undefined) ?? 'text';
+    const outputKey = (config['outputKey'] as string | undefined) ?? 'extracted';
+    const conn = await getConnection(port);
+
+    if (as === 'url') {
+      const url = await getCurrentUrl(conn.client, conn.sessionId);
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: url } }));
+    }
+    if (as === 'title') {
+      const title = await getCurrentTitle(conn.client, conn.sessionId);
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: title } }));
+    }
+    if (as === 'all_text') {
+      const text = await evaluateJs(conn.client, conn.sessionId, 'document.body.innerText');
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: text } }));
+    }
+
+    const ref = await findElement(conn, config);
+
+    if (as === 'text') {
+      const result = await conn.client.send<{ result: { value: unknown } }>(
+        'Runtime.callFunctionOn',
+        { objectId: ref.objectId, functionDeclaration: 'function(){return this.innerText ?? this.textContent ?? ""}', returnByValue: true },
+        conn.sessionId,
+      );
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: result.result.value } }));
+    }
+
+    if (as === 'attribute') {
+      const attr = config['attribute'] as string;
+      if (!attr) throw new Error('browser.extract with as=attribute requires config.attribute');
+      const result = await conn.client.send<{ result: { value: unknown } }>(
+        'Runtime.callFunctionOn',
+        {
+          objectId: ref.objectId,
+          functionDeclaration: `function(){return this.getAttribute(${JSON.stringify(attr)})}`,
+          returnByValue: true,
+        },
+        conn.sessionId,
+      );
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: result.result.value } }));
+    }
+
+    if (as === 'html') {
+      const result = await conn.client.send<{ result: { value: unknown } }>(
+        'Runtime.callFunctionOn',
+        { objectId: ref.objectId, functionDeclaration: 'function(){return this.outerHTML}', returnByValue: true },
+        conn.sessionId,
+      );
+      return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: result.result.value } }));
+    }
+
+    throw new Error(`browser.extract: unknown 'as' value: "${as}". Use text|attribute|html|all_text|url|title`);
+  });
+
+  // ── browser.snapshot ──────────────────────────────────────────────────────
+  // Captures an accessibility tree. Output stored in item.data[outputKey].
+  // Config: port, selector (scope to element), interactiveOnly, compact, outputKey
+  h.set('browser.snapshot', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const outputKey = (config['outputKey'] as string | undefined) ?? 'snapshot';
+    const conn = await getConnection(port);
+
+    const result = await captureSnapshot(conn.client, conn.sessionId, {
+      selector: config['selector'] as string | undefined,
+      interactiveOnly: (config['interactiveOnly'] as boolean | undefined) ?? false,
+      compact: (config['compact'] as boolean | undefined) ?? true,
+    });
+    return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: result } }));
+  });
+
+  // ── browser.screenshot ────────────────────────────────────────────────────
+  // Config: port, path (optional file path), fullPage, format (jpeg|png|webp),
+  //         quality, outputKey (default "screenshot")
+  // Output: if path is set → saves file and puts path in data; else → puts dataUrl in data + binaryBase64
+  h.set('browser.screenshot', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const outputKey = (config['outputKey'] as string | undefined) ?? 'screenshot';
+    const conn = await getConnection(port);
+
+    const userPath = config['path'] as string | undefined;
+    const absPath = userPath ? safeResolvePath(userPath) : undefined;
+    if (absPath) await mkdir(dirname(absPath), { recursive: true });
+
+    const { path: savedPath, dataUrl } = await captureScreenshot(conn.client, conn.sessionId, {
+      path: absPath,
+      fullPage: (config['fullPage'] as boolean | undefined) ?? false,
+      format: (config['format'] as 'jpeg' | 'png' | 'webp' | undefined) ?? 'png',
+      quality: config['quality'] as number | undefined,
+    });
+
+    return items.map(item => ({
+      ...item,
+      data: { ...item.data, [outputKey]: userPath ? savedPath : dataUrl },
+    }));
+  });
+
+  // ── browser.evaluate ──────────────────────────────────────────────────────
+  // Config: port, script (JS expression), outputKey (default "result")
+  h.set('browser.evaluate', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    const script = config['script'] as string;
+    if (!script) throw new Error('browser.evaluate requires config.script');
+    const outputKey = (config['outputKey'] as string | undefined) ?? 'result';
+
+    const conn = await getConnection(port);
+    const result = await evaluateJs(conn.client, conn.sessionId, script);
+    return items.map(item => ({ ...item, data: { ...item.data, [outputKey]: result } }));
+  });
+
+  // ── browser.close ─────────────────────────────────────────────────────────
+  h.set('browser.close', async (items, config): Promise<Item[]> => {
+    const port = (config['port'] as number | undefined) ?? 9222;
+    releaseConnection(port);
+    return items;
+  });
+
+  return h;
+}

package/src/browser/{workflow → playbook}/builtin-handlers.ts

@@ -1,8 +1,8 @@
-// Built-in node handlers registered for every `browse workflow run` invocation.
+// Built-in node handlers registered for every `browse playbook run` invocation.
 //
 // action.http         — fetch a URL (GET/POST/etc.) and put the response in item.data
 // action.save_file    — write item data or binaryBase64 to a file on disk
-// action.log          — console.log each item (useful for debugging workflows)
+// action.log          — console.log each item (useful for debugging playbooks)
 // action.gemini_image — generate image via Gemini web app (browser automation + session store)
 //                       or Imagen REST API (GEMINI_API_KEY), or mock mode
 import { writeFile, readFile, mkdir, chmod } from 'node:fs/promises';
@@ -19,8 +19,7 @@ function safeResolvePath(rawPath: string): string {
   }
   return safePath;
 }
-import type { NodeHandler } from './engine.js';
-import type { Item } from './types.js';
+import type { NodeHandler, Item } from '@monoes/monoplaybook';
 
 // ---------------------------------------------------------------------------
 // Session persistence (shared format with browse-platform.ts)
@@ -150,7 +149,7 @@ async function generateViaGeminiBrowser(
       console.log('│  A browser window has been opened to Gemini.            │');
       console.log('│  Please sign in with your Google account.               │');
       console.log('│                                                         │');
-      console.log('│  The workflow will resume automatically after login.    │');
+      console.log('│  The playbook will resume automatically after login.   │');
       console.log('│  Waiting up to 5 minutes…                               │');
       console.log('└─────────────────────────────────────────────────────────┘');
       console.log('');
@@ -238,24 +237,46 @@ export function createBuiltinHandlers(): Map<string, NodeHandler> {
   const handlers = new Map<string, NodeHandler>();
 
   // action.http
-  // config: { url, method?, headers?, body?, responseField? }
-  // Puts { statusCode, body, json? } into item.data[responseField ?? 'response']
+  // config: { url, method?, headers?, body?, responseField?, timeoutMs?, throwOnError? }
+  // Puts { statusCode, body, json? } into item.data[responseField ?? 'response'].
+  // throwOnError (default true): throws on 4xx/5xx responses.
+  // timeoutMs (default 30000): abort the request after this many ms.
   handlers.set('action.http', async (items, config) => {
     const url = String(config['url'] ?? '');
     const method = String(config['method'] ?? 'GET').toUpperCase();
     const headers = (config['headers'] as Record<string, string>) ?? {};
     const body = config['body'] !== undefined ? JSON.stringify(config['body']) : undefined;
     const responseField = String(config['responseField'] ?? 'response');
-
-    const res = await fetch(url, {
-      method,
-      headers: { 'Content-Type': 'application/json', ...headers },
-      body: method !== 'GET' && method !== 'HEAD' ? body : undefined,
-    });
+    const timeoutMs = Number(config['timeoutMs'] ?? 30_000);
+    const throwOnError = config['throwOnError'] !== false; // default true
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let res: Response;
+    try {
+      res = await fetch(url, {
+        method,
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body: method !== 'GET' && method !== 'HEAD' ? body : undefined,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      const msg = err instanceof Error && err.name === 'AbortError'
+        ? `action.http: request timed out after ${timeoutMs}ms — ${url}`
+        : `action.http: network error — ${err instanceof Error ? err.message : String(err)}`;
+      throw new Error(msg);
+    }
+    clearTimeout(timer);
 
     const text = await res.text();
     let json: unknown;
-    try { json = JSON.parse(text); } catch { /* not JSON */ }
+    try { json = JSON.parse(text); } catch { /* not JSON — body is plain text or binary */ }
+
+    if (throwOnError && !res.ok) {
+      throw new Error(`action.http: HTTP ${res.status} ${res.statusText} — ${url}\n${text.slice(0, 500)}`);
+    }
 
     return items.map(item => ({
       ...item,

package/src/browser/playbook/index.ts

@@ -0,0 +1,2 @@
+export * from './builtin-handlers.js';
+export * from './browser-handlers.js';

package/src/browser/{workflow → playbook}/store.ts

@@ -1,11 +1,11 @@
 import { readFile } from 'node:fs/promises';
-import type { WorkflowDef, RunRecord } from './types.js';
+import type { PlaybookDef, RunRecord } from '@monoes/monoplaybook';
 import type { ActionDef } from '../action-builder/types.js';
 
 // TODO: Upgrade to better-sqlite3 for persistence across process restarts.
 // Schema:
 //   CREATE TABLE browse_runs (
-//     id TEXT PRIMARY KEY, workflow_id TEXT, workflow_name TEXT,
+//     id TEXT PRIMARY KEY, playbook_id TEXT, playbook_name TEXT,
 //     status TEXT, started_at INTEGER, completed_at INTEGER,
 //     items_processed INTEGER, items_total INTEGER, error TEXT
 //   );
@@ -19,25 +19,25 @@ export function clearRunStore(): void {
   runStore.clear();
 }
 
-export async function readWorkflow(filePath: string): Promise<WorkflowDef> {
+export async function readPlaybook(filePath: string): Promise<PlaybookDef> {
   let raw: string;
   try {
     raw = await readFile(filePath, 'utf-8');
   } catch {
-    throw new Error(`Workflow file not found: ${filePath}`);
+    throw new Error(`Playbook file not found: ${filePath}`);
   }
   let def: unknown;
   try {
     def = JSON.parse(raw);
   } catch {
-    throw new Error(`Invalid JSON in workflow file: ${filePath}`);
+    throw new Error(`Invalid JSON in playbook file: ${filePath}`);
   }
-  if (!isWorkflowDef(def)) {
+  if (!isPlaybookDef(def)) {
     const w = def as Record<string, unknown>;
-    if (typeof w?.['id'] !== 'string') throw new Error('Workflow missing required field: id');
-    if (typeof w?.['name'] !== 'string') throw new Error('Workflow missing required field: name');
-    if (!Array.isArray(w?.['nodes'])) throw new Error('Workflow missing required field: nodes');
-    throw new Error('Workflow missing required field: connections');
+    if (typeof w?.['id'] !== 'string') throw new Error('Playbook missing required field: id');
+    if (typeof w?.['name'] !== 'string') throw new Error('Playbook missing required field: name');
+    if (!Array.isArray(w?.['nodes'])) throw new Error('Playbook missing required field: nodes');
+    throw new Error('Playbook missing required field: connections');
   }
   return def;
 }
@@ -49,7 +49,7 @@ function validateAction(def: unknown): void {
   if (!Array.isArray(a['steps'])) throw new Error('Action missing required field: steps');
 }
 
-function isWorkflowDef(def: unknown): def is WorkflowDef {
+function isPlaybookDef(def: unknown): def is PlaybookDef {
   if (typeof def !== 'object' || def === null) return false;
   const w = def as Record<string, unknown>;
   return (
@@ -77,11 +77,11 @@ export async function readAction(filePath: string): Promise<ActionDef> {
   return def as ActionDef;
 }
 
-export async function writeRunRecord(record: RunRecord): Promise<void> {
+export async function writePlaybookRun(record: RunRecord): Promise<void> {
   runStore.set(record.id, { ...record });
 }
 
-export async function listRuns(workflowId?: string): Promise<RunRecord[]> {
+export async function listPlaybookRuns(playbookId?: string): Promise<RunRecord[]> {
   const all = [...runStore.values()];
-  return workflowId ? all.filter(r => r.workflowId === workflowId) : all;
+  return playbookId ? all.filter(r => r.playbookId === playbookId) : all;
 }