praxis-agent 0.30.0 → 0.31.0

package/dist/application/session-service.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { appendFile, copyFile, link, lstat, mkdir, readdir, realpath, stat, unlink, } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, extname, isAbsolute, join, relative, resolve, } from 'node:path';
+import { isPathWithin } from '../platform/path-containment.js';
 import { AGENT_COLOR_DEFAULT, agentColorMessage, getClaudeEffectiveAgentColor, } from '../compatibility/claude/agent-color.js';
 import { createClaudeCompactEntries, formatClaudeCompactSummary, getCumulativeDroppedTokens, } from '../compatibility/claude/compaction.js';
 import { discoverClaudeProjectRoot, isClaudeSessionId, resolveClaudePaths, resolveClaudeScheduledTaskFile, } from '../compatibility/claude/paths.js';
@@ -19,7 +20,7 @@ import { AgentRunCancelledError, AgentRuntime, } from '../core/runtime.js';
 import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 import { BackgroundTaskRuntime, } from './background-task-runtime.js';
 import { usageCostUsd } from '../core/usage.js';
-import { ContextBudget, ContextRecoveryPlanner, estimateModelRequestTokens, isPromptTooLongError, } from '../core/context-budget.js';
+import { ContextBudget, ContextRecoveryPlanner, contextRecoveryMadeProgress, estimateModelRequestTokens, isPromptTooLongError, } from '../core/context-budget.js';
 import { injectFirstUserMessageContext, } from '../core/context.js';
 import { ClaudeHookToolCoordinator } from '../hooks/claude-hook-tools.js';
 import { ClaudeTranscriptStore, } from '../persistence/claude-transcript-store.js';
@@ -464,6 +465,22 @@ function validSessionName(value) {
         ? name.toLocaleLowerCase()
         : null;
 }
