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

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

@@ -0,0 +1,6 @@
+import type { BaseWorkflowState, RehydratableWorkflow } 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;

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

@@ -0,0 +1,366 @@
+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';
+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 { getLatestPiAssistantSettlement, PiTranscriptReader, } from '../../../platform/infra/external-clients/pi/pi-transcript-reader.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.';
+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 recoveredAssistantBySession = new Map();
+    const preToolUse = createPreToolUseHandler({
+        bashForbidden: config.bashForbidden,
+        isWriteAllowed: config.isWriteAllowed,
+        questionToolName: PI_QUESTION_TOOL,
+        customGates: config.customGates,
+    });
+    const runner = createWorkflowRunner({
+        workflowDefinition: config.workflowDefinition,
+        routes: config.routes,
+        bashForbidden: config.bashForbidden,
+        isWriteAllowed: config.isWriteAllowed,
+        questionToolName: PI_QUESTION_TOOL,
+        customGates: config.customGates,
+    });
+    function useEngine(ctx, operation) {
+        const store = createStore(databasePath);
+        try {
+            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,
+                getSessionId: () => sessionId,
+                store,
+            };
+            const workflowDeps = config.buildWorkflowDeps(platform);
+            const engine = new WorkflowEngine(config.workflowDefinition, engineDeps, workflowDeps);
+            return operation(engine, engineDeps, workflowDeps);
+        }
+        finally {
+            store.db.close();
+        }
+    }
+    function markInitializationFailed(ctx, sessionId, detail) {
+        const reason = `Pi workflow initialization failed: ${detail}`;
+        initializationBySession.set(sessionId, {
+            type: 'failed',
+            reason,
+        });
+        ctx.ui.notify(reason, 'error');
+        ctx.shutdown();
+        return reason;
+    }
+    function readinessFailure(ctx) {
+        const session = readSessionId(ctx);
+        if (!session.ok)
+            return session.reason;
+        const status = initializationBySession.get(session.sessionId);
+        if (status?.type === 'ready')
+            return undefined;
+        return status?.type === 'failed' ? status.reason : INITIALIZATION_PENDING_REASON;
+    }
+    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();
+        }
+    }
+    function initializeSession(event, ctx, pi, sessionId) {
+        try {
+            const sessionFile = requireSessionFile(ctx);
+            const header = ctx.sessionManager.getHeader();
+            if (header?.id !== sessionId)
+                return 'Pi session header does not match the active session UUID.';
+            const activeBranchHasWorkflowMarker = hasPiWorkflowMarker(ctx.sessionManager.getBranch());
+            const sessionHasWorkflowMarker = hasPiWorkflowMarker(ctx.sessionManager.getEntries());
+            const result = useEngine(ctx, (engine) => {
+                const sqliteHasWorkflowState = engine.hasSessionStarted(sessionId);
+                if (!sqliteHasWorkflowState) {
+                    const parentFailure = parentSafetyFailure(event, ctx);
+                    if (parentFailure !== undefined)
+                        return {
+                            type: 'error',
+                            output: parentFailure,
+                        };
+                }
+                if (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)
+                    return {
+                        type: 'error',
+                        output: `Pi transcript and SQLite workflow state disagree for session ${sessionId}.`,
+                    };
+                const repository = getRepositoryName(ctx.cwd);
+                if (repository === undefined)
+                    return {
+                        type: 'error',
+                        output: 'repository must be a non-empty string.',
+                    };
+                return engine.startSession(sessionId, sessionFile, repository);
+            });
+            if (result.type !== 'success')
+                return result.output;
+            if (result.output !== '') {
+                pi.sendMessage({
+                    customType: 'deterministic-agent-workflow',
+                    content: result.output,
+                    display: true,
+                }, { triggerTurn: false });
+            }
+            return undefined;
+        }
+        catch (error) {
+            return String(error);
+        }
+    }
+    function runRoute(ctx, args) {
+        const notReady = readinessFailure(ctx);
+        if (notReady !== undefined)
+            return {
+                output: notReady,
+                exitCode: 1,
+            };
+        const session = readSessionId(ctx);
+        if (!session.ok)
+            return {
+                output: session.reason,
+                exitCode: 1,
+            };
+        try {
+            return useEngine(ctx, (_engine, engineDeps, workflowDeps) => runner(args, engineDeps, workflowDeps, {
+                getSessionId: () => session.sessionId,
+                getSessionTranscriptPath: () => requireSessionFile(ctx),
+                getSessionRepository: () => getRepositoryName(ctx.cwd),
+                getRepositoryRoot: () => ctx.cwd,
+                getWorkflowEventsDbPath: () => databasePath,
+            }));
+        }
+        catch (error) {
+            return {
+                output: markInitializationFailed(ctx, session.sessionId, `Workflow operation could not establish safe state: ${String(error)}`),
+                exitCode: 1,
+            };
+        }
+    }
+    return (pi) => {
+        pi.on('session_start', (event, ctx) => {
+            const session = readSessionId(ctx);
+            if (!session.ok) {
+                ctx.ui.notify(`Pi workflow initialization failed: ${session.reason}`, 'error');
+                ctx.shutdown();
+                return;
+            }
+            initializationBySession.set(session.sessionId, { type: 'initializing' });
+            const failure = initializeSession(event, ctx, pi, session.sessionId);
+            if (failure !== undefined) {
+                markInitializationFailed(ctx, session.sessionId, failure);
+                return;
+            }
+            initializationBySession.set(session.sessionId, { type: 'ready' });
+        });
+        pi.on('tool_call', (event, ctx) => {
+            const notReady = readinessFailure(ctx);
+            if (notReady !== undefined)
+                return {
+                    block: true,
+                    reason: notReady,
+                };
+            const session = readSessionId(ctx);
+            if (!session.ok)
+                return {
+                    block: true,
+                    reason: session.reason,
+                };
+            try {
+                const result = useEngine(ctx, (engine) => preToolUse(engine, session.sessionId, event.toolName, { ...event.input }));
+                if (result.type === 'success')
+                    return;
+                return {
+                    block: true,
+                    reason: result.output,
+                };
+            }
+            catch (error) {
+                return {
+                    block: true,
+                    reason: markInitializationFailed(ctx, session.sessionId, `Tool safety could not be established: ${String(error)}`),
+                };
+            }
+        });
+        pi.on('input', (_event, ctx) => {
+            const notReady = readinessFailure(ctx);
+            if (notReady === undefined)
+                return;
+            ctx.ui.notify(notReady, 'error');
+            return { action: 'handled' };
+        });
+        pi.on('agent_settled', (_event, ctx) => {
+            if (readinessFailure(ctx) !== undefined)
+                return;
+            const session = readSessionId(ctx);
+            if (!session.ok)
+                return;
+            const settlement = getLatestPiAssistantSettlement(ctx.sessionManager.getBranch());
+            if (settlement?.stopReason !== 'stop')
+                return;
+            if (recoveredAssistantBySession.get(session.sessionId) === settlement.id)
+                return;
+            try {
+                const result = useEngine(ctx, (engine) => engine.checkStopping(session.sessionId, 'stop'));
+                if (result.type === 'blocked' && ctx.isIdle() && !ctx.hasPendingMessages()) {
+                    recoveredAssistantBySession.set(session.sessionId, settlement.id);
+                    pi.sendUserMessage(PI_IDLE_RECOVERY_MESSAGE);
+                }
+            }
+            catch (error) {
+                markInitializationFailed(ctx, session.sessionId, `Stopping safety could not be established: ${String(error)}`);
+            }
+        });
+        const blockSessionBranching = (ctx) => {
+            const session = readSessionId(ctx);
+            if (!session.ok) {
+                ctx.ui.notify(`${INITIALIZATION_PENDING_REASON} ${session.reason}`, 'error');
+                ctx.shutdown();
+                return { cancel: true };
+            }
+            const notReady = readinessFailure(ctx);
+            if (notReady !== undefined) {
+                markInitializationFailed(ctx, session.sessionId, notReady);
+                return { cancel: true };
+            }
+            ctx.ui.notify(PI_SESSION_BRANCH_BLOCK_MESSAGE, 'warning');
+            return { cancel: true };
+        };
+        pi.on('session_before_tree', (_event, ctx) => blockSessionBranching(ctx));
+        pi.on('session_before_fork', (_event, ctx) => blockSessionBranching(ctx));
+        pi.registerTool({
+            name: toolName,
+            label: 'Workflow',
+            description: 'Execute a deterministic workflow operation such as init, transition, or record-*.',
+            promptSnippet: `Execute deterministic workflow operations with ${toolName}.`,
+            parameters: workflowToolParameters,
+            executionMode: 'sequential',
+            async execute(_toolCallId, parameters, _signal, _onUpdate, ctx) {
+                const result = runRoute(ctx, [parameters.operation, ...(parameters.args ?? [])]);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: result.output,
+                        }],
+                    details: { exitCode: result.exitCode },
+                    isError: result.exitCode !== 0,
+                };
+            },
+        });
+        pi.registerCommand(commandName, {
+            description: `Execute a deterministic workflow operation: /${commandName} <operation> [args]`,
+            handler: async (rawArguments, ctx) => {
+                try {
+                    const result = runRoute(ctx, parsePiCommandArguments(rawArguments));
+                    notifyRouteResult(ctx, pi, result);
+                }
+                catch (error) {
+                    ctx.ui.notify(String(error), 'error');
+                }
+            },
+        });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createPiWorkflowExtension, PI_IDLE_RECOVERY_MESSAGE, PI_SESSION_BRANCH_BLOCK_MESSAGE, } from './features/pi-extension/entrypoint/pi-workflow-extension.js';
+export { PiTranscriptReader } from './platform/infra/external-clients/pi/pi-transcript-reader.js';

