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

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/stored-event.d.ts

@@ -0,0 +1,28 @@
+import type { BaseEvent } from './base-event';
+/** @riviere-role value-object */
+export interface EventEnvelope {
+    readonly type: string;
+    readonly at: string;
+    readonly state: string | undefined;
+}
+/**
+ * Platform wire / storage shape for events.
+ *
+ * Envelope fields are stamped by the platform at persist time (see
+ * `WorkflowEngine.persistEvents`). Workflow authors never construct
+ * `StoredEvent` directly — they call `appendEvent(BaseEvent)` with flat
+ * domain events. Only the engine and direct event-store readers (e.g. the
+ * control-center UI) observe this shape.
+ *
+ * @riviere-role value-object
+ */
+export interface StoredEvent {
+    readonly envelope: EventEnvelope;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+/** @riviere-role domain-service */
+export declare function flattenStoredEvent(stored: StoredEvent): BaseEvent;
+/** @riviere-role domain-service */
+export declare function toPayload(event: BaseEvent): Record<string, unknown>;
+/** @riviere-role domain-service */
+export declare function stripEnvelopeKeys(record: Record<string, unknown>): Record<string, unknown>;

package/dist/platform/domain/stored-event.js

@@ -0,0 +1,22 @@
+/** @riviere-role domain-service */
+export function flattenStoredEvent(stored) {
+    return {
+        ...stripEnvelopeKeys(stored.payload),
+        type: stored.envelope.type,
+        at: stored.envelope.at,
+    };
+}
+/** @riviere-role domain-service */
+export function toPayload(event) {
+    return stripEnvelopeKeys(event);
+}
+/** @riviere-role domain-service */
+export function stripEnvelopeKeys(record) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'type' || key === 'at')
+            continue;
+        result[key] = value;
+    }
+    return result;
+}

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

@@ -1,5 +1,7 @@
 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';
 import type { BaseWorkflowState } from './workflow-state';
@@ -39,10 +41,12 @@ export interface WorkflowDefinition<TWorkflow extends RehydratableWorkflow<TStat
 }
 /** @riviere-role value-object */
 export interface WorkflowEventStore {
-    readEvents(sessionId: string): readonly BaseEvent[];
-    appendEvents(sessionId: string, events: readonly BaseEvent[]): void;
+    readEvents(sessionId: string): readonly StoredEvent[];
+    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,11 +13,14 @@ 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;
     private requireSession;
     private rehydrateFromEvents;
     private persistEvents;
+    private wrapEvents;
+    private applyIdentityGate;
     private verifyIdentity;
 }

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

