praxis-agent 0.32.0 → 0.34.0

package/dist/persistence/claude-transcript-store.js

@@ -2,8 +2,11 @@ import { createHash } from 'node:crypto';
 import { mkdir, open, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { TextDecoder } from 'node:util';
+import { isClaudeDurableLastPromptSnapshot } from '../compatibility/claude/history.js';
+import { isClaudeDurableMetadataType } from '../compatibility/claude/session-metadata.js';
 import { getClaudeContentBlocks, indexClaudeToolLinks, recoverClaudeToolResultLinks, } from '../compatibility/claude/tool-links.js';
 import { ExclusiveFileLease } from '../platform/exclusive-file-lease.js';
+import { readClaudeSessionIndex, } from './claude-session-index.js';
 export class ClaudeTranscriptParseError extends Error {
     lineNumber;
     byteOffset;
@@ -19,6 +22,7 @@ const NON_TAIL_ENTRY_TYPES = new Set([
     'agent-color',
     'agent-name',
     'agent-setting',
+    'ai-title',
     'custom-title',
     'file-history-delta',
     'file-history-snapshot',
@@ -26,6 +30,8 @@ const NON_TAIL_ENTRY_TYPES = new Set([
     'pr-link',
     'queue-operation',
     'relocated',
+    'mode',
+    'tag',
     'worktree-state',
 ]);
 export function classifyTranscriptAppend(written, previousByteLength, encodedLine) {
@@ -63,7 +69,9 @@ function tailsMatch(left, right) {
         left.newlineTerminated === right.newlineTerminated);
 }
 function tailLogicalUuid(tail) {
-    return tail.branchParentUuid ?? tail.lastUuid;
+    return 'branchParentUuid' in tail
+        ? (tail.branchParentUuid ?? null)
+        : tail.lastUuid;
 }
 function getEntryUuid(entry) {
     if (typeof entry.uuid === 'string')
@@ -77,6 +85,10 @@ function findLogicalTailUuid(entries) {
         const entry = entries[index];
         if (!entry)
             continue;
+        if (entry.type === 'last-prompt' &&
+            isClaudeDurableLastPromptSnapshot(entries, index)) {
+            continue;
+        }
         const uuid = getEntryUuid(entry);
         if (uuid)
             return uuid;
@@ -173,7 +185,9 @@ export class ClaudeTranscriptStore {
                     message: error instanceof Error ? error.message : String(error),
                 };
                 if (!recover) {
-                    throw new ClaudeTranscriptParseError(issue.lineNumber, issue.byteOffset, { cause: error });
+                    throw new ClaudeTranscriptParseError(index + 1, byteOffset, {
+                        cause: error,
+                    });
                 }
                 break;
             }
@@ -266,8 +280,10 @@ export class ClaudeTranscriptStore {
         try {
             const value = await operation({
                 load: () => this.load(),
+                loadIndex: () => readClaudeSessionIndex(this.sessionFile, this.schema),
                 append: (expectedTail, entry) => this.appendUnderLease(expectedTail, entry),
                 appendMany: (expectedTail, entries) => this.appendManyUnderLease(expectedTail, entries),
+                appendMetadataSnapshot: (expectedTail, entries) => this.appendMetadataSnapshotUnderLease(expectedTail, entries),
             });
             return { status: 'completed', value };
         }
@@ -314,7 +330,11 @@ export class ClaudeTranscriptStore {
                 }
             }
             else if (entry.type === 'last-prompt') {
-                if (entry.leafUuid !== logicalTailUuid) {
+                const isDurableSnapshot = history.some((candidate) => candidate.type === 'last-prompt' &&
+                    candidate.sessionId === entry.sessionId &&
+                    candidate.leafUuid === entry.leafUuid &&
+                    candidate.lastPrompt === entry.lastPrompt);
+                if (entry.leafUuid !== logicalTailUuid && !isDurableSnapshot) {
                     staleLastPromptLeaf = true;
                     continue;
                 }
@@ -378,6 +398,61 @@ export class ClaudeTranscriptStore {
                 : { ...tail, branchParentUuid },
         };
     }
+    async appendMetadataSnapshotUnderLease(expectedTail, entries) {
+        if (entries.length === 0) {
+            throw new Error('Cannot append an empty Claude metadata snapshot');
+        }
+        if (entries.some((entry) => !isClaudeDurableMetadataType(entry.type))) {
+            throw new Error('Claude metadata snapshot contains a structural entry');
+        }
+        if (new Set(entries.map((entry) => entry.type)).size !== entries.length ||
+            new Set(entries.map((entry) => entry.sessionId)).size !== 1 ||
+            typeof entries[0]?.sessionId !== 'string') {
+            throw new Error('Claude metadata snapshot must contain one session record per type');
+        }
+        const current = await readClaudeSessionIndex(this.sessionFile, this.schema);
+        if (current.issue !== null) {
+            throw new Error('Cannot append metadata to a corrupt Claude transcript');
+        }
+        if (current.byteLength !== expectedTail.byteLength ||
+            current.tail.lastLineHash !== expectedTail.lastLineHash ||
+            current.newlineTerminated !== expectedTail.newlineTerminated) {
+            return { status: 'conflict', reason: 'tail-changed' };
+        }
+        if (!current.newlineTerminated) {
+            throw new Error('Claude transcript is not newline-terminated');
+        }
+        const lines = entries.map((entry) => this.schema.serializeForAppend(entry));
+        const encoded = Buffer.from(`${lines.join('\n')}\n`);
+        const sessionHandle = await open(this.sessionFile, 'a');
+        try {
+            const before = await sessionHandle.stat();
+            if (before.size !== expectedTail.byteLength) {
+                return { status: 'conflict', reason: 'tail-changed' };
+            }
+            await sessionHandle.writeFile(encoded);
+            await sessionHandle.sync();
+            const after = await sessionHandle.stat();
+            if (after.size !== expectedTail.byteLength + encoded.length) {
+                return { status: 'conflict', reason: 'interleaved-write' };
+            }
+        }
+        finally {
+            await sessionHandle.close();
+        }
+        const last = entries.at(-1);
+        return {
+            status: 'appended',
+            tail: {
+                byteLength: expectedTail.byteLength + encoded.length,
+                lastLineHash: hashLine(Buffer.from(lines.at(-1) ?? '')),
+                lastUuid: typeof last?.leafUuid === 'string'
+                    ? last.leafUuid
+                    : expectedTail.lastUuid,
+                newlineTerminated: true,
+            },
+        };
+    }
     serializeNewSidechain(entries) {
         const lines = [];
         const history = [];

package/dist/persistence/in-memory-transcript-store.js

@@ -47,6 +47,7 @@ export class InMemoryTranscriptStore {
                 load: () => this.load(),
                 append: (expectedTail, entry) => this.appendMany(expectedTail, [entry]),
                 appendMany: (expectedTail, entries) => this.appendMany(expectedTail, entries),
+                appendMetadataSnapshot: (expectedTail, entries) => this.appendMany(expectedTail, entries),
             });
             return { status: 'completed', value };
         }

package/dist/persistence/subagent-lifecycle-store.d.ts

@@ -0,0 +1,66 @@
+export type PersistedSubagentStatus = 'running' | 'completed' | 'failed' | 'killed';
+export interface PersistedSubagentRunResult {
+    text: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadInputTokens?: number;
+        cacheCreationInputTokens?: number;
+        webSearchRequests?: number;
+        contextWindow?: number;
+        maxOutputTokens?: number;
+    };
+    modelUsage?: Record<string, PersistedSubagentRunResult['usage']>;
+    durationApiMs?: number;
+    durationApiWithoutRetriesMs?: number;
+    toolUseCount: number;
+    durationMs: number;
+    isolationPath?: string;
+    isolationRetained?: boolean;
+    isolationWarning?: string;
+}
+export interface PersistedSubagentNotification {
+    id: string;
+    status: 'completed' | 'failed' | 'killed';
+    toolUseId: string;
+    result: PersistedSubagentRunResult | null;
+    error: string | null;
+    consumed: boolean;
+    accounting?: {
+        kind: 'detached';
+        model: string;
+        delivered: boolean;
+    };
+}
+export interface PersistedSubagentLifecycle {
+    version: 1;
+    sessionId: string;
+    agentId: string;
+    status: PersistedSubagentStatus;
+    updatedAt: string;
+    transcriptBytes?: number;
+    detail?: string;
+    result?: PersistedSubagentRunResult;
+    notifications?: PersistedSubagentNotification[];
+}
+/** Praxis-private state for a retained Claude-compatible sidechain. */
+export declare class SubagentLifecycleStore {
+    private readonly sessionId;
+    private readonly agentId;
+    private readonly transcriptPath?;
+    private readonly path;
+    private mutation;
+    constructor(praxisRoot: string, sessionId: string, agentId: string, transcriptPath?: string | undefined);
+    read(): Promise<PersistedSubagentLifecycle | null>;
+    write(status: PersistedSubagentStatus, detail?: string, terminal?: {
+        result: PersistedSubagentRunResult;
+        notification?: Omit<PersistedSubagentNotification, 'result' | 'consumed'>;
+    }): Promise<void>;
+    acknowledgeNotification(id: string): Promise<void>;
+    prepareNotificationDetached(id: string, model: string): Promise<void>;
+    confirmNotificationDetached(id: string): Promise<void>;
+    matchesTranscript(record: PersistedSubagentLifecycle): Promise<boolean>;
+    private record;
+    private mutate;
+}
+//# sourceMappingURL=subagent-lifecycle-store.d.ts.map

package/dist/persistence/subagent-lifecycle-store.js

@@ -0,0 +1,299 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isClaudeSessionId } from '../compatibility/claude/paths.js';
+import { isClaudeAgentId } from '../compatibility/claude/sidechain.js';
+import { writeFileAtomically } from '../platform/atomic-write.js';
+const statuses = new Set([
+    'running',
+    'completed',
+    'failed',
+    'killed',
+]);
+function assertIdentity(sessionId, agentId) {
+    if (!isClaudeSessionId(sessionId)) {
+        throw new Error(`Invalid subagent lifecycle session ID: ${sessionId}`);
+    }
+    if (!isClaudeAgentId(agentId)) {
+        throw new Error(`Invalid subagent lifecycle agent ID: ${agentId}`);
+    }
+}
+function isNonnegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function isNonnegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isUsage(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const usage = value;
+    if (!isNonnegativeInteger(usage.inputTokens) ||
+        !isNonnegativeInteger(usage.outputTokens)) {
+        return false;
+    }
+    for (const field of [
+        'cacheReadInputTokens',
+        'cacheCreationInputTokens',
+        'webSearchRequests',
+    ]) {
+        if (usage[field] !== undefined && !isNonnegativeInteger(usage[field])) {
+            return false;
+        }
+    }
+    for (const field of ['contextWindow', 'maxOutputTokens']) {
+        if (usage[field] !== undefined &&
+            (!Number.isSafeInteger(usage[field]) || Number(usage[field]) < 1)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isRunResult(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const result = value;
+    if (typeof result.text !== 'string' ||
+        !isUsage(result.usage) ||
+        !isNonnegativeInteger(result.toolUseCount) ||
+        !isNonnegativeInteger(result.durationMs)) {
+        return false;
+    }
+    if (result.modelUsage !== undefined &&
+        (typeof result.modelUsage !== 'object' ||
+            result.modelUsage === null ||
+            Array.isArray(result.modelUsage) ||
+            !Object.values(result.modelUsage).every(isUsage))) {
+        return false;
+    }
+    for (const field of ['durationApiMs', 'durationApiWithoutRetriesMs']) {
+        if (result[field] !== undefined && !isNonnegativeNumber(result[field])) {
+            return false;
+        }
+    }
+    return ((result.isolationPath === undefined ||
+        typeof result.isolationPath === 'string') &&
+        (result.isolationRetained === undefined ||
+            typeof result.isolationRetained === 'boolean') &&
+        (result.isolationWarning === undefined ||
+            typeof result.isolationWarning === 'string'));
+}
+function isNotification(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const notification = value;
+    const accounting = notification.accounting;
+    return (typeof notification.id === 'string' &&
+        /^[0-9a-f-]{36}$/iu.test(notification.id) &&
+        ['completed', 'failed', 'killed'].includes(String(notification.status)) &&
+        typeof notification.toolUseId === 'string' &&
+        notification.toolUseId.length > 0 &&
+        (notification.result === null || isRunResult(notification.result)) &&
+        (notification.error === null || typeof notification.error === 'string') &&
+        typeof notification.consumed === 'boolean' &&
+        (accounting === undefined ||
+            (typeof accounting === 'object' &&
+                accounting !== null &&
+                !Array.isArray(accounting) &&
+                accounting.kind === 'detached' &&
+                typeof accounting.model === 'string' &&
+                String(accounting.model).trim().length >
+                    0 &&
+                typeof accounting.delivered === 'boolean')));
+}
+/** Praxis-private state for a retained Claude-compatible sidechain. */
+export class SubagentLifecycleStore {
+    sessionId;
+    agentId;
+    transcriptPath;
+    path;
+    mutation = Promise.resolve();
+    constructor(praxisRoot, sessionId, agentId, transcriptPath) {
+        this.sessionId = sessionId;
+        this.agentId = agentId;
+        this.transcriptPath = transcriptPath;
+        assertIdentity(sessionId, agentId);
+        this.path = join(praxisRoot, 'subagent-lifecycle', sessionId, `${agentId}.json`);
+    }
+    async read() {
+        let source;
+        try {
+            source = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch (error) {
+            throw new Error(`Corrupt subagent lifecycle state: ${this.path}`, {
+                cause: error,
+            });
+        }
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error(`Invalid subagent lifecycle state: ${this.path}`);
+        }
+        const record = value;
+        if (record.version !== 1 ||
+            record.sessionId !== this.sessionId ||
+            record.agentId !== this.agentId ||
+            typeof record.status !== 'string' ||
+            !statuses.has(record.status) ||
+            typeof record.updatedAt !== 'string' ||
+            Number.isNaN(Date.parse(record.updatedAt)) ||
+            (record.transcriptBytes !== undefined &&
+                !isNonnegativeInteger(record.transcriptBytes)) ||
+            (record.detail !== undefined && typeof record.detail !== 'string') ||
+            (record.result !== undefined && !isRunResult(record.result)) ||
+            (record.notifications !== undefined &&
+                (!Array.isArray(record.notifications) ||
+                    !record.notifications.every(isNotification)))) {
+            throw new Error(`Invalid subagent lifecycle state: ${this.path}`);
+        }
+        return record;
+    }
+    write(status, detail, terminal) {
+        return this.mutate(async (current) => {
+            const notifications = [...(current?.notifications ?? [])];
+            if (terminal?.notification) {
+                notifications.push({
+                    ...terminal.notification,
+                    result: terminal.result,
+                    consumed: false,
+                });
+            }
+            return this.record({
+                status,
+                ...(detail === undefined ? {} : { detail }),
+                ...(terminal === undefined ? {} : { result: terminal.result }),
+                ...(notifications.length === 0 ? {} : { notifications }),
+            });
+        });
+    }
+    acknowledgeNotification(id) {
+        return this.mutate(async (current) => {
+            if (!current) {
+                throw new Error(`Missing subagent lifecycle state: ${this.path}`);
+            }
+            const notifications = current.notifications ?? [];
+            const matched = notifications.find((notification) => notification.id === id && !notification.consumed);
+            if (!matched)
+                return current;
+            return this.record({
+                status: current.status,
+                ...(current.detail === undefined ? {} : { detail: current.detail }),
+                ...(current.result === undefined ? {} : { result: current.result }),
+                notifications: notifications.map((notification) => notification.id === id
+                    ? { ...notification, consumed: true }
+                    : notification),
+            }, { transcriptBytes: current.transcriptBytes });
+        });
+    }
+    prepareNotificationDetached(id, model) {
+        if (model.trim().length === 0) {
+            throw new Error('Detached notification model must not be blank');
+        }
+        return this.mutate(async (current) => {
+            if (!current) {
+                throw new Error(`Missing subagent lifecycle state: ${this.path}`);
+            }
+            const notifications = current.notifications ?? [];
+            const matched = notifications.find((notification) => notification.id === id);
+            if (!matched || matched.accounting?.kind === 'detached')
+                return current;
+            return this.record({
+                status: current.status,
+                ...(current.detail === undefined ? {} : { detail: current.detail }),
+                ...(current.result === undefined ? {} : { result: current.result }),
+                notifications: notifications.map((notification) => notification.id === id
+                    ? {
+                        ...notification,
+                        accounting: {
+                            kind: 'detached',
+                            model,
+                            delivered: false,
+                        },
+                    }
+                    : notification),
+            }, { transcriptBytes: current.transcriptBytes });
+        });
+    }
+    confirmNotificationDetached(id) {
+        return this.mutate(async (current) => {
+            if (!current) {
+                throw new Error(`Missing subagent lifecycle state: ${this.path}`);
+            }
+            const notifications = current.notifications ?? [];
+            const matched = notifications.find((notification) => notification.id === id);
+            if (!matched?.accounting || matched.accounting.delivered)
+                return current;
+            return this.record({
+                status: current.status,
+                ...(current.detail === undefined ? {} : { detail: current.detail }),
+                ...(current.result === undefined ? {} : { result: current.result }),
+                notifications: notifications.map((notification) => notification.id === id && notification.accounting
+                    ? {
+                        ...notification,
+                        accounting: { ...notification.accounting, delivered: true },
+                    }
+                    : notification),
+            }, { transcriptBytes: current.transcriptBytes });
+        });
+    }
+    async matchesTranscript(record) {
+        if (record.transcriptBytes === undefined ||
+            this.transcriptPath === undefined) {
+            return true;
+        }
+        try {
+            return (await stat(this.transcriptPath)).size === record.transcriptBytes;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    }
+    async record(value, boundary) {
+        let transcriptBytes = boundary?.transcriptBytes;
+        if (boundary === undefined && this.transcriptPath !== undefined) {
+            try {
+                transcriptBytes = (await stat(this.transcriptPath)).size;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return {
+            version: 1,
+            sessionId: this.sessionId,
+            agentId: this.agentId,
+            status: value.status,
+            updatedAt: new Date().toISOString(),
+            ...(transcriptBytes === undefined ? {} : { transcriptBytes }),
+            ...(value.detail === undefined ? {} : { detail: value.detail }),
+            ...(value.result === undefined ? {} : { result: value.result }),
+            ...(value.notifications === undefined
+                ? {}
+                : { notifications: value.notifications }),
+        };
+    }
+    mutate(mutation) {
+        const operation = this.mutation.then(async () => {
+            const record = await mutation(await this.read());
+            await writeFileAtomically(this.path, `${JSON.stringify(record)}\n`, {
+                mode: 0o600,
+            });
+        });
+        this.mutation = operation.catch(() => undefined);
+        return operation;
+    }
+}
+//# sourceMappingURL=subagent-lifecycle-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",
@@ -80,6 +80,7 @@
     "test:pr-link-compat": "npm run build && node scripts/verify-pr-link-compatibility.mjs",
     "test:resume-at-compat": "npm run build && node scripts/verify-resume-session-at-compatibility.mjs",
     "test:resume-selector-compat": "npm run build && node scripts/verify-resume-selector-compatibility.mjs",
+    "test:session-metadata-compat": "npm run build && node scripts/verify-session-metadata-compatibility.mjs",
     "test:thinking-compat": "npm run build && node scripts/verify-thinking-controls.mjs",
     "test:memory-import-compat": "npm run build && node scripts/verify-memory-import-compatibility.mjs",
     "test:tui-compat": "npm run build && node scripts/verify-tui-compatibility.mjs",