@xopcai/xopc 0.0.333 → 0.0.334

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

@@ -0,0 +1,189 @@
+import { createLogger } from "../../../utils/logger/index.js";
+import { init_logger } from "../../../utils/logger.js";
+import { conversationIdSchema } from "../../../../packages/gateway-contract/src/conversation-identity.js";
+import { sessionInputCommandSchema, sessionMaterializeCommandSchema } from "../../../../packages/gateway-contract/src/session-input-command.js";
+import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
+import { parseSlashCommand } from "../../../chat-commands/command-parse.js";
+import { commandRegistry } from "../../../chat-commands/registry.js";
+import "../../../chat-commands/index.js";
+import { isVoiceLikeAttachment } from "../../../channels/attachments/voice-stt-webchat.js";
+import { SessionCommandError, getSessionInputReceipt, isConversationDeleted, retrySessionPreparation } from "../../../storage/sqlite/session-creation-repository.js";
+import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { browserPageContextToAgentContext } from "../../../agent/source-context/browser-page.js";
+import { receiveSessionCommand, sessionCommandSnapshot } from "../../service/session-command-service.js";
+import { z } from "zod";
+//#region src/gateway/hono/routes/session-command-handler.ts
+init_src();
+init_src$1();
+init_logger();
+const log = createLogger("Gateway:SessionCommand");
+function commandError(c, error) {
+	if (error instanceof SessionCommandError) {
+		const status = error.code === "BAD_REQUEST" ? 400 : error.code === "SESSION_DELETED" ? 410 : error.code === "FORBIDDEN" ? 403 : error.code === "NOT_FOUND" ? 404 : 409;
+		return c.json({
+			ok: false,
+			error: {
+				code: error.code,
+				message: error.message
+			}
+		}, status);
+	}
+	throw error;
+}
+async function handleSessionCommand(c, deps, materialize = false) {
+	const id = conversationIdSchema.safeParse(c.req.param("conversationId"));
+	const body = await c.req.json().catch(() => null);
+	const parsed = materialize ? sessionMaterializeCommandSchema.safeParse(body) : sessionInputCommandSchema.safeParse(body);
+	if (!id.success || !parsed.success) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Invalid session command"
+		}
+	}, 400);
+	const command = parsed.data;
+	const principal = getGatewayPrincipal(c);
+	if ("input" in command) {
+		const origin = command.origin.type === "endpoint" ? endpointTurnClaimSchema.safeParse(command.origin) : null;
+		if (origin && (!origin.success || !deps.service.endpointTools.registry.verifyTurnClaim(origin.data.endpointId, origin.data.token))) return c.json({
+			ok: false,
+			error: {
+				code: "INVALID_ENDPOINT",
+				message: "Endpoint connection is not active"
+			}
+		}, 401);
+		if (!origin && principal.kind !== "owner") return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "CLI input requires owner authentication"
+			}
+		}, 403);
+		if (command.input.browserContexts?.length && (!origin?.success || deps.service.endpointTools.registry.get(origin.data.endpointId)?.kind !== "browser")) return c.json({
+			ok: false,
+			error: {
+				code: "FORBIDDEN",
+				message: "Browser context requires a browser endpoint"
+			}
+		}, 403);
+		const inputError = validateWebchatContent(command.input.content) ?? validateWebchatAttachments(command.input.attachments);
+		if (inputError) return c.json({
+			ok: false,
+			error: {
+				code: "BAD_REQUEST",
+				message: inputError
+			}
+		}, 400);
+		const document = parseUserTurnDocument(command.input.content);
+		const refs = new Set((command.input.contextRefs ?? []).flatMap((ref) => ref.refId ? [ref.refId] : []));
+		if (document && !userTurnDocumentRefIds(document).every((ref) => refs.has(ref))) return c.json({
+			ok: false,
+			error: {
+				code: "BAD_REQUEST",
+				message: "Input contains an unknown context reference"
+			}
+		}, 400);
+		const slash = parseSlashCommand(command.input.content);
+		if (slash && commandRegistry.has(slash.command) && command.input.attachments?.some((attachment) => !isVoiceLikeAttachment(attachment))) return c.json({
+			ok: false,
+			error: {
+				code: "BAD_REQUEST",
+				message: "Slash commands do not accept file or image attachments."
+			}
+		}, 400);
+		if (!command.input.content.trim() && !command.input.attachments?.length && !command.input.contextRefs?.length && !command.input.browserContexts?.length && !command.input.appContext) return c.json({
+			ok: false,
+			error: {
+				code: "BAD_REQUEST",
+				message: "Input is empty"
+			}
+		}, 400);
+	}
+	try {
+		const payload = await receiveSessionCommand(deps.service, id.data, principal.principalId, command, async () => {
+			if (!("input" in command)) return [];
+			const contexts = (command.input.browserContexts ?? []).map(browserPageContextToAgentContext);
+			if (command.input.appContext) contexts.push(await deps.service.prepareSessionAppContext(command.input.appContext, principal, id.data, command.clientMessageId));
+			return contexts;
+		});
+		deps.service.emit("session.input-state", payload.inputState);
+		if ("kind" in command && command.kind === "start") deps.service.emit("session.updated", { key: id.data });
+		if (payload.receipt.lifecycle === "preparing") deps.service.sessionPreparations.wake(id.data);
+		else if (payload.receipt.lifecycle === "ready") deps.service.drainSessionInputs(id.data).catch((err) => {
+			log.error({
+				err,
+				conversationId: id.data
+			}, "Accepted session input drain failed");
+		});
+		return c.json({
+			ok: true,
+			payload
+		}, 202);
+	} catch (error) {
+		return commandError(c, error);
+	}
+}
+async function handleSessionInputReceipt(c, deps) {
+	const id = conversationIdSchema.safeParse(c.req.param("conversationId"));
+	if (!id.success) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Invalid conversation identity"
+		}
+	}, 400);
+	try {
+		const receipt = getSessionInputReceipt(id.data, c.req.param("clientMessageId"), getGatewayPrincipal(c).principalId);
+		if (!receipt) return c.json({
+			ok: false,
+			error: {
+				code: "NOT_RECEIVED",
+				message: "Input has not been received"
+			}
+		}, 404);
+		if (isConversationDeleted(id.data)) return c.json({
+			ok: false,
+			error: {
+				code: "SESSION_DELETED",
+				message: "Conversation was deleted"
+			}
+		}, 410);
+		return c.json({
+			ok: true,
+			payload: await sessionCommandSnapshot(deps.service, receipt)
+		});
+	} catch (error) {
+		return commandError(c, error);
+	}
+}
+const preparationRetrySchema = z.strictObject({
+	operationId: z.string().uuid(),
+	expectedRevision: z.number().int().positive(),
+	idempotencyKey: z.string().min(1).max(128)
+});
+async function handleSessionPreparationRetry(c, deps) {
+	const id = conversationIdSchema.safeParse(c.req.param("conversationId"));
+	const parsed = preparationRetrySchema.safeParse(await c.req.json().catch(() => null));
+	if (!id.success || !parsed.success) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Invalid preparation retry"
+		}
+	}, 400);
+	try {
+		const preparation = retrySessionPreparation(id.data, getGatewayPrincipal(c).principalId, parsed.data);
+		deps.service.sessionPreparations.wake(id.data);
+		return c.json({
+			ok: true,
+			payload: { preparation }
+		}, 202);
+	} catch (error) {
+		return commandError(c, error);
+	}
+}
+//#endregion
+export { handleSessionCommand, handleSessionInputReceipt, handleSessionPreparationRetry };

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

