@xopcai/xopc 0.0.433 → 0.0.435

package/dist/src/runtime-tools/hdc-dependency-catalog.js

@@ -0,0 +1,83 @@
+import { HDC_VERSION } from "./harmony-paths.js";
+//#region src/runtime-tools/hdc-dependency-catalog.ts
+const HDC_DISTRIBUTION = {
+	package: "hdw2",
+	version: "2.3.10",
+	url: "https://www.npmjs.com/package/hdw2/v/2.3.10",
+	archiveIntegrity: "sha512-Kcbz0pfxgeSN3zeB3LcaAERfwWAz3unUtzrG7GgJy8fSUW5rb8Tb8jG13dEjfx8oVv69NaIhDGQk+fyscDT1UQ=="
+};
+const HDC_FILES = {
+	"darwin-arm64": [{
+		"targetName": "hdc",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-darwin-arm64-hdc",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/mac-arm/hdc",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/mac-arm/hdc"],
+		"sha256": "441f328329dd9906d6ff7f53674db690913a6bf753bea0a400faa5dca7d9b097",
+		"sizeBytes": 6092944
+	}, {
+		"targetName": "libusb_shared.dylib",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-darwin-arm64-libusb_shared.dylib",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/mac-arm/libusb_shared.dylib",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/mac-arm/libusb_shared.dylib"],
+		"sha256": "62df81c6c938e505011f175f30cdbeb208984594d4d1ff66fc3950403d1dd790",
+		"sizeBytes": 192384
+	}],
+	"darwin-x64": [{
+		"targetName": "hdc",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-darwin-x64-hdc",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/mac-x86/hdc",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/mac-x86/hdc"],
+		"sha256": "5daaaec247a75193d3afa31337c9be44c2326a6062adb188abea6a1d7bafb89d",
+		"sizeBytes": 6120144
+	}, {
+		"targetName": "libusb_shared.dylib",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-darwin-x64-libusb_shared.dylib",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/mac-x86/libusb_shared.dylib",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/mac-x86/libusb_shared.dylib"],
+		"sha256": "621462d23360a5a47e228d9067f98618b27cb39575d774ab79824f086edc4caa",
+		"sizeBytes": 176144
+	}],
+	"linux-x64": [{
+		"targetName": "hdc",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-linux-x64-hdc",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/linux-x86/hdc",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/linux-x86/hdc"],
+		"sha256": "b3d929c7af4ba6ddc2638cd68f43e833ed4b8a5a54e9d23dde07ac201e73dd1f",
+		"sizeBytes": 6129376
+	}, {
+		"targetName": "libusb_shared.so",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-linux-x64-libusb_shared.so",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/linux-x86/libusb_shared.so",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/linux-x86/libusb_shared.so"],
+		"sha256": "431e69ebe2f87ac693c3dae032ec82baa3196b9d403139ae9775ccbaf9227887",
+		"sizeBytes": 116512
+	}],
+	"win32-x64": [{
+		"targetName": "hdc.exe",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-win32-x64-hdc.exe",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/win-x86/hdc.exe",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/win-x86/hdc.exe"],
+		"sha256": "fc71ad9853a6b0d28dbfb95fe2908388f26b1cef07cee835626953093f346b11",
+		"sizeBytes": 5480904
+	}, {
+		"targetName": "libusb_shared.dll",
+		"filename": "hdc-3.2.0c-hdw2-2.3.10-win32-x64-libusb_shared.dll",
+		"url": "https://cdn.jsdelivr.net/npm/hdw2@2.3.10/toolchains/win-x86/libusb_shared.dll",
+		"fallbackUrls": ["https://unpkg.com/hdw2@2.3.10/toolchains/win-x86/libusb_shared.dll"],
+		"sha256": "e978bfe2e22f4db7f7afeefa8a9b042cb4cff938830446c86a28a3b46778a3d2",
+		"sizeBytes": 208328
+	}]
+};
+function hdcDependencyAsset(platform, arch) {
+	const files = HDC_FILES[`${platform}-${arch}`];
+	if (!files) return void 0;
+	return {
+		...files[0],
+		kind: "hdc",
+		version: HDC_VERSION,
+		archive: false,
+		files
+	};
+}
+//#endregion
+export { HDC_DISTRIBUTION, hdcDependencyAsset };

package/dist/src/runtime-tools/hdc-files.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimeToolsConfig } from '../config/schema.js';
+import type { PhoneDependencyAsset } from './phone-dependency-catalog.js';
+import type { PhoneDependencyProgress } from './phone-dependencies.js';
+export declare function verifyHdcFiles(root: string, asset: PhoneDependencyAsset): Promise<void>;
+/** Fetch only the host executable and USB library; never download npm packages or SDK archives. */
+export declare function stageHdcFiles(params: {
+    asset: PhoneDependencyAsset;
+    stateDir: string;
+    config: RuntimeToolsConfig;
+    root: string;
+    signal?: AbortSignal;
+    check: () => void;
+    progress: (event: PhoneDependencyProgress) => void;
+}): Promise<string>;

