@xopcai/xopc 0.0.434 → 0.0.436

package/dist/src/computer/stability-diagnostics.d.ts

@@ -0,0 +1,23 @@
+import type { ComputerTarget } from '@xopcai/computer-control-contract';
+import type { z } from 'zod';
+import type { ComputerDiagnosticSchema, ComputerStabilitySchema } from './errors.js';
+type Stability = z.infer<typeof ComputerStabilitySchema>;
+type Snapshot = {
+    target: ComputerTarget;
+    summary: string;
+    stateDigest: string;
+    imageWidth: number;
+    imageHeight: number;
+};
+/** Compare privately; retain only fixed change categories and bounded element positions, never values or hashes. */
+export declare class ComputerStabilityTracker {
+    private readonly stage;
+    private readonly action?;
+    private readonly changes;
+    private readonly indices;
+    constructor(stage: Stability['stage'], action?: Stability['action']);
+    deadline(): void;
+    compare(before: Snapshot, after: Snapshot): void;
+    diagnostic(errorCode: string, samples: number): z.infer<typeof ComputerDiagnosticSchema>;
+}
+export {};

package/dist/src/computer/stability-diagnostics.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+//#region src/computer/stability-diagnostics.ts
+/** Compare privately; retain only fixed change categories and bounded element positions, never values or hashes. */
+var ComputerStabilityTracker = class {
+	changes = /* @__PURE__ */ new Set();
+	indices = /* @__PURE__ */ new Set();
+	constructor(stage, action) {
+		this.stage = stage;
+		this.action = action;
+	}
+	deadline() {
+		this.changes.add("deadline");
+	}
+	compare(before, after) {
+		const a = before.target, b = after.target;
+		if (a.appId !== b.appId || a.pid !== b.pid || a.processIdentity !== b.processIdentity || a.windowId !== b.windowId) this.changes.add("window_identity");
+		if (a.geometryRevision !== b.geometryRevision || a.width !== b.width || a.height !== b.height) this.changes.add("window_geometry");
+		if (before.imageWidth !== after.imageWidth || before.imageHeight !== after.imageHeight) this.changes.add("image_dimensions");
+		if (before.summary !== after.summary) try {
+			const left = JSON.parse(before.summary), right = JSON.parse(after.summary);
+			const ae = Array.isArray(left.elements) ? left.elements : [], be = Array.isArray(right.elements) ? right.elements : [];
+			if (ae.length !== be.length) this.changes.add("accessibility_structure");
+			if (left.text !== right.text) this.changes.add("accessibility_text");
+			const groups = {
+				accessibility_structure: [
+					"role",
+					"ref",
+					"depth",
+					"parent_index"
+				],
+				accessibility_text: [
+					"label",
+					"value",
+					"value_description"
+				],
+				accessibility_state: [
+					"enabled",
+					"selected",
+					"keyboardFocused",
+					"inputAllowed",
+					"semanticActions",
+					"in_web_content"
+				],
+				accessibility_geometry: ["bounds", "frame"]
+			};
+			for (let i = 0; i < Math.max(ae.length, be.length); i++) {
+				if (JSON.stringify(ae[i]) !== JSON.stringify(be[i]) && this.indices.size < 8 && i <= 16384) this.indices.add(i);
+				for (const [category, fields] of Object.entries(groups)) if (fields.some((field) => JSON.stringify(ae[i]?.[field]) !== JSON.stringify(be[i]?.[field]))) this.changes.add(category);
+			}
+		} catch {
+			this.changes.add("accessibility_structure");
+		}
+		if (before.stateDigest !== after.stateDigest && before.summary === after.summary && JSON.stringify(a) === JSON.stringify(b) && before.imageWidth === after.imageWidth && before.imageHeight === after.imageHeight) this.changes.add("visual_or_unexposed_state");
+	}
+	diagnostic(errorCode, samples) {
+		return {
+			errorCode,
+			phase: this.stage === "initial_capture" ? "observe" : "dispatch",
+			diagnosticId: randomUUID(),
+			stability: {
+				stage: this.stage,
+				samples,
+				...this.action ? { action: this.action } : {},
+				changes: [...this.changes],
+				changedElementIndices: [...this.indices]
+			}
+		};
+	}
+};
+//#endregion
+export { ComputerStabilityTracker };

