@nt-ai-lab/deterministic-agent-workflow-engine 0.3.0 → 0.3.2

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

@@ -315,7 +315,6 @@ export class WorkflowEngine {
         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);
@@ -326,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/infra/cli/presentation/output-guidance.js

@@ -5,7 +5,9 @@ export const JOURNAL_GUIDANCE = [
     'PLATFORM NOTIFICATION',
     '',
     'Record your progress and reasoning as you work by calling:',
-    '  write-journal <agent-name> "<1\u20133 sentence note>"',
+    '  <workflow-command> write-journal <agent-name> "<detailed journal entry>"',
+    '',
+    'Use the same workflow command prefix used for other workflow commands such as transition.',
     '',
     'Use it for key decisions, progress milestones, and blockers.',
     'Every session should have a journal trail of the work performed.',

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.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -13,6 +13,9 @@
   "dependencies": {
     "zod": "^3.25.76"
   },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  },
   "publishConfig": {
     "access": "public"
   }