package/dist/src/runtime-tools/hdc-files.js

@@ -0,0 +1,87 @@
+import { HDC_DISTRIBUTION } from "./hdc-dependency-catalog.js";
+import { RuntimeError } from "./errors.js";
+import { downloadVerifiedArchive, sha256File } from "./downloader.js";
+import { runtimeDownloadPath } from "./paths.js";
+import { basename, isAbsolute, join } from "node:path";
+import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+//#region src/runtime-tools/hdc-files.ts
+async function verifyFile(path, file) {
+	const info = await stat(path);
+	if (!info.isFile() || info.size !== file.sizeBytes || await sha256File(path) !== file.sha256) throw new RuntimeError(`HDC file checksum mismatch: ${file.targetName}`, "RUNTIME_CHECKSUM_MISMATCH", "hdc", "verify", true);
+}
+function hdcFiles(asset) {
+	if (asset.files?.length !== 2 || asset.archive) throw new Error("A pinned standalone HDC file catalog is required");
+	for (const file of asset.files) if (basename(file.targetName) !== file.targetName || file.targetName === "." || file.targetName === ".." || file.targetName.includes("\\")) throw new Error("Invalid HDC target name");
+	return asset.files;
+}
+async function verifyHdcFiles(root, asset) {
+	for (const file of hdcFiles(asset)) await verifyFile(join(root, file.targetName), file);
+}
+/** Fetch only the host executable and USB library; never download npm packages or SDK archives. */
+async function stageHdcFiles(params) {
+	const files = hdcFiles(params.asset);
+	const bundle = params.config.download.bundleDir;
+	if (bundle && !isAbsolute(bundle)) throw new Error("Offline bundle directory must be an absolute path on the Gateway host");
+	if (!bundle && params.config.download.source === "website-only") throw new Error("Select Auto or Direct downloads, or configure an offline bundle directory");
+	const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0);
+	let completedBytes = 0;
+	await mkdir(params.root, { recursive: true });
+	for (const file of files) {
+		params.check();
+		let source;
+		if (bundle) source = join(bundle, file.filename);
+		else {
+			params.progress({
+				kind: "hdc",
+				phase: "download",
+				downloadedBytes: completedBytes,
+				totalBytes
+			});
+			for (const url of [file.url, ...file.fallbackUrls ?? []]) {
+				params.check();
+				try {
+					source = await downloadVerifiedArchive({
+						runtime: "hdc",
+						url,
+						expectedSha256: file.sha256,
+						targetPath: runtimeDownloadPath(params.stateDir, file.filename),
+						expectedBytes: file.sizeBytes,
+						timeoutMs: params.config.download.timeoutMs,
+						proxy: params.config.download.proxy,
+						signal: params.signal,
+						onProgress: (downloadedBytes) => params.progress({
+							kind: "hdc",
+							phase: "download",
+							downloadedBytes: completedBytes + downloadedBytes,
+							totalBytes
+						})
+					});
+					break;
+				} catch (error) {
+					params.check();
+					if (!(error instanceof RuntimeError) || error.code !== "RUNTIME_DOWNLOAD_FAILED" || url === file.fallbackUrls?.at(-1) || !file.fallbackUrls?.length) throw error;
+				}
+			}
+		}
+		if (!source) throw new Error("No standalone HDC file source is available");
+		params.check();
+		params.progress({
+			kind: "hdc",
+			phase: "verify"
+		});
+		await verifyFile(source, file);
+		const target = join(params.root, file.targetName);
+		await copyFile(source, target);
+		if (process.platform !== "win32") await chmod(target, 493);
+		completedBytes += file.sizeBytes;
+	}
+	await writeFile(join(params.root, "source.json"), JSON.stringify({
+		distribution: HDC_DISTRIBUTION,
+		version: params.asset.version,
+		files
+	}, null, 2) + "\n", { mode: 384 });
+	params.check();
+	return params.root;
+}
+//#endregion
+export { stageHdcFiles, verifyHdcFiles };