@@ -20,13 +20,19 @@ export declare function submitSessionInput(c: Context, deps: AuthenticatedRouteD
         code: string;
         message: string;
     };
-}, 403 | 400 | 409, "json">) | (Response & import("hono").TypedResponse<{
+}, 400 | 409 | 403, "json">) | (Response & import("hono").TypedResponse<{
     ok: true;
     payload: {
         conversationId: string;
         ok: true;
         effectiveDelivery: import("../../../storage/sqlite/session-input-repository.js").SessionInputDelivery;
         state: {
+            preparation?: {
+                operationId: string;
+                revision: number;
+                state: "ready" | "preparing" | "preparation_failed";
+                lastError?: string;
+            };
             conversationId: string;
             revision: number;
             activeRunId?: string;
@@ -155,7 +161,7 @@ export declare function replaceLatestSessionTurn(c: Context, deps: Authenticated
 }, 409, "json">) | (Response & import("hono").TypedResponse<{
     ok: false;
     error: {
-        code: "TARGET_NOT_FOUND" | "NOT_LATEST" | "SESSION_BUSY" | "BAD_REQUEST" | "CONTEXT_UNAVAILABLE";
+        code: "BAD_REQUEST" | "SESSION_BUSY" | "TARGET_NOT_FOUND" | "NOT_LATEST" | "CONTEXT_UNAVAILABLE";
         message: string;
     };
 }, 404 | 400 | 409, "json">) | (Response & import("hono").TypedResponse<{
@@ -165,6 +171,12 @@ export declare function replaceLatestSessionTurn(c: Context, deps: Authenticated
         ok: true;
         effectiveDelivery: "next";
         state: {
+            preparation?: {
+                operationId: string;
+                revision: number;
+                state: "ready" | "preparing" | "preparation_failed";
+                lastError?: string;
+            };
             conversationId: string;
             revision: number;
             activeRunId?: string;

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

@@ -1,12 +1,12 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
-import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { browserPageContextsInputSchema } from "../../../../packages/gateway-contract/src/browser-page-context.js";
+import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.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 { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
 import { isTaskDestructiveCommand } from "../../../session/reset-triggers.js";
 import { parseSlashCommand } from "../../../chat-commands/command-parse.js";

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

@@ -1,13 +1,8 @@
 import { deleteBrowserTabBinding, init_browser_tab_binding_repository } from "../../../storage/sqlite/browser-tab-binding-repository.js";
-import { conversationIdSchema } from "../../../../packages/gateway-contract/src/conversation-identity.js";
 import { SessionDiscoveryQuerySchema } from "../../../../packages/gateway-contract/src/session-identity.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import "../../../session/types.js";
-import { deleteSessionRecord, init_session_repository } from "../../../storage/sqlite/session-repository.js";
 import { SidebarLayoutConflictError, getSidebarLayout, init_sidebar_layout_repository, replaceSidebarLayout, sortBySidebarLayout } from "../../../storage/sqlite/sidebar-layout-repository.js";
-import { ConversationAlreadyExistsError, createConversation, init_conversation_repository } from "../../../storage/sqlite/conversation-repository.js";
-import { resolveProjectAgentId } from "../../../projects/project-agent.js";
-import "../../../projects/index.js";
 import { messagesToClientHistory } from "../../../session/client-history.js";
 import { evictEmbeddedSessionRunner } from "../../../agent/embedded/session-runner.js";
 import { SessionEnvironmentService } from "../../../execution-environments/session-environment-service.js";
@@ -17,11 +12,8 @@ import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js"
 import { patchChatModelConfig } from "./chat-model-config.js";
 import { getSessionContextSummary } from "../../session-context-summary.js";
 import { respondStartupUnavailable } from "../lib/startup-unavailable.js";
-import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/sessions.ts
 init_src();
-init_conversation_repository();
-init_session_repository();
 init_browser_tab_binding_repository();
 init_sidebar_layout_repository();
 const log = createGatewayRouteLogger("Sessions");
@@ -36,9 +28,6 @@ const DEFAULT_SIDEBAR_STALE_DAYS = 60;
 function isSessionType(value) {
 	return SESSION_TYPES.has(value);
 }
-function parseExecutionMode(value) {
-	return value === "local_checkout" || value === "managed_worktree" ? value : void 0;
-}
 function ensureGatewayReadyForSessions(c, service, method) {
 	if (service.isGatewayReady()) return null;
 	return respondStartupUnavailable(c, method);
@@ -71,26 +60,6 @@ function isHistoryCursor(value) {
 	if (!/^(0|[1-9]\d*)$/.test(value)) return false;
 	return Number.isSafeInteger(Number(value));
 }
-function buildDirectSessionMetadata(params) {
-	return {
-		sourceChannel: params.source,
-		sourceChatId: [
-			params.accountId,
-			"direct",
-			params.peerId
-		].join(":"),
-		sessionType: "chat",
-		hiddenFromSessionList: true,
-		routing: {
-			agentId: params.agentId,
-			source: params.source,
-			accountId: params.accountId,
-			peerKind: "direct",
-			peerId: params.peerId
-		},
-		customData: { genericNewChatShell: params.source === "webchat" && params.peerId.startsWith("chat_") }
-	};
-}
 function registerSessionsRoutes(authenticated, deps) {
 	const { service } = deps;
 	const environments = new SessionEnvironmentService();
@@ -288,143 +257,6 @@ function registerSessionsRoutes(authenticated, deps) {
 			throw error;
 		}
 	});
-	authenticated.post("/api/sessions", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		if (body.conversationId !== void 0 && !conversationIdSchema.safeParse(body.conversationId).success) return c.json({
-			ok: false,
-			error: "conversationId must be a UUID"
-		}, 400);
-		const channel = typeof body.channel === "string" && body.channel.trim() ? body.channel.trim() : "webchat";
-		const projectId = typeof body.projectId === "string" && body.projectId.trim() ? body.projectId.trim() : void 0;
-		const routingCfg = service.currentConfig;
-		const project = projectId ? service.projects.get(projectId) : null;
-		if (projectId && !project) return c.json({
-			ok: false,
-			error: "Project not found"
-		}, 404);
-		const requestedExecutionMode = parseExecutionMode(body.executionMode);
-		if (body.executionMode !== void 0 && !requestedExecutionMode) return c.json({
-			ok: false,
-			error: "Invalid execution mode"
-		}, 400);
-		if (requestedExecutionMode && !project) return c.json({
-			ok: false,
-			error: "An execution mode requires a project"
-		}, 400);
-		let agentId;
-		try {
-			agentId = resolveProjectAgentId({
-				config: routingCfg,
-				projects: service.projects,
-				explicitAgentId: typeof body.agentId === "string" ? body.agentId : void 0,
-				projectId
-			});
-		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 400);
-		}
-		const chatId = (typeof body.chat_id === "string" && body.chat_id.trim() ? body.chat_id.trim() : void 0) ?? `chat_${randomUUID()}`;
-		const metadata = {
-			agentId,
-			...buildDirectSessionMetadata({
-				agentId,
-				source: channel,
-				accountId: "default",
-				peerId: chatId
-			}),
-			...channel === "tui" ? {
-				hiddenFromSessionList: true,
-				customData: { genericNewChatShell: true }
-			} : {}
-		};
-		let conversationId;
-		try {
-			conversationId = createConversation(metadata, "", body.conversationId).key;
-		} catch (error) {
-			if (error instanceof ConversationAlreadyExistsError) return c.json({
-				ok: false,
-				error: error.message
-			}, 409);
-			throw error;
-		}
-		let environment;
-		if (project && (project.workspaceRoot?.trim() || requestedExecutionMode)) try {
-			environment = await environments.attach({
-				conversationId,
-				project,
-				mode: requestedExecutionMode,
-				baseRef: typeof body.baseRef === "string" ? body.baseRef : void 0
-			});
-		} catch (error) {
-			deleteSessionRecord(conversationId);
-			return c.json({
-				ok: false,
-				code: "execution_environment_unavailable",
-				error: error instanceof Error ? error.message : String(error)
-			}, 409);
-		}
-		try {
-			await service.sessionIndexInstance.saveMessages(conversationId, [], { metadata });
-			if (projectId) service.projects.attachSession(conversationId, projectId);
-		} catch (error) {
-			await service.sessions.delete(conversationId).catch(() => void 0);
-			await environments.release(conversationId).catch(() => void 0);
-			throw error;
-		}
-		const rawInitialConfig = body.initialAgentConfig && typeof body.initialAgentConfig === "object" ? body.initialAgentConfig : {};
-		const model = typeof rawInitialConfig.model === "string" && rawInitialConfig.model.trim() ? rawInitialConfig.model.trim() : void 0;
-		const thinkingLevel = typeof rawInitialConfig.thinkingLevel === "string" && rawInitialConfig.thinkingLevel.trim() ? rawInitialConfig.thinkingLevel.trim() : void 0;
-		const initialAgentConfig = {
-			...model ? { model } : {},
-			...thinkingLevel ? { thinkingLevel } : {},
-			...body.temporary === true ? { userContextMode: "temporary" } : {}
-		};
-		if (channel === "webchat" && model) {
-			const result = await service.sessions.initializeChatModel(conversationId, model, thinkingLevel);
-			if (!result.ok) {
-				await service.sessions.delete(conversationId).catch(() => void 0);
-				await environments.release(conversationId).catch((error) => {
-					log.warn({
-						err: error,
-						conversationId
-					}, "Invalid new session model and execution environment cleanup failed");
-				});
-				return c.json({
-					ok: false,
-					error: result.error
-				}, 400);
-			}
-			delete initialAgentConfig.model;
-			delete initialAgentConfig.thinkingLevel;
-		}
-		if (Object.keys(initialAgentConfig).length > 0) {
-			const result = await service.sessions.patchAgentConfig(conversationId, initialAgentConfig);
-			if (!result.ok) {
-				await service.sessions.delete(conversationId).catch(() => void 0);
-				await environments.release(conversationId).catch((error) => {
-					log.warn({
-						err: error,
-						conversationId
-					}, "Invalid new session config and execution environment cleanup failed");
-				});
-				return c.json({
-					ok: false,
-					error: result.error
-				}, 400);
-			}
-		}
-		if (body.createdSurface === "browser_extension") await service.sessions.patch(conversationId, { customData: { createdSurface: "browser_extension" } });
-		const session = await service.sessions.getSession(conversationId);
-		const agentConfig = channel === "webchat" ? await service.sessions.getFixedAgentConfig(conversationId) : void 0;
-		return c.json({
-			conversationId,
-			session,
-			agentConfig,
-			...environment ? { environment } : {}
-		}, 201);
-	});
 	authenticated.get("/api/sessions", async (c) => {
 		const blocked = ensureGatewayReadyForSessions(c, service, "sessions.list");
 		if (blocked) return blocked;

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

@@ -5,9 +5,9 @@ import { init_src } from "../../../../packages/gateway-contract/src/index.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 { TaskContextMutationOutputSchema } from "../../../tasks/capabilities/relations.js";
 import { TaskDeleteOutputSchema } from "../../../tasks/capabilities/management.js";
 import { TaskMutationOutputSchema } from "../../../tasks/capabilities/write.js";

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

@@ -3,7 +3,8 @@ import { collectTuiStartupResources } from "../../../tui/tui-startup-resources.j
 function registerTuiRoutes(authenticated, deps) {
 	authenticated.get("/api/tui/startup-resources", (c) => {
 		const conversationId = c.req.query("conversationId")?.trim() || void 0;
-		const payload = collectTuiStartupResources(deps.service.currentConfig, conversationId);
+		const agentId = conversationId ? void 0 : c.req.query("agentId")?.trim();
+		const payload = collectTuiStartupResources(deps.service.currentConfig, conversationId, { agentId });
 		return c.json({
 			ok: true,
 			payload

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

@@ -14,6 +14,7 @@ import { mergeTtsConfigFromAppConfig } from "../../../voice/tts/merge-config.js"
 import { listSttProvidersForApi } from "../../../voice/stt/list-providers.js";
 import "../../../voice/tts/index.js";
 import { withModelConfigLock } from "../../../session/model-config-lock.js";
+import { getSessionPreparation } from "../../../storage/sqlite/session-creation-repository.js";
 import { resolveOmniRoute } from "../../../voice/realtime/omniRoute.js";
 import { VoiceSessionCreationError, resolveStreamingStt, resolveStreamingTts } from "../../../voice/realtime/runtime.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
@@ -268,6 +269,14 @@ function registerVoiceRoutes(authenticated, deps) {
 			}
 		}, 400);
 		try {
+			const preparation = parsed.data.conversationId ? getSessionPreparation(parsed.data.conversationId) : void 0;
+			if (preparation && preparation.state !== "ready") return c.json({
+				ok: false,
+				error: {
+					code: "SESSION_PREPARING",
+					message: "Session environment is not ready"
+				}
+			}, 409);
 			if (action === "preflight") {
 				await service.voiceRealtime.preflight(parsed.data);
 				return c.json({ ok: true });

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 { ConfigSchema, init_schema } from "../config/schema.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/lock.js

@@ -1,8 +1,8 @@
 import path from "node:path";
 import fs from "node:fs";
 import { createHash } from "node:crypto";
-import net from "node:net";
 import fs$1 from "node:fs/promises";
+import net from "node:net";
 import { homedir } from "os";
 //#region src/gateway/lock.ts
 /**

package/dist/src/gateway/resolve-webchat-session-key.d.ts

@@ -10,6 +10,6 @@ export type ResolveWebchatConversationIdResult = {
 };
 /**
  * Resolve the server-owned session key for webchat `/api/agent` requests.
- * Creation is intentionally out-of-band via `POST /api/sessions`.
+ * Ordinary creation is accepted atomically by a start input command.
  */
 export declare function resolveWebchatConversationId(input: ResolveWebchatConversationIdInput): ResolveWebchatConversationIdResult;

package/dist/src/gateway/resolve-webchat-session-key.js

@@ -1,13 +1,13 @@
 //#region src/gateway/resolve-webchat-session-key.ts
 /**
 * Resolve the server-owned session key for webchat `/api/agent` requests.
-* Creation is intentionally out-of-band via `POST /api/sessions`.
+* Ordinary creation is accepted atomically by a start input command.
 */
 function resolveWebchatConversationId(input) {
 	const raw = input.conversationId?.trim() ?? "";
 	if (!raw) return {
 		ok: false,
-		error: "Missing conversationId; create sessions via POST /api/sessions"
+		error: "Missing conversationId"
 	};
 	return {
 		ok: true,

package/dist/src/gateway/service/run-gateway-agent.js

@@ -51,7 +51,7 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 		if (resolved.ok === false) throw new Error(resolved.error);
 		webchatConversationId = resolved.conversationId;
 		const meta = await sessionIndex.getSessionMetadata(webchatConversationId);
-		if (!meta) throw new Error("Session not found; create sessions via POST /api/sessions");
+		if (!meta) throw new Error("Session not found; submit a start input command first");
 		webchatTranscriptId = meta?.transcriptId;
 		webchatMetadata = meta;
 		runAbortControllers.set(runId, new AbortController());

package/dist/src/gateway/service/session-command-service.d.ts

@@ -0,0 +1,34 @@
+import type { SessionInputCommand, SessionMaterializeCommand } from '@xopcai/gateway-contract';
+import type { AgentSourceContext } from '../../agent/source-context/types.js';
+import { type SessionInputReceipt } from '../../storage/sqlite/session-creation-repository.js';
+import type { GatewayService } from '../service.js';
+export declare function receiveSessionCommand(service: GatewayService, conversationId: string, principalId: string, command: SessionInputCommand | SessionMaterializeCommand, prepareSourceContexts?: () => Promise<AgentSourceContext[]>): Promise<{
+    receipt: {
+        lifecycle: import("@xopcai/gateway-contract").SessionPreparationState;
+        conversationId: string;
+        clientMessageId: string;
+        inputId: string | null;
+        transcriptId: string;
+        acceptedAt: number;
+    };
+    session: import("../../session/types.js").SessionDetail;
+    agentConfig: import("../../agent/session/session-inspector.js").SessionAgentConfigView;
+    inputState: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
+    effectiveDelivery: import("../../storage/sqlite/session-input-repository.js").SessionInputDelivery;
+    preparation: import("../../storage/sqlite/session-creation-repository.js").SessionPreparation;
+}>;
+export declare function sessionCommandSnapshot(service: GatewayService, receipt: SessionInputReceipt): Promise<{
+    receipt: {
+        lifecycle: import("@xopcai/gateway-contract").SessionPreparationState;
+        conversationId: string;
+        clientMessageId: string;
+        inputId: string | null;
+        transcriptId: string;
+        acceptedAt: number;
+    };
+    session: import("../../session/types.js").SessionDetail;
+    agentConfig: import("../../agent/session/session-inspector.js").SessionAgentConfigView;
+    inputState: import("../../storage/sqlite/session-input-repository.js").SessionInputState;
+    effectiveDelivery: import("../../storage/sqlite/session-input-repository.js").SessionInputDelivery;
+    preparation: import("../../storage/sqlite/session-creation-repository.js").SessionPreparation;
+}>;