@cat-factory/orchestration 0.21.1 → 0.23.0

package/dist/validation/validateRegistrations.js

@@ -0,0 +1,150 @@
+import { registeredAgentKinds, registeredKindRequiresContainer, registeredStructuredOutput, } from '@cat-factory/agents';
+import { CI_FIXER_AGENT_KIND, CONFLICT_RESOLVER_AGENT_KIND, ON_CALL_AGENT_KIND, registeredGateFactories, registeredPipelines, stubGateContext, } from '@cat-factory/kernel';
+import { RESULT_VIEW_ID_SET } from '@cat-factory/contracts';
+// ---------------------------------------------------------------------------
+// Boot-time validation of the deployment's registered extensions (agent kinds, gates,
+// pipelines). A typo'd gate `helperKind`, an unknown `resultView`, or a pipeline naming a
+// kind that doesn't exist used to surface mid-run (a failed dispatch) or silently (a prose
+// fallback). `validateRegistrations()` turns those into a LOUD startup error instead — a
+// facade calls it once after all `register*` side-effect imports + provider wiring, before
+// serving, so a misconfigured deployment fails fast at boot.
+//
+// This lives in orchestration because it cross-checks the gate registry (kernel) against the
+// agent-kind registry (@cat-factory/agents) and the pipeline registry — only orchestration
+// depends on all three.
+// ---------------------------------------------------------------------------
+/** Built-in container helper kinds a gate may escalate to (handled by the executor/harness,
+ * not the custom-kind registry). A gate `helperKind` is valid if it's one of these or a
+ * registered container-capable kind. */
+const BUILT_IN_HELPER_KINDS = new Set([
+    CI_FIXER_AGENT_KIND,
+    CONFLICT_RESOLVER_AGENT_KIND,
+    ON_CALL_AGENT_KIND,
+]);
+/**
+ * Collect every registration problem (does not throw). Useful for tests and for callers that
+ * want to log warnings without aborting. {@link validateRegistrations} throws on any `error`.
+ */
+export function collectRegistrationProblems(opts = {}) {
+    const knownResultViewIds = opts.knownResultViewIds ?? RESULT_VIEW_ID_SET;
+    const builtInHelperKinds = opts.builtInHelperKinds ?? BUILT_IN_HELPER_KINDS;
+    const problems = [];
+    const agentKinds = registeredAgentKinds();
+    const registeredKindIds = new Set(agentKinds.map((d) => d.kind));
+    const gateKinds = new Set(registeredGateFactories().map((g) => g.kind));
+    // 1. Every gate's helperKind must resolve to a registered container-capable kind or a
+    //    built-in helper. The factory is a pure constructor, so we build it with a stub context
+    //    just to read its declared helperKind.
+    for (const { kind, factory } of registeredGateFactories()) {
+        let helperKind;
+        try {
+            helperKind = factory(stubGateContext()).helperKind;
+        }
+        catch (err) {
+            problems.push({
+                severity: 'error',
+                code: 'gate_factory_threw',
+                message: `Gate "${kind}" factory threw while validating: ${err.message}`,
+            });
+            continue;
+        }
+        const helperOk = builtInHelperKinds.has(helperKind) ||
+            (registeredKindIds.has(helperKind) && registeredKindRequiresContainer(helperKind));
+        if (!helperOk) {
+            problems.push({
+                severity: 'error',
+                code: 'gate_helper_unresolved',
+                message: `Gate "${kind}" escalates to helperKind "${helperKind}", which is neither a ` +
+                    `built-in helper nor a registered container-capable agent kind. Register the helper ` +
+                    `(a container surface) or fix the helperKind.`,
+            });
+        }
+    }
+    // 2. Every registered kind's presentation.resultView must be a known view id (else the SPA
+    //    silently falls back to prose).
+    for (const def of agentKinds) {
+        const resultView = def.presentation?.resultView;
+        if (resultView !== undefined && !knownResultViewIds.has(resultView)) {
+            problems.push({
+                severity: 'error',
+                code: 'unknown_result_view',
+                message: `Agent kind "${def.kind}" declares resultView "${resultView}", which is not a known ` +
+                    `result view. Use one of: ${[...knownResultViewIds].join(', ')}.`,
+            });
+        }
+    }
+    // 3. Coherence (warn): a kind with postOps that has an agent step which is NOT structured
+    //    output likely can't feed those post-ops from `result.custom`. Heuristic, so a warning.
+    for (const def of agentKinds) {
+        const hasPostOps = (def.postOps?.length ?? 0) > 0;
+        const declaresStructured = def.agent?.output?.kind === 'structured' || registeredStructuredOutput(def.kind) !== undefined;
+        if (hasPostOps && def.agent && !declaresStructured) {
+            problems.push({
+                severity: 'warn',
+                code: 'postops_without_structured_output',
+                message: `Agent kind "${def.kind}" declares postOps but its agent step has no structured ` +
+                    `output — postOps that read result.custom will see nothing. Declare structuredOutput ` +
+                    `(or agent.output.kind: 'structured') if the post-op consumes the agent's JSON.`,
+            });
+        }
+    }
+    // 4. Pipeline kinds (only when a built-in catalog is supplied — see option doc).
+    if (opts.knownAgentKinds) {
+        const known = opts.knownAgentKinds;
+        for (const pipeline of registeredPipelines()) {
+            for (const agentKind of pipeline.agentKinds) {
+                const ok = known.has(agentKind) ||
+                    registeredKindIds.has(agentKind) ||
+                    gateKinds.has(agentKind) ||
+                    builtInHelperKinds.has(agentKind);
+                if (!ok) {
+                    problems.push({
+                        severity: 'error',
+                        code: 'pipeline_unknown_kind',
+                        message: `Pipeline "${pipeline.id}" references agent kind "${agentKind}", which is not a ` +
+                            `known built-in, a registered kind, or a registered gate.`,
+                    });
+                }
+            }
+        }
+    }
+    return problems;
+}
+/**
+ * Validate the registered extensions, throwing an aggregated error on any `error`-severity
+ * problem and logging `warn`-severity ones. Call once at facade boot, after every `register*`
+ * import side effect + provider wiring, before serving requests.
+ */
+export function validateRegistrations(opts = {}) {
+    const problems = collectRegistrationProblems(opts);
+    if (opts.onWarn) {
+        for (const w of problems.filter((p) => p.severity === 'warn'))
+            opts.onWarn(w);
+    }
+    const errors = problems.filter((p) => p.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`Invalid extension registrations (${errors.length}):\n` +
+            errors.map((e) => `  - [${e.code}] ${e.message}`).join('\n'));
+    }
+}
+// A module-level guard so a per-request facade build (the Worker rebuilds its container per
+// request) validates ONCE rather than on every request. Tests that intentionally register
+// bogus kinds call `collectRegistrationProblems`/`validateRegistrations` directly instead.
+let validated = false;
+/** Run {@link validateRegistrations} at most once per process. Safe to call from a per-request build. */
+export function validateRegistrationsOnce(opts = {}) {
+    if (validated)
+        return;
+    // Flip the guard only AFTER a clean validation. Setting it first would poison the guard on a
+    // throw: on the Worker (where this runs inside `fetch` on the first request) a misconfigured
+    // deployment would 500 exactly once, then — the module flag now `true` for the isolate's life —
+    // serve the broken config silently on every later request. Validating until it passes keeps the
+    // failure loud (every request re-throws) until the deployment is fixed, matching the boot intent.
+    validateRegistrations(opts);
+    validated = true;
+}
+/** Reset the once-guard. Intended for tests that exercise the boot path repeatedly. */
+export function resetRegistrationValidationGuard() {
+    validated = false;
+}
+//# sourceMappingURL=validateRegistrations.js.map

