@nt-ai-lab/deterministic-agent-workflow-cli 0.3.1 → 0.3.3

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

@@ -0,0 +1,6 @@
+import type { BaseWorkflowState, RehydratableWorkflow, WorkflowDefinition, WorkflowEngineDeps } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { RunnerResult } from '../../../platform/domain/workflow-runner-types';
+/** @riviere-role cli-entrypoint */
+export declare function handleRecordReviewRoute<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string, TOperation extends string>(engine: {
+    readonly hasSessionStarted: (sessionId: string) => boolean;
+}, engineDeps: WorkflowEngineDeps, workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>, args: readonly string[], readStdin: (() => string) | undefined, getSessionId: (() => string) | undefined): RunnerResult;

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

@@ -0,0 +1,134 @@
+import { flattenStoredEvent, reviewPayloadSchema, } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR, } from '../../../shell/exit-codes.js';
+function jsonResult(value) {
+    return {
+        output: JSON.stringify(value, null, 2),
+        exitCode: EXIT_ALLOW,
+    };
+}
+function errorResult(output) {
+    return {
+        output,
+        exitCode: EXIT_ERROR,
+    };
+}
+function blockedResult(output) {
+    return {
+        output,
+        exitCode: EXIT_BLOCK,
+    };
+}
+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 validateReviewFlags(flags) {
+    for (const key of flags.keys()) {
+        if (key !== '--type') {
+            return `Unknown flag: ${key}`;
+        }
+    }
+    if (!flags.has('--type')) {
+        return 'record-review requires --type';
+    }
+    return null;
+}
+function isReviewAllowed(allowedWorkflowOperations) {
+    return allowedWorkflowOperations.some((allowedWorkflowOperation) => allowedWorkflowOperation === 'record-review');
+}
+/** @riviere-role cli-entrypoint */
+export function handleRecordReviewRoute(engine, engineDeps, workflowDefinition, args, readStdin, getSessionId) {
+    if (getSessionId === undefined) {
+        return errorResult('record-review requires an active workflow session');
+    }
+    if (readStdin === undefined) {
+        return errorResult('record-review requires JSON on stdin');
+    }
+    const parsedFlags = parseFlagArgs(args.slice(1));
+    if (!parsedFlags.ok) {
+        return errorResult(parsedFlags.message);
+    }
+    const flagError = validateReviewFlags(parsedFlags.flags);
+    if (flagError !== null) {
+        return errorResult(flagError);
+    }
+    const reviewType = parsedFlags.flags.get('--type');
+    if (reviewType === undefined) {
+        return errorResult('record-review requires a non-empty --type value');
+    }
+    const sessionId = getSessionId();
+    if (!engine.hasSessionStarted(sessionId)) {
+        return errorResult(`Session ${sessionId} has not been started`);
+    }
+    const reviewPayloadResult = parseReviewPayload(readStdin);
+    if (!reviewPayloadResult.ok) {
+        return errorResult(reviewPayloadResult.message);
+    }
+    const parsedReview = reviewPayloadSchema.safeParse(reviewPayloadResult.payload);
+    if (!parsedReview.success) {
+        return errorResult(`Invalid review payload: ${parsedReview.error.message}`);
+    }
+    const currentStateName = computeCurrentState(workflowDefinition, engineDeps.store.readEvents(sessionId));
+    const allowedWorkflowOperations = workflowDefinition
+        .getRegistry()[currentStateName]
+        .allowedWorkflowOperations
+        .map((allowedWorkflowOperation) => String(allowedWorkflowOperation));
+    if (!isReviewAllowed(allowedWorkflowOperations)) {
+        return blockedResult(`record-review is not allowed in state ${currentStateName}.`);
+    }
+    const createdAt = engineDeps.now();
+    const stored = engineDeps.store.recordReviewWithEvent(sessionId, createdAt, {
+        reviewType,
+        sourceState: currentStateName,
+        ...parsedReview.data,
+    }, currentStateName);
+    return jsonResult({
+        ok: true,
+        id: stored.id,
+        sessionId,
+        createdAt: stored.createdAt,
+        reviewType,
+        verdict: parsedReview.data.verdict,
+    });
+}
+function computeCurrentState(workflowDefinition, storedEvents) {
+    const state = storedEvents
+        .map(flattenStoredEvent)
+        .reduce((currentState, event) => workflowDefinition.fold(currentState, event), workflowDefinition.initialState());
+    return state.currentStateMachineState;
+}
+function parseReviewPayload(readStdin) {
+    try {
+        return {
+            ok: true,
+            payload: JSON.parse(readStdin()),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `Invalid review JSON: ${String(error)}`,
+        };
+    }
+}

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

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

