@nt-ai-lab/deterministic-agent-workflow-pi 0.5.5-issue-526.ce3247e.0 → 0.5.6

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

@@ -0,0 +1,22 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { PiWorkflowIdleContext } from '../../../platform/domain/pi-workflow-extension-types.js';
+/** @riviere-role cli-entrypoint */
+export declare function registerPiWorkflowAutomation<TState extends {
+    readonly currentStateMachineState: string;
+}>(pi: ExtensionAPI, options: {
+    readonly databasePath: string;
+    readonly automation?: {
+        readonly ownsState: (state: TState) => boolean;
+        readonly onIdle: (context: PiWorkflowIdleContext<TState>) => Promise<void>;
+    };
+    readonly isReady: (ctx: ExtensionContext) => boolean;
+    readonly getState: (ctx: ExtensionContext) => TState;
+    readonly runOperation: (ctx: ExtensionContext, args: readonly string[]) => {
+        readonly exitCode: number;
+        readonly output: string;
+    };
+    readonly fail: (ctx: ExtensionContext, reason: string) => void;
+}): {
+    ownsState: (ctx: ExtensionContext) => boolean;
+    afterOperation: (ctx: ExtensionContext) => void;
+};

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

@@ -0,0 +1,160 @@
+import { ReviewCoordinator } from '@nt-ai-lab/deterministic-agent-workflow-cli';
+import { WorkflowStateError } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { createStore } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+import { createPiExtensionContextWindow } from '../../../platform/infra/external-clients/pi/pi-extension-context-window.js';
+/** @riviere-role cli-entrypoint */
+export function registerPiWorkflowAutomation(pi, options) {
+    const automation = options.automation;
+    if (automation === undefined)
+        return {
+            ownsState: () => false,
+            afterOperation: () => undefined,
+        };
+    const active = new Map();
+    const cancellations = new Map();
+    const refreshContext = createPiExtensionContextWindow(pi);
+    const fail = (ctx, error) => {
+        options.fail(ctx, `Workflow automation failed: ${String(error)}`);
+    };
+    const isReady = (ctx) => {
+        try {
+            return options.isReady(ctx);
+        }
+        catch (error) {
+            fail(ctx, error);
+            return false;
+        }
+    };
+    const ownsState = (ctx) => {
+        if (!isReady(ctx))
+            return false;
+        try {
+            return active.has(ctx.sessionManager.getSessionId()) || automation.ownsState(options.getState(ctx));
+        }
+        catch (error) {
+            fail(ctx, error);
+            return true;
+        }
+    };
+    const runIdle = async (ctx) => {
+        const sessionId = ctx.sessionManager.getSessionId();
+        if (!isReady(ctx) || !ctx.isIdle() || active.has(sessionId) || !ownsState(ctx))
+            return;
+        const controller = new AbortController();
+        active.set(sessionId, controller);
+        const stops = new Set();
+        cancellations.set(sessionId, stops);
+        const requireActive = () => {
+            if (controller.signal.aborted || active.get(sessionId) !== controller ||
+                ctx.sessionManager.getSessionId() !== sessionId || !isReady(ctx)) {
+                throw new WorkflowStateError('The workflow automation context is no longer active.');
+            }
+        };
+        const resume = {};
+        try {
+            await automation.onIdle({
+                sessionId,
+                signal: controller.signal,
+                workingDirectory: ctx.cwd,
+                getState: () => {
+                    requireActive();
+                    return options.getState(ctx);
+                },
+                runOperation: (operation, ...args) => {
+                    requireActive();
+                    const result = options.runOperation(ctx, [operation, ...args]);
+                    if (result.exitCode !== 0)
+                        throw new WorkflowStateError(result.output);
+                    return result.output;
+                },
+                runReviews: async (request, client) => {
+                    requireActive();
+                    const store = createStore(options.databasePath);
+                    const coordinator = new ReviewCoordinator({
+                        store,
+                        client,
+                        now: () => new Date().toISOString()
+                    });
+                    const cancel = async () => {
+                        const result = await coordinator.cancel(request.bundleId, 'Pi session shutdown');
+                        if (result.type === 'failed')
+                            throw new WorkflowStateError(result.reason);
+                    };
+                    stops.add(cancel);
+                    try {
+                        return await coordinator.run({
+                            ...request,
+                            sessionId,
+                            workingDirectory: ctx.cwd
+                        }, options.getState(ctx).currentStateMachineState);
+                    }
+                    finally {
+                        stops.delete(cancel);
+                        store.db.close();
+                    }
+                },
+                resumeWithFreshContext: (instructions) => {
+                    requireActive();
+                    if (resume.instructions !== undefined)
+                        throw new WorkflowStateError('Workflow automation already requested a fresh context.');
+                    if (automation.ownsState(options.getState(ctx))) {
+                        throw new WorkflowStateError('Cannot resume the conversational agent in a workflow-owned state.');
+                    }
+                    refreshContext(ctx, instructions);
+                    resume.instructions = instructions;
+                },
+            });
+        }
+        catch (error) {
+            fail(ctx, error);
+            return;
+        }
+        finally {
+            active.delete(sessionId);
+            cancellations.delete(sessionId);
+        }
+        if (!controller.signal.aborted && resume.instructions !== undefined) {
+            pi.sendUserMessage(resume.instructions);
+        }
+    };
+    pi.on('session_shutdown', async (_event, ctx) => {
+        const sessionId = ctx.sessionManager.getSessionId();
+        active.get(sessionId)?.abort();
+        const results = await Promise.allSettled([...cancellations.get(sessionId) ?? []].map((cancel) => cancel()));
+        for (const result of results) {
+            if (result.status === 'rejected')
+                fail(ctx, result.reason);
+        }
+    });
+    pi.on('agent_settled', (_event, ctx) => runIdle(ctx));
+    pi.on('session_start', (_event, ctx) => runIdle(ctx));
+    pi.on('tool_call', (_event, ctx) => {
+        if (ownsState(ctx))
+            return {
+                block: true,
+                reason: 'The workflow owns this state; conversational tools are disabled.'
+            };
+        return undefined;
+    });
+    pi.on('input', (_event, ctx) => {
+        if (ownsState(ctx))
+            return { action: 'handled' };
+        return undefined;
+    });
+    pi.on('session_before_switch', (_event, ctx) => {
+        if (active.has(ctx.sessionManager.getSessionId()))
+            return { cancel: true };
+        return undefined;
+    });
+    return {
+        ownsState,
+        afterOperation: (ctx) => {
+            if (!ownsState(ctx))
+                return;
+            if (ctx.isIdle())
+                void runIdle(ctx);
+            else
+                ctx.abort();
+        },
+    };
+}

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

