praxis-agent 0.34.0 → 0.36.0

package/dist/application/transcript-projection.d.ts

@@ -0,0 +1,33 @@
+import type { ModelMessage, ModelToolCall } from '../core/runtime.js';
+import type { TranscriptEvent } from '../core/transcript-event.js';
+export type TranscriptDisplayItem = {
+    kind: 'user' | 'assistant' | 'thinking';
+    text: string;
+} | {
+    kind: 'compact';
+    summary: string;
+} | {
+    kind: 'tool';
+    call: ModelToolCall;
+    detail: string;
+} | {
+    kind: 'tool-result';
+    callId: string;
+    text: string;
+    isError: boolean;
+} | {
+    kind: 'shell';
+    callId: string;
+    command: string;
+} | {
+    kind: 'shell-result';
+    callId: string;
+    stdout: string;
+    stderr: string;
+    isError: boolean;
+};
+export declare function activeEvents(events: readonly TranscriptEvent[], checkpoint?: string): TranscriptEvent[];
+export declare function projectActiveMessages(events: readonly TranscriptEvent[], checkpoint?: string): ModelMessage[];
+export declare function projectTranscriptDisplay(events: readonly TranscriptEvent[], checkpoint?: string): TranscriptDisplayItem[];
+export declare function lastUserPrompt(events: readonly TranscriptEvent[], checkpoint?: string): string | null;
+//# sourceMappingURL=transcript-projection.d.ts.map

package/dist/application/transcript-projection.js

@@ -0,0 +1,110 @@
+function effectiveParentId(event) {
+    return event.kind === 'context-boundary'
+        ? event.logicalParentId
+        : event.parentId;
+}
+function bashEnvelope(content) {
+    const input = /^<bash-input>([\s\S]*)<\/bash-input>$/u.exec(content);
+    if (input)
+        return { kind: 'input', command: input[1] ?? '' };
+    const output = /^<bash-stdout>([\s\S]*)<\/bash-stdout><bash-stderr>([\s\S]*)<\/bash-stderr>$/u.exec(content);
+    return output
+        ? { kind: 'output', stdout: output[1] ?? '', stderr: output[2] ?? '' }
+        : null;
+}
+export function activeEvents(events, checkpoint) {
+    const all = [...events];
+    const byId = new Map(all.map((event) => [event.id, event]));
+    const parentIds = new Set(all.flatMap((event) => {
+        const parentId = effectiveParentId(event);
+        return parentId === null ? [] : [parentId];
+    }));
+    const newest = (list) => [...list]
+        .sort((a, b) => a.timestamp.localeCompare(b.timestamp) || a.id.localeCompare(b.id))
+        .at(-1);
+    let leaf = checkpoint === undefined
+        ? (newest(all.filter((event) => !parentIds.has(event.id))) ?? newest(all))
+        : byId.get(checkpoint);
+    if (checkpoint !== undefined && !leaf)
+        throw new Error(`Unknown transcript checkpoint: ${checkpoint}`);
+    if (!leaf)
+        return [];
+    const selected = [];
+    const seen = new Set();
+    while (leaf && !seen.has(leaf.id)) {
+        selected.push(leaf);
+        seen.add(leaf.id);
+        const parentId = effectiveParentId(leaf);
+        leaf = parentId ? byId.get(parentId) : undefined;
+    }
+    return selected.reverse();
+}
+export function projectActiveMessages(events, checkpoint) {
+    return activeEvents(events, checkpoint).flatMap((event) => event.kind === 'messages' ? [...event.messages] : []);
+}
+export function projectTranscriptDisplay(events, checkpoint) {
+    const items = [];
+    let pendingShell = null;
+    for (const event of activeEvents(events, checkpoint)) {
+        if (event.kind === 'context-summary') {
+            items.push({ kind: 'compact', summary: event.summary });
+            continue;
+        }
+        if (event.kind !== 'messages')
+            continue;
+        for (const message of event.messages) {
+            if (message.role === 'user') {
+                const shell = bashEnvelope(message.content);
+                if (shell?.kind === 'input') {
+                    pendingShell = { callId: event.id, command: shell.command };
+                    items.push({ kind: 'shell', ...pendingShell });
+                    continue;
+                }
+                if (shell?.kind === 'output' && pendingShell) {
+                    items.push({
+                        kind: 'shell-result',
+                        callId: pendingShell.callId,
+                        stdout: shell.stdout,
+                        stderr: shell.stderr,
+                        isError: shell.stderr.length > 0,
+                    });
+                    pendingShell = null;
+                    continue;
+                }
+                if (message.content)
+                    items.push({ kind: 'user', text: message.content });
+                continue;
+            }
+            if (message.role === 'assistant') {
+                for (const thinking of message.thinkingBlocks ?? [])
+                    if (thinking.type === 'thinking' && thinking.thinking)
+                        items.push({ kind: 'thinking', text: thinking.thinking });
+                if (message.content)
+                    items.push({ kind: 'assistant', text: message.content });
+                for (const call of message.toolCalls ?? [])
+                    items.push({ kind: 'tool', call, detail: '' });
+                continue;
+            }
+            if (message.role === 'tool')
+                items.push({
+                    kind: 'tool-result',
+                    callId: message.toolCallId,
+                    text: message.content,
+                    isError: message.isError,
+                });
+        }
+    }
+    return items;
+}
+export function lastUserPrompt(events, checkpoint) {
+    const messages = projectActiveMessages(events, checkpoint);
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role === 'user' &&
+            message.content &&
+            bashEnvelope(message.content) === null)
+            return message.content;
+    }
+    return null;
+}
+//# sourceMappingURL=transcript-projection.js.map

