@aexol/spectral 0.9.129 → 0.9.131

package/dist/extensions/code-order/index.js

@@ -0,0 +1,76 @@
+/**
+ * Code Order — native spectral extension.
+ *
+ * Registers a single tool, `code_order_report`, that scans the current
+ * project's directory tree and returns a Markdown cleanup report: oversized
+ * files, deep nesting, empty folders/files, duplicate sibling names and
+ * single-child folders. Language-agnostic, read-only, zero configuration.
+ *
+ * The report is input for the agent — it deduces what to split or flatten
+ * outside of this extension. Tree-like structure is enforced separately via
+ * the system prompt guidelines (see system-prompt.ts).
+ */
+import { resolve } from "node:path";
+import { walkTree, computeMetrics } from "./analyzer.js";
+import { runAllHeuristics } from "./heuristics.js";
+import { renderReport } from "./report.js";
+export default async function codeOrderExtension(ext) {
+    const tool = {
+        name: "code_order_report",
+        label: "Code Order Report",
+        description: "Analyze the current project's folder structure and file sizes, " +
+            "then generate a cleanup report with actionable findings: " +
+            "oversized files, deep nesting, empty folders, duplicate sibling names, single-child folders. " +
+            "Read-only, zero config. Use this to get input data before reorganizing code.",
+        promptSnippet: "`code_order_report` — analyze folder structure & sizes, generate cleanup report",
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Directory to analyze. Default: current working directory.",
+                },
+            },
+        },
+        async execute(_toolCallId, params) {
+            const rawPath = params.path ?? process.cwd();
+            const root = resolve(rawPath);
+            try {
+                const { tree, allFiles, allFolders, maxDepth, fileCount } = await walkTree(root);
+                const metrics = computeMetrics(allFiles, allFolders, maxDepth);
+                const issues = runAllHeuristics(tree, allFiles, allFolders, metrics);
+                const result = {
+                    root,
+                    generatedAt: new Date().toISOString(),
+                    metrics,
+                    issues,
+                };
+                const report = renderReport(result);
+                const summary = `Analyzed ${fileCount.toLocaleString()} files across ` +
+                    `${metrics.totalFolders.toLocaleString()} folders ` +
+                    `(${(metrics.totalSize / (1024 * 1024)).toFixed(1)} MB). ` +
+                    `Found ${issues.length} structural issue(s).`;
+                return {
+                    content: [{ type: "text", text: report }],
+                    details: {
+                        summary,
+                        fileCount,
+                        folderCount: metrics.totalFolders,
+                        totalSize: metrics.totalSize,
+                        issueCount: issues.length,
+                        root,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `❌ Code Order analysis failed: ${msg}` }],
+                    details: { isError: true, error: msg, root },
+                };
+            }
+        },
+    };
+    ext.registerTool(tool);
+    process.stderr.write("[code-order] Registered code_order_report tool.\n");
+}

package/dist/extensions/code-order/report.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Code Order — Markdown report generator.
+ *
+ * Turns an {@link AnalysisResult} into a human/agent-readable Markdown report
+ * with a summary, prioritized issues, top largest files, and the extension
+ * distribution. The report is returned to the session so the LLM can deduce
+ * what to reorganize next.
+ */
+import type { AnalysisResult } from "./types.js";
+/**
+ * Render the full cleanup report as Markdown.
+ */
+export declare function renderReport(result: AnalysisResult): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/extensions/code-order/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/report.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAgDxE;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CA0F3D"}

package/dist/extensions/code-order/report.js