package/dist/platform/domain/pi-command-argument-error.d.ts

@@ -0,0 +1,4 @@
+/** @riviere-role domain-error */
+export declare class PiCommandArgumentError extends TypeError {
+    constructor(message: string);
+}

package/dist/platform/domain/pi-command-argument-error.js

@@ -0,0 +1,7 @@
+/** @riviere-role domain-error */
+export class PiCommandArgumentError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = 'PiCommandArgumentError';
+    }
+}

package/dist/platform/domain/pi-command-arguments.d.ts

@@ -0,0 +1,2 @@
+/** @riviere-role domain-service */
+export declare function parsePiCommandArguments(input: string): readonly string[];

package/dist/platform/domain/pi-command-arguments.js

@@ -0,0 +1,61 @@
+import { PiCommandArgumentError } from './pi-command-argument-error.js';
+function nextState(state, character) {
+    if (state.escaping)
+        return {
+            ...state,
+            current: `${state.current}${character}`,
+            escaping: false,
+        };
+    if (character === '\\')
+        return {
+            ...state,
+            escaping: true,
+            tokenStarted: true,
+        };
+    if (state.quote !== undefined)
+        return character === state.quote
+            ? {
+                ...state,
+                quote: undefined,
+            }
+            : {
+                ...state,
+                current: `${state.current}${character}`,
+            };
+    if (character === '"' || character === "'")
+        return {
+            ...state,
+            quote: character,
+            tokenStarted: true,
+        };
+    if (/\s/.test(character))
+        return state.tokenStarted
+            ? {
+                tokens: [...state.tokens, state.current],
+                current: '',
+                quote: undefined,
+                escaping: false,
+                tokenStarted: false,
+            }
+            : state;
+    return {
+        ...state,
+        current: `${state.current}${character}`,
+        tokenStarted: true,
+    };
+}
+/** @riviere-role domain-service */
+export function parsePiCommandArguments(input) {
+    const parsed = [...input].reduce(nextState, {
+        tokens: [],
+        current: '',
+        quote: undefined,
+        escaping: false,
+        tokenStarted: false,
+    });
+    if (parsed.quote !== undefined)
+        throw new PiCommandArgumentError(`Unmatched ${parsed.quote} quote in workflow command arguments.`);
+    if (parsed.escaping)
+        throw new PiCommandArgumentError('Workflow command arguments end with an unmatched escape character.');
+    return parsed.tokenStarted ? [...parsed.tokens, parsed.current] : parsed.tokens;
+}

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

