praxis-agent 0.30.0 → 0.32.0

package/dist/hooks/claude-session-environment.d.ts

@@ -0,0 +1,16 @@
+export type ClaudeEnvironmentHookEvent = 'Setup' | 'SessionStart' | 'CwdChanged' | 'FileChanged';
+export interface ClaudeSessionEnvironmentOptions {
+    stateRoot: string;
+    warn?(message: string): void;
+}
+export declare class ClaudeSessionEnvironment {
+    private readonly options;
+    private readonly cache;
+    constructor(options: ClaudeSessionEnvironmentOptions);
+    hookFile(sessionId: string, event: ClaudeEnvironmentHookEvent, hookIndex: number): Promise<string | undefined>;
+    invalidate(sessionId: string): void;
+    clearCwdFiles(sessionId: string): Promise<void>;
+    environment(sessionId: string): Promise<Readonly<Record<string, string>> | undefined>;
+    private directory;
+}
+//# sourceMappingURL=claude-session-environment.d.ts.map

package/dist/hooks/claude-session-environment.js

@@ -0,0 +1,112 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const ENV_FILE = /^(setup|sessionstart|cwdchanged|filechanged)-hook-(\d+)\.sh$/u;
+const PRIORITY = {
+    setup: 0,
+    sessionstart: 1,
+    cwdchanged: 2,
+    filechanged: 3,
+};
+export class ClaudeSessionEnvironment {
+    options;
+    cache = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    async hookFile(sessionId, event, hookIndex) {
+        if (process.platform === 'win32')
+            return undefined;
+        const directory = this.directory(sessionId);
+        await mkdir(directory, { recursive: true });
+        this.invalidate(sessionId);
+        return join(directory, `${event.toLowerCase()}-hook-${hookIndex}.sh`);
+    }
+    invalidate(sessionId) {
+        this.cache.delete(sessionId);
+    }
+    async clearCwdFiles(sessionId) {
+        const directory = this.directory(sessionId);
+        try {
+            const files = await readdir(directory);
+            await Promise.all(files
+                .filter((file) => ENV_FILE.test(file) &&
+                (file.startsWith('cwdchanged-') ||
+                    file.startsWith('filechanged-')))
+                .map((file) => writeFile(join(directory, file), '')));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                this.options.warn?.(`Could not clear hook environment: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        this.invalidate(sessionId);
+    }
+    async environment(sessionId) {
+        if (process.platform === 'win32')
+            return undefined;
+        const cached = this.cache.get(sessionId);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const directory = this.directory(sessionId);
+        const environment = Object.create(null);
+        try {
+            const files = (await readdir(directory))
+                .filter((file) => ENV_FILE.test(file))
+                .sort((left, right) => {
+                const leftMatch = left.match(ENV_FILE);
+                const rightMatch = right.match(ENV_FILE);
+                const priority = (PRIORITY[leftMatch?.[1] ?? ''] ?? 99) -
+                    (PRIORITY[rightMatch?.[1] ?? ''] ?? 99);
+                if (priority !== 0)
+                    return priority;
+                return Number(leftMatch?.[2] ?? 0) - Number(rightMatch?.[2] ?? 0);
+            });
+            for (const file of files) {
+                const path = join(directory, file);
+                const content = await readFile(path, 'utf8');
+                for (const [index, line] of content.split(/\r?\n/u).entries()) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith('#'))
+                        continue;
+                    const match = trimmed.match(/^export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u);
+                    const name = match?.[1];
+                    const source = match?.[2];
+                    const value = source === undefined ? undefined : literalExportValue(source);
+                    if (!name || value === undefined) {
+                        this.options.warn?.(`Ignored unsafe CLAUDE_ENV_FILE entry at ${path}:${index + 1}`);
+                        continue;
+                    }
+                    environment[name] = value;
+                }
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                this.options.warn?.(`Could not load hook environment: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const result = Object.keys(environment).length > 0 ? { ...environment } : null;
+        this.cache.set(sessionId, result);
+        return result ?? undefined;
+    }
+    directory(sessionId) {
+        return join(this.options.stateRoot, 'session-env', sessionId);
+    }
+}
+function literalExportValue(source) {
+    const value = source.trim();
+    if (value === '')
+        return '';
+    if (value.startsWith("'") && value.endsWith("'")) {
+        const literal = value.slice(1, -1);
+        return literal.includes("'") ? undefined : literal;
+    }
+    if (value.startsWith('"') && value.endsWith('"')) {
+        const literal = value.slice(1, -1);
+        if (literal.includes('$') || literal.includes('`'))
+            return undefined;
+        return literal.replace(/\\(["\\])/gu, '$1');
+    }
+    return /^[A-Za-z0-9_./:@%+,=-]*$/u.test(value) ? value : undefined;
+}
+//# sourceMappingURL=claude-session-environment.js.map

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/dist/tools/claude-task-tools.d.ts

@@ -1,5 +1,6 @@
 import type { ModelToolCall, ModelToolDefinition, ToolExecutionContext, ToolExecutionResult, ToolRegistry, RuntimeEventSink } from '../core/runtime.js';
 import { type BackgroundBashSnapshot, type BackgroundBashToolResult } from '../application/background-bash-manager.js';
+import { type ClaudeTask } from '../persistence/claude-task-store.js';
 export interface ClaudeTaskToolRegistryOptions {
     base: ToolRegistry;
     cwd: string;
@@ -10,6 +11,10 @@ export interface ClaudeTaskToolRegistryOptions {
     enabledTools?: readonly string[];
     maxOutputBytes?: number;
     eventSink?: RuntimeEventSink;
+    taskHooks?: {
+        created(task: Readonly<ClaudeTask>, signal?: AbortSignal): Promise<void>;
+        completed(task: Readonly<ClaudeTask>, signal?: AbortSignal): Promise<void>;
+    };
 }
 export declare class ClaudeTaskToolRegistry implements ToolRegistry {
     private readonly options;

package/dist/tools/claude-task-tools.js

@@ -342,6 +342,13 @@ export class ClaudeTaskToolRegistry {
         switch (call.name) {
             case 'TaskCreate': {
                 const task = await this.store.create(this.createInput(call.input));
+                try {
+                    await this.options.taskHooks?.created(task, context.signal);
+                }
+                catch (error) {
+                    await this.store.update(task.id, { status: 'deleted' });
+                    throw error;
+                }
                 return {
                     content: `Task #${task.id} created successfully: ${task.subject}`,
                     isError: false,
@@ -374,7 +381,14 @@ export class ClaudeTaskToolRegistry {
             }
             case 'TaskUpdate': {
                 const id = stringField(call.input, 'taskId');
-                const result = await this.store.update(id, this.updateInput(call.input));
+                const update = this.updateInput(call.input);
+                if (update.status === 'completed') {
+                    const task = await this.store.get(id);
+                    if (task && task.status !== 'completed') {
+                        await this.options.taskHooks?.completed(task, context.signal);
+                    }
+                }
+                const result = await this.store.update(id, update);
                 const missing = {
                     success: false,
                     taskId: id,

package/dist/tools/local-tools.d.ts

@@ -11,6 +11,7 @@ export interface LocalToolRegistryOptions {
     maxShellTimeoutMs?: number;
     enableReportFindings?: boolean;
     environment?: Readonly<Record<string, string>>;
+    sessionEnvironment?: (sessionId: string) => Promise<Readonly<Record<string, string>> | undefined>;
     sandbox?: BashSandboxRuntime;
     homeDirectory?: string;
     configRoot?: string;
@@ -44,6 +45,7 @@ export declare class LocalToolRegistry implements ToolRegistry {
     private readonly processRunner;
     private readonly enableReportFindings;
     private readonly environment;
+    private readonly sessionEnvironment;
     private readonly sandbox;
     private readonly homeDirectory;
     private readonly configRoot;

package/dist/tools/local-tools.js

@@ -509,6 +509,7 @@ export class LocalToolRegistry {
     processRunner;
     enableReportFindings;
     environment;
+    sessionEnvironment;
     sandbox;
     homeDirectory;
     configRoot;
@@ -526,6 +527,7 @@ export class LocalToolRegistry {
         this.maxShellTimeoutMs = options.maxShellTimeoutMs ?? 120_000;
         this.enableReportFindings = options.enableReportFindings ?? false;
         this.environment = options.environment;
+        this.sessionEnvironment = options.sessionEnvironment;
         this.sandbox = options.sandbox;
         this.homeDirectory = options.homeDirectory
             ? resolve(options.homeDirectory)
@@ -1258,18 +1260,21 @@ export class LocalToolRegistry {
             throw new Error('Prepared Bash call has no timeout');
         const rawCommand = stringInput(call.input, 'command');
         this.assertProtectedBashCommand(rawCommand, context);
-        const sandboxInput = {
+        const sandboxPolicyInput = {
             command: rawCommand,
             ...(call.input.dangerouslyDisableSandbox === true
                 ? { dangerouslyDisableSandbox: true }
                 : {}),
         };
-        const sandboxed = this.sandbox?.shouldUseSandbox(sandboxInput) ?? false;
+        const sandboxed = this.sandbox?.shouldUseSandbox(sandboxPolicyInput) ?? false;
         const shell = commandShell();
         let result;
         try {
+            const sessionEnvironment = context.sessionId
+                ? await this.sessionEnvironment?.(context.sessionId)
+                : undefined;
             const command = sandboxed
-                ? await this.sandbox?.wrapCommand(sandboxInput, {
+                ? await this.sandbox?.wrapCommand(sandboxPolicyInput, {
                     shell,
                     ...(context.signal ? { signal: context.signal } : {}),
                     commandId: call.id,
@@ -1280,7 +1285,9 @@ export class LocalToolRegistry {
                 args: commandShellArguments(command ?? rawCommand),
                 timeoutMs: timeout,
                 cwd: this.currentCwd(context),
-                ...(this.environment ? { env: this.environment } : {}),
+                ...(this.environment || sessionEnvironment
+                    ? { env: { ...this.environment, ...sessionEnvironment } }
+                    : {}),
                 ...(context.signal ? { signal: context.signal } : {}),
             });
         }

package/package.json

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