package/dist/src/computer/validation-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+import { ComputerValidationSchema } from './errors.js';
+type Validation = z.infer<typeof ComputerValidationSchema>;
+/** Project only allowlisted metadata; Zod messages, values and arbitrary property names may contain private data. */
+export declare function modelValidation(value: unknown, stage: Validation['stage'], error?: unknown, failure?: {
+    path: (string | number)[];
+    code: Validation['issues'][number]['code'];
+}): Validation;
+export {};

package/dist/src/computer/validation-diagnostics.js

@@ -0,0 +1,54 @@
+import { ComputerValidationSchema } from "./errors.js";
+import { z } from "zod";
+//#region src/computer/validation-diagnostics.ts
+const Field = ComputerValidationSchema.shape.issues.element.shape.path.element;
+const Action = ComputerValidationSchema.shape.action;
+const Code = ComputerValidationSchema.shape.issues.element.shape.code;
+function actionName(value) {
+	if (!value || typeof value !== "object") return "unknown";
+	const node = value;
+	return Action.safeParse(typeof node.action === "string" ? node.action : node.kind).data ?? "unknown";
+}
+/** Project only allowlisted metadata; Zod messages, values and arbitrary property names may contain private data. */
+function modelValidation(value, stage, error, failure) {
+	const root = value && typeof value === "object" ? value : {};
+	const payload = root.arguments && typeof root.arguments === "object" ? root.arguments : root;
+	const proposal = payload.proposal && typeof payload.proposal === "object" ? payload.proposal : payload;
+	const action = actionName(typeof proposal.action === "object" ? proposal.action : proposal);
+	const issues = [];
+	const append = (path, code) => {
+		if (issues.length >= 4) return;
+		let node = value;
+		let nestedAction = action;
+		for (const part of path) {
+			if (!node || typeof node !== "object") break;
+			node = node[part];
+			const candidate = actionName(node);
+			if (candidate !== "unknown") nestedAction = candidate;
+		}
+		issues.push({
+			path: path.slice(0, 10).map((part) => Field.safeParse(part).data ?? "unknown_field"),
+			code: Code.safeParse(code).data ?? "invalid_value",
+			action: nestedAction
+		});
+	};
+	const branchScore = (list) => list.length + list.filter((issue) => issue.code === "invalid_value" && ["kind", "action"].includes(String(issue.path.at(-1)))).length * 100;
+	const visit = (list, prefix = []) => {
+		for (const issue of list) if (issue.code === "invalid_union" && issue.errors.length) visit([...issue.errors].sort((a, b) => branchScore(a) - branchScore(b))[0], [...prefix, ...issue.path]);
+		else if (issue.code === "unrecognized_keys") for (const key of issue.keys) append([
+			...prefix,
+			...issue.path,
+			key
+		], issue.code);
+		else append([...prefix, ...issue.path], issue.code);
+	};
+	if (error instanceof z.ZodError) visit(error.issues);
+	if (failure) append(failure.path, failure.code);
+	return {
+		action,
+		stage,
+		issues
+	};
+}
+//#endregion
+export { modelValidation };

package/dist/src/config/agent-profile.js

@@ -1,6 +1,6 @@
+import { normalizeAgentId } from "../agent-catalog/id.js";
 import { resolveEffectiveAgentConfig } from "../agent-config/resolver.js";
 import { init_agent_config } from "../agent-config/index.js";
-import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, resolveAgentWorkspaceDir } from "../agent/agent-scope.js";
 import { getConversationRouting } from "../storage/sqlite/conversation-repository.js";

package/dist/src/execution-environments/local-worktree-manager.js