@@ -0,0 +1,32 @@
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+import type { BaseWorkflowState, RehydratableWorkflow, 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: 'initializing';
+} | {
+    readonly type: 'ready';
+} | {
+    readonly type: 'failed';
+    readonly reason: string;
+};
+/** @riviere-role value-object */
+export type PiSessionIdResult = {
+    readonly ok: true;
+    readonly sessionId: string;
+} | {
+    readonly ok: false;
+    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>;
+    readonly routes: RouteMap<TWorkflow, TState>;
+    readonly buildWorkflowDeps: (platform: PlatformContext) => TDeps;
+    readonly pluginRoot: string;
+    readonly databasePath?: string;
+    readonly commandName?: string;
+    readonly toolName?: string;
+};

package/dist/platform/domain/pi-workflow-extension-types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/infra/external-clients/pi/pi-session-file-error.d.ts

@@ -0,0 +1,4 @@
+/** @riviere-role external-client-error */
+export declare class PiSessionFileError extends TypeError {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/platform/infra/external-clients/pi/pi-session-file-error.js

@@ -0,0 +1,7 @@
+/** @riviere-role external-client-error */
+export class PiSessionFileError extends TypeError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'PiSessionFileError';
+    }
+}

package/dist/platform/infra/external-clients/pi/pi-session-file.d.ts

