cclaw-cli 7.3.0 → 7.4.0

package/dist/content/core-agents.js

@@ -165,6 +165,11 @@ export function sliceBuilderProtocol() {
         "- Honor every `delegation-record`/`delegation-record.mjs` row shape the controller requests so artifact linters keep passing.",
         "- The umbrella `slice-completed` row ties RED/GREEN/REFACTOR/DOC timestamps to your builder span.",
         "",
+        "### Streaming output contract",
+        "- Emit one JSON line to stdout per completed phase: `{\"event\":\"phase-completed\",\"stage\":\"tdd\",\"sliceId\":\"S-<n>\",\"phase\":\"<red|green|refactor|refactor-deferred|doc>\",\"spanId\":\"<span>\",\"runId\":\"<run>\",\"ts\":\"<iso>\"}`.",
+        "- For `phase=green` with inline/deferred refactor folding, include `refactorOutcome.mode` in the same JSON line so live controllers can close the slice without waiting for file sync.",
+        "- If streaming is unavailable in your harness/runtime, keep writing canonical `delegation-record` rows; controller-side live mode will fall back to file-based events.",
+        "",
         "**Role boundary:** do not widen scope, do not self-approve ship-level review, and do not recurse into other agents unless the parent explicitly directs it."
     ].join("\n");
 }

package/dist/internal/wave-status.d.ts

