Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(web): recover every unaccepted chat submission

Bingxi Zhao (Frank)0e6761bc35aa
diff --git a/deeptutor/core/turn_request.py b/deeptutor/core/turn_request.py
index 3b63751f5..af1f95582 100644
--- a/deeptutor/core/turn_request.py
+++ b/deeptutor/core/turn_request.py
@@ -121,6 +121,10 @@ class TurnRequest(BaseModel):
model_config = ConfigDict(extra="forbid")
content: str
+ # Browser-minted causal identity for a newly submitted user row. A retry
+ # can then distinguish its own persisted row from identical text sent in
+ # another tab without relying on clocks or stale transcript baselines.
+ client_submission_id: str | None = Field(default=None, min_length=1, max_length=100)
capability: str | None = "chat"
session_id: str | None = None
tools: list[str] | None = None
diff --git a/deeptutor/services/session/_turn_runtime_shared.py b/deeptutor/services/session/_turn_runtime_shared.py
index fe0b75a77..0f7b4ca12 100644
--- a/deeptutor/services/session/_turn_runtime_shared.py
+++ b/deeptutor/services/session/_turn_runtime_shared.py
@@ -951,7 +951,11 @@ def _request_snapshot_metadata(
snapshot["timedMediaId"] = timed_media_id
if llm_selection:
snapshot["llmSelection"] = llm_selection
- return {"request_snapshot": snapshot}
+ metadata: dict[str, Any] = {"request_snapshot": snapshot}
+ client_submission_id = payload.get("client_submission_id")
+ if isinstance(client_submission_id, str) and client_submission_id:
+ metadata["client_submission_id"] = client_submission_id
+ return metadata
def _format_question_bank_entry(entry: dict[str, Any]) -> str:
diff --git a/tests/api/test_unified_ws_turn_runtime.py b/tests/api/test_unified_ws_turn_runtime.py
index 517fcf819..397cd6403 100644
--- a/tests/api/test_unified_ws_turn_runtime.py
+++ b/tests/api/test_unified_ws_turn_runtime.py
@@ -194,6 +194,7 @@ async def test_turn_runtime_replays_events_and_materializes_messages(
{
"type": "start_turn",
"content": "hello, i'm frank",
+ "client_submission_id": "browser-submission-123",
"session_id": None,
"capability": None,
"tools": [],
@@ -237,6 +238,7 @@ async def test_turn_runtime_replays_events_and_materializes_messages(
user_row, assistant_row = detail["messages"]
assert done_event["metadata"]["user_message_id"] == user_row["id"]
assert done_event["metadata"]["assistant_message_id"] == assistant_row["id"]
+ assert user_row["metadata"]["client_submission_id"] == "browser-submission-123"
assert detail["messages"][0]["metadata"]["request_snapshot"]["persona"] == "socratic"
assert detail["messages"][0]["metadata"]["request_snapshot"]["memoryReferences"] == ["summary"]
assert detail["messages"][0]["metadata"]["request_snapshot"]["bookReferences"] == [
diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.ts
index 66483a038..f41835930 100644
--- a/web/contracts/generated/api.ts
+++ b/web/contracts/generated/api.ts
@@ -15094,6 +15094,11 @@ export interface components {
* @default false
*/
readonly capability_once: boolean;
+ /**
+ * Client Submission Id
+ * @default null
+ */
+ readonly client_submission_id: string | null;
/** Config */
readonly config?: {
readonly [key: string]: unknown;
diff --git a/web/contracts/generated/turn-protocol.ts b/web/contracts/generated/turn-protocol.ts
index 6f2ae9767..08b0ccb61 100644
--- a/web/contracts/generated/turn-protocol.ts
+++ b/web/contracts/generated/turn-protocol.ts
@@ -30,6 +30,7 @@ export type PageIds = string[];
export type BookReferences = BookReference[];
export type Capability = string | null;
export type CapabilityOnce = boolean;
+export type ClientSubmissionId = string | null;
export type ConsultPartnerId = string | null;
export type Content = string;
export type CourseId = string | null;
@@ -279,6 +280,7 @@ export interface StartTurnCommand {
book_references?: BookReferences;
capability?: Capability;
capability_once?: CapabilityOnce;
+ client_submission_id?: ClientSubmissionId;
config?: Config;
consult_partner_id?: ConsultPartnerId;
content: Content;
diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.json
index be86a7116..d7923e8ee 100644
--- a/web/contracts/schema/openapi.json
+++ b/web/contracts/schema/openapi.json
@@ -10144,6 +10144,20 @@
"title": "Capability Once",
"type": "boolean"
},
+ "client_submission_id": {
+ "anyOf": [
+ {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Client Submission Id"
+ },
"config": {
"additionalProperties": true,
"title": "Config",
diff --git a/web/contracts/schema/turn-protocol.json b/web/contracts/schema/turn-protocol.json
index 89db7f480..540b7abbf 100644
--- a/web/contracts/schema/turn-protocol.json
+++ b/web/contracts/schema/turn-protocol.json
@@ -856,6 +856,20 @@
"title": "Capability Once",
"type": "boolean"
},
+ "client_submission_id": {
+ "anyOf": [
+ {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Client Submission Id"
+ },
"config": {
"additionalProperties": true,
"title": "Config",
diff --git a/web/features/chat/ChatStateAdapter.tsx b/web/features/chat/ChatStateAdapter.tsx
index 9a9c5fc79..3bb37970a 100644
--- a/web/features/chat/ChatStateAdapter.tsx
+++ b/web/features/chat/ChatStateAdapter.tsx
@@ -3,10 +3,12 @@
import { activeWorkspaceId } from "@/lib/workspace-scope";
import {
clearFailedSubmission,
- readFailedSubmission,
+ readFailedSubmissions,
serverContainsFailedSubmission,
storeFailedSubmission,
+ type FailedSubmissionRecord,
} from "@/lib/failed-submissions";
+import { randomUuid } from "@/lib/random-uuid";
import React, {
createContext,
@@ -125,6 +127,8 @@ export interface SendMessageOptions {
displayUserMessage?: boolean;
persistUserMessage?: boolean;
requestSnapshotOverride?: MessageRequestSnapshot;
+ /** Internal resend identity: reuse the original server correlation token. */
+ retrySubmissionId?: string;
bookReferences?: BookReferencePayload[];
readingReferences?: ReadingReferencePayload[];
/** Edit-branching: when set, the new user message is inserted as a
@@ -311,6 +315,7 @@ export interface MessageItem {
* "unsent" marker; its requestSnapshot drives the retry. */
failedSubmission?: boolean;
failedSubmissionNeedsReview?: boolean;
+ failedSubmissionId?: string;
}
interface SessionEntry extends Omit<ChatState, "sessionKey"> {
@@ -380,6 +385,7 @@ type Action =
attachments?: MessageAttachment[];
requestSnapshot?: MessageRequestSnapshot;
parentMessageId?: number | null;
+ failedSubmissionId?: string;
}
| { type: "POP_LAST_ASSISTANT"; key: string }
| { type: "RESTORE_ASSISTANT"; key: string; message: MessageItem }
@@ -437,7 +443,7 @@ type Action =
key?: string;
configuration: SessionConfiguration;
}
- | { type: "ENSURE_DRAFT_SESSION"; key: string }
+ | { type: "ENSURE_DRAFT_SESSION"; key: string; failedRecords?: FailedSubmissionRecord[] }
| {
type: "SET_SELECTED_BRANCH";
key: string;
@@ -488,6 +494,40 @@ function createSessionEntry(
};
}
+function draftFailedSubmissionKey(): string {
+ return `draft:${activeWorkspaceId() || "general"}`;
+}
+
+function restoredFailedMessage(
+ record: FailedSubmissionRecord,
+ parentMessageId: number | null,
+): MessageItem {
+ const stored = record.requestSnapshot;
+ const base: Record<string, unknown> =
+ typeof stored === "object" && stored !== null
+ ? (stored as Record<string, unknown>)
+ : {};
+ const snapshot = {
+ ...base,
+ content: record.content,
+ enabledTools: Array.isArray(base.enabledTools) ? base.enabledTools : [],
+ knowledgeBases: Array.isArray(base.knowledgeBases) ? base.knowledgeBases : [],
+ language: typeof base.language === "string" ? base.language : "en",
+ } as MessageRequestSnapshot;
+ return {
+ id: nextOptimisticId(),
+ role: "user",
+ content: record.content,
+ capability: record.capability,
+ parentMessageId,
+ ...(snapshot.attachments?.length ? { attachments: snapshot.attachments } : {}),
+ requestSnapshot: snapshot,
+ failedSubmission: true,
+ failedSubmissionNeedsReview: record.retryRequiresReview,
+ failedSubmissionId: record.submissionId,
+ };
+}
+
function ensureSelectedSession(state: ProviderState): SessionEntry {
if (state.selectedKey && state.sessions[state.selectedKey]) {
return state.sessions[state.selectedKey];
@@ -707,6 +747,9 @@ function reducer(state: ProviderState, action: Action): ProviderState {
...(action.requestSnapshot
? { requestSnapshot: action.requestSnapshot }
: {}),
+ ...(action.failedSubmissionId
+ ? { failedSubmissionId: action.failedSubmissionId }
+ : {}),
},
],
selectedBranches: selectChildBranch(
@@ -1350,9 +1393,26 @@ function reducer(state: ProviderState, action: Action): ProviderState {
// The check belongs here rather than in the caller because a mount effect
// only ever sees the state of the render that created it, which is stale
// the moment anything else has dispatched.
- case "ENSURE_DRAFT_SESSION":
+ case "ENSURE_DRAFT_SESSION": {
if (state.selectedKey && state.sessions[state.selectedKey]) return state;
- return selectFreshDraft(state, action.key);
+ const fresh = selectFreshDraft(state, action.key);
+ if (!action.failedRecords?.length) return fresh;
+ const messages: MessageItem[] = [];
+ for (const record of action.failedRecords) {
+ messages.push(restoredFailedMessage(record, messages.at(-1)?.id ?? null));
+ }
+ return {
+ ...fresh,
+ sessions: {
+ ...fresh.sessions,
+ [action.key]: {
+ ...fresh.sessions[action.key],
+ messages,
+ status: "failed",
+ },
+ },
+ };
+ }
default:
return state;
}
@@ -1697,6 +1757,9 @@ export function ChatStateAdapterProvider({
// or ``nothing_to_regenerate``). Keyed by session entry key.
const pendingRegenerateRef = useRef<Map<string, MessageItem>>(new Map());
const pendingResendRef = useRef<Map<string, MessageItem>>(new Map());
+ const pendingSubmissionIdsRef = useRef<
+ Map<string, { storageKey: string; submissionId: string }>
+ >(new Map());
const resolvingResendRef = useRef<Set<string>>(new Set());
const traceCacheRef = useRef<TraceCache>(new TraceCache());
const traceRequestsRef = useRef<Map<string, AbortController>>(new Map());
@@ -1825,6 +1888,11 @@ export function ChatStateAdapterProvider({
event.turn_id ||
null;
if (sessionId) {
+ const pendingSubmission = pendingSubmissionIdsRef.current.get(effectiveKey);
+ if (pendingSubmission) {
+ pendingSubmissionIdsRef.current.delete(effectiveKey);
+ pendingSubmissionIdsRef.current.set(sessionId, pendingSubmission);
+ }
dispatch({
type: "BIND_SERVER_SESSION",
key: effectiveKey,
@@ -1885,9 +1953,16 @@ export function ChatStateAdapterProvider({
(event.metadata as { status?: string } | undefined)?.status ||
"completed",
);
- // The server finished this turn, so it owns the transcript from
- // here — any locally stored "unproven submission" for it is stale.
- clearFailedSubmission(effectiveKey);
+ // DONE identifies a persisted user row. Clear only this submission;
+ // earlier failed sends in the same conversation remain recoverable.
+ const pendingSubmission = pendingSubmissionIdsRef.current.get(effectiveKey);
+ const doneUserMessageId = (event.metadata as {
+ user_message_id?: number | string | null;
+ } | undefined)?.user_message_id;
+ if (pendingSubmission && doneUserMessageId != null) {
+ clearFailedSubmission(pendingSubmission.storageKey, pendingSubmission.submissionId);
+ }
+ pendingSubmissionIdsRef.current.delete(effectiveKey);
dispatch({
type: "STREAM_END",
key: effectiveKey,
@@ -1963,22 +2038,27 @@ export function ChatStateAdapterProvider({
}
return;
}
- dispatch({ type: "STREAM_EVENT", key: effectiveKey, event });
- if (
- event.type === "error" &&
- Boolean(
- (event.metadata as { turn_terminal?: boolean } | undefined)
- ?.turn_terminal,
- )
- ) {
- const reason = String(
- (event.metadata as { reason?: string } | undefined)?.reason || "",
- );
+ const terminalError = event.type === "error" &&
+ Boolean((event.metadata as { turn_terminal?: boolean } | undefined)?.turn_terminal);
+ const reason = terminalError
+ ? String((event.metadata as { reason?: string } | undefined)?.reason || "")
+ : "";
+ const submissionRejected = new Set([
+ "start_turn_rejected", "invalid_command", "invalid_json",
+ "unsupported_protocol_version", "unknown_message_type",
+ ]).has(reason);
+ // An admission rejection is not an assistant reply. Keep the
+ // placeholder empty so STREAM_END can flag the optimistic user row.
+ if (!submissionRejected) {
+ dispatch({ type: "STREAM_EVENT", key: effectiveKey, event });
+ }
+ if (terminalError) {
// Pre-flight regenerate rejections never mutate server state, so we
// roll back the optimistic POP_LAST_ASSISTANT/STREAM_START placeholder
// to keep the transcript in sync with the server.
if (
reason === "regenerate_busy" ||
+ reason === "regenerate_rejected" ||
reason === "nothing_to_regenerate" ||
reason === "start_turn_rejected"
) {
@@ -1995,10 +2075,11 @@ export function ChatStateAdapterProvider({
}
pendingRegenerateRef.current.delete(effectiveKey);
pendingResendRef.current.delete(effectiveKey);
- // A terminal error is server-generated: the turn was accepted, so
- // the stored submission record (if any) must not resurrect the text
- // as "unsent" after a reload (#1594).
- clearFailedSubmission(effectiveKey);
+ // start_turn_rejected happens before the server creates a turn or
+ // user row. Other terminal errors are not causal proof that the user
+ // row was persisted either; transcript reconciliation uses the
+ // client_submission_id stored on that row.
+ pendingSubmissionIdsRef.current.delete(effectiveKey);
const status = String(
(event.metadata as { status?: string } | undefined)?.status ||
"failed",
@@ -2008,6 +2089,7 @@ export function ChatStateAdapterProvider({
key: effectiveKey,
status: status as SessionRuntimeStatus,
turnId: event.turn_id || null,
+ submissionFailed: submissionRejected,
});
}
},
@@ -2295,59 +2377,25 @@ export function ChatStateAdapterProvider({
Date.now(),
readStoredChatResponseTimeout() * 1000,
);
- // Restore a submission the server never accepted (#1594). The record
- // only survives when no terminal evidence ever arrived. Compare server
- // row identities recorded before submission: a previous turn may have
- // identical text, and must not erase this new unsent message.
+ // Restore every pending submission. A matching client_submission_id on
+ // a persisted user row is the only evidence that this particular send
+ // was accepted; equal text from another tab is not enough.
let restoredMessages = messages;
let restoredStatus = loadedStatus;
if (!options?.revalidate && loadedStatus !== "running") {
- const failedRecord = readFailedSubmission(key);
- if (failedRecord) {
- if (serverContainsFailedSubmission(messages, failedRecord)) {
- clearFailedSubmission(key);
+ for (const failedRecord of readFailedSubmissions(key)) {
+ if (serverContainsFailedSubmission(session.messages ?? [], failedRecord)) {
+ clearFailedSubmission(key, failedRecord.submissionId);
} else {
- const stored = failedRecord.requestSnapshot;
- const base: Record<string, unknown> =
- typeof stored === "object" && stored !== null
- ? (stored as Record<string, unknown>)
- : {};
- // The resend path replays this snapshot verbatim, so restore
- // the fields it requires even if the stored record predates
- // them; ``content`` is authoritative from the record itself.
- const snapshot = {
- ...base,
- content: failedRecord.content,
- enabledTools: Array.isArray(base.enabledTools)
- ? base.enabledTools
- : [],
- knowledgeBases: Array.isArray(base.knowledgeBases)
- ? base.knowledgeBases
- : [],
- language: typeof base.language === "string" ? base.language : "en",
- } as MessageRequestSnapshot;
restoredMessages = [
- ...messages,
- {
- id: nextOptimisticId(),
- role: "user" as const,
- content: failedRecord.content,
- capability: failedRecord.capability,
- parentMessageId: tipMessageId(
- buildVisiblePath(
- messages,
- normalizeSelectedBranches(
- session.preferences?.selected_branches,
- ),
- ).messages,
- ),
- ...(snapshot.attachments?.length
- ? { attachments: snapshot.attachments }
- : {}),
- requestSnapshot: snapshot,
- failedSubmission: true,
- failedSubmissionNeedsReview: failedRecord.retryRequiresReview,
- },
+ ...restoredMessages,
+ restoredFailedMessage(
+ failedRecord,
+ tipMessageId(buildVisiblePath(
+ restoredMessages,
+ normalizeSelectedBranches(session.preferences?.selected_branches),
+ ).messages),
+ ),
];
restoredStatus = "failed";
}
@@ -2472,8 +2520,8 @@ export function ChatStateAdapterProvider({
}, []);
// URL is now the source of truth for session loading.
- // Chat pages load sessions based on URL params; no sessionStorage restore needed.
- // Initialize a draft session so the provider always has a selected key.
+ // Initialize a draft session, restoring first-message failures before a
+ // server session ID exists. A page with a URL-selected session still wins.
//
// React flushes a child's effects before its parent's, so any page under
// this provider has already picked and configured its session by the time
@@ -2482,7 +2530,11 @@ export function ChatStateAdapterProvider({
// reducer decides on live state; this only supplies the key it may need.
useEffect(() => {
if (typeof window === "undefined") return;
- dispatch({ type: "ENSURE_DRAFT_SESSION", key: makeDraftKey() });
+ dispatch({
+ type: "ENSURE_DRAFT_SESSION",
+ key: makeDraftKey(),
+ failedRecords: readFailedSubmissions(draftFailedSubmissionKey()),
+ });
}, []); // eslint-disable-line react-hooks/exhaustive-deps
// Idle recovery: if a streaming session receives no events for the
@@ -2737,6 +2789,13 @@ export function ChatStateAdapterProvider({
: tipId !== null && tipId > 0
? tipId
: undefined;
+ const trackNewSubmission =
+ options?.displayUserMessage !== false &&
+ !options?.masteryAnswer &&
+ !options?.masterySkip &&
+ content.trim() !== "";
+ const submissionId = options?.retrySubmissionId ??
+ (trackNewSubmission ? randomUuid() : undefined);
if (options?.displayUserMessage !== false) {
dispatch({
type: "ADD_USER_MSG",
@@ -2746,6 +2805,7 @@ export function ChatStateAdapterProvider({
attachments: effectiveAttachments,
requestSnapshot,
parentMessageId: localParentId,
+ failedSubmissionId: submissionId,
});
}
dispatch({ type: "STREAM_START", key, startedAt: Date.now() / 1000 });
@@ -2765,38 +2825,28 @@ export function ChatStateAdapterProvider({
legacyPersistUserMessage === false
? false
: undefined;
- // Pessimistic record (#1594): remember this submission locally until
- // evidence arrives that the server took the turn over (``done``, a
- // terminal error, or a cancel). If none ever does — the socket never
- // connected — a reload can restore the text as clearly unsent.
- // Replays/resends (``displayUserMessage: false``) and card answers
- // keep the record of the row they replay rather than adding one.
- if (
- session.sessionId &&
- options?.displayUserMessage !== false &&
- !options?.masteryAnswer &&
- !options?.masterySkip &&
- content.trim() !== ""
- ) {
- storeFailedSubmission(session.sessionId, {
+ // Persist before attempting the socket, including a first turn that
+ // has no server session yet. Replays reuse their original identity.
+ const submissionStorageKey = session.sessionId ?? draftFailedSubmissionKey();
+ if (trackNewSubmission && submissionId) {
+ storeFailedSubmission(submissionStorageKey, {
content,
capability: effectiveCapability,
requestSnapshot,
- priorMatchingUserIds: session.messages
- .filter(
- (message) =>
- message.role === "user" &&
- message.content === content &&
- message.id != null &&
- (typeof message.id === "string" || message.id > 0),
- )
- .map((message) => String(message.id)),
+ submissionId,
+ });
+ }
+ if (submissionId) {
+ pendingSubmissionIdsRef.current.set(key, {
+ storageKey: submissionStorageKey,
+ submissionId,
});
}
return sendThroughRunner(
key,
buildStartTurnInput({
content,
+ clientSubmissionId: submissionId,
tools: effectiveTools,
capability: effectiveCapability,
workspaceMode: effectiveWorkspaceMode ?? "",
@@ -2894,7 +2944,11 @@ export function ChatStateAdapterProvider({
if (session.isStreaming) {
// The user aborted on purpose — do not resurrect this submission as
// "unsent" after the next reload (#1594).
- if (session.sessionId) clearFailedSubmission(session.sessionId);
+ const pendingSubmission = pendingSubmissionIdsRef.current.get(key);
+ if (pendingSubmission) {
+ clearFailedSubmission(pendingSubmission.storageKey, pendingSubmission.submissionId);
+ pendingSubmissionIdsRef.current.delete(key);
+ }
dispatch({ type: "STREAM_END", key, status: "cancelled" });
}
}, []);
@@ -3022,6 +3076,7 @@ export function ChatStateAdapterProvider({
{
displayUserMessage: false,
requestSnapshotOverride: snapshot,
+ retrySubmissionId: liveLastUser.failedSubmissionId,
parentMessageId:
typeof liveLastUser.parentMessageId === "number" &&
liveLastUser.parentMessageId <= 0
diff --git a/web/features/chat/controllers/buildStartTurnInput.ts b/web/features/chat/controllers/buildStartTurnInput.ts
index d1807fbf1..19b76b00d 100644
--- a/web/features/chat/controllers/buildStartTurnInput.ts
+++ b/web/features/chat/controllers/buildStartTurnInput.ts
@@ -70,6 +70,7 @@ export function buildStartTurnInput(input: StartTurnInput): StartTurnCommand {
return buildStartTurn({
...(input.workspaceId !== undefined ? { workspace_id: input.workspaceId } : {}),
content: input.content,
+ ...(input.clientSubmissionId ? { client_submission_id: input.clientSubmissionId } : {}),
capability: input.capability === undefined ? "chat" : input.capability,
session_id: input.sessionId ?? null,
tools: input.tools ?? null,
diff --git a/web/features/chat/model/start-turn.ts b/web/features/chat/model/start-turn.ts
index 9ed142ad9..ebe121d93 100644
--- a/web/features/chat/model/start-turn.ts
+++ b/web/features/chat/model/start-turn.ts
@@ -14,6 +14,7 @@ import type {
export interface StartTurnInput {
workspaceId?: string | null;
content: string;
+ clientSubmissionId?: string | null;
capability?: string | null;
sessionId?: string | null;
tools?: string[] | null;
diff --git a/web/lib/failed-submissions.ts b/web/lib/failed-submissions.ts
index 691022201..6dddaf89c 100644
--- a/web/lib/failed-submissions.ts
+++ b/web/lib/failed-submissions.ts
@@ -1,24 +1,9 @@
-/**
- * Locally persisted failed chat submissions (issue #1594).
- *
- * When a submission never reaches the server (the WebSocket could not
- * connect), the optimistic user row exists only in memory — a reload wiped
- * both the text and any sign it failed. These helpers keep the last failed
- * submission of each session in local storage so the transcript can be
- * reopened with the text recoverable and marked unsent.
- *
- * A record is written pessimistically when a fresh turn is submitted, and
- * removed by any evidence the server took the turn over (a terminal event,
- * ``done``, or a user cancel). Whatever survives is therefore a submission
- * the client cannot prove the server ever accepted.
- */
+/** Locally persisted chat submissions whose acceptance has not been proved. */
import { browserStorage } from "@/shared/storage";
+import { randomUuid } from "@/lib/random-uuid";
-/** The request snapshot replayed by the resend path. Opaque here on
- * purpose: at runtime it is a full ``MessageRequestSnapshot``, but typing
- * it would point ``lib/`` at ``features/``. The chat adapter casts it
- * back on the way out. */
+/** Kept opaque here so lib/ does not depend on features/. */
export type FailedSubmissionSnapshot = unknown;
export interface FailedSubmissionRecord {
@@ -26,7 +11,9 @@ export interface FailedSubmissionRecord {
capability: string;
requestSnapshot: FailedSubmissionSnapshot;
savedAt: number;
- /** Server user rows with this text before this submission was attempted. */
+ /** Also sent to the server and stored on its user row. */
+ submissionId?: string;
+ /** Legacy records had only a same-text baseline, which is not causal proof. */
priorMatchingUserIds?: string[];
/** The text survived, but its request context could not be stored. */
retryRequiresReview?: boolean;
@@ -34,34 +21,38 @@ export interface FailedSubmissionRecord {
const STORAGE_KEY = "deeptutor.failedSubmissions";
const FALLBACK_KEY_PREFIX = `${STORAGE_KEY}.fallback.`;
-/** Records older than this are stale transcript history, not a pending retry. */
const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
function isRecord(value: unknown): value is FailedSubmissionRecord {
if (!value || typeof value !== "object") return false;
const record = value as Partial<FailedSubmissionRecord>;
- return (
- typeof record.content === "string" &&
+ return typeof record.content === "string" &&
record.content.trim() !== "" &&
Boolean(record.requestSnapshot) &&
- typeof record.savedAt === "number"
- );
+ typeof record.savedAt === "number";
+}
+
+function asRecords(value: unknown): FailedSubmissionRecord[] {
+ // Accept the single-record shape used before this fix.
+ const records = isRecord(value) ? [value] :
+ (Array.isArray(value) ? value.filter(isRecord) : []);
+ // A pre-ID record has no causal server identity. Preserve its text and
+ // require review before resend rather than matching another tab's row.
+ return records.map((record) => record.submissionId
+ ? record
+ : { ...record, submissionId: `legacy:${record.savedAt}`, retryRequiresReview: true });
}
-function readAll(): Record<string, FailedSubmissionRecord> {
+function readAll(): Record<string, FailedSubmissionRecord[]> {
if (typeof window === "undefined") return {};
try {
const raw = browserStorage.readRaw("local", STORAGE_KEY);
- if (!raw) return {};
- const parsed: unknown = JSON.parse(raw);
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
- return {};
- }
- const out: Record<string, FailedSubmissionRecord> = {};
- for (const [sessionId, value] of Object.entries(
- parsed as Record<string, unknown>,
- )) {
- if (sessionId && isRecord(value)) out[sessionId] = value;
+ const parsed: unknown = raw ? JSON.parse(raw) : {};
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+ const out: Record<string, FailedSubmissionRecord[]> = {};
+ for (const [sessionId, value] of Object.entries(parsed)) {
+ const records = asRecords(value);
+ if (sessionId && records.length) out[sessionId] = records;
}
return out;
} catch {
@@ -73,105 +64,141 @@ function fallbackKey(sessionId: string): string {
return `${FALLBACK_KEY_PREFIX}${encodeURIComponent(sessionId)}`;
}
-function writeAll(records: Record<string, FailedSubmissionRecord>): boolean {
+function writeAll(records: Record<string, FailedSubmissionRecord[]>): boolean {
if (typeof window === "undefined") return false;
return browserStorage.writeRaw("local", STORAGE_KEY, JSON.stringify(records));
}
-/** Only a *new* server row proves this submission was accepted. Earlier turns
- * can have identical text, so comparing the last user's content is unsafe. */
+/** A matching server-issued submission ID is the only proof of acceptance.
+ * Another tab can submit the same text after this tab's last refresh. */
export function serverContainsFailedSubmission(
- messages: readonly { id?: number | string; role: string; content: string }[],
+ messages: readonly {
+ id?: number | string;
+ role: string;
+ content: string;
+ metadata?: Record<string, unknown>;
+ }[],
record: FailedSubmissionRecord,
): boolean {
- if (!record.priorMatchingUserIds) return false;
- const prior = new Set(record.priorMatchingUserIds);
- return messages.some(
- (message) =>
- message.role === "user" &&
- message.content === record.content &&
- message.id != null &&
- !prior.has(String(message.id)),
+ return Boolean(record.submissionId) && messages.some(
+ (message) => message.role === "user" &&
+ message.metadata?.client_submission_id === record.submissionId,
);
}
-/** Remember ``submission`` as the latest unproven submission of a session. */
+/** Preserve every pending message in a session, including successive failures. */
export function storeFailedSubmission(
sessionId: string,
submission: {
content: string;
capability?: string | null;
requestSnapshot: FailedSubmissionSnapshot;
+ submissionId?: string;
priorMatchingUserIds?: string[];
},
-): void {
- if (!sessionId || submission.content.trim() === "") return;
+): string | null {
+ if (!sessionId || submission.content.trim() === "") return null;
+ const submissionId = submission.submissionId ?? randomUuid();
const records = readAll();
const now = Date.now();
- for (const [key, record] of Object.entries(records)) {
- if (now - record.savedAt > MAX_AGE_MS) delete records[key];
+ for (const [key, entries] of Object.entries(records)) {
+ const fresh = entries.filter((record) => now - record.savedAt <= MAX_AGE_MS);
+ if (fresh.length) records[key] = fresh;
+ else delete records[key];
}
- records[sessionId] = {
+ const current = readFailedSubmissions(sessionId);
+ const next = current.filter((record) => record.submissionId !== submissionId);
+ next.push({
content: submission.content,
capability: submission.capability ?? "",
requestSnapshot: submission.requestSnapshot,
savedAt: now,
+ submissionId,
priorMatchingUserIds: submission.priorMatchingUserIds ?? [],
- };
+ });
+ records[sessionId] = next;
if (writeAll(records)) {
browserStorage.removeRaw("session", fallbackKey(sessionId));
- return;
+ return submissionId;
}
- // A base64 attachment can exceed localStorage's quota. sessionStorage is
- // independent and survives a reload in this tab, so try the full request
- // there before falling back to the text alone.
- const fullRecord = records[sessionId];
- if (browserStorage.writeRaw("session", fallbackKey(sessionId), JSON.stringify(fullRecord))) {
- return;
+ // Large attachments may exhaust one storage area. Keep the complete
+ // request in the other area before dropping to text-only snapshots.
+ if (browserStorage.writeRaw("session", fallbackKey(sessionId), JSON.stringify(next))) {
+ return submissionId;
+ }
+ const textOnly = next.map((record): FailedSubmissionRecord => {
+ const snapshot = record.requestSnapshot as Record<string, unknown> | null;
+ return {
+ ...record,
+ requestSnapshot: {
+ content: record.content,
+ capability: record.capability,
+ language: typeof snapshot?.language === "string" ? snapshot.language : "en",
+ enabledTools: [],
+ knowledgeBases: [],
+ },
+ retryRequiresReview: true,
+ };
+ });
+ if (browserStorage.writeRaw("session", fallbackKey(sessionId), JSON.stringify(textOnly))) {
+ return submissionId;
+ }
+ // sessionStorage may be disabled even when a small localStorage write fits.
+ records[sessionId] = textOnly;
+ if (writeAll(records)) {
+ browserStorage.removeRaw("session", fallbackKey(sessionId));
}
- const snapshot = fullRecord.requestSnapshot as Record<string, unknown> | null;
- const textOnly: FailedSubmissionRecord = {
- ...fullRecord,
- requestSnapshot: {
- content: fullRecord.content,
- capability: fullRecord.capability,
- language: typeof snapshot?.language === "string" ? snapshot.language : "en",
- enabledTools: [],
- knowledgeBases: [],
- },
- retryRequiresReview: true,
- };
- browserStorage.writeRaw("session", fallbackKey(sessionId), JSON.stringify(textOnly));
+ return submissionId;
}
-/** The session's unproven submission, if one survived. */
-export function readFailedSubmission(
- sessionId: string,
-): FailedSubmissionRecord | null {
- if (!sessionId) return null;
+export function readFailedSubmissions(sessionId: string): FailedSubmissionRecord[] {
+ if (!sessionId) return [];
const fallbackRaw = browserStorage.readRaw("session", fallbackKey(sessionId));
- let fallback: FailedSubmissionRecord | null = null;
+ let fallback: FailedSubmissionRecord[] = [];
+ let fallbackValid = false;
try {
const parsed: unknown = fallbackRaw ? JSON.parse(fallbackRaw) : null;
- if (isRecord(parsed)) fallback = parsed;
+ if (isRecord(parsed) || Array.isArray(parsed)) {
+ fallback = asRecords(parsed);
+ fallbackValid = true;
+ }
} catch {
- // An invalid fallback cannot suppress a valid local record.
+ // An invalid fallback cannot suppress valid local records.
}
- const record = fallback ?? readAll()[sessionId];
- if (!record) return null;
- if (Date.now() - record.savedAt > MAX_AGE_MS) {
- clearFailedSubmission(sessionId);
- return null;
+ const records = fallbackValid ? fallback : (readAll()[sessionId] ?? []);
+ const fresh = records.filter((record) => Date.now() - record.savedAt <= MAX_AGE_MS);
+ if (fresh.length !== records.length) {
+ if (!fresh.length) clearFailedSubmission(sessionId);
+ else writeSessionRecords(sessionId, fresh);
}
- return record;
+ return fresh;
}
-/** Drop the session's record — used once the server is known to own the turn. */
-export function clearFailedSubmission(sessionId: string): void {
- if (!sessionId) return;
- browserStorage.removeRaw("session", fallbackKey(sessionId));
+/** Kept for callers interested in the most recent pending submission. */
+export function readFailedSubmission(sessionId: string): FailedSubmissionRecord | null {
+ return readFailedSubmissions(sessionId).at(-1) ?? null;
+}
+
+function writeSessionRecords(sessionId: string, entries: FailedSubmissionRecord[]): void {
const records = readAll();
- if (!(sessionId in records)) return;
- delete records[sessionId];
- if (!writeAll(records)) browserStorage.removeRaw("local", STORAGE_KEY);
+ if (entries.length) records[sessionId] = entries;
+ else delete records[sessionId];
+ if (writeAll(records)) {
+ browserStorage.removeRaw("session", fallbackKey(sessionId));
+ } else {
+ // An empty array is a tombstone when a localStorage write cannot clear
+ // its old record; the fallback must take precedence over that old data.
+ browserStorage.writeRaw("session", fallbackKey(sessionId), JSON.stringify(entries));
+ }
+}
+
+/** Clear only the submission the server acknowledged; older failures remain. */
+export function clearFailedSubmission(sessionId: string, submissionId?: string): void {
+ if (!sessionId) return;
+ if (!submissionId) {
+ writeSessionRecords(sessionId, []);
+ return;
+ }
+ const current = readFailedSubmissions(sessionId);
+ writeSessionRecords(sessionId, current.filter((record) => record.submissionId !== submissionId));
}
diff --git a/web/tests/chat-failed-submission-recovery.spec.tsx b/web/tests/chat-failed-submission-recovery.spec.tsx
index af8bcbf35..03a4294c8 100644
--- a/web/tests/chat-failed-submission-recovery.spec.tsx
+++ b/web/tests/chat-failed-submission-recovery.spec.tsx
@@ -1,11 +1,15 @@
import { act, fireEvent, render, screen } from "@testing-library/react";
-import { beforeEach, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
import {
ChatStateAdapterProvider,
useChatStateAdapter,
} from "@/features/chat/ChatStateAdapter";
import { initI18n } from "@/i18n/init";
-import { readFailedSubmission, storeFailedSubmission } from "@/lib/failed-submissions";
+import {
+ readFailedSubmission,
+ readFailedSubmissions,
+ storeFailedSubmission,
+} from "@/lib/failed-submissions";
initI18n("en");
@@ -98,11 +102,10 @@ function completedServerSession() {
};
}
-function seedUnsentSubmission(content = "Hello offline", priorMatchingUserIds: string[] = []) {
- storeFailedSubmission("s1", {
+function seedUnsentSubmission(content = "Hello offline") {
+ return storeFailedSubmission("s1", {
content,
capability: "chat",
- priorMatchingUserIds,
requestSnapshot: {
content,
capability: "chat",
@@ -120,6 +123,7 @@ function Harness() {
<>
<button onClick={() => void loadSession("s1")}>Load</button>
<button onClick={() => sendMessage("Hello offline")}>Send</button>
+ <button onClick={() => sendMessage("Second offline")}>Send another</button>
<button onClick={() => void resendLastMessage()}>Resend</button>
<div data-testid="submissionFailed">
{String(state.submissionFailed)}
@@ -155,12 +159,16 @@ function readStoredKeys() {
}
beforeEach(() => {
+ localStorage.clear();
+ sessionStorage.clear();
fixture.connected = false;
fixture.sent = [];
fixture.emit = undefined;
fixture.close = undefined;
});
+afterEach(() => vi.restoreAllMocks());
+
it("marks a submission the server never received as unsent, not a failed reply", async () => {
vi.useFakeTimers();
try {
@@ -190,7 +198,7 @@ it("marks a submission the server never received as unsent, not a failed reply",
expect(screen.getByTestId("lastTurnFailed").textContent).toBe("true");
// The text survives in local storage for reload recovery.
expect(JSON.parse(screen.getByTestId("stored").textContent ?? "{}"))
- .toMatchObject({ s1: { content: "Hello offline" } });
+ .toMatchObject({ s1: [{ content: "Hello offline" }] });
} finally {
vi.useRealTimers();
}
@@ -256,6 +264,7 @@ it("restores the unsent submission after a reload and resends it on retry", asyn
});
it("drops the record when the server transcript already holds the submission", async () => {
+ const submissionId = seedUnsentSubmission();
const serverHoldsIt = {
...completedServerSession(),
status: "failed",
@@ -266,6 +275,7 @@ it("drops the record when the server transcript already holds the submission", a
session_id: "s1",
role: "user",
content: "Hello offline",
+ metadata: { client_submission_id: submissionId },
events: [],
attachments: [],
created_at: 3,
@@ -274,7 +284,6 @@ it("drops the record when the server transcript already holds the submission", a
],
};
fixture.session = serverHoldsIt;
- seedUnsentSubmission();
render(
<ChatStateAdapterProvider>
<Harness />
@@ -327,7 +336,7 @@ it("keeps a new unsent submission when an older server turn has identical text",
await vi.advanceTimersByTimeAsync(2_400);
});
const saved = readFailedSubmission("s1");
- expect(saved?.priorMatchingUserIds).toEqual(["3"]);
+ expect(saved?.submissionId).toBeTruthy();
firstView.unmount();
render(
<ChatStateAdapterProvider>
@@ -391,3 +400,151 @@ it("preserves text after storage quota errors without offering an incomplete res
expect(screen.getByTestId("submissionNeedsReview").textContent).toBe("true");
expect(screen.getByTestId("lastTurnFailed").textContent).toBe("false");
});
+
+it("restores a failed first message in a draft and can retry after reload", async () => {
+ vi.useFakeTimers();
+ try {
+ fixture.session = undefined;
+ const firstView = render(
+ <ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>,
+ );
+ fireEvent.click(screen.getByText("Send"));
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(2_400);
+ });
+ expect(readMessages()).toEqual([
+ { role: "user", content: "Hello offline", failed: true },
+ ]);
+ expect(readFailedSubmissions("draft:general")).toHaveLength(1);
+ firstView.unmount();
+
+ fixture.connected = true;
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ expect(readMessages()).toEqual([
+ { role: "user", content: "Hello offline", failed: true },
+ ]);
+ expect(screen.getByTestId("lastTurnFailed").textContent).toBe("true");
+ await act(async () => {
+ fireEvent.click(screen.getByText("Resend"));
+ });
+ expect(fixture.sent.at(-1)).toMatchObject({
+ type: "start_turn",
+ content: "Hello offline",
+ session_id: null,
+ });
+ await act(async () => {
+ fixture.emit?.({
+ type: "done", source: "chat", stage: "responding", content: "",
+ turn_id: "draft-retry", seq: 1, timestamp: Date.now() / 1000,
+ metadata: { status: "completed", user_message_id: 1, assistant_message_id: 2 },
+ });
+ });
+ expect(readFailedSubmissions("draft:general")).toEqual([]);
+ } finally {
+ vi.useRealTimers();
+ }
+});
+
+it("keeps a start_turn_rejected submission as an unsent user row across reload", async () => {
+ fixture.connected = true;
+ fixture.session = completedServerSession();
+ const firstView = render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ fireEvent.click(screen.getByText("Send"));
+ await act(async () => {
+ fixture.emit?.({
+ type: "error", source: "transport", stage: "", content: "Turn rejected",
+ timestamp: Date.now() / 1000,
+ metadata: { reason: "start_turn_rejected", turn_terminal: true, status: "failed" },
+ });
+ });
+ expect(readMessages().at(-1)).toEqual({
+ role: "user", content: "Hello offline", failed: true,
+ });
+ expect(readFailedSubmissions("s1")).toHaveLength(1);
+ firstView.unmount();
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ expect(readMessages().at(-1)).toEqual({
+ role: "user", content: "Hello offline", failed: true,
+ });
+ expect(screen.getByTestId("lastTurnFailed").textContent).toBe("true");
+});
+
+it("keeps both unsent messages when a second direct send fails", async () => {
+ vi.useFakeTimers();
+ try {
+ fixture.session = completedServerSession();
+ const firstView = render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ fireEvent.click(screen.getByText("Send"));
+ await act(async () => { await vi.advanceTimersByTimeAsync(2_400); });
+ fireEvent.click(screen.getByText("Send another"));
+ await act(async () => { await vi.advanceTimersByTimeAsync(2_400); });
+ expect(readFailedSubmissions("s1").map((record) => record.content)).toEqual([
+ "Hello offline", "Second offline",
+ ]);
+ firstView.unmount();
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ expect(readMessages().slice(-2)).toEqual([
+ { role: "user", content: "Hello offline", failed: true },
+ { role: "user", content: "Second offline", failed: true },
+ ]);
+ } finally {
+ vi.useRealTimers();
+ }
+});
+
+it("does not mistake another tab's identical text for this submission", async () => {
+ const ownId = seedUnsentSubmission();
+ fixture.session = {
+ ...completedServerSession(),
+ messages: [
+ ...completedServerSession().messages,
+ {
+ id: 3, session_id: "s1", role: "user", content: "Hello offline",
+ metadata: { client_submission_id: "other-tab-submission" },
+ events: [], attachments: [], created_at: 3, parent_message_id: 2,
+ },
+ ],
+ };
+ const firstView = render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ expect(readMessages().at(-1)).toEqual({
+ role: "user", content: "Hello offline", failed: true,
+ });
+ expect(readFailedSubmissions("s1")).toHaveLength(1);
+ firstView.unmount();
+ (fixture.session.messages as Array<Record<string, unknown>>)[2].metadata = {
+ client_submission_id: ownId,
+ };
+ render(<ChatStateAdapterProvider><Harness /></ChatStateAdapterProvider>);
+ await act(async () => { fireEvent.click(screen.getByText("Load")); });
+ expect(readMessages().at(-1)).toEqual({
+ role: "user", content: "Hello offline", failed: false,
+ });
+ expect(readFailedSubmissions("s1")).toEqual([]);
+});
+
+it("falls back to localStorage text when sessionStorage is unavailable", () => {
+ const localSetItem = localStorage.setItem.bind(localStorage);
+ vi.spyOn(localStorage, "setItem").mockImplementation((key, value) => {
+ if (value.length > 500) throw new DOMException("Quota", "QuotaExceededError");
+ localSetItem(key, value);
+ });
+ vi.spyOn(sessionStorage, "setItem").mockImplementation(() => {
+ throw new DOMException("Unavailable", "SecurityError");
+ });
+ storeFailedSubmission("s1", {
+ content: "Keep this text", capability: "chat",
+ requestSnapshot: {
+ content: "Keep this text", language: "en",
+ attachments: [{ filename: "huge.png", base64: "A".repeat(10_000) }],
+ },
+ });
+ const record = readFailedSubmission("s1");
+ expect(record?.content).toBe("Keep this text");
+ expect(record?.retryRequiresReview).toBe(true);
+ expect(localStorage.getItem("deeptutor.failedSubmissions")).toContain("Keep this text");
+});