@khorsheed/dsh-room 0.1.0

package/lib/types/plan-service.js

@@ -0,0 +1,266 @@
+import { randomUUID } from 'node:crypto';
+import { coordinatorMember, memberId, replay } from './journal.js';
+import { activePlanMs, dependencyResults, admitPlanAttempt, changePlan, parsePlanCommand, planCommandSignature, queuePlanAttempt, readyPlanTasks, recoverPlan, settlePlanAttempt } from './plan.js';
+export function readPlan(room) {
+    const event = room.snapshotEvents().filter(event => event.type === 'room/plan-state').at(-1);
+    return event?.type === 'room/plan-state' ? structuredClone(event.data) : undefined;
+}
+/** One serialized writer for durable goal transitions and automatic leaf dispatch. */
+export class PlanService {
+    ctx;
+    engine;
+    tails = new Map();
+    recovered = new Set();
+    timers = new Map();
+    constructor(ctx, engine) {
+        this.ctx = ctx;
+        this.engine = engine;
+    }
+    locked(room, action) {
+        const previous = this.tails.get(room.id) ?? Promise.resolve();
+        const next = previous.catch(() => { }).then(action);
+        this.tails.set(room.id, next);
+        void next.finally(() => { if (this.tails.get(room.id) === next)
+            this.tails.delete(room.id); }).catch(() => { });
+        return next;
+    }
+    /** Cold inspection projects the restart pause without writing or starting agents. */
+    view(sessionId, view) {
+        if (this.recovered.has(sessionId))
+            return view;
+        const { requests: _requests, ...recovered } = recoverPlan({ ...view, requests: [] }, Date.now());
+        return recovered;
+    }
+    async recover(room) {
+        return this.locked(room, () => this.recoverUnlocked(room));
+    }
+    async recoverUnlocked(room) {
+        if (this.recovered.has(room.id))
+            return;
+        const current = readPlan(room);
+        if (current !== undefined) {
+            const recovered = recoverPlan(current, Date.now());
+            const events = room.snapshotEvents();
+            for (const task of recovered.tasks) {
+                const attempt = task.attempts.at(-1);
+                if (attempt?.status !== 'queued')
+                    continue;
+                const dispatch = events.find(event => event.type === 'room/dispatch' && event.data.id === attempt.deliveryId);
+                if (dispatch?.type !== 'room/dispatch')
+                    continue;
+                const edge = events.filter(event => event.type === 'room/delivery-state' && event.data.dispatchSeq === dispatch.seq).at(-1);
+                if (edge?.type === 'room/delivery-state' && ['running', 'uncertain'].includes(edge.data.state)) {
+                    attempt.status = 'uncertain';
+                    attempt.error = 'Restart interrupted the durable admission boundary';
+                    task.status = 'failed';
+                    recovered.status = 'paused';
+                    recovered.reason = 'Reconcile uncertain attempts before continuing';
+                }
+            }
+            room.append('room/plan-state', recovered);
+            await this.ctx.sessions.flush(room);
+        }
+        this.recovered.add(room.id);
+    }
+    async write(room, plan) {
+        room.append('room/plan-state', plan);
+        await this.ctx.sessions.flush(room);
+        this.armDeadline(room, plan);
+    }
+    armDeadline(room, plan) {
+        clearTimeout(this.timers.get(room.id));
+        this.timers.delete(room.id);
+        if (plan.status !== 'running')
+            return;
+        const remaining = Math.max(1, plan.budget.maxActiveMs - activePlanMs(plan, Date.now()));
+        const timer = setTimeout(() => {
+            void this.locked(room, async () => {
+                const current = readPlan(room);
+                if (current?.status !== 'running')
+                    return;
+                if (activePlanMs(current, Date.now()) < current.budget.maxActiveMs) {
+                    this.armDeadline(room, current);
+                    return;
+                }
+                const paused = changePlan(current, { action: 'pause', reason: 'Active-time budget exhausted', requestId: randomUUID(), expectedRevision: current.revision }, { actor: { kind: 'coordinator', memberId: 'budget-timer' }, memberIds: new Set(), now: Date.now() });
+                await this.write(room, paused);
+            }).catch(error => this.ctx.logger.warn(`room: goal deadline persistence failed: ${String(error)}`));
+        }, Math.min(remaining, 2147483647));
+        timer.unref?.();
+        this.timers.set(room.id, timer);
+    }
+    async command(room, json, actor) {
+        const command = parsePlanCommand(json);
+        return this.locked(room, async () => {
+            await this.recoverUnlocked(room);
+            const events = room.snapshotEvents();
+            const state = replay(events);
+            const members = new Set(state.members.map(member => memberId(events, member)));
+            if (actor.kind !== 'human' && !members.has(actor.memberId))
+                throw new Error('Calling member left the room');
+            const coordinator = coordinatorMember(state, events);
+            if (actor.kind === 'coordinator' && (coordinator === undefined || memberId(events, coordinator) !== actor.memberId))
+                throw new Error('Coordinator changed before command admission');
+            // Check all revisions, including a previous closed goal, before reusing an identity.
+            const earlier = events.filter(event => event.type === 'room/plan-state').flatMap(event => event.type === 'room/plan-state' ? event.data.requests : []).find(receipt => receipt.id === command.requestId);
+            if (earlier !== undefined) {
+                if (earlier.signature !== planCommandSignature(command))
+                    throw new Error('Plan request identity was reused for different input');
+                await this.ctx.sessions.flush(room);
+                await this.pump(room);
+                await this.engine().recover(room);
+                return readPlan(room);
+            }
+            const current = readPlan(room);
+            const next = changePlan(current, command, { actor, memberIds: members, now: Date.now() });
+            const wake = actor.kind === 'human' && coordinator !== undefined && next.status === 'running'
+                && ((command.action === 'create' && command.mode === 'execute') || (command.action === 'resume' && (current?.status === 'draft' || next.tasks.length === 0)))
+                ? room.append('room/dispatch', { id: randomUUID(), origin: 'report', reportFor: `goal-start:${next.id}:${command.requestId}`,
+                    targets: [coordinator.name], targetIds: [memberId(events, coordinator)], plan: { goalId: next.id },
+                    text: `The human authorized execution of goal ${next.id}: ${next.objective}. Read room_read, organize appropriate stages and tasks with room_plan, invite members when useful, and dispatch within the recorded budget. Small work can remain direct. Review submitted evidence before accepting tasks; wait for correlated reports instead of polling.`,
+                }) : undefined;
+            if (command.action === 'reconcile')
+                this.reconcileDelivery(room, next, command.taskId, command.attemptId, command.requestId);
+            await this.write(room, next);
+            await this.pump(room);
+            if (wake !== undefined && coordinator !== undefined)
+                this.engine().dispatch(room, coordinator.name, wake.data.text, { dispatchSeq: wake.seq, targetId: memberId(events, coordinator) });
+            // Resumption can release durable reports and reservations that survived a pause.
+            if (command.action === 'resume' || command.action === 'cancel' || command.action === 'complete')
+                await this.engine().recover(room);
+            return readPlan(room);
+        });
+    }
+    allows(room, dispatchSeq) {
+        if (dispatchSeq === undefined)
+            return true;
+        const event = room.snapshotEvents().find(event => event.seq === dispatchSeq);
+        if (event?.type !== 'room/dispatch' || event.data.plan === undefined)
+            return true;
+        const plan = readPlan(room);
+        return this.recovered.has(room.id) && plan?.id === event.data.plan.goalId && plan.status === 'running';
+    }
+    async admitted(room, dispatchSeq) {
+        if (dispatchSeq === undefined)
+            return;
+        const event = room.snapshotEvents().find(event => event.seq === dispatchSeq);
+        if (event?.type !== 'room/dispatch' || event.data.plan === undefined)
+            return;
+        const link = event.data.plan;
+        await this.locked(room, async () => {
+            await this.recoverUnlocked(room);
+            const plan = readPlan(room);
+            if (plan?.id !== link.goalId || plan.status !== 'running')
+                throw new Error('Goal no longer permits automatic work');
+            if (link.taskId !== undefined && link.attemptId !== undefined)
+                await this.write(room, admitPlanAttempt(plan, link.taskId, link.attemptId, Date.now()));
+        });
+    }
+    async settled(room, dispatchSeq, outcome) {
+        if (dispatchSeq === undefined)
+            return;
+        const event = room.snapshotEvents().find(event => event.seq === dispatchSeq);
+        if (event?.type !== 'room/dispatch' || event.data.plan?.taskId === undefined || event.data.plan.attemptId === undefined)
+            return;
+        const { goalId, taskId, attemptId } = event.data.plan;
+        await this.locked(room, async () => {
+            const current = readPlan(room);
+            if (current?.id !== goalId)
+                return;
+            const next = settlePlanAttempt(current, taskId, attemptId, {
+                state: outcome.state,
+                ...outcome.error === undefined ? {} : { error: outcome.error },
+                ...outcome.state === 'done' && outcome.text?.trim() ? { evidence: {
+                        summary: outcome.text.slice(0, 32000), references: [`room-delivery:${room.id}:${dispatchSeq}`], artifacts: [],
+                    } } : {},
+            }, Date.now());
+            await this.write(room, next);
+            await this.pump(room);
+        });
+    }
+    /** Human goal reconciliation settles its room delivery and supersedes stale queued reports. */
+    reconcileDelivery(room, plan, taskId, attemptId, requestId) {
+        const attempt = plan.tasks.find(task => task.id === taskId)?.attempts.find(attempt => attempt.id === attemptId);
+        if (attempt === undefined)
+            return;
+        const events = room.snapshotEvents();
+        const dispatch = events.find(event => event.type === 'room/dispatch' && event.data.id === attempt.deliveryId);
+        if (dispatch?.type !== 'room/dispatch')
+            return;
+        const state = replay(events);
+        for (const target of dispatch.data.targetIds ?? []) {
+            const deliveryId = `${dispatch.seq}:${target}`;
+            const member = state.members.find(member => memberId(events, member) === target);
+            const run = state.runs.find(run => run.member === member?.name);
+            if (run?.runId === deliveryId && ['running', 'failed'].includes(run.state))
+                room.append('room/run-state', { member: run.member, runId: run.runId, startedAt: run.startedAt, state: attempt.status === 'submitted' ? 'done' : 'failed',
+                    ...attempt.status === 'failed' ? { error: attempt.submission?.summary ?? 'Human reconciled the attempt as failed' } : {} });
+            room.append('room/delivery-state', { id: deliveryId, dispatchSeq: dispatch.seq, memberId: target,
+                state: attempt.status === 'submitted' ? 'done' : 'failed', text: attempt.submission?.summary ?? 'Human reconciliation' });
+            for (const oldReport of events) {
+                if (oldReport.type !== 'room/dispatch' || oldReport.data.reportFor !== deliveryId)
+                    continue;
+                for (const recipient of oldReport.data.targetIds ?? []) {
+                    const oldId = `${oldReport.seq}:${recipient}`;
+                    if (state.deliveries?.find(delivery => delivery.id === oldId)?.status === 'queued')
+                        room.append('room/delivery-state', { id: oldId, dispatchSeq: oldReport.seq, memberId: recipient, state: 'cancelled', error: 'Superseded by human reconciliation' });
+                }
+            }
+        }
+        const coordinator = coordinatorMember(state, events);
+        if (coordinator !== undefined)
+            room.append('room/dispatch', { id: randomUUID(), origin: 'report', reportFor: `reconcile:${attempt.id}:${requestId}`,
+                targets: [coordinator.name], targetIds: [memberId(events, coordinator)], plan: { goalId: plan.id },
+                text: `Human reconciled task ${taskId}, attempt ${attemptId} as ${attempt.status}. Evidence: ${JSON.stringify(attempt.submission)}. Read the current plan before reviewing or retrying.`,
+            });
+    }
+    async pump(room) {
+        let plan = readPlan(room);
+        if (plan?.status !== 'running')
+            return;
+        for (const task of readyPlanTasks(plan)) {
+            const events = room.snapshotEvents();
+            const state = replay(events);
+            const owner = state.members.find(member => memberId(events, member) === task.ownerMemberId);
+            const coordinator = coordinatorMember(state, events);
+            if (owner === undefined || coordinator === undefined) {
+                await this.write(room, changePlan(plan, { action: 'pause', reason: 'A task owner or coordinator is unavailable', requestId: randomUUID(), expectedRevision: plan.revision }, { actor: { kind: 'coordinator', memberId: 'scheduler' }, memberIds: new Set(), now: Date.now() }));
+                return;
+            }
+            // Reserve against budgets before appending a dispatch. The dispatch ID is
+            // an opaque correlation identity; the execution journal also retains its seq.
+            const attemptId = randomUUID();
+            const dispatchId = randomUUID();
+            let reserved;
+            try {
+                reserved = queuePlanAttempt(plan, task.id, attemptId, dispatchId, Date.now());
+            }
+            catch (error) {
+                if (String(error).includes('concurrency is full'))
+                    return;
+                throw error;
+            }
+            if (reserved.status !== 'running') {
+                await this.write(room, reserved);
+                return;
+            }
+            const dependencyEvidence = dependencyResults(plan, task);
+            const text = [
+                `Goal ${plan.id}, task ${task.id}, attempt ${attemptId}.`,
+                `Objective: ${plan.objective}`, task.instruction,
+                `Acceptance criteria: ${JSON.stringify(task.criteria)}`,
+                `Inputs: ${JSON.stringify(task.inputRefs)}. Expected artifacts: ${JSON.stringify(task.artifactPaths)}.`,
+                `Accepted dependency results: ${JSON.stringify(dependencyEvidence)}`,
+                'Submit your result and evidence with room_plan action submit (taskId, attemptId, evidence: {summary,references,artifacts}, requestId, expectedRevision from room_read). Only the coordinator or human accepts results; do not claim acceptance yourself.',
+            ].join('\n');
+            const dispatch = room.append('room/dispatch', { id: dispatchId, origin: 'coordinator', targets: [owner.name], targetIds: [task.ownerMemberId], text,
+                plan: { goalId: plan.id, taskId: task.id, attemptId },
+                ...memberId(events, coordinator) === task.ownerMemberId ? {} : { replyTo: memberId(events, coordinator) }, });
+            await this.write(room, reserved);
+            this.engine().dispatch(room, owner.name, text, { dispatchSeq: dispatch.seq, targetId: task.ownerMemberId });
+            plan = reserved;
+        }
+    }
+    dispose() { for (const timer of this.timers.values())
+        clearTimeout(timer); this.timers.clear(); }
+}

