Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

fix(onboarding): give the first-run summary its own writing phase

Louis Beaumont4f6ebf3827cc
diff --git a/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx b/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx
index ab9399f5d..2108ec5c9 100644
--- a/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx
+++ b/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx
@@ -78,7 +78,12 @@ export function FirstRunLearningBanner(props: LearningWindowOptions = {}) {
const { phase, capturedApps, remainingMs, chatId, emptyReason, dismiss } =
useLearningWindow(props);
- if (phase !== "learning" && phase !== "ready" && phase !== "empty") {
+ if (
+ phase !== "learning" &&
+ phase !== "writing" &&
+ phase !== "ready" &&
+ phase !== "empty"
+ ) {
return null;
}
@@ -139,6 +144,38 @@ export function FirstRunLearningBanner(props: LearningWindowOptions = {}) {
</div>
)}
+ {phase === "writing" && (
+ <div className="flex flex-col gap-2">
+ <div className="flex items-center gap-3">
+ <Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" />
+ <p className="text-xs font-medium text-foreground">
+ Writing your summary
+ </p>
+ </div>
+ {/* No countdown. The clock measured how long we would keep waiting
+ for something to summarize, and that question is already
+ answered; the model can take tens of seconds and outlast the
+ ceiling, so a timer here would tick to 0:00 and then keep
+ spinning. */}
+ <p className="text-[11px] leading-relaxed text-muted-foreground">
+ Screenpipe saw enough. Putting the summary together now — this
+ takes a few seconds.
+ </p>
+ {capturedApps.length > 0 && (
+ <div className="flex items-center gap-2 pt-0.5">
+ <span className="shrink-0 text-[11px] text-muted-foreground">
+ Reading from
+ </span>
+ <span className="flex items-center gap-1">
+ {capturedApps.map((app) => (
+ <CapturedAppIcon key={app.name} app={app} />
+ ))}
+ </span>
+ </div>
+ )}
+ </div>
+ )}
+
{phase === "ready" && (
<div className="flex flex-col gap-2">
<p className="text-xs font-medium text-foreground">
diff --git a/apps/screenpipe-app-tauri/lib/first-run/learning-window.test.ts b/apps/screenpipe-app-tauri/lib/first-run/learning-window.test.ts
index 6a3d7d89b..99b31ffb1 100644
--- a/apps/screenpipe-app-tauri/lib/first-run/learning-window.test.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run/learning-window.test.ts
@@ -20,6 +20,7 @@ import {
markLearningDone,
markLearningEmpty,
markLearningReady,
+ markLearningWriting,
normalizeEmptyReason,
readLearningWindow,
resetLearningWindow,
@@ -528,3 +529,37 @@ describe("classifyEmptyReason", () => {
expect(classifyEmptyReason(undefined)).toBe("unknown");
});
});
+
+describe("writing phase", () => {
+ it("resumes a persisted writing phase as ready when the chat was seeded", () => {
+ // The process died after seedFirstRunSummaryChat but before markReady.
+ // The summary exists, so send the user to it rather than to an empty state.
+ beginLearningWindow(new Date().toISOString());
+ markLearningWriting();
+ const current = readLearningWindow();
+ localStorage.setItem(
+ "screenpipe.first-run.learning-window.v1",
+ JSON.stringify({ ...current, phase: "writing", chatId: "chat-42" }),
+ );
+ const resumed = readLearningWindow();
+ expect(resumed.phase).toBe("ready");
+ expect(resumed.chatId).toBe("chat-42");
+ });
+
+ it("settles a persisted writing phase with no chat instead of restoring a spinner", () => {
+ // The model call died with the process and the seed claim is already
+ // spent, so nothing will resume the work. Restoring `writing` would show a
+ // spinner that can never finish.
+ beginLearningWindow(new Date().toISOString());
+ markLearningWriting();
+ expect(readLearningWindow().phase).toBe("empty");
+ });
+
+ it("marks writing without disturbing the anchor", () => {
+ const anchor = new Date().toISOString();
+ beginLearningWindow(anchor);
+ const writing = markLearningWriting();
+ expect(writing.phase).toBe("writing");
+ expect(writing.startedAt).toBe(anchor);
+ });
+});
diff --git a/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts b/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts
index e3aee5ada..049bf5823 100644
--- a/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts
@@ -20,16 +20,33 @@
* nothing in it. We show a ceiling so the wait is bounded and predictable,
* but resolve as soon as there is enough to say something true.
*
- * 2. The summary is DETERMINISTIC. It is rendered from /activity-summary
- * fields, with no model call. That keeps the first moment instant, offline,
- * free (a Free account's entire monthly hosted-AI allowance is small enough
- * that spending it here would be a poor trade), and — most importantly —
- * unable to hallucinate on thin evidence.
+ * 2. The summary has a DETERMINISTIC floor. `buildLearningSummary` renders it
+ * from /activity-summary fields with no model call, so there is always a
+ * real summary available instantly, offline and free, and one that cannot
+ * hallucinate on thin evidence.
+ *
+ * The window does then offer the user's own AI preset a chance to say it
+ * better, grounded on exactly those same facts (see `summarize-with-ai`),
+ * and takes the deterministic text whenever the model is absent, declines,
+ * errors, or returns something the validator rejects. This comment used to
+ * claim there was no model call at all, which was true of the builder and
+ * false of the window; the AI attempt is why the `writing` phase exists.
*/
export type FirstRunLearningPhase =
| "idle"
| "learning"
+ /**
+ * Evidence is in and the summary is being produced.
+ *
+ * Split out of `learning` because the two are not the same wait and the UI
+ * cannot honestly show the same thing for both. Writing awaits a model, which
+ * the code below notes can take tens of seconds, so the countdown can reach
+ * zero while this is still running — leaving a spinner next to `0:00` and no
+ * explanation. Nothing is owed to the clock any more once we get here: the
+ * window has what it needs and is only waiting on the summary.
+ */
+ | "writing"
| "ready"
| "empty"
| "done";
@@ -511,6 +528,7 @@ function normalize(value: unknown): FirstRunLearningState {
const state = value as Partial<FirstRunLearningState>;
const phase: FirstRunLearningPhase =
state.phase === "learning" ||
+ state.phase === "writing" ||
state.phase === "ready" ||
state.phase === "empty" ||
state.phase === "done"
@@ -536,6 +554,31 @@ function normalize(value: unknown): FirstRunLearningState {
}
}
+ // `writing` cannot survive the process that was doing the writing. The model
+ // call died with it, and the seed claim is already spent, so nothing will
+ // pick the work back up. Resume to whatever actually landed: the chat if it
+ // was seeded before the app went away, otherwise a settled empty state with
+ // a dismiss button. Leaving it as `writing` would restore a spinner that can
+ // never finish, which is the failure this phase exists to remove.
+ if (phase === "writing") {
+ if (typeof state.chatId === "string" && state.chatId) {
+ return {
+ phase: "ready",
+ startedAt,
+ seededAt: typeof state.seededAt === "string" ? state.seededAt : null,
+ chatId: state.chatId,
+ emptyReason: null,
+ capturedApps: [],
+ };
+ }
+ return {
+ ...EMPTY_STATE,
+ phase: "empty",
+ startedAt,
+ emptyReason: "unknown",
+ };
+ }
+
return {
phase,
startedAt,
@@ -604,6 +647,17 @@ export function releaseLearningSeed(): void {
writeLearningWindow({ ...current, seededAt: null });
}
+/**
+ * Evidence accepted; the summary is being produced.
+ *
+ * Persisted rather than kept in the hook so a reopened window resumes into the
+ * resolution in `normalize` instead of restoring a countdown it already left.
+ */
+export function markLearningWriting(): FirstRunLearningState {
+ const current = readLearningWindow();
+ return writeLearningWindow({ ...current, phase: "writing" });
+}
+
export function markLearningReady(chatId: string): FirstRunLearningState {
const current = readLearningWindow();
return writeLearningWindow({ ...current, phase: "ready", chatId });
diff --git a/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.test.ts b/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.test.ts
index c8afa3a1c..34a0b38f7 100644
--- a/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.test.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.test.ts
@@ -205,3 +205,52 @@ describe("useLearningWindow settings race", () => {
});
});
});
+
+describe("useLearningWindow writing phase", () => {
+ // Regression: `writing` is set from inside the resolve effect. When that
+ // effect was keyed on `isLearning` alone, the transition tore it down,
+ // cleanup set `cancelled`, the in-flight detail fetch aborted and the
+ // summary bailed and released the seed — so the chat was never seeded and
+ // the banner sat on a dead spinner. The phases must share one effect.
+ it("still seeds the chat after flipping out of learning", async () => {
+ const { fetchRecentActivity } = await import(
+ "@/lib/first-run/recent-activity"
+ );
+ const { seedFirstRunSummaryChat } = await import(
+ "@/lib/first-run/seed-summary-chat"
+ );
+ vi.mocked(fetchRecentActivity).mockResolvedValue({
+ data_status: "ok",
+ total_frames: 48,
+ total_active_minutes: 4,
+ apps: [
+ { name: "Arc", frame_count: 30 },
+ { name: "Obsidian", frame_count: 18 },
+ ],
+ } as never);
+ vi.mocked(seedFirstRunSummaryChat).mockResolvedValue("chat-7" as never);
+ // The model must be SLOW for this to test anything. The bug was an effect
+ // tear-down racing an in-flight call; with an instantly-resolving mock the
+ // whole resolve finishes before React processes the state change and the
+ // race never happens, so the test passes against the broken code too.
+ const { summarizeFirstRunWithAi } = await import(
+ "@/lib/first-run/summarize-with-ai"
+ );
+ vi.mocked(summarizeFirstRunWithAi).mockImplementation(
+ () => new Promise((r) => setTimeout(() => r(null as never), 200)),
+ );
+ getOnboardingStatus.mockResolvedValue(
+ okStatus(
+ completedAgo((MIN_LEARNING_MS + LEARNING_WINDOW_CEILING_MS) / 2),
+ ) as never,
+ );
+
+ const { result } = renderHook(() => useLearningWindow());
+
+ await waitFor(() => expect(seedFirstRunSummaryChat).toHaveBeenCalled(), {
+ timeout: 8_000,
+ });
+ await waitFor(() => expect(result.current.phase).toBe("ready"));
+ expect(result.current.chatId).toBe("chat-7");
+ });
+});
diff --git a/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.ts b/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.ts
index dad58fdef..4e37d96ef 100644
--- a/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run/use-learning-window.ts
@@ -23,6 +23,7 @@ import {
markLearningDone,
markLearningEmpty,
markLearningReady,
+ markLearningWriting,
releaseLearningSeed,
readLearningWindow,
type FirstRunCapturedApp,
@@ -120,6 +121,16 @@ export function useLearningWindow(
const seedingRef = useRef(false);
const isLearning = state.phase === "learning";
+ /**
+ * Both phases the resolve effect must stay mounted for.
+ *
+ * `learning` flips to `writing` from inside `resolve`, so keying the effect
+ * on `isLearning` alone would tear it down mid-flight: cleanup sets
+ * `cancelled`, aborts the in-flight detail fetch, and the summary bails and
+ * hands the seed claim back. Keeping both phases truthy means the transition
+ * changes no dependency and the running resolve is left alone.
+ */
+ const isResolving = isLearning || state.phase === "writing";
const startedAt = state.startedAt;
// Countdown to the ceiling. Purely cosmetic — the window resolves on
@@ -134,12 +145,16 @@ export function useLearningWindow(
// Poll captured activity, resolve when there is enough to say something true.
useEffect(() => {
- if (!isLearning || !startedAt) return;
+ if (!isResolving || !startedAt) return;
let cancelled = false;
const controller = new AbortController();
const resolve = async () => {
+ // Already producing the summary. The interval keeps firing through
+ // `writing` so the effect is not torn down under the in-flight call, but
+ // there is nothing left to poll for.
+ if (seedingRef.current) return;
const activity = await fetchRecentActivity(startedAt, {
signal: controller.signal,
});
@@ -158,6 +173,12 @@ export function useLearningWindow(
if (aiRef.current.aiSettingsLoaded === false) return;
if (seedingRef.current || !claimLearningSeed()) return;
seedingRef.current = true;
+ // Leave `learning` the moment the evidence gate is satisfied, before the
+ // model call below. Everything after this point is producing the summary,
+ // not waiting for something to summarize, and the countdown must stop:
+ // the model can outlive the ceiling, and a spinner beside `0:00` reads as
+ // a hang rather than as work in progress.
+ setState(markLearningWriting());
// Re-fetch with detail now that we are committing to a summary.
const detailed =
@@ -256,7 +277,7 @@ export function useLearningWindow(
controller.abort();
clearInterval(timer);
};
- }, [isLearning, startedAt]);
+ }, [isResolving, startedAt]);
// Ceiling: settle honestly if evidence never arrived.
useEffect(() => {