@rynx-ai/server 0.1.0 → 0.1.9

package/dist/machine-session-service.js

@@ -0,0 +1,559 @@
+/**
+ * Daemon-owned application service for the first Remote Runtime Session slice.
+ *
+ * This service deliberately has no HTTP, Koa, WebSocket, or Direct-binding
+ * knowledge. Durable records, live state, events, and interruption remain owned
+ * by the daemon process and arrive through narrow injected ports. Local and
+ * Direct adapters can therefore expose the same behavior without copying state
+ * into a Control Plane database.
+ */
+import { SESSION_PROVIDER_IDS, getRuntimeProfile, isSessionProviderId, newSessionId, normalizeSessionTitle, } from "@rynx-ai/core";
+import { REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE, REMOTE_RUNTIME_SESSION_MAX_CURSOR_CHARS, REMOTE_RUNTIME_SESSION_MAX_ID_CHARS, REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE, } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { ensureCodexResumeRollout, } from "@rynx-ai/runtime";
+const DEFAULT_LIST_LIMIT = REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE;
+const MAX_LIST_LIMIT = REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE;
+const DEFAULT_SNAPSHOT_ITEM_LIMIT = REMOTE_RUNTIME_SESSION_DEFAULT_PAGE_SIZE;
+const MAX_SNAPSHOT_ITEM_LIMIT = REMOTE_RUNTIME_SESSION_MAX_PAGE_SIZE;
+const DEFAULT_LIST_PAGE_MAX_BYTES = 48 * 1024;
+const DEFAULT_SNAPSHOT_PAGE_MAX_BYTES = 48 * 1024;
+const MIN_PAGE_MAX_BYTES = 4 * 1024;
+const MAX_PAGE_MAX_BYTES = 56 * 1024;
+const DEFAULT_DIRECTORY_SCAN_LIMIT = 10_000;
+const MAX_DIRECTORY_SCAN_LIMIT = 100_000;
+const MAX_SESSION_ID_CHARS = REMOTE_RUNTIME_SESSION_MAX_ID_CHARS;
+export class MachineSessionServiceInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MachineSessionServiceInputError";
+    }
+}
+/** Expected application failure; adapters decide how to represent it on the wire. */
+export class MachineSessionServiceFailure extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = "MachineSessionServiceFailure";
+    }
+}
+/** Application boundary shared by an in-process Local adapter and Direct RPC. */
+export class MachineSessionService {
+    ports;
+    maxListLimit;
+    listPageMaxBytes;
+    maxSnapshotItemLimit;
+    snapshotPageMaxBytes;
+    directoryScanLimit;
+    constructor(ports, options = {}) {
+        this.ports = ports;
+        this.maxListLimit = boundedInteger(options.maxListLimit ?? MAX_LIST_LIMIT, 1, MAX_LIST_LIMIT, "maxListLimit");
+        this.listPageMaxBytes = boundedInteger(options.listPageMaxBytes ?? DEFAULT_LIST_PAGE_MAX_BYTES, MIN_PAGE_MAX_BYTES, MAX_PAGE_MAX_BYTES, "listPageMaxBytes");
+        this.maxSnapshotItemLimit = boundedInteger(options.maxSnapshotItemLimit ?? MAX_SNAPSHOT_ITEM_LIMIT, 1, MAX_SNAPSHOT_ITEM_LIMIT, "maxSnapshotItemLimit");
+        this.snapshotPageMaxBytes = boundedInteger(options.snapshotPageMaxBytes ?? DEFAULT_SNAPSHOT_PAGE_MAX_BYTES, MIN_PAGE_MAX_BYTES, MAX_PAGE_MAX_BYTES, "snapshotPageMaxBytes");
+        this.directoryScanLimit = boundedInteger(options.directoryScanLimit ?? DEFAULT_DIRECTORY_SCAN_LIMIT, 1, MAX_DIRECTORY_SCAN_LIMIT, "directoryScanLimit");
+    }
+    async list(input = {}) {
+        const limit = requestLimit(input.limit, DEFAULT_LIST_LIMIT, this.maxListLimit, "limit");
+        const cursor = input.cursor === undefined
+            ? undefined
+            : decodeListCursor(input.cursor);
+        const allMetas = this.ports.registry.list();
+        const metas = [...allMetas]
+            .sort(compareMetaRecency)
+            .slice(0, this.directoryScanLimit);
+        const logged = await this.ports.log.listSessions({ limit: this.directoryScanLimit + 1 });
+        const directoryTruncated = allMetas.length > this.directoryScanLimit || logged.length > this.directoryScanLimit;
+        const boundedLogs = logged.slice(0, this.directoryScanLimit);
+        const metaById = new Map(metas.map((meta) => [meta.id, meta]));
+        const logById = new Map(boundedLogs.map((entry) => [entry.sessionId, entry]));
+        const ids = new Set([...metaById.keys(), ...logById.keys()]);
+        const summaries = [...ids]
+            .map((id) => sessionSummary(id, metaById.get(id), logById.get(id), this.ports.runtimeState))
+            .sort(compareSummaryRecency);
+        const afterCursor = cursor === undefined
+            ? summaries
+            : summaries.filter((summary) => isAfterListCursor(summary, cursor));
+        const page = afterCursor.slice(0, limit);
+        while (page.length > 0) {
+            const result = listPage(page, afterCursor.length > page.length, directoryTruncated);
+            if (page.length === 1 || jsonByteLength(result) <= this.listPageMaxBytes)
+                return result;
+            page.pop();
+        }
+        return listPage([], false, directoryTruncated);
+    }
+    async snapshot(input) {
+        const sessionId = validOpaqueToken(input.sessionId, "sessionId", MAX_SESSION_ID_CHARS);
+        const afterId = input.afterId === undefined
+            ? undefined
+            : validOpaqueToken(input.afterId, "afterId", MAX_SESSION_ID_CHARS);
+        const limit = requestLimit(input.limit, DEFAULT_SNAPSHOT_ITEM_LIMIT, this.maxSnapshotItemLimit, "limit");
+        const candidates = (await this.ports.log.list(sessionId, {
+            ...(afterId === undefined ? {} : { afterId }),
+            limit: limit + 1,
+        })).slice(0, limit + 1).map((item) => structuredClone(item));
+        const runtime = cloneRuntimeSnapshot(this.ports.runtimeState.snapshot(sessionId));
+        const empty = snapshotPage(sessionId, [], runtime, false);
+        const items = candidates.slice(0, limit);
+        while (items.length > 0) {
+            const result = snapshotPage(sessionId, items, runtime, candidates.length > items.length);
+            if (items.length === 1 || jsonByteLength(result) <= this.snapshotPageMaxBytes)
+                return result;
+            items.pop();
+        }
+        return empty;
+    }
+    /**
+     * Install a live subscriber synchronously, before returning control to an
+     * adapter. The adapter may now acknowledge readiness and request snapshot
+     * pages while buffering this tail, closing the subscribe/snapshot race.
+     */
+    watch(sessionIdInput, options = {}) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const iterator = this.ports.events.subscribe(sessionId)[Symbol.asyncIterator]();
+        return cancellableWatch(sessionId, iterator, options.signal);
+    }
+    async interrupt(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        return { interrupted: await this.ports.interruption.interrupt(sessionId) };
+    }
+    /** Session-scoped projection of the target daemon's own Agent catalog. */
+    async agentOptions() {
+        const catalog = this.requireAgents();
+        const agents = (await catalog.list()).map((agent) => ({
+            id: agent.id,
+            ...(agent.name === undefined ? {} : { name: agent.name }),
+            ...(agent.runtime === undefined ? {} : { runtime: agent.runtime }),
+            ...(agent.model === undefined ? {} : { model: agent.model }),
+        }));
+        agents.sort((left, right) => (left.name ?? left.id).localeCompare(right.name ?? right.id) || left.id.localeCompare(right.id));
+        return { agents };
+    }
+    /** Target-owned Provider readiness plus the existing Agent preset catalog. */
+    async launchOptions() {
+        const statusCache = new Map();
+        const { agents } = await this.agentOptions();
+        const [providers, launchAgents] = await Promise.all([
+            Promise.all(SESSION_PROVIDER_IDS.map(async (provider) => ({
+                id: provider,
+                name: getRuntimeProfile(provider).displayName,
+                ...await this.runtimeReadiness(provider, statusCache),
+            }))),
+            Promise.all(agents.map(async (agent) => {
+                const execution = this.ports.execution;
+                if (!execution) {
+                    return {
+                        ...agent,
+                        ready: false,
+                        reason: "Session execution is unavailable on this Runtime.",
+                    };
+                }
+                try {
+                    const runtime = await execution.runtime.resolveRuntime({ agentName: agent.id });
+                    return {
+                        ...agent,
+                        runtime,
+                        ...await this.runtimeReadiness(runtime, statusCache),
+                    };
+                }
+                catch {
+                    return {
+                        ...agent,
+                        ready: false,
+                        reason: "Agent execution settings could not be resolved.",
+                    };
+                }
+            })),
+        ]);
+        return { providers, agents: launchAgents };
+    }
+    /** Create target-owned Session identity from one Agent preset or direct Provider. */
+    async create(input) {
+        const hasAgent = input.agent !== undefined;
+        const hasProvider = input.provider !== undefined;
+        if (hasAgent === hasProvider) {
+            throw new MachineSessionServiceInputError("exactly one of agent or provider is required");
+        }
+        let target;
+        if (hasAgent) {
+            const agent = validOpaqueToken(input.agent, "agent", MAX_SESSION_ID_CHARS);
+            const known = (await this.requireAgents().list()).some((candidate) => candidate.id === agent);
+            if (!known)
+                throw new MachineSessionServiceFailure("not_found", "agent not found");
+            target = { agent };
+        }
+        else {
+            if (!isSessionProviderId(input.provider)) {
+                throw new MachineSessionServiceInputError("provider must be codex or claude");
+            }
+            const readiness = await this.runtimeReadiness(input.provider);
+            if (!readiness.ready) {
+                throw new MachineSessionServiceFailure("failed_precondition", readiness.reason ?? "provider is not ready");
+            }
+            target = { provider: input.provider };
+        }
+        const sessionId = newSessionId();
+        this.ports.registry.create({
+            id: sessionId,
+            source: "console",
+            ...target,
+            ...(input.model === undefined ? {} : { model: input.model }),
+            ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort }),
+            ...(input.title === undefined ? {} : { title: input.title }),
+            createdAt: new Date().toISOString(),
+        });
+        return { sessionId };
+    }
+    /** Inject one turn through the target daemon's native single-writer runner. */
+    async sendMessage(sessionIdInput, messageInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        if (typeof messageInput !== "string" || messageInput.length === 0) {
+            throw new MachineSessionServiceInputError("message must be a non-empty string");
+        }
+        const meta = this.ports.registry.get(sessionId);
+        const consoleMeta = meta?.source === "console" ? meta : undefined;
+        if (consoleMeta && !consoleMeta.title) {
+            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(messageInput));
+        }
+        const execution = await this.ensureLiveSession(sessionId, meta);
+        const outcome = await execution.runner.injectMessage(sessionId, messageInput);
+        if (outcome === "failed") {
+            throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`);
+        }
+        if (outcome !== "injected") {
+            throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`);
+        }
+        return { ok: true, injected: true };
+    }
+    /** Explicitly restore the target daemon's live runner without starting a turn. */
+    async startTerminal(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        await this.ensureLiveSession(sessionId);
+        return { ok: true };
+    }
+    async ensureLiveSession(sessionId, meta = this.ports.registry.get(sessionId)) {
+        const execution = this.requireExecution();
+        const consoleMeta = meta?.source === "console" ? meta : undefined;
+        const bound = consoleMeta ? null : ((await execution.sessionStore?.get(sessionId)) ?? null);
+        if (!meta && !bound) {
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        }
+        const liveRuntime = await execution.runtime.resolveRuntime({
+            agentName: consoleMeta?.agent,
+            agentSpec: consoleMeta?.config,
+            provider: meta?.provider ?? bound?.runtime,
+        });
+        if (liveRuntime === "codex") {
+            const codexRecord = await execution.sessionStore?.get(sessionId);
+            if (codexRecord?.codexSessionId) {
+                ensureCodexResumeRollout({
+                    sessionId,
+                    threadId: codexRecord.codexSessionId,
+                    cwd: codexRecord.cwd ?? process.cwd(),
+                    items: await this.ports.log.snapshot(sessionId),
+                });
+            }
+        }
+        const live = await execution.runner.ensureLiveSession(sessionId, {
+            ...(bound?.cwd
+                ? { cwd: bound.cwd }
+                : consoleMeta?.config?.osEnv?.cwd
+                    ? { cwd: consoleMeta.config.osEnv.cwd }
+                    : {}),
+            runtime: liveRuntime,
+            ...(consoleMeta?.reasoningEffort
+                ? { reasoningEffort: consoleMeta.reasoningEffort }
+                : {}),
+            ...(consoleMeta?.agent ? { agentName: consoleMeta.agent } : {}),
+            ...(consoleMeta?.config ? { agentSpec: consoleMeta.config } : {}),
+        });
+        if (!live) {
+            throw new MachineSessionServiceFailure("failed_precondition", `live session unavailable (${liveRuntime})`, execution.runner.lastLiveSessionError?.(sessionId));
+        }
+        return execution;
+    }
+    async resolveInteraction(sessionIdInput, interactionIdInput, resolution) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        const interactionId = validOpaqueToken(interactionIdInput, "interactionId", MAX_SESSION_ID_CHARS);
+        return this.requireExecution().runner.resolveInteraction(sessionId, interactionId, structuredClone(resolution));
+    }
+    async delete(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        try {
+            await this.ports.lifecycle?.beforeDelete?.(sessionId);
+        }
+        catch (error) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Session-owned resources could not be fenced before deletion", error instanceof Error ? error.message : String(error));
+        }
+        this.ports.execution?.runner.stopRunner(sessionId);
+        this.ports.events.close?.(sessionId);
+        this.ports.registry.remove(sessionId);
+        await this.ports.log.deleteSession(sessionId);
+        this.ports.runtimeState.remove?.(sessionId);
+        try {
+            await this.ports.lifecycle?.afterDelete?.(sessionId);
+        }
+        catch (error) {
+            throw new MachineSessionServiceFailure("outcome_unknown", "Session was deleted but resource finalization did not complete", error instanceof Error ? error.message : String(error));
+        }
+        return { ok: true };
+    }
+    requireAgents() {
+        if (!this.ports.agents) {
+            throw new MachineSessionServiceFailure("failed_precondition", "session agent options are unavailable");
+        }
+        return this.ports.agents;
+    }
+    runtimeReadiness(runtime, cache) {
+        const cached = cache?.get(runtime);
+        if (cached)
+            return cached;
+        const pending = this.probeRuntimeReadiness(runtime);
+        cache?.set(runtime, pending);
+        return pending;
+    }
+    async probeRuntimeReadiness(runtime) {
+        const runner = this.ports.execution?.runner;
+        if (!runner?.getStatus) {
+            return { ready: false, reason: "Runtime readiness could not be checked." };
+        }
+        try {
+            const status = await runner.getStatus({ runtime });
+            const ready = status.codex_available &&
+                status.logged_in &&
+                status.session_store_writable &&
+                status.codex_sessions_accessible;
+            if (ready)
+                return { ready: true };
+            return {
+                ready: false,
+                reason: boundedLaunchReason(runtimeSetupReason(runtime, status)),
+            };
+        }
+        catch {
+            return { ready: false, reason: "Runtime readiness check failed." };
+        }
+    }
+    requireExecution() {
+        if (!this.ports.execution) {
+            throw new MachineSessionServiceFailure("failed_precondition", "session execution is unavailable");
+        }
+        return this.ports.execution;
+    }
+}
+/** One-line title derived from the first user message; no model call. */
+export function synthesizeSessionTitle(message, limit = 60) {
+    const collapsed = message.replace(/\s+/g, " ").trim();
+    if (collapsed.length <= limit)
+        return collapsed;
+    return `${collapsed.slice(0, limit - 1).trimEnd()}…`;
+}
+/** Keep target-owned setup diagnostics comfortably inside the wire DTO bound. */
+function boundedLaunchReason(reason) {
+    const normalized = reason.replace(/\s+/g, " ").trim();
+    return [...normalized].slice(0, 512).join("") || "Runtime needs setup.";
+}
+function runtimeSetupReason(runtime, status) {
+    const name = getRuntimeProfile(runtime).displayName;
+    if (!status.codex_available)
+        return `${name} CLI is unavailable.`;
+    if (!status.logged_in)
+        return `${name} is not authenticated.`;
+    if (!status.session_store_writable)
+        return "The Session store is not writable.";
+    if (!status.codex_sessions_accessible)
+        return `${name} Session storage is not accessible.`;
+    return status.issues.find((issue) => issue.trim().length > 0) ??
+        `${name} needs setup before it can start Sessions.`;
+}
+function listPage(sessions, hasMore, directoryTruncated) {
+    return {
+        sessions,
+        hasMore,
+        ...(hasMore && sessions.length > 0 ? { nextCursor: encodeListCursor(sessions.at(-1)) } : {}),
+        directoryTruncated,
+    };
+}
+function isAfterListCursor(summary, cursor) {
+    const updatedAt = summaryUpdatedAt(summary);
+    return updatedAt < cursor.updatedAt || (updatedAt === cursor.updatedAt && summary.id > cursor.id);
+}
+function encodeListCursor(summary) {
+    const cursor = {
+        v: 1,
+        updatedAt: summaryUpdatedAt(summary),
+        id: summary.id,
+    };
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeListCursor(value) {
+    if (value.length === 0 ||
+        value.length > REMOTE_RUNTIME_SESSION_MAX_CURSOR_CHARS ||
+        !/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new MachineSessionServiceInputError("cursor is invalid");
+    }
+    try {
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.length === 0 || bytes.toString("base64url") !== value)
+            throw new Error();
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error();
+        const record = parsed;
+        if (Object.keys(record).length !== 3 ||
+            !("v" in record) ||
+            !("updatedAt" in record) ||
+            !("id" in record)) {
+            throw new Error();
+        }
+        if (record.v !== 1) {
+            throw new MachineSessionServiceInputError("cursor version is not supported");
+        }
+        return {
+            v: 1,
+            updatedAt: validTimestamp(record.updatedAt, "cursor.updatedAt"),
+            id: validOpaqueToken(record.id, "cursor.id", MAX_SESSION_ID_CHARS),
+        };
+    }
+    catch (error) {
+        if (error instanceof MachineSessionServiceInputError)
+            throw error;
+        throw new MachineSessionServiceInputError("cursor is invalid");
+    }
+}
+function snapshotPage(sessionId, items, runtime, hasMore) {
+    return {
+        sessionId,
+        items,
+        runtime,
+        hasMore,
+        ...(hasMore && items.length > 0 ? { nextAfterId: items.at(-1).id } : {}),
+    };
+}
+function sessionSummary(id, meta, log, runtimeState) {
+    const createdAt = meta?.createdAt ?? timestampFromEpoch(log?.createdAt, "createdAt");
+    const updatedAt = log
+        ? timestampFromEpoch(log.updatedAt, "updatedAt")
+        : (meta?.updatedAt ?? createdAt);
+    return {
+        id,
+        ...(meta?.provider === undefined ? {} : { provider: meta.provider }),
+        ...(meta?.agent === undefined ? {} : { agent: meta.agent }),
+        ...(meta?.title === undefined ? {} : { title: normalizeSessionTitle(meta.title) }),
+        status: runtimeState.snapshot(id).status,
+        createdAt: validTimestamp(createdAt, "createdAt"),
+        source: meta?.source ?? "unknown",
+        updatedAt: validTimestamp(updatedAt, "updatedAt"),
+    };
+}
+function compareMetaRecency(left, right) {
+    const leftTime = validTimestamp(left.updatedAt ?? left.createdAt, "updatedAt");
+    const rightTime = validTimestamp(right.updatedAt ?? right.createdAt, "updatedAt");
+    return rightTime.localeCompare(leftTime) || left.id.localeCompare(right.id);
+}
+function compareSummaryRecency(left, right) {
+    return summaryUpdatedAt(right).localeCompare(summaryUpdatedAt(left)) || left.id.localeCompare(right.id);
+}
+function summaryUpdatedAt(summary) {
+    return summary.updatedAt ?? summary.createdAt;
+}
+function cancellableWatch(sessionId, iterator, signal) {
+    let cancelled = false;
+    let cancellationResolve;
+    const cancellation = new Promise((resolve) => {
+        cancellationResolve = resolve;
+    });
+    let cancelPromise;
+    const onAbort = () => {
+        void cancel().catch(() => undefined);
+    };
+    const cancel = () => {
+        if (cancelPromise)
+            return cancelPromise;
+        cancelled = true;
+        cancellationResolve();
+        signal?.removeEventListener("abort", onAbort);
+        cancelPromise = Promise.resolve(iterator.return?.()).then(() => undefined);
+        return cancelPromise;
+    };
+    if (signal?.aborted)
+        void cancel().catch(() => undefined);
+    else
+        signal?.addEventListener("abort", onAbort, { once: true });
+    const consumer = {
+        async next() {
+            if (cancelled)
+                return { value: undefined, done: true };
+            try {
+                const result = await Promise.race([
+                    iterator.next(),
+                    cancellation.then(() => ({ value: undefined, done: true })),
+                ]);
+                if (result.done)
+                    await cancel();
+                return result;
+            }
+            catch (error) {
+                await cancel().catch(() => undefined);
+                throw error;
+            }
+        },
+        async return() {
+            await cancel();
+            return { value: undefined, done: true };
+        },
+    };
+    const watch = {
+        sessionId,
+        cancel,
+        [Symbol.asyncIterator]() {
+            return consumer;
+        },
+    };
+    return watch;
+}
+function cloneRuntimeSnapshot(snapshot) {
+    return {
+        status: snapshot.status,
+        activeResponseIds: [...snapshot.activeResponseIds],
+        pendingInteractions: snapshot.pendingInteractions.map((pending) => ({
+            responseId: pending.responseId,
+            interaction: structuredClone(pending.interaction),
+        })),
+    };
+}
+function requestLimit(value, fallback, maximum, field) {
+    return value === undefined ? Math.min(fallback, maximum) : boundedInteger(value, 1, maximum, field);
+}
+function boundedInteger(value, minimum, maximum, field) {
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new MachineSessionServiceInputError(`${field} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
+function validOpaqueToken(value, field, maximum) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maximum ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new MachineSessionServiceInputError(`${field} must be a non-empty opaque string of at most ${maximum} characters`);
+    }
+    return value;
+}
+function validTimestamp(value, field) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new MachineSessionServiceInputError(`${field} must be a valid timestamp`);
+    }
+    return new Date(value).toISOString();
+}
+function timestampFromEpoch(value, field) {
+    if (value === undefined || !Number.isFinite(value)) {
+        throw new MachineSessionServiceInputError(`${field} is unavailable`);
+    }
+    return new Date(value).toISOString();
+}
+function jsonByteLength(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf8");
+}

package/dist/provider-cli-host.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderCliId, ProviderCliJob, ProviderCliOperation, ProviderCliStatusList } from "@rynx-ai/protocol/control";
+/** Read-only Runtime-owned Provider CLI inventory, safe to expose over Direct Runtime. */
+export interface ProviderCliStatusHost {
+    listStatuses(): Promise<ProviderCliStatusList>;
+}
+/** Local-machine mutation port. Control never forwards this interface remotely. */
+export interface ProviderCliManagementHost extends ProviderCliStatusHost {
+    startOperation(provider: ProviderCliId, operation: ProviderCliOperation): Promise<ProviderCliJob>;
+    getJob(id: string): ProviderCliJob | undefined;
+}

package/dist/provider-cli-host.js

@@ -0,0 +1 @@
+export {};

package/dist/remote-runtime-dispatcher.d.ts

@@ -0,0 +1,94 @@
+import type { RemoteRuntimeEmulatorGesturePoint, RemoteRuntimeRpcRequest, RemoteRuntimeRpcResponse, RemoteRuntimeSequencedSessionEvent } from "@rynx-ai/protocol/remote-runtime-rpc";
+import { type DaemonRuntimeHost } from "./remote-runtime.js";
+import { type MachineSessionService } from "./machine-session-service.js";
+import { type SessionBrowserService } from "./session-browser-service.js";
+import { type SessionEmulatorService } from "./session-emulator-service.js";
+import { type SessionTerminalAttachment, type SessionTerminalHost, type SessionTerminalOpenOptions } from "./session-terminal-host.js";
+import type { ProviderCliStatusHost } from "./provider-cli-host.js";
+/** Binding-neutral application identity established before dispatch. */
+export interface AuthenticatedRuntimeSubject {
+    subjectId: string;
+    effectiveAuthorities: readonly string[];
+}
+export interface RemoteRuntimeDispatchContext {
+    subject: AuthenticatedRuntimeSubject;
+    signal?: AbortSignal;
+}
+export interface RemoteRuntimeDispatcherOptions {
+    runtime: DaemonRuntimeHost;
+    emulator?: RemoteRuntimeEmulatorHost;
+    sessionEmulators?: RemoteRuntimeSessionEmulatorHost;
+    sessions?: RemoteRuntimeSessionHost;
+    browsers?: RemoteRuntimeBrowserHost;
+    terminals?: SessionTerminalHost;
+    providerClis?: ProviderCliStatusHost;
+    /** Optional diagnostic sink. Wire errors deliberately omit internal details. */
+    onError?: (error: unknown, request: RemoteRuntimeRpcRequest) => void;
+}
+export type RemoteRuntimeSessionHost = Pick<MachineSessionService, "list" | "snapshot" | "watch" | "interrupt" | "agentOptions" | "launchOptions" | "create" | "sendMessage" | "startTerminal" | "delete" | "resolveInteraction">;
+export type RemoteRuntimeBrowserHost = Pick<SessionBrowserService, "getState" | "open" | "close" | "createPage" | "closePage" | "activatePage" | "navigatePage" | "goBack" | "goForward" | "reload">;
+export type RemoteRuntimeSessionEmulatorHost = Pick<SessionEmulatorService, "getState" | "listDevices" | "attach" | "detach" | "tap" | "type" | "button" | "rotate" | "launch" | "gesture" | "releaseDevice" | "stopDevice">;
+export interface OpenRemoteRuntimeSessionEvents {
+    sessionId: string;
+    daemonInstanceId: string;
+    events: AsyncIterable<RemoteRuntimeSequencedSessionEvent>;
+    cancel(): Promise<void>;
+}
+export type RemoteRuntimeSessionEventsOpenErrorCode = "unauthorized" | "invalid_request" | "method_not_found" | "internal";
+export declare class RemoteRuntimeSessionEventsOpenError extends Error {
+    readonly code: RemoteRuntimeSessionEventsOpenErrorCode;
+    constructor(code: RemoteRuntimeSessionEventsOpenErrorCode, message: string, options?: ErrorOptions);
+}
+/** Transport-independent emulator application port used by Local and Direct bindings. */
+export interface RemoteRuntimeEmulatorHost {
+    devices(): Promise<unknown[]>;
+    active(): Promise<unknown | null>;
+    deviceSession?(input: {
+        device: string;
+    }): Promise<unknown | null>;
+    attach(device?: string): Promise<unknown>;
+    tap(input: {
+        x: number;
+        y: number;
+        device?: string;
+    }): Promise<unknown>;
+    type(input: {
+        text: string;
+        device?: string;
+        mode?: string;
+    }): Promise<unknown>;
+    button(input: {
+        name?: string;
+        device?: string;
+    }): Promise<unknown>;
+    rotate(input: {
+        orientation: string;
+        device?: string;
+    }): Promise<unknown>;
+    launch(input: {
+        appId: string;
+        device?: string;
+    }): Promise<unknown>;
+    gesture(input: {
+        points: RemoteRuntimeEmulatorGesturePoint[];
+        device?: string;
+    }): Promise<unknown>;
+    kill(input: {
+        device?: string;
+    }): Promise<unknown>;
+    shutdown(input: {
+        device?: string;
+    }): Promise<unknown>;
+}
+/** Transport-neutral V1 unary dispatcher shared by Local and Direct bindings. */
+export declare class RemoteRuntimeDispatcher {
+    private readonly options;
+    constructor(options: RemoteRuntimeDispatcherOptions);
+    dispatch(request: RemoteRuntimeRpcRequest, { subject, signal }: RemoteRuntimeDispatchContext): Promise<RemoteRuntimeRpcResponse>;
+    openSessionEvents(sessionId: string, context: RemoteRuntimeDispatchContext): OpenRemoteRuntimeSessionEvents;
+    openSessionTerminal(sessionId: string, options: SessionTerminalOpenOptions, context: RemoteRuntimeDispatchContext): Promise<SessionTerminalAttachment>;
+    private withEmulator;
+    private withSessions;
+    private withSessionEmulators;
+    private withBrowsers;
+}