praxis-agent 0.36.0 → 0.37.0

package/README.md

@@ -122,7 +122,8 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   for supported local terminals,
   `Ctrl+V` text/image clipboard paste, `Ctrl+Z` shell suspension and `fg`
   recovery, permission-gated `!` shell turns, navigable current/per-turn Git
-  diff views, rich decision panels, and measured context budgets; print mode,
+  diff views, semantic plan/question decision panels with complete
+  screen-reader actions, and measured context budgets; print mode,
   structured JSON/JSONL, context compaction, tool loops, and bounded execution.
 - **Built-in tools** — read, write, edit, glob, search, shell, notebook, PDF,
   image, web, scheduled prompts, workflows, and worktrees.
@@ -152,7 +153,20 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   Claude-compatible main-thread agent definitions with native prompt, model,
   tool, memory, first-turn, and resume behavior. Agent execution uses one
   durable lifecycle vocabulary with bounded cancellation and drain,
-  continuation, notifications, and single-owner orphan recovery.
+  continuation, notifications, and single-owner orphan recovery. Experimental
+  local Teams (`PRAXIS_ENABLE_TEAMS=true`) stay absent from ordinary startup by
+  default and add durable task ownership plus one ordered mailbox with stable
+  identities, fixed broadcast recipients, durable cursors, bounded retention,
+  and bounded model-context projection. Teams are explicitly experimental and
+  opt-in: `PRAXIS_ENABLE_TEAMS=true` is required; otherwise Team code is not
+  loaded, discovered, or exposed. New Teams default to Hybrid lead control and
+  sequential execution, with optional Coordinator and Swarm policies. Commits
+  remain Lead-owned. Swarm admits only independent, dependency-ready,
+  non-conflicting tasks, within durable agent, concurrency, token, duration,
+  and shutdown-drain budgets.
+  Child permissions can only tighten the parent; concurrent asks form one FIFO
+  Lead Decision queue with provenance. Coordinator leads are restricted to
+  orchestration, and custom Team agents receive no MCP capability.
 - **Claude-compatible ecosystem** — shared instructions with recursive `@`
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and transcript data.

package/dist/application/durable-follow-up.d.ts

@@ -0,0 +1,14 @@
+export interface DurableFollowUpBatch {
+    readonly id: string;
+    readonly messages: readonly string[];
+    acknowledge(): Promise<void>;
+}
+export declare class DurableFollowUpTracker {
+    private readonly pending;
+    register(batch: DurableFollowUpBatch): void;
+    add(batch: DurableFollowUpBatch): void;
+    track(batch: DurableFollowUpBatch): void;
+    followUpUserMessagesCompleted(messages: readonly string[]): Promise<void>;
+    size(): number;
+}
+//# sourceMappingURL=durable-follow-up.d.ts.map

package/dist/application/durable-follow-up.js

@@ -0,0 +1,52 @@
+function multiset(values) {
+    const result = new Map();
+    for (const value of values)
+        result.set(value, (result.get(value) ?? 0) + 1);
+    return result;
+}
+function containsAll(container, required) {
+    const available = multiset(container);
+    for (const [value, count] of multiset(required)) {
+        if ((available.get(value) ?? 0) < count)
+            return false;
+    }
+    return true;
+}
+export class DurableFollowUpTracker {
+    pending = new Map();
+    register(batch) {
+        if (!batch || typeof batch.id !== 'string' || batch.id.trim() === '')
+            throw new Error('Invalid durable follow-up batch');
+        if (!Array.isArray(batch.messages) || batch.messages.length === 0)
+            return;
+        if (batch.messages.some((message) => typeof message !== 'string'))
+            throw new Error('Invalid durable follow-up messages');
+        const existing = this.pending.get(batch.id);
+        if (existing) {
+            if (existing.messages.length !== batch.messages.length ||
+                existing.messages.some((message, index) => message !== batch.messages[index]))
+                throw new Error(`Conflicting durable follow-up batch: ${batch.id}`);
+            return;
+        }
+        this.pending.set(batch.id, batch);
+    }
+    add(batch) {
+        this.register(batch);
+    }
+    track(batch) {
+        this.register(batch);
+    }
+    async followUpUserMessagesCompleted(messages) {
+        const completed = [...messages];
+        for (const [id, batch] of this.pending) {
+            if (!containsAll(completed, batch.messages))
+                continue;
+            await batch.acknowledge();
+            this.pending.delete(id);
+        }
+    }
+    size() {
+        return this.pending.size;
+    }
+}
+//# sourceMappingURL=durable-follow-up.js.map