@@ -32,6 +32,17 @@ export interface RunWaveStatusOptions {
      * `<projectRoot>/.cclaw/artifacts`.
      */
     artifactsDir?: string;
+    /**
+     * Event ingestion mode:
+     * - auto: prefer live stream file; fallback to delegation-events.jsonl.
+     * - live: force live stream first; fallback to delegation-events.jsonl with warning.
+     * - file: skip stream file and use delegation-events.jsonl only.
+     */
+    streamMode?: "auto" | "live" | "file";
+    /**
+     * Optional absolute stream path override (tests).
+     */
+    streamPath?: string;
 }
 /**
  * Deterministic helper for the TDD controller. Reads the managed

package/dist/internal/wave-status.js

@@ -3,16 +3,21 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
 import { readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { readFlowState } from "../runs.js";
+import { DEFAULT_SLICE_STREAM_REL_PATH, readEventStreamFile } from "../streaming/event-stream.js";
 import { mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./plan-split-waves.js";
 const PARALLEL_EXEC_MANAGED_START = "<!-- parallel-exec-managed-start -->";
 const PARALLEL_EXEC_MANAGED_END = "<!-- parallel-exec-managed-end -->";
 function parseArgs(tokens) {
-    const args = { format: "json" };
+    const args = { format: "json", streamMode: "auto" };
     for (const token of tokens) {
         if (token === "--json")
             args.format = "json";
         else if (token === "--human" || token === "--text")
             args.format = "human";
+        else if (token === "--live")
+            args.streamMode = "live";
+        else if (token === "--file-only")
+            args.streamMode = "file";
         else if (token.startsWith("--format=")) {
             const raw = token.slice("--format=".length).trim();
             if (raw === "json" || raw === "human")
@@ -20,6 +25,13 @@ function parseArgs(tokens) {
             else
                 throw new Error(`Unknown wave-status --format value: ${raw}`);
         }
+        else if (token.startsWith("--stream-mode=")) {
+            const raw = token.slice("--stream-mode=".length).trim();
+            if (raw === "auto" || raw === "live" || raw === "file")
+                args.streamMode = raw;
+            else
+                throw new Error(`Unknown wave-status --stream-mode value: ${raw}`);
+        }
         else {
             throw new Error(`Unknown wave-status flag: ${token}`);
         }
@@ -228,34 +240,72 @@ export async function runWaveStatus(projectRoot, options = {}) {
             }
         }
     }
-    // Also consult the JSONL events in case the ledger projection lags.
-    try {
-        const { events } = await readDelegationEvents(projectRoot);
-        for (const ev of events) {
-            if (ev.event !== "completed")
-                continue;
-            if (ev.runId !== activeRunId)
-                continue;
-            if (ev.stage !== "tdd")
-                continue;
-            if (typeof ev.sliceId !== "string")
-                continue;
-            if (typeof ev.phase !== "string")
-                continue;
-            if (TERMINAL_PHASES.has(ev.phase)) {
-                closedSlices.add(ev.sliceId);
-                continue;
-            }
-            if (ev.phase === "green" && ev.refactorOutcome) {
-                const mode = ev.refactorOutcome.mode;
-                if (mode === "inline" || mode === "deferred") {
+    const warnings = [];
+    const streamMode = options.streamMode ?? "auto";
+    const streamPath = options.streamPath ?? path.join(projectRoot, DEFAULT_SLICE_STREAM_REL_PATH);
+    let shouldReadJsonlFallback = streamMode === "file";
+    // Prefer live stream events when requested/available.
+    if (streamMode !== "file") {
+        const streamResult = await readEventStreamFile(streamPath);
+        if (streamResult.droppedLines > 0) {
+            warnings.push(`wave_stream_dropped_lines: ${streamResult.droppedLines}`);
+        }
+        if (streamResult.events.length > 0) {
+            for (const ev of streamResult.events) {
+                if (ev.runId && ev.runId !== activeRunId)
+                    continue;
+                if (ev.stage && ev.stage !== "tdd")
+                    continue;
+                if (TERMINAL_PHASES.has(ev.phase)) {
                     closedSlices.add(ev.sliceId);
+                    continue;
+                }
+                if (ev.phase === "green" && ev.refactorOutcome) {
+                    const mode = ev.refactorOutcome.mode;
+                    if (mode === "inline" || mode === "deferred") {
+                        closedSlices.add(ev.sliceId);
+                    }
                 }
             }
+            shouldReadJsonlFallback = false;
+        }
+        else {
+            shouldReadJsonlFallback = true;
+            if (streamMode === "auto" || streamMode === "live") {
+                warnings.push("wave_status_live_fallback_to_file: no parseable stream events");
+            }
         }
     }
-    catch {
-        // best-effort; ledger already covers the canonical case.
+    // Fallback to JSONL events when live stream is absent or disabled.
+    if (shouldReadJsonlFallback) {
+        try {
+            const { events } = await readDelegationEvents(projectRoot);
+            for (const ev of events) {
+                if (ev.event !== "completed")
+                    continue;
+                if (ev.runId !== activeRunId)
+                    continue;
+                if (ev.stage !== "tdd")
+                    continue;
+                if (typeof ev.sliceId !== "string")
+                    continue;
+                if (typeof ev.phase !== "string")
+                    continue;
+                if (TERMINAL_PHASES.has(ev.phase)) {
+                    closedSlices.add(ev.sliceId);
+                    continue;
+                }
+                if (ev.phase === "green" && ev.refactorOutcome) {
+                    const mode = ev.refactorOutcome.mode;
+                    if (mode === "inline" || mode === "deferred") {
+                        closedSlices.add(ev.sliceId);
+                    }
+                }
+            }
+        }
+        catch {
+            // best-effort; ledger already covers the canonical case.
+        }
     }
     const waves = merged.map((wave) => {
         const members = wave.members.map((m) => m.sliceId);
@@ -272,7 +322,6 @@ export async function runWaveStatus(projectRoot, options = {}) {
         };
     });
     const firstOpenWave = waves.find((w) => w.status === "open" || w.status === "partial") ?? null;
-    const warnings = [];
     if (merged.length === 0 && planRaw.length === 0) {
         warnings.push("wave_plan_missing: 05-plan.md not found or empty under <artifacts-dir>.");
     }
@@ -349,7 +398,7 @@ export async function runWaveStatusCommand(projectRoot, argv, io) {
         io.stderr.write(`cclaw internal wave-status: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }
-    const report = await runWaveStatus(projectRoot);
+    const report = await runWaveStatus(projectRoot, { streamMode: parsed.streamMode });
     if (parsed.format === "json") {
         io.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
     }

package/dist/streaming/event-stream.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_SLICE_STREAM_REL_PATH = ".cclaw/state/slice-builder-stream.jsonl";
+export interface SliceBuilderPhaseEvent {
+    event: "phase-completed";
+    runId?: string;
+    stage?: string;
+    sliceId: string;
+    phase: string;
+    spanId?: string;
+    refactorOutcome?: {
+        mode?: string;
+    };
+}
+export interface EventStreamParseResult {
+    events: SliceBuilderPhaseEvent[];
+    droppedLines: number;
+}
+/**
+ * Incremental JSONL parser with bounded in-memory buffer. If chunks arrive
+ * faster than the consumer drains complete lines, we trim the oldest partial
+ * payload once maxBufferBytes is exceeded instead of letting memory grow
+ * unbounded.
+ */
+export declare class EventStreamLineBuffer {
+    private readonly maxBufferBytes;
+    private buffer;
+    constructor(maxBufferBytes?: number);
+    push(chunk: string | Buffer): EventStreamParseResult;
+    flush(): EventStreamParseResult;
+}
+export declare function parseEventStreamText(raw: string): EventStreamParseResult;
+export declare function readEventStreamFile(absPath: string): Promise<EventStreamParseResult>;