@@ -1,6 +1,6 @@
 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';
+import type { PiSessionIdResult } from '../../../platform/domain/pi-workflow-extension-types.js';
 /** @riviere-role cli-entrypoint */
 export declare function translationNote(toolName: string): string;
 /** @riviere-role cli-entrypoint */

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

@@ -1,5 +1,5 @@
 import type { BaseWorkflowState, RehydratableWorkflow, TransitionContext } from '@nt-ai-lab/deterministic-agent-workflow-engine';
-import type { PiWorkflowExtension, PiWorkflowExtensionConfig } from '../../../platform/domain/pi-workflow-extension-types';
+import type { PiWorkflowExtension, PiWorkflowExtensionConfig } from '../../../platform/domain/pi-workflow-extension-types.js';
 export declare const PI_IDLE_RECOVERY_MESSAGE: string;
 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 */

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

@@ -8,6 +8,7 @@ import { hasPiWorkflowMarker, PI_WORKFLOW_MARKER_CUSTOM_TYPE, } from '../../../p
 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';
 import { createPiWorkflowSessionOwnership } from './pi-workflow-session-ownership.js';
+import { registerPiWorkflowAutomation } from './pi-workflow-automation.js';
 const PI_QUESTION_TOOL = 'question';
 const DEFAULT_COMMAND_NAME = 'workflow';
 const DEFAULT_TOOL_NAME = 'workflow';
