@nt-ai-lab/deterministic-agent-workflow-pi 0.4.3 → 0.5.3

package/dist/features/pi-extension/entrypoint/pi-workflow-extension-platform.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { RunnerResult } from '@nt-ai-lab/deterministic-agent-workflow-cli';
+import type { PiSessionIdResult } from '../../../platform/domain/pi-workflow-extension-types';
+/** @riviere-role cli-entrypoint */
+export declare function translationNote(toolName: string): string;
+/** @riviere-role cli-entrypoint */
+export declare function resolveDatabasePath(configured: string | undefined): string;
+/** @riviere-role cli-entrypoint */
+export declare function readSessionId(ctx: ExtensionContext): PiSessionIdResult;
+/** @riviere-role cli-entrypoint */
+export declare function requireSessionFile(ctx: ExtensionContext): string;
+/** @riviere-role cli-entrypoint */
+export declare function notifyRouteResult(ctx: ExtensionContext, pi: ExtensionAPI, result: RunnerResult): void;
+/** @riviere-role cli-entrypoint */
+export declare function readWorkflowInstruction(path: string, note: string): string;

package/dist/features/pi-extension/entrypoint/pi-workflow-extension-platform.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** @riviere-role cli-entrypoint */
+export function translationNote(toolName) {
+    return [
+        `> **Pi**: When instructions say to run a workflow command, call the \`${toolName}\` tool instead:`,
+        '> `operation: "<op>", args: ["<arg>", ...]`.',
+        '',
+        '---',
+        '',
+        '',
+    ].join('\n');
+}
+/** @riviere-role cli-entrypoint */
+export function resolveDatabasePath(configured) {
+    if (configured !== undefined && configured !== '')
+        return configured;
+    const fromEnvironment = process.env['WORKFLOW_EVENTS_DB'];
+    if (fromEnvironment !== undefined && fromEnvironment !== '')
+        return fromEnvironment;
+    return join(homedir(), 'ai-workflow-database', '.workflow-events.db');
+}
+/** @riviere-role cli-entrypoint */
+export function readSessionId(ctx) {
+    try {
+        const sessionId = ctx.sessionManager.getSessionId();
+        if (sessionId.trim().length === 0)
+            return {
+                ok: false,
+                reason: 'Pi returned an empty session UUID.'
+            };
+        return {
+            ok: true,
+            sessionId
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `Pi session UUID is unavailable: ${String(error)}`
+        };
+    }
+}
+/** @riviere-role cli-entrypoint */
+export function requireSessionFile(ctx) {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    if (sessionFile === undefined)
+        throw new TypeError('Ephemeral Pi sessions are unsupported because no persistent transcript file is available.');
+    return sessionFile;
+}
+/** @riviere-role cli-entrypoint */
+export function notifyRouteResult(ctx, pi, result) {
+    if (result.exitCode !== 0) {
+        ctx.ui.notify(result.output, 'error');
+        return;
+    }
+    if (result.output === '') {
+        ctx.ui.notify('Workflow operation completed.', 'info');
+        return;
+    }
+    pi.sendUserMessage(result.output);
+}
+/** @riviere-role cli-entrypoint */
+export function readWorkflowInstruction(path, note) {
+    return `${note}${readFileSync(path, 'utf8')}`;
+}

package/dist/features/pi-extension/entrypoint/pi-workflow-extension.d.ts

@@ -1,6 +1,6 @@
-import type { BaseWorkflowState, RehydratableWorkflow } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { BaseWorkflowState, RehydratableWorkflow, TransitionContext } from '@nt-ai-lab/deterministic-agent-workflow-engine';
 import type { PiWorkflowExtension, PiWorkflowExtensionConfig } from '../../../platform/domain/pi-workflow-extension-types';
 export declare const PI_IDLE_RECOVERY_MESSAGE = "You have stopped. You should never stop until the workflow is complete unless your current state permits stopping.";
 export declare const PI_SESSION_BRANCH_BLOCK_MESSAGE = "Pi session tree navigation and forks are disabled while a workflow is active.";
 /** @riviere-role cli-entrypoint */