package/dist/features/workflow-runner/entrypoint/review-routes.spec.js

@@ -0,0 +1,272 @@
+import { describe, expect, it, } from 'vitest';
+import { pass, toPayload, WorkflowStateError, } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { z } from 'zod';
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_ERROR } from '../../../shell/exit-codes.js';
+import { handleRecordReviewRoute } from './review-routes.js';
+class ReviewRouteWorkflow {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    getState() {
+        return this.state;
+    }
+    appendEvent(_event) {
+        void _event;
+    }
+    getPendingEvents() {
+        return [];
+    }
+    startSession(_transcriptPath, _repository) {
+        void _transcriptPath;
+        void _repository;
+    }
+    getTranscriptPath() {
+        return '';
+    }
+    registerAgent(_agentType, _agentId) {
+        void _agentType;
+        void _agentId;
+        return pass();
+    }
+    handleTeammateIdle(_agentName) {
+        void _agentName;
+        return pass();
+    }
+}
+class ReviewRouteStore {
+    storedReviews = [];
+    storedEvents;
+    constructor(initialState = 'REVIEWING') {
+        this.storedEvents = [buildStoredEvent('test-session', 'session-started', '2026-01-01T00:00:00.000Z', initialState, { currentState: initialState })];
+    }
+    readEvents(sessionId) {
+        return sessionId === 'test-session' ? this.storedEvents : [];
+    }
+    appendEvents(sessionId, events) {
+        void sessionId;
+        this.storedEvents.push(...events);
+    }
+    sessionExists(sessionId) {
+        return sessionId === 'test-session';
+    }
+    hasSessionStarted(sessionId) {
+        return sessionId === 'test-session';
+    }
+    recordReflection(_sessionId, _createdAt, _input) {
+        void _sessionId;
+        void _createdAt;
+        void _input;
+        throw new WorkflowStateError('Reflection storage is not configured');
+    }
+    listReflections(_sessionId) {
+        void _sessionId;
+        return [];
+    }
+    recordReview(_sessionId, _createdAt, _input) {
+        void _sessionId;
+        void _createdAt;
+        void _input;
+        throw new WorkflowStateError('Use recordReviewWithEvent for review recording');
+    }
+    recordReviewWithEvent(sessionId, createdAt, input, eventState) {
+        const storedReview = {
+            id: this.storedReviews.length + 1,
+            sessionId,
+            createdAt,
+            ...input,
+        };
+        this.storedReviews.push(storedReview);
+        this.storedEvents.push(buildStoredEvent(sessionId, 'review-recorded', createdAt, eventState, {
+            reviewId: storedReview.id,
+            reviewType: input.reviewType,
+            verdict: input.verdict,
+        }));
+        return storedReview;
+    }
+    listSessionReviews(sessionId) {
+        return this.storedReviews.filter((review) => review.sessionId === sessionId);
+    }
+    listReviews(_filters) {
+        void _filters;
+        return this.storedReviews;
+    }
+}
+function buildStoredEvent(sessionId, type, at, state, payload) {
+    void sessionId;
+    const event = {
+        type,
+        at,
+        ...payload,
+    };
+    return {
+        envelope: {
+            type,
+            at,
+            state,
+        },
+        payload: toPayload(event),
+    };
+}
+const workflowDefinition = {
+    fold(state, event) {
+        if (event.type === 'session-started') {
+            if (event.currentState !== 'PLANNING' && event.currentState !== 'REVIEWING')
+                return state;
+            return { currentStateMachineState: event.currentState };
+        }
+        if (event.type !== 'transitioned')
+            return state;
+        if (event.to !== 'PLANNING' && event.to !== 'REVIEWING')
+            return state;
+        return { currentStateMachineState: event.to };
+    },
+    buildWorkflow(state) {
+        return new ReviewRouteWorkflow(state);
+    },
+    stateSchema: z.enum(['PLANNING', 'REVIEWING']),
+    initialState() {
+        return { currentStateMachineState: 'REVIEWING' };
+    },
+    getRegistry() {
+        return {
+            PLANNING: {
+                emoji: '🧠',
+                agentInstructions: 'planning.md',
+                canTransitionTo: ['REVIEWING'],
+                allowedWorkflowOperations: [],
+            },
+            REVIEWING: {
+                emoji: '🔍',
+                agentInstructions: 'reviewing.md',
+                canTransitionTo: ['PLANNING'],
+                allowedWorkflowOperations: ['record-review'],
+            },
+        };
+    },
+    buildTransitionContext(state, from, to) {
+        return {
+            state,
+            from,
+            to,
+            gitInfo: {
+                currentBranch: 'main',
+                workingTreeClean: true,
+                headCommit: 'abc123',
+                changedFilesVsDefault: [],
+                hasCommitsVsDefault: false,
+            },
+        };
+    },
+};
+function createEngineDeps(store) {
+    return {
+        store,
+        getPluginRoot: () => '',
+        getEnvFilePath: () => '',
+        readFile: () => '',
+        appendToFile: () => undefined,
+        now: () => '2026-01-01T00:01:00.000Z',
+        transcriptReader: { readMessages: () => [] },
+    };
+}
+function recordReview(store, readStdin, sessionId = 'test-session') {
+    return handleRecordReviewRoute({ hasSessionStarted: (candidateSessionId) => store.hasSessionStarted(candidateSessionId) }, createEngineDeps(store), workflowDefinition, ['record-review', '--type', 'custom-review'], readStdin, () => sessionId);
+}
+describe('handleRecordReviewRoute', () => {
+    it('returns error when stdin is invalid JSON', () => {
+        const store = new ReviewRouteStore();
+        const result = recordReview(store, () => '{');
+        expect(result.exitCode).toBe(EXIT_ERROR);
+        expect(result.output).toContain('Invalid review JSON');
+        expect(store.storedReviews).toStrictEqual([]);
+    });
+    it('returns error when verdict is unknown', () => {
+        const store = new ReviewRouteStore();
+        const result = recordReview(store, () => JSON.stringify({
+            verdict: 'MAYBE',
+            findings: []
+        }));
+        expect(result.exitCode).toBe(EXIT_ERROR);
+        expect(result.output).toContain('Invalid review payload');
+        expect(store.storedReviews).toStrictEqual([]);
+    });
+    it('returns error when session has not started', () => {
+        const store = new ReviewRouteStore();
+        const result = recordReview(store, () => JSON.stringify({
+            verdict: 'PASS',
+            findings: []
+        }), 'missing-session');
+        expect(result).toStrictEqual({
+            exitCode: EXIT_ERROR,
+            output: 'Session missing-session has not been started',
+        });
+    });
+    it('records review row and review event when payload is valid', () => {
+        const store = new ReviewRouteStore();
+        const result = recordReview(store, () => JSON.stringify({
+            verdict: 'FAIL',
+            findings: [{ title: 'Missing command tests' }],
+        }));
+        expect(result.exitCode).toBe(EXIT_ALLOW);
+        expect(JSON.parse(result.output)).toStrictEqual({
+            ok: true,
+            id: 1,
+            sessionId: 'test-session',
+            createdAt: '2026-01-01T00:01:00.000Z',
+            reviewType: 'custom-review',
+            verdict: 'FAIL',
+        });
+        expect(store.storedReviews).toStrictEqual([{
+                id: 1,
+                sessionId: 'test-session',
+                createdAt: '2026-01-01T00:01:00.000Z',
+                reviewType: 'custom-review',
+                sourceState: 'REVIEWING',
+                verdict: 'FAIL',
+                findings: [{ title: 'Missing command tests' }],
+            }]);
+        expect(store.storedEvents.at(-1)).toStrictEqual(buildStoredEvent('test-session', 'review-recorded', '2026-01-01T00:01:00.000Z', 'REVIEWING', {
+            reviewId: 1,
+            reviewType: 'custom-review',
+            verdict: 'FAIL',
+        }));
+    });
+    it('preserves repeated review attempts', () => {
+        const store = new ReviewRouteStore();
+        recordReview(store, () => JSON.stringify({
+            verdict: 'FAIL',
+            findings: [{ title: 'First failure' }]
+        }));
+        recordReview(store, () => JSON.stringify({
+            verdict: 'PASS',
+            findings: []
+        }));
+        expect(store.storedReviews.map((review) => ({
+            id: review.id,
+            verdict: review.verdict
+        }))).toStrictEqual([
+            {
+                id: 1,
+                verdict: 'FAIL'
+            },
+            {
+                id: 2,
+                verdict: 'PASS'
+            },
+        ]);
+        expect(store.storedEvents.filter((event) => event.envelope.type === 'review-recorded')).toHaveLength(2);
+    });
+    it('returns blocked when current state disallows record-review', () => {
+        const store = new ReviewRouteStore('PLANNING');
+        const result = recordReview(store, () => JSON.stringify({
+            verdict: 'PASS',
+            findings: []
+        }));
+        expect(result).toStrictEqual({
+            exitCode: EXIT_BLOCK,
+            output: 'record-review is not allowed in state PLANNING.',
+        });
+        expect(store.storedReviews).toStrictEqual([]);
+    });
+});

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