@@ -291,7 +292,7 @@ export function createPiWorkflowExtension(config) {
             return { action: 'handled' };
         });
         pi.on('agent_settled', (_event, ctx) => {
-            if (isInactive(ctx) || readinessFailure(ctx) !== undefined)
+            if (isInactive(ctx) || readinessFailure(ctx) !== undefined || automation.ownsState(ctx))
                 return;
             const session = readSessionId(ctx);
             if (!session.ok)
@@ -340,6 +341,8 @@ export function createPiWorkflowExtension(config) {
             executionMode: 'sequential',
             async execute(_toolCallId, parameters, _signal, _onUpdate, ctx) {
                 const result = runRoute(ctx, [parameters.operation, ...(parameters.args ?? [])], pi);
+                if (result.exitCode === 0)
+                    automation.afterOperation(ctx);
                 return {
                     content: [{
                             type: 'text',
@@ -355,12 +358,23 @@ export function createPiWorkflowExtension(config) {
             handler: async (rawArguments, ctx) => {
                 try {
                     const result = runRoute(ctx, parsePiCommandArguments(rawArguments), pi);
-                    notifyRouteResult(ctx, pi, result);
+                    if (result.exitCode === 0)
+                        automation.afterOperation(ctx);
+                    if (result.exitCode !== 0 || (!automation.ownsState(ctx) && readinessFailure(ctx) === undefined))
+                        notifyRouteResult(ctx, pi, result);
                 }
                 catch (error) {
                     ctx.ui.notify(String(error), 'error');
                 }
             },
         });
+        const automation = registerPiWorkflowAutomation(pi, {
+            databasePath,
+            ...(config.automation === undefined ? {} : { automation: config.automation }),
+            isReady: (ctx) => readinessFailure(ctx) === undefined && !ownership.usesInheritedWorkflow(ctx.sessionManager.getSessionId()),
+            getState: (ctx) => useEngine(ctx, (engine) => engine.getWorkflowState(ctx.sessionManager.getSessionId())),
+            runOperation: (ctx, args) => runRoute(ctx, args, pi),
+            fail: (ctx, reason) => markSafetyUnavailable(ctx, ctx.sessionManager.getSessionId(), reason),
+        });
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { createPiWorkflowExtension, PI_IDLE_RECOVERY_MESSAGE, PI_SESSION_BRANCH_BLOCK_MESSAGE, } from './features/pi-extension/entrypoint/pi-workflow-extension';
-export type { PiWorkflowExtension, PiWorkflowExtensionConfig, } from './platform/domain/pi-workflow-extension-types';
-export { resolvePiMainSessionId } from './platform/domain/pi-main-session';
-export { refreshPiContextWindow } from './platform/infra/external-clients/pi/pi-context-window';
-export { PiTranscriptReader } from './platform/infra/external-clients/pi/pi-transcript-reader';
+export { createPiWorkflowExtension, PI_IDLE_RECOVERY_MESSAGE, PI_SESSION_BRANCH_BLOCK_MESSAGE, } from './features/pi-extension/entrypoint/pi-workflow-extension.js';
+export type { PiWorkflowExtension, PiWorkflowExtensionConfig, PiWorkflowIdleContext, } from './platform/domain/pi-workflow-extension-types.js';
+export { resolvePiMainSessionId } from './platform/domain/pi-main-session.js';
+export { refreshPiContextWindow } from './platform/infra/external-clients/pi/pi-context-window.js';
+export { PiTranscriptReader } from './platform/infra/external-clients/pi/pi-transcript-reader.js';

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

@@ -1,6 +1,6 @@
 import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
-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';
+import type { BaseWorkflowState, RehydratableWorkflow, ReviewBundleRequest, TransitionContext, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { PlatformContext, PreToolUseHandlerConfig, RouteMap, ReviewAgentClient, ReviewCoordinatorResult } from '@nt-ai-lab/deterministic-agent-workflow-cli';
 /** @riviere-role value-object */
 export type PiWorkflowExtension = ExtensionFactory;
 /** @riviere-role value-object */
@@ -23,6 +23,16 @@ export type PiSessionIdResult = {
     readonly reason: string;
 };
 /** @riviere-role value-object */
+export interface PiWorkflowIdleContext<TState> {
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+    readonly workingDirectory: string;
+    getState(): TState;
+    runOperation(operation: string, ...args: readonly string[]): string;
+    runReviews(request: Omit<ReviewBundleRequest, 'sessionId' | 'workingDirectory'>, client: ReviewAgentClient): Promise<ReviewCoordinatorResult>;
+    resumeWithFreshContext(stateInstructions: string): void;
+}
+/** @riviere-role value-object */
 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>;
@@ -33,4 +43,8 @@ export type PiWorkflowExtensionConfig<TWorkflow extends RehydratableWorkflow<TSt
     readonly commandName?: string;
     readonly toolName?: string;
     readonly stopPreventionMessage?: string;
+    readonly automation?: {
+        readonly ownsState: (state: TState) => boolean;
+        readonly onIdle: (context: PiWorkflowIdleContext<TState>) => Promise<void>;
+    };
 };

package/dist/platform/infra/external-clients/pi/pi-extension-context-window.d.ts

@@ -0,0 +1,3 @@
+import { type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+/** @riviere-role external-client-service */
+export declare function createPiExtensionContextWindow(pi: ExtensionAPI): (ctx: ExtensionContext, instructions: string) => void;

package/dist/platform/infra/external-clients/pi/pi-extension-context-window.js

@@ -0,0 +1,77 @@
+import { existsSync } from 'node:fs';
+import { buildSessionContext, } from '@earendil-works/pi-coding-agent';
+const BOUNDARY_TYPE = 'pi-context-window-state';
+function readBoundary(ctx) {
+    const branch = ctx.sessionManager.getBranch();
+    const boundary = branch.findLast((entry) => entry.type === 'custom' && entry.customType === BOUNDARY_TYPE);
+    if (boundary === undefined)
+        return undefined;
+    if (boundary.type !== 'custom' || typeof boundary.data !== 'string' || boundary.data.trim().length === 0) {
+        throw new TypeError('Pi context boundary has invalid state instructions.');
+    }
+    return {
+        boundary,
+        instructions: boundary.data,
+        entries: branch.slice(branch.indexOf(boundary))
+    };
+}
+/** @riviere-role external-client-service */
+export function createPiExtensionContextWindow(pi) {
+    pi.on('context', (_event, ctx) => {
+        try {
+            const window = readBoundary(ctx);
+            if (window === undefined)
+                return;
+            return {
+                messages: [{
+                        role: 'user',
+                        content: window.instructions,
+                        timestamp: Date.parse(window.boundary.timestamp),
+                    }, ...buildSessionContext(window.entries).messages],
+            };
+        }
+        catch (error) {
+            ctx.abort();
+            ctx.ui.notify(`Pi context safety is unavailable: ${String(error)}`, 'error');
+            ctx.shutdown();
+            return { messages: [] };
+        }
+    });
+    pi.on('session_before_compact', (event, ctx) => {
+        try {
+            const window = readBoundary(ctx);
+            if (window === undefined)
+                return;
+            return {
+                compaction: {
+                    summary: window.instructions,
+                    firstKeptEntryId: window.boundary.id,
+                    tokensBefore: event.preparation.tokensBefore,
+                },
+            };
+        }
+        catch (error) {
+            ctx.abort();
+            ctx.ui.notify(`Pi context safety is unavailable: ${String(error)}`, 'error');
+            ctx.shutdown();
+            return { cancel: true };
+        }
+    });
+    return (ctx, instructions) => {
+        if (instructions.trim().length === 0) {
+            throw new TypeError('Pi context state instructions must not be empty.');
+        }
+        if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+            throw new TypeError('Cannot refresh Pi context until the session is idle without pending messages.');
+        }
+        const sessionFile = ctx.sessionManager.getSessionFile();
+        if (sessionFile === undefined || !existsSync(sessionFile)) {
+            throw new TypeError('Cannot refresh Pi context without a persisted session.');
+        }
+        pi.appendEntry(BOUNDARY_TYPE, instructions);
+        const window = readBoundary(ctx);
+        if (window?.instructions !== instructions || window.boundary.id !== ctx.sessionManager.getLeafId()) {
+            throw new TypeError('Pi did not persist the requested context boundary.');
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nt-ai-lab/deterministic-agent-workflow-pi",
-  "version": "0.5.5-issue-526.ce3247e.0",
+  "version": "0.5.6",
   "private": false,
   "type": "module",
   "engines": {
@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "typebox": "^1.3.7",
-    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.4.8-issue-526.ce3247e.0",
-    "@nt-ai-lab/deterministic-agent-workflow-cli": "0.4.8-issue-526.ce3247e.0",
-    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.4.8-issue-526.ce3247e.0"
+    "@nt-ai-lab/deterministic-agent-workflow-cli": "0.4.9",
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.4.9",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.4.9"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",