@open-agent-toolkit/cli 0.2.5 → 0.2.6

package/dist/config/resolve.js

@@ -17,6 +17,20 @@ const DEFAULT_SHARED_CONFIG = {
         awsProfile: null,
         awsRegion: null,
     },
+    explainers: {
+        defaults: {
+            palette: 'neutral',
+            visualProfile: 'clean',
+            themeBundlePath: null,
+        },
+        publish: {
+            provider: null,
+            s3Uri: null,
+            publicBaseUrl: null,
+            awsRegion: null,
+            awsProfile: null,
+        },
+    },
     documentation: {
         root: null,
         tooling: null,
@@ -72,6 +86,10 @@ const DEFAULT_WORKFLOW_CONFIG = {
             mode: null,
             policy: null,
         },
+        explainers: {
+            projectExplainer: 'ask',
+            projectRecap: 'ask',
+        },
     },
 };
 const ENV_OVERRIDE_MAP = {

package/dist/validation/project-state.d.ts

@@ -1,5 +1,6 @@
 import { readdir as defaultReaddir, readFile as defaultReadFile } from 'node:fs/promises';
 import { type ProjectStateKind, type ProjectStatePhase } from '../commands/shared/frontmatter.js';
+import type { ExplainerDecisionV1 } from '@open-agent-toolkit/control-plane';
 export interface NormalizedProjectState {
     oat_kind: ProjectStateKind;
     oat_phase?: ProjectStatePhase;
@@ -8,6 +9,8 @@ export interface NormalizedProjectState {
     oat_siblings: string[];
     oat_depends_on: string[];
     oat_children: string[];
+    oat_project_explainer?: ExplainerDecisionV1 | null;
+    oat_project_recap?: ExplainerDecisionV1 | null;
 }
 export interface ProjectStateValidationError {
     code: string;

package/dist/validation/project-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-state.d.ts","sourceRoot":"","sources":["../../src/validation/project-state.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,IAAI,cAAc,EACzB,QAAQ,IAAI,eAAe,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,sBAAsB,CAAC;IAC9B,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,0CAA2C,SAAQ,IAAI,CACtE,gCAAgC,EAChC,iBAAiB,CAClB;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC;AAmND,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAqE9B;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gCAAqC,GAC7C,IAAI,CAYN;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwBlC;AAED,wBAAsB,wCAAwC,CAC5D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0CAA0C,GAClD,OAAO,CAAC,IAAI,CAAC,CAkDf"}
+{"version":3,"file":"project-state.d.ts","sourceRoot":"","sources":["../../src/validation/project-state.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,IAAI,cAAc,EACzB,QAAQ,IAAI,eAAe,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAyB7E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,qBAAqB,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnD,iBAAiB,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,sBAAsB,CAAC;IAC9B,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,0CAA2C,SAAQ,IAAI,CACtE,gCAAgC,EAChC,iBAAiB,CAClB;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC;AA6SD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CA+E9B;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gCAAqC,GAC7C,IAAI,CAYN;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwBlC;AAED,wBAAsB,wCAAwC,CAC5D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0CAA0C,GAClD,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/validation/project-state.js

@@ -2,6 +2,26 @@ import { readdir as defaultReaddir, readFile as defaultReadFile, } from 'node:fs
 import { basename, join } from 'node:path';
 import { getFrontmatterBlock, isProjectStateKind, isProjectStatePhase, } from '../commands/shared/frontmatter.js';
 import YAML from 'yaml';
+const EXPLAINER_DECISIONS = ['generate', 'skip'];
+const EXPLAINER_SOURCES = [
+    'interactive',
+    'kickoff_prompt',
+    'autonomous_policy',
+];
+const EXPLAINER_DECISION_KEYS = ['decision', 'source', 'decided_at'];
+const EXPLAINER_ALLOWED_PAIRS = {
+    oat_project_explainer: new Set([
+        'generate:interactive',
+        'skip:interactive',
+        'generate:kickoff_prompt',
+    ]),
+    oat_project_recap: new Set([
+        'generate:interactive',
+        'skip:interactive',
+        'generate:autonomous_policy',
+    ]),
+};
+const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 function readStringField(frontmatter, key) {
     const value = frontmatter[key];
     return typeof value === 'string' ? value : undefined;
@@ -20,6 +40,75 @@ function readStringArrayField(frontmatter, key, errors) {
     });
     return [];
 }
+function readExplainerDecision(frontmatter, key, errors) {
+    const value = frontmatter[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        errors.push({
+            code: 'invalid-explainer-decision-record',
+            message: `${key} must be null or a decision object`,
+        });
+        return null;
+    }
+    const record = value;
+    const keys = Object.keys(record);
+    if (keys.some((entry) => !EXPLAINER_DECISION_KEYS.includes(entry))) {
+        errors.push({
+            code: 'invalid-explainer-decision-keys',
+            message: `${key} must contain only decision, source, and decided_at`,
+        });
+        return null;
+    }
+    const decision = record.decision;
+    const source = record.source;
+    const decidedAt = record.decided_at;
+    let valid = true;
+    if (typeof decision !== 'string' ||
+        !EXPLAINER_DECISIONS.includes(decision)) {
+        errors.push({
+            code: 'invalid-explainer-decision',
+            message: `${key}.decision must be generate or skip`,
+        });
+        valid = false;
+    }
+    if (typeof source !== 'string' ||
+        !EXPLAINER_SOURCES.includes(source)) {
+        errors.push({
+            code: 'invalid-explainer-source',
+            message: `${key}.source must be interactive, kickoff_prompt, or autonomous_policy`,
+        });
+        valid = false;
+    }
+    if (typeof decidedAt !== 'string' ||
+        !ISO_TIMESTAMP_PATTERN.test(decidedAt) ||
+        Number.isNaN(Date.parse(decidedAt))) {
+        errors.push({
+            code: 'invalid-explainer-timestamp',
+            message: `${key}.decided_at must be an ISO 8601 timestamp`,
+        });
+        valid = false;
+    }
+    if (valid &&
+        !EXPLAINER_ALLOWED_PAIRS[key].has(`${String(decision)}:${String(source)}`)) {
+        errors.push({
+            code: 'invalid-explainer-decision-source',
+            message: `${key} does not allow decision ${String(decision)} from source ${String(source)}`,
+        });
+        valid = false;
+    }
+    return valid
+        ? {
+            decision: decision,
+            source: source,
+            decided_at: decidedAt,
+        }
+        : null;
+}
 function readKind(frontmatter) {
     const rawKind = readStringField(frontmatter, 'oat_kind');
     return rawKind && isProjectStateKind(rawKind) ? rawKind : 'implementation';
@@ -190,6 +279,8 @@ export function validateProjectState(input) {
         oat_siblings: readStringArrayField(input.frontmatter, 'oat_siblings', errors),
         oat_depends_on: readStringArrayField(input.frontmatter, 'oat_depends_on', errors),
         oat_children: readStringArrayField(input.frontmatter, 'oat_children', errors),
+        oat_project_explainer: readExplainerDecision(input.frontmatter, 'oat_project_explainer', errors),
+        oat_project_recap: readExplainerDecision(input.frontmatter, 'oat_project_recap', errors),
     };
     validateChildLinkage(input, state, errors);
     validateInheritedContextGate(input.frontmatter, state, errors);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.2.5"
+    "@open-agent-toolkit/control-plane": "0.2.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",