@xfey/tutti 0.1.67 → 0.1.69

package/dist/chat-assistant/index.d.ts

@@ -43,7 +43,7 @@ export type ReadOnlyChatAssistantOptions = {
     workspaceRoot: string;
     model: ReadOnlyChatAssistantModel;
     promptsRoot?: string;
-    onScratchpadSourceChanged?: () => void;
+    onScratchpadSourceChanged?: (message: MessageProjection) => void;
     now?: () => Date;
 };
 export declare function isChatAssistantOutput(value: unknown): value is ChatAssistantOutput;

package/dist/chat-assistant/index.js

@@ -206,7 +206,7 @@ export class ReadOnlyChatAssistant {
             invalidates: mainChatMessageInvalidates(),
         });
         if (refs?.scratchpad_source !== "exclude") {
-            this.options.onScratchpadSourceChanged?.();
+            this.options.onScratchpadSourceChanged?.(message);
         }
     }
     appendClarificationRoundAssistantMessage(input) {

package/dist/collaboration-state/index.d.ts

@@ -3,7 +3,7 @@ export { createIdleExecutionStatusProjection } from "./execution-status.js";
 export { createMainChatAgentMessage, createMainChatMessage, createMainChatSystemMessage, ensureInitialProjectWelcomeMessage, hasMainChatArtifactPreviewMessage, hasMainChatTaskResultMessage, hasMainChatWorklistCompileMessage, hasMainChatWorklistFeedbackMessage, readCompletedWorklistFeedbackTaskIds, readMessageProjectionById, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMainChatMessagesForScratchpadCycle, } from "./messages.js";
 export { createEmptyScratchpadProjection, readScratchpadReceiptSourceRefs, readScratchpadProjection, upsertScratchpadProjection, } from "./scratchpad.js";
 export { markScratchpadRefreshFailed, markScratchpadRefreshStarted, markScratchpadRefreshSucceeded, markScratchpadSourceDirty, readScratchpadSourceState, } from "./scratchpad-source-state.js";
-export { captureTaskCompileContext, completeTaskCompileContext, readActiveTaskCompileContext, rollbackTaskCompileContext, taskCompileContextSnapshot, } from "./task-compile-context.js";
+export { captureTaskCompileContext, completeTaskCompileContext, readActiveTaskCompileContext, readCurrentScratchpadSourceRefs, rollbackTaskCompileContext, taskCompileContextSnapshot, } from "./task-compile-context.js";
 export { deleteStaleClarificationSubmitReplayHints, readActiveClarificationProjection, readClarificationRoundProjection, readClarificationRoundsForThread, readClarificationThreadResponse, readSealedClarificationRoundsWithoutSuccessor, } from "./clarification-records.js";
 export { createClarificationRoundAgentMessage, createClarificationRoundMessage, readClarificationRoundMessagesWindow, } from "./clarification-messages.js";
 export { openNextTaskBoundClarificationRound, openNextTaskCompileClarificationRound, openTaskCompileClarificationRound, } from "./clarification-rounds.js";

package/dist/collaboration-state/index.js

@@ -3,7 +3,7 @@ export { createIdleExecutionStatusProjection } from "./execution-status.js";
 export { createMainChatAgentMessage, createMainChatMessage, createMainChatSystemMessage, ensureInitialProjectWelcomeMessage, hasMainChatArtifactPreviewMessage, hasMainChatTaskResultMessage, hasMainChatWorklistCompileMessage, hasMainChatWorklistFeedbackMessage, readCompletedWorklistFeedbackTaskIds, readMessageProjectionById, readMainChatMessageWindow, readMainChatMessagesBeforeCursor, readMainChatMessagesForScratchpadCycle, } from "./messages.js";
 export { createEmptyScratchpadProjection, readScratchpadReceiptSourceRefs, readScratchpadProjection, upsertScratchpadProjection, } from "./scratchpad.js";
 export { markScratchpadRefreshFailed, markScratchpadRefreshStarted, markScratchpadRefreshSucceeded, markScratchpadSourceDirty, readScratchpadSourceState, } from "./scratchpad-source-state.js";
-export { captureTaskCompileContext, completeTaskCompileContext, readActiveTaskCompileContext, rollbackTaskCompileContext, taskCompileContextSnapshot, } from "./task-compile-context.js";
+export { captureTaskCompileContext, completeTaskCompileContext, readActiveTaskCompileContext, readCurrentScratchpadSourceRefs, rollbackTaskCompileContext, taskCompileContextSnapshot, } from "./task-compile-context.js";
 export { deleteStaleClarificationSubmitReplayHints, readActiveClarificationProjection, readClarificationRoundProjection, readClarificationRoundsForThread, readClarificationThreadResponse, readSealedClarificationRoundsWithoutSuccessor, } from "./clarification-records.js";
 export { createClarificationRoundAgentMessage, createClarificationRoundMessage, readClarificationRoundMessagesWindow, } from "./clarification-messages.js";
 export { openNextTaskBoundClarificationRound, openNextTaskCompileClarificationRound, openTaskCompileClarificationRound, } from "./clarification-rounds.js";

package/dist/collaboration-state/task-compile-context.d.ts

@@ -1,7 +1,8 @@
 import type { WorkflowInvocationRef } from "@tutti/shared/ids";
 import { type SqliteDatabase } from "../store/index.js";
-import type { CaptureTaskCompileContextInput, CompleteTaskCompileContextInput, RollbackTaskCompileContextInput, ScratchpadContentSnapshot, TaskCompileContextRecord } from "./types.js";
+import type { CaptureTaskCompileContextInput, CompleteTaskCompileContextInput, RollbackTaskCompileContextInput, ScratchpadContentSnapshot, ScratchpadSourceRefInput, TaskCompileContextRecord } from "./types.js";
 export declare function readActiveTaskCompileContext(db: SqliteDatabase, workflowRef?: WorkflowInvocationRef): TaskCompileContextRecord | null;
+export declare function readCurrentScratchpadSourceRefs(db: SqliteDatabase): ScratchpadSourceRefInput[];
 export declare function captureTaskCompileContext(db: SqliteDatabase, input: CaptureTaskCompileContextInput): TaskCompileContextRecord;
 export declare function completeTaskCompileContext(db: SqliteDatabase, input: CompleteTaskCompileContextInput): {
     updated_at?: string;

package/dist/collaboration-state/task-compile-context.js

@@ -2,6 +2,16 @@ import { withHostStoreTransaction } from "../store/index.js";
 import { readScratchpadProjection } from "./scratchpad.js";
 import { readScratchpadSourceState } from "./scratchpad-source-state.js";
 import { nowIso, stringifyJson } from "./serialization.js";
+function cursorIsAfter(left, right) {
+    if (left === undefined) {
+        return false;
+    }
+    if (right === undefined) {
+        return true;
+    }
+    const timeOrder = left.created_at.localeCompare(right.created_at);
+    return timeOrder > 0 || (timeOrder === 0 && left.message_id > right.message_id);
+}
 function parseStringArray(value, field) {
     let parsed;
     try {
@@ -89,7 +99,7 @@ export function readActiveTaskCompileContext(db, workflowRef) {
     }
     return mapContextRow(row, readContextSources(db, row.workflow_ref));
 }
-function currentScratchpadSources(db) {
+export function readCurrentScratchpadSourceRefs(db) {
     return db
         .prepare(`
         SELECT message_id, created_at
@@ -98,7 +108,12 @@ function currentScratchpadSources(db) {
           AND source_scope = 'main_chat'
         ORDER BY created_at ASC, message_id ASC
       `)
-        .all();
+        .all()
+        .map((source) => ({
+        message_id: source.message_id,
+        source_scope: "main_chat",
+        created_at: source.created_at,
+    }));
 }
 export function captureTaskCompileContext(db, input) {
     return withHostStoreTransaction(db, (tx) => {
@@ -114,7 +129,7 @@ export function captureTaskCompileContext(db, input) {
             throw new Error("A ready Scratchpad is required to capture Task Compile Context");
         }
         const sourceState = readScratchpadSourceState(tx);
-        const sources = currentScratchpadSources(tx);
+        const sources = readCurrentScratchpadSourceRefs(tx);
         const lastSource = sources.at(-1);
         const through = sourceState.refreshed_through_cursor ??
             (lastSource === undefined
@@ -233,11 +248,18 @@ export function rollbackTaskCompileContext(db, input) {
         }
         const rolledBackAt = nowIso(input.now);
         const sourceState = readScratchpadSourceState(tx);
-        const dirtySince = sourceState.in_flight !== undefined &&
-            new Date(rolledBackAt).getTime() <= new Date(sourceState.in_flight.started_at).getTime()
-            ? new Date(new Date(sourceState.in_flight.started_at).getTime() + 1).toISOString()
-            : rolledBackAt;
         const after = context.source_window.after;
+        const through = context.source_window.through;
+        const hasBoundaryAfterSourceChanges = sourceState.dirty_since !== undefined ||
+            sourceState.in_flight !== undefined ||
+            cursorIsAfter(sourceState.refreshed_through_cursor, through);
+        const dirtySince = hasBoundaryAfterSourceChanges
+            ? sourceState.in_flight !== undefined &&
+                new Date(rolledBackAt).getTime() <= new Date(sourceState.in_flight.started_at).getTime()
+                ? new Date(new Date(sourceState.in_flight.started_at).getTime() + 1).toISOString()
+                : rolledBackAt
+            : null;
+        const restoredThrough = hasBoundaryAfterSourceChanges ? after : through;
         tx.prepare(`
         INSERT INTO scratchpad_source_state (
           id,
@@ -256,7 +278,7 @@ export function rollbackTaskCompileContext(db, input) {
           refreshed_through_cursor_message_id = excluded.refreshed_through_cursor_message_id,
           dirty_since = excluded.dirty_since,
           updated_at = excluded.updated_at
-      `).run(after?.created_at ?? null, after?.message_id ?? null, after?.created_at ?? null, after?.message_id ?? null, dirtySince, rolledBackAt);
+      `).run(after?.created_at ?? null, after?.message_id ?? null, restoredThrough?.created_at ?? null, restoredThrough?.message_id ?? null, dirtySince, rolledBackAt);
         tx.prepare("DELETE FROM active_task_compile_context WHERE workflow_ref = ?").run(input.workflow_ref);
         return true;
     });

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

@@ -1,5 +1,5 @@
 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 { ExecutionStatusProjection, MessageProjection, 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";
@@ -18,6 +18,10 @@ export declare class Phase5ControlPlane {
     private readonly runLifecycle;
     private readonly now;
     private readonly scratchpadAutoRefreshScheduler;
+    private readonly pendingReferenceSummaryPaths;
+    private readonly referenceSummaryWaiters;
+    private pendingAllReferenceSummaries;
+    private referenceSummaryStartScheduled;
     private lastRecoveryConclusion;
     constructor(options: Phase5ControlPlaneOptions);
     getExecutionStatus(): ExecutionStatusProjection;
@@ -26,7 +30,7 @@ export declare class Phase5ControlPlane {
     startScratchpadRefresh(options?: {
         lane?: ProcedureLane;
     }): ControlPlaneCommandResult<RefreshScratchpadDisposition, RefreshScratchpadResult>;
-    notifyScratchpadSourceChanged(): void;
+    notifyScratchpadSourceChanged(message: MessageProjection): void;
     refreshProjectBrief(options: {
         reason: ProjectBriefRefreshReason;
         workflowRef?: WorkflowInvocationRef;
@@ -36,9 +40,12 @@ export declare class Phase5ControlPlane {
     startTaskCompile(payload: SubmitWorklistPayload): ControlPlaneCommandResult<SubmitWorklistDisposition, SubmitWorklistResult>;
     startContextSyncAnalysis(trigger?: ContextSyncWorkflowTrigger): ControlPlaneCommandResult<ContextSyncDisposition, ContextSyncResult>;
     startReferenceSummaryRefresh(payload?: RefreshReferenceSummariesPayload): ControlPlaneCommandResult<RefreshReferenceSummariesDisposition, RefreshReferenceSummariesResult>;
+    private tryStartPendingReferenceSummaryRefresh;
     sendClarificationRoundMessage(roundId: ClarificationRoundRef, payload: SendClarificationRoundMessagePayload, author: TrustedHumanAuthor): ControlPlaneCommandResult<SendClarificationRoundMessageDisposition, SendClarificationRoundMessageResult>;
     submitClarificationRound(roundId: ClarificationRoundRef, payload: SubmitClarificationRoundPayload, commandId: IdempotencyKey): ControlPlaneCommandResult<SubmitClarificationRoundDisposition, SubmitClarificationRoundResult>;
     waitForIdle(): Promise<void>;
+    private hasPendingReferenceSummaryRefresh;
+    private schedulePendingReferenceSummaryRefresh;
     private startRunForTask;
     private readActiveRun;
     private readActiveProcedures;

package/dist/control-plane/index.js

@@ -9,6 +9,7 @@ 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 { shouldUseMessageAsScratchpadSource } from "./scratchpad-source-messages.js";
 import { startControlPlaneTaskCompile } from "./task-compile-start.js";
 import { startControlPlaneTaskCompileContinuation } from "./task-compile-continuation.js";
 import { startControlPlaneTaskBoundFollowUpCheck } from "./follow-up-start.js";
@@ -30,6 +31,10 @@ export class Phase5ControlPlane {
     runLifecycle;
     now;
     scratchpadAutoRefreshScheduler;
+    pendingReferenceSummaryPaths = new Set();
+    referenceSummaryWaiters = new Map();
+    pendingAllReferenceSummaries = false;
+    referenceSummaryStartScheduled = false;
     lastRecoveryConclusion = null;
     constructor(options) {
         this.store = options.store;
@@ -102,7 +107,10 @@ export class Phase5ControlPlane {
             publishProcedureTransition: (state) => this.publishProcedureTransition(state),
         });
     }
-    notifyScratchpadSourceChanged() {
+    notifyScratchpadSourceChanged(message) {
+        if (!shouldUseMessageAsScratchpadSource(message)) {
+            return;
+        }
         this.scratchpadAutoRefreshScheduler.notifySourceChanged();
     }
     refreshProjectBrief(options) {
@@ -139,6 +147,11 @@ export class Phase5ControlPlane {
                     this.tryRunTaskArrivalScheduler();
                 }
             },
+            registerReferenceSummaryWaiter: (activityRef, waiter) => {
+                const existing = this.referenceSummaryWaiters.get(activityRef) ?? [];
+                existing.push(waiter);
+                this.referenceSummaryWaiters.set(activityRef, existing);
+            },
             onTasksAdded: () => {
                 tasksAdded = true;
             },
@@ -159,11 +172,25 @@ export class Phase5ControlPlane {
         });
     }
     startReferenceSummaryRefresh(payload = {}) {
-        return startReferenceSummaryRefreshProcedure({
+        if (payload.paths === undefined) {
+            this.pendingAllReferenceSummaries = true;
+            this.pendingReferenceSummaryPaths.clear();
+        }
+        else {
+            for (const path of payload.paths) {
+                this.pendingReferenceSummaryPaths.add(path);
+            }
+        }
+        return this.tryStartPendingReferenceSummaryRefresh();
+    }
+    tryStartPendingReferenceSummaryRefresh() {
+        const refreshAll = this.pendingAllReferenceSummaries;
+        const paths = refreshAll ? undefined : [...this.pendingReferenceSummaryPaths];
+        const result = startReferenceSummaryRefreshProcedure({
             engine: this.engine,
             store: this.store,
             events: this.events,
-            ...(payload.paths === undefined ? {} : { paths: payload.paths }),
+            ...(paths === undefined ? {} : { paths }),
             resolveWorkflowRunner: this.resolveWorkflowRunner,
             readActiveActivity: () => this.readSchedulerBlocker(),
             projectContext: this.projectContext,
@@ -171,6 +198,18 @@ export class Phase5ControlPlane {
             now: this.now,
             publishProcedureTransition: (state) => this.publishProcedureTransition(state),
         });
+        if (result.disposition.kind !== "already_running") {
+            if (refreshAll) {
+                this.pendingAllReferenceSummaries = false;
+                this.pendingReferenceSummaryPaths.clear();
+            }
+            else {
+                for (const path of paths ?? []) {
+                    this.pendingReferenceSummaryPaths.delete(path);
+                }
+            }
+        }
+        return result;
     }
     sendClarificationRoundMessage(roundId, payload, author) {
         return runSendClarificationRoundMessage({
@@ -198,11 +237,29 @@ export class Phase5ControlPlane {
         while (true) {
             await this.engine.waitForIdle();
             await this.runEngine.waitForIdle();
-            if (this.readAnyActiveActivity() === null) {
+            await Promise.resolve();
+            if (this.readAnyActiveActivity() === null &&
+                !this.hasPendingReferenceSummaryRefresh()) {
                 return;
             }
+            this.schedulePendingReferenceSummaryRefresh();
         }
     }
+    hasPendingReferenceSummaryRefresh() {
+        return this.pendingAllReferenceSummaries || this.pendingReferenceSummaryPaths.size !== 0;
+    }
+    schedulePendingReferenceSummaryRefresh() {
+        if (!this.hasPendingReferenceSummaryRefresh() || this.referenceSummaryStartScheduled) {
+            return;
+        }
+        this.referenceSummaryStartScheduled = true;
+        queueMicrotask(() => {
+            this.referenceSummaryStartScheduled = false;
+            if (this.hasPendingReferenceSummaryRefresh()) {
+                void this.tryStartPendingReferenceSummaryRefresh();
+            }
+        });
+    }
     startRunForTask(input) {
         const result = startControlPlaneRunForTask({
             runEngine: this.runEngine,
@@ -304,6 +361,9 @@ export class Phase5ControlPlane {
             onTerminal: (terminalState) => this.handleRunTerminalTransition(terminalState),
         });
         this.scratchpadAutoRefreshScheduler.notifyActivityChanged();
+        if (state.transition_kind === "terminal") {
+            this.schedulePendingReferenceSummaryRefresh();
+        }
     }
     handleRunTerminalTransition(state) {
         if (state.activity.status === "finished") {
@@ -377,6 +437,7 @@ export class Phase5ControlPlane {
             owner,
             roundId,
             resolveWorkflowRunner: this.resolveWorkflowRunner,
+            projectContext: this.projectContext,
             logger: this.logger,
             now: this.now,
             publishProcedureTransition: (state) => {
@@ -421,6 +482,23 @@ export class Phase5ControlPlane {
             getExecutionStatus: () => this.getExecutionStatus(),
         });
         this.scratchpadAutoRefreshScheduler.notifyActivityChanged();
+        if (state.transition_kind === "terminal") {
+            const activityRef = state.activity.activity_ref;
+            const waiters = this.referenceSummaryWaiters.get(activityRef) ?? [];
+            this.referenceSummaryWaiters.delete(activityRef);
+            for (const waiter of waiters) {
+                try {
+                    waiter(state);
+                }
+                catch (error) {
+                    this.logger?.info({
+                        activity_ref: activityRef,
+                        error_name: error instanceof Error ? error.name : "UnknownError",
+                    }, "Reference summary continuation failed");
+                }
+            }
+            this.schedulePendingReferenceSummaryRefresh();
+        }
     }
     logProcedureTransition(state) {
         const activity = state.activity;

package/dist/control-plane/recent-references.d.ts

@@ -0,0 +1,26 @@
+import type { MessageId } from "@tutti/shared/ids";
+import type { MessageReferenceFileRef } from "@tutti/shared/schemas/api";
+import type { ScratchpadSourceRefInput } from "../collaboration-state/types.js";
+import type { SqliteDatabase } from "../store/index.js";
+import type { RecentReferenceContext } from "./reference-context-types.js";
+export type RecentReferenceSource = MessageReferenceFileRef & {
+    message_id: MessageId;
+};
+export declare function readRecentReferenceSources(db: SqliteDatabase, sourceRefs: Array<Pick<ScratchpadSourceRefInput, "message_id">>): RecentReferenceSource[];
+export declare function readPendingRecentReferenceSummaryPaths(options: {
+    workspaceRoot: string;
+    sources: RecentReferenceSource[];
+    now: () => Date;
+}): string[];
+export declare function materializeRecentReferences(options: {
+    workspaceRoot: string;
+    sources: RecentReferenceSource[];
+    now: () => Date;
+}): RecentReferenceContext[];
+export declare function materializeWorkflowRecentReferences(options: {
+    db: SqliteDatabase;
+    workspaceRoot: string;
+    workflowRef: string;
+    now: () => Date;
+}): RecentReferenceContext[];
+//# sourceMappingURL=recent-references.d.ts.map

package/dist/control-plane/recent-references.js

@@ -0,0 +1,94 @@
+import { readMessageProjectionById, readScratchpadReceiptSourceRefs, } from "../collaboration-state/index.js";
+import { readReferenceSummaryEntries } from "../workspace-ops/index.js";
+export function readRecentReferenceSources(db, sourceRefs) {
+    const sources = [];
+    const seen = new Set();
+    for (const sourceRef of sourceRefs) {
+        const message = readMessageProjectionById(db, sourceRef.message_id);
+        const reference = message?.refs?.reference_file;
+        if (message?.author.kind !== "human" ||
+            reference === undefined ||
+            reference.source !== "human_upload") {
+            continue;
+        }
+        const identity = `${reference.path}\u0000${reference.blob_oid ?? ""}`;
+        if (seen.has(identity)) {
+            continue;
+        }
+        seen.add(identity);
+        sources.push({ message_id: sourceRef.message_id, ...reference });
+    }
+    return sources;
+}
+export function readPendingRecentReferenceSummaryPaths(options) {
+    const paths = [...new Set(options.sources.map((source) => source.path))];
+    if (paths.length === 0) {
+        return [];
+    }
+    const entries = new Map(readReferenceSummaryEntries({
+        workspaceRoot: options.workspaceRoot,
+        paths,
+        now: options.now,
+    }).map((entry) => [entry.path, entry]));
+    const pending = new Set();
+    for (const source of options.sources) {
+        const entry = entries.get(source.path);
+        if (source.blob_oid === undefined ||
+            entry === undefined ||
+            entry.blob_oid !== source.blob_oid) {
+            continue;
+        }
+        if (entry.summary.status === "missing" || entry.summary.status === "stale") {
+            pending.add(source.path);
+        }
+    }
+    return [...pending];
+}
+export function materializeRecentReferences(options) {
+    const paths = [...new Set(options.sources.map((source) => source.path))];
+    const entries = new Map(paths.length === 0
+        ? []
+        : readReferenceSummaryEntries({
+            workspaceRoot: options.workspaceRoot,
+            paths,
+            now: options.now,
+        }).map((entry) => [entry.path, entry]));
+    return options.sources.map((source) => {
+        const entry = entries.get(source.path);
+        if (source.blob_oid === undefined) {
+            return unavailableRecentReference(source, "source_blob_unavailable");
+        }
+        if (entry === undefined) {
+            return unavailableRecentReference(source, "reference_unavailable");
+        }
+        if (entry.blob_oid !== source.blob_oid) {
+            return unavailableRecentReference(source, "reference_source_changed");
+        }
+        if (entry.summary.status === "available" && entry.summary.text !== undefined) {
+            return {
+                path: source.path,
+                name: source.name,
+                summary: { status: "available", text: entry.summary.text },
+            };
+        }
+        if (entry.summary.status === "unavailable") {
+            return unavailableRecentReference(source, entry.summary.unavailable_reason ?? "summary_unavailable");
+        }
+        return unavailableRecentReference(source, "summary_not_ready");
+    });
+}
+export function materializeWorkflowRecentReferences(options) {
+    return materializeRecentReferences({
+        workspaceRoot: options.workspaceRoot,
+        sources: readRecentReferenceSources(options.db, readScratchpadReceiptSourceRefs(options.db, options.workflowRef)),
+        now: options.now,
+    });
+}
+function unavailableRecentReference(source, reason) {
+    return {
+        path: source.path,
+        name: source.name,
+        summary: { status: "unavailable", reason },
+    };
+}
+//# sourceMappingURL=recent-references.js.map

package/dist/control-plane/reference-context-types.d.ts

@@ -0,0 +1,12 @@
+export type RecentReferenceContext = {
+    path: string;
+    name: string;
+    summary: {
+        status: "available";
+        text: string;
+    } | {
+        status: "unavailable";
+        reason: string;
+    };
+};
+//# sourceMappingURL=reference-context-types.d.ts.map

package/dist/control-plane/reference-context-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reference-context-types.js.map

package/dist/control-plane/reference-summary-refresh.d.ts

@@ -1,4 +1,4 @@
-import type { ActivityRef } from "@tutti/shared/ids";
+import type { ActivityRef, WorkflowInvocationRef } from "@tutti/shared/ids";
 import type { RefreshReferenceSummariesDisposition, RefreshReferenceSummariesResult } from "@tutti/shared/schemas/api";
 import type { ProcedureEngine, ProcedureEngineState } from "../procedure-engine/index.js";
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
@@ -17,6 +17,10 @@ export declare function startReferenceSummaryRefreshProcedure(input: {
     projectContext: Phase5ControlPlaneOptions["projectContext"];
     logger?: ControlPlaneLogger | undefined;
     now: () => Date;
+    onExecuteStart?: (input: {
+        activityRef: ActivityRef;
+        workflowRef: WorkflowInvocationRef;
+    }) => void;
     publishProcedureTransition: (state: ProcedureEngineState) => void;
 }): ControlPlaneCommandResult<RefreshReferenceSummariesDisposition, RefreshReferenceSummariesResult>;
 //# sourceMappingURL=reference-summary-refresh.d.ts.map