package/dist/application/turn-lifecycle.d.ts

@@ -0,0 +1,40 @@
+import { type ModelDocument, type ModelImage, type RuntimeEventSink } from '../core/runtime.js';
+import type { LifecycleState } from '../core/agent-orchestration.js';
+export type TurnTerminalState = Extract<LifecycleState, 'completed' | 'failed' | 'cancelled'>;
+export type TurnActivation = {
+    kind: 'start';
+    sessionId: string;
+    name?: string;
+} | {
+    kind: 'resume';
+    sessionId: string;
+    name?: string;
+    atMessageId?: string;
+};
+export type TurnSubmission = {
+    kind: 'prompt';
+    text: string;
+    images?: readonly ModelImage[];
+    documents?: readonly ModelDocument[];
+} | {
+    kind: 'shell';
+    command: string;
+} | {
+    kind: 'retry';
+    prompt: string;
+};
+export interface TurnRequest {
+    activation: TurnActivation;
+    submission: TurnSubmission;
+    signal?: AbortSignal;
+}
+export declare class TurnTerminalController {
+    private readonly sink;
+    private terminal;
+    constructor(sink: RuntimeEventSink);
+    emit: RuntimeEventSink;
+    complete(): void;
+    fail(error: unknown, signal?: AbortSignal): void;
+    private transition;
+}
+//# sourceMappingURL=turn-lifecycle.d.ts.map

package/dist/application/turn-lifecycle.js

@@ -0,0 +1,36 @@
+import { AgentRunCancelledError, ModelProviderError, } from '../core/runtime.js';
+export class TurnTerminalController {
+    sink;
+    terminal = false;
+    constructor(sink) {
+        this.sink = sink;
+    }
+    emit = (event) => {
+        if (event.type === 'state' &&
+            (event.state === 'completed' ||
+                event.state === 'cancelled' ||
+                event.state === 'failed')) {
+            return;
+        }
+        this.sink(event);
+    };
+    complete() {
+        this.transition('completed');
+    }
+    fail(error, signal) {
+        if (this.terminal)
+            return;
+        const cancelled = signal?.aborted === true ||
+            error instanceof AgentRunCancelledError ||
+            (error instanceof ModelProviderError && error.kind === 'cancelled');
+        this.transition(cancelled ? 'cancelled' : 'failed');
+    }
+    transition(state) {
+        if (this.terminal) {
+            throw new Error('Turn terminal transition already emitted');
+        }
+        this.terminal = true;
+        this.sink({ type: 'state', state });
+    }
+}
+//# sourceMappingURL=turn-lifecycle.js.map

