@nt-ai-lab/deterministic-agent-workflow-pi 0.5.5 → 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

@@ -4,9 +4,11 @@ import { createPreToolUseHandler, createWorkflowRunner, formatStopPreventionMess
 import { createStore } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
 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 { hasPiWorkflowMarker, PI_WORKFLOW_MARKER_CUSTOM_TYPE, } 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';
+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';
@@ -23,6 +25,7 @@ export function createPiWorkflowExtension(config) {
     const databasePath = resolveDatabasePath(config.databasePath);
     const commandName = config.commandName ?? DEFAULT_COMMAND_NAME;
     const toolName = config.toolName ?? DEFAULT_TOOL_NAME;
+    const ownership = createPiWorkflowSessionOwnership(databasePath);
     const initializationBySession = new Map();
     const sessionStartsById = new Map();
     const recoveredAssistantBySession = new Map();
@@ -54,7 +57,7 @@ export function createPiWorkflowExtension(config) {
             appendToFile: () => undefined,
             now,
             transcriptReader: new PiTranscriptReader(() => ctx.sessionManager.getBranch()),
-            sessionContext: { getMainSessionId: () => sessionId },
+            sessionContext: { getMainSessionId: () => ownership.delegatedParent(sessionId, store) ?? sessionId, },
         };
     }
     function useEngine(ctx, operation) {
@@ -63,6 +66,7 @@ export function createPiWorkflowExtension(config) {
             const engineDeps = buildEngineDeps(ctx, store);
             const now = engineDeps.now;
             const sessionId = ctx.sessionManager.getSessionId();
+            ownership.requireAccess(store, sessionId);
             const platform = {
                 getPluginRoot: () => config.pluginRoot,
                 now,
@@ -77,15 +81,6 @@ 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) {
         return failSession(ctx, sessionId, `Pi workflow initialization failed: ${detail}`);
     }
@@ -114,23 +109,9 @@ export function createPiWorkflowExtension(config) {
     }
     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) {
-            return event.reason === 'fork' ? 'Forked Pi session has no verifiable parent session file.' : undefined;
-        }
-        const parent = readPiSessionMetadata(parentSessionFile);
-        const store = createStore(databasePath);
-        try {
-            return store.hasSessionStarted(parent.id) || parent.hasWorkflowMarker
-                ? `Cannot fork Pi session ${parent.id}: its workflow is active.`
-                : undefined;
-        }
-        finally {
-            store.db.close();
-        }
+        if (!session.ok)
+            return false;
+        return initializationBySession.get(session.sessionId)?.type === 'inactive';
     }
     function initializeSession(event, ctx, pi, sessionId) {
         try {
@@ -140,22 +121,29 @@ export function createPiWorkflowExtension(config) {
                 return 'Pi session header does not match the active session UUID.';
             const activeBranchHasWorkflowMarker = hasPiWorkflowMarker(ctx.sessionManager.getBranch());
             const sessionHasWorkflowMarker = hasPiWorkflowMarker(ctx.sessionManager.getEntries());
+            const inheritedWorkflowState = ownership.usesInheritedWorkflow(sessionId);
+            const delegatedParent = ownership.delegatedParent(sessionId);
             const result = useEngine(ctx, (engine) => {
                 const sqliteHasWorkflowState = engine.hasSessionStarted(sessionId);
                 if (!sqliteHasWorkflowState) {
-                    const parentFailure = parentSafetyFailure(event, ctx);
+                    const parentFailure = ownership.parentSafetyFailure(event, ctx);
                     if (parentFailure !== undefined)
                         return {
                             type: 'error',
                             output: parentFailure,
                         };
                 }
-                if (sessionHasWorkflowMarker && !activeBranchHasWorkflowMarker)
+                if (delegatedParent !== undefined && !sqliteHasWorkflowState)
+                    return {
+                        type: 'error',
+                        output: `Pi parent session ${delegatedParent} has no persisted workflow.`,
+                    };
+                if (!inheritedWorkflowState && sessionHasWorkflowMarker && !activeBranchHasWorkflowMarker)
                     return {
                         type: 'error',
                         output: `The active Pi branch does not contain this session's ${PI_WORKFLOW_MARKER_CUSTOM_TYPE} marker.`,
                     };
-                if (activeBranchHasWorkflowMarker !== sqliteHasWorkflowState)
+                if (!inheritedWorkflowState && activeBranchHasWorkflowMarker !== sqliteHasWorkflowState)
                     return {
                         type: 'error',
                         output: `Pi transcript and SQLite workflow state disagree for session ${sessionId}.`,
@@ -244,7 +232,7 @@ export function createPiWorkflowExtension(config) {
             }
             sessionStartsById.set(session.sessionId, event);
             try {
-                const hasPersistedWorkflow = hasPersistedWorkflowState(session.sessionId);
+                const hasPersistedWorkflow = ownership.hasPersistedWorkflow(session.sessionId);
                 const hasTranscriptWorkflow = hasPiWorkflowMarker(ctx.sessionManager.getEntries());
                 if (!hasPersistedWorkflow && !hasTranscriptWorkflow) {
                     initializationBySession.set(session.sessionId, { type: 'inactive' });
@@ -304,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)
@@ -353,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',
@@ -368,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/features/pi-extension/entrypoint/pi-workflow-session-ownership.d.ts

@@ -0,0 +1,12 @@
+import type { ExtensionContext, SessionStartEvent } from '@earendil-works/pi-coding-agent';
+import { type SqliteEventStore } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+interface PiWorkflowSessionOwnership {
+    delegatedParent(sessionId: string, store?: SqliteEventStore): string | undefined;
+    hasPersistedWorkflow(sessionId: string): boolean;
+    usesInheritedWorkflow(sessionId: string): boolean;
+    parentSafetyFailure(event: SessionStartEvent, ctx: ExtensionContext): string | undefined;
+    requireAccess(store: SqliteEventStore, sessionId: string): void;
+}
+/** @riviere-role cli-entrypoint */
+export declare function createPiWorkflowSessionOwnership(databasePath: string): PiWorkflowSessionOwnership;
+export {};

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

@@ -0,0 +1,72 @@
+import { createStore, } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+import { resolvePiMainSessionId } from '../../../platform/domain/pi-main-session.js';
+import { readPiSessionMetadata } from '../../../platform/infra/external-clients/pi/pi-session-file.js';
+/** @riviere-role cli-entrypoint */
+export function createPiWorkflowSessionOwnership(databasePath) {
+    const delegatedParent = (sessionId, existingStore) => {
+        const store = existingStore ?? createStore(databasePath);
+        try {
+            if (store.hasSessionStarted(sessionId))
+                return undefined;
+            const mainSessionId = resolvePiMainSessionId(sessionId);
+            return mainSessionId === sessionId ? undefined : mainSessionId;
+        }
+        finally {
+            if (existingStore === undefined)
+                store.db.close();
+        }
+    };
+    const requireParent = (store, parentSessionId) => {
+        if (!store.hasSessionStarted(parentSessionId)) {
+            throw new TypeError(`Pi parent session ${parentSessionId} has no persisted workflow.`);
+        }
+    };
+    return {
+        delegatedParent,
+        hasPersistedWorkflow(sessionId) {
+            const store = createStore(databasePath);
+            try {
+                const parentSessionId = delegatedParent(sessionId, store);
+                if (parentSessionId !== undefined) {
+                    requireParent(store, parentSessionId);
+                    return true;
+                }
+                return store.hasSessionStarted(sessionId);
+            }
+            finally {
+                store.db.close();
+            }
+        },
+        usesInheritedWorkflow(sessionId) {
+            const store = createStore(databasePath);
+            try {
+                return delegatedParent(sessionId, store) !== undefined;
+            }
+            finally {
+                store.db.close();
+            }
+        },
+        parentSafetyFailure(event, ctx) {
+            const parentSessionFile = ctx.sessionManager.getHeader()?.parentSession;
+            if (parentSessionFile === undefined) {
+                return event.reason === 'fork' ? 'Forked Pi session has no verifiable parent session file.' : undefined;
+            }
+            const parent = readPiSessionMetadata(parentSessionFile);
+            const store = createStore(databasePath);
+            try {
+                return store.hasSessionStarted(parent.id) || parent.hasWorkflowMarker
+                    ? `Cannot fork Pi session ${parent.id}: its workflow is active.`
+                    : undefined;
+            }
+            finally {
+                store.db.close();
+            }
+        },
+        requireAccess(store, sessionId) {
+            const parentSessionId = delegatedParent(sessionId, store);
+            if (parentSessionId !== undefined) {
+                requireParent(store, parentSessionId);
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +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 { 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/index.js

@@ -1,2 +1,4 @@
 export { createPiWorkflowExtension, PI_IDLE_RECOVERY_MESSAGE, PI_SESSION_BRANCH_BLOCK_MESSAGE, } from './features/pi-extension/entrypoint/pi-workflow-extension.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-main-session.d.ts

@@ -0,0 +1,2 @@
+/** @riviere-role domain-service */
+export declare function resolvePiMainSessionId(currentSessionId: string, environment?: Readonly<Record<string, string | undefined>>): string;

package/dist/platform/domain/pi-main-session.js

@@ -0,0 +1,15 @@
+const PI_SUBAGENT_PARENT_SESSION = 'PI_SUBAGENT_PARENT_SESSION';
+/** @riviere-role domain-service */
+export function resolvePiMainSessionId(currentSessionId, environment = process.env) {
+    const current = currentSessionId.trim();
+    if (current.length === 0)
+        throw new TypeError('Pi returned an empty session UUID.');
+    const rawParent = environment[PI_SUBAGENT_PARENT_SESSION];
+    if (rawParent === undefined)
+        return current;
+    const parent = rawParent.trim();
+    if (parent.length === 0) {
+        throw new TypeError(`${PI_SUBAGENT_PARENT_SESSION} must contain a non-empty session UUID.`);
+    }
+    return parent;
+}

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-context-window.d.ts

@@ -0,0 +1,3 @@
+import { type AgentSession } from '@earendil-works/pi-coding-agent';
+/** @riviere-role external-client-service */
+export declare function refreshPiContextWindow(session: AgentSession, stateInstructions: string): void;

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

@@ -0,0 +1,17 @@
+import { estimateTokens, } from '@earendil-works/pi-coding-agent';
+/** @riviere-role external-client-service */
+export function refreshPiContextWindow(session, stateInstructions) {
+    if (stateInstructions.trim().length === 0) {
+        throw new TypeError('Pi context state instructions must not be empty.');
+    }
+    if (!session.isIdle) {
+        throw new TypeError('Cannot refresh Pi context until the session is idle.');
+    }
+    if (!session.sessionManager.isPersisted()) {
+        throw new TypeError('Cannot refresh Pi context without a persisted session.');
+    }
+    const tokensBefore = session.messages.reduce((total, message) => total + estimateTokens(message), 0);
+    const boundary = session.sessionManager.appendCustomEntry('pi-context-window-boundary');
+    session.sessionManager.appendCompaction(stateInstructions, boundary, tokensBefore);
+    session.agent.state.messages = session.sessionManager.buildSessionContext().messages;
+}

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",
+  "version": "0.5.6",
   "private": false,
   "type": "module",
   "engines": {
@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "typebox": "^1.3.7",
-    "@nt-ai-lab/deterministic-agent-workflow-cli": "0.4.8",
-    "@nt-ai-lab/deterministic-agent-workflow-engine": "0.4.7",
-    "@nt-ai-lab/deterministic-agent-workflow-event-store": "0.4.7"
+    "@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",