-export declare function createPiWorkflowExtension<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string>(config: PiWorkflowExtensionConfig<TWorkflow, TState, TDeps, TStateName, TOperation>): PiWorkflowExtension;
+export declare function createPiWorkflowExtension<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string, TTransitionContext extends TransitionContext<TState, TStateName> = TransitionContext<TState, TStateName>>(config: PiWorkflowExtensionConfig<TWorkflow, TState, TDeps, TStateName, TOperation, TTransitionContext>): PiWorkflowExtension;

package/dist/features/pi-extension/entrypoint/pi-workflow-extension.js

@@ -1,5 +1,3 @@
-import { readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
 import { createPreToolUseHandler, createWorkflowRunner, getRepositoryName, } from '@nt-ai-lab/deterministic-agent-workflow-cli';
@@ -8,77 +6,25 @@ import { Type } from 'typebox';
 import { parsePiCommandArguments } from '../../../platform/domain/pi-command-arguments.js';
 import { hasPiWorkflowMarker, PI_WORKFLOW_MARKER_CUSTOM_TYPE, readPiSessionMetadata, } from '../../../platform/infra/external-clients/pi/pi-session-file.js';
 import { getLatestPiAssistantSettlement, PiTranscriptReader, } from '../../../platform/infra/external-clients/pi/pi-transcript-reader.js';
+import { notifyRouteResult, readSessionId, readWorkflowInstruction, requireSessionFile, resolveDatabasePath, translationNote, } from './pi-workflow-extension-platform.js';
 const PI_QUESTION_TOOL = 'question';
 const DEFAULT_COMMAND_NAME = 'workflow';
 const DEFAULT_TOOL_NAME = 'workflow';
 const INITIALIZATION_PENDING_REASON = 'Pi workflow initialization has not completed safely. Tool execution is blocked.';
+const INACTIVE_WORKFLOW_REASON = 'Pi workflow is inactive. Run the workflow init command before using workflow operations.';
 export const PI_IDLE_RECOVERY_MESSAGE = 'You have stopped. You should never stop until the workflow is complete unless your current state permits stopping.';
 export const PI_SESSION_BRANCH_BLOCK_MESSAGE = 'Pi session tree navigation and forks are disabled while a workflow is active.';
 const workflowToolParameters = Type.Object({
     operation: Type.String({ description: 'Workflow operation, for example init or transition' }),
     args: Type.Optional(Type.Array(Type.String({ description: 'One workflow operation argument' }))),
 });
-function translationNote(toolName) {
-    return [
-        `> **Pi**: When instructions say to run a workflow command, call the \`${toolName}\` tool instead:`,
-        '> `operation: "<op>", args: ["<arg>", ...]`.',
-        '',
-        '---',
-        '',
-        '',
-    ].join('\n');
-}
-function resolveDatabasePath(configured) {
-    if (configured !== undefined && configured !== '')
-        return configured;
-    const fromEnvironment = process.env['WORKFLOW_EVENTS_DB'];
-    if (fromEnvironment !== undefined && fromEnvironment !== '')
-        return fromEnvironment;
-    return join(homedir(), 'ai-workflow-database', '.workflow-events.db');
-}
-function readSessionId(ctx) {
-    try {
-        const sessionId = ctx.sessionManager.getSessionId();
-        if (sessionId.trim().length === 0)
-            return {
-                ok: false,
-                reason: 'Pi returned an empty session UUID.',
-            };
-        return {
-            ok: true,
-            sessionId,
-        };
-    }
-    catch (error) {
-        return {
-            ok: false,
-            reason: `Pi session UUID is unavailable: ${String(error)}`,
-        };
-    }
-}
-function requireSessionFile(ctx) {
-    const sessionFile = ctx.sessionManager.getSessionFile();
-    if (sessionFile === undefined)
-        throw new TypeError('Ephemeral Pi sessions are unsupported because no persistent transcript file is available.');
-    return sessionFile;
-}
-function notifyRouteResult(ctx, pi, result) {
-    if (result.exitCode !== 0) {
-        ctx.ui.notify(result.output, 'error');
-        return;
-    }
-    if (result.output === '') {
-        ctx.ui.notify('Workflow operation completed.', 'info');
-        return;
-    }
-    pi.sendUserMessage(result.output);
-}
 /** @riviere-role cli-entrypoint */
 export function createPiWorkflowExtension(config) {
     const databasePath = resolveDatabasePath(config.databasePath);
     const commandName = config.commandName ?? DEFAULT_COMMAND_NAME;
     const toolName = config.toolName ?? DEFAULT_TOOL_NAME;
     const initializationBySession = new Map();
+    const sessionStartsById = new Map();
     const recoveredAssistantBySession = new Map();
     const preToolUse = createPreToolUseHandler({
         bashForbidden: config.bashForbidden,
@@ -94,23 +40,28 @@ export function createPiWorkflowExtension(config) {
         questionToolName: PI_QUESTION_TOOL,
         customGates: config.customGates,
     });
+    function buildEngineDeps(ctx, store) {
+        const sessionId = ctx.sessionManager.getSessionId();
+        const now = () => new Date().toISOString();
+        const note = translationNote(toolName);
+        return {
+            store,
+            getPluginRoot: () => config.pluginRoot,
+            getEnvFilePath: () => join(config.pluginRoot, '.pi', 'unused.env'),
+            getRepositoryName: () => getRepositoryName(ctx.cwd),
+            readFile: (path) => readWorkflowInstruction(path, note),
+            appendToFile: () => undefined,
+            now,
+            transcriptReader: new PiTranscriptReader(() => ctx.sessionManager.getBranch()),
+            sessionContext: { getMainSessionId: () => sessionId },
+        };
+    }
     function useEngine(ctx, operation) {
         const store = createStore(databasePath);
         try {
+            const engineDeps = buildEngineDeps(ctx, store);
+            const now = engineDeps.now;
             const sessionId = ctx.sessionManager.getSessionId();
-            const now = () => new Date().toISOString();
-            const note = translationNote(toolName);
-            const engineDeps = {
-                store,
-                getPluginRoot: () => config.pluginRoot,
-                getEnvFilePath: () => join(config.pluginRoot, '.pi', 'unused.env'),
-                getRepositoryName: () => getRepositoryName(ctx.cwd),
-                readFile: (path) => `${note}${readFileSync(path, 'utf8')}`,
-                appendToFile: () => undefined,
-                now,
-                transcriptReader: new PiTranscriptReader(() => ctx.sessionManager.getBranch()),
-                sessionContext: { getMainSessionId: () => sessionId },
-            };
             const platform = {
                 getPluginRoot: () => config.pluginRoot,
                 now,
@@ -125,8 +76,22 @@ export function createPiWorkflowExtension(config) {
             store.db.close();
         }
     }
+    function hasPersistedWorkflowState(sessionId) {
+        const store = createStore(databasePath);
+        try {
+            return store.hasSessionStarted(sessionId);
+        }
+        finally {
+            store.db.close();
+        }
+    }
     function markInitializationFailed(ctx, sessionId, detail) {
-        const reason = `Pi workflow initialization failed: ${detail}`;
+        return failSession(ctx, sessionId, `Pi workflow initialization failed: ${detail}`);
+    }
+    function markSafetyUnavailable(ctx, sessionId, detail) {
+        return failSession(ctx, sessionId, `Pi workflow safety is unavailable: ${detail}`);
+    }
+    function failSession(ctx, sessionId, reason) {
         initializationBySession.set(sessionId, {
             type: 'failed',
             reason,
@@ -142,8 +107,14 @@ export function createPiWorkflowExtension(config) {
         const status = initializationBySession.get(session.sessionId);
         if (status?.type === 'ready')
             return undefined;
+        if (status?.type === 'inactive')
+            return INACTIVE_WORKFLOW_REASON;
         return status?.type === 'failed' ? status.reason : INITIALIZATION_PENDING_REASON;
     }
+    function isInactive(ctx) {
+        const session = readSessionId(ctx);
+        return session.ok && initializationBySession.get(session.sessionId)?.type === 'inactive';
+    }
     function parentSafetyFailure(event, ctx) {
         const parentSessionFile = ctx.sessionManager.getHeader()?.parentSession;
         if (parentSessionFile === undefined) {
@@ -211,7 +182,29 @@ export function createPiWorkflowExtension(config) {
             return String(error);
         }
     }
-    function runRoute(ctx, args) {
+    function runRoute(ctx, args, pi) {
+        if (isInactive(ctx) && args[0] === 'init') {
+            const session = readSessionId(ctx);
+            if (!session.ok)
+                return {
+                    output: session.reason,
+                    exitCode: 1,
+                };
+            const event = sessionStartsById.get(session.sessionId);
+            if (event === undefined)
+                return {
+                    output: INITIALIZATION_PENDING_REASON,
+                    exitCode: 1,
+                };
+            initializationBySession.set(session.sessionId, { type: 'initializing' });
+            const failure = initializeSession(event, ctx, pi, session.sessionId);
+            if (failure !== undefined)
+                return {
+                    output: markInitializationFailed(ctx, session.sessionId, failure),
+                    exitCode: 1,
+                };
+            initializationBySession.set(session.sessionId, { type: 'ready' });
+        }
         const notReady = readinessFailure(ctx);
         if (notReady !== undefined)
             return {
@@ -235,7 +228,7 @@ export function createPiWorkflowExtension(config) {
         }
         catch (error) {
             return {
-                output: markInitializationFailed(ctx, session.sessionId, `Workflow operation could not establish safe state: ${String(error)}`),
+                output: markSafetyUnavailable(ctx, session.sessionId, `Workflow operation could not establish safe state: ${String(error)}`),
                 exitCode: 1,
             };
         }
@@ -248,6 +241,19 @@ export function createPiWorkflowExtension(config) {
                 ctx.shutdown();
                 return;
             }
+            sessionStartsById.set(session.sessionId, event);
+            try {
+                const hasPersistedWorkflow = hasPersistedWorkflowState(session.sessionId);
+                const hasTranscriptWorkflow = hasPiWorkflowMarker(ctx.sessionManager.getEntries());
+                if (!hasPersistedWorkflow && !hasTranscriptWorkflow) {
+                    initializationBySession.set(session.sessionId, { type: 'inactive' });
+                    return;
+                }
+            }
+            catch (error) {
+                markInitializationFailed(ctx, session.sessionId, String(error));
+                return;
+            }
             initializationBySession.set(session.sessionId, { type: 'initializing' });
             const failure = initializeSession(event, ctx, pi, session.sessionId);
             if (failure !== undefined) {
@@ -257,6 +263,8 @@ export function createPiWorkflowExtension(config) {
             initializationBySession.set(session.sessionId, { type: 'ready' });
         });
         pi.on('tool_call', (event, ctx) => {
+            if (isInactive(ctx))
+                return;
             const notReady = readinessFailure(ctx);
             if (notReady !== undefined)
                 return {
@@ -281,11 +289,13 @@ export function createPiWorkflowExtension(config) {
             catch (error) {
                 return {
                     block: true,
-                    reason: markInitializationFailed(ctx, session.sessionId, `Tool safety could not be established: ${String(error)}`),
+                    reason: markSafetyUnavailable(ctx, session.sessionId, `Tool safety could not be established: ${String(error)}`),
                 };
             }
         });
         pi.on('input', (_event, ctx) => {
+            if (isInactive(ctx))
+                return;
             const notReady = readinessFailure(ctx);
             if (notReady === undefined)
                 return;
@@ -293,7 +303,7 @@ export function createPiWorkflowExtension(config) {
             return { action: 'handled' };
         });
         pi.on('agent_settled', (_event, ctx) => {
-            if (readinessFailure(ctx) !== undefined)
+            if (isInactive(ctx) || readinessFailure(ctx) !== undefined)
                 return;
             const session = readSessionId(ctx);
             if (!session.ok)
@@ -311,7 +321,7 @@ export function createPiWorkflowExtension(config) {
                 }
             }
             catch (error) {
-                markInitializationFailed(ctx, session.sessionId, `Stopping safety could not be established: ${String(error)}`);
+                markSafetyUnavailable(ctx, session.sessionId, `Stopping safety could not be established: ${String(error)}`);
             }
         });
         const blockSessionBranching = (ctx) => {
@@ -321,6 +331,8 @@ export function createPiWorkflowExtension(config) {
                 ctx.shutdown();
                 return { cancel: true };
             }
+            if (isInactive(ctx))
+                return undefined;
             const notReady = readinessFailure(ctx);
             if (notReady !== undefined) {
                 markInitializationFailed(ctx, session.sessionId, notReady);
@@ -339,7 +351,7 @@ export function createPiWorkflowExtension(config) {
             parameters: workflowToolParameters,
             executionMode: 'sequential',
             async execute(_toolCallId, parameters, _signal, _onUpdate, ctx) {
-                const result = runRoute(ctx, [parameters.operation, ...(parameters.args ?? [])]);
+                const result = runRoute(ctx, [parameters.operation, ...(parameters.args ?? [])], pi);
                 return {
                     content: [{
                             type: 'text',
@@ -354,7 +366,7 @@ export function createPiWorkflowExtension(config) {
             description: `Execute a deterministic workflow operation: /${commandName} <operation> [args]`,
             handler: async (rawArguments, ctx) => {
                 try {
-                    const result = runRoute(ctx, parsePiCommandArguments(rawArguments));
+                    const result = runRoute(ctx, parsePiCommandArguments(rawArguments), pi);
                     notifyRouteResult(ctx, pi, result);
                 }
                 catch (error) {

package/dist/platform/domain/pi-workflow-extension-types.d.ts

@@ -1,10 +1,12 @@
 import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
-import type { BaseWorkflowState, RehydratableWorkflow, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { BaseWorkflowState, RehydratableWorkflow, TransitionContext, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
 import type { PlatformContext, PreToolUseHandlerConfig, RouteMap } from '@nt-ai-lab/deterministic-agent-workflow-cli';
 /** @riviere-role value-object */
 export type PiWorkflowExtension = ExtensionFactory;
 /** @riviere-role value-object */
 export type PiInitializationStatus = {
+    readonly type: 'inactive';
+} | {
     readonly type: 'initializing';
 } | {
     readonly type: 'ready';
@@ -21,8 +23,8 @@ export type PiSessionIdResult = {
     readonly reason: string;
 };
 /** @riviere-role value-object */
-export type PiWorkflowExtensionConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> = Omit<PreToolUseHandlerConfig<TWorkflow, TState, TStateName>, 'questionToolName'> & {
-    readonly workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>;
+export type PiWorkflowExtensionConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string, TTransitionContext extends TransitionContext<TState, TStateName> = TransitionContext<TState, TStateName>> = Omit<PreToolUseHandlerConfig<TWorkflow, TState, TStateName>, 'questionToolName'> & {
+    readonly workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation, TTransitionContext>;
     readonly routes: RouteMap<TWorkflow, TState>;
     readonly buildWorkflowDeps: (platform: PlatformContext) => TDeps;
     readonly pluginRoot: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-pi",
-  "version": "0.4.3",
+  "version": "0.5.3",
   "private": false,
   "type": "module",
   "engines": {
@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "typebox": "^1.3.7",
-    "@nt-ai-lab/deterministic-agent-workflow-cli": "0.4.4",
-    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.4.4",
-    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.4.4"
+    "@nt-ai-lab/deterministic-agent-workflow-cli": "0.4.6",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.4.6",
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.4.6"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",