package/dist/validation/validateRegistrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateRegistrations.js","sourceRoot":"","sources":["../../src/validation/validateRegistrations.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/orchestration",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Delivery-workflow engine for the Agent Architecture Board (execution, bootstrap, pipelines, board, boardScan, requirements, and composition root).",
   "repository": {
     "type": "git",
@@ -25,14 +25,14 @@
   },
   "dependencies": {
     "ai": "^6.0.209",
-    "@cat-factory/agents": "0.14.8",
-    "@cat-factory/contracts": "0.25.1",
-    "@cat-factory/integrations": "0.20.1",
-    "@cat-factory/kernel": "0.28.1",
-    "@cat-factory/prompt-fragments": "0.7.23",
-    "@cat-factory/sandbox": "0.8.1",
-    "@cat-factory/spend": "0.9.2",
-    "@cat-factory/workspaces": "0.7.35"
+    "@cat-factory/agents": "0.15.0",
+    "@cat-factory/contracts": "0.27.0",
+    "@cat-factory/integrations": "0.21.1",
+    "@cat-factory/kernel": "0.30.0",
+    "@cat-factory/prompt-fragments": "0.7.25",
+    "@cat-factory/sandbox": "0.8.3",
+    "@cat-factory/spend": "0.9.4",
+    "@cat-factory/workspaces": "0.7.37"
   },
   "devDependencies": {
     "typescript": "7.0.1-rc",