package/dist/application/native-session-transcript.d.ts

@@ -0,0 +1,72 @@
+import type { ModelMessage, ModelToolCall, ToolExecutionResult } from '../core/runtime.js';
+import type { TranscriptMessagesEvent } from '../core/transcript-event.js';
+import type { NativeTranscriptStore } from '../persistence/native-transcript-store.js';
+export type NativeTranscriptActivation = {
+    readonly kind: 'start';
+} | {
+    readonly kind: 'resume';
+    readonly atEventId?: string;
+};
+export interface NativeMessageAppend {
+    readonly messages: readonly ModelMessage[];
+    readonly model?: string;
+    readonly terminalReason?: TranscriptMessagesEvent['terminalReason'];
+}
+export interface NativeCompactionAppend {
+    readonly summary: string;
+    readonly trigger: 'auto' | 'manual';
+    readonly preTokens: number;
+    readonly postTokens: number;
+    readonly durationMs: number;
+    readonly preservedMessages?: readonly ModelMessage[];
+}
+export type NativeInterruption = {
+    readonly kind: 'complete' | 'none';
+} | {
+    readonly kind: 'interrupted-prompt';
+    readonly prompt: string;
+} | {
+    readonly kind: 'interrupted-turn';
+} | {
+    readonly kind: 'recoverable-tools';
+    readonly calls: readonly ModelToolCall[];
+} | {
+    readonly kind: 'indeterminate-tools';
+    readonly callIds: readonly string[];
+};
+export interface NativeSessionTranscriptLease {
+    activeMessages(): ModelMessage[];
+    interruption(): NativeInterruption;
+    beginToolExecution(callId: string): Promise<void>;
+    appendToolCompletion(input: {
+        callId: string;
+        result: ToolExecutionResult;
+        followUpUserMessages?: readonly string[];
+    }): Promise<void>;
+    appendMessages(input: NativeMessageAppend): Promise<string>;
+    appendCompaction(input: NativeCompactionAppend): Promise<{
+        boundaryId: string;
+        summaryId: string;
+    }>;
+}
+export interface NativeForkOptions {
+    readonly atEventId?: string;
+    readonly recordCount?: number;
+    readonly ensureExisting?: boolean;
+}
+export interface NativeSessionTranscriptOptions {
+    readonly sessionId: string;
+    readonly store: NativeTranscriptStore;
+    readonly createId?: () => string;
+    readonly now?: () => string;
+}
+export declare class NativeSessionTranscript {
+    private readonly sessionId;
+    private readonly store;
+    private readonly createId;
+    private readonly now;
+    constructor(options: NativeSessionTranscriptOptions);
+    forkTo(target: NativeSessionTranscript, options?: NativeForkOptions): Promise<void>;
+    withLease<T>(activation: NativeTranscriptActivation, operation: (lease: NativeSessionTranscriptLease) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=native-session-transcript.d.ts.map

package/dist/application/native-session-transcript.js

@@ -0,0 +1,351 @@
+import { randomUUID } from 'node:crypto';
+import { activeEvents, projectActiveMessages, unresolvedActiveToolCallIds, } from './transcript-projection.js';
+export class NativeSessionTranscript {
+    sessionId;
+    store;
+    createId;
+    now;
+    constructor(options) {
+        this.sessionId = options.sessionId;
+        this.store = options.store;
+        this.createId = options.createId ?? randomUUID;
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    async forkTo(target, options = {}) {
+        if (this.sessionId === target.sessionId)
+            throw new Error('native fork source and target session IDs must differ');
+        const sourceResult = await this.store.withLease((lease) => lease.load());
+        if (sourceResult.status === 'conflict')
+            throw new Error(`native fork source lease conflict: ${sourceResult.reason}`);
+        const source = sourceResult.value;
+        if (source.records.length === 0)
+            throw new Error('native fork source session is missing or empty');
+        if (source.records.some((record) => record.event.sessionId !== this.sessionId))
+            throw new Error('native fork source sessionId does not match');
+        const recordCount = options.recordCount;
+        if (recordCount !== undefined &&
+            (!Number.isSafeInteger(recordCount) ||
+                recordCount <= 0 ||
+                recordCount > source.records.length))
+            throw new Error('native fork source recordCount is invalid');
+        const prefix = source.records.slice(0, recordCount);
+        const selected = activeEvents(prefix.map((record) => record.event), options.atEventId);
+        const terminal = prefix.at(-1)?.event;
+        if (terminal?.kind === 'context-boundary' ||
+            selected.at(-1)?.kind === 'context-boundary')
+            throw new Error('native fork source ends with an incomplete context boundary');
+        const expected = selected.map((event) => ({
+            ...event,
+            sessionId: target.sessionId,
+        }));
+        const ensureExisting = options.ensureExisting === true;
+        const targetResult = await target.store.withLease(async (lease) => {
+            const reservation = await lease.reserve();
+            if (reservation.status === 'reserved') {
+                const empty = await lease.load();
+                const appended = await lease.appendMany(empty.tail, expected);
+                if (appended.status === 'conflict')
+                    throw new Error(`native fork target append conflict: ${appended.reason}`);
+                return;
+            }
+            if (!ensureExisting)
+                throw new Error('native fork target already exists');
+            const existing = await lease.load();
+            if (existing.records.length < expected.length ||
+                expected.some((event, index) => JSON.stringify(existing.records[index]?.event) !==
+                    JSON.stringify(event)))
+                throw new Error('native fork target is not the expected native fork');
+        });
+        if (targetResult.status === 'conflict')
+            throw new Error(`native fork target lease conflict: ${targetResult.reason}`);
+    }
+    async withLease(activation, operation) {
+        let prepared;
+        let selectedId;
+        const result = await this.store.withLease(async (nativeLease) => {
+            if (activation.kind === 'start') {
+                const reserved = await nativeLease.reserve();
+                if (reserved.status === 'conflict')
+                    throw new Error('native transcript session already exists');
+            }
+            prepared = await nativeLease.load();
+            if (activation.kind === 'resume') {
+                if (prepared.records.length === 0)
+                    throw new Error('native transcript session is missing or empty');
+                if (prepared.records.some((record) => record.event.sessionId !== this.sessionId))
+                    throw new Error('native transcript sessionId does not match');
+                const events = prepared.records.map((record) => record.event);
+                const selected = activeEvents(events, activation.atEventId);
+                if (selected.length === 0)
+                    throw new Error('native transcript session has no active events');
+                selectedId = selected.at(-1)?.id;
+            }
+            const initial = prepared;
+            const currentId = selectedId ?? initial.records.at(-1)?.event.id ?? null;
+            const records = [...initial.records];
+            let tail = currentId === null
+                ? initial.tail
+                : { ...initial.tail, branchParentId: currentId };
+            let activeId = currentId;
+            let mutationQueue = Promise.resolve();
+            const enqueue = (operation) => {
+                const result = mutationQueue.then(operation, operation);
+                mutationQueue = result.then(() => undefined, () => undefined);
+                return result;
+            };
+            const lease = {
+                activeMessages: () => projectActiveMessages(records.map((record) => record.event), activeId ?? undefined).slice(),
+                interruption: () => {
+                    const events = activeEvents(records.map((record) => record.event), activeId ?? undefined);
+                    const boundaryIndex = Math.max(-1, ...events
+                        .map((event, index) => event.kind === 'context-boundary' ? index : -1)
+                        .filter((index) => index >= 0));
+                    const active = events.slice(boundaryIndex + 1);
+                    const calls = new Map();
+                    const results = new Set();
+                    const claimed = new Set();
+                    for (const event of active) {
+                        if (event.kind === 'tool-execution-started') {
+                            claimed.add(event.callId);
+                            continue;
+                        }
+                        if (event.kind !== 'messages')
+                            continue;
+                        for (const message of event.messages) {
+                            if (message.role === 'assistant')
+                                for (const call of message.toolCalls ?? [])
+                                    calls.set(call.id, call);
+                            else if (message.role === 'tool')
+                                results.add(message.toolCallId);
+                        }
+                    }
+                    const unresolved = [...calls.entries()].filter(([id]) => !results.has(id));
+                    const indeterminate = unresolved
+                        .map(([id]) => id)
+                        .filter((id) => claimed.has(id));
+                    if (indeterminate.length > 0)
+                        return { kind: 'indeterminate-tools', callIds: indeterminate };
+                    if (unresolved.length > 0)
+                        return {
+                            kind: 'recoverable-tools',
+                            calls: unresolved.map(([, call]) => call),
+                        };
+                    let lastMessages;
+                    for (const event of active) {
+                        if (event.kind !== 'messages')
+                            continue;
+                        lastMessages = event.messages;
+                    }
+                    const lastMessage = lastMessages?.at(-1);
+                    if (lastMessage?.role === 'assistant')
+                        return { kind: 'complete' };
+                    if (lastMessages?.some((message) => message.role === 'tool'))
+                        return { kind: 'interrupted-turn' };
+                    if (lastMessage?.role === 'user')
+                        return { kind: 'interrupted-prompt', prompt: lastMessage.content };
+                    return { kind: 'none' };
+                },
+                beginToolExecution: (callId) => enqueue(async () => {
+                    const events = activeEvents(records.map((record) => record.event), activeId ?? undefined);
+                    const activeMessages = projectActiveMessages(records.map((record) => record.event), activeId ?? undefined);
+                    const call = activeMessages
+                        .filter((message) => message.role === 'assistant')
+                        .flatMap((message) => message.toolCalls ?? [])
+                        .find((candidate) => candidate.id === callId);
+                    if (!call)
+                        throw new Error(`Unknown native tool call: ${callId}`);
+                    const boundaryIndex = Math.max(-1, ...events.map((event, index) => event.kind === 'context-boundary' ? index : -1));
+                    const postBoundary = events.slice(boundaryIndex + 1);
+                    const resolved = new Set(projectActiveMessages(records.map((record) => record.event), activeId ?? undefined)
+                        .filter((message) => message.role === 'tool')
+                        .map((message) => message.toolCallId));
+                    if (resolved.has(callId))
+                        throw new Error(`Native tool call is already resolved: ${callId}`);
+                    if (postBoundary.some((event) => event.kind === 'tool-execution-started' &&
+                        event.callId === callId))
+                        throw new Error(`Native tool call already claimed: ${callId}`);
+                    const event = {
+                        kind: 'tool-execution-started',
+                        id: this.createId(),
+                        parentId: activeId,
+                        sessionId: this.sessionId,
+                        timestamp: this.now(),
+                        callId,
+                    };
+                    const appended = await nativeLease.append(tail, event);
+                    if (appended.status === 'conflict')
+                        throw new Error(`native transcript append conflict: ${appended.reason}`);
+                    records.push({ event });
+                    tail = appended.tail;
+                    activeId = event.id;
+                }),
+                appendToolCompletion: (input) => enqueue(async () => {
+                    const { callId, result, followUpUserMessages = [] } = input;
+                    const events = activeEvents(records.map((record) => record.event), activeId ?? undefined);
+                    const messages = projectActiveMessages(records.map((record) => record.event), activeId ?? undefined);
+                    const call = messages
+                        .filter((message) => message.role === 'assistant')
+                        .flatMap((message) => message.toolCalls ?? [])
+                        .find((candidate) => candidate.id === callId);
+                    if (!call)
+                        throw new Error(`Unknown native tool call: ${callId}`);
+                    if (!events.some((event) => event.kind === 'tool-execution-started' &&
+                        event.callId === callId))
+                        throw new Error(`Native tool call was not claimed: ${callId}`);
+                    if (messages.some((message) => message.role === 'tool' && message.toolCallId === callId))
+                        throw new Error(`Native tool call is already resolved: ${callId}`);
+                    const event = {
+                        kind: 'messages',
+                        id: this.createId(),
+                        parentId: activeId,
+                        sessionId: this.sessionId,
+                        timestamp: this.now(),
+                        messages: [
+                            {
+                                role: 'tool',
+                                toolCallId: callId,
+                                content: result.content,
+                                ...(result.contentBlocks?.length
+                                    ? { contentBlocks: result.contentBlocks }
+                                    : {}),
+                                ...(result.images?.length ? { images: result.images } : {}),
+                                ...(result.documents?.length
+                                    ? { documents: result.documents }
+                                    : {}),
+                                isError: result.isError,
+                            },
+                            ...followUpUserMessages.map((content) => ({
+                                role: 'user',
+                                content,
+                            })),
+                        ],
+                    };
+                    const appended = await nativeLease.append(tail, event);
+                    if (appended.status === 'conflict')
+                        throw new Error(`native transcript append conflict: ${appended.reason}`);
+                    records.push({ event });
+                    tail = appended.tail;
+                    activeId = event.id;
+                }),
+                appendMessages: (input) => enqueue(async () => {
+                    if (input.messages.length === 0)
+                        throw new Error('native transcript cannot append empty messages');
+                    const event = {
+                        kind: 'messages',
+                        id: this.createId(),
+                        parentId: activeId,
+                        sessionId: this.sessionId,
+                        timestamp: this.now(),
+                        messages: [...input.messages],
+                        ...(input.model === undefined ? {} : { model: input.model }),
+                        ...(input.terminalReason === undefined
+                            ? {}
+                            : { terminalReason: input.terminalReason }),
+                    };
+                    const appended = await nativeLease.append(tail, event);
+                    if (appended.status === 'conflict')
+                        throw new Error(`native transcript append conflict: ${appended.reason}`);
+                    records.push({ event });
+                    tail = appended.tail;
+                    activeId = event.id;
+                    return event.id;
+                }),
+                appendCompaction: (input) => enqueue(async () => {
+                    if (records.length === 0 || activeId === null)
+                        throw new Error('Cannot compact an empty native transcript');
+                    if (input.summary.trim().length === 0)
+                        throw new Error('Native compact summary must not be blank');
+                    for (const value of [
+                        input.preTokens,
+                        input.postTokens,
+                        input.durationMs,
+                    ]) {
+                        if (!Number.isFinite(value) || value < 0)
+                            throw new Error('Native compact accounting values must be non-negative');
+                    }
+                    const events = records.map((record) => record.event);
+                    if (unresolvedActiveToolCallIds(projectActiveMessages(events, activeId)).length > 0)
+                        throw new Error('Cannot compact a native transcript with unresolved tool calls');
+                    const boundaryId = this.createId();
+                    const summaryId = this.createId();
+                    const boundary = {
+                        kind: 'context-boundary',
+                        id: boundaryId,
+                        parentId: null,
+                        sessionId: this.sessionId,
+                        timestamp: this.now(),
+                        logicalParentId: activeId,
+                        trigger: input.trigger,
+                        preTokens: input.preTokens,
+                        postTokens: input.postTokens,
+                        durationMs: input.durationMs,
+                    };
+                    const summary = {
+                        kind: 'context-summary',
+                        id: summaryId,
+                        parentId: boundaryId,
+                        sessionId: this.sessionId,
+                        timestamp: this.now(),
+                        summary: input.summary,
+                    };
+                    const suffix = input.preservedMessages ?? [];
+                    const replayToolCallIds = new Map();
+                    for (const message of suffix) {
+                        if (message.role !== 'assistant')
+                            continue;
+                        for (const call of message.toolCalls ?? [])
+                            replayToolCallIds.set(call.id, this.createId());
+                    }
+                    const replaySuffix = suffix.map((message) => {
+                        if (message.role === 'assistant')
+                            return {
+                                ...message,
+                                ...(message.toolCalls === undefined
+                                    ? {}
+                                    : {
+                                        toolCalls: message.toolCalls.map((call) => ({
+                                            ...call,
+                                            id: replayToolCallIds.get(call.id) ?? call.id,
+                                        })),
+                                    }),
+                            };
+                        if (message.role === 'tool')
+                            return {
+                                ...message,
+                                toolCallId: replayToolCallIds.get(message.toolCallId) ??
+                                    message.toolCallId,
+                            };
+                        return { ...message };
+                    });
+                    const suffixEvent = replaySuffix.length
+                        ? {
+                            kind: 'messages',
+                            id: this.createId(),
+                            parentId: summaryId,
+                            sessionId: this.sessionId,
+                            timestamp: this.now(),
+                            messages: replaySuffix,
+                        }
+                        : undefined;
+                    const compactedEvents = [
+                        boundary,
+                        summary,
+                        ...(suffixEvent === undefined ? [] : [suffixEvent]),
+                    ];
+                    const appended = await nativeLease.appendMany(tail, compactedEvents);
+                    if (appended.status === 'conflict')
+                        throw new Error(`native transcript append conflict: ${appended.reason}`);
+                    records.push({ event: boundary }, { event: summary }, ...(suffixEvent === undefined ? [] : [{ event: suffixEvent }]));
+                    tail = appended.tail;
+                    activeId = suffixEvent?.id ?? summaryId;
+                    return { boundaryId, summaryId };
+                }),
+            };
+            return operation(lease);
+        });
+        if (result.status === 'conflict')
+            throw new Error(`native transcript lease conflict: ${result.reason}`);
+        return result.value;
+    }
+}
+//# sourceMappingURL=native-session-transcript.js.map

package/dist/application/native-sidechain-transcript.d.ts

@@ -0,0 +1,34 @@
+import { type NativeSessionTranscriptLease } from './native-session-transcript.js';
+export type NativeSidechainPermissionMode = 'acceptEdits' | 'auto' | 'bypassPermissions' | 'default' | 'dontAsk' | 'plan';
+export interface NativeSidechainMetadata {
+    readonly agentType: string;
+    readonly description: string;
+    readonly toolUseId: string;
+    readonly spawnDepth: number;
+    readonly cwd: string;
+    readonly promptId: string;
+    readonly name?: string;
+    readonly permissionMode?: NativeSidechainPermissionMode;
+    readonly isolation?: 'worktree';
+    readonly parentAgentId?: string;
+    readonly worktreePath?: string;
+}
+export interface NativeSidechainPaths {
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly directory: string;
+    readonly transcriptFile: string;
+    readonly metadataFile: string;
+    readonly lockFile?: string;
+}
+export declare class NativeSidechainTranscript {
+    private readonly paths;
+    private readonly transcript;
+    private readonly store;
+    constructor(paths: NativeSidechainPaths);
+    create(prompt: string, metadata: NativeSidechainMetadata): Promise<void>;
+    withLease<T>(operation: (lease: NativeSessionTranscriptLease) => Promise<T>): Promise<T>;
+    loadReadOnly(): Promise<import("../persistence/native-transcript-store.js").NativeTranscriptRecovery>;
+    metadata(): Promise<NativeSidechainMetadata>;
+}
+//# sourceMappingURL=native-sidechain-transcript.d.ts.map