@@ -8,8 +8,8 @@ import { assertManagedWorktreePath, assertNoNestedRegisteredWorktrees, readDirec
 import { dirname, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { mkdir, rm, stat } from "node:fs/promises";
 import lockfile from "proper-lockfile";
+import { mkdir, rm, stat } from "node:fs/promises";
 //#region src/execution-environments/local-worktree-manager.ts
 init_logger();
 const log = createLogger("ExecutionEnvironment:LocalWorktree");

package/dist/src/extensions/agent-plugins/skill-catalog.js

@@ -1,7 +1,7 @@
-import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { containedPath } from "./contained-path.js";
 import "./validation.js";
 import { AgentPluginStore } from "./store.js";
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
 import { createSkillConfigManager } from "../../agent/skills/config.js";
 import { parseSkillLocalizations } from "../../agent/skills/parse-skill-metadata.js";
 import { buildSkillMarkdownPreviewFromRaw } from "../../agent/skills/skill-markdown-preview-from-raw.js";

package/dist/src/extensions/agent-plugins/validation.js

@@ -9,8 +9,8 @@ import { dirname, join, resolve } from "node:path";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import yaml from "js-yaml";
 import { validateHeaderName, validateHeaderValue } from "node:http";
+import yaml from "js-yaml";
 //#region src/extensions/agent-plugins/validation.ts
 init_schema();
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";

package/dist/src/gateway/agents-admin.js

@@ -1,9 +1,9 @@
 import { normalizeAgentId, validateAgentIdForNewAgent } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope, listAgentEntries, resolveAgentProfileDir, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath } from "../agent/agent-scope.js";
+import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
 import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
 import { AgentCatalogService } from "../agent-catalog/service.js";
-import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
 import { GATEWAY_BUILTIN_TOOL_IDS } from "./agent-builtin-tools.js";
 import { resolve } from "node:path";

package/dist/src/gateway/global-defaults-admin.js

@@ -1,8 +1,8 @@
 import { AgentDefaultsSchema } from "../agent-config/schema.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { validatePhoneModelChange } from "../phone/model-adapter.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { validateComputerModelChange } from "../computer/model-config.js";
 import { GATEWAY_BUILTIN_TOOLS } from "./agent-builtin-tools.js";
 import { isDeepStrictEqual } from "node:util";

package/dist/src/gateway/hono/routes/agents.js

@@ -1,6 +1,6 @@
+import { normalizeAgentId } from "../../../agent-catalog/id.js";
 import { AgentEntrySchema, AgentModelsOverrideSchema, AgentProfileSchema, RuntimePolicySchema, SkillOverrideSchema, ToolPoliciesSchema } from "../../../agent-config/schema.js";
 import { init_agent_config } from "../../../agent-config/index.js";
-import { normalizeAgentId } from "../../../agent-catalog/id.js";
 import { init_agent_scope } from "../../../agent/agent-scope.js";
 import { getVoiceModelsConfig } from "../../../config/voice.js";
 import { createGatewayAgent, deleteAgentAvatarFile, deleteGatewayAgent, getGatewayAgentEffectiveConfig, listAgentProfileFiles, listGatewayAgents, readAgentAvatarFile, readAgentProfileFile, resolveAgentAvatarImage, updateGatewayAgent, writeAgentAvatarFromBase64, writeAgentProfileFile } from "../../agents-admin.js";

package/dist/src/gateway/hono/routes/config-patch/misc.js

@@ -1,10 +1,10 @@
 import { BindingsSchema, init_binding_schema } from "../../../../routing/binding-schema.js";
-import { AgentCatalogService } from "../../../../agent-catalog/service.js";
 import { ComputerConfigSchema, init_config } from "../../../../computer/config.js";
 import { ContextPlanningConfigSchema, HomeIntelligenceConfigSchema, KnowledgeMemoryConfigSchema, UserContextConfigSchema, UserModelConfigSchema, init_config as init_config$1 } from "../../../../user-context/config.js";
 import { BrowserConfigSchema, McpConfigSchema, VoiceConfigSchema, init_schema } from "../../../../config/schema.js";
 import { CredentialResolver, init_credentials } from "../../../../auth/credentials.js";
 import { canonicalizeConfiguredMcpServer } from "../../../../config/mcp-config-normalize.js";
+import { AgentCatalogService } from "../../../../agent-catalog/service.js";
 import { mergeGatewaySkillsMarketplacePatch, mergeSessionConfigPatch, mergeUpdateConfigPatch } from "../../../../config/web-patch.js";
 import { assertGatewayAuthConfigured, resolveGatewayAuth } from "../../../auth.js";
 import { isMaskedSecretPatchValue } from "../../lib/mask-secret-length.js";

package/dist/src/gateway/hono/routes/notes.js

@@ -1,9 +1,9 @@
 import { NoteDeleteOutputSchema, NoteGetOutputSchema, ProductReadContracts } from "../../../../packages/gateway-contract/src/capabilities.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
-import { CapabilityError } from "../../../capabilities/runtime/errors.js";
-import "../../../capabilities/runtime/dispatcher.js";
 import { init_session_key, resolveConversationId } from "../../../routing/session-key.js";
 import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { resolveReverseProxyPublicUrl } from "../../public-url.js";
 import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { resolveGatewayEffectiveHost } from "../../../config/gateway-bind.js";

package/dist/src/gateway/hono/routes/phone-setup.js

@@ -1,7 +1,6 @@
 import { resolveStateDir } from "../../../config/paths-state.js";
 import { getSessionMetadata, init_session_read_repository } from "../../../storage/sqlite/session-read-repository.js";
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
-import { AgentCatalogService } from "../../../agent-catalog/service.js";
 import { init_paths } from "../../../config/paths.js";
 import { resolveEffectiveAgentConfigForAgent } from "../../../config/agent-profile.js";
 import { phoneModelProfile } from "../../../phone/model-policy.js";
@@ -11,6 +10,7 @@ import { managedHdcPath, managedHosJar, managedJavaHome } from "../../../runtime
 import { managedPhoneAdbPath } from "../../../runtime-tools/phone-dependency-catalog.js";
 import "../../../phone/model-adapter.js";
 import { getPhoneRuntime } from "../../../phone/runtime.js";
+import { AgentCatalogService } from "../../../agent-catalog/service.js";
 import { PhoneSetupService } from "../../../phone/setup/service.js";
 import { PhoneDependencyManager, probePhoneAdb } from "../../../runtime-tools/phone-dependencies.js";
 import { createHash } from "node:crypto";

package/dist/src/gateway/hono/routes/projects.js

@@ -6,12 +6,12 @@ import { loadTranscriptRowsForSession } from "../../../storage/sqlite/transcript
 import "../../../storage/sqlite/index.js";
 import { ActivityService } from "../../../activity/service.js";
 import "../../../activity/index.js";
-import { CapabilityError } from "../../../capabilities/runtime/errors.js";
-import "../../../capabilities/runtime/dispatcher.js";
 import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
 import "../../../knowledge-memory/index.js";
 import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "../../../projects/project-kind.js";
 import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError } from "../../../projects/project-service.js";

