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): always finish the learning handoff

Louis Beaumonte3587f56545d
diff --git a/apps/screenpipe-app-tauri/components/first-run/learning-banner.test.tsx b/apps/screenpipe-app-tauri/components/first-run/learning-banner.test.tsx
index f59f29c4e..bb86353e8 100644
--- a/apps/screenpipe-app-tauri/components/first-run/learning-banner.test.tsx
+++ b/apps/screenpipe-app-tauri/components/first-run/learning-banner.test.tsx
@@ -163,7 +163,8 @@ describe("first-run learning banner", () => {
expect(dismiss).toHaveBeenCalled();
});
- it("keeps every empty result out of the interface", () => {
+ it("ends a foreground empty result with useful setup choices", () => {
+ const dismiss = vi.fn();
for (const emptyReason of [
"not_recording",
"no_capture_in_range",
@@ -173,11 +174,35 @@ describe("first-run learning banner", () => {
"single_app_below_floor",
"unknown",
] as const) {
- mocks.view = view({ phase: "empty", emptyReason });
+ mocks.view = view({
+ phase: "empty",
+ emptyReason,
+ showProgress: true,
+ dismiss,
+ });
const rendered = render(<FirstRunLearningBanner />);
- expect(rendered.container).toBeEmptyDOMElement();
+ expect(screen.getByText("screenpipe is ready")).toBeInTheDocument();
+ expect(screen.getByTestId("first-run-next-steps")).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("first-run-open-summary"),
+ ).not.toBeInTheDocument();
rendered.unmount();
}
+
+ mocks.view = view({ phase: "empty", showProgress: true, dismiss });
+ render(<FirstRunLearningBanner />);
+ fireEvent.click(screen.getByRole("button", { name: "this is ready" }));
+ expect(dismiss).toHaveBeenCalled();
+ });
+
+ it("keeps an empty background retry out of the interface", () => {
+ mocks.view = view({
+ phase: "empty",
+ emptyReason: "below_frame_floor",
+ showProgress: false,
+ });
+ const rendered = render(<FirstRunLearningBanner />);
+ expect(rendered.container).toBeEmptyDOMElement();
});
it("keeps a late learning or writing retry in the background", () => {
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 d736dc5c5..6c380ee4f 100644
--- a/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx
+++ b/apps/screenpipe-app-tauri/components/first-run/learning-banner.tsx
@@ -121,6 +121,52 @@ export function FirstRunReadyPanel({
);
}
+export function FirstRunSetupReadyPanel({
+ onDismiss,
+ nextSteps,
+}: {
+ onDismiss: () => void;
+ nextSteps: React.ReactNode;
+}) {
+ return (
+ <div data-testid="first-run-setup-ready">
+ <div className="p-5">
+ <div className="flex items-center gap-2">
+ <span className="h-2 w-2 bg-phosphor-strong" aria-hidden="true" />
+ <span className="font-mono text-[9px] uppercase tracking-[0.2em] text-phosphor-strong">
+ setup · ready
+ </span>
+ </div>
+ <h2 className="mt-3 font-mono text-base font-semibold lowercase text-foreground">
+ screenpipe is ready
+ </h2>
+ <p className="mt-2 max-w-xl text-[11px] leading-relaxed text-muted-foreground">
+ there was not enough activity in this short setup window to write a
+ useful first summary. you can still enable your daily summary now.
+ </p>
+ </div>
+
+ {nextSteps}
+
+ <div className="flex items-center justify-between gap-4 border-t border-border px-4 py-3">
+ <p className="text-[10px] leading-relaxed text-muted-foreground">
+ these optional setups remain available from scheduled tasks and
+ connections.
+ </p>
+ <Button
+ size="sm"
+ variant="ghost"
+ className="h-7 shrink-0 px-2 text-[9px]"
+ data-testid="first-run-setup-complete"
+ onClick={onDismiss}
+ >
+ this is ready
+ </Button>
+ </div>
+ </div>
+ );
+}
+
/**
* First-run learning window.
*
@@ -136,14 +182,15 @@ export function FirstRunLearningBanner(
const { targets: handoffTargets, hint: handoffHint, askAgent } =
useAgentHandoff(phase === "ready");
- // Only show progress when setup just caused it, and only show a terminal
- // outcome when there is something useful to open. Empty is an internal
- // result/telemetry state, not a user task or an error they asked to inspect.
+ // Only show progress when setup just caused it. A foreground empty result is
+ // still a terminal onboarding state: hiding it also hid the daily-summary
+ // setup and made the two-minute card appear to vanish. Background retries
+ // remain quiet unless they produce a summary worth opening.
if (
phase !== "ready" &&
!(
showProgress &&
- (phase === "learning" || phase === "writing")
+ (phase === "learning" || phase === "writing" || phase === "empty")
)
) {
return fallback ? <>{fallback}</> : null;
@@ -169,7 +216,9 @@ export function FirstRunLearningBanner(
data-testid="first-run-learning-banner"
data-phase={phase}
className={`mx-auto mb-4 w-full border border-border bg-background ${
- phase === "ready" ? "max-w-3xl overflow-hidden" : "max-w-3xl p-4"
+ phase === "ready" || phase === "empty"
+ ? "max-w-3xl overflow-hidden"
+ : "max-w-3xl p-4"
}`}
>
{phase === "learning" && (
@@ -250,6 +299,13 @@ export function FirstRunLearningBanner(
nextSteps={<FirstRunNextSteps userToken={learningOptions.userToken} />}
/>
)}
+
+ {phase === "empty" && (
+ <FirstRunSetupReadyPanel
+ onDismiss={() => dismiss()}
+ nextSteps={<FirstRunNextSteps userToken={learningOptions.userToken} />}
+ />
+ )}
</section>
);
}
diff --git a/apps/screenpipe-app-tauri/e2e/specs/first-run-learning-window.spec.ts b/apps/screenpipe-app-tauri/e2e/specs/first-run-learning-window.spec.ts
index b59abe473..fb86cb551 100644
--- a/apps/screenpipe-app-tauri/e2e/specs/first-run-learning-window.spec.ts
+++ b/apps/screenpipe-app-tauri/e2e/specs/first-run-learning-window.spec.ts
@@ -18,12 +18,13 @@
// What this proves that unit tests cannot:
// 1. The banner mounts on Home — the surface setup now routes to — and its
// countdown is live rather than a frozen first render.
-// 2. An empty result settles durably but never becomes product UI. The real
-// engine reason remains in state/telemetry for diagnosis without making
-// an internal evidence threshold the user's problem.
+// 2. A foreground empty result settles durably into useful setup choices.
+// The real engine reason remains in state/telemetry without making the
+// internal evidence threshold the user's problem.
// 3. A late retry runs in the background and surfaces only if a summary is
// ready. Reopening hours later must not look like onboarding restarted.
-// 4. Silent terminal states stay silent across reloads.
+// 4. Foreground terminal choices survive reload until the user dismisses
+// them; background terminal states stay silent.
//
// The summary text and the seed-once rules are pure functions covered in
// lib/first-run/learning-window.test.ts. This spec drives the state machine
@@ -195,10 +196,11 @@ const learningState = (over: Record<string, unknown> = {}) => ({
expect(existsSync(filepath)).toBe(true);
});
- it("settles an empty engine result without putting it in the interface", async () => {
+ it("ends an empty foreground result on useful setup choices", async () => {
// Ceiling already elapsed, so the window must settle on this mount. With
// recording off the engine answers that it is not recording, and that
- // exact reason remains available for diagnosis without becoming a card.
+ // exact reason remains available for diagnosis while onboarding still
+ // reaches the daily-summary setup instead of disappearing.
await openHomeWith(
learningState({
startedAt: new Date(Date.now() - 10 * 60 * 1_000).toISOString(),
@@ -219,25 +221,36 @@ const learningState = (over: Record<string, unknown> = {}) => ({
timeoutMsg: "window never persisted a classified empty reason",
},
);
- expect(await bannerCount()).toBe(0);
+ expect(await bannerCount()).toBe(1);
+ expect(await bannerPhase()).toBe("empty");
const bodyText = (await browser.execute(
() => document.body.textContent ?? "",
)) as string;
- expect(bodyText).not.toContain("Nothing to summarize");
+ expect(bodyText).toContain("screenpipe is ready");
+ expect(bodyText).toContain("enable daily summary");
- const filepath = await saveScreenshot("first-run-empty-silent");
+ const filepath = await saveScreenshot("first-run-empty-ready");
expect(existsSync(filepath)).toBe(true);
});
- it("keeps the settled empty result silent across a reload", async () => {
+ it("keeps the setup choices across reload until the user dismisses them", async () => {
await showWindow({ Home: { page: null } });
await browser.switchToWindow("home");
await browser.execute(() => {
window.location.href = "/home?section=home";
});
await browser.pause(t(4_000));
- expect(await bannerCount()).toBe(0);
+ expect(await bannerCount()).toBe(1);
+ expect(await bannerPhase()).toBe("empty");
expect((await storedLearningState())?.phase).toBe("empty");
+
+ const done = await browser.$('[data-testid="first-run-setup-complete"]');
+ await done.click();
+ await browser.waitUntil(async () => (await bannerCount()) === 0, {
+ timeout: t(10_000),
+ timeoutMsg: "setup choices survived explicit dismissal",
+ });
+ expect((await storedLearningState())?.phase).toBe("done");
});
it("offers the summary once one is ready, then gets out of the way", async () => {
@@ -272,8 +285,20 @@ const learningState = (over: Record<string, unknown> = {}) => ({
// localStorage partition, so Home never saw it. Nothing is seeded here — the
// window has to appear from a real completion alone.
it("opens from a real setup completion, with nothing seeded", async () => {
+ // Simulate a user deleting ~/.screenpipe while WebView data survives. The
+ // old terminal lifecycle must not suppress a newly completed setup.
await browser.execute((key: string) => {
- window.localStorage.removeItem(key);
+ window.localStorage.setItem(
+ key,
+ JSON.stringify({
+ phase: "done",
+ startedAt: new Date(Date.now() - 10 * 60 * 1_000).toISOString(),
+ showProgress: true,
+ seededAt: null,
+ chatId: null,
+ emptyReason: null,
+ }),
+ );
}, LEARNING_STORAGE_KEY);
// Re-complete setup through the real command, exactly as the last slide
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 11ee7dc4a..86a350005 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
@@ -390,9 +390,11 @@ describe("window lifecycle", () => {
const stale = new Date(
Date.now() - LEARNING_WINDOW_CEILING_MS - 1_000,
).toISOString();
- beginLearningWindow(stale);
+ beginLearningWindow(stale, true);
// A reload after the ceiling must not show an expired countdown.
- expect(readLearningWindow().phase).toBe("empty");
+ const settled = readLearningWindow();
+ expect(settled.phase).toBe("empty");
+ expect(settled.showProgress).toBe(true);
});
it("never rehydrates captured apps, which would show stale evidence", () => {
@@ -604,6 +606,7 @@ describe("a window that expired while nothing was mounted", () => {
seededAt: null,
chatId: null,
emptyReason: null,
+ showProgress: true,
}),
);
};
@@ -621,6 +624,7 @@ describe("a window that expired while nothing was mounted", () => {
// state of its own.
expect(state.emptyReason).toBe("unknown");
expect(state.pendingEmptyReport).toBe(true);
+ expect(state.showProgress).toBe(true);
});
it("flags the settle rather than inventing a new diagnostic reason", () => {
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 6fcade8bb..e8e6811ac 100644
--- a/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts
+++ b/apps/screenpipe-app-tauri/lib/first-run/learning-window.ts
@@ -574,6 +574,7 @@ function normalize(value: unknown): FirstRunLearningState {
...EMPTY_STATE,
phase: "empty",
startedAt,
+ showProgress: state.showProgress === true,
// Deliberately still `unknown`, not a new reason. The hook re-derives
// the real engine reason from `pendingEmptyReport` below, exactly as
// the ceiling effect would have, so diagnostics keep their fidelity.
@@ -594,7 +595,7 @@ function normalize(value: unknown): FirstRunLearningState {
return {
phase: "ready",
startedAt,
- showProgress: false,
+ showProgress: state.showProgress === true,
seededAt: typeof state.seededAt === "string" ? state.seededAt : null,
chatId: state.chatId,
emptyReason: null,
@@ -606,6 +607,7 @@ function normalize(value: unknown): FirstRunLearningState {
...EMPTY_STATE,
phase: "empty",
startedAt,
+ showProgress: state.showProgress === true,
emptyReason: "unknown",
// NOT flagged for reporting, unlike the expired-learning path above. A
// `writing` window that lost its process may still have an in-flight
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 71013bc42..90881eed4 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
@@ -49,6 +49,7 @@ import {
LEARNING_WINDOW_CEILING_MS,
LEARNING_WINDOW_GRACE_MS,
MIN_LEARNING_MS,
+ beginLearningWindow,
markLearningDone,
readLearningWindow,
resetLearningWindow,
@@ -171,6 +172,20 @@ describe("useLearningWindow opening", () => {
expect(result.current.phase).toBe("idle");
expect(startedEvents()).toHaveLength(0);
});
+
+ it("starts a fresh window after setup is completed again with stale webview state", async () => {
+ beginLearningWindow(completedAgo(10 * 60_000));
+ markLearningDone();
+ const completedAt = completedAgo(30_000);
+ getOnboardingStatus.mockResolvedValue(okStatus(completedAt));
+
+ const { result } = renderHook(() => useLearningWindow());
+
+ await waitFor(() => expect(result.current.phase).toBe("learning"));
+ expect(result.current.startedAt).toBe(completedAt);
+ expect(result.current.showProgress).toBe(true);
+ expect(startedEvents()).toHaveLength(1);
+ });
});
describe("useLearningWindow settings race", () => {
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 b4e65fe8f..c7c8a4618 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
@@ -93,7 +93,7 @@ export function useLearningWindow(
// cutoff stays exactly right because `completedAt` IS the moment setup
// ended — everything summarized was captured after it.
useEffect(() => {
- if (state.phase !== "idle") return;
+ if (state.phase === "learning" || state.phase === "writing") return;
let cancelled = false;
void (async () => {
try {
@@ -101,7 +101,21 @@ export function useLearningWindow(
if (cancelled || result.status !== "ok") return;
const opening = learningWindowOpening(result.data.completedAt);
if (opening.kind === "none") return;
- if (readLearningWindow().phase !== "idle") return;
+ const stored = readLearningWindow();
+ const completedMs = Date.parse(result.data.completedAt ?? "");
+ const startedMs = Date.parse(stored.startedAt ?? "");
+ const isFreshCompletion =
+ stored.phase === "idle" ||
+ !Number.isFinite(startedMs) ||
+ (Number.isFinite(completedMs) && completedMs > startedMs);
+ if (!isFreshCompletion) return;
+
+ // `~/.screenpipe` is not the WebView storage partition. A manual data
+ // reset can therefore leave an old empty/done result in localStorage
+ // even though setup just wrote a brand-new completion. The fresh
+ // backend timestamp is authoritative: retire the stale lifecycle and
+ // start this setup's learning window.
+ if (stored.phase !== "idle") resetLearningWindow();
// The only signal that a window ever opened. Without it an absent
// outcome is indistinguishable from a window that never started, and
// "never started" was by far the most common outcome.