@xfey/tutti 0.1.0

package/dist/control-plane/follow-up-output.d.ts

@@ -0,0 +1,53 @@
+import type { ActivityRef, ClarificationRoundRef, TaskId, WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { HostProjectStore } from "../store/index.js";
+import type { ControlPlaneLogger } from "./types.js";
+import type { FollowUpCheckWorkflowInput, FollowUpCheckWorkflowOutput } from "./workflows/index.js";
+export declare function closeTaskBoundFollowUpAsRetaskingRequired(input: {
+    store: HostProjectStore;
+    events: WorkspaceEventBus;
+    taskId: TaskId;
+    roundId: ClarificationRoundRef;
+    summary: string;
+    now: () => Date;
+}): {
+    kind: "failed";
+    summary: string;
+    result_anchor: {
+        kind: "clarification_round";
+        clarification_round_ref: `clar_round_${string}`;
+    };
+};
+export declare function applyFollowUpCheckOutput(input: {
+    store: HostProjectStore;
+    events: WorkspaceEventBus;
+    logger?: ControlPlaneLogger | undefined;
+    output: FollowUpCheckWorkflowOutput;
+    workflowRef: WorkflowInvocationRef;
+    activityRef: ActivityRef;
+    roundId: ClarificationRoundRef;
+    followUpInput: FollowUpCheckWorkflowInput;
+    now: () => Date;
+}): {
+    kind: "failed";
+    summary: string;
+    result_anchor: {
+        kind: "clarification_round";
+        clarification_round_ref: `clar_round_${string}`;
+    };
+} | {
+    kind: "needs_human";
+    summary: string;
+    result_anchor: {
+        kind: "clarification_round";
+        clarification_round_ref: `clar_round_${string}`;
+    };
+} | {
+    kind: "completed";
+    summary: string;
+    result_anchor: {
+        kind: "clarification_round";
+        clarification_round_ref: `clar_round_${string}`;
+    };
+};
+//# sourceMappingURL=follow-up-output.d.ts.map

package/dist/control-plane/follow-up-output.js

@@ -0,0 +1,141 @@
+import { closeTaskBoundClarificationAsRetaskingRequired, openNextTaskBoundClarificationRound, } from "../collaboration-state/index.js";
+import { clarificationInvalidates, taskRunInvalidates } from "./invalidations.js";
+export function closeTaskBoundFollowUpAsRetaskingRequired(input) {
+    const closed = closeTaskBoundClarificationAsRetaskingRequired(input.store.db, {
+        round_id: input.roundId,
+        summary: input.summary,
+        now: input.now,
+    });
+    if (closed === null) {
+        return {
+            kind: "failed",
+            summary: "Task-bound clarification state could not be closed.",
+            result_anchor: {
+                kind: "clarification_round",
+                clarification_round_ref: input.roundId,
+            },
+        };
+    }
+    const invalidates = taskRunInvalidates(input.taskId);
+    if (closed.kind === "closed") {
+        input.events.publish({
+            event_type: "message.created",
+            payload: { message: closed.message },
+            invalidates: [...invalidates, ...clarificationInvalidates(input.roundId, closed.thread.id)],
+        });
+        input.events.publish({
+            event_type: "worklist.changed",
+            payload: {
+                reason: "task_state_changed",
+                changed_task_ids: [input.taskId],
+            },
+            invalidates,
+        });
+        input.events.publish({
+            event_type: "task.updated",
+            payload: { task: closed.task },
+            invalidates,
+        });
+        input.events.publish({
+            event_type: "task_detail.updated",
+            payload: {
+                task_id: input.taskId,
+                task: closed.task,
+                detail: closed.task_detail,
+            },
+            invalidates,
+        });
+    }
+    input.events.publish({
+        event_type: "clarification.changed",
+        payload: {
+            reason: "successor_materialized",
+            thread_id: closed.thread.id,
+            round_id: input.roundId,
+            successor_ref: { kind: "chain_closed" },
+        },
+        invalidates: [...invalidates, ...clarificationInvalidates(input.roundId, closed.thread.id)],
+    });
+    return {
+        kind: "failed",
+        summary: `Retasking required: ${input.summary}`,
+        result_anchor: {
+            kind: "clarification_round",
+            clarification_round_ref: input.roundId,
+        },
+    };
+}
+export function applyFollowUpCheckOutput(input) {
+    input.logger?.info({
+        workflow_ref: input.workflowRef,
+        activity_ref: input.activityRef,
+        decision: input.output.decision,
+        summary: input.output.summary,
+    }, "Follow-up check completed");
+    if (input.output.decision === "needs_more_input") {
+        const opened = openNextTaskBoundClarificationRound(input.store.db, {
+            continue_from_round_id: input.roundId,
+            request_payload: input.output.clarification_request_payload,
+            now: input.now,
+        });
+        const nextRoundId = opened.round.id;
+        input.events.publish({
+            event_type: "clarification.changed",
+            payload: {
+                reason: "successor_materialized",
+                thread_id: opened.thread.id,
+                round_id: input.roundId,
+                successor_ref: {
+                    kind: "next_round",
+                    clarification_round_ref: nextRoundId,
+                },
+            },
+            invalidates: clarificationInvalidates(input.roundId, opened.thread.id),
+        });
+        input.events.publish({
+            event_type: "message.created",
+            payload: { message: opened.card_message },
+            invalidates: clarificationInvalidates(nextRoundId, opened.thread.id),
+        });
+        input.events.publish({
+            event_type: "clarification.changed",
+            payload: {
+                reason: "round_opened",
+                thread_id: opened.thread.id,
+                round_id: nextRoundId,
+            },
+            invalidates: clarificationInvalidates(nextRoundId, opened.thread.id),
+        });
+        return {
+            kind: "needs_human",
+            summary: input.output.clarification_request_payload.summary,
+            result_anchor: {
+                kind: "clarification_round",
+                clarification_round_ref: nextRoundId,
+            },
+        };
+    }
+    if (input.output.decision === "requires_retasking") {
+        const summary = input.output.summary.trim().length === 0
+            ? "The submitted answer requires a new task."
+            : input.output.summary;
+        return closeTaskBoundFollowUpAsRetaskingRequired({
+            store: input.store,
+            events: input.events,
+            taskId: input.followUpInput.task_id,
+            roundId: input.roundId,
+            summary,
+            now: input.now,
+        });
+    }
+    const summary = input.output.summary.trim().length === 0 ? "Follow-up accepted." : input.output.summary;
+    return {
+        kind: "completed",
+        summary,
+        result_anchor: {
+            kind: "clarification_round",
+            clarification_round_ref: input.roundId,
+        },
+    };
+}
+//# sourceMappingURL=follow-up-output.js.map

package/dist/control-plane/follow-up-run.d.ts

@@ -0,0 +1,22 @@
+import { type ClarificationRoundRef, type TaskId } from "@tutti/shared/ids";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { HostProjectStore } from "../store/index.js";
+import type { RunPipelineResolver } from "./types.js";
+import type { StartRunForTaskInput } from "./run-start.js";
+type StartRunForTask = (input: StartRunForTaskInput) => void;
+export declare function startRunFromFollowUp(input: {
+    store: HostProjectStore;
+    events: WorkspaceEventBus;
+    resolveRunPipeline: RunPipelineResolver | undefined;
+    readMainlineStatus: (() => {
+        mainline_clean: boolean;
+    }) | undefined;
+    startRunForTask: StartRunForTask;
+    taskId: TaskId;
+    threadId: string;
+    roundId: ClarificationRoundRef;
+    followUpCheckSummary?: string | undefined;
+    now: () => Date;
+}): void;
+export {};
+//# sourceMappingURL=follow-up-run.d.ts.map

package/dist/control-plane/follow-up-run.js

@@ -0,0 +1,90 @@
+import { createActivityRef, } from "@tutti/shared/ids";
+import { materializeTaskBoundRunSuccessor, readNextRunnableTask, readTaskDetailProjection, readTaskRunResultsPage, } from "../collaboration-state/index.js";
+import { readRunContinuationContextFromStore } from "./follow-up-context.js";
+import { clarificationInvalidates } from "./invalidations.js";
+import { toDomainRunLineage } from "./run-lineage.js";
+export function startRunFromFollowUp(input) {
+    const pipelineResolution = input.resolveRunPipeline?.();
+    if (pipelineResolution === undefined || pipelineResolution.kind !== "ready") {
+        return;
+    }
+    if (input.readMainlineStatus !== undefined && !input.readMainlineStatus().mainline_clean) {
+        return;
+    }
+    const latestRunResult = readTaskRunResultsPage(input.store.db, input.taskId, {
+        limit: 1,
+    })?.items[0];
+    if (latestRunResult === undefined || latestRunResult.result_kind !== "needs_human") {
+        return;
+    }
+    const continuationContext = readRunContinuationContextFromStore({
+        db: input.store.db,
+        task_id: input.taskId,
+        thread_id: input.threadId,
+        round_id: input.roundId,
+        ...(input.followUpCheckSummary === undefined
+            ? {}
+            : { follow_up_check_summary: input.followUpCheckSummary }),
+    });
+    if (continuationContext === null) {
+        return;
+    }
+    const activityRef = createActivityRef();
+    const materialized = materializeTaskBoundRunSuccessor(input.store.db, {
+        round_id: input.roundId,
+        activity_ref: activityRef,
+        now: input.now,
+    });
+    if (materialized === null || materialized.kind !== "materialized") {
+        return;
+    }
+    const successorRef = {
+        kind: "run",
+        activity_ref: activityRef,
+    };
+    input.events.publish({
+        event_type: "clarification.changed",
+        payload: {
+            reason: "successor_materialized",
+            thread_id: input.threadId,
+            round_id: input.roundId,
+            successor_ref: successorRef,
+        },
+        invalidates: clarificationInvalidates(input.roundId, input.threadId),
+    });
+    const taskDetail = readTaskDetailProjection(input.store.db, input.taskId);
+    if (taskDetail === null) {
+        return;
+    }
+    const next = readNextRunnableTask(input.store.db);
+    const queuedTaskIds = next.kind === "found"
+        ? [
+            input.taskId,
+            ...next.queued_task_ids.filter((queuedTaskId) => queuedTaskId !== input.taskId),
+        ]
+        : [input.taskId];
+    const parentLineage = toDomainRunLineage(latestRunResult.run_lineage);
+    const runLineage = {
+        kind: "continuation",
+        attempt: parentLineage.attempt + 1,
+        parent_activity_ref: latestRunResult.activity_ref,
+        root_activity_ref: parentLineage.root_activity_ref ?? latestRunResult.activity_ref,
+    };
+    const dispatchContext = {
+        trigger: "continuation",
+        queue_scope: { kind: "worklist" },
+        current_task_id: input.taskId,
+        ordered_task_refs: queuedTaskIds,
+        current_module_id: materialized.task.module_id,
+    };
+    input.startRunForTask({
+        activity_ref: activityRef,
+        task: materialized.task,
+        task_detail: taskDetail,
+        run_lineage: runLineage,
+        dispatch_context: dispatchContext,
+        continuation_context: continuationContext,
+        runner: pipelineResolution.runner,
+    });
+}
+//# sourceMappingURL=follow-up-run.js.map

package/dist/control-plane/follow-up-start.d.ts

@@ -0,0 +1,26 @@
+import { type ClarificationRoundRef } from "@tutti/shared/ids";
+import type { ProcedureEngine, ProcedureEngineState } from "../procedure-engine/index.js";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { HostProjectStore } from "../store/index.js";
+import type { StartRunForTaskInput } from "./run-start.js";
+import type { ControlPlaneLogger, Phase5ControlPlaneOptions, RunPipelineResolver } from "./types.js";
+import type { ProcedureWorkflowRunnerResolver } from "./workflows/index.js";
+export declare function startControlPlaneTaskBoundFollowUpCheck(options: {
+    engine: ProcedureEngine;
+    store: HostProjectStore;
+    events: WorkspaceEventBus;
+    owner: {
+        kind: "task";
+        task_id: string;
+    };
+    threadId: string;
+    roundId: ClarificationRoundRef;
+    resolveWorkflowRunner: ProcedureWorkflowRunnerResolver;
+    resolveRunPipeline: RunPipelineResolver | undefined;
+    readMainlineStatus: Phase5ControlPlaneOptions["readMainlineStatus"] | undefined;
+    logger: ControlPlaneLogger | undefined;
+    now: () => Date;
+    publishProcedureTransition: (state: ProcedureEngineState) => void;
+    startRunForTask: (runInput: StartRunForTaskInput) => void;
+}): boolean;
+//# sourceMappingURL=follow-up-start.d.ts.map

package/dist/control-plane/follow-up-start.js

@@ -0,0 +1,101 @@
+import { createWorkflowInvocationRef, } from "@tutti/shared/ids";
+import { readFollowUpCheckInputFromStore } from "./follow-up-context.js";
+import { applyFollowUpCheckOutput, closeTaskBoundFollowUpAsRetaskingRequired, } from "./follow-up-output.js";
+import { startRunFromFollowUp as startRunFromFollowUpSuccessor } from "./follow-up-run.js";
+import { logProcedureExecutionError } from "./procedure-logging.js";
+export function startControlPlaneTaskBoundFollowUpCheck(options) {
+    const runnerResolution = options.resolveWorkflowRunner();
+    if (runnerResolution.kind !== "ready" || runnerResolution.runner.runFollowUpCheck === undefined) {
+        return false;
+    }
+    const workflowRef = createWorkflowInvocationRef();
+    let output;
+    const start = options.engine.startProcedure({
+        workflow_ref: workflowRef,
+        workflow_kind: "follow_up_check",
+        lane: "foreground",
+        title: "Check Follow-up",
+        summary: "Checking whether the task can continue.",
+        now: options.now,
+        onTransition: (state) => {
+            options.publishProcedureTransition(state);
+            if (state.activity.status === "finished" && output?.decision === "resume") {
+                startRunFromFollowUpSuccessor({
+                    store: options.store,
+                    events: options.events,
+                    resolveRunPipeline: options.resolveRunPipeline,
+                    readMainlineStatus: options.readMainlineStatus,
+                    startRunForTask: (runInput) => {
+                        options.startRunForTask(runInput);
+                    },
+                    taskId: options.owner.task_id,
+                    threadId: options.threadId,
+                    roundId: options.roundId,
+                    followUpCheckSummary: output.summary,
+                    now: options.now,
+                });
+            }
+        },
+        onError: ({ context, error }) => logProcedureExecutionError({
+            logger: options.logger,
+            workflowKind: "follow_up_check",
+            workflowRef,
+            activityRef: context.activity_ref,
+            error,
+        }),
+        execute: async (context) => {
+            const inputResult = readFollowUpCheckInputFromStore({
+                db: options.store.db,
+                workflow_ref: workflowRef,
+                task_id: options.owner.task_id,
+                thread_id: options.threadId,
+                round_id: options.roundId,
+            });
+            if (inputResult.kind === "unavailable") {
+                return {
+                    kind: "failed",
+                    summary: "Task-bound clarification state could not be read.",
+                    result_anchor: {
+                        kind: "clarification_round",
+                        clarification_round_ref: options.roundId,
+                    },
+                };
+            }
+            if (inputResult.kind === "invalid") {
+                return closeTaskBoundFollowUpAsRetaskingRequired({
+                    store: options.store,
+                    events: options.events,
+                    taskId: options.owner.task_id,
+                    roundId: options.roundId,
+                    summary: inputResult.summary,
+                    now: options.now,
+                });
+            }
+            const input = inputResult.input;
+            output = await runnerResolution.runner.runFollowUpCheck?.(input, {
+                workflow_ref: workflowRef,
+                activity_ref: context.activity_ref,
+            });
+            if (output === undefined) {
+                return {
+                    kind: "failed",
+                    summary: "follow_up_check runner is unavailable.",
+                    result_anchor: { kind: "workflow", workflow_ref: workflowRef },
+                };
+            }
+            return applyFollowUpCheckOutput({
+                store: options.store,
+                events: options.events,
+                logger: options.logger,
+                output,
+                workflowRef,
+                activityRef: context.activity_ref,
+                roundId: options.roundId,
+                followUpInput: input,
+                now: options.now,
+            });
+        },
+    });
+    return start.kind === "accepted";
+}
+//# sourceMappingURL=follow-up-start.js.map

package/dist/control-plane/formatters.d.ts

@@ -0,0 +1,12 @@
+import type { ActivityProjection } from "@tutti/shared/schemas/api";
+export declare function defaultProcedureFailureSystemMessage(activity: ActivityProjection): string;
+export declare function formatStartupRecoverySummary(input: {
+    recoveredRunCount: number;
+    replayedRoundCount: number;
+    interruptedCommandCount: number;
+    removedRunWorkspaceCount: number;
+    removedTempBranchCount: number;
+    cleanupWarningCount: number;
+    staleReplayHintCount: number;
+}): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/control-plane/formatters.js

@@ -0,0 +1,47 @@
+const CHAT_NOTICE_SUMMARY_LIMIT = 180;
+function shortSummary(value) {
+    const trimmed = value.trim();
+    if (trimmed.length <= CHAT_NOTICE_SUMMARY_LIMIT) {
+        return trimmed;
+    }
+    return `${trimmed.slice(0, CHAT_NOTICE_SUMMARY_LIMIT - 3)}...`;
+}
+export function defaultProcedureFailureSystemMessage(activity) {
+    const title = activity.title.trim().length === 0 ? "Procedure" : activity.title.trim();
+    const summary = shortSummary(activity.summary);
+    if (summary.length === 0) {
+        return `Procedure failed: ${title}.`;
+    }
+    return `Procedure failed: ${title}. ${summary}`;
+}
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function formatStartupRecoverySummary(input) {
+    const parts = [];
+    if (input.recoveredRunCount > 0) {
+        parts.push(`${countNoun(input.recoveredRunCount, "stale Run")} marked failed`);
+    }
+    if (input.replayedRoundCount > 0) {
+        parts.push(`${countNoun(input.replayedRoundCount, "sealed clarification round")} replayed`);
+    }
+    if (input.interruptedCommandCount > 0) {
+        parts.push(`${countNoun(input.interruptedCommandCount, "in-progress command")} interrupted`);
+    }
+    if (input.removedRunWorkspaceCount > 0) {
+        parts.push(`${countNoun(input.removedRunWorkspaceCount, "stale run workspace")} removed`);
+    }
+    if (input.removedTempBranchCount > 0) {
+        parts.push(`${countNoun(input.removedTempBranchCount, "stale run branch", "stale run branches")} removed`);
+    }
+    if (input.staleReplayHintCount > 0) {
+        parts.push(`${countNoun(input.staleReplayHintCount, "stale replay hint")} cleared`);
+    }
+    if (input.cleanupWarningCount > 0) {
+        parts.push(`${countNoun(input.cleanupWarningCount, "cleanup warning")} recorded`);
+    }
+    return parts.length === 0
+        ? "Startup recovery completed."
+        : `Startup recovery completed: ${parts.join("; ")}.`;
+}
+//# sourceMappingURL=formatters.js.map

package/dist/control-plane/index.d.ts

@@ -0,0 +1,62 @@
+import { type ActivityRef, type ClarificationRoundRef, type IdempotencyKey, type WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { ExecutionStatusProjection, ContextSyncDisposition, ContextSyncResult, RefreshScratchpadDisposition, RefreshScratchpadResult, RunSchedulerNowDisposition, RunSchedulerNowPayload, RefreshReferenceSummariesDisposition, RefreshReferenceSummariesPayload, RefreshReferenceSummariesResult, SendClarificationRoundMessageDisposition, SendClarificationRoundMessagePayload, SendClarificationRoundMessageResult, SubmitClarificationRoundDisposition, SubmitClarificationRoundPayload, SubmitClarificationRoundResult, SubmitWorklistDisposition, SubmitWorklistPayload, SubmitWorklistResult, ProcedureLane } from "@tutti/shared/schemas/api";
+import type { ContextSyncWorkflowTrigger } from "./workflows/index.js";
+import type { ControlPlaneCommandResult, Phase5ControlPlaneOptions, StartupRecoveryOptions, StartupRecoveryResult, TrustedHumanAuthor } from "./types.js";
+import { type ProjectBriefRefreshReason, type RefreshProjectBriefProjectionResult } from "./project-brief-refresh.js";
+export type { ControlPlaneCommandResult, ControlPlaneLogger, Phase5ControlPlaneOptions, RunCorrectionContext, RunContinuationContext, RunDispatchContext, RunDispatchTrigger, RunPipelineInput, RunPipelineResolution, RunPipelineResolver, RunPipelineResult, RunPipelineRunner, RunPipelineTimelineEvent, StartupRecoveryOptions, StartupRecoveryResult, TrustedHumanAuthor, } from "./types.js";
+export declare class Phase5ControlPlane {
+    private readonly engine;
+    private readonly runEngine;
+    private readonly store;
+    private readonly events;
+    private readonly resolveWorkflowRunner;
+    private readonly resolveRunPipeline;
+    private readonly readMainlineStatus;
+    private readonly readActiveApproval;
+    private readonly logger;
+    private readonly projectContext;
+    private readonly now;
+    private readonly scratchpadAutoRefreshScheduler;
+    private lastRecoveryConclusion;
+    constructor(options: Phase5ControlPlaneOptions);
+    getExecutionStatus(): ExecutionStatusProjection;
+    runSchedulerNow(payload?: RunSchedulerNowPayload): ControlPlaneCommandResult<RunSchedulerNowDisposition, never>;
+    runStartupRecovery(options?: StartupRecoveryOptions): StartupRecoveryResult;
+    startScratchpadRefresh(options?: {
+        lane?: ProcedureLane;
+    }): ControlPlaneCommandResult<RefreshScratchpadDisposition, RefreshScratchpadResult>;
+    notifyScratchpadSourceChanged(): void;
+    refreshProjectBrief(options: {
+        reason: ProjectBriefRefreshReason;
+        workflowRef?: WorkflowInvocationRef;
+        activityRef?: ActivityRef;
+    }): Promise<RefreshProjectBriefProjectionResult>;
+    dispose(): void;
+    startTaskCompile(payload: SubmitWorklistPayload): ControlPlaneCommandResult<SubmitWorklistDisposition, SubmitWorklistResult>;
+    startContextSyncAnalysis(trigger?: ContextSyncWorkflowTrigger): ControlPlaneCommandResult<ContextSyncDisposition, ContextSyncResult>;
+    startReferenceSummaryRefresh(payload?: RefreshReferenceSummariesPayload): ControlPlaneCommandResult<RefreshReferenceSummariesDisposition, RefreshReferenceSummariesResult>;
+    sendClarificationRoundMessage(roundId: ClarificationRoundRef, payload: SendClarificationRoundMessagePayload, author: TrustedHumanAuthor): ControlPlaneCommandResult<SendClarificationRoundMessageDisposition, SendClarificationRoundMessageResult>;
+    submitClarificationRound(roundId: ClarificationRoundRef, payload: SubmitClarificationRoundPayload, commandId: IdempotencyKey): ControlPlaneCommandResult<SubmitClarificationRoundDisposition, SubmitClarificationRoundResult>;
+    waitForIdle(): Promise<void>;
+    private startRunForTask;
+    private readActiveRun;
+    private readActiveProcedures;
+    private readActiveForegroundProcedure;
+    private readActiveScratchpadRefreshProcedure;
+    private readAnyActiveActivity;
+    private readSchedulerBlocker;
+    private readScratchpadRefreshBlocker;
+    private publishTaskRunStarted;
+    private publishRunResultRecorded;
+    private publishRunTransition;
+    private handleRunTerminalTransition;
+    private tryRunTaskArrivalScheduler;
+    private maybeScheduleAfterRunCompletion;
+    private worklistCompletionContextSyncTrigger;
+    private maybeStartContextSyncAfterWorklistCompletion;
+    private startTaskCompileContinuation;
+    private startTaskBoundFollowUpCheck;
+    private publishProcedureTransition;
+    private logProcedureTransition;
+}
+//# sourceMappingURL=index.d.ts.map