@nt-ai-lab/deterministic-agent-workflow-engine 0.2.1 → 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/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,6 +300,17 @@ 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;

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/package.json

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