@@ -0,0 +1,13 @@
+import type { SessionEntry } from '@earendil-works/pi-coding-agent';
+export declare const PI_WORKFLOW_MARKER_CUSTOM_TYPE = "deterministic-agent-workflow";
+/** @riviere-role external-client-model */
+export type PiSessionMetadata = {
+    readonly id: string;
+    readonly hasWorkflowMarker: boolean;
+};
+/** @riviere-role external-client-service */
+export declare function hasPiWorkflowMarker(entries: readonly SessionEntry[]): boolean;
+/** @riviere-role external-client-service */
+export declare function readPiSessionMetadata(filePath: string): PiSessionMetadata;
+/** @riviere-role external-client-service */
+export declare function readPiSessionId(filePath: string): string;

package/dist/platform/infra/external-clients/pi/pi-session-file.js

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { PiSessionFileError } from './pi-session-file-error.js';
+const MAX_ENTRY_BYTES = 1024 * 1024;
+export const PI_WORKFLOW_MARKER_CUSTOM_TYPE = 'deterministic-agent-workflow';
+function parseEntry(entryText, filePath, lineNumber) {
+    if (Buffer.byteLength(entryText) > MAX_ENTRY_BYTES) {
+        throw new PiSessionFileError(`Pi session entry at line ${lineNumber} exceeds ${MAX_ENTRY_BYTES} bytes: ${filePath}`);
+    }
+    if (entryText.trim().length === 0) {
+        const detail = lineNumber === 1 ? 'an empty header' : `an empty entry at line ${lineNumber}`;
+        throw new PiSessionFileError(`Pi session file has ${detail}: ${filePath}`);
+    }
+    try {
+        const entry = JSON.parse(entryText);
+        if (typeof entry !== 'object' || entry === null || !('type' in entry) || typeof entry.type !== 'string') {
+            throw new PiSessionFileError(`Pi session file has an invalid entry at line ${lineNumber}: ${filePath}`);
+        }
+        return entry;
+    }
+    catch (error) {
+        if (error instanceof PiSessionFileError)
+            throw error;
+        throw new PiSessionFileError(`Cannot parse Pi session entry at line ${lineNumber}: ${filePath}`, { cause: error });
+    }
+}
+function readEntries(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    const serializedEntries = content.endsWith('\n') ? content.slice(0, -1).split('\n') : content.split('\n');
+    return serializedEntries.map((entry, index) => parseEntry(entry, filePath, index + 1));
+}
+function requireSessionId(header, filePath) {
+    if (header.type !== 'session')
+        throw new PiSessionFileError(`Pi session file does not begin with a session header: ${filePath}`);
+    if (typeof header.id !== 'string' || header.id.trim().length === 0) {
+        throw new PiSessionFileError(`Pi session header has no valid session UUID: ${filePath}`);
+    }
+    return header.id;
+}
+function isWorkflowMarker(entry) {
+    return entry.type === 'custom_message' && entry.customType === PI_WORKFLOW_MARKER_CUSTOM_TYPE;
+}
+/** @riviere-role external-client-service */
+export function hasPiWorkflowMarker(entries) {
+    return entries.some((entry) => entry.type === 'custom_message' && entry.customType === PI_WORKFLOW_MARKER_CUSTOM_TYPE);
+}
+/** @riviere-role external-client-service */
+export function readPiSessionMetadata(filePath) {
+    try {
+        const [header, ...entries] = readEntries(filePath);
+        return {
+            id: requireSessionId(header, filePath),
+            hasWorkflowMarker: entries.some(isWorkflowMarker),
+        };
+    }
+    catch (error) {
+        if (error instanceof PiSessionFileError)
+            throw error;
+        throw new PiSessionFileError(`Cannot read Pi session file: ${filePath}`, { cause: error });
+    }
+}
+/** @riviere-role external-client-service */
+export function readPiSessionId(filePath) {
+    return readPiSessionMetadata(filePath).id;
+}