@@ -0,0 +1,140 @@
+/**
+ * Code Order — Markdown report generator.
+ *
+ * Turns an {@link AnalysisResult} into a human/agent-readable Markdown report
+ * with a summary, prioritized issues, top largest files, and the extension
+ * distribution. The report is returned to the session so the LLM can deduce
+ * what to reorganize next.
+ */
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function severityEmoji(sev) {
+    switch (sev) {
+        case "critical":
+            return "🔴";
+        case "warning":
+            return "🟡";
+        default:
+            return "ℹ️";
+    }
+}
+function groupByType(issues) {
+    const out = new Map();
+    for (const i of issues) {
+        const arr = out.get(i.type) ?? [];
+        arr.push(i);
+        out.set(i.type, arr);
+    }
+    return out;
+}
+const ISSUE_TITLES = {
+    oversized_file: "Oversized files",
+    deep_nesting: "Deep nesting",
+    empty_folder: "Empty folders",
+    empty_file: "Empty files",
+    duplicate_names: "Duplicate sibling folder names",
+    single_child_folder: "Single-child folders",
+};
+const ISSUE_ORDER = [
+    "oversized_file",
+    "deep_nesting",
+    "duplicate_names",
+    "empty_folder",
+    "empty_file",
+    "single_child_folder",
+];
+/**
+ * Render the full cleanup report as Markdown.
+ */
+export function renderReport(result) {
+    const { root, generatedAt, metrics, issues } = result;
+    const lines = [];
+    lines.push(`# Code Order Report — ${root}`);
+    lines.push("");
+    lines.push(`_Generated: ${generatedAt}_`);
+    lines.push("");
+    // Summary
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`**${metrics.totalFiles.toLocaleString()} files** | ` +
+        `**${metrics.totalFolders.toLocaleString()} folders** | ` +
+        `**${formatBytes(metrics.totalSize)} total** | ` +
+        `max depth ${metrics.maxDepth}`);
+    lines.push("");
+    // Issues
+    if (issues.length === 0) {
+        lines.push("## Issues");
+        lines.push("");
+        lines.push("✅ No structural issues detected. The project looks tidy.");
+        lines.push("");
+    }
+    else {
+        const grouped = groupByType(issues);
+        const counts = { critical: 0, warning: 0, info: 0 };
+        for (const i of issues)
+            counts[i.severity]++;
+        lines.push(`## Issues (${issues.length})`);
+        lines.push("");
+        lines.push(`**${counts.critical} critical** · **${counts.warning} warnings** · **${counts.info} info**`);
+        lines.push("");
+        for (const type of ISSUE_ORDER) {
+            const group = grouped.get(type);
+            if (!group || group.length === 0)
+                continue;
+            const sev = group[0].severity;
+            lines.push(`### ${severityEmoji(sev)} ${ISSUE_TITLES[type]} (${group.length})`);
+            lines.push("");
+            if (type === "oversized_file") {
+                lines.push("| Size | Path | Suggestion |");
+                lines.push("|------|------|------------|");
+                for (const i of group) {
+                    const size = i.message.match(/is ([\d.]+ [KMG]?B)/)?.[1] ?? "?";
+                    lines.push(`| ${size} | \`${i.path}\` | ${i.suggestion ?? ""} |`);
+                }
+                lines.push("");
+            }
+            else {
+                for (const i of group) {
+                    lines.push(`- \`${i.path}\` — ${i.message}`);
+                    if (i.suggestion)
+                        lines.push(`  - ${i.suggestion}`);
+                }
+                lines.push("");
+            }
+        }
+    }
+    // Top largest files
+    if (metrics.topLargestFiles.length > 0) {
+        lines.push(`## Top ${metrics.topLargestFiles.length} largest files`);
+        lines.push("");
+        lines.push("| Size | Path |");
+        lines.push("|------|------|");
+        for (const f of metrics.topLargestFiles) {
+            lines.push(`| ${formatBytes(f.size)} | \`${f.path}\` |`);
+        }
+        lines.push("");
+    }
+    // Extension distribution
+    if (metrics.extensions.length > 0) {
+        lines.push("## Extension distribution");
+        lines.push("");
+        lines.push("| Extension | Files | Total size |");
+        lines.push("|-----------|-------|------------|");
+        for (const e of metrics.extensions.slice(0, 20)) {
+            lines.push(`| .${e.extension} | ${e.count} | ${formatBytes(e.size)} |`);
+        }
+        if (metrics.extensions.length > 20) {
+            lines.push(`| … | … | … |`);
+            lines.push(`| _total_ | ${metrics.totalFiles} | ${formatBytes(metrics.totalSize)} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/extensions/code-order/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Code Order — shared types.
+ *
+ * Tree-like representation of a scanned directory. Every node is either a file
+ * or a folder; folders aggregate size/file/folder counts from their children.
+ */
+export interface FileNode {
+    readonly path: string;
+    readonly name: string;
+    readonly size: number;
+    /** Lowercase extension without the leading dot. Empty string when none. */
+    readonly extension: string;
+    readonly isFile: true;
+    readonly mtime: number;
+}
+export interface FolderNode {
+    path: string;
+    name: string;
+    isFile: false;
+    totalSize: number;
+    fileCount: number;
+    folderCount: number;
+    maxDepth: number;
+    children: TreeNode[];
+}
+export type TreeNode = FileNode | FolderNode;
+export type IssueType = "oversized_file" | "deep_nesting" | "empty_folder" | "empty_file" | "duplicate_names" | "single_child_folder";
+export type IssueSeverity = "info" | "warning" | "critical";
+export interface Issue {
+    type: IssueType;
+    severity: IssueSeverity;
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+export interface ExtensionEntry {
+    extension: string;
+    count: number;
+    size: number;
+}
+export interface ProjectMetrics {
+    totalFiles: number;
+    totalFolders: number;
+    totalSize: number;
+    maxDepth: number;
+    avgFileSize: number;
+    medianFileSize: number;
+    extensions: ExtensionEntry[];
+    topLargestFiles: FileNode[];
+    emptyFolders: string[];
+    emptyFiles: string[];
+}
+export interface AnalysisResult {
+    root: string;
+    generatedAt: string;
+    metrics: ProjectMetrics;
+    issues: Issue[];
+}
+export interface AnalysisOptions {
+    /** Absolute directory to analyze. Defaults to process.cwd(). */
+    root: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/code-order/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/extensions/code-order/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE7C,MAAM,MAAM,SAAS,GAClB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,YAAY,GACZ,iBAAiB,GACjB,qBAAqB,CAAC;AAEzB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5D,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,eAAe,EAAE,QAAQ,EAAE,CAAC;IAC5B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC/B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACb"}

package/dist/extensions/code-order/types.js

@@ -0,0 +1,7 @@
+/**
+ * Code Order — shared types.
+ *
+ * Tree-like representation of a scanned directory. Every node is either a file
+ * or a folder; folders aggregate size/file/folder counts from their children.
+ */
+export {};

package/dist/mcp/ui-stream-types.d.ts

@@ -43,7 +43,7 @@ export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
     streamId: string;
     sequence: number;
     frameType: "patch" | "checkpoint" | "final";
-    phase: "settled" | "shell" | "narrative" | "structure" | "detail";
+    phase: "structure" | "settled" | "shell" | "narrative" | "detail";
     message?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     checkpoint?: Record<string, unknown> | undefined;
@@ -52,7 +52,7 @@ export declare const visualizationStreamEnvelopeSchema: z.ZodObject<{
     streamId: string;
     sequence: number;
     frameType: "patch" | "checkpoint" | "final";
-    phase: "settled" | "shell" | "narrative" | "structure" | "detail";
+    phase: "structure" | "settled" | "shell" | "narrative" | "detail";
     message?: string | undefined;
     spec?: Record<string, unknown> | undefined;
     checkpoint?: Record<string, unknown> | undefined;

package/dist/relay/dispatcher.d.ts

@@ -163,7 +163,7 @@ export interface ClientMessageDeps {
  *  - `manager.prompt()` rejection → logged; the manager itself broadcasts
  *    an `error` event to subscribers, so we don't double-report.
  */
-export declare function handleClientMessage(frame: ClientMessageFrame, deps: ClientMessageDeps): void;
+export declare function handleClientMessage(frame: ClientMessageFrame, deps: ClientMessageDeps): Promise<void>;
 /**
  * Dispatch a `subscribe` frame from the backend. Handles the case where a
  * browser enters an old session — we load history from SQLite immediately
@@ -175,7 +175,7 @@ export declare function handleClientMessage(frame: ClientMessageFrame, deps: Cli
  * tab needs it). The `ready.catch` handler is only registered once — on the
  * first subscriber creation — to avoid duplicate error events.
  */
-export declare function handleSubscribe(frame: SubscribeFrame, deps: ClientMessageDeps): void;
+export declare function handleSubscribe(frame: SubscribeFrame, deps: ClientMessageDeps): Promise<void>;
 /**
  * Dispatch a `cancel_turn` frame. Disposes the session's agent bridge and
  * removes the stream so the next user message creates a fresh one. The

package/dist/relay/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/relay/dispatcher.js

@@ -58,8 +58,10 @@ import { handleGetAgentSettings, handleListAgents, handlePutAgentSettings, } fro
 import { handleGetSettings, handlePutSettings, } from "../server/handlers/settings.js";
 import { handleGetPromptMutationSettings, handlePutPromptMutationSettings, } from "../server/handlers/prompt-mutation-settings.js";
 import { shutdownState } from "../server/shutdown.js";
+import { humanizeProviderError } from "../server/error-humanizer.js";
 import { handleAutoResearch } from "./auto-research.js";
 import { handleAutoOptimize } from "./auto-optimizer.js";
+import { chunkHistory } from "./history-chunker.js";
 /**
  * Inline path matcher. Returns `null` for any path/method combination we
  * don't recognise; the caller turns that into a `404 Unknown route`.
@@ -1104,6 +1106,72 @@ function makeRelaySubscriber(sessionId, relay) {
         },
     };
 }
+/**
+ * Emit the chunked `session_ready_*` sequence for a freshly-attached session.
+ *
+ * Replaces the legacy single `session_ready` frame with:
+ *   1. `session_ready_start` — metadata + in-flight turn + chunk totals
+ *   2. N × `history_chunk` — atomic slices of the history tail
+ *   3. `session_ready_end` — completion + integrity total
+ *
+ * A `setImmediate` yield follows every `history_chunk` emit so chunk builds
+ * and Redis publishes are naturally spaced and don't block other CLI work.
+ *
+ * All metadata fields carried by the legacy `session_ready` event are
+ * preserved verbatim on `session_ready_start`; none are dropped.
+ */
+async function emitChunkedSessionReady(relay, sessionId, history, attachResult) {
+    const chunks = chunkHistory(history);
+    relay.send({
+        kind: "ws_event",
+        sessionId,
+        event: {
+            type: "session_ready_start",
+            sessionId,
+            currentTurn: attachResult.currentTurn,
+            totalChunks: chunks.length,
+            totalMessages: history.length,
+            totalMessageCount: attachResult.totalMessageCount,
+            loadedMessageCount: attachResult.loadedMessageCount,
+            hasEarlierMessages: attachResult.hasEarlierMessages || undefined,
+            forkCompactPending: attachResult.forkCompactPending || undefined,
+            compacting: attachResult.compacting || undefined,
+            contextWindowUsed: attachResult.contextWindowUsed,
+            contextWindowMax: attachResult.contextWindowMax,
+            intervalActive: attachResult.intervalActive || undefined,
+            intervalMinutes: attachResult.intervalMinutes,
+            intervalNextTickAt: attachResult.intervalNextTickAt,
+            intervalLaunchCount: attachResult.intervalLaunchCount,
+            intervalHasLoop: attachResult.intervalHasLoop || undefined,
+            intervalGoal: attachResult.intervalGoal,
+        },
+    });
+    for (const chunk of chunks) {
+        relay.send({
+            kind: "ws_event",
+            sessionId,
+            event: {
+                type: "history_chunk",
+                sessionId,
+                index: chunk.index,
+                total: chunk.total,
+                messages: chunk.messages,
+            },
+        });
+        // Yield to the event loop so chunk serialization and Redis publishes
+        // are spaced out and don't block other CLI work.
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    relay.send({
+        kind: "ws_event",
+        sessionId,
+        event: {
+            type: "session_ready_end",
+            sessionId,
+            totalMessages: history.length,
+        },
+    });
+}
 /**
  * Dispatch a `client_message` frame. Idempotent w.r.t. attach: the same
  * `Subscriber` is reused across messages for a given session.
@@ -1118,7 +1186,7 @@ function makeRelaySubscriber(sessionId, relay) {
  *  - `manager.prompt()` rejection → logged; the manager itself broadcasts
  *    an `error` event to subscribers, so we don't double-report.
  */
-export function handleClientMessage(frame, deps) {
+export async function handleClientMessage(frame, deps) {
     const { sessionId, message, modelId, reasoningEffort } = frame;
     const { manager, relay, subscribers } = deps;
     const logger = deps.logger ?? console;
@@ -1212,37 +1280,16 @@ export function handleClientMessage(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
             return;
         }
         subscribers.set(sessionId, subscriber);
-        // Synthesize the initial frame the WS route used to send. The
-        // browser's protocol layer expects `session_ready` as the first
-        // event on a new stream.
-        relay.send({
-            kind: "ws_event",
-            sessionId,
-            event: {
-                type: "session_ready",
-                sessionId,
-                history: attachResult.history,
-                totalMessageCount: attachResult.totalMessageCount,
-                loadedMessageCount: attachResult.loadedMessageCount,
-                hasEarlierMessages: attachResult.hasEarlierMessages || undefined,
-                currentTurn: attachResult.currentTurn,
-                forkCompactPending: attachResult.forkCompactPending || undefined,
-                contextWindowUsed: attachResult.contextWindowUsed,
-                contextWindowMax: attachResult.contextWindowMax,
-                compacting: attachResult.compacting || undefined,
-                intervalActive: attachResult.intervalActive || undefined,
-                intervalMinutes: attachResult.intervalMinutes,
-                intervalNextTickAt: attachResult.intervalNextTickAt,
-                intervalLaunchCount: attachResult.intervalLaunchCount,
-                intervalHasLoop: attachResult.intervalHasLoop || undefined,
-                intervalGoal: attachResult.intervalGoal,
-            },
-        });
+        // Synthesize the initial frames the WS route used to send. The
+        // browser's protocol layer expects `session_ready_start` as the first
+        // event on a new stream, followed by N `history_chunk` frames and a
+        // final `session_ready_end`.
+        await emitChunkedSessionReady(relay, sessionId, attachResult.history, attachResult);
         // Surface bridge-start failures as `error` events; otherwise the
         // browser would sit on a `session_ready` with no further frames.
         attachResult.ready.catch((err) => {
@@ -1250,7 +1297,7 @@ export function handleClientMessage(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
         });
     }
@@ -1291,7 +1338,7 @@ export function handleClientMessage(frame, deps) {
  * tab needs it). The `ready.catch` handler is only registered once — on the
  * first subscriber creation — to avoid duplicate error events.
  */
-export function handleSubscribe(frame, deps) {
+export async function handleSubscribe(frame, deps) {
     const { sessionId } = frame;
     const { manager, relay, subscribers } = deps;
     const logger = deps.logger ?? console;
@@ -1311,29 +1358,16 @@ export function handleSubscribe(frame, deps) {
         relay.send({
             kind: "ws_event",
             sessionId,
-            event: { type: "error", message: msg },
+            event: { type: "error", message: humanizeProviderError(err) },
         });
         return;
     }
     // Send history to all browser subscribers. The backend's fan-out
-    // delivers this to the newly-subscribed tab (and any others).
-    relay.send({
-        kind: "ws_event",
-        sessionId,
-        event: {
-            type: "session_ready",
-            sessionId,
-            history: attachResult.history,
-            totalMessageCount: attachResult.totalMessageCount,
-            loadedMessageCount: attachResult.loadedMessageCount,
-            hasEarlierMessages: attachResult.hasEarlierMessages || undefined,
-            currentTurn: attachResult.currentTurn,
-            forkCompactPending: attachResult.forkCompactPending || undefined,
-            contextWindowUsed: attachResult.contextWindowUsed,
-            contextWindowMax: attachResult.contextWindowMax,
-            compacting: attachResult.compacting || undefined,
-        },
-    });
+    // delivers this to the newly-subscribed tab (and any others). The
+    // chunked `session_ready_*` sequence replaces the legacy single
+    // `session_ready` frame so large history tails are streamed in
+    // bounded slices rather than one Redis publish.
+    await emitChunkedSessionReady(relay, sessionId, attachResult.history, attachResult);
     if (isNewSubscriber) {
         // Surface bridge-start failures as `error` events; otherwise the
         // browser would sit on a `session_ready` with no further frames.
@@ -1342,7 +1376,7 @@ export function handleSubscribe(frame, deps) {
             relay.send({
                 kind: "ws_event",
                 sessionId,
-                event: { type: "error", message: msg },
+                event: { type: "error", message: humanizeProviderError(err) },
             });
         });
     }

package/dist/relay/history-chunker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure, synchronous history chunker for the chunked `session_ready` protocol.
+ *
+ * Splits a `WireMessage[]` history tail into atomic chunks bounded by both a
+ * max-message count and a max-byte size (whichever triggers first). A single
+ * message is never split across chunks — if one message alone exceeds
+ * `maxBytes`, it is emitted as its own chunk and a `console.warn` is logged
+ * (anomaly, not fatal).
+ *
+ * This module has no I/O and no side effects beyond the documented `console.warn`
+ * for oversize messages. It is safe to unit-test in isolation.
+ */
+import type { WireMessage } from "../server/wire.js";
+/** Maximum number of messages packed into a single `history_chunk`. */
+export declare const MAX_MESSAGES_PER_CHUNK = 25;
+/** Maximum serialized byte size of a single `history_chunk`'s messages. */
+export declare const MAX_BYTES_PER_CHUNK: number;
+/** A single atomic slice of the history tail. */
+export interface HistoryChunk {
+    /** 0-based position of this chunk in the emitted sequence. */
+    index: number;
+    /** Total number of chunks that will be emitted for this history. */
+    total: number;
+    /** Atomic message slice. Never split mid-message. */
+    messages: WireMessage[];
+}
+export interface ChunkHistoryOptions {
+    maxMessages?: number;
+    maxBytes?: number;
+}
+/**
+ * Split `history` into atomic chunks bounded by `maxMessages` and `maxBytes`.
+ *
+ * - Empty history → `[]` (the caller still emits `session_ready_start` +
+ *   `session_ready_end` with zero `history_chunk` frames in between).
+ * - `index` is 0-based; `total` is the final chunk count and is identical on
+ *   every chunk in the returned array (computed after packing so it is always
+ *   accurate, even when oversize messages force solo chunks).
+ * - Messages are atomic: a single message is never split across two chunks.
+ * - If a single message exceeds `maxBytes`, it is emitted alone in its own
+ *   chunk and `console.warn` is called with the message id and index.
+ *
+ * Pure and synchronous — no I/O, no async, no external state.
+ */
+export declare function chunkHistory(history: WireMessage[], opts?: ChunkHistoryOptions): HistoryChunk[];
+//# sourceMappingURL=history-chunker.d.ts.map

package/dist/relay/history-chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-chunker.d.ts","sourceRoot":"","sources":["../../src/relay/history-chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,QAAa,CAAC;AAE9C,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,WAAW,EAAE,EACtB,IAAI,GAAE,mBAAwB,GAC7B,YAAY,EAAE,CA6ChB"}