praxis-agent 0.20.21 → 0.21.0

package/README.md

@@ -170,14 +170,17 @@ Praxis ──────┘
 ```
 
 Praxis can resume Claude Code sessions, and Claude Code can resume compatible
-sessions written by Praxis. Ordinary Praxis session runtime always emits the
-verified Claude Code 2.1.208 write profile and never derives it from an
-installed Claude version; this fixed profile governs generated append and
-sidechain writes. Native fork creation is a separate restricted lossless copy
-path that preserves each existing source record's producer version, so it can
-copy specific black-box-verified foreign shapes such as the observed Claude
-Code 2.1.233 records; unsupported record shapes and unverified versions still
-fail closed and remain read-only. Maintainers can prove mixed-version Claude JSONL interoperability with
+sessions written by Praxis. Every semver-like Claude Code producer version is
+structurally validated and is read/write compatible when its entry shape is
+supported; schema adapters are selected from transcript entry structure rather
+than an installed or fixed producer version, and malformed or unsupported
+shapes fail closed before any write. Each transcript record keeps its original
+producer version, so supported shapes may be mixed across versions in one
+session. Native fork creation is a separate restricted lossless copy path that
+preserves each existing source record's producer version, so it can copy
+specific black-box-verified foreign shapes such as the observed Claude Code
+2.1.233 records; unsupported record shapes and unverified versions still fail
+closed and remain read-only. Maintainers can prove mixed-version Claude JSONL interoperability with
 `npm run test:cross-version-session-compat`, `test:cross-version-fork-compat`,
 `test:cross-version-sidechain-compat`, `test:cross-version-compaction-compat`,
 and `test:cross-version-resume-at-compat`, covering linear resume, native fork,

package/dist/application/background-agent-manager.js

@@ -233,15 +233,21 @@ export class BackgroundAgentManager {
         const task = this.tasks.get(agentId);
         if (!task)
             throw new Error(`No task found with ID: ${agentId}`);
-        if (options.block && task.promise) {
-            if (options.timeout === 0) {
-                await task.promise;
-            }
-            else {
-                await waitBounded(task.promise, options.timeout);
-            }
+        // A positive block wait settles a pending task chain — a stopped task's
+        // cleanup chain included — or lets the timeout elapse. Zero-timeout and
+        // non-blocking retrievals never wait.
+        if (options.block && options.timeout > 0 && task.promise) {
+            await waitBounded(task.promise, options.timeout);
         }
-        return this.formatOutput(task);
+        // The retrieval outcome reflects the task's state after any wait: success
+        // once terminal, not_ready for non-blocking retrievals, and timeout for a
+        // blocking retrieval whose window (including zero) closed while live.
+        const retrieval = task.status !== 'running'
+            ? 'success'
+            : options.block
+                ? 'timeout'
+                : 'not_ready';
+        return this.formatOutput(task, retrieval);
     }
     stop(agentId) {
         agentId = this.resolveRequired(agentId);
@@ -469,9 +475,8 @@ export class BackgroundAgentManager {
             durationMs: task.durationMs,
         };
     }
-    formatOutput(task) {
+    formatOutput(task, retrieval) {
         const output = task.result?.text ?? task.error ?? '';
-        const retrieval = task.status === 'running' ? 'not_ready' : 'success';
         return [
             `<retrieval_status>${retrieval}</retrieval_status>`,
             `<task_id>${task.spec.agentId}</task_id>`,

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

@@ -0,0 +1,96 @@
+import type { ModelMessage } from '../core/runtime.js';
+/** Versioned, explicit progress state for one session's extracted memory. */
+export interface SessionMemoryState {
+    schemaVersion: 1;
+    initialized: boolean;
+    lastObservedTokens: number;
+    lastObservedToolCalls: number;
+    lastSummarizedMessageId: string | null;
+    extractionStartedAt: number | null;
+    extractionCompletedAt: number | null;
+    extractionError: string | null;
+}
+export declare class SessionMemoryStateError extends Error {
+    readonly name = "SessionMemoryStateError";
+    constructor(message: string);
+}
+export declare class SessionMemoryTimeoutError extends Error {
+    readonly name = "SessionMemoryTimeoutError";
+    constructor(message: string);
+}
+export declare function createFreshSessionMemoryState(): SessionMemoryState;
+export interface SessionMemoryStoreOptions {
+    configRoot: string;
+    sessionId: string;
+}
+/**
+ * Durable sidecar for one session's extracted memory under
+ * `<configRoot>/praxis/session-memory/<sessionId>/`. All writes are atomic
+ * (same-directory temp file, fsync, then rename) and version-checked. Never
+ * touches shared Claude transcript entries.
+ */
+export declare class SessionMemoryStore {
+    private readonly directory;
+    private readonly stateFile;
+    private readonly summaryFile;
+    constructor(options: SessionMemoryStoreOptions);
+    load(): Promise<SessionMemoryState>;
+    loadSummary(): Promise<string>;
+    writeSummary(summary: string): Promise<void>;
+    writeState(state: SessionMemoryState): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface SessionMemoryExtractorInput {
+    summary: string;
+    tokens: number;
+    toolCalls: number;
+    messages?: readonly ModelMessage[];
+}
+export type SessionMemoryExtractor = (input: SessionMemoryExtractorInput) => Promise<string> | string;
+export interface SessionMemoryControllerOptions {
+    store: SessionMemoryStore;
+    extractor: SessionMemoryExtractor;
+    initTokens?: number;
+    updateTokens?: number;
+    updateToolCalls?: number;
+    waitTimeoutMs?: number;
+}
+/**
+ * Serialized extraction lifecycle for one session. Concurrent callers of
+ * `observe` share one in-flight extraction promise, so two extractors never
+ * run for the same session. A persisted extraction that never completed is
+ * marked failed on reopen and can be retried.
+ */
+export declare class SessionMemoryController {
+    private readonly options;
+    private readonly initTokens;
+    private readonly updateTokens;
+    private readonly updateToolCalls;
+    private readonly waitTimeoutMs;
+    private stateValue;
+    private summaryValue;
+    private inFlight;
+    private loading;
+    private observedTokens;
+    private observedToolCalls;
+    constructor(options: SessionMemoryControllerOptions);
+    observe(tokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+    /**
+     * Adds non-negative deltas to the current cumulative observed totals and
+     * delegates to the serialized extraction path with those cumulative totals.
+     * The persisted counters only advance once an extraction succeeds.
+     */
+    observeDelta(inputTokens: number, toolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+    /** Safe snapshot of the loaded durable summary; empty when none exists. */
+    summary(): Promise<string>;
+    /** Safe snapshot of the loaded session memory state. */
+    state(): Promise<SessionMemoryState>;
+    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    waitForIdle(): Promise<void>;
+    clear(): Promise<void>;
+    private ensureLoaded;
+    private loadState;
+    private isExtractionDue;
+    private runExtraction;
+}
+//# sourceMappingURL=session-memory.d.ts.map

package/dist/application/session-memory.js

@@ -0,0 +1,383 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { isClaudeSessionId } from '../compatibility/claude/paths.js';
+import { writeFileAtomically } from '../platform/atomic-write.js';
+export class SessionMemoryStateError extends Error {
+    name = 'SessionMemoryStateError';
+    constructor(message) {
+        super(message);
+    }
+}
+export class SessionMemoryTimeoutError extends Error {
+    name = 'SessionMemoryTimeoutError';
+    constructor(message) {
+        super(message);
+    }
+}
+export function createFreshSessionMemoryState() {
+    return {
+        schemaVersion: 1,
+        initialized: false,
+        lastObservedTokens: 0,
+        lastObservedToolCalls: 0,
+        lastSummarizedMessageId: null,
+        extractionStartedAt: null,
+        extractionCompletedAt: null,
+        extractionError: null,
+    };
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isNullableTimestamp(value) {
+    return (value === null ||
+        (typeof value === 'number' && Number.isFinite(value) && value >= 0));
+}
+function assertValidSessionMemoryState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new SessionMemoryStateError('Session memory state must be an object');
+    }
+    const record = value;
+    if (record.schemaVersion !== 1) {
+        throw new SessionMemoryStateError(`Unsupported session memory schema version: ${String(record.schemaVersion)}`);
+    }
+    if (typeof record.initialized !== 'boolean') {
+        throw new SessionMemoryStateError('Session memory state initialized must be a boolean');
+    }
+    if (!isNonNegativeSafeInteger(record.lastObservedTokens)) {
+        throw new SessionMemoryStateError('Session memory state lastObservedTokens must be a non-negative safe integer');
+    }
+    if (!isNonNegativeSafeInteger(record.lastObservedToolCalls)) {
+        throw new SessionMemoryStateError('Session memory state lastObservedToolCalls must be a non-negative safe integer');
+    }
+    if (record.lastSummarizedMessageId !== null &&
+        typeof record.lastSummarizedMessageId !== 'string') {
+        throw new SessionMemoryStateError('Session memory state lastSummarizedMessageId must be a string or null');
+    }
+    if (!isNullableTimestamp(record.extractionStartedAt)) {
+        throw new SessionMemoryStateError('Session memory state extractionStartedAt must be a non-negative timestamp or null');
+    }
+    if (!isNullableTimestamp(record.extractionCompletedAt)) {
+        throw new SessionMemoryStateError('Session memory state extractionCompletedAt must be a non-negative timestamp or null');
+    }
+    if (record.extractionError !== null &&
+        typeof record.extractionError !== 'string') {
+        throw new SessionMemoryStateError('Session memory state extractionError must be a string or null');
+    }
+}
+function parseSessionMemoryState(source) {
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new SessionMemoryStateError('Session memory state is not valid JSON');
+    }
+    assertValidSessionMemoryState(value);
+    return value;
+}
+/**
+ * Durable sidecar for one session's extracted memory under
+ * `<configRoot>/praxis/session-memory/<sessionId>/`. All writes are atomic
+ * (same-directory temp file, fsync, then rename) and version-checked. Never
+ * touches shared Claude transcript entries.
+ */
+export class SessionMemoryStore {
+    directory;
+    stateFile;
+    summaryFile;
+    constructor(options) {
+        if (typeof options.configRoot !== 'string' ||
+            options.configRoot.length === 0) {
+            throw new SessionMemoryStateError('Session memory configRoot must be a non-empty string');
+        }
+        if (!isClaudeSessionId(options.sessionId)) {
+            throw new SessionMemoryStateError(`Invalid session memory session ID: ${options.sessionId}`);
+        }
+        this.directory = resolve(options.configRoot, 'praxis', 'session-memory', options.sessionId);
+        this.stateFile = join(this.directory, 'state.json');
+        this.summaryFile = join(this.directory, 'summary.md');
+    }
+    async load() {
+        let source;
+        try {
+            source = await readFile(this.stateFile, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return createFreshSessionMemoryState();
+            }
+            throw error;
+        }
+        return parseSessionMemoryState(source);
+    }
+    async loadSummary() {
+        let source;
+        try {
+            source = await readFile(this.summaryFile, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+        return source;
+    }
+    async writeSummary(summary) {
+        if (typeof summary !== 'string' || summary.trim().length === 0) {
+            throw new SessionMemoryStateError('Session memory summary must be a non-empty string');
+        }
+        await writeFileAtomically(this.summaryFile, summary);
+    }
+    async writeState(state) {
+        assertValidSessionMemoryState(state);
+        const existing = await this.load();
+        if (state.lastObservedTokens < existing.lastObservedTokens ||
+            state.lastObservedToolCalls < existing.lastObservedToolCalls) {
+            throw new SessionMemoryStateError('Session memory observed counters must be monotonic');
+        }
+        await writeFileAtomically(this.stateFile, `${JSON.stringify(state, null, 2)}\n`);
+    }
+    async clear() {
+        await Promise.all([
+            rm(this.stateFile, { force: true }),
+            rm(this.summaryFile, { force: true }),
+        ]);
+    }
+}
+/**
+ * Serialized extraction lifecycle for one session. Concurrent callers of
+ * `observe` share one in-flight extraction promise, so two extractors never
+ * run for the same session. A persisted extraction that never completed is
+ * marked failed on reopen and can be retried.
+ */
+export class SessionMemoryController {
+    options;
+    initTokens;
+    updateTokens;
+    updateToolCalls;
+    waitTimeoutMs;
+    stateValue = null;
+    summaryValue = '';
+    inFlight = null;
+    loading = null;
+    observedTokens = 0;
+    observedToolCalls = 0;
+    constructor(options) {
+        this.options = options;
+        this.initTokens = options.initTokens ?? 10_000;
+        this.updateTokens = options.updateTokens ?? 5_000;
+        this.updateToolCalls = options.updateToolCalls ?? 20;
+        this.waitTimeoutMs = options.waitTimeoutMs ?? 30_000;
+        for (const [name, value] of [
+            ['initTokens', this.initTokens],
+            ['updateTokens', this.updateTokens],
+            ['updateToolCalls', this.updateToolCalls],
+        ]) {
+            if (!isNonNegativeSafeInteger(value) || value === 0) {
+                throw new SessionMemoryStateError(`Session memory ${name} must be a positive safe integer`);
+            }
+        }
+        if (typeof this.waitTimeoutMs !== 'number' ||
+            !Number.isFinite(this.waitTimeoutMs) ||
+            this.waitTimeoutMs <= 0) {
+            throw new SessionMemoryStateError('Session memory waitTimeoutMs must be a positive number');
+        }
+    }
+    async observe(tokens, toolCalls, messageId, messages) {
+        await this.ensureLoaded();
+        const state = this.stateValue;
+        if (state === null) {
+            throw new SessionMemoryStateError('Session memory state is unavailable');
+        }
+        if (!isNonNegativeSafeInteger(tokens) ||
+            !isNonNegativeSafeInteger(toolCalls)) {
+            throw new SessionMemoryStateError('Session memory observed counters must be non-negative safe integers');
+        }
+        if (typeof messageId !== 'string' || messageId.length === 0) {
+            throw new SessionMemoryStateError('Session memory message ID must be a non-empty string');
+        }
+        if (tokens < state.lastObservedTokens ||
+            toolCalls < state.lastObservedToolCalls) {
+            throw new SessionMemoryStateError(`Session memory observed counters regressed (tokens ${tokens} < ${state.lastObservedTokens}, toolCalls ${toolCalls} < ${state.lastObservedToolCalls})`);
+        }
+        this.observedTokens = Math.max(this.observedTokens, tokens);
+        this.observedToolCalls = Math.max(this.observedToolCalls, toolCalls);
+        if (!this.isExtractionDue(this.observedTokens, this.observedToolCalls)) {
+            return false;
+        }
+        if (this.inFlight === null) {
+            const extraction = this.runExtraction(this.observedTokens, this.observedToolCalls, messageId, messages);
+            this.inFlight = extraction;
+            extraction
+                .catch(() => undefined)
+                .finally(() => {
+                if (this.inFlight === extraction)
+                    this.inFlight = null;
+            });
+        }
+        return true;
+    }
+    /**
+     * Adds non-negative deltas to the current cumulative observed totals and
+     * delegates to the serialized extraction path with those cumulative totals.
+     * The persisted counters only advance once an extraction succeeds.
+     */
+    async observeDelta(inputTokens, toolCalls, messageId, messages) {
+        await this.ensureLoaded();
+        const state = this.stateValue;
+        if (state === null) {
+            throw new SessionMemoryStateError('Session memory state is unavailable');
+        }
+        if (!isNonNegativeSafeInteger(inputTokens) ||
+            !isNonNegativeSafeInteger(toolCalls)) {
+            throw new SessionMemoryStateError('Session memory observed deltas must be non-negative safe integers');
+        }
+        if (typeof messageId !== 'string' || messageId.length === 0) {
+            throw new SessionMemoryStateError('Session memory message ID must be a non-empty string');
+        }
+        this.observedTokens += inputTokens;
+        this.observedToolCalls += toolCalls;
+        return this.observe(this.observedTokens, this.observedToolCalls, messageId, messages);
+    }
+    /** Safe snapshot of the loaded durable summary; empty when none exists. */
+    async summary() {
+        await this.ensureLoaded();
+        return this.summaryValue;
+    }
+    /** Safe snapshot of the loaded session memory state. */
+    async state() {
+        await this.ensureLoaded();
+        if (this.stateValue === null) {
+            throw new SessionMemoryStateError('Session memory state is unavailable');
+        }
+        return { ...this.stateValue };
+    }
+    /** Resolves when no extraction is running; rejects on failure or timeout. */
+    async waitForIdle() {
+        await this.ensureLoaded();
+        const extraction = this.inFlight;
+        if (extraction === null)
+            return;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new SessionMemoryTimeoutError(`Session memory extraction did not complete within ${this.waitTimeoutMs}ms`)), this.waitTimeoutMs);
+        });
+        try {
+            await Promise.race([extraction, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    async clear() {
+        await this.ensureLoaded();
+        if (this.inFlight !== null) {
+            throw new SessionMemoryStateError('Session memory cannot be cleared while extraction is in progress');
+        }
+        await this.options.store.clear();
+        const fresh = createFreshSessionMemoryState();
+        this.stateValue = fresh;
+        this.observedTokens = fresh.lastObservedTokens;
+        this.observedToolCalls = fresh.lastObservedToolCalls;
+        this.summaryValue = '';
+    }
+    ensureLoaded() {
+        if (this.loading !== null)
+            return this.loading;
+        this.loading = this.loadState().catch((error) => {
+            this.loading = null;
+            throw error;
+        });
+        return this.loading;
+    }
+    async loadState() {
+        const [state, summary] = await Promise.all([
+            this.options.store.load(),
+            this.options.store.loadSummary(),
+        ]);
+        if (state.extractionStartedAt !== null &&
+            state.extractionCompletedAt === null) {
+            const elapsed = Date.now() - state.extractionStartedAt;
+            const recovered = {
+                ...state,
+                extractionStartedAt: null,
+                extractionCompletedAt: null,
+                extractionError: elapsed >= this.waitTimeoutMs
+                    ? `Session memory extraction is stale after ${elapsed}ms`
+                    : 'Session memory extraction was interrupted',
+            };
+            await this.options.store.writeState(recovered);
+            this.stateValue = recovered;
+        }
+        else {
+            this.stateValue = state;
+        }
+        this.observedTokens = this.stateValue.lastObservedTokens;
+        this.observedToolCalls = this.stateValue.lastObservedToolCalls;
+        this.summaryValue = summary;
+    }
+    isExtractionDue(tokens, toolCalls) {
+        const state = this.stateValue;
+        if (state === null)
+            return false;
+        if (!state.initialized)
+            return tokens >= this.initTokens;
+        return (tokens - state.lastObservedTokens >= this.updateTokens ||
+            toolCalls - state.lastObservedToolCalls >= this.updateToolCalls);
+    }
+    async runExtraction(tokens, toolCalls, messageId, messages) {
+        const state = this.stateValue;
+        if (state === null) {
+            throw new SessionMemoryStateError('Session memory state is unavailable');
+        }
+        this.stateValue = {
+            ...state,
+            extractionStartedAt: Date.now(),
+            extractionCompletedAt: null,
+            extractionError: null,
+        };
+        await this.options.store.writeState(this.stateValue);
+        try {
+            const summary = await this.options.extractor({
+                summary: this.summaryValue,
+                tokens,
+                toolCalls,
+                ...(messages?.length ? { messages } : {}),
+            });
+            if (typeof summary !== 'string' || summary.trim().length === 0) {
+                throw new SessionMemoryStateError('Session memory extractor returned an empty summary');
+            }
+            // Persist the summary before the completed state so a crash in between
+            // is recovered as a stale extraction and safely re-extracted.
+            await this.options.store.writeSummary(summary);
+            this.stateValue = {
+                ...this.stateValue,
+                initialized: true,
+                lastObservedTokens: tokens,
+                lastObservedToolCalls: toolCalls,
+                lastSummarizedMessageId: messageId,
+                extractionStartedAt: null,
+                extractionCompletedAt: Date.now(),
+                extractionError: null,
+            };
+            await this.options.store.writeState(this.stateValue);
+            this.summaryValue = summary;
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error.message : String(error);
+            this.stateValue = {
+                ...this.stateValue,
+                extractionStartedAt: null,
+                extractionCompletedAt: null,
+                extractionError: failure,
+            };
+            await this.options.store
+                .writeState(this.stateValue)
+                .catch(() => undefined);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=session-memory.js.map

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

@@ -17,6 +17,7 @@ import { type ScheduledPrompt } from './scheduled-prompt-manager.js';
 import { type WorkflowTaskSnapshot } from './workflow-manager.js';
 import type { WorkspaceContext } from './session-worktree.js';
 import { type ClaudeSessionCostSnapshot } from './session-cost-tracker.js';
+import { type ClaudeToolRole } from '../tools/claude-capabilities.js';
 import type { ClaudeInteractiveToolManager } from '../tools/claude-interactive-tools.js';
 import type { ClaudePermissionMode } from '../permissions/claude-permission-resolver.js';
 import type { ClaudeMcpRuntime, ClaudeMcpServerStatus, ClaudeMcpToolInspection } from '../mcp/claude-mcp-tools.js';
@@ -45,6 +46,10 @@ export interface ClaudeSessionServiceOptions {
     subagentToolNames?: readonly string[];
     taskToolNames?: readonly string[];
     scheduledToolNames?: readonly string[];
+    /** Runtime gates for Claude capability-driven tool exposure. */
+    toolRole?: ClaudeToolRole;
+    toolCapabilityEnvironment?: Readonly<Record<string, string | undefined>>;
+    simpleMode?: boolean;
     enableDynamicWakeups?: boolean;
     enableWorkflows?: boolean;
     providerForModel?: (model: string) => ModelProvider;
@@ -63,6 +68,10 @@ export interface ClaudeSessionServiceOptions {
     brief?: boolean;
     collectMetrics?: boolean;
     sessionPersistence?: boolean;
+    /** Enable durable per-session memory extraction and injection. Defaults to
+     *  enabled whenever session persistence is enabled; ignored when
+     *  `sessionPersistence === false`. */
+    enableSessionMemory?: boolean;
     sessionKind?: 'bg';
     workspace?: WorkspaceContext;
     initialWorktree?: boolean;
@@ -169,6 +178,7 @@ export declare class ClaudeSessionService {
     private readonly sessionCostTrackers;
     private activeCostSessionId;
     private closeCostSavePromise;
+    private readonly sessionMemoryControllers;
     private runtimeCwd;
     constructor(options: ClaudeSessionServiceOptions);
     nextScheduledPrompt(signal?: AbortSignal): Promise<ScheduledPrompt | null>;
@@ -258,6 +268,14 @@ export declare class ClaudeSessionService {
     private mainAgentSystemPrompt;
     private assembledSystemMessages;
     private contextBudget;
+    private sessionMemoryEnabled;
+    private sessionMemoryController;
+    private sessionMemoryMessage;
+    private boundSessionMemorySummary;
+    private formatSessionMemoryConversation;
+    private extractSessionMemory;
+    private toolCapabilities;
+    private capabilityToolNames;
     private append;
     private logicalTailUuid;
 }