@open-agent-toolkit/cli 0.2.20 → 0.2.21

package/assets/skills/explainer-kit/references/contracts.md

@@ -30,13 +30,25 @@ claims, sources, overrides, and the freshness policy. It returns:
 No provider name, command, credential, or dispatch protocol is part of this
 contract.
 
-Every unattended run also requires a provider-neutral author callback. An
-in-process caller supplies `options.author(request)`; a JSON-only CLI caller
-uses `--author-module author.mjs`. The core invokes it once per recipe artifact
-with an `AuthorRequestV1` containing the exact narrative outline, reconciled
-fact base, and bounded-discovery context. It must return an `AuthorResultV1`
-with every required section in order, non-empty prose, and non-secret
-provenance. The executable callback is never persisted in `run-request.json`.
+Every run, interactive or unattended, also requires a provider-neutral author
+callback; a run without one fails `E_AUTHOR_REQUIRED`. An in-process caller
+supplies `options.author(request)`; a JSON-only CLI caller uses
+`--author-module author.mjs`. The core invokes it once per resolved artifact
+with an `explainer-kit.author-request/v2` payload containing the artifact
+identity and type, the artifact's authoring path, the inlined brief, the
+reconciled fact base, the resolved theme, the shell source for artistic
+artifacts, the required narrative sections for narrative floor artifacts, and
+bounded-discovery context. It must return an `explainer-kit.author-result/v2`
+carrying exactly one of `content.markdown` or `content.html`, matching the
+artifact's declared authoring path, plus non-secret provenance. A floor result
+may also carry `proposedArtifacts` of `{id, profileId, rationale}`; the
+referenced expansion profile supplies the type, authoring path, brief, and
+shell. The executable callback is never persisted in `run-request.json`.
+
+Unknown profile IDs and unsafe, duplicate, or floor-colliding artifact IDs are
+hard errors. Proposals beyond a profile's `maxCount` or the recipe's
+`expansion.limits.maxArtifacts` are rejected with a warning and the run
+continues.
 
 ## Explicit source forms
 
@@ -57,7 +69,8 @@ provenance. The executable callback is never persisted in `run-request.json`.
 An unattended request asserts that its explicit source artifacts are already
 approved. It does not prompt, and it fails before narrative serialization when
 the author is absent, returns an invalid result, or copies excessive verbatim
-source text. Interactive review and same-run approval/resume remain unchanged.
+source text. It auto-approves with `auto-drafted` marking once the artifacts are
+built and checked.
 
 ## Pipeline and retained package
 
@@ -65,19 +78,30 @@ The core executes:
 
 1. validate request and recipe
 2. reconcile or check the fact base
-3. apply bounded discovery and obtain or create recipe content
+3. apply bounded discovery
 4. resolve one theme
-5. render typed artifacts
-6. run structural and optional browser QA
-7. write the manifest and build record
+5. author each floor artifact against its brief, evaluate expansion proposals,
+   and author each accepted expansion artifact
+6. render typed artifacts through the narrative renderer or validate
+   agent-composed HTML, per each artifact's declared authoring path
+7. run structural, guideline, and optional browser QA
+8. resolve content approval — the interactive gate pauses here, after render and
+   QA and before anything is published or persisted externally
+9. write the manifest and build record
 
 The run package retains the privacy-safe `run-request.json`,
 `source/content-approval.json`, `source/fact-base.json`,
-`source/fact-base.md`, `source/content/*.md`, optional structured
-`source/author/*.json` results, `theme.resolved.json`, rendered `site/` files,
-`manifest.json`, and `build-record.json` as far as each stage succeeds. A stage
-failure records a structured error and recovery action without deleting earlier
-outputs. Raw art direction is omitted unless the request explicitly opts in.
+`source/fact-base.md`, authored content under `source/content/*.md` and
+`source/content/*.html`, structured `source/author/*.json` results,
+`theme.resolved.json`, rendered `site/` files, `manifest.json`, and
+`build-record.json` as far as each stage succeeds. A stage failure records a
+structured error and recovery action without deleting earlier outputs. Raw art
+direction is omitted unless the request explicitly opts in.
+
+Build-record stages are terminal once `passed` or `warned`. A rejected run that
+is later approved reopens the render and QA stages through a narrowly guarded
+record-level reset so the corrected sources are re-rendered and re-validated,
+leaving an auditable trail rather than approving stale artifacts.
 
 When a caller supplies `discover({ round, recipe, factBase })`, the callback
 returns the findings added in that round. The core stops after two consecutive