package/dist/application/turn-memory-coordinator.d.ts

@@ -0,0 +1,43 @@
+import type { ModelMessage } from '../core/runtime.js';
+import type { ProjectMemoryExtractionRuntime, ProjectMemoryMessage, ProjectMemoryRecallRuntime } from './project-memory.js';
+export interface TurnSessionMemoryRuntime {
+    summary(): Promise<string>;
+    waitForCompact(): Promise<void>;
+    observeContext(currentTokens: number, turnToolCalls: number, messageId: string, messages?: readonly ModelMessage[]): Promise<boolean>;
+}
+export interface TurnMemoryCoordinatorOptions {
+    sessionId: string;
+    session?: TurnSessionMemoryRuntime;
+    projectRecall?: ProjectMemoryRecallRuntime;
+    projectExtraction?: ProjectMemoryExtractionRuntime;
+    warn?: (message: string) => void;
+}
+/** Turn-scoped, best-effort coordination for both derived memory stores. */
+export declare class TurnMemoryCoordinator {
+    private readonly options;
+    private recall;
+    constructor(options: TurnMemoryCoordinatorOptions);
+    prefetch(input: {
+        turnId: string;
+        prompt: string;
+        signal?: AbortSignal;
+    }): void;
+    sessionSummary(): Promise<string>;
+    consumeRecall(): {
+        content: string;
+        attachmentCount: number;
+    } | null;
+    recordRead(path: string): void;
+    beforeCompact(): Promise<void>;
+    afterCompact(): Promise<void>;
+    observeSuccess(input: {
+        messageId?: string;
+        occupancyTokens: number;
+        toolCalls: number;
+        messages: readonly ModelMessage[];
+        projectMessages: readonly ProjectMemoryMessage[];
+        directMaintenance?: boolean;
+    }): Promise<void>;
+    private warn;
+}
+//# sourceMappingURL=turn-memory-coordinator.d.ts.map

package/dist/application/turn-memory-coordinator.js

