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

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type { BaseWorkflowState } from './platform/domain/workflow-state';
 export { WorkflowStateError } from './platform/domain/workflow-state';
 export type { BaseEvent } from './platform/domain/base-event';
 export { baseEventSchema } from './platform/domain/base-event';
+export type { EventEnvelope, StoredEvent, } from './platform/domain/stored-event';
+export { flattenStoredEvent, stripEnvelopeKeys, toPayload, } from './platform/domain/stored-event';
 export { engineEventSchema } from './platform/domain/engine-events';
 export type { EngineEvent, SessionStartedEvent, TransitionedEvent, AgentRegisteredEvent, AgentShutDownEvent, JournalEntryEvent, WriteCheckedEvent, BashCheckedEvent, PluginReadCheckedEvent, IdleCheckedEvent, IdentityVerifiedEvent, ContextRequestedEvent, } from './platform/domain/engine-events';
 export { repositoryMetadataEventSchema } from './platform/domain/repository-tracking-events';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { WorkflowStateError } from './platform/domain/workflow-state.js';
 export { baseEventSchema } from './platform/domain/base-event.js';
+export { flattenStoredEvent, stripEnvelopeKeys, toPayload, } from './platform/domain/stored-event.js';
 export { engineEventSchema } from './platform/domain/engine-events.js';
 export { repositoryMetadataEventSchema } from './platform/domain/repository-tracking-events.js';
 export { checkBashCommand } from './platform/domain/bash-enforcement.js';

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,6 @@
 import type { ZodType } from 'zod';
 import type { BaseEvent } from './base-event';
+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,8 +40,8 @@ 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;
 }

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

@@ -19,5 +19,6 @@ export declare class WorkflowEngine<TWorkflow extends RehydratableWorkflow<TStat
     private requireSession;
     private rehydrateFromEvents;
     private persistEvents;
+    private wrapEvents;
     private verifyIdentity;
 }

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

@@ -2,6 +2,7 @@ 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';
 /** @riviere-role domain-service */
 export class WorkflowEngine {
@@ -27,7 +28,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 {
@@ -155,9 +156,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(),
@@ -287,15 +288,34 @@ 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;
     }
     verifyIdentity(sessionId, workflow) {
         const transcriptPath = workflow.getTranscriptPath();
@@ -304,14 +324,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/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.2.1",
   "private": false,
   "type": "module",
   "exports": {