package/dist/src/gateway/hono/routes/session-input-handler.js

@@ -6,9 +6,9 @@ import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packa
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { SessionInputControlConflict, init_session_input_control_repository } from "../../../storage/sqlite/session-input-control-repository.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { init_providers, resolveModel } from "../../../providers/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
-import { init_providers, resolveModel } from "../../../providers/index.js";
 import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
 import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";

package/dist/src/gateway/hono/routes/tasks.js

@@ -6,9 +6,9 @@ import { hasGatewayScope } from "../../security/gateway-scopes.js";
 import { enqueueTaskChangedEvent, init_task_change_events } from "../../../tasks/task-change-events.js";
 import { TaskRepository, init_task_repository } from "../../../tasks/task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "../../../tasks/task-run-repository.js";
+import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
-import { TaskConversationRepository } from "../../../tasks/task-conversation-repository.js";
 import { TaskCriterionReviewRepository } from "../../../tasks/task-criterion-review-repository.js";
 import { TaskContextMutationOutputSchema } from "../../../tasks/capabilities/relations.js";
 import { TaskDeleteOutputSchema } from "../../../tasks/capabilities/management.js";

package/dist/src/gateway/image-generation-setup.js

@@ -1,11 +1,11 @@
 import { normalizeAgentId } from "../agent-catalog/id.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
 import { init_agent_scope } from "../agent/agent-scope.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { ConfigSchema, init_schema } from "../config/schema.js";
 import { resolveEffectiveAgentConfigForAgent } from "../config/agent-profile.js";
 import { fetchWithTimeoutGuarded } from "../media-shared/http/provider-http.js";
 import "../media-shared/http/index.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { getImageGenerationProvider, listImageGenerationProvidersSummary } from "../agent/image/generation/provider-registry.js";
 //#region src/gateway/image-generation-setup.ts
 init_repository();