package/dist/streaming/event-stream.js

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+export const DEFAULT_SLICE_STREAM_REL_PATH = ".cclaw/state/slice-builder-stream.jsonl";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function parseEventLine(rawLine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawLine);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (parsed.event !== "phase-completed")
+        return null;
+    const sliceId = asString(parsed.sliceId);
+    const phase = asString(parsed.phase);
+    if (!sliceId || !phase)
+        return null;
+    const stage = asString(parsed.stage);
+    const runId = asString(parsed.runId);
+    const spanId = asString(parsed.spanId);
+    const refactorOutcome = isRecord(parsed.refactorOutcome)
+        ? { mode: asString(parsed.refactorOutcome.mode) }
+        : undefined;
+    return {
+        event: "phase-completed",
+        ...(runId ? { runId } : {}),
+        ...(stage ? { stage } : {}),
+        sliceId,
+        phase,
+        ...(spanId ? { spanId } : {}),
+        ...(refactorOutcome ? { refactorOutcome } : {})
+    };
+}
+/**
+ * Incremental JSONL parser with bounded in-memory buffer. If chunks arrive
+ * faster than the consumer drains complete lines, we trim the oldest partial
+ * payload once maxBufferBytes is exceeded instead of letting memory grow
+ * unbounded.
+ */
+export class EventStreamLineBuffer {
+    maxBufferBytes;
+    buffer = "";
+    constructor(maxBufferBytes = 256 * 1024) {
+        this.maxBufferBytes = maxBufferBytes;
+    }
+    push(chunk) {
+        this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        let droppedLines = 0;
+        if (this.buffer.length > this.maxBufferBytes) {
+            const overflowStart = this.buffer.length - this.maxBufferBytes;
+            const nextBreak = this.buffer.indexOf("\n", overflowStart);
+            if (nextBreak >= 0) {
+                this.buffer = this.buffer.slice(nextBreak + 1);
+            }
+            else {
+                this.buffer = "";
+            }
+            droppedLines += 1;
+        }
+        const events = [];
+        let newlineIdx = this.buffer.indexOf("\n");
+        while (newlineIdx >= 0) {
+            const line = this.buffer.slice(0, newlineIdx).trim();
+            this.buffer = this.buffer.slice(newlineIdx + 1);
+            if (line.length > 0) {
+                const parsed = parseEventLine(line);
+                if (parsed)
+                    events.push(parsed);
+                else
+                    droppedLines += 1;
+            }
+            newlineIdx = this.buffer.indexOf("\n");
+        }
+        return { events, droppedLines };
+    }
+    flush() {
+        if (this.buffer.trim().length === 0) {
+            this.buffer = "";
+            return { events: [], droppedLines: 0 };
+        }
+        const parsed = parseEventLine(this.buffer.trim());
+        this.buffer = "";
+        if (parsed) {
+            return { events: [parsed], droppedLines: 0 };
+        }
+        return { events: [], droppedLines: 1 };
+    }
+}
+export function parseEventStreamText(raw) {
+    const buffer = new EventStreamLineBuffer();
+    const pushed = buffer.push(raw);
+    const flushed = buffer.flush();
+    return {
+        events: [...pushed.events, ...flushed.events],
+        droppedLines: pushed.droppedLines + flushed.droppedLines
+    };
+}
+export async function readEventStreamFile(absPath) {
+    let raw = "";
+    try {
+        raw = await fs.readFile(absPath, "utf8");
+    }
+    catch {
+        return { events: [], droppedLines: 0 };
+    }
+    return parseEventStreamText(raw);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {