praxis-agent 0.35.0 → 0.36.0

package/README.md

@@ -1,5 +1,7 @@
 # Praxis
 
+[English](README.md) | [简体中文](README_zh.md)
+
 [![CI](https://github.com/Forest-Isle/Praxis/actions/workflows/ci.yml/badge.svg)](https://github.com/Forest-Isle/Praxis/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Forest-Isle/Praxis/actions/workflows/codeql.yml/badge.svg)](https://github.com/Forest-Isle/Praxis/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Forest-Isle/Praxis/badge)](https://scorecard.dev/viewer/?uri=github.com/Forest-Isle/Praxis)
@@ -148,7 +150,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
 - **Durable local work** — resumable sessions, full-history forks, file
   checkpoints, tasks, foreground/background subagents, top-level agents, and
   Claude-compatible main-thread agent definitions with native prompt, model,
-  tool, memory, first-turn, and resume behavior.
+  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.
 - **Claude-compatible ecosystem** — shared instructions with recursive `@`
   imports, memory, skills, commands, agents, hooks, settings, MCP servers,
   plugins, and transcript data.

package/dist/application/background-agent-manager.d.ts

@@ -1,4 +1,5 @@
 import type { ModelUsage, ModelUsageByModel } from '../core/runtime.js';
+import { type LifecycleState } from '../core/agent-orchestration.js';
 export interface BackgroundAgentRunResult {
     text: string;
     usage: ModelUsage;
@@ -19,6 +20,10 @@ export declare class BackgroundAgentRunError extends Error {
 export declare class BackgroundAgentShutdownError extends Error {
     constructor();
 }
+export interface BackgroundAgentLifecycleSource {
+    current(): LifecycleState;
+    subscribe(listener: (state: LifecycleState) => void): () => void;
+}
 export interface BackgroundAgentTaskSpec {
     agentId: string;
     name?: string;
@@ -28,13 +33,15 @@ export interface BackgroundAgentTaskSpec {
     toolUseId: string;
     outputFile: string;
     resolvedModel: string;
+    lifecycle: BackgroundAgentLifecycleSource;
     markBackground?(): void;
     acknowledgeNotification?(notificationId: string): Promise<void>;
     prepareNotificationDetached?(notificationId: string, model: string): Promise<void>;
     confirmNotificationDetached?(notificationId: string): Promise<void>;
     run(message: string, signal: AbortSignal, continuation: boolean, toolUseId: string): Promise<BackgroundAgentRunResult>;
 }
-type BackgroundAgentStatus = 'running' | 'completed' | 'failed' | 'stopped' | 'interrupted';
+type BackgroundAgentStatus = LifecycleState;
+export declare function legacyBackgroundStatus(state: BackgroundAgentStatus): 'running' | 'stopped' | 'interrupted' | 'completed' | 'failed';
 export interface BackgroundAgentNotificationIdentity {
     agentId: string;
     toolUseId: string;
@@ -66,12 +73,15 @@ export declare class BackgroundAgentManager {
         operation: Promise<BackgroundAgentRunResult>;
         startedAt: number;
     }): BackgroundAgentSnapshot;
-    registerCompleted(spec: BackgroundAgentTaskSpec, result: BackgroundAgentRunResult): BackgroundAgentSnapshot;
-    registerInterrupted(spec: BackgroundAgentTaskSpec, error?: string): BackgroundAgentSnapshot;
-    registerTerminal(spec: BackgroundAgentTaskSpec, status: 'failed' | 'stopped', error: string): BackgroundAgentSnapshot;
+    registerPersisted(spec: BackgroundAgentTaskSpec, presentation?: {
+        result?: BackgroundAgentRunResult | null;
+        error?: string | null;
+        startedAt?: number;
+        durationMs?: number | null;
+    }): BackgroundAgentSnapshot;
     registerPersistedNotification(agentId: string, notification: {
         id: string;
-        status: 'completed' | 'failed' | 'stopped';
+        status: 'completed' | 'failed' | 'cancelled';
         result: BackgroundAgentRunResult | null;
         error: string | null;
         toolUseId: string;
@@ -112,7 +122,7 @@ export declare class BackgroundAgentManager {
     private resolveOptional;
     private stopTask;
     private assertNameAvailable;
-    private finishStopped;
+    private finishCancelled;
     private resolveRequired;
     private snapshot;
     private formatOutput;

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

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { isTerminalLifecycleState, } from '../core/agent-orchestration.js';
 import { isClaudeAgentId } from '../compatibility/claude/sidechain.js';
 const MAX_TIMEOUT_MS = 600_000;
 const DEFAULT_CLOSE_DRAIN_MS = 5_000;
@@ -16,6 +17,25 @@ export class BackgroundAgentShutdownError extends Error {
         this.name = 'BackgroundAgentShutdownError';
     }
 }
+export function legacyBackgroundStatus(state) {
+    if (state === 'queued' ||
+        state === 'running' ||
+        state === 'waiting' ||
+        state === 'cancelling')
+        return 'running';
+    if (state === 'cancelled')
+        return 'stopped';
+    if (state === 'orphaned')
+        return 'interrupted';
+    return state;
+}
+function notificationWireStatus(status) {
+    if (status === 'completed' || status === 'failed')
+        return status;
+    if (status === 'cancelled')
+        return 'killed';
+    return null;
+}
 function assertAgentId(agentId) {
     if (!isClaudeAgentId(agentId)) {
         throw new Error(`Invalid background agent ID: ${agentId}`);
@@ -174,11 +194,11 @@ export class BackgroundAgentManager {
     }
     launch(spec) {
         const { task } = this.registerTask(spec, {
-            status: 'running',
+            status: spec.lifecycle.current(),
             controller: null,
             result: null,
             error: null,
-            generation: 0,
+            runSequence: 0,
             startedAt: Date.now(),
             durationMs: null,
         }, 'throw');
@@ -189,11 +209,11 @@ export class BackgroundAgentManager {
     adopt(options) {
         const { spec } = options;
         const { task } = this.registerTask(spec, {
-            status: 'running',
+            status: spec.lifecycle.current(),
             controller: options.controller,
             result: null,
             error: null,
-            generation: 1,
+            runSequence: 1,
             startedAt: options.startedAt,
             durationMs: null,
         }, 'throw');
@@ -201,39 +221,18 @@ export class BackgroundAgentManager {
         this.track(task, options.operation, 1, spec.toolUseId);
         return this.snapshot(task);
     }
-    registerCompleted(spec, result) {
-        const { task } = this.registerTask(spec, {
-            status: 'completed',
-            controller: null,
-            result,
-            error: null,
-            generation: 0,
-            startedAt: Date.now() - result.durationMs,
-            durationMs: result.durationMs,
-        }, 'return-existing');
-        return this.snapshot(task);
-    }
-    registerInterrupted(spec, error = 'Persisted agent was interrupted before completion') {
+    registerPersisted(spec, presentation = {}) {
         const { task } = this.registerTask(spec, {
-            status: 'interrupted',
+            status: spec.lifecycle.current(),
             controller: null,
-            result: null,
-            error,
-            generation: 0,
-            startedAt: Date.now(),
-            durationMs: 0,
-        }, 'return-existing');
-        return this.snapshot(task);
-    }
-    registerTerminal(spec, status, error) {
-        const { task } = this.registerTask(spec, {
-            status,
-            controller: null,
-            result: null,
-            error,
-            generation: 0,
-            startedAt: Date.now(),
-            durationMs: 0,
+            result: presentation.result ?? null,
+            error: presentation.error ?? null,
+            runSequence: 0,
+            startedAt: presentation.startedAt ??
+                (presentation.durationMs === undefined
+                    ? Date.now()
+                    : Date.now() - (presentation.durationMs ?? 0)),
+            durationMs: presentation.durationMs ?? null,
         }, 'return-existing');
         return this.snapshot(task);
     }
@@ -250,7 +249,12 @@ export class BackgroundAgentManager {
     }
     notificationClaimAgentIds() {
         return [...this.tasks.entries()]
-            .filter(([, task]) => task.status === 'running' || task.notifications.length > 0)
+            .filter(([, task]) => task.promise !== null ||
+            task.status === 'queued' ||
+            task.status === 'running' ||
+            task.status === 'waiting' ||
+            task.status === 'cancelling' ||
+            task.notifications.length > 0)
             .map(([agentId]) => agentId);
     }
     snapshotById(agentId) {
@@ -281,7 +285,7 @@ export class BackgroundAgentManager {
         // The retrieval outcome reflects the task's state after any wait: success
         // once terminal, not_ready for non-blocking retrievals, and timeout for a
         // blocking retrieval whose window (including zero) closed while live.
-        const retrieval = task.status !== 'running'
+        const retrieval = isTerminalLifecycleState(task.status)
             ? 'success'
             : options.block
                 ? 'timeout'
@@ -299,14 +303,21 @@ export class BackgroundAgentManager {
     async stopAndWait(agentId, timeout = DEFAULT_CLOSE_DRAIN_MS) {
         const message = this.stop(agentId);
         const task = this.tasks.get(agentId);
-        if (task?.promise)
+        if (task?.promise) {
             await waitBounded(task.promise, timeout);
+        }
+        if (!task || task.promise || !isTerminalLifecycleState(task.status)) {
+            return `Task ${agentId} cancellation is still in progress`;
+        }
+        if (task.status !== 'cancelled') {
+            return `Task ${agentId} cancellation ended with status ${legacyBackgroundStatus(task.status)}`;
+        }
         return message;
     }
     stopAll() {
         const stopped = [];
         for (const task of this.tasks.values()) {
-            if (task.status !== 'running' || !task.controller)
+            if (!task.promise || !task.controller || task.cancellationRequested)
                 continue;
             this.stopTask(task, 'Stopped by explicit bulk kill');
             stopped.push(task.spec.agentId);
@@ -325,8 +336,8 @@ export class BackgroundAgentManager {
         this.resolveClosed();
         const running = [];
         for (const task of this.tasks.values()) {
-            if (task.status === 'running' && task.controller) {
-                task.status = 'stopped';
+            if (task.promise && task.controller) {
+                task.cancellationRequested = true;
                 task.error = 'Stopped because the background agent manager closed';
                 task.suppressNotifications = true;
                 task.notifications.length = 0;
@@ -337,6 +348,8 @@ export class BackgroundAgentManager {
                 running.push(task.promise);
         }
         await waitBounded(Promise.allSettled(running).then(() => undefined), drainMilliseconds);
+        for (const task of this.tasks.values())
+            task.unsubscribeLifecycle?.();
         this.tasks.clear();
         this.names.clear();
     }
@@ -355,11 +368,21 @@ export class BackgroundAgentManager {
             });
         }
         const priorStatus = task.status;
-        if (task.promise && task.status === 'running') {
+        if (task.cancellationRequested &&
+            (task.promise !== null || task.status !== 'cancelled')) {
+            return JSON.stringify({
+                success: false,
+                message: `Agent "${agentId}" is cancelling and cannot receive a continuation yet.`,
+            });
+        }
+        if (task.promise) {
             task.queuedMessages.push({ message, toolUseId });
         }
         else {
-            this.start(task, message, true, toolUseId);
+            task.queuedMessages.push({ message, toolUseId });
+            const next = task.queuedMessages.shift();
+            if (next)
+                this.start(task, next.message, true, next.toolUseId);
         }
         return JSON.stringify({
             success: true,
@@ -373,7 +396,10 @@ export class BackgroundAgentManager {
             !eligibleTasks.some(([, task]) => task.notifications.length > 0)) {
             const running = eligibleTasks
                 .map(([, task]) => task)
-                .filter((task) => task.status === 'running')
+                .filter((task) => task.promise !== null ||
+                task.status === 'queued' ||
+                task.status === 'running' ||
+                task.status === 'cancelling')
                 .map((task) => task.promise)
                 .filter((promise) => promise !== null);
             if (running.length > 0) {
@@ -386,12 +412,16 @@ export class BackgroundAgentManager {
         let durationApiMs = 0;
         let durationApiWithoutRetriesMs = 0;
         let durationSeen = false;
-        const consumedTasks = [];
+        const consumedNotifications = [];
         for (const [, task] of eligibleTasks) {
             if (task.notifications.length === 0)
                 continue;
             for (const notification of task.notifications) {
-                notifications.push(this.formatNotification(task, notification));
+                const message = this.formatNotification(task, notification);
+                if (message === null)
+                    continue;
+                notifications.push(message);
+                consumedNotifications.push({ task, notification });
                 if (notification.result) {
                     assertValidResultUsage(notification.result.usage);
                     usage = addUsageChecked(undefined, usage, notification.result.usage);
@@ -407,18 +437,13 @@ export class BackgroundAgentManager {
                     durationApiWithoutRetriesMs = addApiDuration(notification.result.durationApiWithoutRetriesMs ?? total, durationApiWithoutRetriesMs, 'durationApiWithoutRetriesMs');
                 }
             }
-            consumedTasks.push(task);
         }
         const modelUsage = modelUsageByModel.size === 0
             ? undefined
             : Object.fromEntries(modelUsageByModel);
         if (options.consume !== false) {
-            for (const task of consumedTasks) {
-                if (!task.spec.acknowledgeNotification)
-                    continue;
-                for (const notification of task.notifications) {
-                    await task.spec.acknowledgeNotification(notification.id);
-                }
+            for (const { task, notification } of consumedNotifications) {
+                await task.spec.acknowledgeNotification?.(notification.id);
             }
         }
         const result = {
@@ -428,8 +453,9 @@ export class BackgroundAgentManager {
             ...(durationSeen ? { durationApiMs, durationApiWithoutRetriesMs } : {}),
         };
         if (options.consume !== false) {
-            for (const task of consumedTasks)
-                task.notifications.splice(0);
+            for (const { task, notification } of consumedNotifications) {
+                task.notifications.splice(task.notifications.indexOf(notification), 1);
+            }
         }
         return result;
     }
@@ -454,6 +480,8 @@ export class BackgroundAgentManager {
         for (const task of this.tasks.values()) {
             for (const notification of [...task.notifications]) {
                 const message = this.formatNotification(task, notification);
+                if (message === null)
+                    continue;
                 const index = remaining.indexOf(message);
                 if (index < 0)
                     continue;
@@ -465,9 +493,9 @@ export class BackgroundAgentManager {
     async acknowledgeDelivered(delivered) {
         for (const [agentId, task] of this.tasks) {
             for (const notification of [...task.notifications]) {
-                if (notification.status === 'interrupted')
+                const status = notificationWireStatus(notification.status);
+                if (status === null)
                     continue;
-                const status = notification.status === 'stopped' ? 'killed' : notification.status;
                 if (!delivered({ agentId, toolUseId: notification.toolUseId, status })) {
                     continue;
                 }
@@ -479,9 +507,9 @@ export class BackgroundAgentManager {
     async acknowledgeDeliveredAsDetached(delivered) {
         for (const [agentId, task] of this.tasks) {
             for (const notification of [...task.notifications]) {
-                if (notification.status === 'interrupted')
+                const status = notificationWireStatus(notification.status);
+                if (status === null)
                     continue;
-                const status = notification.status === 'stopped' ? 'killed' : notification.status;
                 if (!delivered({ agentId, toolUseId: notification.toolUseId, status })) {
                     continue;
                 }
@@ -493,67 +521,71 @@ export class BackgroundAgentManager {
         }
     }
     start(task, message, continuation, toolUseId) {
-        task.generation += 1;
-        const generation = task.generation;
+        task.runSequence += 1;
+        const runSequence = task.runSequence;
         const controller = new AbortController();
-        task.status = 'running';
+        task.cancellationRequested = false;
         task.startedAt = Date.now();
         task.durationMs = null;
         task.controller = controller;
         task.result = null;
         task.error = null;
-        this.track(task, task.spec.run(message, controller.signal, continuation, toolUseId), generation, toolUseId);
+        this.track(task, task.spec.run(message, controller.signal, continuation, toolUseId), runSequence, toolUseId);
     }
-    track(task, operation, generation, toolUseId) {
+    track(task, operation, runSequence, toolUseId) {
         task.promise = operation
             .then((result) => {
-            if (task.generation !== generation)
+            if (task.runSequence !== runSequence)
                 return;
-            if (task.status === 'stopped') {
-                this.finishStopped(task, result);
+            if (task.status === 'cancelled') {
+                this.finishCancelled(task, result);
                 return;
             }
-            task.status = 'completed';
             task.result = result;
             task.durationMs = result.durationMs;
             task.error = null;
-            task.notifications.push({
-                id: result.notificationId ?? randomUUID(),
-                status: 'completed',
-                result,
-                error: null,
-                toolUseId,
-            });
+            if (task.status === 'completed')
+                task.notifications.push({
+                    id: result.notificationId ?? randomUUID(),
+                    status: 'completed',
+                    result,
+                    error: null,
+                    toolUseId,
+                });
         })
             .catch((error) => {
-            if (task.generation !== generation)
+            if (task.runSequence !== runSequence)
                 return;
-            if (task.status === 'stopped') {
-                this.finishStopped(task, error instanceof BackgroundAgentRunError ? error.result : undefined);
+            if (task.status === 'cancelled') {
+                this.finishCancelled(task, error instanceof BackgroundAgentRunError ? error.result : undefined);
                 return;
             }
             const failedResult = error instanceof BackgroundAgentRunError ? error.result : undefined;
-            task.status = 'failed';
             task.result = null;
             task.durationMs =
                 failedResult?.durationMs ?? Date.now() - task.startedAt;
             task.error = error instanceof Error ? error.message : String(error);
-            task.notifications.push({
-                id: failedResult?.notificationId ?? randomUUID(),
-                status: 'failed',
-                result: failedResult ?? null,
-                error: task.error,
-                toolUseId,
-            });
+            if (task.status === 'failed')
+                task.notifications.push({
+                    id: failedResult?.notificationId ?? randomUUID(),
+                    status: 'failed',
+                    result: failedResult ?? null,
+                    error: task.error,
+                    toolUseId,
+                });
         })
             .finally(() => {
-            if (task.generation !== generation)
+            if (task.runSequence !== runSequence)
                 return;
             task.controller = null;
             task.promise = null;
-            const next = task.queuedMessages.shift();
-            if (next && task.status !== 'stopped') {
-                this.start(task, next.message, true, next.toolUseId);
+            if (!task.cancellationRequested &&
+                (task.status === 'completed' ||
+                    task.status === 'failed' ||
+                    task.status === 'cancelled')) {
+                const next = task.queuedMessages.shift();
+                if (next)
+                    this.start(task, next.message, true, next.toolUseId);
             }
         });
     }
@@ -582,7 +614,13 @@ export class BackgroundAgentManager {
             notifications: [],
             queuedMessages: [],
             suppressNotifications: false,
+            cancellationRequested: false,
+            unsubscribeLifecycle: null,
         };
+        task.unsubscribeLifecycle = spec.lifecycle.subscribe((state) => {
+            if (!this.closed)
+                task.status = state;
+        });
         this.tasks.set(spec.agentId, task);
         return { task, created: true };
     }
@@ -592,10 +630,11 @@ export class BackgroundAgentManager {
         return this.names.get(identifier);
     }
     stopTask(task, reason) {
-        if (task.status !== 'running' || !task.controller) {
-            throw new Error(`Task ${task.spec.agentId} is not running (status: ${task.status})`);
+        if (!task.promise || !task.controller || task.cancellationRequested) {
+            const status = legacyBackgroundStatus(task.status);
+            throw new Error(`Task ${task.spec.agentId} is not running (status: ${status})`);
         }
-        task.status = 'stopped';
+        task.cancellationRequested = true;
         task.error = reason;
         task.durationMs ??= Date.now() - task.startedAt;
         task.queuedMessages.length = 0;
@@ -609,7 +648,7 @@ export class BackgroundAgentManager {
             throw new Error(`Background agent name already exists: ${name}`);
         }
     }
-    finishStopped(task, result) {
+    finishCancelled(task, result) {
         const stoppedResult = result ?? {
             text: task.error ?? 'Stopped by TaskStop',
             usage: { inputTokens: 0, outputTokens: 0 },
@@ -621,7 +660,7 @@ export class BackgroundAgentManager {
         if (!task.suppressNotifications) {
             task.notifications.push({
                 id: stoppedResult.notificationId ?? randomUUID(),
-                status: 'stopped',
+                status: 'cancelled',
                 result: stoppedResult,
                 error: task.error,
                 toolUseId: task.spec.toolUseId,
@@ -653,11 +692,12 @@ export class BackgroundAgentManager {
     }
     formatOutput(task, retrieval) {
         const output = task.result?.text ?? task.error ?? '';
+        const status = legacyBackgroundStatus(task.status);
         return [
             `<retrieval_status>${retrieval}</retrieval_status>`,
             `<task_id>${task.spec.agentId}</task_id>`,
             '<task_type>local_agent</task_type>',
-            `<status>${task.status}</status>`,
+            `<status>${status}</status>`,
             ...(task.result?.isolationPath
                 ? [
                     `<worktree_path>${escapeXml(task.result.isolationPath)}</worktree_path>`,
@@ -674,7 +714,9 @@ export class BackgroundAgentManager {
     }
     formatNotification(task, notification) {
         const result = notification.result?.text ?? notification.error ?? '';
-        const status = notification.status === 'stopped' ? 'killed' : notification.status;
+        const status = notificationWireStatus(notification.status);
+        if (status === null)
+            return null;
         const usage = notification.result
             ? `<usage><total_tokens>${notification.result.usage.inputTokens + notification.result.usage.outputTokens}</total_tokens><tool_uses>${notification.result.toolUseCount}</tool_uses><duration_ms>${notification.result.durationMs}</duration_ms></usage>`
             : '';

package/dist/application/context-engine.d.ts

@@ -0,0 +1,56 @@
+import { type ModelProviderError, type ModelMessage, type ModelToolDefinition, type ModelUsage } from '../core/runtime.js';
+import { type ContextBudget, type ContextBudgetReport } from '../core/context-budget.js';
+export interface ContextEnvelope {
+    readonly messages: readonly ModelMessage[];
+    readonly tools: readonly ModelToolDefinition[];
+    readonly outputTokens?: number;
+}
+export interface ContextCompactionProposal {
+    readonly envelope: ContextEnvelope;
+    commit(): Promise<void>;
+}
+export interface ContextTransitionInput {
+    readonly trigger: 'auto' | 'reactive';
+    readonly before: ContextBudgetReport;
+    readonly irreducible: ContextBudgetReport;
+    readonly signal?: AbortSignal;
+}
+export interface ContextTransitionPort {
+    current(): ContextEnvelope;
+    irreducible(): ContextEnvelope;
+    propose(input: ContextTransitionInput): Promise<ContextCompactionProposal>;
+}
+export interface ContextEngineMemoryPort {
+    beforeCompact?(): Promise<void>;
+    afterCompact?(): Promise<void>;
+}
+export interface ContextEngineOptions {
+    budget?: ContextBudget;
+    memory?: ContextEngineMemoryPort;
+    autoCompact?: boolean;
+}
+export type ContextRecoveryResult = {
+    readonly kind: 'not-applicable';
+} | {
+    readonly kind: 'retry';
+    readonly envelope: ContextEnvelope;
+} | {
+    readonly kind: 'exhausted';
+    readonly error: ModelProviderError;
+};
+/** Owns context measurement, bounded recovery, and the proposal/commit seam. */
+export declare class ContextEngine {
+    private recoveryUsed;
+    private readonly budget;
+    private readonly memory;
+    private readonly autoCompact;
+    constructor(options?: ContextEngineOptions);
+    prepare(port: ContextTransitionPort, signal?: AbortSignal): Promise<ContextEnvelope>;
+    recover(error: unknown, port: ContextTransitionPort, signal?: AbortSignal): Promise<ContextRecoveryResult>;
+    observeUsage(usage: ModelUsage, messages: readonly ModelMessage[], tools: readonly ModelToolDefinition[]): void;
+    report(envelope: ContextEnvelope, options?: {
+        promptTooLong?: boolean;
+    }): ContextBudgetReport | undefined;
+    private reportRequired;
+}
+//# sourceMappingURL=context-engine.d.ts.map