@nt-ai-lab/deterministic-agent-workflow-engine 0.2.1 → 0.3.1

package/dist/platform/domain/reflection-types.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export const reflectionCategorySchema = z.enum([
+    'state-efficiency',
+    'review-rework',
+    'quality-gates',
+    'tooling',
+    'workflow-design',
+]);
+export const reflectionConfidenceSchema = z.enum(['low', 'medium', 'high']);
+const evidenceBaseSchema = z.object({ label: z.string().min(1).optional(), });
+export const reflectionEvidenceSchema = z.discriminatedUnion('kind', [
+    evidenceBaseSchema.extend({
+        kind: z.literal('state-period'),
+        state: z.string().min(1),
+        startedAt: z.string().min(1).optional(),
+        endedAt: z.string().min(1).optional(),
+    }),
+    evidenceBaseSchema.extend({
+        kind: z.literal('event'),
+        seq: z.number().int().positive(),
+    }),
+    evidenceBaseSchema.extend({
+        kind: z.literal('event-range'),
+        startSeq: z.number().int().positive(),
+        endSeq: z.number().int().positive(),
+    }),
+    evidenceBaseSchema.extend({
+        kind: z.literal('journal-entry'),
+        at: z.string().min(1),
+        agentName: z.string().min(1).optional(),
+    }),
+    evidenceBaseSchema.extend({
+        kind: z.literal('transcript-range'),
+        startIndex: z.number().int().nonnegative(),
+        endIndex: z.number().int().nonnegative(),
+    }),
+    evidenceBaseSchema.extend({
+        kind: z.literal('tool-activity'),
+        state: z.string().min(1).optional(),
+        toolName: z.string().min(1).optional(),
+        metric: z.string().min(1).optional(),
+    }),
+]);
+export const reflectionFindingSchema = z.object({
+    title: z.string().min(1),
+    category: reflectionCategorySchema,
+    opportunity: z.string().min(1),
+    likelyCause: z.string().min(1),
+    suggestedChange: z.string().min(1),
+    expectedImpact: z.string().min(1),
+    confidence: reflectionConfidenceSchema.optional(),
+    evidence: z.array(reflectionEvidenceSchema).min(1),
+});
+export const reflectionPayloadSchema = z.object({
+    summary: z.string().min(1).optional(),
+    findings: z.array(reflectionFindingSchema).max(10),
+}).strict();
+export const recordReflectionInputSchema = z.object({
+    label: z.string().min(1).optional(),
+    agentName: z.string().min(1).optional(),
+    sourceState: z.string().min(1).optional(),
+    reflection: reflectionPayloadSchema,
+}).strict();
+export const storedReflectionSchema = z.object({
+    id: z.number().int().positive(),
+    sessionId: z.string().min(1),
+    createdAt: z.string().min(1),
+    label: z.string().min(1).optional(),
+    agentName: z.string().min(1).optional(),
+    sourceState: z.string().min(1).optional(),
+    reflection: reflectionPayloadSchema,
+}).strict();

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

@@ -1,5 +1,6 @@
 import type { ZodType } from 'zod';
 import type { BaseEvent } from './base-event';
+import type { RecordReflectionInput, StoredReflection } from './reflection-types';
 import type { StoredEvent } from './stored-event';
 import type { PreconditionResult } from './precondition-result';
 import type { TranscriptReader } from '../infra/external-clients/transcript/transcript-reader';
