praxis-agent 0.35.0 → 0.37.0

package/dist/platform/exclusive-file-lease.js

@@ -45,6 +45,9 @@ export class ExclusiveFileLease {
         if (!owner)
             return null;
         return {
+            token: owner.token,
+            pid: owner.pid,
+            createdAt: owner.createdAt,
             release: () => this.releaseOwned(this.lockFile, owner.token),
         };
     }

package/dist/tools/claude-capabilities.d.ts

@@ -25,6 +25,7 @@ export interface ClaudeToolCapabilityInput {
     readonly agentTriggers?: boolean;
     readonly backgroundAgents?: boolean;
     readonly subagents?: boolean;
+    readonly teams?: boolean;
     /** Explicit allow-list for capability-gated tools; never enables a gate. */
     readonly tools?: readonly string[];
     /** Always wins over the allow-list and the default rules. */
@@ -35,6 +36,7 @@ export interface ClaudeToolCapabilityInput {
 export declare const CLAUDE_CODE_ENABLE_TASKS = "CLAUDE_CODE_ENABLE_TASKS";
 export declare const CLAUDE_CODE_DISABLE_CRON = "CLAUDE_CODE_DISABLE_CRON";
 export declare const PRAXIS_ENABLE_WORKFLOW_SCRIPTS = "PRAXIS_ENABLE_WORKFLOW_SCRIPTS";
+export declare const PRAXIS_ENABLE_TEAMS = "PRAXIS_ENABLE_TEAMS";
 /** task-v2 task-board tools, gated by the `tasks` capability. */
 export declare const CLAUDE_TASK_V2_TOOLS: readonly ["TaskCreate", "TaskGet", "TaskList", "TaskUpdate"];
 /** Workflow tool, gated by the `workflowScripts` capability. */
@@ -45,6 +47,8 @@ export declare const CLAUDE_AGENT_TRIGGER_TOOLS: readonly ["CronCreate", "CronDe
 export declare const CLAUDE_AGENT_TOOLS: readonly ["Agent"];
 /** Background task lifecycle tools, gated by the `backgroundAgents` capability. */
 export declare const CLAUDE_BACKGROUND_TOOLS: readonly ["TaskOutput", "TaskStop"];
+/** Experimental local Team lifecycle names, gated by `PRAXIS_ENABLE_TEAMS`. */
+export declare const PRAXIS_TEAM_TOOLS: readonly ["TeamCreate", "TeamResume", "TeamList", "TeamAccept", "TeamStop", "TeamSend"];
 /** Coordination tools advertised by a coordinator only when explicitly enabled. */
 export declare const CLAUDE_COORDINATION_TOOLS: readonly ["AskUserQuestion", "SendMessage", "SendUserMessage", "Monitor", "PushNotification"];
 /** Recursively suppressed for worker agents regardless of any allow-list. */

package/dist/tools/claude-capabilities.js

@@ -3,6 +3,7 @@ import { resolveToolSchedulingPolicy } from '../core/tool-scheduling-policy.js';
 export const CLAUDE_CODE_ENABLE_TASKS = 'CLAUDE_CODE_ENABLE_TASKS';
 export const CLAUDE_CODE_DISABLE_CRON = 'CLAUDE_CODE_DISABLE_CRON';
 export const PRAXIS_ENABLE_WORKFLOW_SCRIPTS = 'PRAXIS_ENABLE_WORKFLOW_SCRIPTS';
+export const PRAXIS_ENABLE_TEAMS = 'PRAXIS_ENABLE_TEAMS';
 /** task-v2 task-board tools, gated by the `tasks` capability. */
 export const CLAUDE_TASK_V2_TOOLS = [
     'TaskCreate',
@@ -23,6 +24,15 @@ export const CLAUDE_AGENT_TRIGGER_TOOLS = [
 export const CLAUDE_AGENT_TOOLS = ['Agent'];
 /** Background task lifecycle tools, gated by the `backgroundAgents` capability. */
 export const CLAUDE_BACKGROUND_TOOLS = ['TaskOutput', 'TaskStop'];
+/** Experimental local Team lifecycle names, gated by `PRAXIS_ENABLE_TEAMS`. */
+export const PRAXIS_TEAM_TOOLS = Object.freeze([
+    'TeamCreate',
+    'TeamResume',
+    'TeamList',
+    'TeamAccept',
+    'TeamStop',
+    'TeamSend',
+]);
 /** Coordination tools advertised by a coordinator only when explicitly enabled. */
 export const CLAUDE_COORDINATION_TOOLS = [
     'AskUserQuestion',
@@ -43,6 +53,7 @@ export const CLAUDE_CAPABILITY_GATED_TOOLS = new Set([
     ...CLAUDE_AGENT_TRIGGER_TOOLS,
     ...CLAUDE_AGENT_TOOLS,
     ...CLAUDE_BACKGROUND_TOOLS,
+    ...PRAXIS_TEAM_TOOLS,
     ...CLAUDE_COORDINATION_TOOLS,
 ]);
 const EMPTY_ENV = {};
@@ -91,6 +102,7 @@ export function resolveClaudeToolCapabilities(input) {
     }
     const backgroundAgents = input.backgroundAgents ?? false;
     const subagents = input.subagents ?? false;
+    const teams = input.teams ?? envBoolean(env, PRAXIS_ENABLE_TEAMS) ?? false;
     if (input.tools)
         validateNames(input.tools, '--tools');
     if (input.disallowedTools)
@@ -121,13 +133,17 @@ export function resolveClaudeToolCapabilities(input) {
         for (const name of CLAUDE_BACKGROUND_TOOLS)
             enabled.add(name);
     }
+    if (teams) {
+        for (const name of PRAXIS_TEAM_TOOLS)
+            enabled.add(name);
+    }
     if (input.role === 'worker') {
-        for (const name of CLAUDE_WORKER_RECURSIVE_TOOLS)
+        for (const name of [...CLAUDE_WORKER_RECURSIVE_TOOLS, ...PRAXIS_TEAM_TOOLS])
             enabled.delete(name);
     }
     else if (input.role === 'coordinator') {
         const explicit = new Set(input.tools ?? []);
-        for (const name of CLAUDE_COORDINATION_TOOLS) {
+        for (const name of [...CLAUDE_COORDINATION_TOOLS, ...PRAXIS_TEAM_TOOLS]) {
             if (!explicit.has(name))
                 enabled.delete(name);
         }

package/dist/tools/team-lead-tools.d.ts

@@ -0,0 +1,19 @@
+import type { ModelToolCall, ModelToolDefinition, ToolExecutionContext, ToolExecutionResult, ToolRegistry } from '../core/runtime.js';
+import type { TeamLeadOperations } from '../application/team-lead-operations.js';
+/** Tools a Coordinator Lead may use; all other base/MCP tools are denied. */
+export declare const COORDINATOR_LEAD_ALLOWLIST: readonly ["Agent", "TaskOutput", "TaskStop", "TaskCreate", "TaskGet", "TaskList", "TaskUpdate", "AskUserQuestion", "EnterPlanMode", "ExitPlanMode", "SendMessage", "SendUserMessage", "Monitor", "PushNotification", "TeamCreate", "TeamResume", "TeamList", "TeamAccept", "TeamStop", "TeamSend"];
+export declare class TeamLeadToolRegistry implements ToolRegistry {
+    private readonly base;
+    private readonly operations;
+    private readonly sessionId;
+    private readonly enabled;
+    constructor(base: ToolRegistry, operations: TeamLeadOperations, sessionId: string, toolNames: readonly string[]);
+    definitions(): readonly ModelToolDefinition[];
+    schedulingPolicy(call: ModelToolCall): import("../core/runtime.js").ToolSchedulingPolicy;
+    prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
+    execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    private isAllowed;
+    private assertLeadPolicyAllows;
+    private result;
+}
+//# sourceMappingURL=team-lead-tools.d.ts.map

package/dist/tools/team-lead-tools.js

@@ -0,0 +1,479 @@
+import { parseTeamMailboxPayload, } from '../core/team-mailbox.js';
+import { parseTeamBudgetOverrides } from '../core/team-ownership.js';
+const names = [
+    'TeamCreate',
+    'TeamResume',
+    'TeamList',
+    'TeamAccept',
+    'TeamStop',
+    'TeamSend',
+];
+/** Tools a Coordinator Lead may use; all other base/MCP tools are denied. */
+export const COORDINATOR_LEAD_ALLOWLIST = Object.freeze([
+    'Agent',
+    'TaskOutput',
+    'TaskStop',
+    'TaskCreate',
+    'TaskGet',
+    'TaskList',
+    'TaskUpdate',
+    'AskUserQuestion',
+    'EnterPlanMode',
+    'ExitPlanMode',
+    'SendMessage',
+    'SendUserMessage',
+    'Monitor',
+    'PushNotification',
+    ...names,
+]);
+const coordinatorAllowlist = new Set(COORDINATOR_LEAD_ALLOWLIST);
+const teamPayloadSchema = {
+    oneOf: [
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'text'],
+            properties: {
+                kind: { const: 'text' },
+                text: { type: 'string', minLength: 1 },
+                summary: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId', 'taskId', 'text'],
+            properties: {
+                kind: { const: 'task' },
+                phase: { const: 'request' },
+                requestId: { type: 'string', minLength: 1 },
+                taskId: { type: 'string', minLength: 1 },
+                text: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId', 'taskId', 'status'],
+            properties: {
+                kind: { const: 'task' },
+                phase: { const: 'response' },
+                requestId: { type: 'string', minLength: 1 },
+                taskId: { type: 'string', minLength: 1 },
+                status: { enum: ['accepted', 'rejected', 'completed', 'failed'] },
+                text: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId'],
+            properties: {
+                kind: { const: 'shutdown' },
+                phase: { const: 'request' },
+                requestId: { type: 'string', minLength: 1 },
+                reason: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId', 'approved'],
+            properties: {
+                kind: { const: 'shutdown' },
+                phase: { const: 'response' },
+                requestId: { type: 'string', minLength: 1 },
+                approved: { type: 'boolean' },
+                reason: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId', 'plan'],
+            properties: {
+                kind: { const: 'plan' },
+                phase: { const: 'request' },
+                requestId: { type: 'string', minLength: 1 },
+                plan: { type: 'string', minLength: 1 },
+            },
+        },
+        {
+            type: 'object',
+            additionalProperties: false,
+            required: ['kind', 'phase', 'requestId', 'approved'],
+            properties: {
+                kind: { const: 'plan' },
+                phase: { const: 'response' },
+                requestId: { type: 'string', minLength: 1 },
+                approved: { type: 'boolean' },
+                feedback: { type: 'string', minLength: 1 },
+            },
+        },
+    ],
+};
+const definitions = [
+    {
+        name: 'TeamCreate',
+        description: 'Create a local Team.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['teamId', 'name', 'roster', 'tasks'],
+            properties: {
+                teamId: { type: 'string' },
+                name: { type: 'string' },
+                roster: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['name', 'agentType', 'access'],
+                        properties: {
+                            name: { type: 'string' },
+                            agentType: { type: 'string' },
+                            access: { enum: ['read-only', 'write'] },
+                        },
+                    },
+                },
+                tasks: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['id', 'description', 'assignee', 'blockedBy', 'claims'],
+                        properties: {
+                            id: { type: 'string' },
+                            description: { type: 'string' },
+                            assignee: { type: 'string' },
+                            blockedBy: { type: 'array', items: { type: 'string' } },
+                            claims: {
+                                type: 'object',
+                                additionalProperties: false,
+                                required: [
+                                    'files',
+                                    'publicContracts',
+                                    'generatedArtifacts',
+                                    'migrations',
+                                    'mergeTargets',
+                                ],
+                                properties: Object.fromEntries([
+                                    'files',
+                                    'publicContracts',
+                                    'generatedArtifacts',
+                                    'migrations',
+                                    'mergeTargets',
+                                ].map((key) => [
+                                    key,
+                                    { type: 'array', items: { type: 'string' } },
+                                ])),
+                            },
+                        },
+                    },
+                },
+                leadPolicy: { enum: ['hybrid', 'coordinator'] },
+                executionPolicy: { enum: ['sequential', 'swarm'] },
+                commitPolicy: { enum: ['lead'] },
+                budgets: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        maxAgents: { type: 'integer', minimum: 1 },
+                        maxConcurrent: { type: 'integer', minimum: 1 },
+                        maxTokens: { type: 'integer', minimum: 1 },
+                        maxDurationMs: { type: 'integer', minimum: 1 },
+                        shutdownDrainMs: { type: 'integer', minimum: 0, maximum: 600000 },
+                    },
+                },
+            },
+        },
+    },
+    {
+        name: 'TeamResume',
+        description: 'Resume a local Team.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['teamId'],
+            properties: { teamId: { type: 'string' } },
+        },
+    },
+    {
+        name: 'TeamList',
+        description: 'List local Teams.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {},
+        },
+    },
+    {
+        name: 'TeamAccept',
+        description: 'Accept or reject a completed Team task.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['teamId', 'taskId'],
+            properties: {
+                teamId: { type: 'string' },
+                taskId: { type: 'string' },
+                generation: { type: 'integer', minimum: 0 },
+                decision: { enum: ['accepted', 'rejected'], default: 'accepted' },
+            },
+        },
+    },
+    {
+        name: 'TeamStop',
+        description: 'Stop a local Team.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['teamId'],
+            properties: {
+                teamId: { type: 'string' },
+                drainMs: { type: 'integer', minimum: 0, maximum: 600000 },
+            },
+        },
+    },
+    {
+        name: 'TeamSend',
+        description: 'Send a typed message through a local Team mailbox.',
+        inputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['teamId', 'to', 'payload'],
+            properties: {
+                teamId: { type: 'string' },
+                to: {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'array', items: { type: 'string' }, minItems: 1 },
+                        { const: 'broadcast' },
+                    ],
+                },
+                payload: teamPayloadSchema,
+            },
+        },
+    },
+];
+function objectInput(input, allowed) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Team tool input must be an object');
+    for (const key of Object.keys(input))
+        if (!allowed.includes(key))
+            throw new Error(`Unknown Team field: ${key}`);
+}
+function stringValue(input, key) {
+    const value = input[key];
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error(`Invalid ${key}`);
+    return value;
+}
+function validate(input, name) {
+    if (name === 'TeamCreate') {
+        objectInput(input, [
+            'teamId',
+            'name',
+            'roster',
+            'tasks',
+            'leadPolicy',
+            'executionPolicy',
+            'commitPolicy',
+            'budgets',
+        ]);
+        stringValue(input, 'teamId');
+        stringValue(input, 'name');
+        if (!Array.isArray(input.roster) || !Array.isArray(input.tasks))
+            throw new Error('Invalid Team roster or tasks');
+        if (input.leadPolicy !== undefined &&
+            input.leadPolicy !== 'hybrid' &&
+            input.leadPolicy !== 'coordinator')
+            throw new Error('Invalid leadPolicy');
+        if (input.executionPolicy !== undefined &&
+            input.executionPolicy !== 'sequential' &&
+            input.executionPolicy !== 'swarm')
+            throw new Error('Invalid executionPolicy');
+        if (input.commitPolicy !== undefined && input.commitPolicy !== 'lead')
+            throw new Error('Invalid commitPolicy');
+        if (input.budgets !== undefined) {
+            if (!input.budgets ||
+                typeof input.budgets !== 'object' ||
+                Array.isArray(input.budgets))
+                throw new Error('Invalid Team budgets');
+            parseTeamBudgetOverrides(input.budgets);
+        }
+        for (const member of input.roster) {
+            if (!member || typeof member !== 'object' || Array.isArray(member))
+                throw new Error('Invalid Team member');
+            objectInput(member, [
+                'name',
+                'agentType',
+                'access',
+            ]);
+        }
+        for (const task of input.tasks) {
+            if (!task || typeof task !== 'object' || Array.isArray(task))
+                throw new Error('Invalid Team task');
+            const value = task;
+            objectInput(value, [
+                'id',
+                'description',
+                'assignee',
+                'blockedBy',
+                'claims',
+            ]);
+            if (!value.claims ||
+                typeof value.claims !== 'object' ||
+                Array.isArray(value.claims))
+                throw new Error('Invalid Team claims');
+            objectInput(value.claims, [
+                'files',
+                'publicContracts',
+                'generatedArtifacts',
+                'migrations',
+                'mergeTargets',
+            ]);
+        }
+        return input;
+    }
+    if (name === 'TeamList') {
+        objectInput(input, []);
+        return {};
+    }
+    if (name === 'TeamResume') {
+        objectInput(input, ['teamId']);
+        stringValue(input, 'teamId');
+        return input;
+    }
+    if (name === 'TeamAccept') {
+        objectInput(input, ['teamId', 'taskId', 'generation', 'decision']);
+        stringValue(input, 'teamId');
+        stringValue(input, 'taskId');
+        if (input.generation !== undefined &&
+            (!Number.isSafeInteger(input.generation) ||
+                input.generation < 0))
+            throw new Error('Invalid generation');
+        if (input.decision !== undefined &&
+            input.decision !== 'accepted' &&
+            input.decision !== 'rejected')
+            throw new Error('Invalid decision');
+        return {
+            ...input,
+            ...(input.decision === undefined ? { decision: 'accepted' } : {}),
+        };
+    }
+    if (name === 'TeamSend') {
+        objectInput(input, ['teamId', 'to', 'payload']);
+        stringValue(input, 'teamId');
+        if (input.to !== 'broadcast') {
+            if (typeof input.to === 'string') {
+                stringValue(input, 'to');
+            }
+            else if (Array.isArray(input.to)) {
+                if (input.to.length === 0 ||
+                    input.to.some((value) => typeof value !== 'string' || value.trim() === ''))
+                    throw new Error('Invalid Team recipients');
+            }
+            else
+                throw new Error('Invalid Team recipients');
+        }
+        return { ...input, payload: parseTeamMailboxPayload(input.payload) };
+    }
+    objectInput(input, ['teamId', 'drainMs']);
+    stringValue(input, 'teamId');
+    if (input.drainMs !== undefined &&
+        (typeof input.drainMs !== 'number' ||
+            !Number.isFinite(input.drainMs) ||
+            input.drainMs < 0 ||
+            input.drainMs > 600000))
+        throw new Error('Invalid drainMs');
+    if (input.drainMs !== undefined && !Number.isSafeInteger(input.drainMs))
+        throw new Error('Invalid drainMs');
+    return input;
+}
+export class TeamLeadToolRegistry {
+    base;
+    operations;
+    sessionId;
+    enabled;
+    constructor(base, operations, sessionId, toolNames) {
+        this.base = base;
+        this.operations = operations;
+        this.sessionId = sessionId;
+        this.enabled = new Set(toolNames.filter((name) => names.includes(name)));
+    }
+    definitions() {
+        return [
+            ...this.base
+                .definitions()
+                .filter((definition) => this.isAllowed(definition.name)),
+            ...definitions.filter((definition) => this.enabled.has(definition.name) && this.isAllowed(definition.name)),
+        ];
+    }
+    schedulingPolicy(call) {
+        this.assertLeadPolicyAllows(call.name);
+        if (names.includes(call.name)) {
+            if (!this.enabled.has(call.name))
+                throw new Error(`Tool ${call.name} is unavailable`);
+            return { concurrency: 'exclusive', cancelOnInterrupt: true };
+        }
+        return (this.base.schedulingPolicy?.(call) ?? {
+            concurrency: 'concurrent',
+        });
+    }
+    async prepare(call, context) {
+        this.assertLeadPolicyAllows(call.name);
+        if (names.includes(call.name) && !this.enabled.has(call.name))
+            throw new Error(`Tool ${call.name} is unavailable`);
+        if (!this.enabled.has(call.name))
+            return this.base.prepare(call, context);
+        return { ...call, input: validate(call.input, call.name) };
+    }
+    async execute(call, context) {
+        this.assertLeadPolicyAllows(call.name);
+        if (names.includes(call.name) && !this.enabled.has(call.name))
+            throw new Error(`Tool ${call.name} is unavailable`);
+        if (!this.enabled.has(call.name))
+            return this.base.execute(call, context);
+        if (context.signal?.aborted)
+            throw new Error('Team tool interrupted');
+        const input = validate(call.input, call.name);
+        let value;
+        switch (call.name) {
+            case 'TeamCreate':
+                value = await this.operations.create(input, this.sessionId);
+                break;
+            case 'TeamResume':
+                value = await this.operations.resume(input.teamId, this.sessionId);
+                break;
+            case 'TeamList':
+                return this.result({ teams: await this.operations.list() });
+            case 'TeamAccept':
+                value = await this.operations.accept(input, this.sessionId);
+                break;
+            case 'TeamStop':
+                value = await this.operations.stop(input, this.sessionId);
+                break;
+            case 'TeamSend':
+                value = await this.operations.send(input, this.sessionId, call.id);
+                return this.result({ message: value });
+        }
+        return this.result({ team: value });
+    }
+    isAllowed(name) {
+        return (this.operations.activeLeadPolicy(this.sessionId) !== 'coordinator' ||
+            coordinatorAllowlist.has(name));
+    }
+    assertLeadPolicyAllows(name) {
+        if (!this.isAllowed(name))
+            throw new Error(`Tool ${name} is unavailable for Coordinator Lead`);
+    }
+    result(value) {
+        return {
+            content: JSON.stringify(value),
+            isError: false,
+            nativeToolUseResult: value,
+        };
+    }
+}
+//# sourceMappingURL=team-lead-tools.js.map

package/dist/tools/team-member-tools.d.ts

@@ -0,0 +1,21 @@
+import type { ModelToolCall, ModelToolDefinition, ToolExecutionContext, ToolExecutionResult, ToolRegistry, ToolSchedulingPolicy } from '../core/runtime.js';
+export interface TeamMemberToolRegistryOptions {
+    readonly base: ToolRegistry;
+    readonly access: 'read-only' | 'write';
+    readonly cwd: string;
+}
+export declare class TeamMemberToolRegistry implements ToolRegistry {
+    private readonly options;
+    private readonly allowed;
+    private readonly canonicalCwdPromise;
+    constructor(options: TeamMemberToolRegistryOptions);
+    definitions(): readonly ModelToolDefinition[];
+    schedulingPolicy(call: ModelToolCall): ToolSchedulingPolicy;
+    prepare(call: ModelToolCall, context: ToolExecutionContext): Promise<ModelToolCall>;
+    execute(call: ModelToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    private validateCallShape;
+    private validate;
+    private validateNormalizedCommand;
+    private hasInlineInterpreter;
+}
+//# sourceMappingURL=team-member-tools.d.ts.map