@xopcai/xopc 0.0.332 → 0.0.334

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/scenes/host.js

@@ -13,6 +13,7 @@ import { SceneMailObservationService } from "../../scenes/mailObservations.js";
 import { maintainSceneStorage } from "../../scenes/maintenance.js";
 import { SceneMetrics } from "../../scenes/metrics.js";
 import { resolveSceneModelRef } from "../../scenes/model.js";
+import { SceneCapabilityRegistry } from "../../scenes/registry.js";
 import { SceneResultNotifications } from "../../scenes/resultNotifications.js";
 import { SceneRuntime } from "../../scenes/runtime.js";
 import { familyPlanTemplate, mailFollowUpTemplate } from "../../scenes/templates.js";
@@ -20,8 +21,8 @@ import { SceneUserNotesProvider } from "../../scenes/userNotes.js";
 import { createSceneBrowserDispatcher } from "./browserNotifications.js";
 import { GatewaySceneMailContext } from "./mailContext.js";
 import { SlackThreadSource } from "./slackThreadSource.js";
-import { TaskSourceRegistry } from "../../scenes/taskFollowUp/contracts.js";
-import { TaskFollowUpService } from "../../scenes/taskFollowUp/service.js";
+import { SceneSourceRegistry, decisionLogTemplate, taskFollowUpTemplate } from "../../scenes/taskFollowUp/contracts.js";
+import { SceneTaskExecutionService } from "../../scenes/taskFollowUp/service.js";
 //#region src/gateway/scenes/host.ts
 init_providers();
 init_scenes_schema();