@@ -5,6 +5,7 @@ import { hookCommonInputSchema, preToolUseInputSchema, subagentStartInputSchema,
 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';
+import { handleRecordReviewRoute } from './review-routes.js';
 function resolvePreToolUseHandler(config) {
     const hasPolicy = config.bashForbidden !== undefined || config.isWriteAllowed !== undefined || config.customGates !== undefined;
     if (config.preToolUseHandler !== undefined) {
@@ -172,6 +173,8 @@ function resolveBuiltinRoute(engine, engineDeps, config, args, routeName, readSt
             return handleGetReflectionProcessRoute(engine, engineDeps, config, args, getSessionId, getSessionTranscriptPath, getSessionRepository, getRepositoryRoot, getWorkflowEventsDbPath);
         case 'record-reflection':
             return handleRecordReflectionRoute(engine, engineDeps, args, readStdin, getSessionId);
+        case 'record-review':
+            return handleRecordReviewRoute(engine, engineDeps, config.workflowDefinition, args, readStdin, getSessionId);
         case 'write-journal':
             return handleWriteJournalRoute(engine, engineDeps, args, getSessionId);
         default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-cli",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,9 +12,12 @@
   ],
   "dependencies": {
     "zod": "^3.25.76",
-    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.3.1",
-    "@nt-ai-lab/deterministic-agent-workflow-dsl": "0.3.1",
-    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.3.1"
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.3.3",
+    "@nt-ai-lab/deterministic-agent-workflow-dsl": "0.3.3",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.3.3"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
   },
   "publishConfig": {
     "access": "public"