package/dist/platform/infra/external-clients/pi/pi-transcript-reader.d.ts

@@ -0,0 +1,15 @@
+import type { SessionEntry } from '@earendil-works/pi-coding-agent';
+import type { TranscriptMessage, TranscriptReader } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+/** @riviere-role external-client-model */
+export type PiAssistantSettlement = {
+    readonly id: string;
+    readonly stopReason: string;
+};
+/** @riviere-role external-client-service */
+export declare function getLatestPiAssistantSettlement(entries: readonly SessionEntry[]): PiAssistantSettlement | undefined;
+/** @riviere-role external-client-model */
+export declare class PiTranscriptReader implements TranscriptReader {
+    private readonly getBranch;
+    constructor(getBranch: () => readonly SessionEntry[]);
+    readMessages(): readonly TranscriptMessage[];
+}

package/dist/platform/infra/external-clients/pi/pi-transcript-reader.js

@@ -0,0 +1,32 @@
+/** @riviere-role external-client-service */
+export function getLatestPiAssistantSettlement(entries) {
+    const entry = entries.findLast((candidate) => candidate.type === 'message' && candidate.message.role === 'assistant');
+    if (entry?.type !== 'message' || entry.message.role !== 'assistant')
+        return undefined;
+    return {
+        id: entry.id,
+        stopReason: entry.message.stopReason,
+    };
+}
+/** @riviere-role external-client-model */
+export class PiTranscriptReader {
+    getBranch;
+    constructor(getBranch) {
+        this.getBranch = getBranch;
+    }
+    readMessages() {
+        return this.getBranch().flatMap((entry) => {
+            if (entry.type !== 'message' || entry.message.role !== 'assistant')
+                return [];
+            const text = entry.message.content
+                .filter((content) => content.type === 'text')
+                .map((content) => content.text)
+                .join('\n')
+                .trim();
+            return [{
+                    id: entry.id,
+                    textContent: text.length === 0 ? undefined : text,
+                }];
+        });
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nt-ai-lab/deterministic-agent-workflow-pi",
+  "version": "0.4.3",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NTCoding/deterministic-agent-workflows.git",
+    "directory": "packages/deterministic-agent-workflows-pi"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "vitest": "^2.1.9",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}