@xfey/tutti 0.1.0

package/dist/control-plane/index.js

@@ -0,0 +1,416 @@
+import { readWorklistProjection } from "../collaboration-state/index.js";
+import { ProcedureEngine } from "../procedure-engine/index.js";
+import { RunEngine } from "../run-engine/index.js";
+import { publishProcedureTransition as publishProcedureTransitionEvent, publishRunResultRecorded as publishRunResultRecordedEvent, publishRunTransition as publishRunTransitionEvent, publishTaskRunStarted as publishTaskRunStartedEvent, } from "./event-publishers.js";
+import { startContextSyncAnalysisProcedure } from "./context-sync.js";
+import { refreshProjectBriefProjection, } from "./project-brief-refresh.js";
+import { startReferenceSummaryRefreshProcedure } from "./reference-summary-refresh.js";
+import { runControlPlaneStartupRecovery } from "./startup-recovery.js";
+import { readControlPlaneExecutionStatus } from "./execution-status.js";
+import { ScratchpadAutoRefreshScheduler } from "./scratchpad-auto-refresh.js";
+import { startControlPlaneScratchpadRefresh } from "./scratchpad-refresh-start.js";
+import { startControlPlaneTaskCompile } from "./task-compile-start.js";
+import { startControlPlaneTaskCompileContinuation } from "./task-compile-continuation.js";
+import { startControlPlaneTaskBoundFollowUpCheck } from "./follow-up-start.js";
+import { runControlPlaneSchedulerForTaskArrival, runControlPlaneSchedulerNow, } from "./run-scheduler.js";
+import { startControlPlaneRunForTask } from "./run-start.js";
+import { runSendClarificationRoundMessage, runSubmitClarificationRound, } from "./clarification-commands.js";
+import { emitWorklistCompletedFeedback, emitWorklistFailedFeedback, } from "./worklist-terminal-feedback.js";
+export class Phase5ControlPlane {
+    engine;
+    runEngine;
+    store;
+    events;
+    resolveWorkflowRunner;
+    resolveRunPipeline;
+    readMainlineStatus;
+    readActiveApproval;
+    logger;
+    projectContext;
+    now;
+    scratchpadAutoRefreshScheduler;
+    lastRecoveryConclusion = null;
+    constructor(options) {
+        this.store = options.store;
+        this.events = options.events;
+        this.resolveWorkflowRunner = options.resolveWorkflowRunner;
+        this.resolveRunPipeline = options.resolveRunPipeline;
+        this.readMainlineStatus = options.readMainlineStatus;
+        this.readActiveApproval = options.readActiveApproval;
+        this.logger = options.logger;
+        this.projectContext = options.projectContext;
+        this.now = options.now ?? (() => new Date());
+        this.engine = new ProcedureEngine({ now: this.now });
+        this.runEngine = new RunEngine({ now: this.now });
+        this.scratchpadAutoRefreshScheduler = new ScratchpadAutoRefreshScheduler({
+            store: this.store,
+            now: this.now,
+            readScratchpadRefreshBlocker: () => this.readScratchpadRefreshBlocker(),
+            startScratchpadRefresh: () => this.startScratchpadRefresh({ lane: "scratchpad_background" }),
+        });
+    }
+    getExecutionStatus() {
+        return readControlPlaneExecutionStatus({
+            procedureEngine: this.engine,
+            runEngine: this.runEngine,
+            store: this.store,
+            lastRecoveryConclusion: this.lastRecoveryConclusion,
+            ...(this.readActiveApproval === undefined
+                ? {}
+                : { readActiveApproval: this.readActiveApproval }),
+            now: this.now,
+        });
+    }
+    runSchedulerNow(payload = {}) {
+        return runControlPlaneSchedulerNow({
+            store: this.store,
+            payload,
+            resolveRunPipeline: this.resolveRunPipeline,
+            readMainlineStatus: this.readMainlineStatus,
+            readSchedulerBlocker: () => this.readSchedulerBlocker(),
+            startRunForTask: (runInput) => this.startRunForTask(runInput),
+            now: this.now,
+        });
+    }
+    runStartupRecovery(options = {}) {
+        return runControlPlaneStartupRecovery({
+            store: this.store,
+            events: this.events,
+            options,
+            now: this.now,
+            getExecutionStatus: () => this.getExecutionStatus(),
+            setLastRecoveryConclusion: (conclusion) => {
+                this.lastRecoveryConclusion = conclusion;
+            },
+            replaySealedRound: (sealed, roundId) => sealed.thread.owner.kind === "task_compile"
+                ? this.startTaskCompileContinuation(sealed.thread.owner, roundId)
+                : this.startTaskBoundFollowUpCheck(sealed.thread.owner, sealed.thread.id, roundId),
+        });
+    }
+    startScratchpadRefresh(options = {}) {
+        return startControlPlaneScratchpadRefresh({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            projectContext: this.projectContext,
+            ...(options.lane === undefined ? {} : { lane: options.lane }),
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => this.publishProcedureTransition(state),
+        });
+    }
+    notifyScratchpadSourceChanged() {
+        this.scratchpadAutoRefreshScheduler.notifySourceChanged();
+    }
+    refreshProjectBrief(options) {
+        return refreshProjectBriefProjection({
+            store: this.store,
+            projectContext: this.projectContext,
+            reason: options.reason,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            ...(options.workflowRef === undefined ? {} : { workflowRef: options.workflowRef }),
+            ...(options.activityRef === undefined ? {} : { activityRef: options.activityRef }),
+            logger: this.logger,
+            now: this.now,
+        });
+    }
+    dispose() {
+        this.scratchpadAutoRefreshScheduler.dispose();
+    }
+    startTaskCompile(payload) {
+        let tasksAdded = false;
+        return startControlPlaneTaskCompile({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            payload,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            projectContext: this.projectContext,
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => {
+                this.publishProcedureTransition(state);
+                if (tasksAdded &&
+                    state.activity.status === "finished" &&
+                    state.activity.workflow_kind === "task_compile") {
+                    this.tryRunTaskArrivalScheduler();
+                }
+            },
+            onTasksAdded: () => {
+                tasksAdded = true;
+            },
+        });
+    }
+    startContextSyncAnalysis(trigger = { kind: "manual" }) {
+        return startContextSyncAnalysisProcedure({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            trigger,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            readActiveActivity: () => this.readSchedulerBlocker(),
+            projectContext: this.projectContext,
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => this.publishProcedureTransition(state),
+        });
+    }
+    startReferenceSummaryRefresh(payload = {}) {
+        return startReferenceSummaryRefreshProcedure({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            ...(payload.paths === undefined ? {} : { paths: payload.paths }),
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            readActiveActivity: () => this.readSchedulerBlocker(),
+            projectContext: this.projectContext,
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => this.publishProcedureTransition(state),
+        });
+    }
+    sendClarificationRoundMessage(roundId, payload, author) {
+        return runSendClarificationRoundMessage({
+            store: this.store,
+            events: this.events,
+            roundId,
+            payload,
+            author,
+            now: this.now,
+        });
+    }
+    submitClarificationRound(roundId, payload, commandId) {
+        return runSubmitClarificationRound({
+            store: this.store,
+            events: this.events,
+            roundId,
+            payload,
+            commandId,
+            now: this.now,
+            startTaskCompileContinuation: (owner, submittedRoundId) => this.startTaskCompileContinuation(owner, submittedRoundId),
+            startTaskBoundFollowUpCheck: (owner, threadId, submittedRoundId) => this.startTaskBoundFollowUpCheck(owner, threadId, submittedRoundId),
+            notifyScratchpadSourceChanged: () => this.notifyScratchpadSourceChanged(),
+        });
+    }
+    async waitForIdle() {
+        while (true) {
+            await this.engine.waitForIdle();
+            await this.runEngine.waitForIdle();
+            if (this.readAnyActiveActivity() === null) {
+                return;
+            }
+        }
+    }
+    startRunForTask(input) {
+        return startControlPlaneRunForTask({
+            runEngine: this.runEngine,
+            store: this.store,
+            run: input,
+            projectContext: this.projectContext,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            logger: this.logger,
+            now: this.now,
+            publishRunTransition: (state) => this.publishRunTransition(state),
+            publishTaskRunStarted: (task, activityRef) => this.publishTaskRunStarted(task, activityRef),
+            publishRunResultRecorded: (recorded) => this.publishRunResultRecorded(recorded),
+        });
+    }
+    readActiveRun() {
+        const runStatus = this.runEngine.getExecutionStatus();
+        if (runStatus.status !== "idle" && runStatus.active_activity !== undefined) {
+            return {
+                activity_ref: runStatus.active_activity.activity_ref,
+                activity_kind: runStatus.active_activity.activity_kind,
+            };
+        }
+        return null;
+    }
+    readActiveProcedures() {
+        return this.engine.getActiveProcedures().map((activity) => ({
+            activity_ref: activity.activity_ref,
+            activity_kind: "procedure",
+            lane: activity.lane ?? "foreground",
+            ...(activity.workflow_kind === undefined ? {} : { workflow_kind: activity.workflow_kind }),
+        }));
+    }
+    readActiveForegroundProcedure() {
+        return (this.readActiveProcedures().find((activity) => {
+            return activity.lane === "foreground";
+        }) ?? null);
+    }
+    readActiveScratchpadRefreshProcedure() {
+        return (this.readActiveProcedures().find((activity) => {
+            return activity.workflow_kind === "scratchpad_refresh";
+        }) ?? null);
+    }
+    readAnyActiveActivity() {
+        const activeRun = this.readActiveRun();
+        if (activeRun !== null) {
+            return activeRun;
+        }
+        return this.readActiveProcedures()[0] ?? null;
+    }
+    readSchedulerBlocker() {
+        const activeRun = this.readActiveRun();
+        if (activeRun !== null) {
+            return activeRun;
+        }
+        return this.readActiveForegroundProcedure();
+    }
+    readScratchpadRefreshBlocker() {
+        const activeScratchpadRefresh = this.readActiveScratchpadRefreshProcedure();
+        if (activeScratchpadRefresh !== null) {
+            return activeScratchpadRefresh;
+        }
+        return this.readActiveForegroundProcedure();
+    }
+    publishTaskRunStarted(task, activityRef) {
+        publishTaskRunStartedEvent(this.events, task, activityRef);
+    }
+    publishRunResultRecorded(recorded) {
+        publishRunResultRecordedEvent(this.events, recorded);
+    }
+    publishRunTransition(state) {
+        publishRunTransitionEvent({
+            events: this.events,
+            state,
+            now: this.now,
+            getExecutionStatus: () => this.getExecutionStatus(),
+            onTerminal: (terminalState) => this.handleRunTerminalTransition(terminalState),
+        });
+        this.scratchpadAutoRefreshScheduler.notifyActivityChanged();
+    }
+    handleRunTerminalTransition(state) {
+        if (state.activity.status === "finished") {
+            this.maybeScheduleAfterRunCompletion();
+            return;
+        }
+        if (state.activity.status === "failed" && state.activity.task_id !== undefined) {
+            emitWorklistFailedFeedback({
+                store: this.store,
+                events: this.events,
+                taskId: state.activity.task_id,
+                now: this.now,
+            });
+        }
+    }
+    tryRunTaskArrivalScheduler() {
+        const result = runControlPlaneSchedulerForTaskArrival({
+            store: this.store,
+            resolveRunPipeline: this.resolveRunPipeline,
+            readMainlineStatus: this.readMainlineStatus,
+            readSchedulerBlocker: () => this.readSchedulerBlocker(),
+            startRunForTask: (runInput) => this.startRunForTask(runInput),
+            now: this.now,
+        });
+        return result.disposition.kind === "scheduled";
+    }
+    maybeScheduleAfterRunCompletion() {
+        if (this.tryRunTaskArrivalScheduler()) {
+            return;
+        }
+        emitWorklistCompletedFeedback({
+            store: this.store,
+            events: this.events,
+            now: this.now,
+        });
+        this.maybeStartContextSyncAfterWorklistCompletion();
+    }
+    worklistCompletionContextSyncTrigger() {
+        const worklist = readWorklistProjection(this.store.db);
+        const tasks = worklist.modules.flatMap((entry) => entry.tasks);
+        if (tasks.length === 0 || tasks.some((task) => task.status !== "done")) {
+            return undefined;
+        }
+        return {
+            kind: "worklist_all_tasks_completed",
+            completed_task_count: tasks.length,
+            module_count: worklist.modules.length,
+        };
+    }
+    maybeStartContextSyncAfterWorklistCompletion() {
+        const trigger = this.worklistCompletionContextSyncTrigger();
+        if (trigger === undefined || this.readSchedulerBlocker() !== null) {
+            return;
+        }
+        void this.startContextSyncAnalysis(trigger);
+    }
+    startTaskCompileContinuation(owner, roundId) {
+        let tasksAdded = false;
+        return startControlPlaneTaskCompileContinuation({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            owner,
+            roundId,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => {
+                this.publishProcedureTransition(state);
+                if (tasksAdded &&
+                    state.activity.status === "finished" &&
+                    state.activity.workflow_kind === "task_compile") {
+                    this.tryRunTaskArrivalScheduler();
+                }
+            },
+            onTasksAdded: () => {
+                tasksAdded = true;
+            },
+        });
+    }
+    startTaskBoundFollowUpCheck(owner, threadId, roundId) {
+        return startControlPlaneTaskBoundFollowUpCheck({
+            engine: this.engine,
+            store: this.store,
+            events: this.events,
+            owner,
+            threadId,
+            roundId,
+            resolveWorkflowRunner: this.resolveWorkflowRunner,
+            resolveRunPipeline: this.resolveRunPipeline,
+            readMainlineStatus: this.readMainlineStatus,
+            logger: this.logger,
+            now: this.now,
+            publishProcedureTransition: (state) => this.publishProcedureTransition(state),
+            startRunForTask: (runInput) => {
+                void this.startRunForTask(runInput);
+            },
+        });
+    }
+    publishProcedureTransition(state) {
+        this.logProcedureTransition(state);
+        publishProcedureTransitionEvent({
+            events: this.events,
+            store: this.store,
+            state,
+            now: this.now,
+            getExecutionStatus: () => this.getExecutionStatus(),
+        });
+        this.scratchpadAutoRefreshScheduler.notifyActivityChanged();
+    }
+    logProcedureTransition(state) {
+        const activity = state.activity;
+        const fields = {
+            activity_ref: activity.activity_ref,
+            activity_status: activity.status,
+            ...(activity.workflow_ref === undefined ? {} : { workflow_ref: activity.workflow_ref }),
+            ...(activity.workflow_kind === undefined ? {} : { workflow_kind: activity.workflow_kind }),
+            ...(activity.started_at === undefined ? {} : { started_at: activity.started_at }),
+            ...(activity.ended_at === undefined ? {} : { ended_at: activity.ended_at }),
+        };
+        if (activity.started_at !== undefined && activity.ended_at !== undefined) {
+            fields.duration_ms = Math.max(0, new Date(activity.ended_at).getTime() - new Date(activity.started_at).getTime());
+        }
+        const message = activity.status === "running"
+            ? "Procedure started"
+            : activity.status === "finished"
+                ? "Procedure completed"
+                : activity.status === "needs_human"
+                    ? "Procedure needs human input"
+                    : "Procedure failed";
+        this.logger?.info(fields, message);
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,12 @@
+import type { ClarificationRoundRef, TaskId } from "@tutti/shared/ids";
+import type { QueryInvalidationHint } from "@tutti/shared/schemas/api";
+export declare const EXECUTION_STATUS_INVALIDATES: QueryInvalidationHint[];
+export declare const STARTUP_RECOVERY_INVALIDATES: QueryInvalidationHint[];
+export declare function mainChatInvalidates(): QueryInvalidationHint[];
+export declare function scratchpadRefreshInvalidates(): QueryInvalidationHint[];
+export declare function taskCompileInvalidates(): QueryInvalidationHint[];
+export declare function projectContextBootstrapInvalidates(): QueryInvalidationHint[];
+export declare function clarificationInvalidates(roundId: ClarificationRoundRef, threadId?: string): QueryInvalidationHint[];
+export declare function taskRunInvalidates(taskId: TaskId): QueryInvalidationHint[];
+export declare function procedureFailureInvalidates(): QueryInvalidationHint[];
+//# sourceMappingURL=invalidations.d.ts.map

package/dist/control-plane/invalidations.js

@@ -0,0 +1,67 @@
+export const EXECUTION_STATUS_INVALIDATES = [
+    { kind: "execution_status" },
+    { kind: "bootstrap" },
+];
+export const STARTUP_RECOVERY_INVALIDATES = [
+    { kind: "recovery_summaries" },
+    { kind: "worklist" },
+    { kind: "clarification" },
+    { kind: "execution_status" },
+    { kind: "bootstrap" },
+];
+export function mainChatInvalidates() {
+    return [{ kind: "messages", scope: "main_chat" }, { kind: "read_state" }, { kind: "bootstrap" }];
+}
+export function scratchpadRefreshInvalidates() {
+    return [{ kind: "scratchpad" }, { kind: "execution_status" }, { kind: "bootstrap" }];
+}
+export function taskCompileInvalidates() {
+    return [
+        { kind: "worklist" },
+        { kind: "scratchpad" },
+        { kind: "execution_status" },
+        { kind: "bootstrap" },
+    ];
+}
+export function projectContextBootstrapInvalidates() {
+    return [
+        { kind: "execution_status" },
+        { kind: "viewer" },
+        { kind: "workspace" },
+        { kind: "bootstrap" },
+    ];
+}
+export function clarificationInvalidates(roundId, threadId) {
+    return [
+        {
+            kind: "clarification",
+            ...(threadId === undefined ? {} : { thread_id: threadId }),
+            round_id: roundId,
+        },
+        { kind: "messages", scope: "clarification_round", round_id: roundId },
+        { kind: "messages", scope: "main_chat" },
+        { kind: "execution_status" },
+        { kind: "read_state" },
+        { kind: "bootstrap" },
+    ];
+}
+export function taskRunInvalidates(taskId) {
+    return [
+        { kind: "worklist" },
+        { kind: "task", task_id: taskId },
+        { kind: "task_detail", task_id: taskId },
+        { kind: "task_run_results", task_id: taskId },
+        { kind: "project_timeline" },
+        { kind: "execution_status" },
+        { kind: "read_state" },
+        { kind: "bootstrap" },
+    ];
+}
+export function procedureFailureInvalidates() {
+    return [
+        { kind: "messages", scope: "main_chat" },
+        { kind: "read_state" },
+        ...EXECUTION_STATUS_INVALIDATES,
+    ];
+}
+//# sourceMappingURL=invalidations.js.map

package/dist/control-plane/procedure-logging.d.ts

@@ -0,0 +1,11 @@
+import type { ActivityRef, WorkflowInvocationRef } from "@tutti/shared/ids";
+import type { WorkflowKind } from "@tutti/shared/domain";
+import type { ControlPlaneLogger } from "./types.js";
+export declare function logProcedureExecutionError(input: {
+    logger: ControlPlaneLogger | undefined;
+    workflowKind: WorkflowKind;
+    workflowRef: WorkflowInvocationRef;
+    activityRef: ActivityRef;
+    error: unknown;
+}): void;
+//# sourceMappingURL=procedure-logging.d.ts.map

package/dist/control-plane/procedure-logging.js

@@ -0,0 +1,95 @@
+const MAX_ERROR_MESSAGE_LENGTH = 1_000;
+const MAX_DETAIL_STRING_LENGTH = 1_000;
+const MAX_DETAIL_ARRAY_ITEMS = 20;
+const MAX_DETAIL_OBJECT_KEYS = 40;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function compactString(value, maxLength) {
+    const normalized = value.replace(/\s+/gu, " ").trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxLength)}...`;
+}
+function boundedDetailValue(value, seen = new WeakSet()) {
+    if (value === null ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "undefined") {
+        return value;
+    }
+    if (typeof value === "string") {
+        return compactString(value, MAX_DETAIL_STRING_LENGTH);
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        const items = value
+            .slice(0, MAX_DETAIL_ARRAY_ITEMS)
+            .map((item) => boundedDetailValue(item, seen));
+        if (value.length > MAX_DETAIL_ARRAY_ITEMS) {
+            items.push(`[${value.length - MAX_DETAIL_ARRAY_ITEMS} more items]`);
+        }
+        return items;
+    }
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: compactString(value.message, MAX_DETAIL_STRING_LENGTH),
+        };
+    }
+    if (isRecord(value)) {
+        if (seen.has(value)) {
+            return "[Circular]";
+        }
+        seen.add(value);
+        const entries = Object.entries(value);
+        const bounded = {};
+        for (const [key, nested] of entries.slice(0, MAX_DETAIL_OBJECT_KEYS)) {
+            const boundedNested = boundedDetailValue(nested, seen);
+            if (boundedNested !== undefined) {
+                bounded[key] = boundedNested;
+            }
+        }
+        if (entries.length > MAX_DETAIL_OBJECT_KEYS) {
+            bounded.truncated_key_count = entries.length - MAX_DETAIL_OBJECT_KEYS;
+        }
+        seen.delete(value);
+        return bounded;
+    }
+    if (typeof value === "function") {
+        return value.name.trim().length === 0 ? "[Function]" : `[Function:${value.name}]`;
+    }
+    if (typeof value === "symbol") {
+        return value.description === undefined ? "[Symbol]" : `[Symbol:${value.description}]`;
+    }
+    return "[Unsupported]";
+}
+function errorDetails(error) {
+    if (!isRecord(error) || !("details" in error)) {
+        return undefined;
+    }
+    return boundedDetailValue(error.details);
+}
+function errorCode(error) {
+    if (!isRecord(error) || typeof error.code !== "string") {
+        return undefined;
+    }
+    return error.code;
+}
+export function logProcedureExecutionError(input) {
+    input.logger?.info({
+        activity_ref: input.activityRef,
+        workflow_ref: input.workflowRef,
+        workflow_kind: input.workflowKind,
+        error_name: input.error instanceof Error ? input.error.name : "NonError",
+        error_message: compactString(input.error instanceof Error ? input.error.message : String(input.error), MAX_ERROR_MESSAGE_LENGTH),
+        ...(errorCode(input.error) === undefined ? {} : { error_code: errorCode(input.error) }),
+        ...(errorDetails(input.error) === undefined
+            ? {}
+            : { error_details: errorDetails(input.error) }),
+    }, "Procedure execution error");
+}
+//# sourceMappingURL=procedure-logging.js.map

package/dist/control-plane/project-brief-refresh.d.ts

@@ -0,0 +1,31 @@
+import type { ActivityRef, WorkflowInvocationRef } from "@tutti/shared/ids";
+import { type ProjectBriefProjection } from "../project-brief/index.js";
+import type { HostProjectStore } from "../store/index.js";
+import type { ControlPlaneLogger, Phase5ControlPlaneOptions } from "./types.js";
+import type { ProcedureWorkflowRunner, ProcedureWorkflowRunnerResolver } from "./workflows/index.js";
+export type ProjectBriefRefreshReason = "project_context_bootstrap" | "context_sync" | "project_docs_init" | "task_run_promotion" | "provider_configured";
+export type RefreshProjectBriefProjectionResult = {
+    kind: "refreshed";
+    brief: Extract<ProjectBriefProjection, {
+        state: "ready" | "stale";
+    }>;
+} | {
+    kind: "skipped";
+    reason: "project_context_unavailable" | "provider_unavailable" | "runner_unavailable" | "already_fresh" | "source_not_ready";
+} | {
+    kind: "failed";
+    reason: "source_unavailable" | "projection_unavailable" | "provider_failed";
+};
+export declare function projectBriefShouldRefreshForUpdatedPaths(paths: readonly string[]): boolean;
+export declare function refreshProjectBriefProjection(input: {
+    store: HostProjectStore;
+    projectContext: Phase5ControlPlaneOptions["projectContext"] | undefined;
+    reason: ProjectBriefRefreshReason;
+    runner?: ProcedureWorkflowRunner;
+    resolveWorkflowRunner?: ProcedureWorkflowRunnerResolver;
+    workflowRef?: WorkflowInvocationRef;
+    activityRef?: ActivityRef;
+    logger?: ControlPlaneLogger | undefined;
+    now: () => Date;
+}): Promise<RefreshProjectBriefProjectionResult>;
+//# sourceMappingURL=project-brief-refresh.d.ts.map