praxis-agent 0.35.0 → 0.37.0

package/dist/application/team-agent-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { ModelProvider, ModelToolCall, PermissionApproval, PermissionDecision, PermissionResolver, RuntimeEventSink } from '../core/runtime.js';
+import type { ContextAssembler } from '../core/context.js';
+import type { ClaudeExtensionCatalog } from '../extensions/claude-extensions.js';
+import type { ClaudeHookRunner } from '../hooks/claude-hooks.js';
+import { type AgentPermissionMode } from './subagent-service.js';
+import type { TeamAgentRuntime } from './team-manager.js';
+export interface ClaudeTeamAgentRuntimeOptions {
+    readonly nativeRoot: string;
+    readonly configRoot: string;
+    readonly claudeVersion: string;
+    readonly provider: ModelProvider;
+    readonly extensions?: ClaudeExtensionCatalog;
+    readonly hooks?: ClaudeHookRunner;
+    readonly contextAssembler?: ContextAssembler;
+    readonly providerForModel?: (model: string) => ModelProvider;
+    readonly permissionResolverForMode?: (mode: AgentPermissionMode) => PermissionResolver;
+    readonly eventSink?: RuntimeEventSink;
+    readonly approveTool?: (call: ModelToolCall, originalCall?: ModelToolCall, decision?: PermissionDecision) => PermissionApproval | Promise<PermissionApproval>;
+}
+export declare class ClaudeTeamAgentRuntime implements TeamAgentRuntime {
+    private readonly options;
+    constructor(options: ClaudeTeamAgentRuntimeOptions);
+    run(input: Parameters<TeamAgentRuntime['run']>[0]): Promise<{
+        status: 'completed' | 'failed' | 'orphaned';
+        totalTokens: number;
+        durationMs: number;
+    }>;
+}
+//# sourceMappingURL=team-agent-runtime.d.ts.map

