@nt-ai-lab/deterministic-agent-workflow-cli 0.2.0 → 0.3.0

package/dist/features/workflow-cli/entrypoint/workflow-cli.js

@@ -55,6 +55,9 @@ export function createWorkflowCli(config) {
         const result = runner(args, engineDeps, workflowDeps, {
             readStdin,
             getSessionId,
+            getSessionRepository: () => getRepositoryName(process.cwd()),
+            getRepositoryRoot: () => process.cwd(),
+            getWorkflowEventsDbPath: () => workflowEventsDbPath,
         });
         if (result.output) {
             processDeps.writeStdout(result.output);

package/dist/features/workflow-runner/domain/reflection-process-observations.d.ts

@@ -0,0 +1,14 @@
+import type { StoredEvent } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { ReflectionProcess, StatePeriod } from './reflection-process-types';
+/** @riviere-role domain-service */
+export declare function computeStatePeriods(events: readonly StoredEvent[], currentState: string): ReadonlyArray<StatePeriod>;
+/** @riviere-role domain-service */
+export declare function buildObservedEventTypes(events: readonly StoredEvent[]): ReflectionProcess['workflow']['observedEventTypes'];
+/** @riviere-role domain-service */
+export declare function buildStateDurationSummary(periods: readonly StatePeriod[]): ReflectionProcess['observations']['stateDurations'];
+/** @riviere-role domain-service */
+export declare function buildTransitionSummary(events: readonly StoredEvent[]): ReflectionProcess['observations']['transitions'];
+/** @riviere-role domain-service */
+export declare function buildDenialSummary(events: readonly StoredEvent[]): ReflectionProcess['observations']['denials'];
+/** @riviere-role domain-service */
+export declare function buildToolSummary(transcriptPath: string | undefined, sessionId: string, periods: readonly StatePeriod[]): ReflectionProcess['observations']['tools'];

package/dist/features/workflow-runner/domain/reflection-process-observations.js

@@ -0,0 +1,309 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { openSqliteDatabase } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+const jsonlToolUseSchema = z.object({
+    type: z.literal('tool_use'),
+    name: z.string(),
+});
+const jsonlAssistantSchema = z.object({
+    type: z.literal('assistant'),
+    timestamp: z.string().optional(),
+    message: z.object({ content: z.array(z.unknown()).optional() }).optional(),
+});
+const opencodeActivityRowSchema = z.object({
+    m_time: z.number().nullable(),
+    p_time: z.number().nullable(),
+    part_data: z.string(),
+});
+const opencodeToolPartSchema = z.object({
+    type: z.literal('tool'),
+    tool: z.string(),
+});
+function parseTs(raw) {
+    if (typeof raw !== 'string')
+        return 0;
+    const parsed = Date.parse(raw);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function safeParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function collectToolUses(content, timestampMs) {
+    const results = [];
+    for (const block of content) {
+        const parsed = jsonlToolUseSchema.safeParse(block);
+        if (parsed.success) {
+            results.push({
+                name: parsed.data.name,
+                timestampMs,
+            });
+        }
+    }
+    return results;
+}
+function extractToolCallsFromJsonl(path) {
+    const raw = readFileSync(path, 'utf8');
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    return lines.flatMap((line) => {
+        const parsed = jsonlAssistantSchema.safeParse(safeParseJson(line));
+        if (!parsed.success)
+            return [];
+        return collectToolUses(parsed.data.message?.content ?? [], parseTs(parsed.data.timestamp));
+    });
+}
+function extractOpencodeToolCall(row) {
+    const parsedRow = opencodeActivityRowSchema.safeParse(row);
+    if (!parsedRow.success)
+        return null;
+    const parsedPart = opencodeToolPartSchema.safeParse(safeParseJson(parsedRow.data.part_data));
+    if (!parsedPart.success)
+        return null;
+    return {
+        name: parsedPart.data.tool,
+        timestampMs: parsedRow.data.p_time ?? parsedRow.data.m_time ?? 0,
+    };
+}
+function extractToolCallsFromOpencode(path, sessionId) {
+    const db = openSqliteDatabase(path, { readonly: true });
+    try {
+        const rows = db.prepare(`
+      SELECT m.time_created as m_time, p.time_created as p_time, p.data as part_data
+      FROM message m
+      JOIN part p ON p.message_id = m.id
+      WHERE m.session_id = ?
+      ORDER BY m.time_created ASC, p.time_created ASC
+    `).all(sessionId);
+        const calls = [];
+        for (const row of rows) {
+            const call = extractOpencodeToolCall(row);
+            if (call !== null)
+                calls.push(call);
+        }
+        return calls;
+    }
+    finally {
+        db.close();
+    }
+}
+function readToolCalls(transcriptPath, sessionId) {
+    if (transcriptPath === undefined || transcriptPath.length === 0)
+        return [];
+    try {
+        if (transcriptPath.endsWith('.jsonl'))
+            return extractToolCallsFromJsonl(transcriptPath);
+        if (transcriptPath.endsWith('.db'))
+            return extractToolCallsFromOpencode(transcriptPath, sessionId);
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/** @riviere-role domain-service */
+export function computeStatePeriods(events, currentState) {
+    if (events.length === 0)
+        return [];
+    const firstEvent = events[0];
+    const lastEvent = events[events.length - 1];
+    const startEvent = events.find((event) => event.envelope.type === 'session-started') ?? firstEvent;
+    const startStateRaw = startEvent.payload['currentState'];
+    const initialState = typeof startStateRaw === 'string' && startStateRaw.length > 0 ? startStateRaw : currentState;
+    const aggregated = events.reduce((accumulator, event) => {
+        if (event.envelope.type !== 'transitioned')
+            return accumulator;
+        const nextState = event.payload['to'];
+        if (typeof nextState !== 'string' || nextState.length === 0)
+            return accumulator;
+        const endedAt = event.envelope.at;
+        return {
+            state: nextState,
+            startedAt: endedAt,
+            periods: [...accumulator.periods, {
+                    state: accumulator.state,
+                    startedAt: accumulator.startedAt,
+                    endedAt,
+                    durationMs: Math.max(parseTs(endedAt) - parseTs(accumulator.startedAt), 0),
+                }],
+        };
+    }, {
+        state: initialState,
+        startedAt: startEvent.envelope.at,
+        periods: [],
+    });
+    return [...aggregated.periods, {
+            state: aggregated.state,
+            startedAt: aggregated.startedAt,
+            endedAt: lastEvent.envelope.at,
+            durationMs: Math.max(parseTs(lastEvent.envelope.at) - parseTs(aggregated.startedAt), 0),
+        }];
+}
+/** @riviere-role domain-service */
+export function buildObservedEventTypes(events) {
+    const counts = new Map();
+    const payloadKeys = new Map();
+    for (const event of events) {
+        counts.set(event.envelope.type, (counts.get(event.envelope.type) ?? 0) + 1);
+        const keys = payloadKeys.get(event.envelope.type) ?? new Set();
+        for (const key of Object.keys(event.payload))
+            keys.add(key);
+        payloadKeys.set(event.envelope.type, keys);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([type, count]) => ({
+        type,
+        count,
+        payloadKeys: [...(payloadKeys.get(type) ?? new Set())].sort((a, b) => a.localeCompare(b)),
+    }));
+}
+/** @riviere-role domain-service */
+export function buildStateDurationSummary(periods) {
+    const totalDurationMs = periods.reduce((sum, period) => sum + period.durationMs, 0);
+    const byState = periods.reduce((map, period) => {
+        const current = map.get(period.state) ?? {
+            durationMs: 0,
+            entryCount: 0,
+        };
+        map.set(period.state, {
+            durationMs: current.durationMs + period.durationMs,
+            entryCount: current.entryCount + 1,
+        });
+        return map;
+    }, new Map());
+    return {
+        totalDurationMs,
+        states: [...byState.entries()]
+            .map(([state, value]) => ({
+            state,
+            durationMs: value.durationMs,
+            percentageOfSession: totalDurationMs === 0 ? 0 : Math.round((value.durationMs / totalDurationMs) * 1000) / 10,
+            entryCount: value.entryCount,
+        }))
+            .sort((a, b) => b.durationMs - a.durationMs || a.state.localeCompare(b.state)),
+    };
+}
+/** @riviere-role domain-service */
+export function buildTransitionSummary(events) {
+    const transitions = events.flatMap((event) => {
+        if (event.envelope.type !== 'transitioned')
+            return [];
+        const from = event.payload['from'];
+        const to = event.payload['to'];
+        return typeof from === 'string' && typeof to === 'string'
+            ? [{
+                    from,
+                    to,
+                }]
+            : [];
+    });
+    const counts = transitions.reduce((map, transition) => {
+        const key = `${transition.from}\u0000${transition.to}`;
+        map.set(key, (map.get(key) ?? 0) + 1);
+        return map;
+    }, new Map());
+    const repeatedPathCounts = transitions.slice(0, -1).reduce((map, transition, index) => {
+        const next = transitions.at(index + 1);
+        if (next === undefined)
+            return map;
+        const key = [transition.from, transition.to, next.to].join('\u0000');
+        map.set(key, (map.get(key) ?? 0) + 1);
+        return map;
+    }, new Map());
+    return {
+        transitions: [...counts.entries()]
+            .map(([key, count]) => {
+            const parts = key.split('\u0000');
+            const from = parts[0];
+            const to = parts[1];
+            return {
+                from: typeof from === 'string' ? from : '',
+                to: typeof to === 'string' ? to : '',
+                count,
+            };
+        })
+            .sort((a, b) => b.count - a.count || a.from.localeCompare(b.from) || a.to.localeCompare(b.to)),
+        repeatedPaths: [...repeatedPathCounts.entries()]
+            .filter(([, count]) => count > 1)
+            .map(([key, count]) => ({
+            path: key.split('\u0000'),
+            count,
+        }))
+            .sort((a, b) => b.count - a.count || a.path.join('>').localeCompare(b.path.join('>'))),
+    };
+}
+/** @riviere-role domain-service */
+export function buildDenialSummary(events) {
+    const byType = {
+        write: 0,
+        bash: 0,
+        pluginRead: 0,
+        idle: 0,
+    };
+    const byState = new Map();
+    const denialTypes = new Map([
+        ['write-checked', 'write'],
+        ['bash-checked', 'bash'],
+        ['plugin-read-checked', 'pluginRead'],
+        ['idle-checked', 'idle'],
+    ]);
+    for (const event of events) {
+        const key = denialTypes.get(event.envelope.type);
+        if (key === undefined || event.payload['allowed'] !== false)
+            continue;
+        byType[key] += 1;
+        const state = event.envelope.state ?? 'unknown';
+        byState.set(state, (byState.get(state) ?? 0) + 1);
+    }
+    return {
+        total: byType.write + byType.bash + byType.pluginRead + byType.idle,
+        byType,
+        byState: [...byState.entries()]
+            .map(([state, count]) => ({
+            state,
+            count,
+        }))
+            .sort((a, b) => b.count - a.count || a.state.localeCompare(b.state)),
+    };
+}
+function buildCounts(calls, startedAtMs, endedAtMs) {
+    return calls.reduce((accumulator, call) => {
+        if (call.timestampMs < startedAtMs || call.timestampMs > endedAtMs)
+            return accumulator;
+        accumulator.toolCounts.set(call.name, (accumulator.toolCounts.get(call.name) ?? 0) + 1);
+        return {
+            totalToolCalls: accumulator.totalToolCalls + 1,
+            toolCounts: accumulator.toolCounts,
+        };
+    }, {
+        totalToolCalls: 0,
+        toolCounts: new Map(),
+    });
+}
+function bucketToolCallsByState(calls, periods) {
+    return periods.map((period) => {
+        const counts = buildCounts(calls, parseTs(period.startedAt), parseTs(period.endedAt));
+        return {
+            state: period.state,
+            totalToolCalls: counts.totalToolCalls,
+            toolCounts: [...counts.toolCounts.entries()]
+                .map(([name, count]) => ({
+                name,
+                count,
+            }))
+                .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)),
+        };
+    });
+}
+/** @riviere-role domain-service */
+export function buildToolSummary(transcriptPath, sessionId, periods) {
+    const calls = readToolCalls(transcriptPath, sessionId);
+    return {
+        usedToolNames: [...new Set(calls.map((call) => call.name))].sort((a, b) => a.localeCompare(b)),
+        byState: bucketToolCallsByState(calls, periods),
+    };
+}

package/dist/features/workflow-runner/domain/reflection-process-types.d.ts

@@ -0,0 +1,92 @@
+/** @riviere-role value-object */
+export type ReflectionProcess = {
+    readonly schemaVersion: 1;
+    readonly context: {
+        readonly sessionId: string;
+        readonly repository?: string;
+        readonly repositoryRoot?: string;
+        readonly transcriptPath?: string;
+        readonly eventStorePath?: string;
+        readonly currentState: string;
+    };
+    readonly discovery: {
+        readonly sources: ReadonlyArray<{
+            readonly kind: 'repository-root' | 'transcript' | 'event-store';
+            readonly path: string;
+            readonly sessionId?: string;
+        }>;
+    };
+    readonly workflow: {
+        readonly knownStates: ReadonlyArray<string>;
+        readonly observedEventTypes: ReadonlyArray<{
+            readonly type: string;
+            readonly count: number;
+            readonly payloadKeys: ReadonlyArray<string>;
+        }>;
+    };
+    readonly observations: {
+        readonly stateDurations: {
+            readonly totalDurationMs: number;
+            readonly states: ReadonlyArray<{
+                readonly state: string;
+                readonly durationMs: number;
+                readonly percentageOfSession: number;
+                readonly entryCount: number;
+            }>;
+        };
+        readonly transitions: {
+            readonly transitions: ReadonlyArray<{
+                readonly from: string;
+                readonly to: string;
+                readonly count: number;
+            }>;
+            readonly repeatedPaths: ReadonlyArray<{
+                readonly path: ReadonlyArray<string>;
+                readonly count: number;
+            }>;
+        };
+        readonly denials: {
+            readonly total: number;
+            readonly byType: {
+                readonly write: number;
+                readonly bash: number;
+                readonly pluginRead: number;
+                readonly idle: number;
+            };
+            readonly byState: ReadonlyArray<{
+                readonly state: string;
+                readonly count: number;
+            }>;
+        };
+        readonly tools: {
+            readonly usedToolNames: ReadonlyArray<string>;
+            readonly byState: ReadonlyArray<{
+                readonly state: string;
+                readonly totalToolCalls: number;
+                readonly toolCounts: ReadonlyArray<{
+                    readonly name: string;
+                    readonly count: number;
+                }>;
+            }>;
+        };
+    };
+    readonly instructions: {
+        readonly objective: string;
+        readonly questionsToAnswer: ReadonlyArray<string>;
+        readonly constraints: ReadonlyArray<string>;
+        readonly recommendedSteps: ReadonlyArray<string>;
+    };
+    readonly output: {
+        readonly kind: 'reflection';
+        readonly schemaVersion: 1;
+        readonly allowedCategories: ReadonlyArray<'state-efficiency' | 'review-rework' | 'quality-gates' | 'tooling' | 'workflow-design'>;
+        readonly maxFindings: 10;
+    };
+};
+/** @riviere-role value-object */
+export type StatePeriod = {
+    readonly state: string;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly durationMs: number;
+};

package/dist/features/workflow-runner/domain/reflection-process-types.js

@@ -0,0 +1 @@
+export {};

package/dist/features/workflow-runner/domain/reflection-process.d.ts

@@ -0,0 +1,14 @@
+import type { BaseWorkflowState, RehydratableWorkflow, StoredEvent, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { ReflectionProcess } from './reflection-process-types';
+/** @riviere-role domain-service */
+export declare function buildReflectionProcess<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(input: {
+    readonly sessionId: string;
+    readonly repository?: string;
+    readonly repositoryRoot?: string;
+    readonly transcriptPath?: string;
+    readonly eventStorePath?: string;
+    readonly workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>;
+    readonly events: readonly StoredEvent[];
+}): ReflectionProcess;
+/** @riviere-role domain-service */
+export declare function resolveRepository(events: readonly StoredEvent[]): string | undefined;

package/dist/features/workflow-runner/domain/reflection-process.js

@@ -0,0 +1,95 @@
+import { flattenStoredEvent } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { buildDenialSummary, buildObservedEventTypes, buildStateDurationSummary, buildToolSummary, buildTransitionSummary, computeStatePeriods, } from './reflection-process-observations.js';
+function computeCurrentState(workflowDefinition, events) {
+    return events.reduce((state, event) => workflowDefinition.fold(state, flattenStoredEvent(event)), workflowDefinition.initialState()).currentStateMachineState;
+}
+function buildDiscoverySources(input) {
+    return [
+        ...(input.repositoryRoot === undefined ? [] : [{
+                kind: 'repository-root',
+                path: input.repositoryRoot,
+            }]),
+        ...(input.transcriptPath === undefined || input.transcriptPath === '' ? [] : [{
+                kind: 'transcript',
+                path: input.transcriptPath,
+            }]),
+        ...(input.eventStorePath === undefined || input.eventStorePath === '' ? [] : [{
+                kind: 'event-store',
+                path: input.eventStorePath,
+                sessionId: input.sessionId,
+            }]),
+    ];
+}
+/** @riviere-role domain-service */
+export function buildReflectionProcess(input) {
+    const currentState = computeCurrentState(input.workflowDefinition, input.events);
+    const periods = computeStatePeriods(input.events, currentState);
+    return {
+        schemaVersion: 1,
+        context: {
+            sessionId: input.sessionId,
+            ...(input.repository === undefined ? {} : { repository: input.repository }),
+            ...(input.repositoryRoot === undefined ? {} : { repositoryRoot: input.repositoryRoot }),
+            ...(input.transcriptPath === undefined || input.transcriptPath === '' ? {} : { transcriptPath: input.transcriptPath }),
+            ...(input.eventStorePath === undefined || input.eventStorePath === '' ? {} : { eventStorePath: input.eventStorePath }),
+            currentState,
+        },
+        discovery: { sources: buildDiscoverySources(input), },
+        workflow: {
+            knownStates: Object.keys(input.workflowDefinition.getRegistry()).sort((a, b) => a.localeCompare(b)),
+            observedEventTypes: buildObservedEventTypes(input.events),
+        },
+        observations: {
+            stateDurations: buildStateDurationSummary(periods),
+            transitions: buildTransitionSummary(input.events),
+            denials: buildDenialSummary(input.events),
+            tools: buildToolSummary(input.transcriptPath, input.sessionId, periods),
+        },
+        instructions: {
+            objective: 'Produce optimisation opportunities only for this session. Do not restate information already visible in the UI.',
+            questionsToAnswer: [
+                'Where was the most time spent, and why?',
+                'Did any state loops indicate rework or late discovery?',
+                'Did a review phase or quality gate discover issues later than it should have?',
+                'Were instructions unclear, tools blocked, or better tools unused?',
+                'What concrete workflow, tooling, or process change would improve the next run?',
+            ],
+            constraints: [
+                'Do not include what went well.',
+                'Do not summarize the session without an improvement conclusion.',
+                'Do not assume the largest numbers are the most important issues.',
+                'Use raw evidence only to confirm cause and recommendation.',
+                'Every finding must be evidence-backed and actionable.',
+            ],
+            recommendedSteps: [
+                'Scan the repository to find the project workflow definition and related state files.',
+                'Review the observed event types to understand workflow-specific signals.',
+                'Inspect the event log and transcript for the observations that appear most relevant.',
+                'Record only structured optimisation findings that match the required output schema.',
+            ],
+        },
+        output: {
+            kind: 'reflection',
+            schemaVersion: 1,
+            allowedCategories: [
+                'state-efficiency',
+                'review-rework',
+                'quality-gates',
+                'tooling',
+                'workflow-design',
+            ],
+            maxFindings: 10,
+        },
+    };
+}
+/** @riviere-role domain-service */
+export function resolveRepository(events) {
+    for (const event of events) {
+        if (event.envelope.type !== 'session-started')
+            continue;
+        const repository = event.payload['repository'];
+        if (typeof repository === 'string' && repository.length > 0)
+            return repository;
+    }
+    return undefined;
+}

package/dist/features/workflow-runner/entrypoint/reflection-routes.d.ts

@@ -0,0 +1,7 @@
+import type { BaseWorkflowState, RehydratableWorkflow, WorkflowEngineDeps } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { RunnerResult, WorkflowRunnerConfig } from '../../../platform/domain/workflow-runner-types';
+/** @riviere-role cli-entrypoint */
+export declare function handleGetReflectionProcessRoute<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(engine: WorkflowEngine<TWorkflow, TState, TDeps, TStateName, TOperation>, engineDeps: WorkflowEngineDeps, config: WorkflowRunnerConfig<TWorkflow, TState, TDeps, TStateName, TOperation>, args: readonly string[], getSessionId?: () => string, getSessionTranscriptPath?: () => string, getSessionRepository?: () => string | undefined, getRepositoryRoot?: () => string, getWorkflowEventsDbPath?: () => string): RunnerResult;
+/** @riviere-role cli-entrypoint */
+export declare function handleRecordReflectionRoute<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(engine: WorkflowEngine<TWorkflow, TState, TDeps, TStateName, TOperation>, engineDeps: WorkflowEngineDeps, args: readonly string[], readStdin: (() => string) | undefined, getSessionId?: () => string): RunnerResult;

package/dist/features/workflow-runner/entrypoint/reflection-routes.js

@@ -0,0 +1,114 @@
+import { recordReflectionInputSchema, } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { EXIT_ALLOW, EXIT_ERROR, } from '../../../shell/exit-codes.js';
+import { buildReflectionProcess, resolveRepository, } from '../domain/reflection-process.js';
+function jsonResult(value) {
+    return {
+        output: JSON.stringify(value, null, 2),
+        exitCode: EXIT_ALLOW,
+    };
+}
+function errorResult(output) {
+    return {
+        output,
+        exitCode: EXIT_ERROR,
+    };
+}
+function parseFlagArgs(args) {
+    const flags = new Map();
+    for (const [index, key] of args.entries()) {
+        if (index % 2 === 1)
+            continue;
+        const value = args[index + 1];
+        if (!key.startsWith('--')) {
+            return {
+                ok: false,
+                message: `Invalid flag: ${String(key)}`,
+            };
+        }
+        if (typeof value !== 'string' || value.length === 0) {
+            return {
+                ok: false,
+                message: `Missing value for flag: ${key}`,
+            };
+        }
+        flags.set(key, value);
+    }
+    return {
+        ok: true,
+        flags,
+    };
+}
+function validateReflectionFlags(flags) {
+    for (const key of flags.keys()) {
+        if (key !== '--label' && key !== '--agent-name' && key !== '--source-state') {
+            return `Unknown flag: ${key}`;
+        }
+    }
+    return null;
+}
+/** @riviere-role cli-entrypoint */
+export function handleGetReflectionProcessRoute(engine, engineDeps, config, args, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath) {
+    if (args.length > 1) {
+        return errorResult('get-reflection-process does not accept arguments');
+    }
+    if (getSessionId === undefined) {
+        return errorResult('get-reflection-process requires an active workflow session');
+    }
+    const sessionId = getSessionId();
+    if (!engine.hasSessionStarted(sessionId)) {
+        return errorResult(`Session ${sessionId} has not been started`);
+    }
+    const events = engineDeps.store.readEvents(sessionId);
+    return jsonResult(buildReflectionProcess({
+        sessionId,
+        repository: getSessionRepository?.() ?? resolveRepository(events),
+        repositoryRoot: getRepositoryRoot?.(),
+        transcriptPath: getSessionTranscriptPath?.(),
+        eventStorePath: getWorkflowEventsDbPath?.(),
+        workflowDefinition: config.workflowDefinition,
+        events,
+    }));
+}
+/** @riviere-role cli-entrypoint */
+export function handleRecordReflectionRoute(engine, engineDeps, args, readStdin, getSessionId) {
+    if (getSessionId === undefined) {
+        return errorResult('record-reflection requires an active workflow session');
+    }
+    if (readStdin === undefined) {
+        return errorResult('record-reflection requires JSON on stdin');
+    }
+    const parsedFlags = parseFlagArgs(args.slice(1));
+    if (!parsedFlags.ok) {
+        return errorResult(parsedFlags.message);
+    }
+    const flagError = validateReflectionFlags(parsedFlags.flags);
+    if (flagError !== null) {
+        return errorResult(flagError);
+    }
+    const sessionId = getSessionId();
+    if (!engine.hasSessionStarted(sessionId)) {
+        return errorResult(`Session ${sessionId} has not been started`);
+    }
+    try {
+        const reflectionPayload = JSON.parse(readStdin());
+        const parsed = recordReflectionInputSchema.safeParse({
+            label: parsedFlags.flags.get('--label'),
+            agentName: parsedFlags.flags.get('--agent-name'),
+            sourceState: parsedFlags.flags.get('--source-state'),
+            reflection: reflectionPayload,
+        });
+        if (!parsed.success) {
+            return errorResult(`Invalid reflection payload: ${parsed.error.message}`);
+        }
+        const stored = engineDeps.store.recordReflection(sessionId, engineDeps.now(), parsed.data);
+        return jsonResult({
+            ok: true,
+            id: stored.id,
+            sessionId: stored.sessionId,
+            createdAt: stored.createdAt,
+        });
+    }
+    catch (error) {
+        return errorResult(`Invalid reflection JSON: ${String(error)}`);
+    }
+}

package/dist/features/workflow-runner/entrypoint/workflow-runner.js

@@ -1,9 +1,10 @@
-import { WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { pass, WorkflowEngine, } from '@nt-ai-lab/deterministic-agent-workflow-engine';
 import { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR } from '../../../shell/exit-codes.js';
 import { formatContextInjection, formatDenyDecision } from '../../../platform/infra/cli/presentation/hook-output.js';
 import { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema, teammateIdleInputSchema, } from '../../../platform/infra/external-clients/claude-hooks/hook-schemas.js';
 import { createPreToolUseHandler } from '../../../platform/domain/pre-tool-use-handler.js';
 import { getRepositoryName } from '../../../platform/infra/external-clients/git/repository-name.js';
+import { handleGetReflectionProcessRoute, handleRecordReflectionRoute, } from './reflection-routes.js';
 function resolvePreToolUseHandler(config) {
     const hasPolicy = config.bashForbidden !== undefined || config.isWriteAllowed !== undefined || config.customGates !== undefined;
     if (config.preToolUseHandler !== undefined) {
@@ -83,7 +84,7 @@ export function createWorkflowRunner(config) {
     return (args, engineDeps, workflowDeps, options) => {
         const engine = new WorkflowEngine(config.workflowDefinition, engineDeps, workflowDeps);
         if (args.length > 0) {
-            return handleRoute(engine, config, args, args[0], options?.getSessionId, options?.getSessionTranscriptPath, options?.getSessionRepository);
+            return handleRoute(engine, engineDeps, config, args, args[0], options?.readStdin, options?.getSessionId, options?.getSessionTranscriptPath, options?.getSessionRepository, options?.getRepositoryRoot, options?.getWorkflowEventsDbPath);
         }
         if (options?.readStdin === undefined)
             return {
@@ -93,7 +94,43 @@ export function createWorkflowRunner(config) {
         return handleHook(engine, resolvedHandler, options.readStdin);
     };
 }
-function handleRoute(engine, config, args, routeName, getSessionId, getSessionTranscriptPath, getSessionRepository) {
+function handleWriteJournalRoute(engine, engineDeps, args, getSessionId) {
+    const hasExplicitSessionId = getSessionId === undefined;
+    const sessionId = hasExplicitSessionId ? args[1] : getSessionId();
+    const agentNameIndex = hasExplicitSessionId ? 2 : 1;
+    const contentIndex = hasExplicitSessionId ? 3 : 2;
+    const agentName = args[agentNameIndex];
+    const content = args.slice(contentIndex).join(' ').trim();
+    if (typeof sessionId !== 'string' || typeof agentName !== 'string' || content.length === 0) {
+        return {
+            output: 'write-journal requires <agent-name> and <content> arguments',
+            exitCode: EXIT_ERROR,
+        };
+    }
+    return engineResultToRunnerResult(engine.transaction(sessionId, 'write-journal', (workflow) => {
+        workflow.appendEvent({
+            type: 'journal-entry',
+            at: engineDeps.now(),
+            agentName,
+            content,
+        });
+        return pass();
+    }));
+}
+function handleGetStateRoute(engine, args, getSessionId) {
+    const sessionId = getSessionId === undefined ? args[1] : getSessionId();
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        return {
+            output: 'get-state requires <session-id> argument',
+            exitCode: EXIT_ERROR,
+        };
+    }
+    return engineResultToRunnerResult(engine.getState(sessionId));
+}
+function handleRoute(engine, engineDeps, config, args, routeName, readStdin, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath) {
+    const builtin = resolveBuiltinRoute(engine, engineDeps, config, args, routeName, readStdin, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath);
+    if (builtin !== undefined)
+        return builtin;
     const routeDef = Object.hasOwn(config.routes, routeName) ? config.routes[routeName] : undefined;
     if (routeDef === undefined)
         return {
@@ -127,6 +164,20 @@ function handleRoute(engine, config, args, routeName, getSessionId, getSessionTr
             return engineResultToRunnerResult(engine.transaction(resolveSessionId(), routeName, (workflow) => routeDef.handler(workflow, ...argsAfterSessionId())));
     }
 }
+function resolveBuiltinRoute(engine, engineDeps, config, args, routeName, readStdin, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath) {
+    switch (routeName) {
+        case 'get-state':
+            return handleGetStateRoute(engine, args, getSessionId);
+        case 'get-reflection-process':
+            return handleGetReflectionProcessRoute(engine, engineDeps, config, args, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath);
+        case 'record-reflection':
+            return handleRecordReflectionRoute(engine, engineDeps, args, readStdin, getSessionId);
+        case 'write-journal':
+            return handleWriteJournalRoute(engine, engineDeps, args, getSessionId);
+        default:
+            return undefined;
+    }
+}
 function handleHook(engine, resolvedHandler, readStdin) {
     const stdin = readStdin();
     const hookInput = JSON.parse(stdin);

package/dist/platform/domain/workflow-runner-types.d.ts

@@ -13,6 +13,8 @@ export type RunnerOptions = {
     readonly getSessionId?: () => string;
     readonly getSessionTranscriptPath?: () => string;
     readonly getSessionRepository?: () => string | undefined;
+    readonly getRepositoryRoot?: () => string;
+    readonly getWorkflowEventsDbPath?: () => string;
 };
 /** @riviere-role value-object */
 export type WorkflowRunnerConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -11,10 +11,10 @@
     "dist"
   ],
   "dependencies": {
-    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.2.0",
-    "@nt-ai-lab/deterministic-agent-workflow-dsl": "0.2.0",
-    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.2.0",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.3.0",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.3.0",
+    "@nt-ai-lab/deterministic-agent-workflow-dsl": "0.3.0"
   },
   "publishConfig": {
     "access": "public"