@@ -47,30 +48,39 @@ var GatewaySceneHost = class {
 		const repository = new SceneRepository(db);
 		repository.installTemplate(mailFollowUpTemplate);
 		repository.installTemplate(familyPlanTemplate);
+		repository.installTemplate(taskFollowUpTemplate);
+		repository.installTemplate(decisionLogTemplate);
 		const mail = input.mail ?? new GatewaySceneMailContext(db, clock);
-		const providers = [mail, new SceneUserNotesProvider(db, clock)];
+		const providers = new SceneCapabilityRegistry([mail, new SceneUserNotesProvider(db, clock)]);
 		const authorize = (activation) => {
 			if (activation.ownerId !== input.principal.ownerId || activation.workspaceId !== input.principal.workspaceId) return {
 				accountIds: [],
 				contextProviders: [],
 				effectHandlers: []
 			};
-			const accountIds = mail.authorizedAccounts(activation);
+			const grants = providers.list().flatMap((provider) => {
+				const accountIds = provider.authorization?.(activation) ?? null;
+				return accountIds === null ? [] : [{
+					id: provider.id,
+					accountIds
+				}];
+			});
 			return {
-				accountIds,
-				contextProviders: [...activation.scope.kind === "personal" ? ["user_notes"] : [], ...accountIds.length ? ["mail"] : []],
+				accountIds: [...new Set(grants.flatMap((grant) => grant.accountIds))],
+				contextProviders: grants.map((grant) => grant.id),
 				effectHandlers: []
 			};
 		};
 		const grant = async (activation) => authorize(activation);
 		const executor = input.executor ?? new SceneAgentExecutor(() => resolveModel(resolveSceneModelRef(input.config())));
-		const slackThread = new SlackThreadSource(db);
-		const followUps = new TaskFollowUpService(db, {
+		const sourceProviders = new SceneSourceRegistry([new SlackThreadSource(db)]);
+		const activationAdapters = new SceneCapabilityRegistry([new SceneTaskExecutionService(db, {
 			config: input.config,
-			sources: new TaskSourceRegistry([slackThread])
-		});
+			sources: sourceProviders
+		})]);
 		this.http = {
-			followUps,
+			activationAdapters,
+			sourceProviders,
 			repository,
 			mail,
 			mailDiscovery: mail instanceof GatewaySceneMailContext ? mail : void 0,
@@ -99,7 +109,10 @@ var GatewaySceneHost = class {
 		assertSceneStorageReady(this.db);
 		this.runtime.start();
 		const poll = () => {
-			this.http.followUps?.tick().catch((err) => log.error({ err }, "Task follow-up check failed"));
+			for (const adapter of this.http.activationAdapters.list()) adapter.tick().catch((err) => log.error({
+				err,
+				adapter: adapter.id
+			}, "Scene adapter check failed"));
 			try {
 				if (this.clock() >= this.nextMaintenanceAt) {
 					maintainSceneStorage(this.db, this.clock());
@@ -118,7 +131,7 @@ var GatewaySceneHost = class {
 	tick() {
 		if (this.stopped) return Promise.reject(/* @__PURE__ */ new Error("Scene host stopped"));
 		if (this.active) return this.active;
-		const work = Promise.all([this.runtime.tick(), this.http.followUps?.tick()]).then(() => {
+		const work = Promise.all([this.runtime.tick(), ...this.http.activationAdapters.list().map((adapter) => adapter.tick())]).then(() => {
 			if (!this.stopped) this.notifications.drain();
 		});
 		this.active = work.finally(() => {
@@ -131,7 +144,7 @@ var GatewaySceneHost = class {
 		this.stopped = true;
 		if (this.timer) clearInterval(this.timer);
 		this.timer = void 0;
-		await this.http.followUps?.stop();
+		await Promise.all(this.http.activationAdapters.list().map((adapter) => adapter.stop()));
 		await this.runtime.stop();
 		await this.browserDispatcher.stop();
 		await this.active?.catch(() => void 0);

package/dist/src/gateway/scenes/slackThreadSource.d.ts

@@ -2,7 +2,7 @@ import type { DatabaseSync } from 'node:sqlite';
 import { z } from 'zod';
 import { ComposioSessionsAdapter } from '../../connectors/composio-sessions.js';
 import { type ScenePrincipal } from '../../scenes/contracts.js';
-import type { TaskSourceAdapter, SourceSnapshot } from '../../scenes/taskFollowUp/contracts.js';
+import type { SceneSourceAdapter, SourceSnapshot } from '../../scenes/taskFollowUp/contracts.js';
 export declare const slackThreadSchema: z.ZodObject<{
     accountId: z.ZodString;
     teamId: z.ZodString;
@@ -16,7 +16,7 @@ export declare function parseSlackThreadUrl(value: string): {
     threadTs: string;
 };
 /** Read-only connector adapter. Account policy is rechecked before and after every page. */
-export declare class SlackThreadSource implements TaskSourceAdapter {
+export declare class SlackThreadSource implements SceneSourceAdapter {
     private readonly db;
     private readonly adapter;
     readonly id = "slack_thread";

package/dist/src/gateway/security/gateway-scopes.js

@@ -22,6 +22,7 @@ function requiredGatewayScope(method, path) {
 	if (method === "GET" && path === "/api/connectors/approvals") return "sessions.read";
 	if (method === "POST" && path === "/api/connectors/approvals/respond") return "sessions.write";
 	if (path === "/api/agent" || path.startsWith("/api/agent/")) return "agents.run";
+	if (path.startsWith("/api/usage")) return "gateway.admin";
 	if (path.startsWith("/api/agents") || path.startsWith("/api/models")) return methodScope(method, "agents.read", "gateway.admin");
 	if (path.startsWith("/api/sessions") || path.startsWith("/api/side-chats")) return methodScope(method, "sessions.read", "sessions.write");
 	if (path.startsWith("/api/tasks")) return methodScope(method, "tasks.read", "tasks.write");

package/dist/src/gateway/service/active-execution.d.ts

@@ -0,0 +1,19 @@
+import type { TurnOrigin } from '@xopcai/endpoint-tools-protocol';
+export type ActiveExecutionKind = 'chat' | 'side-chat' | 'task' | 'workflow' | 'automation';
+export type ActiveExecutionInitiator = 'user' | 'background';
+export type ActiveExecution = {
+    conversationId: string;
+    runId: string;
+    kind: ActiveExecutionKind;
+    initiator: ActiveExecutionInitiator;
+    phase: 'running';
+    startedAt: number;
+};
+export declare function describeActiveExecution(input: {
+    conversationId: string;
+    runId: string;
+    origin: TurnOrigin;
+    taskRunId?: string;
+    kind?: ActiveExecutionKind;
+    startedAt?: number;
+}): ActiveExecution;

package/dist/src/gateway/service/active-execution.js

@@ -0,0 +1,16 @@
+//#region src/gateway/service/active-execution.ts
+function describeActiveExecution(input) {
+	const { origin } = input;
+	const background = origin.type === "system" && (origin.source === "automation" || origin.source === "heartbeat" || origin.source === "internal");
+	const kind = input.kind ?? (origin.type === "system" && origin.source === "automation" ? "automation" : origin.type === "system" && origin.source === "workflow" ? "workflow" : input.taskRunId ? "task" : "chat");
+	return {
+		conversationId: input.conversationId,
+		runId: input.runId,
+		kind,
+		initiator: background ? "background" : "user",
+		phase: "running",
+		startedAt: input.startedAt ?? Date.now()
+	};
+}
+//#endregion
+export { describeActiveExecution };

package/dist/src/gateway/service/agent-runner.d.ts

@@ -7,6 +7,7 @@ import type { ChannelManager } from '../../channels/manager.js';
 import type { SessionIndex } from '../../session/index.js';
 import { type ClarificationStreamEvent } from '../ephemeral-clarification-waiter.js';
 import type { ClarifyRequestPayload, ClarifyRequestResult } from '../../agent/tools/clarify-tool.js';
+import { type ActiveExecution, type ActiveExecutionKind } from './active-execution.js';
 import type { UserTurnAttachment, UserTurnInput } from '../user-turn-input.js';
 import type { AgentSourceContext, TurnContextRef } from '../../agent/source-context/types.js';
 import { SessionInputCoordinator, type ReplaceLatestTurnInput, type SubmitSessionInput } from './session-input-coordinator.js';
@@ -33,6 +34,7 @@ export declare class GatewayAgentRunner {
     private readonly ephemeralClarifications;
     /** Maps webchat session key → active `runId` for `clarify` tool routing. */
     private readonly activeWebchatRunBySession;
+    private readonly activeExecutionBySession;
     private readonly externalStreamBySession;
     private readonly externalClarificationResponses;
     readonly inputs: SessionInputCoordinator;
@@ -45,9 +47,11 @@ export declare class GatewayAgentRunner {
         conversationId: string;
         runId: string;
     }>;
+    listActiveExecutions(): ActiveExecution[];
     disposeClarifications(): void;
     registerExternalWebchatRun(conversationId: string, runId: string, publish: (event: ClarificationStreamEvent) => void, options?: {
         beforeClarificationResponse?: () => boolean;
+        kind?: ActiveExecutionKind;
     }): void;
     unregisterExternalWebchatRun(conversationId: string, runId: string): void;
     cancelClarificationForRun(runId: string): void;

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

@@ -1,10 +1,11 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { listActiveSessionInputRuns } from "../../storage/sqlite/session-input-repository.js";
+import { listActiveSessionInputExecutions, listActiveSessionInputRuns } from "../../storage/sqlite/session-input-repository.js";
 import { createClarificationWait, getClarification, getClarificationSnapshot, init_clarification_wait_repository, resolveClarification, supersedeActiveClarification } from "../../storage/sqlite/clarification-wait-repository.js";
 import { init_connection_wait_repository, onConnectionWaitChanged } from "../../storage/sqlite/connection-wait-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
 import { EphemeralClarificationWaiter } from "../ephemeral-clarification-waiter.js";
+import { describeActiveExecution } from "./active-execution.js";
 import { runGatewayAgent } from "./run-gateway-agent.js";
 import { fitSourceContextsToBudget } from "../../agent/source-context/budget.js";
 import { SessionInputCoordinator } from "./session-input-coordinator.js";
@@ -29,6 +30,7 @@ var GatewayAgentRunner = class {
 	ephemeralClarifications = new EphemeralClarificationWaiter();
 	/** Maps webchat session key → active `runId` for `clarify` tool routing. */
 	activeWebchatRunBySession = /* @__PURE__ */ new Map();
+	activeExecutionBySession = /* @__PURE__ */ new Map();
 	externalStreamBySession = /* @__PURE__ */ new Map();
 	externalClarificationResponses = /* @__PURE__ */ new Map();
 	inputs;
@@ -118,18 +120,33 @@ var GatewayAgentRunner = class {
 			runId
 		}));
 	}
+	listActiveExecutions() {
+		const executions = new Map(listActiveSessionInputExecutions().map((run) => [run.conversationId, describeActiveExecution(run)]));
+		for (const [conversationId, execution] of this.activeExecutionBySession) executions.set(conversationId, execution);
+		return [...executions.values()];
+	}
 	disposeClarifications() {
 		this.ephemeralClarifications.dispose();
 		this.unsubscribeConnectionWait();
 	}
 	registerExternalWebchatRun(conversationId, runId, publish, options) {
 		this.activeWebchatRunBySession.set(conversationId, runId);
+		this.activeExecutionBySession.set(conversationId, describeActiveExecution({
+			conversationId,
+			runId,
+			origin: {
+				type: "endpoint",
+				endpointId: "electron-side-chat"
+			},
+			kind: options?.kind
+		}));
 		this.externalStreamBySession.set(conversationId, publish);
 		if (options?.beforeClarificationResponse) this.externalClarificationResponses.set(conversationId, options.beforeClarificationResponse);
 	}
 	unregisterExternalWebchatRun(conversationId, runId) {
 		if (this.activeWebchatRunBySession.get(conversationId) === runId) {
 			this.activeWebchatRunBySession.delete(conversationId);
+			this.activeExecutionBySession.delete(conversationId);
 			this.externalStreamBySession.delete(conversationId);
 			this.externalClarificationResponses.delete(conversationId);
 		}
@@ -152,6 +169,7 @@ var GatewayAgentRunner = class {
 			bus: this.opts.bus,
 			runAbortControllers: this.runAbortControllers,
 			activeWebchatRunBySession: this.activeWebchatRunBySession,
+			activeExecutionBySession: this.activeExecutionBySession,
 			sessionIndex: this.opts.sessionIndex,
 			emit: this.opts.emit,
 			publishRealtime: this.opts.publishRealtime,

package/dist/src/gateway/service/marketplace-service.js

@@ -3,12 +3,12 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
 import { init_paths, resolveExtensionsDir } from "../../config/paths.js";
+import { removeSkillsLockEntry } from "../../agent/skills/hub-lock.js";
+import { deleteManagedSkill, installSkillFromZip, listManagedSkillDirs } from "../../agent/skills/managed-store.js";
 import { getExtensionLockfileManager } from "../../extensions/lockfile.js";
 import { AgentPluginStore } from "../../extensions/agent-plugins/store.js";
 import { createSkillConfigManager } from "../../agent/skills/config.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "../../agent/skills/workspace-skills-dir.js";
-import { removeSkillsLockEntry } from "../../agent/skills/hub-lock.js";
-import { deleteManagedSkill, installSkillFromZip, listManagedSkillDirs } from "../../agent/skills/managed-store.js";
 import { normalizeSkillInstallTarget } from "../../agent/skills/install-target.js";
 import { isAgentPluginArchive, withAgentPluginArchive } from "../../extensions/agent-plugins/sources.js";
 import { existsSync, rmSync } from "node:fs";

package/dist/src/gateway/service/run-gateway-agent.d.ts

@@ -6,6 +6,7 @@ import type { SessionIndex } from '../../session/index.js';
 import type { ChatStreamEvent } from '../chat-stream/protocol.js';
 import type { UserTurnAttachment } from '../user-turn-input.js';
 import type { AgentSourceContext } from '../../agent/source-context/types.js';
+import { type ActiveExecution } from './active-execution.js';
 export type RunGatewayAgentYield = ChatStreamEvent;
 export type RunGatewayAgentDeps = {
     config: Config;
@@ -13,6 +14,7 @@ export type RunGatewayAgentDeps = {
     bus: MessageBus;
     runAbortControllers: Map<string, AbortController>;
     activeWebchatRunBySession: Map<string, string>;
+    activeExecutionBySession: Map<string, ActiveExecution>;
     sessionIndex: SessionIndex;
     emit: (type: string, payload: unknown) => void;
     publishRealtime: (topic: string, event: string, data: unknown) => void;

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

@@ -17,6 +17,7 @@ import { markdownNotificationPreview } from "../../notifications/plain-text.js";
 import { resolveWebchatConversationId } from "../resolve-webchat-session-key.js";
 import { recordExplicitRelationshipFollowUp } from "../../user-context/relationship-continuity.js";
 import { coalesceThinkingDeltas } from "../chat-stream/thinking-delta-coalescer.js";
+import { describeActiveExecution } from "./active-execution.js";
 import crypto from "crypto";
 //#region src/gateway/service/run-gateway-agent.ts
 init_connection_wait_repository();
@@ -35,7 +36,7 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 		max: 10
 	}, "Attachments capped for webchat");
 	const runId = runOptions?.runId ?? crypto.randomUUID();
-	const { agentService, bus, runAbortControllers, activeWebchatRunBySession, sessionIndex: sessionIndexFromDeps, emit, publishRealtime, completeRealtimeTopic } = deps;
+	const { agentService, bus, runAbortControllers, activeWebchatRunBySession, activeExecutionBySession, sessionIndex: sessionIndexFromDeps, emit, publishRealtime, completeRealtimeTopic } = deps;
 	const sessionIndex = sessionIndexFromDeps;
 	let taskRun;
 	let taskRunStatus = "failed";
@@ -50,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());
@@ -132,6 +133,12 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 			agentService.beginInboundTurn(conversationId);
 			if (!activeWebchatRunBySession.has(conversationId)) {
 				activeWebchatRunBySession.set(conversationId, runId);
+				activeExecutionBySession.set(conversationId, describeActiveExecution({
+					conversationId,
+					runId,
+					origin,
+					taskRunId: runOptions?.taskRunId
+				}));
 				registeredActiveWebchatRun = true;
 				publishRealtime("sessions", "run.started", {
 					conversationId,
@@ -217,6 +224,7 @@ async function* runGatewayAgent(deps, message, channel, chatId, origin, attachme
 				}
 				if (registeredActiveWebchatRun && activeWebchatRunBySession.get(conversationId) === runId) {
 					activeWebchatRunBySession.delete(conversationId);
+					activeExecutionBySession.delete(conversationId);
 					publishRealtime("sessions", "run.completed", {
 						conversationId,
 						runId,

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;
+}>;

package/dist/src/gateway/service/session-command-service.js

@@ -0,0 +1,81 @@
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../storage/sqlite/session-repository.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
+import { resolveProjectAgentId } from "../../projects/project-agent.js";
+import "../../projects/index.js";
+import { getModelThinking } from "../../providers/model-thinking.js";
+import { withModelConfigLock } from "../../session/model-config-lock.js";
+import { SessionCommandError, acceptSessionCommand, getSessionPreparation, matchSessionInputReceipt, sessionCommandHash } from "../../storage/sqlite/session-creation-repository.js";
+//#region src/gateway/service/session-command-service.ts
+init_providers();
+init_session_repository();
+function validateCreation(service, creation) {
+	const project = creation.projectId ? service.projects.get(creation.projectId) : null;
+	if (creation.projectId && !project) throw new Error("Project not found");
+	if (resolveProjectAgentId({
+		config: service.currentConfig,
+		projects: service.projects,
+		explicitAgentId: creation.agentId,
+		projectId: creation.projectId ?? void 0
+	}) !== creation.agentId) throw new Error("Invalid agent identity");
+	if (project?.workspaceRoot?.trim() && !creation.execution) throw new Error("Select an execution environment");
+	if (creation.execution && !project?.workspaceRoot?.trim()) throw new Error("Project requires a workspace");
+	if (!getModelThinking(resolveModel(creation.model)).options.includes(creation.thinkingLevel)) throw new Error("Unsupported model thinking level");
+}
+async function receiveSessionCommand(service, conversationId, principalId, command, prepareSourceContexts = async () => []) {
+	return withModelConfigLock(conversationId, async () => {
+		const clientMessageId = "commandId" in command ? command.commandId : command.clientMessageId;
+		const existing = matchSessionInputReceipt(conversationId, clientMessageId, principalId, sessionCommandHash(command));
+		if (existing) return sessionCommandSnapshot(service, existing);
+		if ("kind" in command && command.kind === "append") {
+			const session = getSessionMetadata(conversationId);
+			if (!session) throw new SessionCommandError("NOT_FOUND", "Conversation not found");
+			if (session.transcriptId !== command.expectedTranscriptId) throw new SessionCommandError("SESSION_CHANGED", "Conversation transcript changed");
+		}
+		if (service.voiceRealtime?.hasConversation(conversationId)) throw new SessionCommandError("SESSION_BUSY", "End the voice call before sending text");
+		if ("creation" in command) try {
+			validateCreation(service, command.creation);
+		} catch (error) {
+			throw new SessionCommandError("BAD_REQUEST", error instanceof Error ? error.message : "Invalid creation configuration");
+		}
+		const receipt = acceptSessionCommand({
+			conversationId,
+			principalId,
+			command,
+			preparedInput: "input" in command ? await service.prepareSessionCommandInput({
+				conversationId,
+				clientMessageId,
+				delivery: command.kind === "start" ? "next" : command.delivery,
+				content: command.input.content,
+				attachments: command.input.attachments,
+				contextRefs: command.input.contextRefs,
+				sourceContexts: await prepareSourceContexts(),
+				thinking: command.kind === "start" ? command.creation.thinkingLevel : (await service.sessions.getAgentConfig(conversationId)).thinkingLevel,
+				origin: command.origin.type === "endpoint" ? {
+					type: "endpoint",
+					endpointId: command.origin.endpointId
+				} : command.origin
+			}) : void 0,
+			attachProject: (id, projectId) => service.projects.attachSession(id, projectId)
+		});
+		if ("kind" in command && command.kind === "append" && command.delivery === "steer" && receipt.inputId) await service.dispatchAcceptedSessionInput(conversationId, receipt.inputId);
+		return sessionCommandSnapshot(service, receipt);
+	});
+}
+async function sessionCommandSnapshot(service, receipt) {
+	const { principalId: _principal, requestHash: _hash, ...identity } = receipt;
+	const inputState = service.getSessionInputState(receipt.conversationId);
+	return {
+		receipt: {
+			...identity,
+			lifecycle: getSessionPreparation(receipt.conversationId)?.state ?? "ready"
+		},
+		session: await service.sessions.getSession(receipt.conversationId),
+		agentConfig: await service.sessions.getAgentConfig(receipt.conversationId),
+		inputState,
+		effectiveDelivery: inputState.inputs.find((input) => input.id === receipt.inputId)?.effectiveDelivery ?? "next",
+		preparation: getSessionPreparation(receipt.conversationId)
+	};
+}
+//#endregion
+export { receiveSessionCommand, sessionCommandSnapshot };

package/dist/src/gateway/service/session-input-coordinator.d.ts

@@ -44,6 +44,27 @@ export declare class SessionInputCoordinator {
         emit: (type: string, payload: unknown) => void;
     });
     snapshot(conversationId: string): SessionInputState;
+    prepareInput(input: SubmitSessionInput): Promise<{
+        status: "queued";
+        requestedDelivery: SessionInputDelivery;
+        effectiveDelivery: "next";
+        content: string;
+        attachments: UserTurnAttachment[];
+        contextRefs: import("../../agent/source-context/types.js").SourceContextRefSummary[];
+        contextSnapshots: AgentSourceContext[];
+        thinking: string;
+        origin: {
+            type: "endpoint";
+            endpointId: string;
+        } | {
+            type: "channel";
+            channel: string;
+        } | {
+            type: "system";
+            source: "automation" | "cli" | "workflow" | "heartbeat" | "internal";
+        };
+    }>;
+    dispatchAcceptedInput(conversationId: string, inputId: string): Promise<void>;
     private publish;
     private runSubmissionExclusive;
     submit(input: SubmitSessionInput): Promise<{

package/dist/src/gateway/service/session-input-coordinator.js

@@ -42,6 +42,47 @@ var SessionInputCoordinator = class {
 	snapshot(conversationId) {
 		return getSessionInputState(conversationId);
 	}
+	async prepareInput(input) {
+		const attachments = await this.deps.prepareAttachments(input.conversationId, input.attachments);
+		const contexts = fitSourceContextsToBudget([...await this.deps.prepareContexts(input.conversationId, input.contextRefs) ?? [], ...input.sourceContexts ?? []]);
+		return {
+			status: "queued",
+			requestedDelivery: input.delivery,
+			effectiveDelivery: "next",
+			content: input.content.trim(),
+			attachments,
+			contextRefs: contexts.map(summarizeSourceContext),
+			contextSnapshots: contexts,
+			thinking: input.thinking,
+			origin: input.origin
+		};
+	}
+	async dispatchAcceptedInput(conversationId, inputId) {
+		const input = getSessionInputById(conversationId, inputId);
+		if (!input) return;
+		await this.runSubmissionExclusive(input.conversationId, async () => {
+			const row = getSessionInputById(conversationId, inputId);
+			const state = this.snapshot(input.conversationId);
+			if (!row || row.status !== "queued" || row.origin.type === "endpoint" || row.requestedDelivery !== "steer" || !state.activeRunId || row.attachments?.length || row.contextSnapshots?.length || state.preparation && state.preparation.state !== "ready") return;
+			setSessionInputStatus(row.id, "injecting", {
+				effectiveDelivery: "steer",
+				targetRunId: state.activeRunId
+			});
+			try {
+				if (!await this.deps.steer(row.conversationId, row.content)) setSessionInputStatus(row.id, "queued", {
+					effectiveDelivery: "next",
+					targetRunId: null
+				});
+			} catch (error) {
+				log.warn({
+					err: error,
+					conversationId: row.conversationId,
+					inputId
+				}, "Accepted steering input awaits execution recovery");
+			}
+			this.publish(row.conversationId);
+		});
+	}
 	publish(conversationId) {
 		const state = this.snapshot(conversationId);
 		this.deps.emit("session.input-state", state);

package/dist/src/gateway/service/session-preparation-worker.d.ts

@@ -0,0 +1,15 @@
+import type { GatewayService } from '../service.js';
+export declare class SessionPreparationWorker {
+    private readonly service;
+    private timer?;
+    private readonly active;
+    private cleaning;
+    private cleanupTask?;
+    private readonly environments;
+    constructor(service: GatewayService);
+    start(): void;
+    stop(): Promise<void>;
+    wake(conversationId: string): void;
+    private cleanup;
+    private prepare;
+}