praxis-agent 0.55.0 → 0.55.1

package/README.md

@@ -347,7 +347,7 @@ normal/low-capability full-frame p95 budgets of `<16.7/<33 ms`.
 `npm run test:coverage` measures all production code under `src/**` with V8 and
 enforces global floors of 79% statements, 70% branches, 85% functions, and 81% lines,
 and rejects any production runtime module with zero covered statements (while allowing
-type-only modules). `npm run test:fixtures` executes the 70-behavior native contract; 62 behaviors
+type-only modules). `npm run test:fixtures` executes the 71-behavior native contract; 63 behaviors
 are qualified and 8 are explicitly excluded. `npm run verify:fixture-contracts`
 performs the structural check and is part of `npm run check`.
 `npm run test:core-completion` is retained as a compatibility alias for

package/dist/application/context-engine.js

@@ -1,5 +1,6 @@
 import { AgentRunCancelledError, } from '../core/runtime.js';
 import { contextRecoveryMadeProgress, isPromptTooLongError, } from '../core/context-budget.js';
+import { StaleContextGenerationError } from './context-preparation.js';
 function assertSignal(signal) {
     if (signal?.aborted)
         throw new AgentRunCancelledError();
@@ -95,7 +96,9 @@ export class ContextEngine {
             return { kind: 'retry', envelope: proposal.envelope };
         }
         catch (cause) {
-            if (signal?.aborted || cause instanceof AgentRunCancelledError)
+            if (signal?.aborted ||
+                cause instanceof AgentRunCancelledError ||
+                cause instanceof StaleContextGenerationError)
                 throw cause;
             return { kind: 'exhausted', error };
         }

package/dist/application/context-preparation.d.ts

@@ -0,0 +1,60 @@
+import { type ContextAssembler, type ContextAssemblyOptions } from '../core/context.js';
+import type { ModelMessage, ModelToolDefinition } from '../core/runtime.js';
+import type { ContextEnvelope } from './context-engine.js';
+export interface ContextPreparationProjection {
+    readonly generation: number;
+    readonly envelope: ContextEnvelope;
+    readonly stableSystemMessageCount: number;
+}
+export interface ContextPreparationSources {
+    readonly history: () => readonly ModelMessage[];
+    readonly memory: () => readonly ModelMessage[];
+    readonly activeTools: () => readonly ModelToolDefinition[];
+}
+export interface ContextPreparationProjectOptions {
+    readonly includeHistory?: boolean;
+    readonly includeMemory?: boolean;
+    readonly pendingMessages?: readonly ModelMessage[];
+}
+export interface ContextHistoryReplacement {
+    readonly generation: number;
+    readonly envelope: ContextEnvelope;
+    readonly stableSystemMessageCount: number;
+    commit<T>(replace: () => Promise<T>): Promise<{
+        generation: number;
+        value: T;
+    }>;
+}
+export declare class StaleContextGenerationError extends Error {
+    readonly expectedGeneration: number;
+    readonly actualGeneration: number;
+    constructor(expectedGeneration: number, actualGeneration: number);
+}
+export interface ContextPreparationOptions {
+    readonly assembler?: ContextAssembler;
+    readonly sources: ContextPreparationSources;
+    readonly agentMentions?: () => {
+        readonly prompt: string;
+        readonly messages: readonly string[];
+    };
+    readonly initialGeneration?: number;
+}
+/** Owns provider-visible context projection and guarded history replacement. */
+export declare class ContextPreparation {
+    private readonly assembler;
+    private readonly sources;
+    private readonly agentMentions;
+    private generation;
+    private prepared;
+    private replacementQueue;
+    constructor(options: ContextPreparationOptions);
+    refresh(options?: ContextAssemblyOptions): Promise<void>;
+    project(options?: ContextPreparationProjectOptions): ContextPreparationProjection;
+    proposeHistoryReplacement(input: {
+        readonly historyMessages: readonly ModelMessage[];
+        readonly pendingMessages?: readonly ModelMessage[];
+    }): ContextHistoryReplacement;
+    private projectWithMessages;
+    private decorate;
+}
+//# sourceMappingURL=context-preparation.d.ts.map

package/dist/application/context-preparation.js

@@ -0,0 +1,139 @@
+import { injectFirstUserMessageContext, projectContextSnapshot, } from '../core/context.js';
+import { assembleContextSnapshot } from '../core/prompt-composer.js';
+export class StaleContextGenerationError extends Error {
+    expectedGeneration;
+    actualGeneration;
+    constructor(expectedGeneration, actualGeneration) {
+        super(`Stale context generation: expected ${expectedGeneration}, actual ${actualGeneration}; prepare a new history replacement`);
+        this.name = 'StaleContextGenerationError';
+        this.expectedGeneration = expectedGeneration;
+        this.actualGeneration = actualGeneration;
+    }
+}
+function validateGeneration(generation) {
+    if (!Number.isSafeInteger(generation) || generation < 1) {
+        throw new TypeError('Context generation must be a positive safe integer');
+    }
+}
+function cloneTools(tools) {
+    return tools.map((tool) => ({ ...tool }));
+}
+/** Owns provider-visible context projection and guarded history replacement. */
+export class ContextPreparation {
+    assembler;
+    sources;
+    agentMentions;
+    generation;
+    prepared;
+    replacementQueue = Promise.resolve();
+    constructor(options) {
+        this.assembler = options.assembler;
+        this.sources = options.sources;
+        this.agentMentions = options.agentMentions;
+        this.generation = options.initialGeneration ?? 1;
+        validateGeneration(this.generation);
+    }
+    async refresh(options = {}) {
+        const snapshot = await assembleContextSnapshot(this.assembler, options);
+        const projection = projectContextSnapshot(snapshot);
+        const stableCount = projection.stableSystemSectionCount;
+        const prepared = {
+            stableSystemMessages: projection.systemMessages.slice(0, stableCount),
+            volatileSystemMessages: projection.systemMessages.slice(stableCount),
+            ...(projection.firstUserMessageContext === undefined
+                ? {}
+                : { firstUserMessageContext: projection.firstUserMessageContext }),
+            stableSystemMessageCount: stableCount,
+        };
+        this.prepared = prepared;
+    }
+    project(options = {}) {
+        return this.projectWithMessages((options.includeHistory ?? true) ? this.sources.history() : [], (options.includeMemory ?? true) ? this.sources.memory() : [], options.pendingMessages ?? []);
+    }
+    proposeHistoryReplacement(input) {
+        const baseGeneration = this.generation;
+        if (baseGeneration === Number.MAX_SAFE_INTEGER) {
+            throw new RangeError('Context generation cannot exceed Number.MAX_SAFE_INTEGER');
+        }
+        const generation = baseGeneration + 1;
+        const projection = this.projectWithMessages(input.historyMessages, [], input.pendingMessages ?? []);
+        let committed = false;
+        return {
+            generation,
+            envelope: projection.envelope,
+            stableSystemMessageCount: projection.stableSystemMessageCount,
+            commit: async (replace) => {
+                const operation = this.replacementQueue.then(async () => {
+                    if (this.generation !== baseGeneration) {
+                        throw new StaleContextGenerationError(baseGeneration, this.generation);
+                    }
+                    if (committed) {
+                        throw new StaleContextGenerationError(baseGeneration, this.generation);
+                    }
+                    const value = await replace();
+                    this.generation = generation;
+                    committed = true;
+                    return { generation, value };
+                });
+                this.replacementQueue = operation.then(() => undefined, () => undefined);
+                return operation;
+            },
+        };
+    }
+    projectWithMessages(historyMessages, memoryMessages, pendingMessages) {
+        const prepared = this.prepared;
+        if (!prepared) {
+            throw new Error('ContextPreparation must be refreshed before projecting');
+        }
+        const history = [...historyMessages];
+        const memory = [...memoryMessages];
+        const pending = [...pendingMessages];
+        const decoratedHistory = this.decorate([...history, ...memory, ...pending]);
+        const messages = [
+            ...prepared.stableSystemMessages,
+            ...prepared.volatileSystemMessages,
+            ...decoratedHistory,
+        ];
+        return {
+            generation: this.generation,
+            envelope: {
+                messages,
+                tools: cloneTools(this.sources.activeTools()),
+            },
+            stableSystemMessageCount: prepared.stableSystemMessageCount,
+        };
+    }
+    decorate(messages) {
+        const prepared = this.prepared;
+        if (!prepared) {
+            throw new Error('ContextPreparation must be refreshed before projecting');
+        }
+        const withFirstUserContext = injectFirstUserMessageContext(messages, prepared.firstUserMessageContext);
+        const mentionInput = this.agentMentions?.();
+        if (!mentionInput || mentionInput.messages.length === 0)
+            return withFirstUserContext;
+        let insertionIndex = withFirstUserContext.length;
+        let foundPrompt = false;
+        for (let index = withFirstUserContext.length - 1; index >= 0; index -= 1) {
+            const message = withFirstUserContext[index];
+            if (message?.role === 'user' &&
+                typeof message.content === 'string' &&
+                message.content.endsWith(mentionInput.prompt)) {
+                insertionIndex = index;
+                foundPrompt = true;
+                break;
+            }
+        }
+        if (!foundPrompt)
+            return withFirstUserContext;
+        return [
+            ...withFirstUserContext.slice(0, insertionIndex),
+            ...mentionInput.messages.map((content) => ({
+                role: 'user',
+                content,
+            })),
+            ...withFirstUserContext.slice(insertionIndex),
+        ];
+    }
+}
+//# sourceMappingURL=context-preparation.js.map

package/dist/application/session-service.d.ts

@@ -236,7 +236,7 @@ export declare class ClaudeSessionService {
     private readonly hookLifecycle;
     private readonly leadOperations;
     private readonly fileChangeWatcher;
-    private readonly activeTurnInputs;
+    private readonly turnCoordinator;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;

package/dist/application/session-service.js

@@ -21,9 +21,9 @@ import { BackgroundTaskRuntime, } from './background-task-runtime.js';
 import { backgroundAgentNotificationMarkers, } from './background-agent-manager.js';
 import { usageCostUsd } from '../core/usage.js';
 import { isSessionId } from '../core/session.js';
-import { ActiveTurnInputMailbox, } from '../core/active-turn-input.js';
 import { ContextBudget, estimateModelRequestTokens, isPromptTooLongError, } from '../core/context-budget.js';
 import { ContextEngine } from './context-engine.js';
+import { ContextPreparation } from './context-preparation.js';
 import { TurnMemoryCoordinator } from './turn-memory-coordinator.js';
 import { injectFirstUserMessageContext, projectContextSnapshot, } from '../core/context.js';
 import { assembleContextSnapshot } from '../core/prompt-composer.js';
@@ -38,7 +38,7 @@ import { SubagentLifecycleStore } from '../persistence/subagent-lifecycle-store.
 import { ModelCompactor } from './model-compactor.js';
 import { agentMemoryPrompt, ClaudeSubagentExecutor, StructuredOutputRegistry, } from './subagent-service.js';
 import { ScheduledPromptManager, } from './scheduled-prompt-manager.js';
-import { TurnTerminalController } from './turn-lifecycle.js';
+import { TurnCoordinator } from './turn-lifecycle.js';
 import { ClaudeScheduledToolRegistry } from '../tools/claude-scheduled-tools.js';
 import { ClaudeTaskToolRegistry } from '../tools/claude-task-tools.js';
 import { ClaudeWorkflowToolRegistry } from '../tools/claude-workflow-tools.js';
@@ -684,12 +684,16 @@ export class ClaudeSessionService {
     hookLifecycle;
     leadOperations;
     fileChangeWatcher;
-    activeTurnInputs = new Map();
+    turnCoordinator;
     runtimeCwd;
     constructor(options) {
         const dataPlane = options.dataPlane ?? 'native';
         assertNativeDataPlane(dataPlane);
         this.options = { ...options, dataPlane };
+        this.turnCoordinator = new TurnCoordinator({
+            eventSink: options.eventSink ?? (() => undefined),
+            createSteeringId: randomUUID,
+        });
         this.assertNativeTranscriptOptions();
         this.leadOperations = options.teamLeadOperations ?? null;
         this.hookLifecycle = new HookLifecycle(options.hooks, options.eventSink);
@@ -899,18 +903,7 @@ export class ClaudeSessionService {
     }
     async close() {
         this.closing = true;
-        for (const { mailbox } of this.activeTurnInputs.values()) {
-            if (!mailbox)
-                continue;
-            for (const item of mailbox.close()) {
-                this.options.eventSink?.({
-                    type: 'user-input-rejected',
-                    id: item.id,
-                    content: item.content,
-                    reason: 'closed',
-                });
-            }
-        }
+        this.turnCoordinator.close();
         await this.fileChangeWatcher?.close(5_000);
         await this.hookLifecycle.close();
         await this.drainDetachedHookRuns(5_000);
@@ -1330,28 +1323,10 @@ export class ClaudeSessionService {
         });
     }
     steer(sessionId, content) {
-        const active = this.activeTurnInputs.get(sessionId);
-        if (!active)
-            return { kind: 'no-active-turn' };
-        const mailbox = active.mailbox;
-        if (!mailbox)
-            return { kind: 'not-steerable' };
-        const result = mailbox.enqueue(content);
-        if (result.kind === 'accepted')
-            return result;
-        if (result.kind === 'empty')
-            return result;
-        return { kind: 'turn-completing' };
+        return this.turnCoordinator.steer(sessionId, content);
     }
     withdrawSteering(sessionId, id) {
-        const active = this.activeTurnInputs.get(sessionId);
-        if (!active)
-            return { kind: 'no-active-turn' };
-        const mailbox = active.mailbox;
-        if (!mailbox)
-            return { kind: 'not-steerable' };
-        const result = mailbox.withdraw(id);
-        return result.kind === 'withdrawn' ? result : { kind: 'not-pending' };
+        return this.turnCoordinator.withdrawSteering(sessionId, id);
     }
     async resumeShell(sessionId, command, signal, name, resumeSessionAt) {
         this.worktreeManager?.bindSession(sessionId);
@@ -2535,29 +2510,8 @@ export class ClaudeSessionService {
         const documents = submission.kind === 'prompt' ? (submission.documents ?? []) : [];
         const shellCommand = submission.kind === 'shell' ? submission.command : undefined;
         const skipUserPrompt = submission.kind === 'retry';
-        const controller = new TurnTerminalController(this.options.eventSink ?? (() => undefined));
-        let activeTurnInput;
-        let activeTurnRecord;
-        try {
+        return this.turnCoordinator.run(request, async ({ emit, steering }) => {
             this.assertTurnWritable();
-            if (prompt.length === 0 && images.length === 0 && documents.length === 0)
-                throw new Error('Prompt must not be empty');
-            if (name !== undefined && name.length === 0) {
-                throw new Error('Session name must not be empty');
-            }
-            if (shellCommand !== undefined && shellCommand.trim().length === 0) {
-                throw new Error('Shell command must not be empty');
-            }
-            if (this.activeTurnInputs.has(sessionId)) {
-                throw new Error(`conflict: locked (session ${sessionId} already has an active turn)`);
-            }
-            activeTurnRecord =
-                shellCommand === undefined
-                    ? {
-                        mailbox: (activeTurnInput = new ActiveTurnInputMailbox(randomUUID)),
-                    }
-                    : {};
-            this.activeTurnInputs.set(sessionId, activeTurnRecord);
             await this.activateSessionCostTracker(sessionId);
             await this.ensureFileResources(sessionId, signal);
             this.worktreeManager?.bindSession(sessionId);
@@ -3071,7 +3025,7 @@ export class ClaudeSessionService {
                         deferPreToolUseOutcome: (call) => pendingRecoveryToolCallIds.has(call.id),
                     })
                     : null;
-                const runtime = new AgentRuntime(provider, controller.emit, {
+                const runtime = new AgentRuntime(provider, emit, {
                     emitInitialContextState: false,
                     ...(this.options.emitToolUseSummaries
                         ? {
@@ -3413,19 +3367,30 @@ export class ClaudeSessionService {
                     let agentSystem = null;
                     let planModeMessage;
                     let sessionMemoryMessage = null;
-                    let contextMessages = [];
-                    let contextProjection = {
-                        systemMessages: [],
-                        stableSystemSectionCount: 0,
-                    };
-                    let stableSystemMessageCount = 0;
+                    let agentMentionMessages = [];
+                    const contextPreparation = new ContextPreparation({
+                        ...(this.options.contextAssembler
+                            ? { assembler: this.options.contextAssembler }
+                            : {}),
+                        sources: {
+                            history: activeTurnMessages,
+                            memory: () => projectMemoryRecallMessages,
+                            activeTools: () => provider.capabilities.tools
+                                ? (activeTurnTools?.definitions() ?? [])
+                                : [],
+                        },
+                        agentMentions: () => ({
+                            prompt: effectivePrompt,
+                            messages: agentMentionMessages,
+                        }),
+                    });
                     refreshRuntimeContext = async () => {
                         agentSystem = await this.mainAgentSystemPrompt(agent);
                         planModeMessage =
                             this.options.interactiveTools?.contextMessage(sessionId);
                         // DEBUG_PLAN_CONTEXT
                         sessionMemoryMessage = this.sessionMemoryMessage(await turnMemory.sessionSummary());
-                        const assembledContext = await assembleContextSnapshot(this.options.contextAssembler, {
+                        await contextPreparation.refresh({
                             cwd: this.activeCwd(),
                             lifecycleId: sessionId,
                             ...(agentSystem
@@ -3442,10 +3407,6 @@ export class ClaudeSessionService {
                                     : {}),
                             },
                         });
-                        contextProjection = projectContextSnapshot(assembledContext);
-                        stableSystemMessageCount =
-                            contextProjection.stableSystemSectionCount;
-                        contextMessages = [...contextProjection.systemMessages];
                     };
                     await refreshRuntimeContext();
                     const expansion = shouldSkipUserPrompt()
@@ -3475,9 +3436,6 @@ export class ClaudeSessionService {
                     let compactionDurationMs;
                     let compactionDurationWithoutRetriesMs;
                     let compactionModelUsage;
-                    const currentDefinitions = () => provider.capabilities.tools
-                        ? (activeTurnTools?.definitions() ?? [])
-                        : [];
                     const budget = this.contextBudget(provider);
                     const contextEngine = new ContextEngine({
                         ...(budget ? { budget } : {}),
@@ -3509,88 +3467,50 @@ export class ClaudeSessionService {
                             ? { documents }
                             : {}),
                     }));
-                    const agentMentionMessages = shellCommand === undefined && !shouldSkipUserPrompt()
-                        ? (this.options.extensions?.agentMentionMessages(effectivePrompt) ?? [])
-                        : [];
-                    const injectAgentMentionContext = (messages) => {
-                        if (agentMentionMessages.length === 0)
-                            return [...messages];
-                        let insertionIndex = messages.length;
-                        let foundPrompt = false;
-                        for (let index = messages.length - 1; index >= 0; index -= 1) {
-                            const message = messages[index];
-                            if (message?.role === 'user' &&
-                                typeof message.content === 'string' &&
-                                message.content.endsWith(effectivePrompt)) {
-                                insertionIndex = index;
-                                foundPrompt = true;
-                                break;
-                            }
-                        }
-                        if (!foundPrompt)
-                            return [...messages];
-                        return [
-                            ...messages.slice(0, insertionIndex),
-                            ...agentMentionMessages.map((content) => ({
-                                role: 'user',
-                                content,
-                            })),
-                            ...messages.slice(insertionIndex),
-                        ];
-                    };
-                    const injectDynamicContext = (messages) => injectFirstUserMessageContext(messages, contextProjection.firstUserMessageContext);
-                    const injectTurnContext = (messages) => injectAgentMentionContext(injectDynamicContext(messages));
+                    agentMentionMessages =
+                        shellCommand === undefined && !shouldSkipUserPrompt()
+                            ? (this.options.extensions?.agentMentionMessages(effectivePrompt) ?? [])
+                            : [];
                     let compactionAnchorUuid = this.lastMessageUuid(snapshot.entries);
                     const contextTransitionPort = (pendingMessages = [], preservedUserMessages = []) => ({
                         current: () => {
-                            const historyMessages = [
-                                ...activeTurnMessages(),
-                                ...projectMemoryRecallMessages,
-                            ];
-                            return {
-                                messages: [
-                                    ...contextMessages,
-                                    ...injectTurnContext([
-                                        ...historyMessages,
-                                        ...pendingMessages,
-                                    ]),
-                                ],
-                                tools: currentDefinitions(),
-                            };
+                            const projection = contextPreparation.project({
+                                pendingMessages,
+                            });
+                            return projection.envelope;
                         },
-                        irreducible: () => ({
-                            messages: [
-                                ...contextMessages,
-                                ...injectTurnContext([
-                                    ...pendingMessages,
-                                    ...preservedUserMessages.map((content) => ({
-                                        role: 'user',
-                                        content,
-                                    })),
-                                ]),
+                        irreducible: () => contextPreparation.project({
+                            includeHistory: false,
+                            includeMemory: false,
+                            pendingMessages: [
+                                ...pendingMessages,
+                                ...preservedUserMessages.map((content) => ({
+                                    role: 'user',
+                                    content,
+                                })),
                             ],
-                            tools: currentDefinitions(),
-                        }),
+                        }).envelope,
                         propose: async () => {
                             const activeNativeLease = nativeLease;
                             if (!budget)
                                 throw new Error('Context budget is unavailable');
-                            const definitions = currentDefinitions();
+                            const definitions = contextPreparation.project().envelope.tools;
                             const historyMessages = activeTurnMessages();
                             if (historyMessages.length === 0)
                                 throw new Error('Cannot compact an empty native transcript');
                             if (unresolvedActiveToolCallIds(historyMessages).length > 0)
                                 throw new Error('Cannot compact a native transcript with unresolved tool calls');
-                            const irreducibleMessages = [
-                                ...contextMessages,
-                                ...injectTurnContext([
+                            const irreducibleMessages = contextPreparation.project({
+                                includeHistory: false,
+                                includeMemory: false,
+                                pendingMessages: [
                                     ...pendingMessages,
                                     ...preservedUserMessages.map((content) => ({
                                         role: 'user',
                                         content,
                                     })),
-                                ]),
-                            ];
+                                ],
+                            }).envelope.messages;
                             let compactableMessages = historyMessages;
                             let preservedMessages = [];
                             let compactionLogicalParentId;
@@ -3757,14 +3677,15 @@ export class ClaudeSessionService {
                             };
                             let replayMessages = preservedMessages;
                             try {
-                                const replayReport = budget.evaluate([
-                                    ...contextMessages,
-                                    ...injectTurnContext([
+                                const replayReport = budget.evaluate(contextPreparation.project({
+                                    includeHistory: false,
+                                    includeMemory: false,
+                                    pendingMessages: [
                                         summaryMessage,
                                         ...replayMessages,
                                         ...pendingMessages,
-                                    ]),
-                                ], definitions);
+                                    ],
+                                }).envelope.messages, definitions);
                                 if (replayReport.shouldCompact)
                                     throw new Error('replay overflow');
                             }
@@ -3775,23 +3696,16 @@ export class ClaudeSessionService {
                                 // contains its contents and user prompts remain available.
                                 replayMessages = replayMessages.filter((message) => message.role === 'user' && !Array.isArray(message.content));
                             }
-                            const proposedMessages = [
-                                ...contextMessages,
-                                ...injectTurnContext([
-                                    summaryMessage,
-                                    ...replayMessages,
-                                    ...pendingMessages,
-                                ]),
-                            ];
+                            const replacement = contextPreparation.proposeHistoryReplacement({
+                                historyMessages: [summaryMessage, ...replayMessages],
+                                pendingMessages,
+                            });
                             return {
-                                envelope: {
-                                    messages: proposedMessages,
-                                    tools: definitions,
-                                },
+                                envelope: replacement.envelope,
                                 commit: async () => {
                                     if (signal?.aborted)
                                         throw new AgentRunCancelledError();
-                                    const ids = await nativeLease.appendCompaction({
+                                    const committed = await replacement.commit(() => nativeLease.appendCompaction({
                                         summary: compacted.summary,
                                         trigger: 'auto',
                                         preTokens,
@@ -3808,7 +3722,8 @@ export class ClaudeSessionService {
                                                 preservePrefix: false,
                                             }
                                             : {}),
-                                    });
+                                    }));
+                                    const ids = committed.value;
                                     await this.runAdvisoryHook(sessionId, 'PostCompact', { trigger: 'auto', compact_summary: compacted.summary }, 'auto', signal);
                                     if (this.options.hooks) {
                                         const outcome = await this.hookLifecycle.refresh(sessionId, hookSession, signal);
@@ -4095,25 +4010,24 @@ export class ClaudeSessionService {
                         };
                     }
                     if (shellCommand === undefined && budget) {
-                        const definitions = currentDefinitions();
                         await contextEngine.prepare(contextTransitionPort([], currentTurnUserMessages ?? []), signal);
-                        budget.assertFits(budget.evaluate([
-                            ...contextMessages,
-                            ...injectTurnContext(activeTurnMessages()),
-                        ], definitions));
+                        const projection = contextPreparation.project({
+                            includeMemory: false,
+                        });
+                        budget.assertFits(budget.evaluate(projection.envelope.messages, projection.envelope.tools));
                     }
                     let stopHookActive = false;
+                    const initialProjection = contextPreparation.project({
+                        includeMemory: false,
+                    });
                     const runtimeRequest = {
                         sessionId,
-                        messages: [
-                            ...contextMessages,
-                            ...injectTurnContext(activeTurnMessages()),
-                        ],
-                        stableSystemMessageCount,
+                        messages: initialProjection.envelope.messages,
+                        stableSystemMessageCount: initialProjection.stableSystemMessageCount,
                         cwd: this.activeCwd(),
                         toolResultDirectory,
                         observer,
-                        ...(activeTurnInput ? { steering: activeTurnInput } : {}),
+                        ...(steering ? { steering } : {}),
                         ...(this.options.effort ? { effort: this.options.effort } : {}),
                         ...(this.options.maxModelTurns !== undefined
                             ? { maxModelTurns: this.options.maxModelTurns }
@@ -4138,14 +4052,10 @@ export class ClaudeSessionService {
                             if (shellCommand === undefined) {
                                 await contextEngine.prepare(contextTransitionPort([], currentTurnUserMessages ?? []), signal);
                             }
-                            runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
-                            return [
-                                ...contextMessages,
-                                ...injectTurnContext([
-                                    ...activeTurnMessages(),
-                                    ...projectMemoryRecallMessages,
-                                ]),
-                            ];
+                            const projection = contextPreparation.project();
+                            runtimeRequest.stableSystemMessageCount =
+                                projection.stableSystemMessageCount;
+                            return projection.envelope.messages;
                         },
                         ...(this.options.hooks ||
                             subagentExecutor ||
@@ -4274,14 +4184,10 @@ export class ClaudeSessionService {
                             }
                             // The single reactive retry must use the compacted transcript, not
                             // the stale request copy captured before the compact boundary.
-                            runtimeRequest.messages = [
-                                ...contextMessages,
-                                ...injectTurnContext([
-                                    ...activeTurnMessages(),
-                                    ...projectMemoryRecallMessages,
-                                ]),
-                            ];
-                            runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
+                            const projection = contextPreparation.project();
+                            runtimeRequest.messages = projection.envelope.messages;
+                            runtimeRequest.stableSystemMessageCount =
+                                projection.stableSystemMessageCount;
                             runtimeRequest.deferFailureKinds = true;
                             try {
                                 result = await attemptMainTurn();
@@ -4417,11 +4323,11 @@ export class ClaudeSessionService {
                         ? projectNativeSessionEntries(nativeLease.activeEvents()).at(-1)
                             ?.uuid
                         : undefined;
-                    const providerVisibleMessages = [
-                        ...contextMessages,
-                        ...injectTurnContext(memorySnapshot),
-                    ];
-                    const definitions = currentDefinitions();
+                    const providerProjection = contextPreparation.project({
+                        includeMemory: false,
+                    });
+                    const providerVisibleMessages = providerProjection.envelope.messages;
+                    const definitions = providerProjection.envelope.tools;
                     const currentContextTokens = contextEngine.report({
                         messages: providerVisibleMessages,
                         tools: definitions,
@@ -4507,27 +4413,8 @@ export class ClaudeSessionService {
                     return scratchResult.value;
                 });
             }
-            controller.complete();
             return result;
-        }
-        catch (error) {
-            controller.fail(error, signal);
-            throw error;
-        }
-        finally {
-            if (activeTurnInput !== undefined) {
-                for (const item of activeTurnInput.close()) {
-                    this.options.eventSink?.({
-                        type: 'user-input-rejected',
-                        id: item.id,
-                        content: item.content,
-                        reason: signal?.aborted ? 'cancelled' : 'failed',
-                    });
-                }
-            }
-            if (this.activeTurnInputs.get(sessionId) === activeTurnRecord)
-                this.activeTurnInputs.delete(sessionId);
-        }
+        });
     }
     async ensureFileResources(sessionId, signal) {
         const resources = this.options.fileResources ?? [];

package/dist/application/turn-lifecycle.d.ts

@@ -1,6 +1,5 @@
 import { type ModelDocument, type ModelImage, type RuntimeEventSink } from '../core/runtime.js';
-import type { LifecycleState } from '../core/agent-orchestration.js';
-export type TurnTerminalState = Extract<LifecycleState, 'completed' | 'failed' | 'cancelled'>;
+import { type ActiveTurnInputCommandResult, type ActiveTurnInputPort } from '../core/active-turn-input.js';
 export type TurnActivation = {
     kind: 'start';
     sessionId: string;
@@ -28,13 +27,26 @@ export interface TurnRequest {
     submission: TurnSubmission;
     signal?: AbortSignal;
 }
-export declare class TurnTerminalController {
-    private readonly sink;
-    private terminal;
-    constructor(sink: RuntimeEventSink);
-    emit: RuntimeEventSink;
-    complete(): void;
-    fail(error: unknown, signal?: AbortSignal): void;
+export interface TurnScope {
+    readonly emit: RuntimeEventSink;
+    readonly steering?: ActiveTurnInputPort;
+}
+export interface TurnCoordinatorOptions {
+    readonly eventSink: RuntimeEventSink;
+    readonly createSteeringId: () => string;
+}
+/** Owns the lifecycle and active-turn coordination for one session service. */
+export declare class TurnCoordinator {
+    private readonly options;
+    private readonly activeTurns;
+    constructor(options: TurnCoordinatorOptions);
+    run<T>(request: TurnRequest, work: (scope: TurnScope) => Promise<T>): Promise<T>;
+    steer(sessionId: string, content: string): ActiveTurnInputCommandResult;
+    withdrawSteering(sessionId: string, id: string): ActiveTurnInputCommandResult;
+    close(): void;
+    private validateRequest;
+    private terminalState;
     private transition;
+    private rejectPending;
 }
 //# sourceMappingURL=turn-lifecycle.d.ts.map

package/dist/application/turn-lifecycle.js

@@ -1,36 +1,150 @@
 import { AgentRunCancelledError, ModelProviderError, } from '../core/runtime.js';
-export class TurnTerminalController {
-    sink;
-    terminal = false;
-    constructor(sink) {
-        this.sink = sink;
-    }
-    emit = (event) => {
-        if (event.type === 'state' &&
-            (event.state === 'completed' ||
-                event.state === 'cancelled' ||
-                event.state === 'failed')) {
-            return;
+import { ActiveTurnInputMailbox, } from '../core/active-turn-input.js';
+/** Owns the lifecycle and active-turn coordination for one session service. */
+export class TurnCoordinator {
+    options;
+    activeTurns = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async run(request, work) {
+        const { sessionId } = request.activation;
+        const mailbox = request.submission.kind === 'shell'
+            ? undefined
+            : new ActiveTurnInputMailbox(this.options.createSteeringId);
+        const record = {
+            ...(mailbox ? { mailbox } : {}),
+            terminal: false,
+        };
+        let terminalState = 'failed';
+        let pendingFailure;
+        const scope = {
+            emit: (event) => {
+                if (event.type === 'state' &&
+                    (event.state === 'completed' ||
+                        event.state === 'failed' ||
+                        event.state === 'cancelled')) {
+                    return;
+                }
+                this.options.eventSink(event);
+            },
+            ...(mailbox ? { steering: mailbox } : {}),
+        };
+        try {
+            this.validateRequest(request);
+            if (this.activeTurns.has(sessionId)) {
+                throw new Error(`conflict: locked (session ${sessionId} already has an active turn)`);
+            }
+            this.activeTurns.set(sessionId, record);
+            const result = await work(scope);
+            terminalState = 'completed';
+            this.transition(record, 'completed');
+            return result;
+        }
+        catch (error) {
+            if (!record.terminal) {
+                terminalState = this.terminalState(error, request.signal);
+                this.transition(record, terminalState);
+            }
+            throw error;
+        }
+        finally {
+            try {
+                if (mailbox) {
+                    pendingFailure = this.rejectPending(mailbox.close(), terminalState === 'cancelled' ? 'cancelled' : 'failed');
+                }
+            }
+            finally {
+                if (this.activeTurns.get(sessionId) === record) {
+                    this.activeTurns.delete(sessionId);
+                }
+            }
+            if (pendingFailure) {
+                // A rejected-input sink failure intentionally retains its prior precedence.
+                // eslint-disable-next-line no-unsafe-finally -- compatibility is covered by the sink-error regression
+                throw pendingFailure.error;
+            }
         }
-        this.sink(event);
-    };
-    complete() {
-        this.transition('completed');
     }
-    fail(error, signal) {
-        if (this.terminal)
-            return;
-        const cancelled = signal?.aborted === true ||
+    steer(sessionId, content) {
+        const active = this.activeTurns.get(sessionId);
+        if (!active)
+            return { kind: 'no-active-turn' };
+        if (!active.mailbox)
+            return { kind: 'not-steerable' };
+        const result = active.mailbox.enqueue(content);
+        if (result.kind === 'accepted' || result.kind === 'empty')
+            return result;
+        return { kind: 'turn-completing' };
+    }
+    withdrawSteering(sessionId, id) {
+        const active = this.activeTurns.get(sessionId);
+        if (!active)
+            return { kind: 'no-active-turn' };
+        if (!active.mailbox)
+            return { kind: 'not-steerable' };
+        const result = active.mailbox.withdraw(id);
+        return result.kind === 'withdrawn' ? result : { kind: 'not-pending' };
+    }
+    close() {
+        let firstFailure;
+        for (const active of this.activeTurns.values()) {
+            if (!active.mailbox)
+                continue;
+            const failure = this.rejectPending(active.mailbox.close(), 'closed');
+            firstFailure ??= failure;
+        }
+        if (firstFailure)
+            throw firstFailure.error;
+    }
+    validateRequest(request) {
+        const { activation, submission } = request;
+        const prompt = submission.kind === 'shell'
+            ? `! ${submission.command}`
+            : submission.kind === 'retry'
+                ? submission.prompt
+                : submission.text;
+        const images = submission.kind === 'prompt' ? (submission.images ?? []) : [];
+        const documents = submission.kind === 'prompt' ? (submission.documents ?? []) : [];
+        if (prompt.length === 0 && images.length === 0 && documents.length === 0) {
+            throw new Error('Prompt must not be empty');
+        }
+        if (activation.name !== undefined && activation.name.length === 0) {
+            throw new Error('Session name must not be empty');
+        }
+        if (submission.kind === 'shell' && submission.command.trim().length === 0) {
+            throw new Error('Shell command must not be empty');
+        }
+    }
+    terminalState(error, signal) {
+        return signal?.aborted === true ||
             error instanceof AgentRunCancelledError ||
-            (error instanceof ModelProviderError && error.kind === 'cancelled');
-        this.transition(cancelled ? 'cancelled' : 'failed');
+            (error instanceof ModelProviderError && error.kind === 'cancelled')
+            ? 'cancelled'
+            : 'failed';
+    }
+    transition(record, state) {
+        if (record.terminal)
+            return;
+        record.terminal = true;
+        this.options.eventSink({ type: 'state', state });
     }
-    transition(state) {
-        if (this.terminal) {
-            throw new Error('Turn terminal transition already emitted');
+    rejectPending(items, reason) {
+        let firstFailure;
+        for (const item of items) {
+            try {
+                this.options.eventSink({
+                    type: 'user-input-rejected',
+                    id: item.id,
+                    content: item.content,
+                    reason,
+                });
+            }
+            catch (error) {
+                firstFailure ??= { error };
+            }
         }
-        this.terminal = true;
-        this.sink({ type: 'state', state });
+        return firstFailure;
     }
 }
 //# sourceMappingURL=turn-lifecycle.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.55.0",
+  "version": "0.55.1",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",