ue-mcp 1.3.3 → 1.3.4

package/dist/dialog-guard.d.ts

@@ -0,0 +1,287 @@
+/**
+ * The dialog guard. One per editor, one implementation, one decision.
+ *
+ * A modal dialog parks Unreal's game thread. Nothing may run while one is up,
+ * whatever raised it and whichever route the caller came in by, and the caller
+ * has to be forced to deal with it rather than being left to notice.
+ *
+ * Everything that can reach an editor delegates here:
+ *
+ *   GuardedBridge.call   every bridge request, so tool actions, flow steps,
+ *                        nested flow runs and handler-internal calls are all
+ *                        covered at the one boundary they share
+ *   tool dispatch        actions served in this process, which never reach the
+ *                        bridge and so cannot be refused by it
+ *   the HTTP routes      the same, through the same object
+ *
+ * There is no second copy of this logic. A call site decides nothing; it asks
+ * `check` and does what it says.
+ *
+ * DETECTION is proactive. The plugin publishes the active modal to its status
+ * file from the modal-loop tick, which is the one tick that keeps running while
+ * the game thread is parked, so a watcher there knows a dialog appeared even if
+ * nothing is being called and the session is completely idle. The plugin's own
+ * refusal and an on-demand probe both feed the same state, so a dialog is
+ * caught by whichever notices first.
+ */
+import type { EditorSession } from "./session.js";
+import type { IBridge } from "./bridge.js";
+import type { ElicitFn } from "./types.js";
+import type { DialogMode } from "./user-state.js";
+/** The dialog, as every layer describes it. */
+export interface BlockingDialog {
+    title: string;
+    message: string;
+    buttons: string[];
+    choices: Array<{
+        buttonLabel: string;
+        respondWith: string;
+    }>;
+}
+export declare function isModalSafeMethod(method: string): boolean;
+/** True for the refusal the plugin's own gate emits. */
+export declare function isDialogRefusal(v: unknown): boolean;
+/** A button press, and whether the editor confirmed it landed. */
+export interface DialogPress {
+    button: string;
+    confirmed: boolean;
+}
+/** What a caller must do about this call. */
+export type GuardDecision = {
+    allow: true;
+} | {
+    allow: false;
+    refusal: Record<string, unknown>;
+};
+export interface GuardDeps {
+    /** How this machine wants a blocking dialog handled. */
+    mode: () => DialogMode;
+    /** Reads the live dialog list. Modal-safe, so it answers while parked. */
+    probe: () => Promise<unknown>;
+    /** Presses one button by label. */
+    press: (buttonLabel: string) => Promise<unknown>;
+    /** Present only when the connected client advertised elicitation. */
+    elicit?: () => ElicitFn | undefined;
+    /**
+     * The editor's published status snapshot, polled so a modal raised while
+     * nothing is running is still noticed.
+     *
+     * Supplied rather than read here, so this is not a second reader of the
+     * same file: the caller passes the instance-aware one, which prefers
+     * `status.<pid>.json` over the shared file two editors of one project
+     * take turns writing, and which reports how old the snapshot is.
+     */
+    readSnapshot?: () => {
+        modal?: unknown;
+        ageSeconds?: number;
+    } | null;
+    /** Whether the bridge socket is currently up. */
+    isConnected?: () => boolean;
+}
+/**
+ * How old a status file may be and still describe a live editor. The plugin
+ * flushes it on a timer while running, so anything older is a leftover.
+ */
+export declare const STATUS_STALE_AFTER_MS = 15000;
+export declare class DialogGuard {
+    private deps;
+    private blocking;
+    /** True when the only evidence of a dialog is a file nobody is updating. */
+    private staleStatus;
+    /** What the last interactive answer did, for callers that report it. */
+    private pressed;
+    /** Identity of the dialog the last press was aimed at. */
+    private lastAsked;
+    /** The ask in flight, so parallel calls share it instead of each asking. */
+    private asking;
+    /** Which dialog that in-flight ask is about. */
+    private askingFor;
+    private poll;
+    constructor(deps: GuardDeps);
+    /** Replace the dependencies without losing what the guard knows. */
+    setDeps(deps: GuardDeps): void;
+    /** What the last interactive answer did, or null if nothing was pressed. */
+    get lastPressed(): DialogPress | null;
+    /** The dialog currently believed to be blocking, if any. */
+    get current(): BlockingDialog | null;
+    /** How this machine wants a blocking dialog handled, before elicitation. */
+    get mode(): DialogMode;
+    /** Whether there is anybody to put an elicitation form in front of. */
+    get canElicit(): boolean;
+    /** Record a dialog. Called by the watcher, a probe, or a plugin refusal. */
+    note(dialog: BlockingDialog): void;
+    /**
+     * Record that the editor is clear.
+     *
+     * Only ever called with positive evidence: a probe that ANSWERED and listed
+     * nothing, or a non-modal-safe bridge call that ran. A failed probe is not
+     * evidence and must never land here, or a dropped socket would disarm the
+     * guard while the dialog is still on screen.
+     */
+    clear(): void;
+    /**
+     * Whether this mode hands over the calls that press a dialog's buttons.
+     *
+     * The one place that rule lives. stop_editor computed `mode !== "defer"`
+     * itself, so the same decision existed twice and could drift: the guard's
+     * defer branch omits `choices` entirely while the other kept a stripped
+     * version of them.
+     *
+     * Not conditioned on elicitation. `auto` exists precisely for a caller
+     * with nobody to ask, so withholding the press calls from it would leave
+     * that caller no way to answer at all. Routes with nobody on them are
+     * handled where they are known about, in `refusal`.
+     */
+    static handsOverPressCalls(mode: DialogMode, canElicit?: boolean): boolean;
+    /**
+     * The mode as it actually applies, given whether anyone can be asked.
+     *
+     * interactive with no channel to a person is not interactive: it would
+     * report "interactive" and hand the buttons to the agent anyway, which is
+     * auto's behaviour under a mode whose contract is that a PERSON chooses.
+     * The mode resolver already falls back to defer when the client advertises
+     * no elicitation; this applies the same rule everywhere else.
+     */
+    static effectiveMode(mode: DialogMode, canElicit: boolean): DialogMode;
+    /** True when this bridge method may be sent while a modal is up. */
+    static bridgeAllowed(method: string): boolean;
+    /** True when this tool action may run while a modal is up. */
+    static actionAllowed(taskName: string): boolean;
+    /**
+     * The single decision.
+     *
+     * `subject` is the bridge method or the `tool.action` being attempted, and is
+     * only used to name it back to the caller and to check the allow list.
+     */
+    check(subject: string, kind: "bridge" | "action", opts?: {
+        canElicit?: boolean;
+    }): Promise<GuardDecision>;
+    /**
+     * Recovery actions: always permitted, whatever is latched.
+     *
+     * Relaunching or stopping an editor is how a caller gets out of a state
+     * where the editor is stuck. An editor whose socket has parked while its
+     * status thread keeps publishing holds the latch fresh indefinitely, so
+     * gating these refused the only way back forever. They still report the
+     * dialog through the same stamp every allowed read carries.
+     */
+    static isRecoveryAction(taskName: string): boolean;
+    /**
+     * The decision about a dialog the caller ALREADY has, with no probe.
+     *
+     * `check` is this plus finding the dialog first. A caller that just read it
+     * (stop_editor, which must read before it sends a quit) uses this, so the
+     * mode is applied in exactly one place without paying for a second read or
+     * risking a re-probe that answers differently.
+     */
+    decideFor(subject: string, dialog: BlockingDialog, opts?: {
+        canElicit?: boolean;
+    }): Promise<GuardDecision>;
+    /**
+     * Re-read what is on screen, deciding nothing.
+     *
+     * `check` applies the mode, which in interactive raises a form and presses a
+     * button. A caller that has just answered a dialog by hand and only wants
+     * the state corrected must not do that: it would put a form up for whatever
+     * prompt the first answer surfaced and press a button on it, unasked.
+     */
+    refresh(): Promise<void>;
+    /**
+     * What is on screen right now.
+     *
+     * The watcher usually knows already. When it does not, ask the editor. A
+     * probe that THROWS is not an answer: the state is left exactly as it was,
+     * so an unreachable editor cannot disarm the guard.
+     */
+    private currentDialog;
+    /** Put it to the person; return the button they chose, or null. */
+    private askUser;
+    /** The one refusal shape, whatever the route and whatever the mode. */
+    refusal(subject: string, dialog: BlockingDialog, opts?: {
+        canElicit?: boolean;
+    }): Record<string, unknown>;
+    /**
+     * The refusal shape. ONE definition, so every route hands a caller the same
+     * fields to branch on.
+     *
+     * Static because stop_editor builds its refusal without an instance: it runs
+     * over its own transport while a quit may be in flight. It used to assemble
+     * its own object, which carried `dialogBlocking` but no `refusedMethod`,
+     * `dialogTitle`, `dialogMessage` or `error`, so a client reading those got
+     * undefined depending on which route refused it.
+     */
+    static describeRefusal(subject: string, dialog: BlockingDialog, resolvedMode: DialogMode, canElicit?: boolean): Record<string, unknown>;
+    /**
+     * Learn from a bridge reply.
+     *
+     * A refusal names the dialog. Anything else is evidence the game thread ran,
+     * but ONLY for a method the plugin would have refused: a modal-safe method
+     * answers either way, so reading the dialog list must not be mistaken for the
+     * dialog having gone.
+     */
+    observe(method: string, result: unknown): void;
+    /**
+     * Watch the editor's status file so a dialog raised while nothing is running
+     * is known immediately, rather than at the next call.
+     *
+     * The plugin refreshes that file from the modal-loop tick, which keeps firing
+     * while the game thread is parked. Watching costs nothing on the hot path and
+     * needs no bridge traffic; the poll is a fallback for platforms where the
+     * watch does not fire.
+     */
+    startWatching(intervalMs?: number): void;
+    stopWatching(): void;
+}
+/**
+ * A raw bridge that still cannot press a dialog button.
+ *
+ * Plugin guard tasks run on the RAW bridge on purpose: routing them through
+ * GuardedBridge would re-enter the guard pipeline that is running them. That
+ * left one real hole, because `set_dialog_policy` is modal-safe in the plugin
+ * and WILL be served: a guard task could arm a policy that answers the modal
+ * already on screen, with no person involved, under a mode that promises
+ * exactly the opposite.
+ *
+ * Applied to the SESSION's bridge, so it holds on every path: the guarded
+ * bridge wraps it, guard tasks get it, and a handler reaching for
+ * `ctx.session.bridge` directly gets it too. Wrapping only one caller left the
+ * escape one line away.
+ *
+ * This refuses those two methods and nothing else, from state already held, so
+ * it adds no round-trip and cannot recurse.
+ */
+export declare function withoutDialogActuation<T extends IBridge>(session: EditorSession, raw: T): T;
+/**
+ * Mark a successful result as coming from an editor that is blocked.
+ *
+ * An allowed read still SAYS a dialog is up: get_status is the first call every
+ * client makes, and reporting a healthy editor while the game thread is parked
+ * is the one answer it must never give.
+ *
+ * `editorBlockedByDialog` deliberately is NOT `dialogBlocking`, which means
+ * "this call was refused". Stamping that here would have a client treat a
+ * successful read as a refusal.
+ *
+ * Returns the value unchanged when there is nothing to say, or when the shape
+ * cannot carry the fields: an array is `typeof "object"`, so it took the
+ * properties and then lost them silently in JSON.stringify.
+ */
+export declare function stampBlockedEditor(data: unknown, dialog: BlockingDialog | null): unknown;
+/**
+ * The guard for a session, created from the session itself if it has none.
+ *
+ * The gate fails closed: no guard means the boundary cannot establish whether
+ * a modal is up, so it refuses. That is only safe if every session HAS one,
+ * and guards were created in one startup pass, so a session registered any
+ * other way had none and was refused everything it ever tried.
+ *
+ * Every dependency here is derivable from the session, so there is no reason
+ * for that gap to exist. What startup adds on top is the client's elicitation
+ * capability, which is not knowable here; guardFor replaces the deps, so that
+ * pass upgrades this guard rather than competing with it.
+ */
+export declare function ensureGuard(session: EditorSession): Promise<DialogGuard>;
+export declare function guardFor(session: EditorSession, deps: GuardDeps): DialogGuard;
+export declare function existingGuard(session: EditorSession): DialogGuard | undefined;
+/** Test seam. */
+export declare function forgetGuard(session: EditorSession): void;