package/dist/src/runtime-tools/phone-dependencies.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'node:events';
+import type { PhoneConfig } from '../phone/contracts.js';
 import type { RuntimeToolsConfig } from '../config/schema.js';
 import { type PhoneDependencyKind } from './phone-dependency-catalog.js';
 export type PhoneDependencyStatus = {
@@ -10,6 +11,8 @@ export type PhoneDependencyStatus = {
     source?: 'managed' | 'system' | 'custom';
     canInstall: boolean;
     error?: string;
+    distribution?: string;
+    downloadUrl?: string;
 };
 export type PhoneDependencyProgress = {
     kind: PhoneDependencyKind;
@@ -27,9 +30,11 @@ export declare class PhoneDependencyManager extends EventEmitter {
         stateDir: string;
         config: RuntimeToolsConfig;
         adbPath?: string;
+        phone?: PhoneConfig;
     });
+    private harmony;
     private operationKey;
-    status(): Promise<PhoneDependencyStatus[]>;
+    status(kinds?: readonly PhoneDependencyKind[]): Promise<PhoneDependencyStatus[]>;
     private progress;
     private verifyServer;
     /** Installation is explicit; readiness checks and phone viewing never provision tools. */

package/dist/src/runtime-tools/phone-dependencies.js

@@ -6,6 +6,7 @@ import { runRuntimeCommand } from "./command.js";
 import { downloadVerifiedArchive, sha256File } from "./downloader.js";
 import { withInstallLock } from "./install-lock.js";
 import { runtimeDownloadPath } from "./paths.js";
+import { HarmonyDependencyManager } from "./harmony-dependencies.js";
 import { dirname, isAbsolute, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
@@ -29,11 +30,24 @@ var PhoneDependencyManager = class extends EventEmitter {
 		super();
 		this.options = options;
 	}
+	harmony() {
+		return new HarmonyDependencyManager({
+			...this.options,
+			phone: this.options.phone ?? { hdcPath: void 0 }
+		}, (event) => this.emit("progress", event));
+	}
 	operationKey(kind) {
 		return `${this.options.stateDir}:${kind}`;
 	}
-	async status() {
-		return Promise.all(["adb", "scrcpy"].map(async (kind) => {
+	async status(kinds = [
+		"adb",
+		"scrcpy",
+		"hdc",
+		"hoscrcpy",
+		"java"
+	]) {
+		return Promise.all(kinds.map(async (kind) => {
+			if (kind === "hdc" || kind === "hoscrcpy" || kind === "java") return this.harmony().status(kind);
 			const canInstall = this.options.config.enabled && Boolean(phoneDependencyAsset(kind));
 			const requestedVersion = kind === "adb" ? ADB_VERSION : SCRCPY_VERSION;
 			if (operations.has(this.operationKey(kind))) return {
@@ -79,6 +93,10 @@ var PhoneDependencyManager = class extends EventEmitter {
 	}
 	/** Installation is explicit; readiness checks and phone viewing never provision tools. */
 	async install(kind, options = {}) {
+		if (kind === "hdc" || kind === "hoscrcpy" || kind === "java") {
+			if (options.sourcePath) throw new Error("Use verified offline bundles for HarmonyOS dependencies");
+			return this.harmony().install(kind, options);
+		}
 		const check = () => {
 			options.signal?.throwIfAborted();
 			options.beforeCommit?.();

package/dist/src/runtime-tools/phone-dependency-catalog.d.ts

@@ -1,7 +1,15 @@
 export declare const ADB_VERSION = "37.0.1";
 export declare const SCRCPY_VERSION = "3.3.3";
 export declare const SCRCPY_SHA256 = "7e70323ba7f259649dd4acce97ac4fefbae8102b2c6d91e2e7be613fd5354be0";
-export type PhoneDependencyKind = 'adb' | 'scrcpy';
+export type PhoneDependencyKind = 'adb' | 'scrcpy' | 'hdc' | 'hoscrcpy' | 'java';
+export type PhoneDependencyFile = {
+    targetName: string;
+    filename: string;
+    url: string;
+    fallbackUrls?: readonly string[];
+    sha256: string;
+    sizeBytes: number;
+};
 export type PhoneDependencyAsset = {
     kind: PhoneDependencyKind;
     version: string;
@@ -9,6 +17,7 @@ export type PhoneDependencyAsset = {
     url: string;
     sha256: string;
     archive: boolean;
+    files?: readonly PhoneDependencyFile[];
 };
 export declare function phoneDependencyAsset(kind: PhoneDependencyKind, platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PhoneDependencyAsset | undefined;
 export declare const managedPhoneAdbDir: (stateDir?: string) => string;

package/dist/src/runtime-tools/phone-dependency-catalog.js

@@ -1,4 +1,5 @@
 import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { harmonyDependencyAsset } from "./harmony-dependency-catalog.js";
 import { join } from "node:path";
 //#region src/runtime-tools/phone-dependency-catalog.ts
 init_paths_state();
@@ -21,6 +22,7 @@ const ADB_ASSETS = {
 	}
 };
 function phoneDependencyAsset(kind, platform = process.platform, arch = process.arch) {
+	if (kind === "hdc" || kind === "hoscrcpy" || kind === "java") return harmonyDependencyAsset(kind, platform, arch);
 	if (kind === "scrcpy") {
 		const filename = `scrcpy-server-v${SCRCPY_VERSION}`;
 		return {

package/dist/src/runtime-tools/types.d.ts

@@ -1,6 +1,6 @@
 import type { RuntimeToolsConfig } from '../config/schema.js';
 export type RuntimeKind = 'node' | 'uv' | 'python';
-export type RuntimeArtifactKind = RuntimeKind | 'adb' | 'scrcpy';
+export type RuntimeArtifactKind = RuntimeKind | 'adb' | 'scrcpy' | 'hdc' | 'hoscrcpy' | 'java';
 export type RuntimeSource = 'managed' | 'system';
 export type RuntimeState = 'disabled' | 'unsupported' | 'absent' | 'installing' | 'ready' | 'degraded' | 'corrupted' | 'failed';
 export interface RuntimeExecutables {

package/dist/src/storage/sqlite/schema.d.ts

@@ -1,7 +1,7 @@
 import type { DatabaseSync } from 'node:sqlite';
 export { SCHEMA_META_SCHEMA_VERSION_KEY, readSchemaVersionForTest, readSchemaVersion, setSchemaVersion, ensureSchemaMetaTable } from './schema-version.js';
-export declare const XOPC_DB_SCHEMA_VERSION = 261;
-export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 261;
+export declare const XOPC_DB_SCHEMA_VERSION = 262;
+export declare const XOPC_DB_BASELINE_SCHEMA_VERSION = 262;
 export { XOPC_DB_MINIMUM_SCHEMA_VERSION } from './schema-upgrade.js';
 /** Initialize fresh databases directly; upgrade supported installed databases transactionally. */
 export declare function ensureXopcDatabaseSchema(db: DatabaseSync): void;

package/dist/src/storage/sqlite/schema.js

@@ -14,18 +14,18 @@ function ensureXopcDatabaseSchema(db) {
 	const hasMetadata = tables.some((row) => row.name === "schema_meta");
 	if (!hasMetadata && tables.length) throw new Error("An unversioned database cannot be initialized");
 	const version = hasMetadata ? readSchemaVersion(db) : 0;
-	if (version > 261) throw new DatabaseSchemaTooNewError(version, 261);
+	if (version > 262) throw new DatabaseSchemaTooNewError(version, 262);
 	if (version > 0 && version < 202) throw new DatabaseSchemaTooOldError(version, 202);
-	if (version >= 202 && version < 261) {
-		upgradeXopcDatabase(db, version, 261);
+	if (version >= 202 && version < 262) {
+		upgradeXopcDatabase(db, version, 262);
 		return;
 	}
-	if (version === 261) return;
+	if (version === 262) return;
 	if (db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name != 'schema_meta' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) throw new Error("An unversioned database cannot be initialized");
 	db.exec("BEGIN IMMEDIATE");
 	try {
 		db.exec(readSqliteAsset("schema.sql"));
-		setSchemaVersion(db, 261);
+		setSchemaVersion(db, 262);
 		db.exec("COMMIT");
 	} catch (error) {
 		db.exec("ROLLBACK");
@@ -40,8 +40,8 @@ var init_schema = __esmMin((() => {
 	init_schema_version();
 	init_schema_errors();
 	init_schema_upgrade();
-	XOPC_DB_SCHEMA_VERSION = 261;
-	XOPC_DB_BASELINE_SCHEMA_VERSION = 261;
+	XOPC_DB_SCHEMA_VERSION = 262;
+	XOPC_DB_BASELINE_SCHEMA_VERSION = 262;
 }));
 //#endregion
 init_schema();

package/dist/src/storage/sqlite/schema.sql

@@ -3642,3 +3642,19 @@ CREATE TABLE browser_setup_runs (
   payload_json TEXT NOT NULL
 );
 CREATE INDEX browser_setup_conversation ON browser_setup_runs(conversation_id, agent_id, updated_at);
+
+CREATE TABLE session_input_control (
+  conversation_id TEXT PRIMARY KEY REFERENCES sessions(conversation_id) ON DELETE CASCADE,
+  paused INTEGER NOT NULL DEFAULT 0,
+  version INTEGER NOT NULL DEFAULT 0,
+  stop_run_id TEXT,
+  permitted_input_id TEXT,
+  review_required INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE session_input_control_operations (
+  conversation_id TEXT NOT NULL REFERENCES sessions(conversation_id) ON DELETE CASCADE,
+  operation_id TEXT NOT NULL,
+  request_json TEXT NOT NULL,
+  run_id TEXT,
+  PRIMARY KEY (conversation_id, operation_id)
+);

package/dist/src/storage/sqlite/session-creation-repository.js

@@ -1,6 +1,7 @@
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
 import { sessionCommandIdentity } from "../../../packages/gateway-contract/src/session-input-command.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { authorizeSessionInput, init_session_input_control_repository } from "./session-input-control-repository.js";
 import { init_session_input_repository, insertSessionInput } from "./session-input-repository.js";
 import { cancelConnectionObjective, init_connection_wait_repository } from "./connection-wait-repository.js";
 import { getSessionMetadata } from "./session-read-repository.js";
@@ -13,6 +14,7 @@ import { createHash, randomUUID } from "node:crypto";
 init_src();
 init_conversation_repository();
 init_session_repository();
+init_session_input_control_repository();
 init_session_input_repository();
 init_connection_wait_repository();
 init_transaction();
@@ -103,6 +105,7 @@ function acceptSessionCommand(input) {
 		}
 		const transcriptId = session.transcriptId;
 		const inputId = input.preparedInput ? randomUUID() : null;
+		if ("kind" in command && command.kind === "append" && inputId) authorizeSessionInput(conversationId, inputId, command.controlVersion, command.execution === "single");
 		if (input.preparedInput && inputId) insertSessionInput({
 			...input.preparedInput,
 			conversationId,

package/dist/src/storage/sqlite/session-input-control-repository.d.ts

@@ -0,0 +1,12 @@
+import { type SessionInputControlCommand, type SessionInputControlView } from '@xopcai/gateway-contract';
+export declare class SessionInputControlConflict extends Error {
+}
+export declare function readSessionInputControl(conversationId: string): SessionInputControlView;
+export declare function hasSessionInputControlOperation(conversationId: string, operationId: string): boolean;
+/** The pause fence commits before any asynchronous cancellation or context preparation. */
+export declare function acceptSessionInputControl(conversationId: string, command: SessionInputControlCommand): {
+    runId?: string;
+    replay: boolean;
+};
+/** Called inside the input acceptance transaction, never as a later HTTP side effect. */
+export declare function authorizeSessionInput(conversationId: string, inputId: string, version?: number, single?: boolean): void;

package/dist/src/storage/sqlite/session-input-control-repository.js

@@ -0,0 +1,83 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
+import { canonicalSessionCommand } from "../../../packages/gateway-contract/src/session-input-command.js";
+import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { init_session_instance_repository, readCurrentTranscriptId } from "./session-instance-repository.js";
+//#region src/storage/sqlite/session-input-control-repository.ts
+function readSessionInputControl(conversationId) {
+	const db = getSqliteDatabase();
+	const row = db.prepare(`SELECT paused, version, stop_run_id, review_required FROM session_input_control WHERE conversation_id = ?`).get(conversationId);
+	const runtime = db.prepare("SELECT active_run_id FROM session_input_runtime WHERE conversation_id = ?").get(conversationId);
+	return {
+		paused: Boolean(row?.paused),
+		version: row?.version ?? 0,
+		reviewRequired: Boolean(row?.review_required),
+		phase: row?.stop_run_id ? "stopping" : runtime?.active_run_id ? "running" : "idle"
+	};
+}
+function hasSessionInputControlOperation(conversationId, operationId) {
+	return Boolean(getSqliteDatabase().prepare("SELECT 1 FROM session_input_control_operations WHERE conversation_id = ? AND operation_id = ?").get(conversationId, operationId));
+}
+/** The pause fence commits before any asynchronous cancellation or context preparation. */
+function acceptSessionInputControl(conversationId, command) {
+	return runSqliteWriteTransaction((db) => {
+		const request = canonicalSessionCommand(command);
+		const previous = db.prepare("SELECT request_json, run_id FROM session_input_control_operations WHERE conversation_id = ? AND operation_id = ?").get(conversationId, command.operationId);
+		if (previous) {
+			if (previous.request_json !== request) throw new SessionInputControlConflict("Operation identity was reused");
+			return {
+				replay: true,
+				runId: db.prepare("SELECT stop_run_id FROM session_input_control WHERE conversation_id = ?").get(conversationId)?.stop_run_id === previous.run_id ? previous.run_id ?? void 0 : void 0
+			};
+		}
+		if (readCurrentTranscriptId(db, conversationId) !== command.expectedTranscriptId) throw new SessionInputControlConflict("Conversation transcript changed");
+		const state = readSessionInputControl(conversationId);
+		if (state.version !== command.expectedVersion) throw new SessionInputControlConflict("Queue control changed");
+		if ((command.action === "resume" || command.action === "send" || command.action === "steer") && state.phase === "stopping") throw new SessionInputControlConflict("Wait for stopping to finish");
+		if ((command.action === "send" || command.action === "steer") && !command.inputId) throw new SessionInputControlConflict("Select an input");
+		if (command.action === "send" && state.phase !== "idle") throw new SessionInputControlConflict("Wait for the active input to finish");
+		if (command.action === "send" && db.prepare("SELECT 1 FROM session_input_control WHERE conversation_id = ? AND permitted_input_id IS NOT NULL").get(conversationId)) throw new SessionInputControlConflict("Another input is awaiting execution");
+		if (command.action === "steer" && state.phase !== "running") throw new SessionInputControlConflict("No active reply to steer");
+		if (command.inputId) {
+			const row = db.prepare("SELECT status, version, expected_transcript_id FROM session_inputs WHERE conversation_id = ? AND id = ?").get(conversationId, command.inputId);
+			if (row?.expected_transcript_id && row.expected_transcript_id !== command.expectedTranscriptId) throw new SessionInputControlConflict("Input belongs to an earlier transcript");
+			if (!row || row.status !== "queued" && !(command.action === "send" && row.status === "interrupted") || row.version !== command.inputVersion) throw new SessionInputControlConflict("This input changed or has started");
+		}
+		const runtime = db.prepare("SELECT active_run_id FROM session_input_runtime WHERE conversation_id = ?").get(conversationId);
+		const runId = command.action === "stop" || command.action === "steer" ? runtime?.active_run_id ?? void 0 : void 0;
+		db.prepare(`INSERT INTO session_input_runtime(conversation_id, revision, updated_at_ms) VALUES (?, 0, ?) ON CONFLICT DO NOTHING`).run(conversationId, Date.now());
+		db.prepare(`INSERT INTO session_input_control(conversation_id) VALUES (?) ON CONFLICT DO NOTHING`).run(conversationId);
+		db.prepare(`UPDATE session_input_control SET paused = ?, version = version + 1,
+      stop_run_id = CASE WHEN ? = 'stop' THEN ? ELSE stop_run_id END,
+      permitted_input_id = ?, review_required = CASE WHEN ? = 'resume' THEN 0 ELSE review_required END WHERE conversation_id = ?`).run(command.action === "steer" ? Number(state.paused) : command.action === "resume" ? 0 : 1, command.action, command.action === "stop" ? runId ?? null : null, command.action === "send" ? command.inputId : null, command.action, conversationId);
+		if (command.action === "send") db.prepare("UPDATE session_inputs SET status = 'queued', effective_delivery = 'next', target_run_id = NULL, version = version + 1, updated_at_ms = ? WHERE id = ?").run(Date.now(), command.inputId);
+		if (command.action === "steer") db.prepare("UPDATE session_inputs SET status = 'injecting', effective_delivery = 'steer', target_run_id = ?, version = version + 1, updated_at_ms = ? WHERE id = ?").run(runId, Date.now(), command.inputId);
+		db.prepare(`INSERT INTO session_input_control_operations(conversation_id, operation_id, request_json, run_id) VALUES (?, ?, ?, ?)`).run(conversationId, command.operationId, request, runId ?? null);
+		db.prepare(`UPDATE session_input_runtime SET revision = revision + 1 WHERE conversation_id = ?`).run(conversationId);
+		return {
+			runId,
+			replay: false
+		};
+	});
+}
+/** Called inside the input acceptance transaction, never as a later HTTP side effect. */
+function authorizeSessionInput(conversationId, inputId, version, single = false) {
+	const db = getSqliteDatabase();
+	const state = readSessionInputControl(conversationId);
+	if (version !== void 0 && state.version !== version) throw new SessionInputControlConflict("Queue control changed; retry after refreshing");
+	if (!single) return;
+	if (version === void 0 || state.phase !== "idle") throw new SessionInputControlConflict("Wait for the active input to finish");
+	if (db.prepare("SELECT permitted_input_id FROM session_input_control WHERE conversation_id = ?").get(conversationId)?.permitted_input_id) throw new SessionInputControlConflict("Another input is awaiting execution");
+	db.prepare(`INSERT INTO session_input_control(conversation_id, paused, permitted_input_id, version) VALUES (?, 1, ?, 1)
+    ON CONFLICT(conversation_id) DO UPDATE SET paused = 1, permitted_input_id = excluded.permitted_input_id, version = version + 1`).run(conversationId, inputId);
+}
+var SessionInputControlConflict;
+var init_session_input_control_repository = __esmMin((() => {
+	init_src();
+	init_session_instance_repository();
+	init_transaction();
+	SessionInputControlConflict = class extends Error {};
+}));
+//#endregion
+init_session_input_control_repository();
+export { SessionInputControlConflict, acceptSessionInputControl, authorizeSessionInput, hasSessionInputControlOperation, init_session_input_control_repository, readSessionInputControl };

package/dist/src/storage/sqlite/session-input-repository.d.ts

@@ -1,3 +1,4 @@
+import { readSessionInputControl } from './session-input-control-repository.js';
 import { getSqliteDatabase } from './transaction.js';
 import { type TurnOrigin } from '@xopcai/endpoint-tools-protocol';
 import type { SessionPreparationView } from '@xopcai/gateway-contract';
@@ -56,6 +57,7 @@ export type SessionInput = {
     updatedAtMs: number;
 };
 export type SessionInputState = {
+    control: ReturnType<typeof readSessionInputControl>;
     preparation?: SessionPreparationView;
     conversationId: string;
     revision: number;

package/dist/src/storage/sqlite/session-input-repository.js

@@ -1,6 +1,7 @@
 import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
 import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "./transaction.js";
 import { init_session_instance_repository, readCurrentTranscriptId } from "./session-instance-repository.js";
+import { init_session_input_control_repository, readSessionInputControl } from "./session-input-control-repository.js";
 import { init_src, turnOriginSchema } from "../../../packages/endpoint-tools-protocol/src/index.js";
 //#region src/storage/sqlite/session-input-repository.ts
 function mapInput(row) {
@@ -50,6 +51,7 @@ function getSessionInputState(conversationId) {
     ('queued','running','injecting','interrupted') ORDER BY position, created_at_ms, id`).all(conversationId);
 	return {
 		conversationId,
+		control: readSessionInputControl(conversationId),
 		...preparation ? { preparation } : {},
 		revision: runtime?.revision ?? 0,
 		activeRunId: runtime?.active_run_id ?? void 0,
@@ -148,19 +150,24 @@ function claimNextSessionInput(conversationId, runId, expectedInputId) {
 		if (db.prepare("SELECT 1 FROM session_tombstones WHERE conversation_id=?").get(conversationId)) return void 0;
 		ensureRuntime(db, conversationId);
 		if (db.prepare(`SELECT active_run_id FROM session_input_runtime WHERE conversation_id = ?`).get(conversationId).active_run_id) return void 0;
+		const control = db.prepare("SELECT paused, stop_run_id, permitted_input_id FROM session_input_control WHERE conversation_id = ?").get(conversationId);
+		if (control?.stop_run_id || control?.paused && !control.permitted_input_id) return void 0;
 		if (db.prepare(`UPDATE session_inputs SET status = 'interrupted', error = 'Session changed before delivery',
       version = version + 1, updated_at_ms = ? WHERE conversation_id = ? AND status = 'queued'
       AND expected_transcript_id IS NOT NULL AND expected_transcript_id IS NOT ?`).run(Date.now(), conversationId, readCurrentTranscriptId(db, conversationId)).changes) bumpSessionInputRevision(db, conversationId);
 		const row = db.prepare(`${SELECT_INPUTS} WHERE conversation_id = ? AND effective_delivery = 'next'
-      AND status = 'queued' AND (kind != 'connection_resume' OR NOT EXISTS (
+      AND status = 'queued' AND (? IS NULL OR id = ?) AND (kind != 'connection_resume' OR NOT EXISTS (
         SELECT 1 FROM session_inputs barrier WHERE barrier.conversation_id = session_inputs.conversation_id
         AND barrier.status = 'interrupted' AND barrier.kind = 'message'
         AND json_extract(barrier.payload_json, '$.connectionBarrier') = 1
         AND json_extract(barrier.payload_json, '$.waitId') = json_extract(session_inputs.payload_json, '$.waitId')
         AND json_extract(barrier.payload_json, '$.objectiveRevision') = json_extract(session_inputs.payload_json, '$.objectiveRevision')
       )) ORDER BY CASE WHEN kind = 'connection_resume' THEN 1 ELSE 0 END,
-      interrupt_requested DESC, position, created_at_ms, id LIMIT 1`).get(conversationId);
-		if (!row) return void 0;
+      interrupt_requested DESC, position, created_at_ms, id LIMIT 1`).get(conversationId, control?.paused ? control.permitted_input_id : null, control?.paused ? control.permitted_input_id : null);
+		if (!row) {
+			if (control?.permitted_input_id) db.prepare("UPDATE session_input_control SET permitted_input_id = NULL WHERE conversation_id = ?").run(conversationId);
+			return;
+		}
 		if (expectedInputId && row.id !== expectedInputId) return void 0;
 		const now = Date.now();
 		if (row.kind === "message" && !JSON.parse(row.payload_json ?? "{}").connectionAction) db.prepare(`UPDATE session_inputs SET payload_json = COALESCE((
@@ -174,9 +181,10 @@ function claimNextSessionInput(conversationId, runId, expectedInputId) {
       updated_at_ms = ? WHERE id = ?`).run(runId, now, row.id);
 		db.prepare(`UPDATE session_input_runtime SET active_run_id = ?, active_input_id = ?,
       revision = revision + 1, updated_at_ms = ? WHERE conversation_id = ?`).run(runId, row.id, now, conversationId);
+		db.prepare("UPDATE session_input_control SET permitted_input_id = NULL WHERE conversation_id = ?").run(conversationId);
 		const claimed = mapInput(db.prepare(`${SELECT_INPUTS} WHERE id = ?`).get(row.id));
 		const hasMaterial = (value) => Boolean(value.attachments_json && JSON.parse(value.attachments_json).length || value.context_snapshots_json && JSON.parse(value.context_snapshots_json).length);
-		if (row.interrupt_requested && !claimed.payload?.connectionAction && !hasMaterial(row)) {
+		if (!control?.paused && row.interrupt_requested && !claimed.payload?.connectionAction && !hasMaterial(row)) {
 			const pending = db.prepare(`${SELECT_INPUTS} WHERE conversation_id = ? AND status = 'queued'
         ORDER BY interrupt_requested DESC, position, created_at_ms, id LIMIT 10`).all(conversationId);
 			for (const next of pending) {
@@ -203,6 +211,7 @@ function finishSessionInputRun(conversationId, runId, status, error) {
 		db.prepare(`UPDATE session_input_runtime SET active_run_id = NULL, active_input_id = NULL,
       revision = revision + 1, updated_at_ms = ?
       WHERE conversation_id = ?`).run(now, conversationId);
+		db.prepare("UPDATE session_input_control SET stop_run_id = NULL WHERE conversation_id = ? AND stop_run_id = ?").run(conversationId, runId);
 		return true;
 	});
 }
@@ -219,7 +228,7 @@ function setSessionInputStatus(id, status, patch) {
 function mutateQueuedSessionInput(input) {
 	return runSqliteWriteTransaction((db) => {
 		const row = db.prepare(`${SELECT_INPUTS} WHERE id = ? AND conversation_id = ?`).get(input.id, input.conversationId);
-		if (!row || row.kind !== "message" || row.status !== "queued" || row.version !== input.version) return false;
+		if (!row || row.kind !== "message" || row.status !== "queued" || row.version !== input.version || row.expected_transcript_id && row.expected_transcript_id !== readCurrentTranscriptId(db, input.conversationId)) return false;
 		const now = Date.now();
 		if (input.position !== void 0) {
 			const ordered = db.prepare(`${SELECT_INPUTS} WHERE conversation_id = ? AND status = 'queued' ORDER BY position, created_at_ms, id`).all(input.conversationId).filter((item) => item.id !== input.id);
@@ -241,6 +250,7 @@ function cancelQueuedSessionInput(conversationId, id, version) {
 		const result = db.prepare(`UPDATE session_inputs SET status = 'cancelled', version = version + 1,
       updated_at_ms = ? WHERE id = ? AND conversation_id = ? AND version = ? AND kind = 'message' AND status IN ('queued','interrupted')`).run(Date.now(), id, conversationId, version);
 		if (Number(result.changes) === 0) return false;
+		db.prepare("UPDATE session_input_control SET permitted_input_id = NULL, version = version + 1 WHERE conversation_id = ? AND permitted_input_id = ?").run(conversationId, id);
 		bumpSessionInputRevision(db, conversationId);
 		return true;
 	});
@@ -268,11 +278,13 @@ function recoverSessionInputState() {
       AND json_extract(payload_json, '$.connectionAction') IN ('continue','cancel')`).run(now);
 		db.prepare(`UPDATE session_input_runtime SET active_run_id = NULL, active_input_id = NULL,
       revision = revision + 1, updated_at_ms = ?`).run(now);
+		db.prepare("UPDATE session_input_control SET stop_run_id = NULL").run();
 		return keys.map((row) => row.conversation_id);
 	});
 }
 var SELECT_INPUTS, SessionInstanceChangedError;
 var init_session_input_repository = __esmMin((() => {
+	init_session_input_control_repository();
 	init_session_instance_repository();
 	init_transaction();
 	init_src();

package/dist/src/storage/sqlite/session-repository.js

@@ -60,6 +60,7 @@ function listSessionMetadata(query = {}) {
 		conditions.push(`s.hidden_from_session_list = 0`);
 		conditions.push(`NOT (s.source_channel = 'automation' AND (COALESCE(CASE WHEN json_valid(s.custom_data_json) THEN json_extract(s.custom_data_json, '$.systemInternal') END, 0) = 1 OR COALESCE(CASE WHEN json_valid(s.custom_data_json) THEN json_extract(s.custom_data_json, '$.automationId') END, '') LIKE 'system-memory-%'))`);
 	}
+	if (query.excludeAutomationRuns) conditions.push(`${SESSION_SOURCE_SQL} != 'automation'`);
 	if (query.rootConversationsOnly && !query.search?.trim()) {
 		conditions.push(`NOT EXISTS (
       SELECT 1 FROM task_sessions worker

package/dist/src/storage/sqlite/session-turn-replace-repository.d.ts

@@ -4,6 +4,8 @@ import type { AgentSourceContext, SourceContextRefSummary } from '../../agent/so
 export type ReplaceLatestSessionTurnInput = {
     conversationId: string;
     targetTurnId: string;
+    expectedTranscriptId?: string;
+    controlVersion?: number;
     clientMessageId: string;
     content: string;
     attachments?: unknown[];