@open-agent-toolkit/cli 0.2.62 → 0.2.63

package/assets/skills/oat-explainer-kit/scripts/probe-recap-seams.mjs

@@ -0,0 +1,371 @@
+/**
+ * Pre-flight capability probe for the provider-neutral seams a lifecycle
+ * `project-recap` run requires.
+ *
+ * The probe is pure: it inspects only the inputs a caller would hand to
+ * `runOatExplainer`, applying the same resolution and exclusivity rules
+ * `scripts/run.mjs` applies at runtime. It never imports a module, calls a
+ * callback, validates a browser-session brand, or touches the filesystem.
+ *
+ * Three outcomes are kept distinct and are never conflated:
+ *
+ * - `missing` — no provider is supplied for a seam this mode requires. This is
+ *   the only outcome that may become a recordable `skip` / `capability_probe`
+ *   intent (`code: 'seams-unavailable'`).
+ * - `invalid` — a seam is supplied but violates a resolution rule (both a
+ *   callback and a module path, a non-function callback, an empty module path,
+ *   or an unsupported `coreOptions` route). It fails closed with the same
+ *   message the runtime would raise (`code: 'seams-invalid'`) and is never a
+ *   skip.
+ * - runtime failure — an unloadable module, a non-function export, an unbranded
+ *   browser session, or a failed generation. The probe never observes these
+ *   because it never loads or calls anything, so a failed run after a passing
+ *   probe stays `failed`.
+ *
+ * Each seam has its own classifier that mirrors its `run.mjs` resolver check by
+ * check and in the same order, because the resolvers do not share one order:
+ * `resolveLifecycleCritic` counts only function/truthy candidates before it
+ * type-checks, while the author, visual critic, and set planner type-check the
+ * callback before they reject a direct-plus-module conflict. Keep each
+ * classifier aligned with the resolver named in its comment.
+ */
+
+const MODES = new Set(['interactive', 'unattended']);
+
+const isSet = (value) => value !== undefined;
+
+const invalid = (reason, message) => ({ status: 'invalid', reason, message });
+const supplied = () => ({ status: 'supplied' });
+const absent = () => ({ status: 'absent' });
+
+function badModulePath(value) {
+  return typeof value !== 'string' || value.trim().length === 0;
+}
+
+/** Mirrors `run.mjs#resolveLifecycleAuthor`. */
+function classifyAuthor({ author, authorModulePath }, coreOptions) {
+  if (isSet(coreOptions.author)) {
+    return invalid(
+      'unsupported-core-option',
+      'coreOptions.author is not supported at the OAT adapter boundary; supply author directly.',
+    );
+  }
+  if (isSet(author) && typeof author !== 'function') {
+    return invalid(
+      'callback-not-a-function',
+      'author must be a function when supplied.',
+    );
+  }
+  if (isSet(author) && isSet(authorModulePath)) {
+    return invalid(
+      'multiple-sources',
+      'Supply only one provider-neutral author callback or author module entry point.',
+    );
+  }
+  if (!isSet(author) && !isSet(authorModulePath)) return absent();
+  if (isSet(authorModulePath) && badModulePath(authorModulePath)) {
+    return invalid(
+      'empty-module-path',
+      'authorModulePath must be a non-empty path.',
+    );
+  }
+  return supplied();
+}
+
+/**
+ * Mirrors `run.mjs#resolveLifecycleCritic`.
+ *
+ * `resolveLifecycleCritic` returns `null` rather than throwing when no critic is
+ * supplied, so treating the critic as required looks stricter than the adapter
+ * resolver in isolation. It is not, for the runs this probe serves: an
+ * artifact-bound lifecycle closeout recap passes no `suppliedFactBasePath`, so
+ * `bindProjectSources` binds it `factBase.mode: 'federated'`
+ * (`bind-project-sources.mjs`), and the core throws for a federated fact base
+ * with no critic (`explainer-kit/scripts/lib/fact-base.mjs`). Such a host cannot
+ * produce a recap today; probing the critic turns that mid-run core failure into
+ * a pre-flight capability skip. (A `supplied` fact base is a different
+ * invocation path and does skip the core's critic check, but no lifecycle recap
+ * caller uses it.) Do not "fix" this to match `resolveLifecycleCritic` — that
+ * would reintroduce an unrunnable recap.
+ */
+function classifyCritic({ critic, criticModulePath }, coreOptions) {
+  // The runtime counts only candidates that already look usable, so a
+  // non-function callback beside a module path is a type error rather than a
+  // conflict.
+  const candidates = [
+    typeof critic === 'function' ? critic : null,
+    typeof coreOptions.critic === 'function' ? coreOptions.critic : null,
+    criticModulePath ? criticModulePath : null,
+  ].filter(Boolean);
+  if (candidates.length > 1) {
+    return invalid(
+      'multiple-sources',
+      'Supply only one provider-neutral critic callback or critic module entry point.',
+    );
+  }
+  if (isSet(critic) && typeof critic !== 'function') {
+    return invalid(
+      'callback-not-a-function',
+      'critic must be a function when supplied.',
+    );
+  }
+  if (isSet(coreOptions.critic) && typeof coreOptions.critic !== 'function') {
+    return invalid(
+      'callback-not-a-function',
+      'coreOptions.critic must be a function when supplied.',
+    );
+  }
+  if (isSet(criticModulePath)) {
+    return badModulePath(criticModulePath)
+      ? invalid(
+          'empty-module-path',
+          'criticModulePath must be a non-empty path.',
+        )
+      : supplied();
+  }
+  // `coreOptions.critic` is the documented compatibility route, so it satisfies
+  // the seam rather than invalidating it.
+  return (critic ?? coreOptions.critic) ? supplied() : absent();
+}
+
+/** Mirrors `run.mjs#resolveLifecycleBrowserSession`. */
+function classifyBrowserSession(
+  {
+    browserSession,
+    browserSessionModulePath,
+    browserProbe,
+    browserProbeModulePath,
+  },
+  coreOptions,
+) {
+  if (isSet(coreOptions.browserProbe)) {
+    return invalid(
+      'unsupported-core-option',
+      'coreOptions.browserProbe is not supported at the OAT adapter boundary; supply browserSession directly.',
+    );
+  }
+  if (isSet(browserProbe) || isSet(browserProbeModulePath)) {
+    return invalid(
+      'unsupported-input',
+      'Bare browserProbe callbacks are not supported at the OAT adapter boundary; supply a branded browserSession created by createBrowserProbeSession().',
+    );
+  }
+  if (isSet(coreOptions.browserSession)) {
+    return invalid(
+      'unsupported-core-option',
+      'coreOptions.browserSession is not supported at the OAT adapter boundary; supply browserSession directly.',
+    );
+  }
+  if (isSet(browserSession) && isSet(browserSessionModulePath)) {
+    return invalid(
+      'multiple-sources',
+      'Supply only one browser session descriptor or browser session module entry point.',
+    );
+  }
+  if (isSet(browserSessionModulePath)) {
+    return badModulePath(browserSessionModulePath)
+      ? invalid(
+          'empty-module-path',
+          'browserSessionModulePath must be a non-empty path.',
+        )
+      : supplied();
+  }
+  // A browser session is a descriptor the runtime resolves by truthiness, so a
+  // falsy one raises the same "requires exactly one" error as supplying none.
+  // Classifying it invalid would fail the unattended completion this probe
+  // exists to unblock.
+  return browserSession ? supplied() : absent();
+}
+
+/** Mirrors `run.mjs#resolveLifecycleVisualCritic` and `resolveProviderCallback`. */
+function classifyVisualCritic(
+  { visualCritic, visualCriticModulePath },
+  coreOptions,
+) {
+  if (isSet(coreOptions.visualCritic)) {
+    return invalid(
+      'unsupported-core-option',
+      'coreOptions.visualCritic is not supported at the OAT adapter boundary; supply visualCritic directly.',
+    );
+  }
+  if (isSet(visualCritic) && typeof visualCritic !== 'function') {
+    return invalid(
+      'callback-not-a-function',
+      'visualCritic must be a function when supplied.',
+    );
+  }
+  if (isSet(visualCritic) && isSet(visualCriticModulePath)) {
+    return invalid(
+      'multiple-sources',
+      'Supply only one provider-neutral visual critic callback or visual critic module entry point.',
+    );
+  }
+  if (!isSet(visualCriticModulePath)) {
+    return visualCritic ? supplied() : absent();
+  }
+  return badModulePath(visualCriticModulePath)
+    ? invalid(
+        'empty-module-path',
+        'visualCriticModulePath must be a non-empty path.',
+      )
+    : supplied();
+}
+
+/** Mirrors `run.mjs#resolveLifecycleSetPlanner`. */
+function classifyPlanSet({ planSet, planSetModulePath }, coreOptions) {
+  if (isSet(coreOptions.planSet)) {
+    return invalid(
+      'unsupported-core-option',
+      'coreOptions.planSet is not supported at the OAT adapter boundary; supply planSet directly.',
+    );
+  }
+  if (isSet(planSet) && typeof planSet !== 'function') {
+    return invalid(
+      'callback-not-a-function',
+      'planSet must be a function when supplied.',
+    );
+  }
+  if (isSet(planSet) && isSet(planSetModulePath)) {
+    return invalid(
+      'multiple-sources',
+      'Supply only one provider-neutral set planner callback or set planner module entry point.',
+    );
+  }
+  if (!isSet(planSet) && !isSet(planSetModulePath)) return absent();
+  if (isSet(planSetModulePath) && badModulePath(planSetModulePath)) {
+    return invalid(
+      'empty-module-path',
+      'planSetModulePath must be a non-empty path.',
+    );
+  }
+  return supplied();
+}
+
+/**
+ * The five seams an unattended `project-recap` requires, in report order.
+ *
+ * `requiredIn` mirrors the adapter contract: the author and the fact critic are
+ * required by every federated adapter run, while the browser session, visual
+ * critic, and set planner are required only for unattended project recaps.
+ */
+const SEAMS = [
+  {
+    id: 'author',
+    requiredIn: ['interactive', 'unattended'],
+    classify: classifyAuthor,
+  },
+  {
+    id: 'critic',
+    requiredIn: ['interactive', 'unattended'],
+    classify: classifyCritic,
+  },
+  {
+    id: 'browserSession',
+    requiredIn: ['unattended'],
+    classify: classifyBrowserSession,
+  },
+  {
+    id: 'visualCritic',
+    requiredIn: ['unattended'],
+    classify: classifyVisualCritic,
+  },
+  {
+    id: 'planSet',
+    requiredIn: ['unattended'],
+    classify: classifyPlanSet,
+  },
+];
+
+export const RECAP_SEAM_IDS = Object.freeze(SEAMS.map((seam) => seam.id));
+export const RECAP_PROBE_CODES = Object.freeze([
+  'seams-ok',
+  'seams-unavailable',
+  'seams-invalid',
+]);
+
+export function probeRecapSeams(inputs = {}) {
+  if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) {
+    throw new TypeError('Seam probe inputs must be an object.');
+  }
+  const { mode = 'unattended', coreOptions = {} } = inputs;
+  if (!MODES.has(mode)) {
+    throw new Error(`Unsupported lifecycle mode: ${String(mode)}`);
+  }
+  if (!coreOptions || typeof coreOptions !== 'object') {
+    throw new TypeError('coreOptions must be an object when supplied.');
+  }
+
+  const missing = [];
+  const invalidSeams = [];
+  const resolved = [];
+
+  for (const seam of SEAMS) {
+    const outcome = seam.classify(inputs, coreOptions);
+    if (outcome.status === 'invalid') {
+      invalidSeams.push({
+        seam: seam.id,
+        reason: outcome.reason,
+        message: outcome.message,
+      });
+    } else if (outcome.status === 'supplied') {
+      resolved.push(seam.id);
+    } else if (seam.requiredIn.includes(mode)) {
+      missing.push(seam.id);
+    }
+  }
+
+  // Invalid outranks missing: a broken configuration must fail closed rather
+  // than degrade into a capability skip.
+  if (invalidSeams.length > 0) {
+    return {
+      ok: false,
+      mode,
+      code: 'seams-invalid',
+      missing,
+      invalid: invalidSeams,
+      resolved,
+      message: `Recap seam configuration is invalid: ${invalidSeams
+        .map((entry) => entry.message)
+        .join(' ')}`,
+      guidance:
+        'Correct the reported seam configuration. A configured-but-invalid seam fails closed and is never a capability skip.',
+    };
+  }
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      mode,
+      code: 'seams-unavailable',
+      missing,
+      invalid: invalidSeams,
+      resolved,
+      message: `No provider is configured for ${formatList(missing)}, so ${article(mode)} ${mode} project recap cannot run on this host.`,
+      guidance:
+        mode === 'unattended'
+          ? `Configure ${formatList(missing)} to generate an unattended project recap, or let autonomous resolution record the recap as skip / capability_probe.`
+          : `Configure ${formatList(missing)} to generate an interactive project recap, or record an interactive skip decision.`,
+    };
+  }
+
+  return {
+    ok: true,
+    mode,
+    code: 'seams-ok',
+    missing,
+    invalid: invalidSeams,
+    resolved,
+    message: `Every ${mode} project recap seam resolves on this host.`,
+    guidance: null,
+  };
+}
+
+/** `unattended` and `interactive` both take "an"; keep the surface grammatical. */
+function article(mode) {
+  return /^[aeiou]/i.test(mode) ? 'an' : 'a';
+}
+
+function formatList(values) {
+  if (values.length === 1) return values[0];
+  return `${values.slice(0, -1).join(', ')} and ${values.at(-1)}`;
+}

