@someonegg/agent-hub 0.0.0-stage → 0.7.0

package/dist/server/server/interaction/interaction-service.js

@@ -0,0 +1,276 @@
+import { normalizeMessage } from "./message.js";
+import { paneBindings } from "./pane-binding-manager.js";
+import { isCurrentObservation, observePaneBinding } from "./pane-observation.js";
+import { TerminalActivityService } from "./terminal-activity-service.js";
+import { TerminalPreviewService } from "./terminal-preview-service.js";
+import { attachCommand } from "./tmux-launcher.js";
+import { createTmuxPreviewListener } from "./tmux-preview-listener.js";
+import { validTmuxSessionName } from "./tmux-target.js";
+import { InteractionTransportError, } from "./transport.js";
+export class SessionInteractionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SessionInteractionError";
+    }
+}
+export class SessionInteractionService {
+    sessions;
+    tmux;
+    runtime;
+    enabled;
+    bindings;
+    #busy = new Set();
+    #activity;
+    #previews;
+    #unsubscribe;
+    close() {
+        this.#unsubscribe();
+        this.#previews.close();
+        this.#activity.close();
+    }
+    constructor(sessions, tmux, options) {
+        this.sessions = sessions;
+        this.tmux = tmux;
+        const { enabled, bindings = paneBindings, listener = createTmuxPreviewListener(), runtime, } = options;
+        this.enabled = enabled;
+        this.bindings = bindings;
+        this.runtime = runtime;
+        this.#activity = new TerminalActivityService(listener);
+        this.#previews = new TerminalPreviewService((binding, assertOwner) => this.#perform(() => this.tmux.captureTerminal(binding, assertOwner)), listener);
+        this.#unsubscribe = bindings.subscribe(() => {
+            this.#previews.invalidate();
+            this.#activity.invalidate((id, binding) => bindings.owns(id, binding));
+        });
+    }
+    setBusy(sessionId, busy) {
+        if (busy)
+            this.#busy.add(sessionId);
+        else
+            this.#busy.delete(sessionId);
+    }
+    async resolveTarget(sessionId) {
+        const session = await this.sessions.getInteractionSession(sessionId);
+        if (!session)
+            throw new Error("Session not found");
+        const attempt = this.bindings.latest(sessionId);
+        if (this.bindings.replacement(sessionId) !== null)
+            return null;
+        if (!attempt?.valid)
+            return null;
+        const target = await this.tmux.resolveTarget(attempt);
+        return target && this.bindings.owns(sessionId, target) ? target : null;
+    }
+    async interruptLaunch(target, sessionId, assertActive) {
+        const { binding, interruptSteps } = await this.#prepare(sessionId);
+        if (binding.socketPath !== target.socketPath || binding.sessionName !== target.sessionName)
+            throw new Error("Launch binding changed before interrupt");
+        await this.tmux.sendKeys(target, interruptSteps(), () => {
+            assertActive();
+            this.#assertOwner(sessionId, target);
+        });
+    }
+    sendExitKeys(target, sessionId, keys, assertActive) {
+        return this.tmux.sendKeys(target, [{ keys, delayMs: 0 }], () => {
+            assertActive();
+            this.#assertOwner(sessionId, target);
+        });
+    }
+    killTarget(target, sessionId, assertActive) {
+        return this.tmux.killSession(target, () => {
+            assertActive();
+            this.#assertOwner(sessionId, target);
+        });
+    }
+    async inspectTarget(target, sessionId) {
+        this.#assertOwner(sessionId, target);
+        const state = await this.tmux.inspect(target);
+        this.#assertOwner(sessionId, target);
+        return state;
+    }
+    #assertAvailable(sessionId) {
+        if (this.#busy.has(sessionId))
+            throw new SessionInteractionError("session_busy", "Session management is in progress; input is temporarily unavailable");
+    }
+    async describe(sessionId) {
+        const session = await this.sessions.getInteractionSession(sessionId);
+        if (session === null)
+            return null;
+        return this.describeSnapshot(sessionId, session);
+    }
+    async describeSnapshot(sessionId, session) {
+        if (!this.#supported(session)) {
+            this.#activity.remove(sessionId);
+            return { supported: false, tmux: null, attachCommand: null };
+        }
+        const observed = session.observation ??
+            (await observePaneBinding(sessionId, this.bindings, (attempt) => this.#check(attempt)));
+        if (observed.state !== "alive" || observed.replacement !== null)
+            this.#activity.remove(sessionId);
+        if (observed.sessionId !== sessionId || !isCurrentObservation(observed, this.bindings)) {
+            this.#activity.remove(sessionId);
+            return response("unknown");
+        }
+        switch (observed.state) {
+            case "unbound":
+                return response("unbound");
+            case "invalid":
+                return response("disconnected");
+            case "unknown":
+                return response("unknown");
+            case "exited":
+                return response("disconnected");
+            case "alive": {
+                if (observed.replacement === null)
+                    return {
+                        ...response("connected", observed.target),
+                        activity: this.#activity.read(sessionId, observed.target),
+                    };
+                try {
+                    const replacement = await this.sessions.getInteractionSession(observed.replacement);
+                    if (!isCurrentObservation(observed, this.bindings))
+                        return response("unknown");
+                    return {
+                        ...response("superseded"),
+                        supersededBySessionId: replacement ? observed.replacement : null,
+                    };
+                }
+                catch {
+                    return response("unknown");
+                }
+            }
+        }
+    }
+    #check(attempt) {
+        const connection = this.runtime ? this.runtime.probe(attempt) : this.tmux.connect(attempt);
+        return connection.catch((error) => {
+            if (error instanceof InteractionTransportError && error.code === "disconnected")
+                return null;
+            throw error;
+        });
+    }
+    async matchesTarget(sessionId, target) {
+        const resolved = await this.#prepare(sessionId);
+        return (resolved.binding.socketPath === target.socketPath &&
+            resolved.binding.sessionName === target.sessionName);
+    }
+    async sendMessage(sessionId, message, requireIdle = false) {
+        message = normalizeMessage(message);
+        this.#assertAvailable(sessionId);
+        const { binding } = await this.#prepare(sessionId);
+        this.#assertAvailable(sessionId);
+        this.#assertInputAllowed(sessionId, binding, requireIdle);
+        await this.#perform(() => this.tmux.sendMessage(binding, message, this.#inputGuard(sessionId, binding, requireIdle)));
+    }
+    async handoffPaneBinding(sessionId) {
+        this.#assertAvailable(sessionId);
+        const { binding, bindingCommand } = await this.#prepare(sessionId);
+        this.#assertAvailable(sessionId);
+        await this.#perform(() => this.tmux.sendMessage(binding, bindingCommand, () => this.#assertInputAllowed(sessionId, binding)));
+    }
+    async sendKeys(sessionId, keys, requireIdle = false) {
+        this.#assertAvailable(sessionId);
+        const { binding, keyBindings, interruptSteps } = await this.#prepare(sessionId);
+        this.#assertAvailable(sessionId);
+        this.#assertInputAllowed(sessionId, binding, requireIdle);
+        const mapped = keys.flatMap((key) => key === "interrupt" ? interruptSteps() : [{ keys: [keyBindings[key]], delayMs: 0 }]);
+        await this.#perform(() => this.tmux.sendKeys(binding, mapped, this.#inputGuard(sessionId, binding, requireIdle)));
+    }
+    async captureTerminal(sessionId) {
+        this.#assertAvailable(sessionId);
+        const { binding } = await this.#prepare(sessionId);
+        this.#assertAvailable(sessionId);
+        return this.#previews.captureFresh(binding, () => {
+            this.#assertAvailable(sessionId);
+            this.#assertOwner(sessionId, binding);
+        });
+    }
+    async subscribePreview(sessionId, frame, fail, signal) {
+        const { binding } = await this.#prepare(sessionId);
+        if (signal.aborted)
+            throw new DOMException("Aborted", "AbortError");
+        return this.#previews.subscribe(binding, () => this.#assertOwner(sessionId, binding), frame, fail, signal);
+    }
+    async #prepare(sessionId) {
+        const session = await this.sessions.getInteractionSession(sessionId);
+        if (session === null) {
+            throw new SessionInteractionError("session_not_found", "Session not found");
+        }
+        if (!this.#supported(session)) {
+            throw new SessionInteractionError("interaction_not_supported", "Interaction is not supported for this session");
+        }
+        const interaction = session.interaction;
+        const attempt = this.bindings.latest(sessionId);
+        if (attempt === null || !attempt.valid) {
+            throw new SessionInteractionError("interaction_not_connected", "The session is not connected to a tmux pane");
+        }
+        this.#assertOwner(sessionId, attempt);
+        if (!attempt.socketPath.startsWith("/") || !validTmuxSessionName(attempt.sessionName))
+            throw new SessionInteractionError("interaction_not_connected", "Invalid tmux binding");
+        return {
+            binding: { socketPath: attempt.socketPath, sessionName: attempt.sessionName },
+            interruptSteps: () => interaction.interruptSteps(),
+            keyBindings: interaction.keyBindings,
+            bindingCommand: interaction.bindingCommand,
+        };
+    }
+    #inputGuard(sessionId, binding, requireIdle) {
+        let started = false;
+        return () => {
+            // Check idle at serialized transaction entry. Echo from our own paste or keys
+            // must not prevent Enter or the remaining keys; ownership stays checked throughout.
+            this.#assertInputAllowed(sessionId, binding, requireIdle && !started);
+            started = true;
+        };
+    }
+    #assertInputAllowed(sessionId, binding, requireIdle = false) {
+        this.#assertAvailable(sessionId);
+        this.#assertOwner(sessionId, binding);
+        if (requireIdle && this.#activity.read(sessionId, binding) !== "idle")
+            throw new SessionInteractionError("session_busy", "Session must be live and idle for input");
+    }
+    #assertOwner(sessionId, target) {
+        if (!this.bindings.owns(sessionId, target)) {
+            throw new SessionInteractionError("interaction_not_connected", "The pane binding has been superseded");
+        }
+    }
+    async #perform(operation) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (error instanceof InteractionTransportError) {
+                if (error.code === "disconnected") {
+                    throw new SessionInteractionError("interaction_not_connected", "The tmux target is no longer connected");
+                }
+                if (error.code === "timeout") {
+                    throw new SessionInteractionError("operation_result_unknown", "The tmux operation timed out; its result is unknown and was not retried");
+                }
+                if (error.code === "command_failed") {
+                    throw new SessionInteractionError("interaction_failed", "tmux could not complete the interaction operation");
+                }
+            }
+            throw error;
+        }
+    }
+    #supported(session) {
+        return this.enabled && !session.archived && session.interaction !== null;
+    }
+}
+function response(state, binding) {
+    return {
+        supported: true,
+        tmux: binding
+            ? {
+                socketPath: binding.socketPath,
+                sessionName: binding.sessionName,
+            }
+            : null,
+        state,
+        activity: null,
+        supersededBySessionId: null,
+        attachCommand: binding ? attachCommand(binding.socketPath, binding.sessionName) : null,
+    };
+}
+//# sourceMappingURL=interaction-service.js.map

