@open-agent-toolkit/cli 0.2.10 → 0.2.11

package/assets/skills/explainer-kit/scripts/lib/contracts.mjs

@@ -12,6 +12,8 @@ const SCHEMA_FILES = {
   'durability-evidence': 'durability-evidence.schema.json',
   'publish-request': 'publish-request.schema.json',
   'publish-receipt': 'publish-receipt.schema.json',
+  'author-request': 'author-request.schema.json',
+  'author-result': 'author-result.schema.json',
 };
 
 const SCHEMAS = Object.fromEntries(
@@ -450,6 +452,46 @@ function validateCrossRecord(kind, value, context, errors) {
     }
   }
 
+  if (kind === 'author-request') {
+    const requiredNarrative = Array.isArray(value.recipe?.requiredNarrative)
+      ? value.recipe.requiredNarrative
+      : [];
+    const outlineIds = Array.isArray(value.narrativeOutline)
+      ? value.narrativeOutline.map((section) => section?.id)
+      : [];
+    if (
+      requiredNarrative.length !== outlineIds.length ||
+      requiredNarrative.some((id, index) => outlineIds[index] !== id)
+    ) {
+      add(
+        errors,
+        '$.narrativeOutline',
+        'narrative-outline-mismatch',
+        'Author request narrative outline must exactly match recipe requiredNarrative order.',
+      );
+    }
+  }
+
+  if (kind === 'author-result') {
+    for (const [index, section] of (Array.isArray(value.content?.sections)
+      ? value.content.sections
+      : []
+    ).entries()) {
+      if (
+        isObject(section) &&
+        typeof section.prose === 'string' &&
+        section.prose.trim().length === 0
+      ) {
+        add(
+          errors,
+          `$.content.sections[${index}].prose`,
+          'empty-prose',
+          'Authored section prose must contain non-whitespace text.',
+        );
+      }
+    }
+  }
+
   if (kind === 'manifest') {
     const paths = [];
     for (const artifact of Array.isArray(value.artifacts)
@@ -502,9 +544,17 @@ function validateCrossRecord(kind, value, context, errors) {
       );
     }
 
+    const requiredProvenance = [
+      'run-request.json',
+      'source/content-approval.json',
+    ];
     const expectedImmutable = new Set([
+      ...requiredProvenance,
       value.source?.factBasePath,
       'source/fact-base.md',
+      ...(Array.isArray(value.source?.authorResultPaths)
+        ? value.source.authorResultPaths
+        : []),
       value.theme?.path,
       ...(Array.isArray(value.artifacts)
         ? value.artifacts.flatMap((artifact) => [
@@ -520,6 +570,17 @@ function validateCrossRecord(kind, value, context, errors) {
     const recordedImmutable = isObject(value.immutableHashes)
       ? new Set(Object.keys(value.immutableHashes))
       : new Set();
+    const missingLegacyPaths = requiredProvenance.filter(
+      (path) => !recordedImmutable.has(path),
+    );
+    if (missingLegacyPaths.length > 0) {
+      add(
+        errors,
+        '$.immutableHashes',
+        'legacy-manifest-incomplete',
+        `Legacy manifest is missing immutable coverage for ${missingLegacyPaths.join(', ')}; regenerate the recap package before archival.`,
+      );
+    }
     if (
       expectedImmutable.size !== recordedImmutable.size ||
       [...expectedImmutable].some((path) => !recordedImmutable.has(path))

package/assets/skills/explainer-kit/scripts/lib/durability.mjs

@@ -457,21 +457,9 @@ function requiredArtifacts(manifest) {
 }
 
 function immutablePackage(manifest) {
-  const expectedPaths = [
-    manifest.source.factBasePath,
-    'source/fact-base.md',
-    ...manifest.artifacts.map(({ contentPath }) => contentPath),
-    manifest.theme.path,
-    ...manifest.artifacts
-      .filter(
-        ({ status, renderedPath }) =>
-          status === 'built' && typeof renderedPath === 'string',
-      )
-      .map(({ renderedPath }) => renderedPath),
-  ];
-  return [...new Set(expectedPaths)].map((path) => ({
+  return Object.entries(manifest.immutableHashes).map(([path, hash]) => ({
     path,
-    hash: manifest.immutableHashes[path],
+    hash,
   }));
 }
 

package/assets/skills/explainer-kit/scripts/lib/qa.mjs

@@ -23,6 +23,62 @@ const ARROW_KEYS = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'];
 
 export const REPRESENTATIVE_WIDTHS = Object.freeze([320, 768, 1440]);
 
+export function checkSourceDumping({
+  authoredText,
+  authoredSections,
+  sourceTexts,
+  shingleSize = 8,
+  maxOverlapRatio = 0.6,
+  minMatchedShingles = 3,
+}) {
+  const sourceShingles = new Set(
+    (Array.isArray(sourceTexts) ? sourceTexts : []).flatMap((text) =>
+      shingles(text, shingleSize),
+    ),
+  );
+  const sections = Array.isArray(authoredSections)
+    ? authoredSections
+    : [{ text: authoredText }];
+  const issues = sections.flatMap(({ id, text }) => {
+    const authoredShingles = shingles(text, shingleSize);
+    const matchedShingles = authoredShingles.filter((value) =>
+      sourceShingles.has(value),
+    ).length;
+    const overlapRatio =
+      authoredShingles.length === 0
+        ? 0
+        : matchedShingles / authoredShingles.length;
+    return matchedShingles >= minMatchedShingles &&
+      overlapRatio > maxOverlapRatio
+      ? [
+          {
+            code: 'source-dump',
+            message:
+              'Authored narrative contains too much verbatim source text; rewrite it as audience-ready prose.',
+            details: {
+              ...(typeof id === 'string' && { sectionId: id }),
+              matchedShingles,
+              authoredShingles: authoredShingles.length,
+              overlapRatio,
+            },
+          },
+        ]
+      : [];
+  });
+  return { valid: issues.length === 0, issues };
+}
+
+function shingles(value, size) {
+  const words =
+    typeof value === 'string'
+      ? (value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])
+      : [];
+  if (words.length < size) return [];
+  return Array.from({ length: words.length - size + 1 }, (_, index) =>
+    words.slice(index, index + size).join(' '),
+  );
+}
+
 export const BROWSER_PROBE_EVALUATE = `(() => {
   const root = document.documentElement;
   const clippedX = [...document.querySelectorAll('body *')]

package/assets/skills/explainer-kit/scripts/lib/theme.mjs

@@ -10,6 +10,12 @@ const PALETTE_NAMES = new Set([
   'violet',
 ]);
 const PROFILE_NAMES = new Set(['clean', 'editorial', 'technical']);
+const STYLE_NAMES = new Set([
+  'clean-neutral',
+  'business-corporate',
+  'navy-ocean',
+  'dark-edgy',
+]);
 const RENDER_STRATEGIES = new Set(['default-only', 'user-switchable']);
 const DEFAULT_MODES = new Set(['light', 'dark']);
 const MODE_ROLES = ['surface', 'ink', 'accent', 'status', 'diagramSeries'];
@@ -20,20 +26,28 @@ export async function resolveTheme(selection = {}) {
   const renderStrategy = selection.renderStrategy ?? 'default-only';
   const warnings = [];
   let theme;
+  const hasLegacySelection = ['palette', 'visualProfile'].some(
+    (key) => selection[key] !== undefined,
+  );
+  if (hasLegacySelection) {
+    warnings.push(
+      'Palette and visual profile selection is deprecated; use a curated style.',
+    );
+  }
 
   if (selection.suppliedBundlePath !== undefined) {
     theme = await resolveSuppliedBundle(selection.suppliedBundlePath);
     if (
-      ['palette', 'visualProfile', 'artDirection', 'defaultMode'].some(
+      ['style', 'palette', 'visualProfile', 'artDirection', 'defaultMode'].some(
         (key) => selection[key] !== undefined,
       )
     ) {
       warnings.push(
-        'Supplied bundle wins over palette, visual profile, art direction, and default mode selections.',
+        'Supplied bundle wins over style, palette, visual profile, art direction, and default mode selections.',
       );
     }
   } else {
-    theme = await resolveNamedTheme(selection);
+    theme = await resolveNamedTheme(selection, warnings);
   }
 
   assertResolvedTheme(theme);
@@ -48,7 +62,49 @@ export async function resolveTheme(selection = {}) {
   };
 }
 
-async function resolveNamedTheme(selection) {
+async function resolveNamedTheme(selection, warnings) {
+  if (
+    selection.style !== undefined ||
+    (selection.palette === undefined && selection.visualProfile === undefined)
+  ) {
+    const styleName = selection.style ?? 'clean-neutral';
+    assertNamedSelection(styleName, STYLE_NAMES, 'style');
+    if (selection.style === undefined) {
+      warnings.push(
+        'No explicit style was selected; defaulted to clean-neutral.',
+      );
+    }
+    if (
+      selection.style !== undefined &&
+      (selection.palette !== undefined || selection.visualProfile !== undefined)
+    ) {
+      warnings.push(
+        'Curated style wins over deprecated palette and visual profile selections.',
+      );
+    }
+    const style = await loadBundledJson('styles', styleName);
+    assertStyle(style, styleName);
+    const theme = {
+      schemaVersion: 'explainer-kit.theme/v1',
+      name: style.name,
+      defaultMode: selection.defaultMode ?? style.defaultMode,
+      modes: structuredClone(style.modes),
+      provenance: { style: styleName, derived: false },
+      typography: structuredClone(style.typography),
+      spacing: structuredClone(style.spacing),
+      geometry: structuredClone(style.geometry),
+      elevation: structuredClone(style.elevation),
+      density: style.density,
+      motion: structuredClone(style.motion),
+      diagrams: structuredClone(style.diagrams),
+    };
+    if (selection.artDirection !== undefined) {
+      applyArtDirection(theme, selection.artDirection);
+    }
+    theme.bundleHash = canonicalHash(theme);
+    return theme;
+  }
+
   const paletteName = selection.palette ?? 'neutral';
   const profileName = selection.visualProfile ?? 'clean';
   assertNamedSelection(paletteName, PALETTE_NAMES, 'palette');
@@ -135,6 +191,7 @@ function assertSelection(selection) {
     throw new TypeError('Theme selection must be an object.');
   }
   const allowed = new Set([
+    'style',
     'palette',
     'visualProfile',
     'suppliedBundlePath',
@@ -160,6 +217,47 @@ function assertSelection(selection) {
   }
 }
 
+function assertStyle(style, expectedName) {
+  const expectedKeys = [
+    'name',
+    'defaultMode',
+    'modes',
+    'typography',
+    'spacing',
+    'geometry',
+    'elevation',
+    'density',
+    'motion',
+    'diagrams',
+  ];
+  if (
+    !isObject(style) ||
+    style.name !== expectedName ||
+    !hasExactKeys(style, expectedKeys) ||
+    !DEFAULT_MODES.has(style.defaultMode) ||
+    !isObject(style.modes) ||
+    !hasExactKeys(style.modes, ['light', 'dark'])
+  ) {
+    throw new Error(`Bundled style ${expectedName} has an invalid shape.`);
+  }
+  for (const mode of Object.values(style.modes)) {
+    assertMode(mode);
+  }
+  assertProfile(
+    {
+      name: expectedName,
+      typography: style.typography,
+      spacing: style.spacing,
+      geometry: style.geometry,
+      elevation: style.elevation,
+      density: style.density,
+      motion: style.motion,
+      diagrams: style.diagrams,
+    },
+    expectedName,
+  );
+}
+
 function assertNamedSelection(value, allowed, label) {
   if (typeof value !== 'string' || !allowed.has(value)) {
     throw new Error(`Unknown ${label}: ${String(value)}.`);

package/assets/skills/explainer-kit/scripts/run.mjs

@@ -9,7 +9,7 @@ import { resolveContentApproval } from './lib/content-approval.mjs';
 import { canonicalHash, validateContract } from './lib/contracts.mjs';
 import { processFactBase } from './lib/fact-base.mjs';
 import { writeJsonAtomic, writeTextAtomic } from './lib/fs-safe.mjs';
-import { auditArtifactSet } from './lib/qa.mjs';
+import { auditArtifactSet, checkSourceDumping } from './lib/qa.mjs';
 import {
   loadRecipe,
   shouldStopDiscovery,
@@ -38,6 +38,7 @@ export async function runExplainer(request, options = {}) {
     inputHashes: {},
     contentModels: [],
     contentPaths: new Map(),
+    authorResultPaths: [],
     theme: null,
     renderStrategy: run.request.theme.renderStrategy,
     rendered: [],
@@ -83,9 +84,15 @@ export async function runExplainer(request, options = {}) {
       });
       await executeStage(run, 'content', options, async () => {
         state.discovery = await runDiscovery(recipe, state.factBase, options);
-        state.contentModels = recipe.artifacts.map((artifact) =>
-          createContentModel(recipe, artifact, run.slug, state.factBase),
-        );
+        if (run.request.mode === 'unattended') {
+          const authored = await createAuthoredContent(state, options.author);
+          state.contentModels = authored.models;
+          state.authorResultPaths = authored.resultPaths;
+        } else {
+          state.contentModels = recipe.artifacts.map((artifact) =>
+            createContentModel(recipe, artifact, run.slug, state.factBase),
+          );
+        }
         for (const model of state.contentModels) {
           const validation = validateContentModel(recipe, model);
           if (!validation.valid) {
@@ -106,6 +113,7 @@ export async function runExplainer(request, options = {}) {
       run,
       run.request.mode,
       options.reviewedSource,
+      state.authorResultPaths,
     );
     if (!state.approval.canResume) {
       return resultFor(state);
@@ -251,9 +259,14 @@ async function loadResumableRun(request) {
 }
 
 async function hydrateResumableState(state) {
-  state.factBase = await readJson(
-    join(state.run.runRoot, 'source/fact-base.json'),
-  );
+  const [factBase, approval] = await Promise.all([
+    readJson(join(state.run.runRoot, 'source/fact-base.json')),
+    readJson(join(state.run.runRoot, 'source/content-approval.json')),
+  ]);
+  state.factBase = factBase;
+  state.authorResultPaths = Array.isArray(approval.authorResultPaths)
+    ? [...approval.authorResultPaths]
+    : [];
   state.inputHashes = inputHashes(state.factBase);
   state.factBaseHash = canonicalHash(state.factBase);
   state.contentModels = [];
@@ -534,6 +547,9 @@ function manifestFor(state, buildRecord, createdAt, immutableHashes) {
       factBasePath: 'source/fact-base.json',
       factBaseHash: state.factBaseHash,
       inputHashes: state.inputHashes,
+      ...(state.authorResultPaths.length > 0 && {
+        authorResultPaths: state.authorResultPaths,
+      }),
     },
     theme: {
       path: 'theme.resolved.json',
@@ -551,6 +567,117 @@ function manifestFor(state, buildRecord, createdAt, immutableHashes) {
   };
 }
 
+async function createAuthoredContent(state, author) {
+  if (typeof author !== 'function') {
+    throw codedError(
+      'E_AUTHOR_REQUIRED',
+      'Unattended runs require an explicit author callback.',
+    );
+  }
+
+  const authored = [];
+  for (const artifact of state.recipe.artifacts) {
+    const resultPath = `source/author/${artifact.id}.json`;
+    const authorRequest = {
+      schemaVersion: 'explainer-kit.author-request/v1',
+      run: { runId: state.run.runId, slug: state.run.slug },
+      recipe: {
+        id: state.recipe.id,
+        version: state.recipe.version,
+        requiredNarrative: [...state.recipe.requiredNarrative],
+      },
+      artifact: {
+        id: artifact.id,
+        type: artifact.type,
+      },
+      narrativeOutline: state.recipe.requiredNarrative.map((id) => ({
+        id,
+        title: humanize(id),
+      })),
+      factBase: structuredClone(state.factBase),
+      discovery: structuredClone(state.discovery),
+    };
+    const requestValidation = validateContract('author-request', authorRequest);
+    if (!requestValidation.valid) {
+      throw codedError(
+        'E_AUTHOR_REQUEST',
+        contractErrorMessage('author request', requestValidation.errors),
+      );
+    }
+
+    const result = await author(structuredClone(authorRequest));
+    const resultValidation = validateContract('author-result', result);
+    if (!resultValidation.valid) {
+      throw codedError(
+        'E_AUTHOR_RESULT',
+        contractErrorMessage('author result', resultValidation.errors),
+      );
+    }
+    const sectionIds = result.content.sections.map(({ id }) => id);
+    if (
+      result.artifactId !== artifact.id ||
+      sectionIds.length !== state.recipe.requiredNarrative.length ||
+      state.recipe.requiredNarrative.some(
+        (id, index) => sectionIds[index] !== id,
+      )
+    ) {
+      throw codedError(
+        'E_AUTHOR_RESULT',
+        `Author result for ${artifact.id} must contain the exact required section IDs in order.`,
+      );
+    }
+    const dumpCheck = checkSourceDumping({
+      authoredSections: result.content.sections.map(({ id, prose }) => ({
+        id,
+        text: prose,
+      })),
+      sourceTexts: [
+        ...state.factBase.claims,
+        ...state.factBase.unresolvedClaims,
+      ].map(({ text }) => text),
+    });
+    if (!dumpCheck.valid) {
+      throw codedError(
+        'E_SOURCE_DUMP',
+        dumpCheck.issues.map(({ message }) => message).join('; '),
+      );
+    }
+
+    authored.push({
+      result: structuredClone(result),
+      resultPath,
+      model: {
+        artifactId: artifact.id,
+        slug: state.run.slug,
+        title: result.content.title,
+        description: result.content.description,
+        ...(result.content.eyebrow && { eyebrow: result.content.eyebrow }),
+        ...(result.content.footer && { footer: result.content.footer }),
+        sections: result.content.sections.map(({ id, title, prose }) => ({
+          id,
+          title,
+          content: prose,
+        })),
+        artifactLinks: result.content.artifactLinks ?? [],
+      },
+    });
+  }
+
+  for (const item of authored) {
+    await writeJsonAtomic(state.run.runRoot, item.resultPath, item.result);
+  }
+  return {
+    models: authored.map(({ model }) => model),
+    resultPaths: authored.map(({ resultPath }) => resultPath),
+  };
+}
+
+function contractErrorMessage(label, errors) {
+  return `Invalid ${label}: ${errors
+    .map(({ path, message }) => `${path}: ${message}`)
+    .join('; ')}`;
+}
+
 function createContentModel(recipe, artifact, slug, factBase) {
   const facts = [
     ...factBase.claims.map(({ text, sections }) => ({ text, sections })),
@@ -614,8 +741,11 @@ function validateRecipeSources(recipe, binding) {
 
 async function immutableHashesFor(state) {
   const paths = [
+    'run-request.json',
     'source/fact-base.json',
     'source/fact-base.md',
+    'source/content-approval.json',
+    ...state.authorResultPaths,
     ...state.contentPaths.values(),
     ...(state.theme ? ['theme.resolved.json'] : []),
     ...state.artifacts
@@ -727,9 +857,12 @@ async function parseCli(argv) {
       if (!path) throw new Error('--reviewed-source requires a JSON path.');
       options.reviewedSource = JSON.parse(await readFile(path, 'utf8'));
     } else if (
-      ['--critic-module', '--publish-module', '--durability-module'].includes(
-        value,
-      )
+      [
+        '--author-module',
+        '--critic-module',
+        '--publish-module',
+        '--durability-module',
+      ].includes(value)
     ) {
       const path = argv[++index];
       if (!path) throw new Error(`${value} requires a module path.`);
@@ -745,7 +878,7 @@ async function parseCli(argv) {
   }
   if (!requestPath) {
     throw new Error(
-      'Usage: run.mjs --request <json> [--reviewed-source <json>] [--critic-module <mjs>] [--publish-module <mjs>] [--durability-module <mjs>]',
+      'Usage: run.mjs --request <json> [--reviewed-source <json>] [--author-module <mjs>] [--critic-module <mjs>] [--publish-module <mjs>] [--durability-module <mjs>]',
     );
   }
   return { requestPath, options };

package/assets/skills/explainer-kit/styles/business-corporate.json

@@ -0,0 +1,77 @@
+{
+  "name": "business-corporate",
+  "defaultMode": "light",
+  "modes": {
+    "light": {
+      "surface": {
+        "canvas": "#ffffff",
+        "panel": "#f7f8fa",
+        "elevated": "#eef0f4"
+      },
+      "ink": { "primary": "#1a1f29", "muted": "#4a5568", "inverse": "#ffffff" },
+      "accent": { "primary": "#1b4f8a", "secondary": "#2f6fce" },
+      "status": {
+        "success": "#197a56",
+        "warning": "#965108",
+        "danger": "#b83226",
+        "info": "#1b4f8a"
+      },
+      "diagramSeries": ["#2f6fce", "#965108", "#0f7180", "#6b4fbf"]
+    },
+    "dark": {
+      "surface": {
+        "canvas": "#121a26",
+        "panel": "#1b2533",
+        "elevated": "#293649"
+      },
+      "ink": { "primary": "#f4f7fb", "muted": "#c5cfdb", "inverse": "#121a26" },
+      "accent": { "primary": "#8fc2ff", "secondary": "#75d6df" },
+      "status": {
+        "success": "#8ce0b9",
+        "warning": "#ffd17a",
+        "danger": "#ffaaa3",
+        "info": "#8fc2ff"
+      },
+      "diagramSeries": ["#8fc2ff", "#ffd17a", "#75d6df", "#c5a9ff"]
+    }
+  },
+  "typography": {
+    "sans": ["system-ui", "-apple-system", "BlinkMacSystemFont", "sans-serif"],
+    "serif": ["Charter", "Bitstream Charter", "Georgia", "serif"],
+    "mono": ["ui-monospace", "SFMono-Regular", "Consolas", "monospace"],
+    "scale": {
+      "caption": "0.875rem",
+      "body": "1.0625rem",
+      "title": "1.75rem",
+      "display": "2.75rem"
+    },
+    "lineHeight": { "caption": 1.5, "body": 1.7, "title": 1.2, "display": 1.05 }
+  },
+  "spacing": {
+    "unit": 5,
+    "scale": { "xs": 5, "sm": 10, "md": 20, "lg": 30, "xl": 50 }
+  },
+  "geometry": { "radius": { "sm": 4, "md": 8, "lg": 12 }, "borderWidth": 1 },
+  "elevation": {
+    "shadows": {
+      "low": "0 1px 2px rgb(26 31 41 / 0.08)",
+      "high": "0 10px 28px rgb(26 31 41 / 0.18)"
+    }
+  },
+  "density": "spacious",
+  "motion": {
+    "enabled": true,
+    "durationMs": { "fast": 140, "normal": 220, "slow": 360 },
+    "easing": {
+      "standard": "ease-out",
+      "emphasized": "cubic-bezier(0.16, 1, 0.3, 1)"
+    },
+    "reducedMotion": "disable-nonessential"
+  },
+  "diagrams": {
+    "lineWidth": 1.5,
+    "nodeGap": 40,
+    "arrowStyle": "curved",
+    "labelTreatment": "inline"
+  }
+}