@@ -2,7 +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 { 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;
@@ -27,7 +29,7 @@ export class WorkflowEngine {
         const registry = this.factory.getRegistry();
         const stateNames = Object.keys(registry);
         const pendingEvents = enrichSessionStartedEvents(this.engineDeps, workflow.getPendingEvents(), transcriptPath, resolvedRepository, initialState.currentStateMachineState, stateNames);
-        this.engineDeps.store.appendEvents(sessionId, pendingEvents);
+        this.engineDeps.store.appendEvents(sessionId, this.wrapEvents(pendingEvents, initialState));
         const procedureContent = this.engineDeps.readFile(buildProcedurePath(this.engineDeps, initialState.currentStateMachineState));
         const expectedPrefix = getExpectedPrefix(initialState.currentStateMachineState, registry);
         return {
@@ -39,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);
@@ -69,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;
@@ -132,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',
@@ -155,9 +140,9 @@ export class WorkflowEngine {
             };
         }
         const exemptions = registry[currentStateName].allowForbidden?.bash ?? [];
-        const result = checkBashCommand(command, bashForbidden, exemptions);
-        if (!result.pass) {
-            const reason = `Bash command blocked in ${currentStateName}. ${result.reason}`;
+        const bashCheckResult = checkBashCommand(command, bashForbidden, exemptions);
+        if (!bashCheckResult.pass) {
+            const reason = `Bash command blocked in ${currentStateName}. ${bashCheckResult.reason}`;
             workflow.appendEvent({
                 type: 'bash-checked',
                 at: this.engineDeps.now(),
@@ -191,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({
@@ -272,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`);
     }
@@ -287,15 +271,45 @@ export class WorkflowEngine {
         }
     }
     rehydrateFromEvents(sessionId) {
-        const events = this.engineDeps.store.readEvents(sessionId);
+        const stored = this.engineDeps.store.readEvents(sessionId);
+        const events = stored.map(flattenStoredEvent);
         const state = events.reduce((accumulator, event) => this.factory.fold(accumulator, event), this.factory.initialState());
         return this.factory.buildWorkflow(state, this.workflowDeps);
     }
     persistEvents(sessionId, workflow) {
         const pending = workflow.getPendingEvents();
-        if (pending.length > 0) {
-            this.engineDeps.store.appendEvents(sessionId, pending);
-        }
+        if (pending.length === 0)
+            return;
+        const preAppendState = this.rehydrateFromEvents(sessionId).getState();
+        this.engineDeps.store.appendEvents(sessionId, this.wrapEvents(pending, preAppendState));
+    }
+    wrapEvents(events, startState) {
+        const { stored } = events.reduce((accumulator, event) => ({
+            state: this.factory.fold(accumulator.state, event),
+            stored: [...accumulator.stored, {
+                    envelope: {
+                        type: event.type,
+                        at: event.at,
+                        state: accumulator.state.currentStateMachineState,
+                    },
+                    payload: toPayload(event),
+                }],
+        }), {
+            state: startState,
+            stored: [],
+        });
+        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();
@@ -304,14 +318,14 @@ export class WorkflowEngine {
         const expectedPrefix = getExpectedPrefix(state, registry);
         const pattern = buildPrefixPattern(registry);
         const messages = this.engineDeps.transcriptReader.readMessages(transcriptPath);
-        const result = checkIdentity(messages, pattern);
-        this.engineDeps.store.appendEvents(sessionId, [{
+        const identityCheckResult = checkIdentity(messages, pattern);
+        this.engineDeps.store.appendEvents(sessionId, this.wrapEvents([{
                 type: 'identity-verified',
                 at: this.engineDeps.now(),
-                status: result.status,
+                status: identityCheckResult.status,
                 transcriptPath,
-            }]);
-        if (result.status === 'lost') {
+            }], workflow.getState()));
+        if (identityCheckResult.status === 'lost') {
             return `You forgot. Next message MUST begin with: ${expectedPrefix}`;
         }
         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.d.ts

@@ -1,4 +1,6 @@
 export declare const SEPARATOR = "----------------------------------------------------------------";
+export declare const PLATFORM_NOTIFICATION_FENCE = "****************************************************************";
+export declare const JOURNAL_GUIDANCE: string;
 /** @riviere-role cli-output-formatter */
 export declare function formatBlock(title: string, body: string): string;
 /** @riviere-role cli-output-formatter */

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

@@ -1,11 +1,26 @@
 export const SEPARATOR = '----------------------------------------------------------------';
+export const PLATFORM_NOTIFICATION_FENCE = '****************************************************************';
+export const JOURNAL_GUIDANCE = [
+    PLATFORM_NOTIFICATION_FENCE,
+    'PLATFORM NOTIFICATION',
+    '',
+    'Record your progress and reasoning as you work by calling:',
+    '  write-journal <agent-name> "<1\u20133 sentence note>"',
+    '',
+    'Use it for key decisions, progress milestones, and blockers.',
+    'Every session should have a journal trail of the work performed.',
+    PLATFORM_NOTIFICATION_FENCE,
+].join('\n');
 /** @riviere-role cli-output-formatter */
 export function formatBlock(title, body) {
     return `${title}\n${SEPARATOR}\n${body}`;
 }
+function appendJournalGuidance(body) {
+    return `${body}\n\n${JOURNAL_GUIDANCE}`;
+}
 /** @riviere-role cli-output-formatter */
 export function formatTransitionSuccess(title, procedureContent, expectedPrefix) {
-    return formatBlock(title, `${procedureContent}\n\nNext message MUST begin with: ${expectedPrefix}`);
+    return formatBlock(title, appendJournalGuidance(`${procedureContent}\n\nNext message MUST begin with: ${expectedPrefix}`));
 }
 /** @riviere-role cli-output-formatter */
 export function formatTransitionError(to, reason, currentProcedure, expectedPrefix) {
@@ -25,5 +40,5 @@ export function formatOperationSuccess(op, body, expectedPrefix) {
 }
 /** @riviere-role cli-output-formatter */
 export function formatInitSuccess(procedureContent, expectedPrefix) {
-    return formatBlock('Feature team initialized', `${procedureContent}\n\nNext message MUST begin with: ${expectedPrefix}`);
+    return formatBlock('Feature team initialized', appendJournalGuidance(`${procedureContent}\n\nNext message MUST begin with: ${expectedPrefix}`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "exports": {