package/dist/server/server/interaction/message.js

@@ -0,0 +1,19 @@
+import { MAX_INTERACTION_MESSAGE_BYTES } from "../../shared/interaction.js";
+export class MessageValidationError extends Error {
+    code = "invalid_message";
+    constructor(message) {
+        super(message);
+    }
+}
+export function normalizeMessage(message) {
+    const normalized = message.replace(/\r\n?/g, "\n");
+    const bytes = Buffer.byteLength(normalized, "utf8");
+    if (normalized.trim().length === 0) {
+        throw new MessageValidationError("message must not be blank");
+    }
+    if (bytes > MAX_INTERACTION_MESSAGE_BYTES) {
+        throw new MessageValidationError(`message must not exceed ${MAX_INTERACTION_MESSAGE_BYTES} UTF-8 bytes`);
+    }
+    return normalized;
+}
+//# sourceMappingURL=message.js.map

package/dist/server/server/interaction/pane-binding-manager.js

@@ -0,0 +1,62 @@
+/** Retains only the latest session event and latest claim on each tmux target. */
+export class PaneBindingManager {
+    #sessions = new Map();
+    #targets = new Map();
+    #listeners = new Set();
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    submit(event) {
+        const latest = this.#sessions.get(event.sessionId);
+        let changed = false;
+        if (!latest || compare(event, latest) > 0) {
+            this.#sessions.set(event.sessionId, event);
+            changed = true;
+        }
+        if (!event.attempt.valid) {
+            if (changed)
+                for (const listener of this.#listeners)
+                    listener();
+            return;
+        }
+        const key = targetKey(event.attempt);
+        const owner = this.#targets.get(key);
+        if (!owner || compare(event, owner) > 0) {
+            this.#targets.set(key, event);
+            changed = true;
+        }
+        if (changed)
+            for (const listener of this.#listeners)
+                listener();
+    }
+    latest(sessionId) {
+        return this.#sessions.get(sessionId)?.attempt ?? null;
+    }
+    replacement(sessionId) {
+        const event = this.#sessions.get(sessionId);
+        if (!event?.attempt.valid)
+            return null;
+        const owner = this.#targets.get(targetKey(event.attempt));
+        return owner && compare(owner, event) !== 0 ? owner.sessionId : null;
+    }
+    owns(sessionId, target) {
+        const attempt = this.latest(sessionId);
+        return (!!attempt?.valid &&
+            targetKey(attempt) === targetKey(target) &&
+            this.replacement(sessionId) === null);
+    }
+}
+function targetKey(target) {
+    return JSON.stringify([target.socketPath, target.sessionName]);
+}
+function compare(left, right) {
+    return (left.time - right.time ||
+        (left.sessionId < right.sessionId ? -1 : left.sessionId > right.sessionId ? 1 : 0) ||
+        left.ordinal - right.ordinal ||
+        left.position - right.position);
+}
+export const paneBindings = new PaneBindingManager();
+//# sourceMappingURL=pane-binding-manager.js.map

package/dist/server/server/interaction/pane-observation.js

@@ -0,0 +1,31 @@
+export function isCurrentObservation(observation, bindings) {
+    return (observation.attempt === bindings.latest(observation.sessionId) &&
+        observation.replacement === bindings.replacement(observation.sessionId));
+}
+export async function observePaneBinding(sessionId, bindings, probe) {
+    const attempt = bindings.latest(sessionId);
+    const replacement = bindings.replacement(sessionId);
+    const result = (state) => ({
+        sessionId,
+        attempt,
+        replacement,
+        state,
+        target: null,
+    });
+    if (!attempt)
+        return result("unbound");
+    if (!attempt.valid)
+        return result("invalid");
+    try {
+        const target = await probe(attempt);
+        const observation = target
+            ? { sessionId, attempt, replacement, state: "alive", target }
+            : result("exited");
+        return isCurrentObservation(observation, bindings) ? observation : result("unknown");
+    }
+    catch {
+        // A failed check is never evidence of pane death.
+        return result("unknown");
+    }
+}
+//# sourceMappingURL=pane-observation.js.map

package/dist/server/server/interaction/reconcile-session-state.js

@@ -0,0 +1,21 @@
+/** Reconcile the read result with the later interaction observation. */
+export function reconcileSessionState(value) {
+    if (value.session.status !== "archived" && value.interaction.supported) {
+        const connected = value.interaction.state === "connected";
+        value = {
+            ...value,
+            session: {
+                ...value.session,
+                status: connected ? "live" : "normal",
+                resume: connected || value.interaction.state === "unknown"
+                    ? {
+                        allowed: false,
+                        reason: connected ? "Session is already live" : "Connection validation is unknown",
+                    }
+                    : value.session.resume,
+            },
+        };
+    }
+    return value;
+}
+//# sourceMappingURL=reconcile-session-state.js.map

package/dist/server/server/interaction/runtime-capabilities.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime-capabilities.js.map

package/dist/server/server/interaction/session-runtime.js

@@ -0,0 +1,86 @@
+import { resolveResumeDirectory, } from "../management/session-manager.js";
+import { paneBindings } from "./pane-binding-manager.js";
+import { isCurrentObservation, observePaneBinding, } from "./pane-observation.js";
+/** Shared, bounded observations. Errors never prove that a pane exited. */
+export class SessionRuntime {
+    transport;
+    managers;
+    bindings;
+    #pending = new Map();
+    #waiting = [];
+    #activeSockets = new Map();
+    constructor(transport, managers, bindings = paneBindings) {
+        this.transport = transport;
+        this.managers = managers;
+        this.bindings = bindings;
+    }
+    probe(attempt) {
+        if (!attempt.valid)
+            return Promise.reject(new Error("Invalid binding"));
+        const key = JSON.stringify([attempt.socketPath, attempt.sessionName]);
+        const existing = this.#pending.get(key);
+        if (existing)
+            return existing;
+        const query = (async () => {
+            // Different sessions on one socket must reach the transport together so they
+            // can share one list-sessions query, even when there are more than eight sessions.
+            while (!this.#activeSockets.has(attempt.socketPath) && this.#activeSockets.size >= 8)
+                await new Promise((resolve) => this.#waiting.push(resolve));
+            this.#activeSockets.set(attempt.socketPath, (this.#activeSockets.get(attempt.socketPath) ?? 0) + 1);
+            try {
+                return await this.transport.resolveTarget(attempt);
+            }
+            finally {
+                const remaining = this.#activeSockets.get(attempt.socketPath) - 1;
+                if (remaining > 0)
+                    this.#activeSockets.set(attempt.socketPath, remaining);
+                else {
+                    this.#activeSockets.delete(attempt.socketPath);
+                    this.#waiting.splice(0).forEach((resume) => resume());
+                }
+            }
+        })();
+        this.#pending.set(key, query);
+        void query.then(() => this.#pending.delete(key), () => this.#pending.delete(key));
+        return query;
+    }
+    observe(sessionId) {
+        return observePaneBinding(sessionId, this.bindings, (attempt) => this.probe(attempt));
+    }
+    isCurrent(observation) {
+        return isCurrentObservation(observation, this.bindings);
+    }
+    async evaluate(session, detail = true, observation) {
+        let status = session.archived ? "archived" : "normal";
+        const deny = (reason) => ({ status, resume: { allowed: false, reason } });
+        if (session.archived)
+            return deny("Archived sessions cannot be resumed");
+        const observed = observation ?? (await this.observe(session.id));
+        if (observed.sessionId !== session.id || !this.isCurrent(observed))
+            return deny("Pane binding changed during validation");
+        if (observed.state === "invalid")
+            return deny("The latest pane binding is invalid");
+        if (observed.state === "unknown")
+            return deny("Runtime or working directory validation failed");
+        try {
+            if (observed.state === "alive" && observed.replacement === null)
+                status = "live";
+            if (!detail)
+                return deny("Resume validation required");
+            if (status === "live")
+                return deny("Session is already live");
+            const manager = this.managers.get(session.origin.agent);
+            if (!session.sourceId?.trim() || !manager.isValidNativeId(session.sourceId))
+                return deny("Session has no valid native identity");
+            const resolved = await resolveResumeDirectory(manager, session);
+            if (!this.isCurrent(observed))
+                return deny("Pane binding changed during validation");
+            return { status, resume: { allowed: true, reason: null }, directory: resolved.directory };
+        }
+        catch {
+            status = "normal";
+            return deny("Runtime or working directory validation failed");
+        }
+    }
+}
+//# sourceMappingURL=session-runtime.js.map

package/dist/server/server/interaction/terminal-activity-service.js

@@ -0,0 +1,81 @@
+const WINDOW_MS = 5000;
+const LEASE_MS = 30 * 60_000;
+/** Output activity is independent of terminal captures and connection health. */
+export class TerminalActivityService {
+    listen;
+    now;
+    #observations = new Map();
+    #timer;
+    #closed = false;
+    constructor(listen, now = () => performance.now()) {
+        this.listen = listen;
+        this.now = now;
+        this.#timer = setInterval(() => this.invalidate(() => true), 1000);
+        this.#timer.unref();
+    }
+    read(sessionId, binding) {
+        if (this.#closed)
+            return "unknown";
+        let observation = this.#observations.get(sessionId);
+        if (observation &&
+            (observation.failed ||
+                observation.expiresAt <= this.now() ||
+                observation.binding.socketPath !== binding.socketPath ||
+                observation.binding.sessionName !== binding.sessionName)) {
+            this.remove(sessionId);
+            observation = undefined;
+        }
+        if (!observation) {
+            observation = { binding, expiresAt: this.now() + LEASE_MS, failed: false };
+            this.#observations.set(sessionId, observation);
+            this.#subscribe(observation);
+        }
+        observation.expiresAt = this.now() + LEASE_MS;
+        if (observation.failed || observation.readyAt === undefined)
+            return "unknown";
+        if (observation.outputAt !== undefined && this.now() - observation.outputAt < WINDOW_MS)
+            return "working";
+        return this.now() - observation.readyAt >= WINDOW_MS ? "idle" : "unknown";
+    }
+    #subscribe(observation) {
+        const { binding } = observation;
+        const fail = () => {
+            observation.failed = true;
+            observation.readyAt = undefined;
+            observation.outputAt = undefined;
+            observation.subscription?.close();
+        };
+        try {
+            observation.subscription = this.listen(binding, (output) => {
+                if (!observation.failed && output)
+                    observation.outputAt = this.now();
+            }, fail);
+            if (observation.failed)
+                observation.subscription.close();
+            void observation.subscription.ready.then(() => {
+                if (!observation.failed)
+                    observation.readyAt = this.now();
+            }, fail);
+        }
+        catch {
+            fail();
+        }
+    }
+    remove(sessionId) {
+        const observation = this.#observations.get(sessionId);
+        this.#observations.delete(sessionId);
+        observation?.subscription?.close();
+    }
+    invalidate(owns) {
+        for (const [id, observation] of this.#observations)
+            if (observation.expiresAt <= this.now() || !owns(id, observation.binding))
+                this.remove(id);
+    }
+    close() {
+        this.#closed = true;
+        clearInterval(this.#timer);
+        for (const id of this.#observations.keys())
+            this.remove(id);
+    }
+}
+//# sourceMappingURL=terminal-activity-service.js.map

package/dist/server/server/interaction/terminal-preview-diff.js

@@ -0,0 +1,71 @@
+/** Bounded Myers search. Trace stores only frontiers, never historical snapshots. */
+export function diffLines(before, after) {
+    const a = before.split("\n");
+    const b = after.split("\n");
+    let work = 0;
+    let frontier = new Map([[1, 0]]);
+    const trace = [];
+    for (let d = 0; d <= 256; d++) {
+        trace.push(frontier);
+        const next = new Map();
+        for (let k = -d; k <= d; k += 2) {
+            if (++work > 1_000_000)
+                return null;
+            let x = k === -d || (k !== d && (frontier.get(k - 1) ?? -1) < (frontier.get(k + 1) ?? -1))
+                ? (frontier.get(k + 1) ?? 0)
+                : (frontier.get(k - 1) ?? 0) + 1;
+            let y = x - k;
+            while (x < a.length && y < b.length) {
+                if (++work > 1_000_000)
+                    return null;
+                if (a[x] !== b[y])
+                    break;
+                x++;
+                y++;
+            }
+            next.set(k, x);
+            if (x >= a.length && y >= b.length) {
+                const edits = [];
+                for (let depth = d; depth > 0; depth--) {
+                    const previous = trace[depth];
+                    const diagonal = x - y;
+                    const pk = diagonal === -depth ||
+                        (diagonal !== depth &&
+                            (previous.get(diagonal - 1) ?? -1) < (previous.get(diagonal + 1) ?? -1))
+                        ? diagonal + 1
+                        : diagonal - 1;
+                    const px = previous.get(pk);
+                    const py = px - pk;
+                    while (x > px && y > py) {
+                        x--;
+                        y--;
+                    }
+                    if (x === px) {
+                        y--;
+                        edits.push({ x, line: b[y] });
+                    }
+                    else {
+                        x--;
+                        edits.push({ x });
+                    }
+                }
+                const operations = [];
+                for (const edit of edits.reverse()) {
+                    let op = operations.at(-1);
+                    if (!op || edit.x !== op.startLine + op.deleteCount) {
+                        op = { startLine: edit.x, deleteCount: 0, lines: [] };
+                        operations.push(op);
+                    }
+                    if (edit.line === undefined)
+                        op.deleteCount++;
+                    else
+                        op.lines.push(edit.line);
+                }
+                return operations.reverse();
+            }
+        }
+        frontier = next;
+    }
+    return null;
+}
+//# sourceMappingURL=terminal-preview-diff.js.map