+function projectMemoryMessages(entries) {
+    return selectClaudeActiveTranscript(entries).flatMap((entry) => {
+        if (typeof entry.uuid !== 'string')
+            return [];
+        return projectClaudeModelMessages([entry]).flatMap((message) => (message.role === 'user' || message.role === 'assistant') &&
+            message.content.trim().length > 0
+            ? [
+                {
+                    id: entry.uuid,
+                    role: message.role,
+                    content: message.content,
+                },
+            ]
+            : []);
+    });
+}
 const SESSION_END_HOOK_TIMEOUT_MS = 15_000;
 class HookLifecycle {
     hooks;
@@ -741,6 +758,7 @@ export class ClaudeSessionService {
     async close() {
         await this.hookLifecycle.close();
         this.scheduledPrompts?.close();
+        await this.options.projectMemoryExtraction?.close(5_000);
         await Promise.all([...this.hostedSubagents].map((executor) => executor.close()));
         await Promise.resolve();
         await Promise.all([...this.backgroundNotificationWrites.values()]);
@@ -756,6 +774,9 @@ export class ClaudeSessionService {
     }
     async transitionHookSession(sessionId, reason) {
         await this.hookLifecycle.transition(sessionId, reason);
+        if (reason === 'clear') {
+            this.options.projectMemoryRecall?.clearSession?.(sessionId);
+        }
         this.options.contextAssembler?.invalidate?.({
             lifecycleId: sessionId,
             reason: reason === 'resume' ? 'restore' : 'clear',
@@ -1784,6 +1805,7 @@ export class ClaudeSessionService {
             if (appendResult.status === 'conflict') {
                 throw new Error(`Claude transcript append conflict: ${appendResult.reason}`);
             }
+            this.options.projectMemoryRecall?.recordCompact(sessionId);
             this.options.eventSink?.({
                 type: 'compact-boundary',
                 trigger: 'manual',
@@ -2147,6 +2169,14 @@ export class ClaudeSessionService {
                 agent?.initialPrompt
                 ? `${agent.initialPrompt}\n\n${prompt}`
                 : prompt;
+            const projectMemoryRecallTurn = !skipUserPrompt && shellCommand === undefined
+                ? this.options.projectMemoryRecall?.prefetch({
+                    sessionId,
+                    turnId: randomUUID(),
+                    prompt: effectivePrompt,
+                    ...(signal ? { signal } : {}),
+                })
+                : undefined;
             const initialPricing = this.options.pricing?.resolve(provider.model ?? 'praxis/provider');
             if (this.options.maxBudgetUsd !== undefined && !initialPricing) {
                 throw new Error(`Cannot enforce --max-budget-usd: no pricing is configured for model ${provider.model ?? 'praxis/provider'}`);
@@ -2456,6 +2486,8 @@ export class ClaudeSessionService {
             });
             let currentTurnUserMessages = null;
             let currentTurnToolCalls = 0;
+            let projectMemoryMaintained = false;
+            let projectMemoryRecallMessages = [];
             const observer = {
                 assistantCompleted: async (message) => {
                     const [entry] = translateProviderEvents([
@@ -2534,6 +2566,29 @@ export class ClaudeSessionService {
                         throw new Error('Could not translate tool result');
                     const tail = await this.append(lease, snapshot.tail, entry);
                     snapshot = { entries: [...snapshot.entries, entry], tail };
+                    if (!toolResult.isError && this.options.projectMemoryDirectory) {
+                        const pathValue = call.input.file_path;
+                        const path = typeof pathValue === 'string'
+                            ? resolve(this.activeCwd(), pathValue)
+                            : null;
+                        if (path &&
+                            isPathWithin(this.options.projectMemoryDirectory, path)) {
+                            if (call.name === 'Read') {
+                                this.options.projectMemoryRecall?.recordRead(sessionId, path);
+                            }
+                            else if (call.name === 'Write' || call.name === 'Edit') {
+                                projectMemoryMaintained = true;
+                            }
+                        }
+                        if (call.name === 'Read') {
+                            for (const accessedPath of toolResult.accessedPaths ?? []) {
+                                const resolvedAccessedPath = resolve(this.activeCwd(), accessedPath);
+                                if (isPathWithin(this.options.projectMemoryDirectory, resolvedAccessedPath)) {
+                                    this.options.projectMemoryRecall?.recordRead(sessionId, resolvedAccessedPath);
+                                }
+                            }
+                        }
+                    }
                     if (toolResult.isError ||
                         call.name !== 'Read' ||
                         !this.options.conditionalRuleResolver ||
@@ -2807,7 +2862,10 @@ export class ClaudeSessionService {
                 const compactIfNeeded = async (pendingMessages = [], preservedUserMessages = [], options = {}) => {
                     if (!budget || this.options.autoCompact === false)
                         return;
-                    const historyMessages = projectClaudeModelMessages(snapshot.entries);
+                    const historyMessages = [
+                        ...projectClaudeModelMessages(snapshot.entries),
+                        ...projectMemoryRecallMessages,
+                    ];
                     const predicted = budget.evaluate([
                         ...contextMessages,
                         ...injectTurnContext([...historyMessages, ...pendingMessages]),
@@ -2925,17 +2983,27 @@ export class ClaudeSessionService {
                         createUuid: () => replayUuids.shift() ?? randomUUID(),
                         now: () => timestamp,
                     });
-                    const compactedHistory = projectClaudeModelMessages([
-                        ...snapshot.entries,
-                        ...provisionalEntries,
-                        ...replayEntries,
-                    ]);
+                    const compactedHistory = [
+                        ...projectClaudeModelMessages([
+                            ...snapshot.entries,
+                            ...provisionalEntries,
+                            ...replayEntries,
+                        ]),
+                        ...projectMemoryRecallMessages,
+                    ];
                     const afterHistory = budget.evaluate([...contextMessages, ...injectTurnContext(compactedHistory)], definitions);
                     const afterPending = budget.evaluate([
                         ...contextMessages,
                         ...injectTurnContext([...compactedHistory, ...pendingMessages]),
                     ], definitions);
                     budget.assertFits(afterPending);
+                    if (options.promptTooLong === true &&
+                        !contextRecoveryMadeProgress({
+                            beforeOccupancyTokens: predicted.occupancyTokens,
+                            afterOccupancyTokens: afterPending.occupancyTokens,
+                        })) {
+                        throw new Error('Reactive context compaction made no occupancy progress');
+                    }
                     const entries = [
                         ...compactEntries(afterHistory.estimatedTokens),
                         ...replayEntries,
@@ -3016,6 +3084,7 @@ export class ClaudeSessionService {
                         lifecycleId: sessionId,
                         reason: 'compact',
                     });
+                    this.options.projectMemoryRecall?.recordCompact(sessionId);
                     await refreshRuntimeContext();
                     this.options.eventSink?.({
                         type: 'compact-boundary',
@@ -3201,7 +3270,16 @@ export class ClaudeSessionService {
                     ...(this.options.collectMetrics || this.options.costStateStore
                         ? { collectMetrics: true }
                         : {}),
+                    ...(budget
+                        ? { deferFailureKinds: ['prompt_too_long'] }
+                        : {}),
                     reloadMessages: async () => {
+                        const recalled = projectMemoryRecallTurn?.consumeIfSettled();
+                        if (recalled) {
+                            projectMemoryRecallMessages = [
+                                { role: 'user', content: recalled.content },
+                            ];
+                        }
                         await compactIfNeeded([], currentTurnUserMessages ?? []);
                         if (stableSystemMessageCount === undefined) {
                             delete runtimeRequest.stableSystemMessageCount;
@@ -3211,7 +3289,10 @@ export class ClaudeSessionService {
                         }
                         return [
                             ...contextMessages,
-                            ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
+                            ...injectTurnContext([
+                                ...projectClaudeModelMessages(snapshot.entries),
+                                ...projectMemoryRecallMessages,
+                            ]),
                         ];
                     },
                     ...(this.options.hooks ||
@@ -3297,6 +3378,13 @@ export class ClaudeSessionService {
                 const attemptMainTurn = () => signal
                     ? runtime.run({ ...runtimeRequest, signal })
                     : runtime.run(runtimeRequest);
+                const surfaceExhaustedRecovery = (error) => {
+                    this.options.eventSink?.({
+                        type: 'failed',
+                        message: error.message,
+                        retryable: false,
+                    });
+                };
                 let result;
                 try {
                     result = await attemptMainTurn();
@@ -3304,24 +3392,35 @@ export class ClaudeSessionService {
                 catch (error) {
                     if (!budget || !isPromptTooLongError(error))
                         throw error;
-                    if (recoveryPlanner.consumeReactiveRetry() !== 'reactive-retry')
+                    if (recoveryPlanner.reactiveRetriesRemaining === 0) {
+                        surfaceExhaustedRecovery(error);
                         throw error;
+                    }
+                    const beforeRecovery = budget.evaluate(runtimeRequest.messages, definitions);
                     try {
                         await compactIfNeeded([], currentTurnUserMessages ?? [], {
                             promptTooLong: true,
                         });
                     }
-                    catch {
+                    catch (compactionError) {
+                        if (signal?.aborted ||
+                            compactionError instanceof AgentRunCancelledError) {
+                            throw new AgentRunCancelledError();
+                        }
                         // Compaction could not free the provider-bounded context; surface
                         // the original prompt-too-long error rather than the compaction
                         // failure.
+                        surfaceExhaustedRecovery(error);
                         throw error;
                     }
                     // The single reactive retry must use the compacted transcript, not
                     // the stale request copy captured before the compact boundary.
                     runtimeRequest.messages = [
                         ...contextMessages,
-                        ...injectTurnContext(projectClaudeModelMessages(snapshot.entries)),
+                        ...injectTurnContext([
+                            ...projectClaudeModelMessages(snapshot.entries),
+                            ...projectMemoryRecallMessages,
+                        ]),
                     ];
                     if (stableSystemMessageCount === undefined) {
                         delete runtimeRequest.stableSystemMessageCount;
@@ -3329,13 +3428,27 @@ export class ClaudeSessionService {
                     else {
                         runtimeRequest.stableSystemMessageCount = stableSystemMessageCount;
                     }
+                    const afterRecovery = budget.evaluate(runtimeRequest.messages, definitions);
+                    if (recoveryPlanner.consumeReactiveRetry({
+                        beforeOccupancyTokens: beforeRecovery.occupancyTokens,
+                        afterOccupancyTokens: afterRecovery.occupancyTokens,
+                    }) !== 'reactive-retry') {
+                        surfaceExhaustedRecovery(error);
+                        throw error;
+                    }
+                    runtimeRequest.deferFailureKinds = true;
                     try {
                         result = await attemptMainTurn();
                     }
-                    catch {
+                    catch (retryError) {
                         // Exactly one reactive retry is consumed; fail deterministically
                         // and surface the original prompt-too-long error.
                         recoveryPlanner.recordFailure();
+                        if (signal?.aborted ||
+                            retryError instanceof AgentRunCancelledError) {
+                            throw new AgentRunCancelledError();
+                        }
+                        surfaceExhaustedRecovery(error);
                         throw error;
                     }
                 }
@@ -3465,6 +3578,11 @@ export class ClaudeSessionService {
                         });
                     }
                 }
+                this.options.projectMemoryExtraction?.observe({
+                    sessionId,
+                    directMaintenance: projectMemoryMaintained,
+                    messages: projectMemoryMessages(snapshot.entries),
+                });
                 turnCompleted = true;
                 return {
                     sessionId,

package/dist/cli/interactive.js

@@ -449,6 +449,7 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
     const [costUsd, setCostUsd] = useState();
     const [contextWindowTokens, setContextWindowTokens] = useState(display.contextWindowTokens);
     const [history, setHistory] = useState([...initialHistory]);
+    const activeAttemptThinkingItemsRef = useRef([]);
     const [transcriptScrollOffset, setTranscriptScrollOffset] = useState(0);
     // The pure TUI view model classifies the session identity (fresh/resumed/
     // started) and projects the rendered transcript. Startup diagnostics are
@@ -1183,28 +1184,45 @@ export function InteractiveApp({ dataPlane = resolveDataPlane(), configRoot: sup
                 // Signatures authenticate a thinking block for provider replay; they are
                 // intentionally not part of the user-visible reasoning summary.
                 break;
-            case 'thinking-stop':
+            case 'thinking-stop': {
                 // append flushes pending thinking deltas before the retained boundary
                 // item, keeping streaming order correct; the effective thinking getter
                 // already includes any deltas not yet published.
-                append({
+                const thinkingItem = {
                     kind: 'thinking',
                     text: event.block.type === 'thinking'
                         ? redactSensitiveText(event.block.thinking, sensitiveValues)
                         : (streamingFrameRef.current?.thinking ?? ''),
-                });
+                };
+                activeAttemptThinkingItemsRef.current.push(thinkingItem);
+                append(thinkingItem);
                 streamingFrameRef.current?.resetThinking();
                 streamingFrameRef.current?.flush();
                 break;
+            }
             case 'user-message':
                 append({ kind: 'assistant', text: event.message });
                 break;
             case 'state':
+                if (event.state === 'awaiting-model') {
+                    activeAttemptThinkingItemsRef.current = [];
+                }
                 setStatus(event.state);
                 break;
             case 'usage':
                 setUsage(event.usage);
                 break;
+            case 'model-attempt-discarded':
+                streamingFrameRef.current?.resetText();
+                streamingFrameRef.current?.resetThinking();
+                streamingFrameRef.current?.flush();
+                setUsage({ inputTokens: 0, outputTokens: 0 });
+                if (activeAttemptThinkingItemsRef.current.length > 0) {
+                    const discarded = new Set(activeAttemptThinkingItemsRef.current);
+                    setHistory((current) => current.filter((item) => !discarded.has(item)));
+                    activeAttemptThinkingItemsRef.current = [];
+                }
+                break;
             case 'tool-call':
                 if (['Edit', 'Write', 'NotebookEdit'].includes(event.call.name))
                     turnMutatedFilesRef.current = true;

package/dist/cli/protocol.d.ts

@@ -277,6 +277,7 @@ export declare class StreamJsonOutput {
     private onEvent;
     private writeSessionState;
     private ensureTurn;
+    private discardTurn;
     private startTurn;
     private partialText;
     private finishPartial;

package/dist/cli/protocol.js

@@ -1753,6 +1753,10 @@ export class StreamJsonOutput {
         this.modelTurns = 0;
     }
     onEvent(event) {
+        if (event.type === 'model-attempt-discarded') {
+            this.discardTurn(event.reason);
+            return;
+        }
         if (event.type === 'state') {
             if (this.compacting && event.state !== 'compacting') {
                 this.compacting = false;
@@ -2109,6 +2113,26 @@ export class StreamJsonOutput {
         if (!this.turnActive)
             this.startTurn();
     }
+    discardTurn(reason) {
+        this.write({
+            type: 'system',
+            subtype: 'model_attempt_discarded',
+            reason,
+            uuid: randomUUID(),
+            session_id: this.sessionId,
+        });
+        this.turnText = '';
+        this.turnThinking = [];
+        this.turnCalls = [];
+        this.turnUsage = emptyUsage();
+        this.turnTerminalReason = undefined;
+        this.turnActive = false;
+        this.assistantFlushed = true;
+        this.contentStarted = false;
+        this.textContentIndex = undefined;
+        this.activeThinkingIndex = undefined;
+        this.nextContentIndex = 0;
+    }
     startTurn() {
         if (this.turnActive)
             this.finishTurn();

package/dist/cli/tui/memory-files.d.ts

@@ -18,9 +18,10 @@ export interface LoadTuiMemoryFilesOptions {
     cwd: string;
     homeDirectory?: string;
     dataPlane?: DataPlane;
+    environment?: Readonly<Record<string, string | undefined>>;
 }
 export declare function displayTuiMemoryPath(path: string, cwd: string, homeDirectory?: string): string;
-export declare function loadTuiMemoryFiles({ configRoot, cwd, homeDirectory, dataPlane, }: LoadTuiMemoryFilesOptions): Promise<TuiMemoryFiles>;
+export declare function loadTuiMemoryFiles({ configRoot, cwd, homeDirectory, dataPlane, environment, }: LoadTuiMemoryFilesOptions): Promise<TuiMemoryFiles>;
 type TuiMemoryFolderLauncher = (command: string, args: readonly string[]) => Promise<void>;
 export declare function openTuiMemoryFolder(path: string, launcher?: TuiMemoryFolderLauncher): Promise<void>;
 export {};

package/dist/cli/tui/memory-files.js

@@ -2,9 +2,10 @@ import { spawn } from 'node:child_process';
 import { mkdir, realpath } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, isAbsolute, relative, resolve } from 'node:path';
-import { loadClaudeContextResources, loadClaudeSettings, resolveClaudeProjectMemoryDirectory, } from '../../compatibility/claude/shared-resources.js';
-import { sanitizeClaudeProjectPath } from '../../compatibility/claude/paths.js';
-import { loadNativeContextResources, loadNativeSharedResources, } from '../../persistence/native-resources.js';
+import { loadClaudeContextResources, loadClaudeSettings, } from '../../compatibility/claude/shared-resources.js';
+import { resolveProjectMemoryPolicy } from '../../core/project-memory.js';
+import { resolveProjectMemoryDirectory } from '../../platform/project-memory-paths.js';
+import { loadNativeContextResources, loadNativeSettings, } from '../../persistence/native-resources.js';
 function isWithin(root, path) {
     const value = relative(root, path);
     return value === '' || (!value.startsWith('..') && !isAbsolute(value));
@@ -41,40 +42,39 @@ function importedEntries(resource, instructions, cwd, homeDirectory, sourceDispl
         imported: true,
     }));
 }
-function autoMemorySetting(settings) {
-    let enabled = true;
-    for (const resource of settings) {
-        if (typeof resource.value === 'object' &&
-            resource.value !== null &&
-            !Array.isArray(resource.value)) {
-            const value = resource.value
-                .autoMemoryEnabled;
-            if (typeof value === 'boolean')
-                enabled = value;
-        }
-    }
-    return enabled;
-}
-export async function loadTuiMemoryFiles({ configRoot, cwd, homeDirectory = homedir(), dataPlane = 'claude', }) {
+export async function loadTuiMemoryFiles({ configRoot, cwd, homeDirectory = homedir(), dataPlane = 'claude', environment = process.env, }) {
     const [canonicalCwd, canonicalHome] = await Promise.all([
         realpath(cwd),
         realpath(homeDirectory).catch(() => resolve(homeDirectory)),
     ]);
-    const [context, settings, autoMemoryDirectory] = dataPlane === 'native'
-        ? await Promise.all([
-            loadNativeContextResources({ root: configRoot, cwd }),
-            loadNativeSharedResources({ root: configRoot, cwd }).then((resources) => resources.settings),
-            Promise.resolve(resolve(configRoot, 'memory', sanitizeClaudeProjectPath(cwd))),
-        ])
-        : await Promise.all([
-            loadClaudeContextResources({ configRoot, cwd, homeDirectory }),
-            loadClaudeSettings({ configRoot, cwd }),
-            resolveClaudeProjectMemoryDirectory({
+    const settings = dataPlane === 'native'
+        ? await loadNativeSettings({ root: configRoot, cwd })
+        : await loadClaudeSettings({ configRoot, cwd });
+    const memoryPolicy = resolveProjectMemoryPolicy({
+        dataPlane,
+        settings,
+        environment,
+    });
+    const [context, autoMemoryDirectory] = await Promise.all([
+        dataPlane === 'native'
+            ? loadNativeContextResources({
+                root: configRoot,
+                cwd,
+                environment,
+                includeProjectMemory: memoryPolicy.enabled,
+            })
+            : loadClaudeContextResources({
                 configRoot,
                 cwd,
                 homeDirectory,
+                includeProjectMemory: memoryPolicy.enabled,
             }),
-        ]);
+        resolveProjectMemoryDirectory({
+            dataPlane,
+            configRoot,
+            cwd,
+        }),
+    ]);
     const instructionName = dataPlane === 'native' ? 'PRAXIS.md' : 'CLAUDE.md';
     const userPath = resolve(configRoot, instructionName);
     const projectResources = context.instructions.filter((resource) => resource.importedFrom === undefined &&
@@ -129,7 +129,7 @@ export async function loadTuiMemoryFiles({ configRoot, cwd, homeDirectory = home
         });
         entries.push(...importedEntries(resource, context.instructions, canonicalCwd, canonicalHome, displayPath));
     }
-    const autoMemoryEnabled = autoMemorySetting(settings);
+    const autoMemoryEnabled = memoryPolicy.enabled;
     if (autoMemoryEnabled) {
         entries.push({
             kind: 'folder',