praxis-agent 0.35.0 → 0.37.0

package/dist/application/team-mailbox.js

@@ -0,0 +1,196 @@
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { parseTeamMailboxPayload, } from '../core/team-mailbox.js';
+import { parseTeamId } from '../core/team-ownership.js';
+import { NativeTeamMailbox, } from '../persistence/native-team-mailbox.js';
+const DEFAULT_MAX_BYTES = 64 * 1024;
+const DEFAULT_MAX_MESSAGES = 32;
+function participant(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        throw new Error('Invalid Team mailbox participant');
+    return value;
+}
+function operationIdentity(value) {
+    if (typeof value !== 'string' ||
+        value.trim() === '' ||
+        value !== value.trim() ||
+        value.length > 300 ||
+        value.includes('\r') ||
+        value.includes('\n'))
+        throw new Error('Invalid Team mailbox operation ID');
+    return value;
+}
+export function teamMailboxMessageId(teamId, sender, operationId) {
+    const values = [
+        parseTeamId(teamId),
+        participant(sender),
+        operationIdentity(operationId),
+    ];
+    const hash = createHash('sha256');
+    for (const value of values) {
+        const bytes = Buffer.from(value, 'utf8');
+        hash.update(Buffer.from(String(bytes.length) + ':', 'ascii'));
+        hash.update(bytes);
+    }
+    return hash.digest('hex');
+}
+function render(message) {
+    return `<team-mailbox-message>\n${JSON.stringify(message)}\n</team-mailbox-message>`;
+}
+function assertBound(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`Invalid ${label}`);
+    return value;
+}
+export class TeamMailboxService {
+    options;
+    store;
+    participants;
+    participantSet;
+    constructor(options) {
+        this.options = options;
+        if (!Array.isArray(options.participants) ||
+            options.participants.length === 0)
+            throw new Error('Invalid Team mailbox participants');
+        this.participants = Object.freeze(options.participants.map(participant));
+        if (new Set(this.participants).size !== this.participants.length ||
+            !this.participants.includes('lead'))
+            throw new Error('Invalid Team mailbox roster');
+        this.participantSet = new Set(this.participants);
+        if (options.store) {
+            this.store = options.store;
+        }
+        else {
+            if (!options.nativeRoot || !options.projectIdentity)
+                throw new Error('Native Team mailbox root and project identity are required');
+            this.store = NativeTeamMailbox.open({
+                nativeRoot: options.nativeRoot,
+                projectIdentity: options.projectIdentity,
+                teamId: options.teamId,
+                participants: this.participants,
+                ...(options.retention ? { retention: options.retention } : {}),
+            });
+        }
+    }
+    endpoint(sender) {
+        this.assertParticipant(sender);
+        return new TeamMailboxEndpoint(this, sender);
+    }
+    async send(input, sender) {
+        this.assertParticipant(sender);
+        const recipients = this.recipients(input.to, sender);
+        const result = await this.store.append({
+            messageId: input.messageId,
+            sender,
+            recipients,
+            payload: parseTeamMailboxPayload(input.payload),
+            ...(input.createdAt === undefined ? {} : { createdAt: input.createdAt }),
+        });
+        if (this.options.wake) {
+            try {
+                await this.options.wake({
+                    teamId: result.message.teamId,
+                    messageId: result.message.messageId,
+                    sequence: result.message.sequence,
+                    recipients: result.message.recipients,
+                });
+            }
+            catch (error) {
+                try {
+                    this.options.warn?.(`Team mailbox wake failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                catch {
+                    // Advisory reporting must not change a durably persisted send result.
+                }
+            }
+        }
+        return result.message;
+    }
+    async project(sender, bounds = {}) {
+        this.assertParticipant(sender);
+        const maxBytes = bounds.maxBytes === undefined
+            ? DEFAULT_MAX_BYTES
+            : assertBound(bounds.maxBytes, 'mailbox projection maxBytes');
+        const maxMessages = bounds.maxMessages === undefined
+            ? DEFAULT_MAX_MESSAGES
+            : assertBound(bounds.maxMessages, 'mailbox projection maxMessages');
+        const read = await this.store.read(sender, { maxMessages });
+        if (read.messages.length === 0)
+            return null;
+        const messages = [];
+        let bytes = 0;
+        for (const message of read.messages) {
+            const text = render(message);
+            const size = Buffer.byteLength(text, 'utf8');
+            if (messages.length === 0 && size > maxBytes)
+                throw new Error('First Team mailbox message exceeds projection budget');
+            if (messages.length >= maxMessages || bytes + size > maxBytes)
+                break;
+            messages.push(text);
+            bytes += size;
+        }
+        if (messages.length === 0)
+            return null;
+        const selected = read.messages.slice(0, messages.length);
+        const last = selected[selected.length - 1];
+        if (!last)
+            throw new Error('Team mailbox projection selected no messages');
+        const proof = {
+            participant: sender,
+            expectedCursor: read.expectedCursor,
+            throughSequence: last.sequence,
+            messageIds: selected.map((message) => message.messageId),
+        };
+        const id = `${this.options.teamId}:${sender}:${proof.expectedCursor}-${proof.throughSequence}`;
+        let acknowledged = false;
+        return {
+            id,
+            messages: Object.freeze(messages),
+            acknowledge: async () => {
+                if (acknowledged)
+                    return;
+                await this.store.acknowledge(proof);
+                acknowledged = true;
+            },
+        };
+    }
+    recipients(to, sender) {
+        if (to === 'broadcast') {
+            return Object.freeze([...this.participants].filter((name) => name !== sender).sort());
+        }
+        const values = typeof to === 'string' ? [to] : [...to];
+        if (values.length === 0)
+            throw new Error('Team mailbox delivery requires a recipient');
+        const result = [];
+        for (const value of values) {
+            this.assertParticipant(value);
+            if (value === sender)
+                throw new Error('Team mailbox sender cannot address itself');
+            if (!result.includes(value))
+                result.push(value);
+        }
+        if (result.length === 0)
+            throw new Error('Team mailbox delivery requires a recipient');
+        return Object.freeze(result);
+    }
+    assertParticipant(value) {
+        const name = participant(value);
+        if (!this.participantSet.has(name))
+            throw new Error(`Unknown Team mailbox participant: ${name}`);
+    }
+}
+export class TeamMailboxEndpoint {
+    service;
+    participant;
+    constructor(service, participant) {
+        this.service = service;
+        this.participant = participant;
+    }
+    send(input) {
+        return this.service.send(input, this.participant);
+    }
+    project(bounds) {
+        return this.service.project(this.participant, bounds);
+    }
+}
+//# sourceMappingURL=team-mailbox.js.map

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

@@ -0,0 +1,113 @@
+import type { PermissionResolver, ToolRegistry } from '../core/runtime.js';
+import { type TeamMember, type TeamSnapshot, type TeamTask, type TeamLeadPolicy, type TeamExecutionPolicy, type TeamCommitPolicy, DEFAULT_TEAM_BUDGETS } from '../core/team-ownership.js';
+import { type NativeTeamClaim } from '../persistence/native-team-store.js';
+import { type TeamWorkspaceProvider } from './team-workspace.js';
+import { TeamMailboxService, type TeamMailboxEndpoint } from './team-mailbox.js';
+export interface TeamCreateTaskInput extends Omit<TeamTask, 'execution' | 'usage'> {
+}
+export interface TeamCreateInput {
+    readonly teamId: string;
+    readonly name: string;
+    readonly leadSessionId: string;
+    readonly roster: readonly TeamMember[];
+    readonly tasks: readonly TeamCreateTaskInput[];
+    readonly leadPolicy?: TeamLeadPolicy;
+    readonly executionPolicy?: TeamExecutionPolicy;
+    readonly commitPolicy?: TeamCommitPolicy;
+    readonly budgets?: Partial<typeof DEFAULT_TEAM_BUDGETS>;
+}
+export interface TeamAgentProgress {
+    readonly generation: number;
+    readonly totalTokens: number;
+    readonly durationMs: number;
+}
+export interface TeamAgentRunResult {
+    readonly status: 'completed' | 'failed' | 'orphaned';
+    readonly totalTokens: number;
+    readonly durationMs: number;
+}
+export interface TeamAgentRuntime {
+    run(input: {
+        readonly teamId: string;
+        readonly task: TeamTask;
+        readonly member: TeamMember;
+        readonly generation: number;
+        readonly cwd: string;
+        readonly branch: string | null;
+        readonly tools: ToolRegistry;
+        readonly permissions: PermissionResolver;
+        readonly signal: AbortSignal;
+        readonly mailbox: TeamMailboxEndpoint;
+        readonly reportProgress: (progress: TeamAgentProgress) => void;
+    }): Promise<TeamAgentRunResult>;
+}
+export interface LocalTeamManagerOptions {
+    readonly nativeRoot: string;
+    readonly cwd: string;
+    readonly maxConcurrent: number;
+    readonly baseTools: ToolRegistry;
+    readonly permissions: PermissionResolver;
+    readonly runtime: TeamAgentRuntime;
+    readonly workspace?: TeamWorkspaceProvider;
+}
+export declare class LocalTeamManager {
+    private readonly store;
+    private readonly options;
+    private readonly workspace;
+    private constructor();
+    static open(options: LocalTeamManagerOptions): Promise<LocalTeamManager>;
+    create(input: TeamCreateInput): Promise<LocalTeam>;
+    resume(input: {
+        teamId: string;
+        leadSessionId: string;
+    }): Promise<LocalTeam>;
+    list(): Promise<readonly TeamSnapshot[]>;
+}
+export declare class LocalTeam {
+    private readonly options;
+    private readonly workspace;
+    private readonly claim;
+    private readonly mailbox;
+    private mutation;
+    private readonly active;
+    private admissionOpen;
+    private stopping;
+    private detaching;
+    private detachedSnapshot;
+    private finalSnapshot;
+    private pumpFailure;
+    private readonly indeterminate;
+    private readonly progressWrites;
+    private readonly stopStarted;
+    private readonly resolveStopStarted;
+    private deadlineTimer;
+    private progressOpen;
+    constructor(options: LocalTeamManagerOptions, workspace: TeamWorkspaceProvider, claim: NativeTeamClaim, mailbox: TeamMailboxService);
+    mailboxEndpoint(participant: string): TeamMailboxEndpoint;
+    initialize(resume: boolean): Promise<void>;
+    snapshot(): Promise<TeamSnapshot>;
+    waitForIdle(): Promise<TeamSnapshot>;
+    accept(taskId: string, generation?: number, decision?: 'accepted' | 'rejected'): Promise<TeamSnapshot>;
+    stop(options?: {
+        drainMs?: number;
+    }): Promise<TeamSnapshot>;
+    detach(): Promise<TeamSnapshot>;
+    private detachInternal;
+    private stopWithBudget;
+    private stopInternal;
+    private clearDeadlineTimer;
+    private enqueue;
+    private reconcileOrphans;
+    private pump;
+    private pumpMutation;
+    private launch;
+    private complete;
+    private queueProgress;
+    private persistProgress;
+    private initializeDeadline;
+    private exhaustDuration;
+    private beginBudgetShutdown;
+    private markCancelling;
+    private finishStopping;
+}
+//# sourceMappingURL=team-manager.d.ts.map