package/lib/types/plan.d.ts

@@ -0,0 +1,168 @@
+/** Formal goal state. Ordinary room chat does not create or mutate a plan. */
+export interface PlanBudget {
+    maxParallel: number;
+    maxAttempts: number;
+    maxAttemptsPerTask: number;
+    maxActiveMs: number;
+}
+export interface PlanEvidence {
+    summary: string;
+    references: string[];
+    artifacts: string[];
+}
+export interface PlanAttempt {
+    id: string;
+    deliveryId: string;
+    number: number;
+    status: 'queued' | 'running' | 'submitted' | 'accepted' | 'rejected' | 'failed' | 'cancelled' | 'uncertain';
+    createdAt: number;
+    startedAt?: number;
+    settledAt?: number;
+    submission?: PlanEvidence;
+    review?: {
+        decision: 'accepted' | 'rework';
+        by: string;
+        reason: string;
+        references: string[];
+        time: number;
+    };
+    error?: string;
+    retry?: {
+        by: string;
+        reason: string;
+        time: number;
+    };
+}
+export interface PlanTask {
+    id: string;
+    title: string;
+    stageId: string;
+    parentId?: string;
+    kind: 'group' | 'task';
+    ownerMemberId?: string;
+    instruction: string;
+    criteria: string[];
+    inputRefs: string[];
+    artifactPaths: string[];
+    dependsOn: string[];
+    status: 'pending' | 'running' | 'submitted' | 'accepted' | 'failed' | 'cancelled';
+    attempts: PlanAttempt[];
+}
+export interface RoomPlan {
+    version: 1;
+    id: string;
+    revision: number;
+    objective: string;
+    status: 'draft' | 'running' | 'paused' | 'completed' | 'cancelled';
+    reason?: string;
+    budget: PlanBudget;
+    activeMs: number;
+    resumedAt?: number;
+    stages: {
+        id: string;
+        title: string;
+    }[];
+    tasks: PlanTask[];
+    completion?: PlanEvidence;
+    requests: {
+        id: string;
+        signature: string;
+    }[];
+}
+export type PlanTaskInput = Omit<PlanTask, 'status' | 'attempts'>;
+interface CommandBase {
+    requestId: string;
+    expectedRevision: number;
+}
+export type PlanCommand = CommandBase & ({
+    action: 'create';
+    id: string;
+    objective: string;
+    mode: 'draft' | 'execute';
+    budget: PlanBudget;
+} | {
+    action: 'extend';
+    stages: {
+        id: string;
+        title: string;
+    }[];
+    tasks: PlanTaskInput[];
+} | {
+    action: 'pause';
+    reason: string;
+    goalId?: string;
+} | {
+    action: 'resume';
+} | {
+    action: 'budget';
+    budget: PlanBudget;
+} | {
+    action: 'cancel';
+    reason: string;
+} | {
+    action: 'submit';
+    taskId: string;
+    attemptId: string;
+    evidence: PlanEvidence;
+} | {
+    action: 'review';
+    taskId: string;
+    attemptId: string;
+    decision: 'accepted' | 'rework';
+    reason: string;
+    references: string[];
+} | {
+    action: 'retry';
+    taskId: string;
+    reason: string;
+} | {
+    action: 'reconcile';
+    taskId: string;
+    attemptId: string;
+    outcome: 'failed' | 'submitted';
+    evidence: PlanEvidence;
+} | {
+    action: 'complete';
+    evidence: PlanEvidence;
+});
+export interface PlanActor {
+    kind: 'human' | 'coordinator' | 'worker';
+    memberId: string;
+}
+export interface PlanContext {
+    actor: PlanActor;
+    memberIds: ReadonlySet<string>;
+    now: number;
+}
+export declare function activePlanMs(plan: RoomPlan, now: number): number;
+export declare function latestAttempt(task: PlanTask): PlanAttempt | undefined;
+export declare function acceptedTask(plan: RoomPlan, taskId: string): boolean;
+/** Accepted leaves behind direct and inherited group prerequisites, once each. */
+export declare function dependencyResults(plan: RoomPlan, task: PlanTask): {
+    taskId: string;
+    submission?: PlanEvidence;
+}[];
+export declare function readyPlanTasks(plan: RoomPlan): PlanTask[];
+export declare function activePlanAttempts(plan: RoomPlan): PlanAttempt[];
+/** Pure transition: the service persists the returned revision before dispatch. */
+export declare function changePlan(current: RoomPlan | undefined, command: PlanCommand, context: PlanContext): RoomPlan;
+/** Reserve a single executable leaf and count the attempt before side effects. */
+export declare function queuePlanAttempt(current: RoomPlan, taskId: string, attemptId: string, deliveryId: string, now: number): RoomPlan;
+/** Durable admission; a pause after reservation prevents the native side effect. */
+export declare function admitPlanAttempt(current: RoomPlan, taskId: string, attemptId: string, now: number): RoomPlan;
+/** A normal native result is a submission to review, never implicit acceptance. */
+export declare function settlePlanAttempt(current: RoomPlan, taskId: string, attemptId: string, result: {
+    state: 'done' | 'failed' | 'cancelled';
+    evidence?: PlanEvidence;
+    error?: string;
+}, now: number): RoomPlan;
+/** Restart always pauses automation and fences native executions with unknown outcomes. */
+export declare function recoverPlan(current: RoomPlan, now: number): RoomPlan;
+/** One bounded, strict wire grammar is shared by native tools, MCP and the UI. */
+export declare function parsePlanCommand(text: string): PlanCommand;
+/** JSON schema supplied through room_read so both harness families see one contract. */
+export declare function planCommandContract(): object;
+/** Object field order is not part of a retry identity; array order remains meaningful. */
+export declare function planCommandSignature(command: PlanCommand): string;
+export {};
+//# sourceMappingURL=plan.d.ts.map