@@ -44,6 +45,8 @@ export interface WorkflowEventStore {
     appendEvents(sessionId: string, events: readonly StoredEvent[]): void;
     sessionExists(sessionId: string): boolean;
     hasSessionStarted(sessionId: string): boolean;
+    recordReflection(sessionId: string, createdAt: string, input: RecordReflectionInput): StoredReflection;
+    listReflections(sessionId: string): readonly StoredReflection[];
 }
 /** @riviere-role value-object */
 export type WorkflowEngineDeps = {

package/dist/platform/domain/workflow-engine.d.ts

@@ -1,7 +1,7 @@
 import type { PreconditionResult } from './precondition-result';
 import type { BashForbiddenConfig } from './workflow-registry';
 import type { EngineResult, RehydratableWorkflow, WorkflowDefinition, WorkflowEngineDeps } from './workflow-engine-types';
-import type { BaseWorkflowState } from './workflow-state';
+import { type BaseWorkflowState } from './workflow-state';
 /** @riviere-role domain-service */
 export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> {
     private readonly factory;
@@ -13,6 +13,7 @@ export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TStat
     transition(sessionId: string, target: TStateName): EngineResult;
     checkBash(sessionId: string, toolName: string, command: string, bashForbidden: BashForbiddenConfig): EngineResult;
     checkWrite(sessionId: string, toolName: string, filePath: string, isWriteAllowed: (filePath: string, state: TState) => boolean): EngineResult;
+    getState(sessionId: string): EngineResult;
     persistSessionId(sessionId: string): void;
     hasSession(sessionId: string): boolean;
     hasSessionStarted(sessionId: string): boolean;
@@ -20,5 +21,6 @@ export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TStat
     private rehydrateFromEvents;
     private persistEvents;
     private wrapEvents;
+    private applyIdentityGate;
     private verifyIdentity;
 }

package/dist/platform/domain/workflow-engine.js

@@ -2,8 +2,9 @@ import { checkBashCommand } from './bash-enforcement.js';
 import { checkIdentity } from './identity-verification.js';
 import { buildPrefixPattern, buildProcedurePath, enrichSessionStartedEvents, getExpectedPrefix, readProcedure, } from './workflow-engine-support.js';
 import { formatIllegalTransitionError, formatInitSuccess, formatOperationGateError, formatOperationSuccess, formatTransitionError, formatTransitionSuccess, } from '../infra/cli/presentation/output-guidance.js';
-import { flattenStoredEvent, toPayload } from './stored-event.js';
-import { WorkflowStateError } from './workflow-state.js';
+import { flattenStoredEvent, toPayload, } from './stored-event.js';
+import { WorkflowStateError, } from './workflow-state.js';
+import { serializeWorkflowState } from './workflow-state-serialization.js';
 /** @riviere-role domain-service */
 export class WorkflowEngine {
     factory;
@@ -40,15 +41,9 @@ export class WorkflowEngine {
         this.requireSession(sessionId);
         const workflow = this.rehydrateFromEvents(sessionId);
         const registry = this.factory.getRegistry();
-        const identityResult = this.verifyIdentity(sessionId, workflow);
-        if (identityResult !== undefined) {
-            this.persistEvents(sessionId, workflow);
-            const currentPrefix = getExpectedPrefix(workflow.getState().currentStateMachineState, registry);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError(op, identityResult, currentPrefix)
-            };
-        }
+        const gate = this.applyIdentityGate(sessionId, workflow, op);
+        if (gate !== undefined)
+            return gate;
         const result = fn(workflow);
         this.persistEvents(sessionId, workflow);
         const currentPrefix = getExpectedPrefix(workflow.getState().currentStateMachineState, registry);
@@ -70,15 +65,9 @@ export class WorkflowEngine {
         const state = workflow.getState();
         const currentStateName = state.currentStateMachineState;
         const registry = this.factory.getRegistry();
-        const identityResult = this.verifyIdentity(sessionId, workflow);
-        if (identityResult !== undefined) {
-            this.persistEvents(sessionId, workflow);
-            const currentPrefix = getExpectedPrefix(currentStateName, registry);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError('transition', identityResult, currentPrefix)
-            };
-        }
+        const gate = this.applyIdentityGate(sessionId, workflow, 'transition');
+        if (gate !== undefined)
+            return gate;
         const currentDef = registry[currentStateName];
         if (!currentDef.canTransitionTo.includes(target)) {
             const legalTargets = currentDef.canTransitionTo;
@@ -133,14 +122,9 @@ export class WorkflowEngine {
         const registry = this.factory.getRegistry();
         const currentStateName = workflow.getState().currentStateMachineState;
         const currentPrefix = getExpectedPrefix(currentStateName, registry);
-        const identityResult = this.verifyIdentity(sessionId, workflow);
-        if (identityResult !== undefined) {
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError('bash-check', identityResult, currentPrefix)
-            };
-        }
+        const gate = this.applyIdentityGate(sessionId, workflow, 'bash-check');
+        if (gate !== undefined)
+            return gate;
         if (toolName !== 'Bash') {
             workflow.appendEvent({
                 type: 'bash-checked',
@@ -192,14 +176,9 @@ export class WorkflowEngine {
         const registry = this.factory.getRegistry();
         const currentStateName = workflow.getState().currentStateMachineState;
         const currentPrefix = getExpectedPrefix(currentStateName, registry);
-        const identityResult = this.verifyIdentity(sessionId, workflow);
-        if (identityResult !== undefined) {
-            this.persistEvents(sessionId, workflow);
-            return {
-                type: 'blocked',
-                output: formatOperationGateError('write-check', identityResult, currentPrefix)
-            };
-        }
+        const gate = this.applyIdentityGate(sessionId, workflow, 'write-check');
+        if (gate !== undefined)
+            return gate;
         const writeTools = new Set(['Write', 'Edit', 'NotebookEdit']);
         if (!writeTools.has(toolName)) {
             workflow.appendEvent({
@@ -273,6 +252,10 @@ export class WorkflowEngine {
             output: ''
         };
     }
+    getState(sessionId) {
+        this.requireSession(sessionId);
+        return serializeWorkflowState(this.rehydrateFromEvents(sessionId).getState());
+    }
     persistSessionId(sessionId) {
         this.engineDeps.appendToFile(this.engineDeps.getEnvFilePath(), `export CLAUDE_SESSION_ID='${sessionId}'\n`);
     }
@@ -317,11 +300,21 @@ export class WorkflowEngine {
         });
         return stored;
     }
+    applyIdentityGate(sessionId, workflow, op) {
+        const identityResult = this.verifyIdentity(sessionId, workflow);
+        if (identityResult === undefined)
+            return undefined;
+        this.persistEvents(sessionId, workflow);
+        const currentPrefix = getExpectedPrefix(workflow.getState().currentStateMachineState, this.factory.getRegistry());
+        return {
+            type: 'blocked',
+            output: formatOperationGateError(op, identityResult, currentPrefix),
+        };
+    }
     verifyIdentity(sessionId, workflow) {
         const transcriptPath = workflow.getTranscriptPath();
         const state = workflow.getState().currentStateMachineState;
         const registry = this.factory.getRegistry();
-        const expectedPrefix = getExpectedPrefix(state, registry);
         const pattern = buildPrefixPattern(registry);
         const messages = this.engineDeps.transcriptReader.readMessages(transcriptPath);
         const identityCheckResult = checkIdentity(messages, pattern);
@@ -332,7 +325,17 @@ export class WorkflowEngine {
                 transcriptPath,
             }], workflow.getState()));
         if (identityCheckResult.status === 'lost') {
-            return `You forgot. Next message MUST begin with: ${expectedPrefix}`;
+            const currentProcedure = readProcedure(this.engineDeps, state);
+            return [
+                'Your last message is missing the required state prefix.',
+                '',
+                `- send a new message starting with: ${getExpectedPrefix(state, registry)}`,
+                '- then continue with the current procedure',
+                '',
+                'Current procedure:',
+                '',
+                currentProcedure,
+            ].join('\n');
         }
         return undefined;
     }

package/dist/platform/domain/workflow-state-serialization.d.ts

@@ -0,0 +1,3 @@
+import type { EngineResult } from './workflow-engine-types';
+/** @riviere-role domain-service */
+export declare function serializeWorkflowState(state: unknown): EngineResult;

package/dist/platform/domain/workflow-state-serialization.js

@@ -0,0 +1,16 @@
+/** @riviere-role domain-service */
+export function serializeWorkflowState(state) {
+    try {
+        return {
+            type: 'success',
+            output: JSON.stringify(state, null, 2),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            type: 'error',
+            output: `Failed to serialize workflow state: ${message}`,
+        };
+    }
+}

package/dist/platform/infra/cli/presentation/output-guidance.spec.d.ts

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

package/dist/platform/infra/cli/presentation/output-guidance.spec.js

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { WorkflowEngine, pass, } from '../../../../index.js';
+import { SEPARATOR } from './output-guidance.js';
+function isSessionStartedEvent(event) {
+    return event.type === 'session-started';
+}
+class PlanningWorkflow {
+    state;
+    pendingEvents;
+    constructor(state, pendingEvents = []) {
+        this.state = state;
+        this.pendingEvents = pendingEvents;
+    }
+    getState() {
+        return this.state;
+    }
+    appendEvent(event) {
+        this.pendingEvents = [...this.pendingEvents, event];
+        if (isSessionStartedEvent(event)) {
+            this.state = {
+                ...this.state,
+                transcriptPath: event.transcriptPath,
+            };
+        }
+    }
+    getPendingEvents() {
+        return this.pendingEvents;
+    }
+    startSession(transcriptPath, _repository) {
+        void _repository;
+        this.state = {
+            ...this.state,
+            transcriptPath,
+        };
+        this.pendingEvents = [...this.pendingEvents, {
+                type: 'session-started',
+                at: '2026-01-01T00:00:00Z',
+                transcriptPath,
+                currentState: this.state.currentStateMachineState,
+                states: ['PLANNING'],
+            }];
+    }
+    getTranscriptPath() {
+        return this.state.transcriptPath;
+    }
+    registerAgent(_agentType, _agentId) {
+        void _agentType;
+        void _agentId;
+        return pass();
+    }
+    handleTeammateIdle(_agentName) {
+        void _agentName;
+        return pass();
+    }
+}
+class ReflectionStoreNotConfiguredError extends Error {
+    constructor() {
+        super('Reflection storage is not configured for this test');
+        this.name = 'ReflectionStoreNotConfiguredError';
+    }
+}
+class MemoryStore {
+    eventsBySessionId = new Map();
+    readEvents(sessionId) {
+        return this.eventsBySessionId.get(sessionId) ?? [];
+    }
+    appendEvents(sessionId, events) {
+        const existingEvents = this.eventsBySessionId.get(sessionId) ?? [];
+        this.eventsBySessionId.set(sessionId, [...existingEvents, ...events]);
+    }
+    sessionExists(sessionId) {
+        return this.eventsBySessionId.has(sessionId);
+    }
+    hasSessionStarted(sessionId) {
+        return this.eventsBySessionId.get(sessionId)?.some((event) => {
+            return event.envelope.type === 'session-started';
+        }) ?? false;
+    }
+    recordReflection(_sessionId, _createdAt, _input) {
+        void _sessionId;
+        void _createdAt;
+        void _input;
+        throw new ReflectionStoreNotConfiguredError();
+    }
+    listReflections() {
+        return [];
+    }
+}
+const procedureContent = 'PLANNING instructions';
+const workflowDefinition = {
+    fold(state, event) {
+        if (!isSessionStartedEvent(event)) {
+            return state;
+        }
+        return {
+            ...state,
+            transcriptPath: event.transcriptPath,
+        };
+    },
+    buildWorkflow(state, _deps) {
+        void _deps;
+        return new PlanningWorkflow(state);
+    },
+    stateSchema: z.literal('PLANNING'),
+    initialState() {
+        return {
+            currentStateMachineState: 'PLANNING',
+            transcriptPath: '',
+        };
+    },
+    getRegistry() {
+        return {
+            PLANNING: {
+                emoji: '🧭',
+                agentInstructions: procedureContent,
+                canTransitionTo: [],
+                allowedWorkflowOperations: ['write'],
+                forbidden: { write: true },
+            },
+        };
+    },
+    buildTransitionContext(state, from, to) {
+        return {
+            state,
+            from,
+            to,
+            gitInfo: {
+                currentBranch: 'main',
+                workingTreeClean: true,
+                headCommit: 'abc123',
+                changedFilesVsDefault: [],
+                hasCommitsVsDefault: false,
+            },
+        };
+    },
+};
+const transcriptReader = {
+    readMessages: () => [{
+            id: 'message-1',
+            textContent: 'plain text without the expected prefix',
+        }],
+};
+const engineDeps = {
+    store: new MemoryStore(),
+    getPluginRoot: () => '/plugin-root',
+    getEnvFilePath: () => '/plugin-root/.env',
+    readFile: (path) => {
+        if (path === '/plugin-root/states/planning.md') {
+            return procedureContent;
+        }
+        return '';
+    },
+    appendToFile: (filePath, content) => {
+        void filePath;
+        void content;
+    },
+    now: () => '2026-01-01T00:00:00Z',
+    transcriptReader,
+};
+it('reinserts the current procedure when identity verification fails', () => {
+    const emptyWorkflowDeps = {};
+    const engine = new WorkflowEngine(workflowDefinition, engineDeps, emptyWorkflowDeps);
+    engine.startSession('session-1', '/transcripts/session-1.jsonl');
+    const result = engine.checkWrite('session-1', 'Write', '/workspace/note.md', () => true);
+    const expectedOutput = [
+        'Cannot write-check',
+        SEPARATOR,
+        'Your last message is missing the required state prefix.',
+        '',
+        '- send a new message starting with: 🧭 PLANNING',
+        '- then continue with the current procedure',
+        '',
+        'Current procedure:',
+        '',
+        procedureContent,
+        '',
+        'Next message MUST begin with: 🧭 PLANNING',
+    ].join('\n');
+    const expectedResult = {
+        type: 'blocked',
+        output: expectedOutput,
+    };
+    expect(result).toEqual(expectedResult);
+});

package/package.json

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