@cat-factory/orchestration 0.113.1 → 0.114.0

package/dist/modules/execution/ralph.logic.js

@@ -0,0 +1,80 @@
+import { RALPH_AGENT_KIND, RALPH_DEFAULT_MAX_ITERATIONS, RALPH_MAX_ITERATIONS_CONFIG_ID, RALPH_VALIDATION_COMMAND_CONFIG_ID, } from '@cat-factory/agents';
+// Pure logic + constants for the "Ralph loop" step — a persistent, retry-until-done coding
+// loop whose exit condition is a programmatic validation command run by the harness. Kept
+// side-effect-free (no engine I/O) so it is unit- and conformance-testable in isolation; the
+// stateful driving lives in `RalphController` + `RunDispatcher`.
+// Re-exported so in-package sites source the kind id here (agents stays the single source).
+export { RALPH_AGENT_KIND };
+/** Default repo-relative path of the append-only progress log the ralph agent maintains. */
+export const RALPH_PROGRESS_PATH = '.cat-factory/ralph-progress.md';
+/**
+ * Hard ceiling on the per-task iteration budget, so a fat-fingered config value can't make the
+ * loop spin (near-)forever. Well above any sane hand-set budget; the default is much smaller.
+ */
+export const MAX_RALPH_ITERATIONS_CAP = 50;
+/** Whether a step's kind is the ralph-loop kind. */
+export function isRalphKind(kind) {
+    return kind === RALPH_AGENT_KIND;
+}
+/**
+ * Resolve a ralph step's per-task config from the block's agent-config values: the validation
+ * command (the completion criterion) and the iteration budget (clamped, defaulting to
+ * {@link RALPH_DEFAULT_MAX_ITERATIONS}). The command may resolve empty when the task pinned
+ * none — the engine treats that as a misconfiguration and fails the step with a clear message
+ * (a ralph loop is meaningless without a programmatic criterion).
+ */
+export function resolveRalphConfig(agentConfig) {
+    const validationCommand = (agentConfig?.[RALPH_VALIDATION_COMMAND_CONFIG_ID] ?? '').trim();
+    const raw = Number(agentConfig?.[RALPH_MAX_ITERATIONS_CONFIG_ID]);
+    const maxIterations = Number.isFinite(raw) && raw >= 1
+        ? Math.min(Math.floor(raw), MAX_RALPH_ITERATIONS_CAP)
+        : RALPH_DEFAULT_MAX_ITERATIONS;
+    return { validationCommand, maxIterations };
+}
+/** Seed a fresh ralph step state from a resolved config (attempts start at 0, no history). */
+export function seedRalphState(config) {
+    return {
+        phase: 'iterating',
+        attempts: 0,
+        maxIterations: config.maxIterations,
+        validationCommand: config.validationCommand,
+        progressPath: RALPH_PROGRESS_PATH,
+        attemptLog: [],
+    };
+}
+/**
+ * Fold a ralph step's state into the container context's `ralphValidation` block: the command
+ * the harness runs, the progress-log path, and the 1-based iteration number about to run
+ * (`attempts + 1`). Returns undefined when the step carries no ralph state or an empty command
+ * (a misconfigured step must not dispatch a validation-less run — the engine fails it instead).
+ */
+export function buildRalphValidation(ralph) {
+    if (!ralph || !ralph.validationCommand.trim())
+        return undefined;
+    return {
+        command: ralph.validationCommand,
+        progressPath: ralph.progressPath ?? RALPH_PROGRESS_PATH,
+        iteration: ralph.attempts + 1,
+    };
+}
+/**
+ * Decide the loop's next move from the step state (AFTER the just-finished iteration has been
+ * counted into `attempts`) and its verdict: the criterion passed ⇒ `done`; else another
+ * iteration remains within the budget ⇒ `retry`; else the budget is spent ⇒ `exhausted`.
+ */
+export function decideRalphNext(ralph, verdict) {
+    if (verdict?.validationPassed)
+        return 'done';
+    return ralph.attempts < ralph.maxIterations ? 'retry' : 'exhausted';
+}
+/** One-line, human-readable summary of a verdict for notifications / failure messages. */
+export function describeRalphVerdict(verdict) {
+    if (!verdict)
+        return 'the validation run produced no verdict';
+    if (verdict.validationPassed)
+        return 'the validation command passed';
+    const tail = verdict.validationOutputTail?.trim();
+    const head = `the validation command failed (exit ${verdict.exitCode})`;
+    return tail ? `${head}:\n${tail}` : head;
+}
+//# sourceMappingURL=ralph.logic.js.map