package/dist/src/gateway/xopc-cloud-capability-setup.js

@@ -1,7 +1,6 @@
 import "../agent-config/schema.js";
 import { init_agent_config } from "../agent-config/index.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { ConfigSchema, init_schema } from "../config/schema.js";
 import { phoneModelProfile } from "../phone/model-policy.js";
 import { init_model_policy, isComputerModel, isDedicatedComputerProfile } from "../computer/model-policy.js";
@@ -10,6 +9,7 @@ import { init_voice } from "../../packages/realtime-protocol/src/voice.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../providers/model-catalog-store.js";
 import "../phone/model-adapter.js";
 import { compareCatalogModels } from "../providers/model-catalog-ranking.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { prepareUpdateGlobalDefaults } from "./global-defaults-admin.js";
 //#region src/gateway/xopc-cloud-capability-setup.ts
 init_voice();

package/dist/src/imports/importService.js

@@ -11,8 +11,8 @@ import { scanLocal } from "./scanner.js";
 import { dirname, join } from "node:path";
 import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import yaml from "js-yaml";
 import lockfile from "proper-lockfile";
+import yaml from "js-yaml";
 //#region src/imports/importService.ts
 init_write_file_atomic();
 init_logger();

package/dist/src/local-apps/service.js

@@ -5,9 +5,9 @@ import { init_logger } from "../utils/logger.js";
 import { afterSqliteCommit, init_transaction, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { ExtensionCapabilityBindingsSchema, extensionCapabilityPermissions } from "../../packages/gateway-contract/src/extension-capabilities.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
-import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { init_paths, resolveExtensionsDir } from "../config/paths.js";
 import { slugifyProjectName } from "../projects/project-store.js";
+import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { LocalAppStore } from "./store.js";
 import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { validateLocalAppCapabilityContracts } from "./capabilities/contracts.js";

package/dist/src/personal-agent/service.js

@@ -2,11 +2,11 @@ import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js
 import { init_session_repository, patchSessionMetadata } from "../storage/sqlite/session-repository.js";
 import { setSessionConfig } from "../storage/sqlite/config-repository.js";
 import { AgentCatalogRepository, init_repository } from "../agent-catalog/repository.js";
-import { AgentCatalogService } from "../agent-catalog/service.js";
 import { createConversation, init_conversation_repository } from "../storage/sqlite/conversation-repository.js";
 import { getAvailableModels, init_providers } from "../providers/index.js";
 import { getPersonalAgent, personalAgentId } from "./repository.js";
 import { PERSONAL_MAIN_TOOL_IDS, PERSONAL_READ_TOOL_ALIASES } from "./policy.js";
+import { AgentCatalogService } from "../agent-catalog/service.js";
 import { getModelThinking } from "../providers/model-thinking.js";
 import { personalInstructions } from "./prompts.js";
 import { completePersonalOnboarding } from "./onboarding.js";

package/dist/src/realtime/runtime.js

@@ -195,15 +195,23 @@ var RealtimeRuntime = class {
 					const output = item.view === "compact" ? compactRunEvent(event) : event;
 					if (output) writer.enqueue(output);
 				});
-				subscriptions.set(item.topic, handle);
 				writer.enqueue(serverMessage("realtime.subscribed", {
 					topic: item.topic,
 					cursor: handle.cursor
 				}), "critical");
