praxis-agent 0.34.0 → 0.35.0

package/dist/core/prompt-composer.js

@@ -1,3 +1,4 @@
+import { createContextSnapshot, } from './context.js';
 const PRODUCT_POLICY = `# Praxis
 
 You are Praxis, a local CLI coding agent. Work until the user's request is genuinely handled or a concrete blocker requires their input.
@@ -9,6 +10,8 @@ You are Praxis, a local CLI coding agent. Work until the user's request is genui
 - Summarize or clear bulky intermediate results once their useful facts have been retained.
 - Treat the context window as bounded: preserve decisions and evidence before reducing detail.
 - Keep responses concise and use the user's language unless they request otherwise.`;
+const BRIEF_OUTPUT_POLICY = 'When brief mode is enabled, SendUserMessage is the primary user-visible reply channel. Use it for the answer, progress checkpoints, and blockers. Set status to normal for a direct reply and proactive for an unsolicited update.';
+const STRUCTURED_OUTPUT_POLICY = 'You MUST call StructuredOutput exactly once at the end with a value matching the requested JSON Schema.';
 function baseSection(mode, content) {
     if (mode === 'bare')
         return undefined;
@@ -51,6 +54,52 @@ function normalizedSections(sections, group) {
         return { ...section };
     });
 }
+function turnSections(turn) {
+    if (!turn)
+        return [];
+    return [
+        ...(turn.planMode?.trim()
+            ? [
+                {
+                    id: 'plan-mode',
+                    content: turn.planMode,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.sessionMemory?.trim()
+            ? [
+                {
+                    id: 'session-memory',
+                    content: turn.sessionMemory,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.briefOutput
+            ? [
+                {
+                    id: 'brief-output',
+                    content: BRIEF_OUTPUT_POLICY,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+        ...(turn.structuredOutput
+            ? [
+                {
+                    id: 'structured-output',
+                    content: STRUCTURED_OUTPUT_POLICY,
+                    placement: 'system',
+                    stability: 'volatile',
+                },
+            ]
+            : []),
+    ];
+}
 export class PromptComposer {
     compose(options) {
         const base = baseSection(options.mode, options.baseSystemPrompt);
@@ -63,37 +112,28 @@ export class PromptComposer {
                 stability: 'session',
             }
             : undefined;
-        const tailSections = normalizedSections(options.tailSections ?? [], 'tailSections');
+        const tailSections = normalizedSections([...(options.tailSections ?? []), ...turnSections(options.turn)], 'tailSections');
         const sections = [
             ...(base ? [base] : []),
             ...sessionSections,
             ...(append ? [append] : []),
             ...tailSections,
         ];
-        const identities = new Set();
-        for (const section of sections) {
-            if (identities.has(section.id)) {
-                throw new Error(`Duplicate prompt section ${section.id}`);
-            }
-            identities.add(section.id);
-        }
-        const systemSections = sections.filter((section) => section.placement === 'system');
-        const firstVolatileSystemIndex = systemSections.findIndex((section) => section.stability === 'volatile');
-        const firstUserMessageContext = sections
-            .filter((section) => section.placement === 'first-user')
-            .map((section) => section.content)
-            .join('\n\n');
-        return {
-            sections,
-            systemMessages: systemSections.map((section) => ({
-                role: 'system',
-                content: section.content,
-            })),
-            stableSystemSectionCount: firstVolatileSystemIndex < 0
-                ? systemSections.length
-                : firstVolatileSystemIndex,
-            ...(firstUserMessageContext ? { firstUserMessageContext } : {}),
-        };
+        return createContextSnapshot(sections);
     }
 }
+const defaultContextAssembler = {
+    async assemble(options = {}) {
+        return new PromptComposer().compose({
+            mode: options.mode ?? 'bare',
+            ...(options.baseSystemPrompt === undefined
+                ? {}
+                : { baseSystemPrompt: options.baseSystemPrompt }),
+            ...(options.turn === undefined ? {} : { turn: options.turn }),
+        });
+    },
+};
+export async function assembleContextSnapshot(assembler, options = {}) {
+    return (assembler ?? defaultContextAssembler).assemble(options);
+}
 //# sourceMappingURL=prompt-composer.js.map

package/dist/core/resources.d.ts

@@ -0,0 +1,39 @@
+export type ResourceScope = 'local' | 'project' | 'user';
+export interface TextResource {
+    path: string;
+    scope: ResourceScope;
+    content: string;
+    importedFrom?: string;
+    importRoot?: string;
+}
+export interface JsonResource {
+    path: string;
+    scope: ResourceScope;
+    value: unknown;
+    plugin?: true;
+    pluginName?: string;
+    pluginSource?: string;
+    environment?: Readonly<Record<string, string>>;
+    sensitiveValues?: readonly string[];
+}
+export interface ContextResources {
+    instructions: TextResource[];
+    conditionalRules: ConditionalRule[];
+    memoryIndex: TextResource | null;
+}
+export interface ConditionalRule extends TextResource {
+    baseDirectory: string;
+    content: string;
+    globs: string[];
+    rawContent: string;
+}
+export interface SharedResources {
+    instructions: TextResource[];
+    memory: TextResource[];
+    skills: TextResource[];
+    commands: TextResource[];
+    agents: TextResource[];
+    settings: JsonResource[];
+    mcp: JsonResource[];
+}
+//# sourceMappingURL=resources.d.ts.map

package/dist/core/resources.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=resources.js.map

package/dist/core/runtime.d.ts

@@ -151,7 +151,7 @@ export interface ModelProvider {
 }
 export type RuntimeEvent = {
     type: 'state';
-    state: Exclude<RuntimeState, 'idle' | 'failed'>;
+    state: Exclude<RuntimeState, 'idle'>;
 } | {
     type: 'text-delta';
     delta: string;

package/dist/core/session.d.ts

@@ -0,0 +1,2 @@
+export declare function isSessionId(value: string): boolean;
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.js

@@ -0,0 +1,5 @@
+const SESSION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isSessionId(value) {
+    return SESSION_ID_PATTERN.test(value);
+}
+//# sourceMappingURL=session.js.map

package/dist/core/transcript-codec.d.ts

@@ -0,0 +1,70 @@
+import type { TranscriptEvent } from './transcript-event.js';
+export type TranscriptCodecDiagnostic = {
+    kind: 'unsupported-version';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    schemaVersion: string | number;
+} | {
+    kind: 'corrupt-line';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    schemaVersion?: string | number;
+} | {
+    kind: 'unsupported-event';
+    lineNumber: number | null;
+    byteOffset: number;
+    message: string;
+    eventKind?: string;
+};
+export interface OpaquePreservationToken {
+    readonly __opaqueToken: unique symbol;
+}
+type TokenPayload = {
+    owner: symbol;
+    raw: string;
+    eventFingerprint: string;
+};
+export type PreservationTokenSource = {
+    owner: symbol;
+    raw: string;
+    event: TranscriptEvent;
+};
+export declare function createPreservationToken(owner: symbol, source: PreservationTokenSource): OpaquePreservationToken;
+export declare function readPreservationToken(token: OpaquePreservationToken, owner: symbol): TokenPayload | null;
+export interface DecodedTranscriptRecord {
+    readonly event: TranscriptEvent;
+    readonly preservation?: OpaquePreservationToken;
+}
+export type TranscriptLineResult = {
+    ok: true;
+    record: DecodedTranscriptRecord;
+} | {
+    ok: false;
+    issue: TranscriptCodecDiagnostic;
+};
+export type TranscriptEncodeResult = {
+    ok: true;
+    line: string;
+} | {
+    ok: false;
+    issue: TranscriptCodecDiagnostic;
+};
+export interface TranscriptDocumentResult {
+    readonly records: readonly DecodedTranscriptRecord[];
+    readonly issue: TranscriptCodecDiagnostic | null;
+    readonly validPrefixByteLength: number;
+}
+export interface TranscriptCodec {
+    readonly id: string;
+    readonly version: string | number;
+    readonly writeMode: 'read-only' | 'read-write';
+    decodeLine(line: string, lineNumber?: number, byteOffset?: number): TranscriptLineResult;
+    encodeLine(event: TranscriptEvent, preservation?: OpaquePreservationToken): TranscriptEncodeResult;
+    decodeDocument(source: string | Uint8Array): TranscriptDocumentResult;
+}
+export declare function diagnostic(kind: TranscriptCodecDiagnostic['kind'], message: string, byteOffset: number, lineNumber: number | null, extra?: Partial<TranscriptCodecDiagnostic>): TranscriptCodecDiagnostic;
+export declare function decodeDocumentWith(codec: TranscriptCodec, source: string | Uint8Array): TranscriptDocumentResult;
+export {};
+//# sourceMappingURL=transcript-codec.d.ts.map

package/dist/core/transcript-codec.js

@@ -0,0 +1,60 @@
+const tokenPayloads = new WeakMap();
+export function createPreservationToken(owner, source) {
+    const token = Object.freeze({});
+    tokenPayloads.set(token, {
+        owner: source.owner,
+        raw: source.raw,
+        eventFingerprint: JSON.stringify(source.event),
+    });
+    return token;
+}
+export function readPreservationToken(token, owner) {
+    const payload = tokenPayloads.get(token);
+    return payload?.owner === owner ? payload : null;
+}
+export function diagnostic(kind, message, byteOffset, lineNumber, extra = {}) {
+    return {
+        kind,
+        message,
+        byteOffset,
+        lineNumber,
+        ...extra,
+    };
+}
+export function decodeDocumentWith(codec, source) {
+    const bytes = typeof source === 'string' ? new TextEncoder().encode(source) : source;
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] === 0x0a) {
+            lines.push({ bytes: bytes.subarray(start, i), terminatorBytes: 1 });
+            start = i + 1;
+        }
+    }
+    if (start < bytes.length) {
+        lines.push({ bytes: bytes.subarray(start), terminatorBytes: 0 });
+    }
+    const records = [];
+    let offset = 0;
+    for (const [index, sourceLine] of lines.entries()) {
+        const bytesLine = sourceLine.bytes;
+        let line;
+        try {
+            line = new TextDecoder('utf-8', { fatal: true }).decode(bytesLine);
+        }
+        catch {
+            return {
+                records,
+                issue: diagnostic('corrupt-line', 'Invalid UTF-8 transcript line', offset, index + 1),
+                validPrefixByteLength: offset,
+            };
+        }
+        const result = codec.decodeLine(line, index + 1, offset);
+        if (!result.ok)
+            return { records, issue: result.issue, validPrefixByteLength: offset };
+        records.push(result.record);
+        offset += bytesLine.length + sourceLine.terminatorBytes;
+    }
+    return { records, issue: null, validPrefixByteLength: offset };
+}
+//# sourceMappingURL=transcript-codec.js.map

package/dist/core/transcript-event.d.ts

@@ -0,0 +1,33 @@
+import type { ModelContentBlock, ModelDocument, ModelImage, ModelMessage, ModelTerminalReason } from './runtime.js';
+export interface TranscriptEventIdentity {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly sessionId: string;
+    readonly timestamp: string;
+}
+export interface TranscriptMessagesEvent extends TranscriptEventIdentity {
+    readonly kind: 'messages';
+    readonly messages: readonly ModelMessage[];
+    readonly model?: string;
+    readonly terminalReason?: ModelTerminalReason;
+}
+export interface TranscriptContextBoundaryEvent extends TranscriptEventIdentity {
+    readonly kind: 'context-boundary';
+    readonly logicalParentId: string;
+    readonly trigger: 'auto' | 'manual';
+    readonly preTokens: number;
+    readonly postTokens: number;
+    readonly durationMs: number;
+}
+export interface TranscriptContextSummaryEvent extends TranscriptEventIdentity {
+    readonly kind: 'context-summary';
+    readonly summary: string;
+}
+export type TranscriptEvent = TranscriptMessagesEvent | TranscriptContextBoundaryEvent | TranscriptContextSummaryEvent;
+export declare function isModelImage(value: unknown): value is ModelImage;
+export declare function isModelDocument(value: unknown): value is ModelDocument;
+export declare function isModelContentBlock(value: unknown): value is ModelContentBlock;
+export declare function isTranscriptEvent(value: unknown): value is TranscriptEvent;
+export declare function parseTranscriptEvent(value: unknown): TranscriptEvent;
+export declare function validateTranscriptEvent(value: unknown): value is TranscriptEvent;
+//# sourceMappingURL=transcript-event.d.ts.map

package/dist/core/transcript-event.js

@@ -0,0 +1,198 @@
+const terminalReasons = new Set([
+    'end_turn',
+    'tool_use',
+    'max_tokens',
+    'prompt_too_long',
+]);
+const imageTypes = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp',
+]);
+const documentTypes = new Set([
+    'application/pdf',
+    'text/plain',
+    'text/markdown',
+    'application/json',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+export function isModelImage(value) {
+    return (isRecord(value) &&
+        hasOnlyKeys(value, ['type', 'mediaType', 'data']) &&
+        value.type === 'image' &&
+        imageTypes.has(String(value.mediaType)) &&
+        isNonEmptyString(value.data));
+}
+export function isModelDocument(value) {
+    return (isRecord(value) &&
+        hasOnlyKeys(value, ['type', 'mediaType', 'data']) &&
+        value.type === 'document' &&
+        documentTypes.has(String(value.mediaType)) &&
+        isNonEmptyString(value.data));
+}
+function isModelMedia(value) {
+    return isModelImage(value) || isModelDocument(value);
+}
+export function isModelContentBlock(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type === 'text') {
+        return (hasOnlyKeys(value, ['type', 'text']) && typeof value.text === 'string');
+    }
+    return isModelMedia(value);
+}
+function isModelToolCall(value) {
+    return (isRecord(value) &&
+        hasOnlyKeys(value, ['id', 'name', 'input']) &&
+        isNonEmptyString(value.id) &&
+        isNonEmptyString(value.name) &&
+        isRecord(value.input));
+}
+function isModelThinkingBlock(value) {
+    return isRecord(value) && value.type === 'thinking'
+        ? hasOnlyKeys(value, ['type', 'thinking', 'signature']) &&
+            typeof value.thinking === 'string' &&
+            isNonEmptyString(value.signature)
+        : isRecord(value) && value.type === 'redacted_thinking'
+            ? hasOnlyKeys(value, ['type', 'data']) && isNonEmptyString(value.data)
+            : false;
+}
+function isModelMessage(value) {
+    if (!isRecord(value) || !isNonEmptyString(value.role))
+        return false;
+    if (value.role === 'system') {
+        return (hasOnlyKeys(value, ['role', 'content']) &&
+            typeof value.content === 'string');
+    }
+    if (value.role === 'user') {
+        return (hasOnlyKeys(value, [
+            'role',
+            'content',
+            'contentBlocks',
+            'images',
+            'documents',
+        ]) &&
+            typeof value.content === 'string' &&
+            (!('contentBlocks' in value) ||
+                (Array.isArray(value.contentBlocks) &&
+                    value.contentBlocks.every(isModelContentBlock))) &&
+            (!('images' in value) ||
+                (Array.isArray(value.images) && value.images.every(isModelImage))) &&
+            (!('documents' in value) ||
+                (Array.isArray(value.documents) &&
+                    value.documents.every(isModelDocument))));
+    }
+    if (value.role === 'assistant') {
+        return (hasOnlyKeys(value, ['role', 'content', 'thinkingBlocks', 'toolCalls']) &&
+            typeof value.content === 'string' &&
+            (!('thinkingBlocks' in value) ||
+                (Array.isArray(value.thinkingBlocks) &&
+                    value.thinkingBlocks.every(isModelThinkingBlock))) &&
+            (!('toolCalls' in value) ||
+                (Array.isArray(value.toolCalls) &&
+                    value.toolCalls.every(isModelToolCall))));
+    }
+    return (value.role === 'tool' &&
+        hasOnlyKeys(value, [
+            'role',
+            'toolCallId',
+            'content',
+            'contentBlocks',
+            'images',
+            'documents',
+            'isError',
+        ]) &&
+        isNonEmptyString(value.toolCallId) &&
+        typeof value.content === 'string' &&
+        typeof value.isError === 'boolean' &&
+        (!('contentBlocks' in value) ||
+            (Array.isArray(value.contentBlocks) &&
+                value.contentBlocks.every(isModelContentBlock))) &&
+        (!('images' in value) ||
+            (Array.isArray(value.images) && value.images.every(isModelImage))) &&
+        (!('documents' in value) ||
+            (Array.isArray(value.documents) &&
+                value.documents.every(isModelDocument))));
+}
+function hasValidIdentity(value) {
+    return (isNonEmptyString(value.id) &&
+        (value.parentId === null || isNonEmptyString(value.parentId)) &&
+        isNonEmptyString(value.sessionId) &&
+        typeof value.timestamp === 'string' &&
+        !Number.isNaN(Date.parse(value.timestamp)) &&
+        new Date(value.timestamp).toISOString() === value.timestamp);
+}
+function isNonNegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+export function isTranscriptEvent(value) {
+    if (!isRecord(value) ||
+        !hasValidIdentity(value) ||
+        typeof value.kind !== 'string')
+        return false;
+    if (value.kind === 'messages') {
+        return (hasOnlyKeys(value, [
+            'kind',
+            'id',
+            'parentId',
+            'sessionId',
+            'timestamp',
+            'messages',
+            'model',
+            'terminalReason',
+        ]) &&
+            Array.isArray(value.messages) &&
+            value.messages.length > 0 &&
+            value.messages.every(isModelMessage) &&
+            (!('model' in value) || isNonEmptyString(value.model)) &&
+            (!('terminalReason' in value) ||
+                terminalReasons.has(value.terminalReason)));
+    }
+    if (value.kind === 'context-boundary') {
+        return (hasOnlyKeys(value, [
+            'kind',
+            'id',
+            'parentId',
+            'sessionId',
+            'timestamp',
+            'logicalParentId',
+            'trigger',
+            'preTokens',
+            'postTokens',
+            'durationMs',
+        ]) &&
+            isNonEmptyString(value.logicalParentId) &&
+            (value.trigger === 'auto' || value.trigger === 'manual') &&
+            isNonNegativeNumber(value.preTokens) &&
+            isNonNegativeNumber(value.postTokens) &&
+            isNonNegativeNumber(value.durationMs));
+    }
+    return (value.kind === 'context-summary' &&
+        hasOnlyKeys(value, [
+            'kind',
+            'id',
+            'parentId',
+            'sessionId',
+            'timestamp',
+            'summary',
+        ]) &&
+        typeof value.summary === 'string');
+}
+export function parseTranscriptEvent(value) {
+    if (!isTranscriptEvent(value))
+        throw new Error('Invalid TranscriptEvent');
+    return value;
+}
+export function validateTranscriptEvent(value) {
+    return isTranscriptEvent(value);
+}
+//# sourceMappingURL=transcript-event.js.map

package/dist/persistence/data-plane-adapter.d.ts

@@ -0,0 +1,32 @@
+export type DataPlane = 'native' | 'claude';
+export interface DataPlaneRootOptions {
+    root?: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    homeDirectory?: string;
+}
+export interface DataPlaneAdapterOptions extends DataPlaneRootOptions {
+    cwd: string;
+    sessionId: string;
+}
+export interface ScheduledTaskFileOptions {
+    cwd: string;
+    root: string;
+}
+export interface DataPlanePaths {
+    dataPlane: DataPlane;
+    root: string;
+    projectRoot: string;
+    sessionFile: string;
+    taskRoot: string;
+    stateRoot: string;
+    /** Compatibility alias for callers that previously received `praxisRoot`. */
+    praxisRoot: string;
+    memoryRoot: string;
+}
+export interface DataPlaneAdapter {
+    readonly dataPlane: DataPlane;
+    resolveRoot(options: DataPlaneRootOptions): string;
+    resolvePaths(options: DataPlaneAdapterOptions): DataPlanePaths;
+    resolveScheduledTaskFile(options: ScheduledTaskFileOptions): string;
+}
+//# sourceMappingURL=data-plane-adapter.d.ts.map

package/dist/persistence/data-plane-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data-plane-adapter.js.map

package/dist/persistence/data-plane.d.ts

@@ -1,29 +1,13 @@
-export type DataPlane = 'native' | 'claude';
-export interface ResolveDataPlaneOptions {
+import type { DataPlane, DataPlanePaths, DataPlaneRootOptions } from './data-plane-adapter.js';
+export type { DataPlane, DataPlanePaths } from './data-plane-adapter.js';
+export interface ResolveDataPlaneOptions extends DataPlaneRootOptions {
     dataPlane?: DataPlane;
     cwd: string;
     sessionId: string;
-    root?: string;
-    environment?: Readonly<Record<string, string | undefined>>;
-    homeDirectory?: string;
-}
-export interface DataPlanePaths {
-    dataPlane: DataPlane;
-    root: string;
-    projectRoot: string;
-    sessionFile: string;
-    taskRoot: string;
-    stateRoot: string;
-    /** Compatibility alias for callers that previously received `praxisRoot`. */
-    praxisRoot: string;
-    memoryRoot: string;
 }
 export declare function resolveDataPlane(environment?: Readonly<Record<string, string | undefined>>): DataPlane;
-export declare function resolveDataPlaneRoot(options?: {
+export declare function resolveDataPlaneRoot(options?: DataPlaneRootOptions & {
     dataPlane?: DataPlane;
-    root?: string;
-    environment?: Readonly<Record<string, string | undefined>>;
-    homeDirectory?: string;
 }): string;
 export declare function resolveDataPlanePaths(options: ResolveDataPlaneOptions): DataPlanePaths;
 export declare function resolveScheduledTaskFile(options: {