package/dist/modules/execution/ralph.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/ralph.logic.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,8BAA8B,EAC9B,kCAAkC,GACnC,MAAM,qBAAqB,CAAA;AAE5B,2FAA2F;AAC3F,0FAA0F;AAC1F,6FAA6F;AAC7F,iEAAiE;AAEjE,4FAA4F;AAC5F,OAAO,EAAE,gBAAgB,EAAE,CAAA;AAE3B,4FAA4F;AAC5F,MAAM,CAAC,MAAM,mBAAmB,GAAG,gCAAgC,CAAA;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAA;AAE1C,oDAAoD;AACpD,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,KAAK,gBAAgB,CAAA;AAClC,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAA0C;IAC3E,MAAM,iBAAiB,GAAG,CAAC,WAAW,EAAE,CAAC,kCAAkC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1F,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,8BAA8B,CAAC,CAAC,CAAA;IACjE,MAAM,aAAa,GACjB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAC9B,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,wBAAwB,CAAC;QACrD,CAAC,CAAC,4BAA4B,CAAA;IAClC,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAA;AAC7C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,QAAQ,EAAE,CAAC;QACX,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,YAAY,EAAE,mBAAmB;QACjC,UAAU,EAAE,EAAE;KACf,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAwC;IAExC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAAE,OAAO,SAAS,CAAA;IAC/D,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,iBAAiB;QAChC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,mBAAmB;QACvD,SAAS,EAAE,KAAK,CAAC,QAAQ,GAAG,CAAC;KAC9B,CAAA;AACH,CAAC;AAKD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAqB,EACrB,OAA4B;IAE5B,IAAI,OAAO,EAAE,gBAAgB;QAAE,OAAO,MAAM,CAAA;IAC5C,OAAO,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAA;AACrE,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,oBAAoB,CAAC,OAA4B;IAC/D,IAAI,CAAC,OAAO;QAAE,OAAO,wCAAwC,CAAA;IAC7D,IAAI,OAAO,CAAC,gBAAgB;QAAE,OAAO,+BAA+B,CAAA;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAA;IACjD,MAAM,IAAI,GAAG,uCAAuC,OAAO,CAAC,QAAQ,GAAG,CAAA;IACvE,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/orchestration",
-  "version": "0.113.1",
+  "version": "0.114.0",
   "description": "Delivery-workflow engine for the Agent Architecture Board (execution, bootstrap, pipelines, board, boardScan, requirements, and composition root).",
   "repository": {
     "type": "git",
@@ -25,20 +25,20 @@
   },
   "dependencies": {
     "ai": "^6.0.224",
-    "@cat-factory/contracts": "0.134.0",
-    "@cat-factory/agents": "0.59.1",
-    "@cat-factory/caching": "0.8.6",
-    "@cat-factory/integrations": "0.84.4",
-    "@cat-factory/kernel": "0.129.1",
-    "@cat-factory/workspaces": "0.13.46",
-    "@cat-factory/sandbox": "0.9.85",
-    "@cat-factory/prompt-fragments": "0.13.23",
-    "@cat-factory/spend": "0.12.35"
+    "@cat-factory/agents": "0.60.0",
+    "@cat-factory/caching": "0.8.8",
+    "@cat-factory/contracts": "0.136.0",
+    "@cat-factory/integrations": "0.84.6",
+    "@cat-factory/kernel": "0.130.0",
+    "@cat-factory/prompt-fragments": "0.13.25",
+    "@cat-factory/sandbox": "0.9.87",
+    "@cat-factory/spend": "0.12.37",
+    "@cat-factory/workspaces": "0.13.48"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/sandbox-fixtures": "0.7.158"
+    "@cat-factory/sandbox-fixtures": "0.7.160"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",