@@ -93,7 +117,7 @@ Durability and publishing are never implicit.
   `record-durability.mjs`; the core never creates commits. The first evidence
   commit must contain every path and byte hash in `manifest.immutableHashes`:
   the privacy-safe request, content approval, fact-base JSON and Markdown,
-  declared author results, all content Markdown, the resolved theme, and every
+  declared author results, all authored content, the resolved theme, and every
   built artifact retained in the package. Mutable `manifest.json` and
   `build-record.json` remain excluded for the separate evidence update.
   Schema-v1 manifests created before complete-package coverage are rejected
@@ -110,7 +134,9 @@ verified. Publishing remains independently human-gated by the caller.
 ## Result
 
 `runExplainer` returns the run root, manifest path, build-record path, outcome,
-warnings, and bounded-discovery summary. Input validation and unsupported
+warnings, approval status and marking, and bounded-discovery summary. The
+marking rides in the result and the approval record only; `manifest/v1` stays
+frozen and carries no marking field. Input validation and unsupported
 recipes reject before output mutation. Failures after initialization return a
 `failed` result with paths to the retained record and intermediates.
 

package/assets/skills/explainer-kit/schemas/author-request.v2.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.author-request/v2",
+  "title": "AuthorRequestV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "artifactId",
+    "artifactType",
+    "authoring",
+    "brief",
+    "factBase",
+    "theme"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.author-request/v2" },
+    "artifactId": { "type": "string", "minLength": 1 },
+    "artifactType": {
+      "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+    },
+    "authoring": { "enum": ["markdown", "html"] },
+    "brief": { "type": "string", "minLength": 1 },
+    "factBase": { "$ref": "explainer-kit.fact-base/v1" },
+    "shell": { "type": "string", "minLength": 1 },
+    "theme": { "$ref": "explainer-kit.theme/v1" },
+    "floor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requiredNarrative"],
+      "properties": {
+        "requiredNarrative": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/author-result.v2.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.author-result/v2",
+  "title": "AuthorResultV2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "artifactId", "content", "provenance"],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.author-result/v2" },
+    "artifactId": { "type": "string", "minLength": 1 },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "oneOf": [{ "required": ["markdown"] }, { "required": ["html"] }],
+      "properties": {
+        "markdown": { "type": "string", "minLength": 1 },
+        "html": { "type": "string", "minLength": 1 }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authorId", "generatedAt"],
+      "properties": {
+        "authorId": { "type": "string", "minLength": 1 },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "method": { "type": "string", "minLength": 1 },
+        "trust": {
+          "description": "Stamped by the core on the retained record only. An author callback that asserts it is rejected.",
+          "enum": ["caller-bound", "self-asserted"]
+        }
+      }
+    },
+    "proposedArtifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "profileId", "rationale"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "profileId": { "type": "string", "minLength": 1 },
+          "rationale": { "type": "string", "minLength": 1 }
+        }
+      },
+      "uniqueItems": true
+    }
+  }
+}

package/assets/skills/explainer-kit/scripts/lib/browser-runtime.mjs