package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs

@@ -1,8 +1,15 @@
+import { RECAP_PROBE_CODES, RECAP_SEAM_IDS } from './probe-recap-seams.mjs';
+
 const PRODUCTS = new Set(['projectExplainer', 'projectRecap']);
 const MODES = new Set(['interactive', 'autonomous']);
 const PREFERENCES = new Set(['always', 'ask', 'never']);
 const DECISIONS = new Set(['generate', 'skip']);
-const SOURCES = new Set(['interactive', 'kickoff_prompt', 'autonomous_policy']);
+const SOURCES = new Set([
+  'interactive',
+  'kickoff_prompt',
+  'autonomous_policy',
+  'capability_probe',
+]);
 const ALLOWED_PAIRS = Object.freeze({
   projectExplainer: new Set([
     'generate:interactive',
@@ -13,6 +20,7 @@ const ALLOWED_PAIRS = Object.freeze({
     'generate:interactive',
     'skip:interactive',
     'generate:autonomous_policy',
+    'skip:capability_probe',
   ]),
 });
 const ISO_TIMESTAMP_PATTERN =
@@ -25,6 +33,7 @@ export function resolveIntent({
   preference,
   kickoffRequest = false,
   answer,
+  seamProbe,
   now = new Date().toISOString(),
 }) {
   assertProduct(product);
@@ -39,6 +48,19 @@ export function resolveIntent({
   if (typeof kickoffRequest !== 'boolean') {
     throw new TypeError('kickoffRequest must be a boolean.');
   }
+  if (seamProbe !== undefined) {
+    assertSeamProbe(seamProbe);
+    if (product !== 'projectRecap') {
+      throw new Error(
+        'Seam probe results apply only to projectRecap resolution.',
+      );
+    }
+    if (mode !== 'autonomous') {
+      throw new Error(
+        'Seam probe results apply only to autonomous projectRecap resolution.',
+      );
+    }
+  }
 
   if (mode === 'autonomous') {
     if (answer !== undefined) {
@@ -49,6 +71,7 @@ export function resolveIntent({
       state,
       preference,
       kickoffRequest,
+      seamProbe,
       now,
     });
   }
@@ -149,10 +172,30 @@ function resolveAutonomous({
   state,
   preference,
   kickoffRequest,
+  seamProbe,
   now,
 }) {
   if (product === 'projectRecap') {
     const warnings = [];
+    if (seamProbe !== undefined && seamProbe.ok !== true) {
+      if (seamProbe.code !== 'seams-unavailable') {
+        const error = new Error(
+          `Project recap seams are configured but invalid, so the recap fails closed rather than resolving a capability skip: ${seamProbe.message ?? seamProbe.code}`,
+        );
+        error.code = 'E_RECAP_SEAMS_INVALID';
+        throw error;
+      }
+      warnings.push(
+        `Autonomous project recap skipped: no provider is configured for ${formatSeams(seamProbe.missing)}.`,
+      );
+      return result(
+        product,
+        'skip',
+        'capability_probe',
+        createRecord(product, 'skip', 'capability_probe', now),
+        warnings,
+      );
+    }
     if (state?.decision === 'skip') {
       warnings.push(
         'Autonomous project recap policy overrode a lower-precedence skip decision.',
@@ -206,6 +249,85 @@ function result(
   };
 }
 
+/**
+ * A seam probe result is a decision input, so a malformed one must fail rather
+ * than silently degrade into either a skip or a forced generate.
+ */
+function assertSeamProbe(seamProbe) {
+  if (
+    !seamProbe ||
+    typeof seamProbe !== 'object' ||
+    Array.isArray(seamProbe) ||
+    typeof seamProbe.ok !== 'boolean' ||
+    !RECAP_PROBE_CODES.includes(seamProbe.code)
+  ) {
+    throw new TypeError(
+      'seamProbe must be a probeRecapSeams result with ok and a known code.',
+    );
+  }
+  // A recap that runs from this decision runs unattended, so an interactive
+  // probe is the wrong evidence: it checks only the author and critic and would
+  // report a host with no set planner as fully available.
+  if (seamProbe.mode !== 'unattended') {
+    throw new TypeError(
+      'seamProbe must come from an unattended probe of the recap seams.',
+    );
+  }
+  if (
+    !Array.isArray(seamProbe.missing) ||
+    !Array.isArray(seamProbe.invalid) ||
+    !Array.isArray(seamProbe.resolved)
+  ) {
+    throw new TypeError(
+      'seamProbe must partition the canonical recap seams into missing, invalid, and resolved.',
+    );
+  }
+  // Enforce the partition this message promises: every canonical seam appears
+  // in exactly one bucket. Without the disjointness and coverage checks, a
+  // forged result can claim a seam is both missing and resolved (yielding a
+  // capability skip the probe would never emit), or pad `resolved` with
+  // duplicates of one seam to fake full availability and force a generate.
+  const claimed = [
+    ...seamProbe.missing,
+    ...seamProbe.invalid.map((entry) => entry?.seam),
+    ...seamProbe.resolved,
+  ];
+  const distinct = new Set(claimed);
+  if (
+    distinct.size !== claimed.length ||
+    distinct.size !== RECAP_SEAM_IDS.length ||
+    !RECAP_SEAM_IDS.every((seam) => distinct.has(seam))
+  ) {
+    throw new TypeError(
+      'seamProbe must partition the canonical recap seams into missing, invalid, and resolved.',
+    );
+  }
+  // The result is a discriminated union, so each code must carry exactly the
+  // evidence it claims. A half-populated object must never reach the skip
+  // branch and forge a capability skip out of an invalid seam.
+  const consistent =
+    seamProbe.code === 'seams-ok'
+      ? seamProbe.ok === true &&
+        seamProbe.missing.length === 0 &&
+        seamProbe.invalid.length === 0 &&
+        seamProbe.resolved.length === RECAP_SEAM_IDS.length
+      : seamProbe.ok === false &&
+        (seamProbe.code === 'seams-unavailable'
+          ? seamProbe.missing.length > 0 && seamProbe.invalid.length === 0
+          : seamProbe.invalid.length > 0);
+  if (!consistent) {
+    throw new TypeError(
+      'An unsatisfied seamProbe must list the seams its code claims.',
+    );
+  }
+}
+
+function formatSeams(seams) {
+  if (!Array.isArray(seams) || seams.length === 0) return 'a required seam';
+  if (seams.length === 1) return seams[0];
+  return `${seams.slice(0, -1).join(', ')} and ${seams.at(-1)}`;
+}
+
 function assertProduct(product) {
   if (!PRODUCTS.has(product)) {
     throw new Error(`Unsupported lifecycle product: ${String(product)}`);

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-autonomous
-version: 1.0.12
+version: 1.0.13
 description: Use when a user explicitly asks to run an OAT project autonomously end-to-end. Activates session-only autonomy, resumes the correct lifecycle phase, and drives the existing OAT skills through final PR or a reported boundary.
 argument-hint: '<goal | project-slug | ticket-ref>'
 disable-model-invocation: true
@@ -267,6 +267,15 @@ Reassert this forced recap intent on resume; a stale lower-precedence skip is ov
 The autonomous mode policy has precedence over project state and workflow
 preference, so `never` does not suppress the recap.
 
+Kickoff persists the forced `generate` intent without probing seams, because the
+host that runs the recap is the one that matters and closeout is where it runs.
+The closeout recap gate probes seam availability and may resolve a recordable
+`skip` with source `capability_probe` on a host where a required seam is
+unavailable. That later capability skip is the only thing that overrides this
+forced intent, it is decided before any run rather than from a failed one, and
+it never blocks unattended completion. Do not reassert `generate` over a
+recorded `capability_probe` skip within the same closeout.
+
 Resolve and persist `projectExplainer` as `generate` with source `kickoff_prompt` only when the kickoff request explicitly asks for a project explainer.
 A general autonomous goal, project creation, or normal planning does not count as an explainer request.
 When no explicit kickoff explainer request exists, do not persist a project-explainer intent record.