-				for (const message of handle.initial) {
-					const output = item.view === "compact" ? compactRunEvent(message) : message;
-					if (output) writer.enqueue(output);
-				}
+				const cancelReplay = writer.enqueueReplay((function* () {
+					for (const message of handle.initial) {
+						const output = item.view === "compact" ? compactRunEvent(message) : message;
+						if (output) yield output;
+					}
+				})());
+				subscriptions.set(item.topic, {
+					...handle,
+					unsubscribe: () => {
+						cancelReplay();
+						handle.unsubscribe();
+					}
+				});
 			}
 			return true;
 		};

package/dist/src/realtime/writer.d.ts

@@ -8,8 +8,15 @@ export declare class RealtimeSocketWriter {
     private sending;
     private closed;
     private retryTimer?;
+    private stallTimer?;
     constructor(socket: WebSocket);
     enqueue(message: ServerRealtimeMessage, priority?: 'critical' | 'normal'): boolean;
+    /** Serialize replay only as the socket drains; live messages stay behind the replay. */
+    enqueueReplay(messages: Iterable<ServerRealtimeMessage>): () => void;
     close(): void;
+    private fail;
+    private serialize;
+    private watchForStall;
+    private next;
     private flush;
 }

package/dist/src/realtime/writer.js

@@ -1,7 +1,12 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
 //#region src/realtime/writer.ts
+init_logger();
+const log = createLogger("RealtimeSocketWriter");
 const SOFT_BUFFERED_BYTES = 512 * 1024;