@@ -0,0 +1,442 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+
+// Locations a headless Chromium may already exist at on a developer or CI
+// machine. The core never installs a browser; it only uses one that is there.
+const CHROMIUM_CANDIDATES = Object.freeze([
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+]);
+const PROBE_REQUEST_FIELDS = new Set([
+  'artifact',
+  'disableAnimations',
+  'evaluate',
+  'injectedCss',
+  'javascriptEnabled',
+  'keyboard',
+  'media',
+  'reducedMotion',
+  'scenario',
+  'themeToggle',
+  'viewport',
+  'wideContent',
+]);
+const DISABLE_ANIMATIONS_CSS = `*, *::before, *::after {
+  animation: none !important;
+  animation-duration: 0s !important;
+  transition: none !important;
+  transition-duration: 0s !important;
+  scroll-behavior: auto !important;
+}`;
+
+export const RUNTIME_UNAVAILABLE_REASONS = Object.freeze({
+  driverMissing: 'browser-driver-not-installed',
+  executableMissing: 'no-installed-chromium-executable',
+  disabled: 'disabled-by-configuration',
+});
+
+export const HEADLESS_PROBE_ENV = 'EXPLAINER_KIT_HEADLESS_PROBE';
+
+/**
+ * Operators may switch probe resolution off for hermetic unit runs. The opt-out
+ * is reported separately from a capability failure so it never reads as
+ * "no runtime exists here".
+ */
+export function headlessProbeDisabled(env = process.env) {
+  return ['off', 'false', '0'].includes(
+    String(env[HEADLESS_PROBE_ENV] ?? '').toLowerCase(),
+  );
+}
+
+/**
+ * Detect whether this machine can actually drive a headless browser. The
+ * driver import is dynamic so the bundled core stays installable without it.
+ */
+export async function resolveHeadlessRuntime({
+  loadDriver = () => import('@playwright/test'),
+  fileExists = existsSync,
+  env = process.env,
+} = {}) {
+  if (headlessProbeDisabled(env)) {
+    return { available: false, reason: RUNTIME_UNAVAILABLE_REASONS.disabled };
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = await loadDriver());
+  } catch {
+    return {
+      available: false,
+      reason: RUNTIME_UNAVAILABLE_REASONS.driverMissing,
+    };
+  }
+  if (
+    typeof chromium?.launch !== 'function' ||
+    typeof chromium?.executablePath !== 'function'
+  ) {
+    return {
+      available: false,
+      reason: RUNTIME_UNAVAILABLE_REASONS.driverMissing,
+    };
+  }
+
+  let bundled;
+  try {
+    bundled = chromium.executablePath();
+  } catch {
+    bundled = undefined;
+  }
+  const executablePath = [
+    env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
+    bundled,
+    ...CHROMIUM_CANDIDATES,
+  ].find((candidate) => candidate && fileExists(candidate));
+  if (!executablePath) {
+    return {
+      available: false,
+      reason: RUNTIME_UNAVAILABLE_REASONS.executableMissing,
+    };
+  }
+
+  return {
+    available: true,
+    name: 'chromium',
+    executablePath,
+    launch: () => chromium.launch({ headless: true, executablePath }),
+  };
+}
+
+export async function launchInstalledChromium(options = {}) {
+  const runtime = await resolveHeadlessRuntime(options);
+  if (!runtime.available) {
+    throw new Error(
+      `No headless browser runtime is available (${runtime.reason}).`,
+    );
+  }
+  return runtime.launch();
+}
+
+/**
+ * Materialize a browser probe callback backed by a real headless browser.
+ * Returns an unavailable descriptor instead of throwing when no runtime
+ * exists, so callers can record an accurate capability skip.
+ */
+export async function createBrowserProbeSession(options = {}) {
+  const runtime = await resolveHeadlessRuntime(options);
+  if (!runtime.available) {
+    return { available: false, reason: runtime.reason };
+  }
+
+  const browser = await runtime.launch();
+  const pages = new Map();
+  const server = createServer((request, response) => {
+    const html = pages.get(request.url);
+    if (html === undefined) {
+      response.writeHead(404).end('not found');
+      return;
+    }
+    response.writeHead(200, {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'no-store',
+    });
+    response.end(html);
+  });
+
+  let address;
+  try {
+    address = await listen(server);
+  } catch (cause) {
+    await Promise.allSettled([browser.close(), closeServer(server)]);
+    throw cause;
+  }
+
+  return {
+    available: true,
+    runtime: { name: runtime.name, version: browser.version() },
+    probe: async (probeRequest) => {
+      const route = `/${randomBytes(12).toString('hex')}.html`;
+      pages.set(route, probeRequest.artifact.html);
+      try {
+        return await probeRenderedPage(
+          browser,
+          `http://127.0.0.1:${address.port}${route}`,
+          probeRequest,
+        );
+      } finally {
+        pages.delete(route);
+      }
+    },
+    close: async () => {
+      await Promise.allSettled([browser.close(), closeServer(server)]);
+    },
+  };
+}
+
+export async function probeRenderedPage(browser, url, request) {
+  assertProbeRequestFields(request);
+  const page = await browser.newPage({
+    viewport: request.viewport,
+    reducedMotion: request.reducedMotion ?? 'reduce',
+    javaScriptEnabled: request.javascriptEnabled !== false,
+  });
+  try {
+    if (request.media === 'print') {
+      await page.emulateMedia({
+        media: 'print',
+        reducedMotion: request.reducedMotion ?? 'reduce',
+      });
+    }
+    const stylesheet = probeStylesheet(request);
+    if (stylesheet) {
+      await page.route(url, async (route) => {
+        const response = await route.fetch();
+        const html = await response.text();
+        await route.fulfill({
+          response,
+          body: injectStylesheet(html, stylesheet),
+        });
+      });
+    }
+    await page.goto(url, { waitUntil: 'load' });
+    if (request.wideContent) {
+      await page.evaluate(({ containerSelector, width }) => {
+        const container = document.querySelector(containerSelector);
+        if (!container) return;
+        const probe = document.createElement('div');
+        probe.dataset.releaseWideContent = 'true';
+        probe.style.width = `${width}px`;
+        if (matchMedia('print').matches) probe.style.maxWidth = '100%';
+        probe.style.height = '1px';
+        container.append(probe);
+      }, request.wideContent);
+    }
+
+    const layout = await page.evaluate(request.evaluate);
+    const keyboard = await probeKeyboard(page, request);
+    const themeToggle = request.themeToggle
+      ? await probeThemeToggle(page, request.themeToggle)
+      : layout.themeToggle;
+    return {
+      ...layout,
+      keyboard,
+      ...(themeToggle && { themeToggle }),
+    };
+  } finally {
+    await page.close();
+  }
+}
+
+function assertProbeRequestFields(request) {
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    throw new TypeError('Browser probe request must be an object.');
+  }
+  const unsupported = Object.keys(request).filter(
+    (field) => !PROBE_REQUEST_FIELDS.has(field),
+  );
+  if (unsupported.length > 0) {
+    throw new TypeError(
+      `Browser probe request has unsupported fields: ${unsupported.join(', ')}.`,
+    );
+  }
+  if (
+    request.disableAnimations !== undefined &&
+    typeof request.disableAnimations !== 'boolean'
+  ) {
+    throw new TypeError('Browser probe disableAnimations must be a boolean.');
+  }
+  if (
+    request.injectedCss !== undefined &&
+    typeof request.injectedCss !== 'string'
+  ) {
+    throw new TypeError('Browser probe injectedCss must be a string.');
+  }
+}
+
+function probeStylesheet(request) {
+  return [
+    request.injectedCss?.trim(),
+    request.disableAnimations ? DISABLE_ANIMATIONS_CSS : undefined,
+  ]
+    .filter(Boolean)
+    .join('\n');
+}
+
+function injectStylesheet(html, stylesheet) {
+  const style = `<style data-explainer-probe-controls>${stylesheet}</style>`;
+  return /<\/head\s*>/i.test(html)
+    ? html.replace(/<\/head\s*>/i, `${style}</head>`)
+    : `${style}${html}`;
+}
+
+export async function primeKeyboardFocus(page) {
+  await page.bringToFront();
+  await page.mouse.click(1, 1);
+  await page.evaluate(() => {
+    window.focus();
+    const body = document.body;
+    const originalTabIndex = body.getAttribute('tabindex');
+    try {
+      body.setAttribute('tabindex', '-1');
+      body.focus({ preventScroll: true });
+    } finally {
+      if (originalTabIndex === null) {
+        body.removeAttribute('tabindex');
+      } else {
+        body.setAttribute('tabindex', originalTabIndex);
+      }
+    }
+  });
+}
+
+export async function pressTabFromDocument(
+  page,
+  { pressTab = () => page.keyboard.press('Tab') } = {},
+) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    await primeKeyboardFocus(page);
+    await pressTab();
+    const advanced = await page.evaluate(() => {
+      const focused =
+        document.activeElement !== document.body &&
+        document.activeElement !== document.documentElement;
+      const visibleFocusable = [
+        ...document.querySelectorAll(
+          'a[href], button, input, select, textarea, [tabindex]',
+        ),
+      ].some((element) => {
+        const style = getComputedStyle(element);
+        return (
+          style.display !== 'none' &&
+          style.visibility !== 'hidden' &&
+          element.getClientRects().length > 0
+        );
+      });
+      return focused || !visibleFocusable;
+    });
+    if (advanced) return true;
+    await page.waitForTimeout(25);
+  }
+  return page.evaluate(() => {
+    const visibleControls = [
+      ...document.querySelectorAll(
+        'a[href], button, input, select, textarea, [tabindex]',
+      ),
+    ].filter((element) => {
+      if (!(element instanceof HTMLElement) || element.matches(':disabled')) {
+        return false;
+      }
+      const style = getComputedStyle(element);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+    return (
+      visibleControls.length === 0 ||
+      visibleControls.some((element) => element.tabIndex >= 0)
+    );
+  });
+}
+
+export async function probeArrowKey(page, key) {
+  const positive = key === 'ArrowRight' || key === 'ArrowDown';
+  const makeRoomKey = positive ? 'ArrowLeft' : 'ArrowRight';
+  await page.bringToFront();
+  let before = await deckPosition(page);
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    const hasRoom = positive
+      ? before.current < before.total
+      : before.current > 1;
+    if (hasRoom) break;
+    await page.keyboard.press(makeRoomKey);
+    before = await deckPosition(page);
+    if (positive ? before.current < before.total : before.current > 1) {
+      break;
+    }
+    await page.waitForTimeout(25);
+    before = await deckPosition(page);
+  }
+  if (positive ? before.current >= before.total : before.current <= 1) {
+    return false;
+  }
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    await page.keyboard.press(key);
+    let after = await deckPosition(page);
+    if (
+      positive ? after.current > before.current : after.current < before.current
+    ) {
+      return true;
+    }
+    await page.waitForTimeout(25);
+    after = await deckPosition(page);
+    if (
+      positive ? after.current > before.current : after.current < before.current
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function probeKeyboard(page, request) {
+  const tab = await pressTabFromDocument(page);
+  if (!request.keyboard?.arrows) return { tab };
+
+  const arrows = {};
+  for (const key of request.keyboard.arrows) {
+    arrows[key] = await probeArrowKey(page, key);
+  }
+  return { tab, arrows };
+}
+
+async function probeThemeToggle(page, themeToggle) {
+  const locator = page.locator(themeToggle.selector);
+  const present = (await locator.count()) === 1;
+  if (!present) return { present: false };
+  const initialMode = await page.evaluate(
+    () => document.documentElement.dataset.themeMode,
+  );
+  await locator.focus();
+  await page.keyboard.press('Enter');
+  const toggledMode = await page.evaluate(
+    () => document.documentElement.dataset.themeMode,
+  );
+  await page.reload({ waitUntil: 'load' });
+  const persistedMode = await page.evaluate(
+    () => document.documentElement.dataset.themeMode,
+  );
+  return {
+    present: true,
+    initialMode,
+    toggledMode,
+    keyboardOperable: toggledMode !== initialMode,
+    persisted: persistedMode === toggledMode,
+  };
+}
+
+async function deckPosition(page) {
+  return page.evaluate(() => {
+    const text = document.querySelector('#deck-counter')?.textContent ?? '';
+    const [current, total] = text
+      .split('/')
+      .map((value) => Number.parseInt(value, 10));
+    return { current, total };
+  });
+}
+
+function listen(server) {
+  return new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolveListen(server.address());
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolveClose) => server.close(resolveClose));
+}