praxis-agent 0.30.0 → 0.31.0

package/dist/core/runtime.js

@@ -255,6 +255,8 @@ export class AgentRuntime {
         this.options = options;
     }
     async run(request) {
+        const failurePresentationDeferred = (kind) => request.deferFailureKinds === true ||
+            request.deferFailureKinds?.includes(kind) === true;
         if (this.options.emitInitialContextState !== false) {
             this.emit({ type: 'state', state: 'assembling-context' });
         }
@@ -273,6 +275,8 @@ export class AgentRuntime {
         let durationToolMs = 0;
         let linesAdded = 0;
         let linesRemoved = 0;
+        let activeAttemptHasPresentation = false;
+        let activeAttemptDiscarded = false;
         const definitions = this.provider.capabilities.tools
             ? (this.options.tools?.definitions() ?? [])
             : [];
@@ -288,6 +292,8 @@ export class AgentRuntime {
         try {
             let modelTurns = 0;
             while (true) {
+                activeAttemptHasPresentation = false;
+                activeAttemptDiscarded = false;
                 if (request.signal?.aborted)
                     return this.cancel();
                 if (maxModelTurns !== undefined && modelTurns >= maxModelTurns) {
@@ -379,9 +385,10 @@ export class AgentRuntime {
                     }),
                     resultCompleted: (call, result) => this.presentToolResult(call, result),
                 });
-                const failScheduledTurn = async (error) => {
+                const failScheduledTurn = async (error, afterSettled) => {
                     toolScheduler.abort(error);
                     await toolScheduler.settle().catch(() => undefined);
+                    afterSettled?.();
                     throw error;
                 };
                 const apiStartedAt = request.collectMetrics ? performance.now() : 0;
@@ -418,6 +425,7 @@ export class AgentRuntime {
                             this.emit({ type: 'state', state: 'streaming' });
                         }
                         if (event.type === 'text-delta') {
+                            activeAttemptHasPresentation = true;
                             textBytes += Buffer.byteLength(event.delta);
                             if (textBytes > maxModelOutputBytes) {
                                 throw new Error(`Model output exceeded ${maxModelOutputBytes} bytes`);
@@ -427,6 +435,7 @@ export class AgentRuntime {
                         }
                         else if (event.type === 'thinking-delta' ||
                             event.type === 'thinking-signature-delta') {
+                            activeAttemptHasPresentation = true;
                             textBytes += Buffer.byteLength(event.delta);
                             if (textBytes > maxModelOutputBytes) {
                                 throw new Error(`Model output exceeded ${maxModelOutputBytes} bytes`);
@@ -434,10 +443,12 @@ export class AgentRuntime {
                             this.emit(event);
                         }
                         else if (event.type === 'thinking-stop') {
+                            activeAttemptHasPresentation = true;
                             thinkingBlocks.push(event.block);
                             this.emit(event);
                         }
                         else if (event.type === 'thinking-start') {
+                            activeAttemptHasPresentation = true;
                             const initialThinking = event.block.type === 'redacted_thinking'
                                 ? event.block.data
                                 : event.block.thinking;
@@ -462,10 +473,12 @@ export class AgentRuntime {
                             toolScheduler.schedule(event.call, resolveToolSchedulingPolicy(this.options.tools, event.call));
                         }
                         else if (event.type === 'terminal') {
+                            activeAttemptHasPresentation = true;
                             terminalReason = event.reason;
                             this.emit(event);
                         }
                         else {
+                            activeAttemptHasPresentation = true;
                             turnUsage = event.usage;
                             this.emit(event);
                         }
@@ -495,6 +508,18 @@ export class AgentRuntime {
                     terminalReason === undefined) {
                     return failScheduledTurn(new ModelProviderError('Provider stream ended without a terminal reason', { retryable: true }));
                 }
+                if (terminalReason === 'prompt_too_long') {
+                    const discardAttempt = failurePresentationDeferred('prompt_too_long')
+                        ? () => {
+                            this.emit({
+                                type: 'model-attempt-discarded',
+                                reason: 'prompt_too_long',
+                            });
+                            activeAttemptDiscarded = true;
+                        }
+                        : undefined;
+                    await failScheduledTurn(new ModelProviderError('Provider reported that the active prompt exceeds its context window', { kind: 'prompt_too_long', retryable: false }), discardAttempt);
+                }
                 if (terminalReason === 'tool_use' && toolCalls.length === 0) {
                     return failScheduledTurn(new ModelProviderError('Provider reported tool_use without a completed tool call', { retryable: false }));
                 }
@@ -677,7 +702,18 @@ export class AgentRuntime {
                 return this.cancel();
             const message = error instanceof Error ? error.message : String(error);
             const retryable = error instanceof ModelProviderError ? error.retryable : false;
-            this.emit({ type: 'failed', message, retryable });
+            const kind = error instanceof ModelProviderError
+                ? modelProviderErrorKind(error)
+                : undefined;
+            const failureDeferred = kind !== undefined && failurePresentationDeferred(kind);
+            if (failureDeferred &&
+                activeAttemptHasPresentation &&
+                !activeAttemptDiscarded) {
+                this.emit({ type: 'model-attempt-discarded', reason: kind });
+            }
+            if (!failureDeferred) {
+                this.emit({ type: 'failed', message, retryable });
+            }
             throw error;
         }
     }

package/dist/maintenance/doctor.js

@@ -17,6 +17,7 @@ import { ModelPricingRegistry } from '../core/usage.js';
 import { detectInstalledClaudeVersion, } from '../platform/claude-version.js';
 import { redactSensitiveText, sensitiveEnvironmentValues, } from '../platform/sensitive-data.js';
 import { collectDoctorLocalDiagnostics, resolveDoctorUpdates, } from './doctor-diagnostic.js';
+import { resolveProjectMemoryPolicy } from '../core/project-memory.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -148,23 +149,36 @@ export async function runDoctor(options) {
     const updatesPromise = resolveDoctorUpdates(diagnosticOptions, local.updates);
     let settings;
     let nativeResources;
+    const settingsResources = async () => {
+        settings ??=
+            dataPlane === 'claude'
+                ? await loadClaudeSettings({ configRoot, cwd })
+                : await loadNativeSettings({ root: configRoot, cwd });
+        return settings;
+    };
+    const projectMemoryEnabled = async () => resolveProjectMemoryPolicy({
+        dataPlane,
+        settings: await settingsResources(),
+        environment: options.environment,
+    }).enabled;
     const sharedResources = async () => {
+        const includeProjectMemory = await projectMemoryEnabled();
         if (dataPlane === 'claude') {
             return loadClaudeSharedResources({
                 configRoot,
                 cwd,
                 claudeStatePath: options.claudeStatePath,
+                includeProjectMemory,
             });
         }
         nativeResources ??= await loadNativeSharedResources({
             root: configRoot,
             cwd,
+            environment: options.environment,
+            includeProjectMemory,
         });
         return nativeResources;
     };
-    const settingsResources = async () => dataPlane === 'claude'
-        ? loadClaudeSettings({ configRoot, cwd })
-        : loadNativeSettings({ root: configRoot, cwd });
     const checks = [];
     checks.push(await capture('installation', async () => {
         const executablePath = await canonicalExecutable(options.executablePath);
@@ -350,11 +364,21 @@ export async function runDoctor(options) {
     }));
     checks.push(await capture('resources', async () => {
         const resources = await sharedResources();
+        const includeProjectMemory = await projectMemoryEnabled();
         if (dataPlane === 'native') {
-            await loadNativeContextResources({ root: configRoot, cwd });
+            await loadNativeContextResources({
+                root: configRoot,
+                cwd,
+                environment: options.environment,
+                includeProjectMemory,
+            });
         }
         else {
-            await loadClaudeContextResources({ configRoot, cwd });
+            await loadClaudeContextResources({
+                configRoot,
+                cwd,
+                includeProjectMemory,
+            });
         }
         validateClaudeExtensions([
             ...resources.commands,

package/dist/mcp/claude-mcp-management.js

@@ -191,11 +191,13 @@ export class ClaudeMcpManagement {
             ? await loadNativeSharedResources({
                 root: this.configRoot,
                 cwd: this.cwd,
+                includeProjectMemory: false,
             })
             : await loadClaudeSharedResources({
                 configRoot: this.configRoot,
                 cwd: this.cwd,
                 settingSources: ['user', 'project', 'local'],
+                includeProjectMemory: false,
             });
         const records = new Map();
         for (const resource of resources.mcp) {

package/dist/persistence/native-resources.d.ts

@@ -2,8 +2,10 @@ import type { ClaudeContextResources, ClaudeJsonResource, ClaudeSharedResources
 export interface LoadNativeResourcesOptions {
     root: string;
     cwd: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    includeProjectMemory?: boolean;
 }
 export declare function loadNativeSettings({ root, cwd, }: LoadNativeResourcesOptions): Promise<ClaudeJsonResource[]>;
-export declare function loadNativeSharedResources({ root, cwd, }: LoadNativeResourcesOptions): Promise<ClaudeSharedResources>;
+export declare function loadNativeSharedResources({ root, cwd, environment, includeProjectMemory, }: LoadNativeResourcesOptions): Promise<ClaudeSharedResources>;
 export declare function loadNativeContextResources(options: LoadNativeResourcesOptions): Promise<ClaudeContextResources>;
 //# sourceMappingURL=native-resources.d.ts.map

package/dist/persistence/native-resources.js

@@ -1,6 +1,7 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { sanitizeClaudeProjectPath } from '../compatibility/claude/paths.js';
+import { resolveProjectMemoryPolicy } from '../core/project-memory.js';
+import { resolveProjectMemoryDirectory } from '../platform/project-memory-paths.js';
 async function text(path, scope) {
     try {
         return { path, scope, content: await readFile(path, 'utf8') };
@@ -56,13 +57,26 @@ export async function loadNativeSettings({ root, cwd, }) {
     ]);
     return resources.filter((resource) => resource !== null);
 }
-export async function loadNativeSharedResources({ root, cwd, }) {
+export async function loadNativeSharedResources({ root, cwd, environment = process.env, includeProjectMemory = true, }) {
     const project = resolve(cwd, '.praxis');
-    const memoryRoot = resolve(root, 'memory', sanitizeClaudeProjectPath(cwd));
-    const [userInstruction, projectInstruction, memory, skills, commands, agents, settings, userMcp, projectMcp, localMcp,] = await Promise.all([
+    const memoryRoot = await resolveProjectMemoryDirectory({
+        dataPlane: 'native',
+        configRoot: root,
+        cwd,
+    });
+    const settings = await loadNativeSettings({ root, cwd });
+    const memoryEnabled = includeProjectMemory &&
+        resolveProjectMemoryPolicy({
+            dataPlane: 'native',
+            settings,
+            environment,
+        }).enabled;
+    const [userInstruction, projectInstruction, memory, skills, commands, agents, userMcp, projectMcp, localMcp,] = await Promise.all([
         text(join(root, 'PRAXIS.md'), 'user'),
         text(join(project, 'PRAXIS.md'), 'project'),
-        files(memoryRoot, 'project', (name) => name.endsWith('.md')),
+        memoryEnabled
+            ? files(memoryRoot, 'project', (name) => name.endsWith('.md'))
+            : Promise.resolve([]),
         Promise.all([
             files(join(root, 'skills'), 'user', (name) => name === 'SKILL.md'),
             files(join(project, 'skills'), 'project', (name) => name === 'SKILL.md'),
@@ -75,7 +89,6 @@ export async function loadNativeSharedResources({ root, cwd, }) {
             files(join(root, 'agents'), 'user', (name) => name.endsWith('.md')),
             files(join(project, 'agents'), 'project', (name) => name.endsWith('.md')),
         ]).then(([user, local]) => [...user, ...local]),
-        loadNativeSettings({ root, cwd }),
         json(join(root, 'mcp.json'), 'user'),
         json(join(project, 'mcp.json'), 'project'),
         json(join(project, 'mcp.local.json'), 'local'),

package/dist/platform/path-containment.d.ts

@@ -0,0 +1,2 @@
+export declare function isPathWithin(root: string, candidate: string): boolean;
+//# sourceMappingURL=path-containment.d.ts.map

package/dist/platform/path-containment.js

@@ -0,0 +1,7 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+export function isPathWithin(root, candidate) {
+    const pathFromRoot = relative(resolve(root), resolve(candidate));
+    return (pathFromRoot === '' ||
+        (!pathFromRoot.startsWith('..') && !isAbsolute(pathFromRoot)));
+}
+//# sourceMappingURL=path-containment.js.map

package/dist/platform/project-identity.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resolves the stable local identity for a project. Linked worktrees share the
+ * main repository identity; non-git directories use their canonical path.
+ */
+export declare function resolveProjectIdentity(cwd: string): Promise<string>;
+//# sourceMappingURL=project-identity.d.ts.map

package/dist/platform/project-identity.js

@@ -0,0 +1,66 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+async function canonicalPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return resolve(path);
+        throw error;
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function findGitRoot(cwd) {
+    let current = await canonicalPath(cwd);
+    while (!(await exists(join(current, '.git')))) {
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+    return current;
+}
+async function optionalFile(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/**
+ * Resolves the stable local identity for a project. Linked worktrees share the
+ * main repository identity; non-git directories use their canonical path.
+ */
+export async function resolveProjectIdentity(cwd) {
+    const canonicalCwd = await canonicalPath(cwd);
+    const gitRoot = await findGitRoot(canonicalCwd);
+    if (!gitRoot)
+        return canonicalCwd;
+    const marker = join(gitRoot, '.git');
+    if ((await stat(marker)).isDirectory())
+        return gitRoot;
+    const gitFile = await readFile(marker, 'utf8');
+    const gitDirectoryValue = /^gitdir:\s*(.+)\s*$/mu.exec(gitFile)?.[1];
+    if (!gitDirectoryValue)
+        return gitRoot;
+    const gitDirectory = resolve(gitRoot, gitDirectoryValue);
+    const commonDirectory = await optionalFile(join(gitDirectory, 'commondir'));
+    if (!commonDirectory)
+        return gitRoot;
+    return dirname(await canonicalPath(resolve(gitDirectory, commonDirectory.trim())));
+}
+//# sourceMappingURL=project-identity.js.map

package/dist/platform/project-memory-paths.d.ts

@@ -0,0 +1,13 @@
+import type { ProjectMemoryDataPlane } from '../core/project-memory.js';
+export interface ResolveProjectMemoryDirectoryOptions {
+    dataPlane: ProjectMemoryDataPlane;
+    configRoot: string;
+    cwd: string;
+}
+export declare function resolveProjectMemoryDirectory({ dataPlane, configRoot, cwd, }: ResolveProjectMemoryDirectoryOptions): Promise<string>;
+export declare function resolveProjectMemoryStatePath(options: {
+    dataPlane: ProjectMemoryDataPlane;
+    configRoot: string;
+    memoryDirectory: string;
+}): string;
+//# sourceMappingURL=project-memory-paths.d.ts.map

package/dist/platform/project-memory-paths.js

@@ -0,0 +1,28 @@
+import { realpath } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { resolveProjectIdentity } from './project-identity.js';
+import { sanitizeProjectPath } from './project-path-key.js';
+async function canonicalPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return resolve(path);
+        throw error;
+    }
+}
+export async function resolveProjectMemoryDirectory({ dataPlane, configRoot, cwd, }) {
+    const [root, identity] = await Promise.all([
+        canonicalPath(configRoot),
+        resolveProjectIdentity(cwd),
+    ]);
+    const key = sanitizeProjectPath(identity);
+    return dataPlane === 'native'
+        ? join(root, 'memory', key)
+        : join(root, 'projects', key, 'memory');
+}
+export function resolveProjectMemoryStatePath(options) {
+    return join(resolve(options.configRoot), options.dataPlane === 'native' ? 'state' : 'praxis', 'project-memory', basename(options.memoryDirectory), 'cursor.json');
+}
+//# sourceMappingURL=project-memory-paths.js.map

package/dist/platform/project-path-key.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeProjectPath(path: string): string;
+//# sourceMappingURL=project-path-key.d.ts.map

package/dist/platform/project-path-key.js

@@ -0,0 +1,16 @@
+const MAX_SANITIZED_PROJECT_PATH_LENGTH = 200;
+function stablePathHash(value) {
+    let hash = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        hash = Math.imul(hash, 31) + value.charCodeAt(index);
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}
+export function sanitizeProjectPath(path) {
+    const sanitized = path.replace(/[^a-zA-Z0-9]/g, '-');
+    if (sanitized.length <= MAX_SANITIZED_PROJECT_PATH_LENGTH)
+        return sanitized;
+    return `${sanitized.slice(0, MAX_SANITIZED_PROJECT_PATH_LENGTH)}-${stablePathHash(path).toString(36)}`;
+}
+//# sourceMappingURL=project-path-key.js.map

package/dist/providers/fallback-provider.js

@@ -2,7 +2,9 @@ import { modelProviderErrorKind, ModelProviderError, } from '../core/runtime.js'
 const MAX_ATTEMPTS_PER_MODEL = 3;
 const RETRY_DELAYS_MS = [500, 1_000];
 function retryable(error) {
-    return error instanceof ModelProviderError && error.retryable;
+    return (error instanceof ModelProviderError &&
+        error.retryable &&
+        modelProviderErrorKind(error) !== 'prompt_too_long');
 }
 /** Routes each complete request through Claude's retry-then-fallback policy. */
 export class FallbackModelProvider {

package/package.json

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