-const HARD_BUFFERED_BYTES = 4 * 1024 * 1024;
-const MAX_QUEUED_BYTES = 2 * 1024 * 1024;
+const MAX_EVENT_BYTES = 2 * 1024 * 1024;
+const MAX_QUEUED_BYTES = 16 * 1024 * 1024;
+const DELIVERY_STALL_MS = 15e3;
 var RealtimeSocketWriter = class {
 	critical = [];
 	normal = [];
@@ -9,80 +14,141 @@ var RealtimeSocketWriter = class {
 	sending = false;
 	closed = false;
 	retryTimer;
+	stallTimer;
 	constructor(socket) {
 		this.socket = socket;
 	}
 	enqueue(message, priority = "normal") {
 		if (this.closed || this.socket.readyState !== 1) return false;
-		let data;
-		try {
-			data = JSON.stringify(message);
-		} catch {
-			this.socket.close(1011, "Realtime message serialization failed");
-			this.close();
-			return false;
-		}
-		const item = {
-			data,
-			bytes: Buffer.byteLength(data)
-		};
-		if (item.bytes > MAX_QUEUED_BYTES) {
-			this.socket.close(1009, "Realtime event exceeds delivery limit");
-			this.close();
-			return false;
-		}
+		const item = this.serialize(message);
+		if (!item) return false;
 		if (this.queuedBytes + item.bytes > MAX_QUEUED_BYTES) {
-			this.socket.close(4413, "Realtime client is too slow");
-			this.close();
+			this.fail(4413, "Realtime delivery queue limit exceeded", {
+				eventBytes: item.bytes,
+				...message.kind === "realtime.event" ? {
+					topic: message.payload.topic,
+					event: message.payload.event
+				} : {}
+			});
 			return false;
 		}
 		this.queuedBytes += item.bytes;
 		(priority === "critical" ? this.critical : this.normal).push(item);
 		this.flush();
-		return true;
+		return !this.closed;
+	}
+	/** Serialize replay only as the socket drains; live messages stay behind the replay. */
+	enqueueReplay(messages) {
+		if (this.closed || this.socket.readyState !== 1) return () => {};
+		const item = { iterator: messages[Symbol.iterator]() };
+		this.normal.push(item);
+		this.flush();
+		return () => {
+			const index = this.normal.indexOf(item);
+			if (index >= 0) this.normal.splice(index, 1);
+			item.iterator.return?.();
+		};
 	}
 	close() {
 		if (this.closed) return;
 		this.closed = true;
 		if (this.retryTimer) clearTimeout(this.retryTimer);
+		if (this.stallTimer) clearTimeout(this.stallTimer);
 		this.retryTimer = void 0;
+		this.stallTimer = void 0;
+		for (const item of this.normal) if ("iterator" in item) item.iterator.return?.();
 		this.critical.length = 0;
 		this.normal.length = 0;
 		this.queuedBytes = 0;
 	}
+	fail(code, reason, fields = {}) {
+		log.warn({
+			...fields,
+			code,
+			queuedBytes: this.queuedBytes,
+			bufferedBytes: this.socket.bufferedAmount,
+			pendingItems: this.normal.length + this.critical.length
+		}, reason);
+		this.close();
+		this.socket.close(code, reason);
+	}
+	serialize(message) {
+		let data;
+		try {
+			data = JSON.stringify(message);
+		} catch {
+			this.fail(1011, "Realtime message serialization failed");
+			return;
+		}
+		const bytes = Buffer.byteLength(data);
+		if (bytes > MAX_EVENT_BYTES) {
+			this.fail(1009, "Realtime event exceeds delivery limit", {
+				eventBytes: bytes,
+				...message.kind === "realtime.event" ? {
+					topic: message.payload.topic,
+					event: message.payload.event
+				} : {}
+			});
+			return;
+		}
+		return {
+			data,
+			bytes
+		};
+	}
+	watchForStall() {
+		if (!this.stallTimer) this.stallTimer = setTimeout(() => this.fail(4413, "Realtime delivery stalled"), DELIVERY_STALL_MS);
+	}
+	next() {
+		const critical = this.critical.shift();
+		if (critical) return critical;
+		while (this.normal.length) {
+			const head = this.normal[0];
+			if (!("iterator" in head)) return this.normal.shift();
+			const next = head.iterator.next();
+			if (next.done) {
+				this.normal.shift();
+				continue;
+			}
+			const item = this.serialize(next.value);
+			if (item) this.queuedBytes += item.bytes;
+			return item;
+		}
+	}
 	flush() {
 		if (this.closed || this.sending || this.socket.readyState !== 1) return;
-		if (this.socket.bufferedAmount > HARD_BUFFERED_BYTES) {
-			this.socket.close(4413, "Realtime client is too slow");
-			this.close();
+		if (this.socket.bufferedAmount > MAX_QUEUED_BYTES) {
+			this.fail(4413, "Realtime socket buffer limit exceeded");
 			return;
 		}
 		if (this.socket.bufferedAmount > SOFT_BUFFERED_BYTES) {
+			this.watchForStall();
 			if (!this.retryTimer) this.retryTimer = setTimeout(() => {
 				this.retryTimer = void 0;
 				this.flush();
 			}, 10);
 			return;
 		}
-		const item = this.critical.shift() ?? this.normal.shift();
+		const item = this.next();
 		if (!item) return;
 		this.sending = true;
+		this.watchForStall();
 		try {
 			this.socket.send(item.data, (error) => {
 				if (this.closed) return;
 				this.sending = false;
 				this.queuedBytes -= item.bytes;
+				if (this.stallTimer) clearTimeout(this.stallTimer);
+				this.stallTimer = void 0;
 				if (error) {
-					this.socket.close(1011, "Realtime delivery failed");
-					this.close();
+					this.fail(1011, "Realtime delivery failed");
 					return;
 				}
 				this.flush();
 			});
 		} catch {
 			this.sending = false;
-			this.close();
-			this.socket.close(1011, "Realtime delivery failed");
+			this.fail(1011, "Realtime delivery failed");
 		}
 	}
 };

package/dist/src/runtime-tools/archive.js

@@ -1,8 +1,8 @@
 import { RuntimeError } from "./errors.js";
 import { isAbsolute, join, posix, relative, resolve } from "node:path";
 import { spawn } from "node:child_process";
-import { lstat, mkdir, readdir, readlink, rename, rm, stat } from "node:fs/promises";
 import AdmZip from "adm-zip";
+import { lstat, mkdir, readdir, readlink, rename, rm, stat } from "node:fs/promises";
 //#region src/runtime-tools/archive.ts
 const MAX_ARCHIVE_ENTRIES = 5e4;
 const MAX_TAR_OUTPUT_BYTES = 16 * 1024 * 1024;