praxis-agent 0.60.0 → 0.61.0

package/dist/application/workflow-worktree.d.ts

@@ -1,9 +1,18 @@
 import { type ManagedWorktree } from './managed-worktree.js';
+import type { ClaudeHookRunner } from '../hooks/claude-hooks.js';
 export type WorkflowWorktree = ManagedWorktree;
+export interface WorkflowWorktreeHookContext {
+    runner: ClaudeHookRunner;
+    sessionId: string;
+    transcriptPath: string;
+    permissionMode: string;
+    signal?: AbortSignal;
+}
 export declare function createWorkflowWorktree(options: {
     cwd: string;
     praxisRoot: string;
     runId: string;
     agentId: string;
+    hookContext?: WorkflowWorktreeHookContext;
 }): Promise<WorkflowWorktree>;
 //# sourceMappingURL=workflow-worktree.d.ts.map

package/dist/application/workflow-worktree.js

@@ -1,11 +1,38 @@
-import { join } from 'node:path';
-import { createManagedWorktree, } from './managed-worktree.js';
+import { createOwnedManagedWorktree, } from './managed-worktree.js';
+function lifecycleHookInput(input, context, event) {
+    const reason = 'reason' in input ? input.reason : undefined;
+    return {
+        session_id: context.sessionId,
+        transcript_path: context.transcriptPath,
+        cwd: input.worktreePath,
+        permission_mode: context.permissionMode,
+        hook_event_name: event,
+        worktree_path: input.worktreePath,
+        worktree_kind: input.worktreeKind,
+        worktree_id: input.worktreeId,
+        owner_id: input.ownerId,
+        base_commit: input.baseCommit,
+        ...(event === 'WorktreeRemove' && reason !== undefined ? { reason } : {}),
+    };
+}
+function lifecycleHooks(context) {
+    return {
+        afterCreate: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeCreate'), input.worktreeKind, context.signal),
+        beforeRemove: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeRemove'), input.worktreeKind, context.signal),
+    };
+}
 export async function createWorkflowWorktree(options) {
-    return createManagedWorktree({
+    return createOwnedManagedWorktree({
         cwd: options.cwd,
-        parentDirectory: join(options.praxisRoot, 'workflow-worktrees'),
+        stateRoot: options.praxisRoot,
         directoryName: `${options.runId}-${options.agentId}`,
+        ownerId: `workflow:${options.runId}:${options.agentId}`,
         label: 'Workflow',
+        kind: 'workflow',
+        policy: 'ephemeral',
+        ...(options.hookContext
+            ? { hooks: lifecycleHooks(options.hookContext) }
+            : {}),
     });
 }
 //# sourceMappingURL=workflow-worktree.js.map

package/dist/cli/protocol.d.ts

@@ -243,6 +243,7 @@ export interface ProtocolTimingProjection {
 }
 export declare function projectProtocolTimings(startedAt: number, requestAt?: number, outputAt?: number): ProtocolTimingProjection;
 export declare function createSuccessResult(result: ProtocolResult, info: CliRuntimeInfo, startedAt: number, modelTurns: number, context?: ProtocolSuccessProjectionContext): Record<string, unknown>;
+export declare function formatPrintTextError(message: string, context?: ProtocolErrorProjectionContext): string;
 export declare function createErrorResult(message: string, sessionId: string, startedAt: number, modelTurns: number, context?: ProtocolErrorProjectionContext): Record<string, unknown>;
 /**
  * Returns the argument text of a headless `/color` prompt, or undefined when

package/dist/cli/protocol.js

@@ -94,14 +94,44 @@ export function createSuccessResult(result, info, startedAt, modelTurns, context
         uuid: randomUUID(),
     };
 }
+function classifyErrorResult(message) {
+    const maxBudget = /Maximum budget of \$([0-9]+(?:\.[0-9]+)?) exceeded/iu.exec(message);
+    if (maxBudget || /maximum budget|budget .* exceeded/iu.test(message)) {
+        return {
+            subtype: 'error_max_budget_usd',
+            ...(maxBudget?.[1] === undefined ? {} : { maxBudgetUsd: maxBudget[1] }),
+        };
+    }
+    const maxTurns = /Maximum model turns of (\d+) exceeded/iu.exec(message);
+    if (maxTurns || /maximum model turns|model turn limit/iu.test(message)) {
+        return {
+            subtype: 'error_max_turns',
+            ...(maxTurns?.[1] === undefined ? {} : { maxTurns: maxTurns[1] }),
+        };
+    }
+    if (/StructuredOutput/iu.test(message)) {
+        return { subtype: 'error_max_structured_output_retries' };
+    }
+    return { subtype: 'error_during_execution' };
+}
 function errorResultSubtype(message) {
-    if (/maximum budget|budget .* exceeded/iu.test(message))
-        return 'error_max_budget_usd';
-    if (/maximum model turns|model turn limit/iu.test(message))
-        return 'error_max_turns';
-    if (/StructuredOutput/iu.test(message))
-        return 'error_max_structured_output_retries';
-    return 'error_during_execution';
+    return classifyErrorResult(message).subtype;
+}
+export function formatPrintTextError(message, context = {}) {
+    if (context.providerApiError === true) {
+        const normalized = typeof context.apiErrorStatus === 'number'
+            ? normalizeApiError(message, context.apiErrorStatus)
+            : message;
+        return `${normalized}\n`;
+    }
+    const classification = classifyErrorResult(message);
+    if (classification.maxTurns !== undefined)
+        return `Error: Reached max turns (${classification.maxTurns})`;
+    if (classification.maxBudgetUsd !== undefined)
+        return `Error: Exceeded USD budget (${classification.maxBudgetUsd})`;
+    if (classification.subtype === 'error_max_structured_output_retries')
+        return 'Error: Failed to provide valid structured output after maximum retries';
+    return 'Execution error';
 }
 export function createErrorResult(message, sessionId, startedAt, modelTurns, context = {}) {
     const duration = Date.now() - startedAt;

package/dist/cli-runtime.d.ts

@@ -34,6 +34,7 @@ export interface CliIO {
     stdout(message: string | Uint8Array): void;
     stderr(message: string): void;
     isTTY?: boolean;
+    stdinIsTTY?: boolean;
     readStdinLines?: () => AsyncIterable<string | Uint8Array>;
     readSecret?: (prompt: string, signal?: AbortSignal) => Promise<string>;
 }

package/dist/cli-runtime.js

@@ -65,7 +65,7 @@ import { WorkspaceContext } from './application/session-worktree.js';
 import { launchTmuxWorktree } from './platform/tmux-worktree.js';
 import { claudeSandboxRuntime } from './sandbox/claude-sandbox-runtime.js';
 import { nativeSandboxTempDirectory, loadClaudeSandboxSettings, } from './sandbox/claude-sandbox-settings.js';
-import { createErrorResult, createSuccessResult, isHeadlessCostCommand, matchHeadlessColorCommand, parseCliInvocation, projectProtocolTimings, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
+import { createErrorResult, createSuccessResult, isHeadlessCostCommand, matchHeadlessColorCommand, formatPrintTextError, parseCliInvocation, projectProtocolTimings, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
 import { isDirectProcessSigint } from './cli/process-signal.js';
 import { executeProviderAuthCommand } from './cli/provider-auth-command.js';
 import { describeClaudePlugin, initClaudePlugin, installClaudePlugin, loadClaudePlugins, readPluginRegistry, setClaudePluginEnabled, uninstallClaudePlugin, updateClaudePlugin, validateClaudePlugin, } from './plugins/claude-plugin-runtime.js';
@@ -893,6 +893,7 @@ const consoleIO = {
     stdout: (message) => process.stdout.write(message),
     stderr: (message) => process.stderr.write(message),
     isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    stdinIsTTY: Boolean(process.stdin.isTTY),
     readStdinLines: () => process.stdin,
     readSecret: readConsoleSecret,
 };
@@ -4243,7 +4244,7 @@ async function executeMcpCommand(args, invocation, io, dependencies, signal) {
     }
     throw new Error(`Unknown mcp command: ${action}`);
 }
-function eventSink(io, outputFormat, legacyJson = false) {
+function eventSink(io, outputFormat, legacyJson = false, printText = false) {
     const sensitiveValues = sensitiveEnvironmentValues(process.env);
     if (legacyJson) {
         return (event) => {
@@ -4261,6 +4262,12 @@ function eventSink(io, outputFormat, legacyJson = false) {
     }
     if (outputFormat !== 'text')
         return () => undefined;
+    if (printText)
+        return (event) => {
+            if (event.type === 'warning') {
+                io.stderr(`Warning: ${redactSensitiveText(event.message, sensitiveValues)}\n`);
+            }
+        };
     let turnBuffered = false;
     let bufferedText = '';
     const flushBufferedText = () => {
@@ -4313,6 +4320,29 @@ function promptFrom(values) {
         throw new Error('Prompt is required');
     return prompt;
 }
+async function resolvePrintTextPrompt(io, argvPrompt) {
+    const missingInput = () => new Error('Error: Input must be provided either through stdin or as a prompt argument when using --print');
+    if (io.stdinIsTTY !== false) {
+        if (argvPrompt !== undefined)
+            return argvPrompt;
+        throw missingInput();
+    }
+    const input = io.readStdinLines?.();
+    if (!input)
+        throw new Error('print text input requires stdin support');
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const stdinText = Buffer.concat(chunks).toString('utf8');
+    if (argvPrompt !== undefined && stdinText.length > 0)
+        return `${argvPrompt}\n${stdinText}`;
+    if (argvPrompt !== undefined)
+        return argvPrompt;
+    if (stdinText.length > 0)
+        return stdinText;
+    throw missingInput();
+}
 function backgroundWorkerArgv(argv) {
     const filtered = [];
     let optionsEnded = false;
@@ -5578,9 +5608,14 @@ async function execute(argv, io, dependencies, signal) {
         };
     };
     const headlessPromptArgs = command === 'resume' ? args.slice(2) : knownCommand ? args.slice(1) : args;
-    const headlessPrompt = inputFormat === 'text' && headlessPromptArgs.length > 0
+    const headlessTurnReached = invocation.rewindFiles === undefined &&
+        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
+    const argvHeadlessPrompt = inputFormat === 'text' && headlessPromptArgs.length > 0
         ? promptFrom(headlessPromptArgs)
         : undefined;
+    const headlessPrompt = inputFormat === 'text' && headlessTurnReached && invocation.print
+        ? await resolvePrintTextPrompt(io, argvHeadlessPrompt)
+        : argvHeadlessPrompt;
     if (headlessPrompt === '/release-notes' && !invocation.disableSlashCommands) {
         const startedAt = Date.now();
         const sessionId = invocation.sessionId ?? randomUUID();
@@ -5629,8 +5664,6 @@ async function execute(argv, io, dependencies, signal) {
         }
         return 0;
     }
-    const headlessTurnReached = invocation.rewindFiles === undefined &&
-        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
     if (streamIterator && headlessTurnReached) {
         const first = await nextStreamUser();
         if (first)
@@ -5686,7 +5719,7 @@ async function execute(argv, io, dependencies, signal) {
                         io.stderr(`Warning: ${redactSensitiveText(event.message, sensitiveEnvironmentValues(process.env))}\n`);
                     }
                 }
-                : eventSink(io, outputFormat, invocation.legacyJson),
+                : eventSink(io, outputFormat, invocation.legacyJson, invocation.print && inputFormat === 'text'),
         requireProvider: !streamInputExhausted &&
             !firstTurnIsLocalColor &&
             !firstTurnIsLocalCost &&
@@ -5818,6 +5851,7 @@ async function execute(argv, io, dependencies, signal) {
         if (streamInputExhausted)
             return 0;
         const initialPrompt = firstStreamMessage?.prompt ??
+            headlessPrompt ??
             promptFrom(command === 'resume'
                 ? args.slice(2)
                 : knownCommand
@@ -5833,7 +5867,6 @@ async function execute(argv, io, dependencies, signal) {
             signal?.addEventListener('abort', forwardAbort, { once: true });
             currentTurnAbort = streamIterator ? turnAbort : undefined;
             const runSignal = streamIterator ? turnAbort.signal : signal;
-            await ensureCostBaseline(activeSessionId);
             jsonModelTurns = 0;
             jsonRequestAt = undefined;
             jsonOutputAt = undefined;
@@ -5851,6 +5884,7 @@ async function execute(argv, io, dependencies, signal) {
             let colorArgs;
             let costTurn = false;
             try {
+                await ensureCostBaseline(activeSessionId);
                 costTurn =
                     !invocation.disableSlashCommands && isHeadlessCostCommand(prompt);
                 colorArgs = invocation.disableSlashCommands
@@ -5939,6 +5973,11 @@ async function execute(argv, io, dependencies, signal) {
                 else if (outputFormat === 'json') {
                     writeJson(io, createErrorResult(message, activeSessionId, startedAt, jsonModelTurns, errorContext));
                 }
+                else if (invocation.print &&
+                    inputFormat === 'text' &&
+                    outputFormat === 'text') {
+                    io.stdout(formatPrintTextError(message, errorContext));
+                }
                 else {
                     if (currentTurnAbort === turnAbort)
                         currentTurnAbort = undefined;
@@ -5971,6 +6010,8 @@ async function execute(argv, io, dependencies, signal) {
             }
             else if (outputFormat !== 'text')
                 writeJson(io, { type: 'result', ...result });
+            else if (invocation.print && inputFormat === 'text')
+                io.stdout(`${result.text}\n`);
             else
                 io.stdout(localCommand ? `${result.text}\n` : '\n');
             if (streamOutput && invocation.promptSuggestions) {

package/dist/hooks/claude-hooks.js

@@ -28,7 +28,14 @@ export const HOOK_EVENTS = [
     'FileChanged',
     'SessionEnd',
 ];
-const EXECUTABLE_HOOK_EVENTS = new Set(HOOK_EVENTS);
+const LIFECYCLE_HOOK_EVENTS = [
+    'WorktreeCreate',
+    'WorktreeRemove',
+];
+const EXECUTABLE_HOOK_EVENTS = new Set([
+    ...HOOK_EVENTS,
+    ...LIFECYCLE_HOOK_EVENTS,
+]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -91,6 +98,9 @@ function eventSettings(settings, event, maxTimeoutMs) {
                 if (hook.async !== undefined && typeof hook.async !== 'boolean') {
                     throw new Error(`Invalid Claude ${event} hook async: ${resource.path}`);
                 }
+                if (LIFECYCLE_HOOK_EVENTS.includes(event) && hook.async === true) {
+                    throw new Error(`Invalid Claude ${event} hook async: ${resource.path}`);
+                }
                 return [
                     {
                         command,
@@ -145,8 +155,9 @@ export function validateClaudeHooks(settings, maxTimeoutMs = DEFAULT_TIMEOUT_MS)
         !Number.isInteger(maxTimeoutMs)) {
         throw new Error('Hook max timeout must be a positive integer');
     }
-    for (const event of HOOK_EVENTS)
+    for (const event of [...HOOK_EVENTS, ...LIFECYCLE_HOOK_EVENTS]) {
         eventSettings(settings, event, maxTimeoutMs);
+    }
 }
 function outputRecord(stdout) {
     const trimmed = stdout.trim();
@@ -204,6 +215,9 @@ function hookMatcherValue(input) {
             return basename(optionalString(input.file_path) ?? '');
         case 'SessionEnd':
             return optionalString(input.reason) ?? '';
+        case 'WorktreeCreate':
+        case 'WorktreeRemove':
+            return optionalString(input.worktree_kind) ?? '';
         default:
             return '';
     }

package/dist/persistence/managed-worktree-store.d.ts

@@ -0,0 +1,41 @@
+import { type ExclusiveFileLeaseHandle } from '../platform/exclusive-file-lease.js';
+type ManagedWorktreeKind = 'workflow' | 'agent' | 'team';
+type ManagedWorktreePolicy = 'ephemeral' | 'durable';
+type ManagedWorktreeState = 'creating' | 'active' | 'releasing' | 'retained' | 'released';
+export interface ManagedWorktreeRecord {
+    version: 1;
+    worktreeId: string;
+    kind: ManagedWorktreeKind;
+    policy: ManagedWorktreePolicy;
+    ownerId: string;
+    repositoryRoot: string;
+    worktreePath: string;
+    branch: string | null;
+    baseCommit: string;
+    state: ManagedWorktreeState;
+    createdAt: string;
+    updatedAt: string;
+    retentionReason?: string;
+}
+export declare class ManagedWorktreeStore {
+    readonly path: string;
+    readonly lockPath: string;
+    readonly projectLockPath: string;
+    private readonly directory;
+    private readonly stateRoot;
+    private readonly repositoryRoot;
+    private readonly worktreeId;
+    private readonly worktreeLease;
+    private readonly projectLease;
+    constructor(stateRoot: string, repositoryRoot: string, worktreeId: string);
+    acquireLease(): Promise<ExclusiveFileLeaseHandle | null>;
+    read(): Promise<ManagedWorktreeRecord>;
+    create(record: ManagedWorktreeRecord): Promise<void>;
+    update(record: ManagedWorktreeRecord): Promise<void>;
+    private withProjectLease;
+    private assertUnreservedPath;
+    private assertStoreIdentity;
+    private assertSameIdentity;
+}
+export {};
+//# sourceMappingURL=managed-worktree-store.d.ts.map