package/dist/application/team-agent-runtime.js

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveProjectIdentity } from '../platform/project-identity.js';
+import { sanitizeProjectPath } from '../platform/project-path-key.js';
+import { ClaudeSubagentExecutor, } from './subagent-service.js';
+import { teamMailboxMessageId } from './team-mailbox.js';
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function uuidFromHex(hex) {
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+function executionIdentity(projectIdentity, teamId, taskId, generation) {
+    const value = `${projectIdentity}\0${teamId}\0${taskId}\0${generation}`;
+    const hash = digest(value);
+    return {
+        sessionId: uuidFromHex(hash),
+        promptId: uuidFromHex(digest(`${value}\0prompt`)),
+        runId: `wf_${hash.slice(0, 8)}${hash.slice(8, 14)}-${hash.slice(14, 17)}`,
+        agentId: `a${hash.slice(0, 16)}`,
+        taskDirectory: `${sanitizeProjectPath(taskId)}-${hash.slice(16, 28)}/generation-${generation}`,
+    };
+}
+function taskPrompt(input) {
+    return [
+        `Assigned task ID: ${input.task.id}`,
+        `Assigned Team task: ${input.task.description}`,
+        `Team member: ${input.member.name}`,
+        `Agent type: ${input.member.agentType}`,
+        `Access: ${input.member.access}`,
+        `Assigned cwd: ${input.cwd}`,
+        `Assigned branch: ${input.branch ?? '(shared invocation checkout)'}`,
+        `Claimed files: ${input.task.claims.files.join(', ') || '(none)'}`,
+        `Claimed public contracts: ${input.task.claims.publicContracts.join(', ') || '(none)'}`,
+        `Claimed generated artifacts: ${input.task.claims.generatedArtifacts.join(', ') || '(none)'}`,
+        `Claimed migrations: ${input.task.claims.migrations.join(', ') || '(none)'}`,
+        `Claimed merge targets: ${input.task.claims.mergeTargets.join(', ') || '(none)'}`,
+        'Use only the tools provided for this Team member and work only in the assigned cwd.',
+    ].join('\n');
+}
+export class ClaudeTeamAgentRuntime {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async run(input) {
+        if (this.options.provider.capabilities.usage !== true)
+            throw new Error('Team agent runtime requires provider usage capability');
+        const projectIdentity = await resolveProjectIdentity(input.cwd);
+        const identity = executionIdentity(projectIdentity, input.teamId, input.task.id, input.generation);
+        const transcriptDirectory = join(this.options.nativeRoot, 'state', 'team-executions', sanitizeProjectPath(projectIdentity), `team-${digest(input.teamId).slice(0, 16)}`, identity.taskDirectory);
+        await mkdir(transcriptDirectory, { recursive: true });
+        const approveTool = this.options.approveTool;
+        const executor = new ClaudeSubagentExecutor({
+            configRoot: this.options.configRoot,
+            dataPlane: 'native',
+            cwd: input.cwd,
+            cwdProvider: () => input.cwd,
+            claudeVersion: this.options.claudeVersion,
+            provider: this.options.provider,
+            persistence: 'disk',
+            baseTools: input.tools,
+            permissions: input.permissions,
+            ...(this.options.extensions
+                ? { extensions: this.options.extensions }
+                : {}),
+            ...(this.options.hooks ? { hooks: this.options.hooks } : {}),
+            ...(this.options.contextAssembler
+                ? { contextAssembler: this.options.contextAssembler }
+                : {}),
+            ...(this.options.providerForModel
+                ? { providerForModel: this.options.providerForModel }
+                : {}),
+            ...(this.options.permissionResolverForMode
+                ? {
+                    permissionResolverForMode: this.options.permissionResolverForMode,
+                }
+                : {}),
+            eventSink: (event) => {
+                if (event.type === 'task-progress')
+                    input.reportProgress({
+                        generation: input.generation,
+                        totalTokens: event.usage.totalTokens,
+                        durationMs: event.usage.durationMs,
+                    });
+                this.options.eventSink?.(event);
+            },
+            ...(approveTool
+                ? {
+                    approveTool: (call, originalCall, decision) => {
+                        const wrapped = decision?.behavior === 'ask'
+                            ? {
+                                ...decision,
+                                reason: `${decision.reason ?? 'Team permission request'} [team=${input.teamId} member=${input.member.name} task=${input.task.id} generation=${input.generation}]`,
+                                metadata: {
+                                    ...(decision.metadata ?? {}),
+                                    teamId: input.teamId,
+                                    member: input.member.name,
+                                    taskId: input.task.id,
+                                    generation: input.generation,
+                                },
+                            }
+                            : decision;
+                        return approveTool(call, originalCall, wrapped);
+                    },
+                }
+                : {}),
+            sendOwnedBackgroundAgent: async (_sessionId, _agentId, message, summary, toolUseId) => {
+                const recipient = _agentId;
+                const to = recipient === 'broadcast' ? 'broadcast' : recipient;
+                const endpoint = input.mailbox;
+                await endpoint.send({
+                    messageId: teamMailboxMessageId(input.teamId, input.member.name, toolUseId),
+                    to,
+                    payload: {
+                        kind: 'text',
+                        text: message,
+                        ...(summary === undefined ? {} : { summary }),
+                    },
+                });
+                return 'Message sent successfully.';
+            },
+            durableFollowUpSource: () => input.mailbox.project(),
+        });
+        let failure;
+        let workflowResult;
+        try {
+            workflowResult = await executor.runWorkflowAgent({
+                sessionId: identity.sessionId,
+                promptId: identity.promptId,
+                runId: identity.runId,
+                agentId: identity.agentId,
+                transcriptDirectory,
+                prompt: taskPrompt(input),
+                agentType: input.member.agentType,
+                signal: input.signal,
+            });
+        }
+        catch (error) {
+            failure = error;
+        }
+        let closeFailure;
+        try {
+            await executor.close();
+        }
+        catch (error) {
+            closeFailure = error;
+        }
+        if (failure !== undefined && closeFailure !== undefined) {
+            throw new AggregateError([failure, closeFailure], 'Team agent execution and cleanup failed', { cause: failure });
+        }
+        if (failure !== undefined)
+            throw failure;
+        if (closeFailure !== undefined)
+            throw closeFailure;
+        if (!workflowResult)
+            throw new Error('Team agent workflow completed without a result');
+        const totalTokens = workflowResult.usage.inputTokens + workflowResult.usage.outputTokens;
+        const durationMs = workflowResult.durationMs;
+        input.reportProgress({
+            generation: input.generation,
+            totalTokens,
+            durationMs,
+        });
+        return { status: 'completed', totalTokens, durationMs };
+    }
+}
+//# sourceMappingURL=team-agent-runtime.js.map

package/dist/application/team-capability.d.ts

@@ -0,0 +1,27 @@
+import type { PermissionResolver, ToolRegistry } from '../core/runtime.js';
+import type { ClaudeTeamAgentRuntime } from './team-agent-runtime.js';
+import { LocalTeamManager } from './team-manager.js';
+/** The local Team manager's conservative default parallelism. */
+export declare const DEFAULT_LOCAL_TEAM_CONCURRENCY = 4;
+export interface LocalTeamCapabilityOptions {
+    readonly nativeRoot: string;
+    /** Resolves the active workspace at the moment the Team capability opens. */
+    readonly cwd: () => string;
+    readonly maxConcurrent: number;
+    readonly baseTools: ToolRegistry;
+    readonly permissions: PermissionResolver;
+    readonly createRuntime: () => ClaudeTeamAgentRuntime;
+}
+/**
+ * Lazy internal seam for the future Team lead tools.
+ *
+ * Keeping this port private to composition means enabling the experimental
+ * capability cannot perform Team discovery during ordinary session startup.
+ */
+export declare class LocalTeamCapability {
+    private readonly options;
+    private openPromise;
+    constructor(options: LocalTeamCapabilityOptions);
+    open(): Promise<LocalTeamManager>;
+}
+//# sourceMappingURL=team-capability.d.ts.map

package/dist/application/team-capability.js

@@ -0,0 +1,41 @@
+import { LocalTeamManager } from './team-manager.js';
+/** The local Team manager's conservative default parallelism. */
+export const DEFAULT_LOCAL_TEAM_CONCURRENCY = 4;
+/**
+ * Lazy internal seam for the future Team lead tools.
+ *
+ * Keeping this port private to composition means enabling the experimental
+ * capability cannot perform Team discovery during ordinary session startup.
+ */
+export class LocalTeamCapability {
+    options;
+    openPromise;
+    constructor(options) {
+        this.options = options;
+    }
+    open() {
+        if (this.openPromise)
+            return this.openPromise;
+        const promise = (async () => {
+            const cwd = this.options.cwd();
+            if (!cwd)
+                throw new Error('A Team workspace cwd is required');
+            const runtime = this.options.createRuntime();
+            return LocalTeamManager.open({
+                nativeRoot: this.options.nativeRoot,
+                cwd,
+                maxConcurrent: this.options.maxConcurrent,
+                baseTools: this.options.baseTools,
+                permissions: this.options.permissions,
+                runtime,
+            });
+        })();
+        this.openPromise = promise;
+        void promise.catch(() => {
+            if (this.openPromise === promise)
+                this.openPromise = undefined;
+        });
+        return promise;
+    }
+}
+//# sourceMappingURL=team-capability.js.map

package/dist/application/team-lead-operations.d.ts

@@ -0,0 +1,38 @@
+import type { TeamMailboxMessage } from '../core/team-mailbox.js';
+import type { TeamSnapshot } from '../core/team-ownership.js';
+import type { LocalTeamManager } from './team-manager.js';
+import type { LocalTeamCapability } from './team-capability.js';
+import type { DurableTeamMailboxBatch, TeamMailboxProjectBounds, TeamMailboxSendInput } from './team-mailbox.js';
+export type TeamCreateRequest = Omit<Parameters<LocalTeamManager['create']>[0], 'leadSessionId'>;
+export interface TeamLeadSendInput extends Omit<TeamMailboxSendInput, 'messageId'> {
+    readonly teamId: string;
+}
+export declare class TeamLeadOperations {
+    private readonly capability;
+    private readonly owned;
+    private closed;
+    constructor(capability: Pick<LocalTeamCapability, 'open'>);
+    create(input: TeamCreateRequest, leadSessionId: string): Promise<TeamSnapshot>;
+    resume(teamId: string, leadSessionId: string): Promise<TeamSnapshot>;
+    activeLeadPolicy(leadSessionId: string): 'hybrid' | 'coordinator';
+    list(): Promise<readonly TeamSnapshot[]>;
+    accept(input: {
+        teamId: string;
+        taskId: string;
+        generation?: number;
+        decision?: 'accepted' | 'rejected';
+    }, leadSessionId: string): Promise<TeamSnapshot>;
+    send(input: TeamLeadSendInput, leadSessionId: string, operationId: string): Promise<TeamMailboxMessage>;
+    projectInbox(leadSessionId: string, bounds?: TeamMailboxProjectBounds): Promise<DurableTeamMailboxBatch | null>;
+    stop(input: {
+        teamId: string;
+        drainMs?: number;
+    }, leadSessionId: string): Promise<TeamSnapshot>;
+    waitForIdle(teamId: string, leadSessionId: string): Promise<TeamSnapshot>;
+    detach(teamId: string, leadSessionId: string): Promise<TeamSnapshot>;
+    close(): Promise<void>;
+    private manager;
+    private require;
+    private forLead;
+}
+//# sourceMappingURL=team-lead-operations.d.ts.map

package/dist/application/team-lead-operations.js

@@ -0,0 +1,155 @@
+import { Buffer } from 'node:buffer';
+import { teamMailboxMessageId } from './team-mailbox.js';
+export class TeamLeadOperations {
+    capability;
+    owned = new Map();
+    closed = false;
+    constructor(capability) {
+        this.capability = capability;
+    }
+    async create(input, leadSessionId) {
+        const manager = await this.manager();
+        if (this.owned.has(input.teamId))
+            throw new Error(`Team ${input.teamId} is already active`);
+        const team = await manager.create({ ...input, leadSessionId });
+        const snapshot = await team.snapshot();
+        this.owned.set(input.teamId, {
+            leadSessionId,
+            team,
+            leadPolicy: snapshot.policy?.lead ?? 'hybrid',
+        });
+        return snapshot;
+    }
+    async resume(teamId, leadSessionId) {
+        const current = this.owned.get(teamId);
+        if (current) {
+            if (current.leadSessionId !== leadSessionId)
+                throw new Error(`Team ${teamId} is active under another lead session`);
+            return current.team.snapshot();
+        }
+        const team = await (await this.manager()).resume({ teamId, leadSessionId });
+        const snapshot = await team.snapshot();
+        this.owned.set(teamId, {
+            leadSessionId,
+            team,
+            leadPolicy: snapshot.policy?.lead ?? 'hybrid',
+        });
+        return snapshot;
+    }
+    activeLeadPolicy(leadSessionId) {
+        for (const owned of this.owned.values())
+            if (owned.leadSessionId === leadSessionId &&
+                owned.leadPolicy === 'coordinator')
+                return 'coordinator';
+        return 'hybrid';
+    }
+    async list() {
+        return (await this.manager()).list();
+    }
+    async accept(input, leadSessionId) {
+        return this.forLead(input.teamId, leadSessionId, (team) => team.accept(input.taskId, input.generation, input.decision));
+    }
+    async send(input, leadSessionId, operationId) {
+        const owned = this.require(input.teamId, leadSessionId);
+        return owned.team.mailboxEndpoint('lead').send({
+            messageId: teamMailboxMessageId(input.teamId, 'lead', operationId),
+            to: input.to,
+            payload: input.payload,
+            ...(input.createdAt === undefined ? {} : { createdAt: input.createdAt }),
+        });
+    }
+    async projectInbox(leadSessionId, bounds = {}) {
+        const maxBytes = bounds.maxBytes ?? 64 * 1024;
+        const maxMessages = bounds.maxMessages ?? 32;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+            throw new Error('Invalid Team inbox maxBytes');
+        if (!Number.isSafeInteger(maxMessages) || maxMessages <= 0)
+            throw new Error('Invalid Team inbox maxMessages');
+        const batches = [];
+        let bytes = 0;
+        let messageCount = 0;
+        for (const owned of [...this.owned.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([, value]) => value)) {
+            if (owned.leadSessionId !== leadSessionId)
+                continue;
+            const remainingMessages = maxMessages - messageCount;
+            if (remainingMessages <= 0)
+                break;
+            const batch = await owned.team.mailboxEndpoint('lead').project({
+                maxBytes: maxBytes - bytes,
+                maxMessages: remainingMessages,
+            });
+            if (!batch)
+                continue;
+            batches.push(batch);
+            bytes += batch.messages.reduce((total, message) => total + Buffer.byteLength(message, 'utf8'), 0);
+            messageCount += batch.messages.length;
+            if (bytes >= maxBytes || messageCount >= maxMessages)
+                break;
+        }
+        if (batches.length === 0)
+            return null;
+        let acknowledged = false;
+        return {
+            id: `lead:${leadSessionId}:${batches.map((batch) => batch.id).join('|')}`,
+            messages: Object.freeze(batches.flatMap((batch) => batch.messages)),
+            acknowledge: async () => {
+                if (acknowledged)
+                    return;
+                for (const batch of batches)
+                    await batch.acknowledge();
+                acknowledged = true;
+            },
+        };
+    }
+    async stop(input, leadSessionId) {
+        const owned = this.require(input.teamId, leadSessionId);
+        const snapshot = await owned.team.stop(input.drainMs === undefined ? {} : { drainMs: input.drainMs });
+        this.owned.delete(input.teamId);
+        return snapshot;
+    }
+    async waitForIdle(teamId, leadSessionId) {
+        return this.forLead(teamId, leadSessionId, (team) => team.waitForIdle());
+    }
+    async detach(teamId, leadSessionId) {
+        const owned = this.require(teamId, leadSessionId);
+        const snapshot = await owned.team.detach();
+        this.owned.delete(teamId);
+        return snapshot;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const failures = [];
+        for (const [teamId, owned] of this.owned) {
+            try {
+                await owned.team.stop();
+                this.owned.delete(teamId);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (failures.length)
+            throw new AggregateError(failures, 'Failed to stop Teams');
+    }
+    async manager() {
+        if (this.closed)
+            throw new Error('Team lead operations are closed');
+        return this.capability.open();
+    }
+    require(teamId, leadSessionId) {
+        const owned = this.owned.get(teamId);
+        if (!owned)
+            throw new Error(`Team ${teamId} is not active; resume it first`);
+        if (owned.leadSessionId !== leadSessionId)
+            throw new Error(`Team ${teamId} is active under another lead session`);
+        return owned;
+    }
+    async forLead(teamId, leadSessionId, operation) {
+        return operation(this.require(teamId, leadSessionId).team);
+    }
+}
+//# sourceMappingURL=team-lead-operations.js.map

package/dist/application/team-mailbox.d.ts

@@ -0,0 +1,54 @@
+import { type TeamMailboxMessage, type TeamMailboxPayload } from '../core/team-mailbox.js';
+import { NativeTeamMailbox, type NativeTeamMailboxRetention } from '../persistence/native-team-mailbox.js';
+export interface TeamMailboxWakeMetadata {
+    readonly teamId: string;
+    readonly messageId: string;
+    readonly sequence: number;
+    readonly recipients: readonly string[];
+}
+export interface DurableTeamMailboxBatch {
+    readonly id: string;
+    readonly messages: readonly string[];
+    acknowledge(): Promise<void>;
+}
+export interface TeamMailboxSendInput {
+    readonly messageId: string;
+    readonly to: string | readonly string[] | 'broadcast';
+    readonly payload: TeamMailboxPayload;
+    readonly createdAt?: string;
+}
+export interface TeamMailboxProjectBounds {
+    readonly maxBytes?: number;
+    readonly maxMessages?: number;
+}
+export interface TeamMailboxOptions {
+    readonly nativeRoot?: string;
+    readonly projectIdentity?: string;
+    readonly teamId: string;
+    readonly participants: readonly string[];
+    readonly store?: NativeTeamMailbox;
+    readonly retention?: NativeTeamMailboxRetention;
+    readonly wake?: (metadata: TeamMailboxWakeMetadata) => void | Promise<void>;
+    readonly warn?: (message: string) => void;
+}
+export declare function teamMailboxMessageId(teamId: string, sender: string, operationId: string): string;
+export declare class TeamMailboxService {
+    private readonly options;
+    readonly store: NativeTeamMailbox;
+    private readonly participants;
+    private readonly participantSet;
+    constructor(options: TeamMailboxOptions);
+    endpoint(sender: string): TeamMailboxEndpoint;
+    send(input: TeamMailboxSendInput, sender: string): Promise<TeamMailboxMessage>;
+    project(sender: string, bounds?: TeamMailboxProjectBounds): Promise<DurableTeamMailboxBatch | null>;
+    private recipients;
+    private assertParticipant;
+}
+export declare class TeamMailboxEndpoint {
+    private readonly service;
+    readonly participant: string;
+    constructor(service: TeamMailboxService, participant: string);
+    send(input: TeamMailboxSendInput): Promise<TeamMailboxMessage>;
+    project(bounds?: TeamMailboxProjectBounds): Promise<DurableTeamMailboxBatch | null>;
+}
+//# sourceMappingURL=team-mailbox.d.ts.map