@@ -0,0 +1,98 @@
+/** Turn-scoped, best-effort coordination for both derived memory stores. */
+export class TurnMemoryCoordinator {
+    options;
+    recall;
+    constructor(options) {
+        this.options = options;
+    }
+    prefetch(input) {
+        if (!this.options.projectRecall)
+            return;
+        try {
+            this.recall = this.options.projectRecall.prefetch({
+                sessionId: this.options.sessionId,
+                ...input,
+            });
+        }
+        catch (error) {
+            this.warn('Project memory recall prefetch failed', error);
+        }
+    }
+    async sessionSummary() {
+        if (!this.options.session)
+            return '';
+        try {
+            return await this.options.session.summary();
+        }
+        catch (error) {
+            this.warn('Session memory summary failed', error);
+            return '';
+        }
+    }
+    consumeRecall() {
+        try {
+            return this.recall?.consumeIfSettled() ?? null;
+        }
+        catch (error) {
+            this.warn('Project memory recall consumption failed', error);
+            return null;
+        }
+    }
+    recordRead(path) {
+        try {
+            this.options.projectRecall?.recordRead(this.options.sessionId, path);
+        }
+        catch (error) {
+            this.warn('Project memory read observation failed', error);
+        }
+    }
+    async beforeCompact() {
+        if (!this.options.session)
+            return;
+        try {
+            await this.options.session.waitForCompact();
+        }
+        catch (error) {
+            this.warn('Session memory compact coordination failed', error);
+        }
+    }
+    async afterCompact() {
+        try {
+            this.options.projectRecall?.recordCompact(this.options.sessionId);
+        }
+        catch (error) {
+            this.warn('Project memory compact observation failed', error);
+        }
+    }
+    async observeSuccess(input) {
+        if (this.options.session && input.messageId !== undefined) {
+            try {
+                await this.options.session.observeContext(input.occupancyTokens, input.toolCalls, input.messageId, input.messages);
+            }
+            catch (error) {
+                this.warn('Session memory observation failed', error);
+            }
+        }
+        try {
+            this.options.projectExtraction?.observe({
+                sessionId: this.options.sessionId,
+                messages: input.projectMessages,
+                ...(input.directMaintenance === undefined
+                    ? {}
+                    : { directMaintenance: input.directMaintenance }),
+            });
+        }
+        catch (error) {
+            this.warn('Project memory extraction observation failed', error);
+        }
+    }
+    warn(prefix, error) {
+        try {
+            this.options.warn?.(`${prefix}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        catch {
+            // Warning sinks are deliberately non-authoritative.
+        }
+    }
+}
+//# sourceMappingURL=turn-memory-coordinator.js.map

package/dist/cli/agents-dashboard.js

@@ -2,7 +2,7 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState, } from 'react';
 import { Box, Text, render, useApp, useInput } from 'ink';
 import { loadTuiThemeSettings } from './tui/theme-settings.js';
-import { DEFAULT_TUI_THEME_SETTINGS, TuiThemeProvider, useTuiPalette, } from './tui/theme.js';
+import { DEFAULT_TUI_THEME_SETTINGS, TuiThemeProvider, useTuiTheme, } from './tui/theme.js';
 const DASHBOARD_SECTIONS = [
     'Ready for review',
     'Needs input',
@@ -74,12 +74,17 @@ function groupAgents(agents) {
     return DASHBOARD_SECTIONS.flatMap((section) => agents.filter((agent) => sectionFor(agent) === section));
 }
 function AgentSection({ title, agents, selected, }) {
-    const palette = useTuiPalette();
-    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { bold: true, children: [title, " (", agents.length, ")"] }), agents.length === 0 ? (_jsx(Text, { dimColor: true, children: " None" })) : (agents.map((agent) => (_jsxs(Text, { ...(agent === selected ? { color: palette.accent } : {}), children: [agent === selected ? '› ' : '  ', agent.name, " \u00B7 ", agentStatus(agent), " \u00B7 ", agentKey(agent)] }, agentKey(agent)))))] }));
+    const theme = useTuiTheme();
+    const semanticSelection = theme.screenReader || theme.noColor;
+    return (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { ...theme.text.heading, bold: true, children: [title, " (", agents.length, ")"] }), agents.length === 0 ? (_jsx(Text, { dimColor: true, children: " None" })) : (agents.map((agent) => (_jsxs(Text, { ...(agent === selected ? theme.text.selectedRow : {}), children: [agent === selected
+                        ? semanticSelection
+                            ? 'Selected: '
+                            : '› '
+                        : '  ', agent.name, " \u00B7", ' ', _jsx(Text, { ...(sectionFor(agent) === 'Working' ? theme.text.active : {}), children: agentStatus(agent) }), ' ', "\u00B7 ", agentKey(agent)] }, agentKey(agent)))))] }));
 }
 export function AgentsDashboardApp({ manager, defaults, signal, refreshIntervalMs = 1_000, onCancel, }) {
     const { exit } = useApp();
-    const palette = useTuiPalette();
+    const theme = useTuiTheme();
     const [agents, setAgents] = useState([]);
     const [selectedIndex, setSelectedIndex] = useState(0);
     const selectedIndexRef = useRef(0);
@@ -414,7 +419,7 @@ export function AgentsDashboardApp({ manager, defaults, signal, refreshIntervalM
         editInput();
     });
     const selected = agents[selectedIndex];
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: palette.accent, children: "Praxis agents" }), _jsxs(Text, { dimColor: true, children: [agents.length, " sessions \u00B7 live refresh"] }), DASHBOARD_SECTIONS.map((title) => (_jsx(AgentSection, { title: title, agents: agents.filter((agent) => sectionFor(agent) === title), ...(selected === undefined ? {} : { selected }) }, title))), mode === 'attach' ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Attached to ", attachedId] }), attachedOutput ? (_jsx(Text, { children: attachedOutput })) : (_jsx(Text, { dimColor: true, children: "Waiting for output\u2026" })), _jsxs(Text, { children: ["\u203A ", input] }), _jsx(Text, { dimColor: true, children: "Enter sends \u00B7 Esc detaches \u00B7 Ctrl+C exits" })] })) : mode === 'review' ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Reviewing ", reviewAgent ? agentKey(reviewAgent) : ''] }), _jsx(Text, { children: attachedOutput || 'No review output.' }), _jsxs(Text, { children: ["\u203A ", input] }), _jsx(Text, { dimColor: true, children: "Enter resumes with prompt \u00B7 Esc returns to list" })] })) : (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["\u203A ", input || 'describe a task for a new background agent'] }), _jsx(Text, { dimColor: true, children: "Enter dispatches \u00B7 \u2191/\u2193 select \u00B7 Enter empty attaches \u00B7 Ctrl+X stops \u00B7 Ctrl+R refreshes \u00B7 ? help \u00B7 Esc exits" }), selected ? (_jsxs(Text, { dimColor: true, children: ["Selected ", agentKey(selected)] })) : null] })), busy ? _jsx(Text, { dimColor: true, children: "Working\u2026" }) : null, notice ? _jsx(Text, { color: palette.warning, children: notice }) : null, showHelp ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, children: "Shortcuts" }), _jsx(Text, { children: "Enter dispatches or attaches \u00B7 Esc detaches/exits \u00B7 Ctrl+X stops local background agents \u00B7 Ctrl+R refreshes \u00B7 ? closes help" })] })) : null] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { ...theme.text.heading, ...theme.text.productIdentity, children: "Praxis agents" }), _jsxs(Text, { dimColor: true, children: [agents.length, " sessions \u00B7 live refresh"] }), DASHBOARD_SECTIONS.map((title) => (_jsx(AgentSection, { title: title, agents: agents.filter((agent) => sectionFor(agent) === title), ...(selected === undefined ? {} : { selected }) }, title))), mode === 'attach' ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Attached to ", attachedId] }), attachedOutput ? (_jsx(Text, { children: attachedOutput })) : (_jsx(Text, { dimColor: true, children: "Waiting for output\u2026" })), _jsxs(Text, { children: ["\u203A ", input] }), _jsx(Text, { dimColor: true, children: "Enter sends \u00B7 Esc detaches \u00B7 Ctrl+C exits" })] })) : mode === 'review' ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["Reviewing ", reviewAgent ? agentKey(reviewAgent) : ''] }), _jsx(Text, { children: attachedOutput || 'No review output.' }), _jsxs(Text, { children: ["\u203A ", input] }), _jsx(Text, { dimColor: true, children: "Enter resumes with prompt \u00B7 Esc returns to list" })] })) : (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsxs(Text, { children: ["\u203A ", input || 'describe a task for a new background agent'] }), _jsx(Text, { dimColor: true, children: "Enter dispatches \u00B7 \u2191/\u2193 select \u00B7 Enter empty attaches \u00B7 Ctrl+X stops \u00B7 Ctrl+R refreshes \u00B7 ? help \u00B7 Esc exits" }), selected ? (_jsxs(Text, { dimColor: true, children: ["Selected ", agentKey(selected)] })) : null] })), busy ? _jsx(Text, { dimColor: true, children: "Working\u2026" }) : null, notice ? _jsx(Text, { ...theme.text.warning, children: notice }) : null, showHelp ? (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, children: "Shortcuts" }), _jsx(Text, { children: "Enter dispatches or attaches \u00B7 Esc detaches/exits \u00B7 Ctrl+X stops local background agents \u00B7 Ctrl+R refreshes \u00B7 ? closes help" })] })) : null] }));
 }
 export async function runAgentsDashboard(options, dependencies = {}) {
     const controller = new AbortController();