@executablemd/runtime 0.8.1 → 0.9.1

package/esm/executable-observer.js

@@ -0,0 +1,42 @@
+/**
+ * Observing which executable build a command actually runs
+ * (specs/native-agent-session-launch-spec.md §Executable binding).
+ *
+ * A provider session whose identity XMD chose itself only means something
+ * while the build that established it can be reproduced. Two builds of one
+ * provider accept the same session identity and disagree silently about what
+ * it names — that is how issue #519's first gate produced a healthy-looking
+ * session with no history in it. So before a session crosses an ownership
+ * boundary, the exact file about to run is observed, and enough is retained to
+ * recognize it later.
+ *
+ * What is observed is a canonical path, the SHA-256 of that file's bytes, and
+ * whatever the file says when asked its version. Only the last two ever become
+ * durable: a path stops being true when a build moves, and names host layout
+ * besides.
+ *
+ * This is a plain capability the trusted host builds and hands directly to the
+ * provider that needs it. It is deliberately not a contextual Api. Executable
+ * validation decides which retained history is accepted, and a decision
+ * document middleware could replace is not one — a replaceable resolver could
+ * point the observation at a different binary than the one that runs.
+ *
+ * Provider-specific meaning is not this module's business: which command to
+ * run, what a version string looks like, and what to do about a mismatch
+ * belong to the adapter that knows the provider.
+ */
+/**
+ * An observation failure that names its reason.
+ *
+ * The reason is the actionable part and the message is diagnostic. Neither is
+ * retained: a caller turns this into its own refusal, and the paths involved
+ * stay on this side of that boundary.
+ */
+export class ExecutableObservationError extends Error {
+    name = "ExecutableObservationError";
+    refusal;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.refusal = options.refusal;
+    }
+}

package/esm/files.js

@@ -13,8 +13,10 @@
  * replacement — admission, resolution, target classification, parent creation,
  * and commit — rather than a sequence a caller assembles, because assembling it
  * from outside is what would let a path admitted by one provider be used by
- * another. `API.Fs` remains the low-level host surface a host adapter is built
- * on; it is not this boundary.
+ * another. `deleteFile` is the same kind of whole act, and every operation here
+ * is mandatory: a provider with nothing to offer for one does not omit it and
+ * leave a document reaching the host instead. `API.Fs` remains the low-level
+ * host surface a host adapter is built on; it is not this boundary.
  *
  * `checkFilePath` is the one exception, and it is deliberately weak: pure path
  * arithmetic, no filesystem access, and nothing usable comes back — no path, no
@@ -47,6 +49,7 @@
  * and `instanceof` answers false across them, which would turn a provider
  * failure into an unrecognized throw exactly when it matters most.
  */
+import "./_dnt.polyfills.js";
 import { createApi } from "@effectionx/context-api";
 /** The stable discriminant on ordinary filesystem failure data. */
 export const FILES_ERROR = "executablemd.runtime.files-error/v1";
@@ -79,6 +82,7 @@ const REASONS = [
 const OPERATIONS = [
     "check-file-path",
     "read",
+    "delete",
     "glob",
     "temporary-directory",
 ];
@@ -548,6 +552,10 @@ export const Files = createApi("executablemd.runtime.files", {
         throw new FilesProviderUnavailableError();
     },
     // deno-lint-ignore require-yield
+    *deleteFile(_input) {
+        throw new FilesProviderUnavailableError();
+    },
+    // deno-lint-ignore require-yield
     *globFiles(_input) {
         throw new FilesProviderUnavailableError();
     },

package/esm/host-files.js

@@ -35,6 +35,25 @@
  * has nothing to resolve, and `rename` replaces the link rather than following
  * it wherever it points.
  *
+ * ## Deletions
+ *
+ * A deletion is the mirror image of a write in the one place that matters: the
+ * final path segment is deliberately *not* resolved. A write follows an
+ * internal link to the file it names, because replacing the link would be the
+ * surprising outcome; a deletion removes the link itself, because following it
+ * would remove something the document never named — possibly outside the
+ * working directory entirely. So resolution stops at the parent prefix, which
+ * still catches a directory link leading out, and the authored last segment is
+ * put back onto it unresolved.
+ *
+ * What is then removed is decided by an explicit `lstat` rather than by the
+ * platform. A directory is refused whether or not it is empty, and every
+ * runtime this ships to reports a nonrecursive removal of one differently.
+ * Absence is success on both sides of that classification: a path that already
+ * names nothing was already what the document asked for. The removal is the
+ * single commit point, and nothing is acquired around it, so cancellation
+ * before it changes nothing and there is no cleanup to fail.
+ *
  * ## What crosses the boundary
  *
  * Nothing from a caught platform error. An errno code *selects* a
@@ -47,7 +66,7 @@ import { ensure, Err, Ok, resource, scoped, until } from "effection";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { mkdtempSync } from "node:fs";
-import { realpath } from "node:fs/promises";
+import { realpath, rmdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { FsApi, rm } from "@effectionx/fs";
 import { API } from "./apis.js";
@@ -184,6 +203,41 @@ function* destination(input) {
         return { reason: reasonOf(error) };
     }
 }
+/**
+ * The path a removal would act on, with the final segment left alone.
+ *
+ * Deletion is the one operation whose target must *not* be resolved. A final
+ * symbolic link is the entry the document named, and following it would remove
+ * something the document never mentioned — possibly outside the working
+ * directory entirely. So only the parent prefix is resolved, and the authored
+ * last segment is put back onto it unresolved. Resolving the parent is what
+ * still catches a directory link leading out; leaving the last segment is what
+ * keeps a link a link.
+ *
+ * The working directory names itself — `.`, or anything that normalizes onto it
+ * — and that case cannot go through the parent at all: the parent of `cwd` is
+ * outside `cwd`, so the same comparison would report the working directory as
+ * an escape. It is classified directly instead, and target classification then
+ * refuses it for what it is.
+ */
+function* removalDestination(input) {
+    try {
+        const base = (yield* API.Fs.operations.realpath(input.cwd)) ?? input.cwd;
+        const named = resolve(input.cwd, input.path);
+        if (named === resolve(input.cwd)) {
+            return { path: base };
+        }
+        const parent = yield* resolveExisting(dirname(named));
+        const path = join(parent, basename(named));
+        if (!within(base, path)) {
+            return { reason: "resolved-escape" };
+        }
+        return { path };
+    }
+    catch (error) {
+        return { reason: reasonOf(error) };
+    }
+}
 function nonWriteFailure(operation, phase, reason) {
     return Err(filesFailure({ operation, phase, reason }));
 }
@@ -349,6 +403,75 @@ export function hostFilesHandler(options = {}) {
         }
         return Ok(fileWriteSuccess("host-committed"));
     }
+    /**
+     * Remove one regular file or one final symbolic link.
+     *
+     * Classification comes first and it is `lstat`, so what is judged is the
+     * entry the document named rather than whatever it leads to. A directory is
+     * refused whether or not it is empty: `<File.Delete>` names one file, and the
+     * platforms disagree about what removing an empty directory nonrecursively
+     * even reports — one answers `EISDIR`, another `EFAULT`. Deciding it here is
+     * what makes that disagreement invisible.
+     *
+     * Absence is success, in both places it can appear. A path that already names
+     * nothing was already what the document asked for, and a path that stops
+     * existing between the classification and the removal is the same answer
+     * arrived at by a different route — the removal is this operation's single
+     * commit point, and it has no earlier state to restore.
+     */
+    function* deleteFile(input) {
+        const lexical = inadmissible(input);
+        if (lexical !== undefined) {
+            return nonWriteFailure("delete", "lexical", lexical);
+        }
+        const target = yield* removalDestination(input);
+        if ("reason" in target) {
+            return nonWriteFailure("delete", "resolution", target.reason);
+        }
+        notify(observe, { operation: "delete", phase: "target" });
+        let wasSymbolicLink = false;
+        try {
+            const info = yield* API.Fs.operations.lstat(target.path);
+            if (!info.exists) {
+                return Ok(undefined);
+            }
+            if (info.isDirectory) {
+                return nonWriteFailure("delete", "target", "directory");
+            }
+            if (!info.isFile && !info.isSymbolicLink) {
+                return nonWriteFailure("delete", "target", "special-file");
+            }
+            wasSymbolicLink = info.isSymbolicLink;
+        }
+        catch (error) {
+            return nonWriteFailure("delete", "target", reasonOf(error));
+        }
+        notify(observe, { operation: "delete", phase: "access" });
+        try {
+            yield* API.Fs.operations.remove(target.path, { recursive: false });
+        }
+        catch (error) {
+            const reason = reasonOf(error);
+            if (reason === "missing") {
+                return Ok(undefined);
+            }
+            // Windows removes a symbolic link to a directory with RemoveDirectory,
+            // and not every runtime's `rm` falls back to it. The entry was classified
+            // a link above, so removing it as a directory still removes only the
+            // link. A fallback that fails leaves the original refusal in force.
+            if (wasSymbolicLink) {
+                try {
+                    yield* until(rmdir(target.path));
+                    return Ok(undefined);
+                }
+                catch {
+                    return nonWriteFailure("delete", "access", reason);
+                }
+            }
+            return nonWriteFailure("delete", "access", reason);
+        }
+        return Ok(undefined);
+    }
     /**
      * The regular files under `cwd` that `include` selects and `exclude` does not.
      *
@@ -409,7 +532,7 @@ export function hostFilesHandler(options = {}) {
             let created;
             try {
                 // oxlint-disable-next-line local/no-sync-filesystem
-                created = mkdtempSync(join(tmpdir(), "xmd-tempdir-"));
+                created = mkdtempSync(join(options.temporaryRoot ?? tmpdir(), "xmd-tempdir-"));
             }
             catch (error) {
                 yield* provide(nonWriteFailure("temporary-directory", "acquire", reasonOf(error)));
@@ -427,7 +550,7 @@ export function hostFilesHandler(options = {}) {
             yield* provide(Ok(canonical));
         });
     }
-    return { checkFilePath, readTextFile, writeTextFile, globFiles, temporaryDirectory };
+    return { checkFilePath, readTextFile, writeTextFile, deleteFile, globFiles, temporaryDirectory };
 }
 /**
  * Remove a temporary directory as its scope ends.
@@ -486,6 +609,9 @@ export function useHostFiles(options = {}) {
         *writeTextFile([input]) {
             return yield* handler.writeTextFile(input);
         },
+        *deleteFile([input]) {
+            return yield* handler.deleteFile(input);
+        },
         *globFiles([input]) {
             return yield* handler.globFiles(input);
         },

package/esm/launcher.js

@@ -0,0 +1,322 @@
+/**
+ * The native launcher — how a host hands one child process the terminal.
+ *
+ * This is not `exec`. An ordinary command is a captured child: its stdout and
+ * stderr are piped so a document can display, capture and journal them, and
+ * its exit status is a value the document reads. A native coding-agent UI is
+ * the opposite of that. It draws on the terminal, reads the person's
+ * keystrokes, and owns the conversation it has with them. None of that may
+ * become an XMD process result or a journaled transcript, and a piped child
+ * cannot be interactive at all.
+ *
+ * So a launch asks for three things in order, and each is refusable on its
+ * own:
+ *
+ * 1. `reserve()` takes the one foreground-terminal lease for the run. A host
+ *    with no terminal refuses here, which is before any session ownership has
+ *    moved. Two launches cannot hold it at once even when they name different
+ *    sessions, so native UIs are sequential by construction.
+ * 2. `flush()` gives the reader everything the document has produced so far,
+ *    so the native UI does not open on top of half-written output.
+ * 3. `launch()` spawns the child with the terminal inherited, waits for it,
+ *    and reports its terminal status and nothing else.
+ *
+ * There is no host default. `xmd run` installs the foreground launcher;
+ * a test or embedding host installs a controlled one that needs no terminal.
+ * Until one is installed every operation refuses, which is what keeps
+ * document help and inspection free of any of this.
+ */
+import { createApi } from "@effectionx/context-api";
+import { ensure, race, resource, scoped, until, withResolvers } from "effection";
+import { spawn as spawnChild } from "node:child_process";
+import process from "node:process";
+export const NATIVE_LAUNCHER_UNAVAILABLE = "no native launcher is installed — this host does not hand a native agent UI " +
+    "the terminal. `xmd run` installs one; a test or embedding host installs its own.";
+export class NativeLauncherUnavailableError extends Error {
+    name = "NativeLauncherUnavailableError";
+    constructor(message = NATIVE_LAUNCHER_UNAVAILABLE) {
+        super(message);
+    }
+}
+export const NativeLauncher = createApi("runtime.nativeLauncher", {
+    // deno-lint-ignore require-yield
+    *reserve() {
+        throw new NativeLauncherUnavailableError();
+    },
+    // deno-lint-ignore require-yield
+    *flush() {
+        throw new NativeLauncherUnavailableError();
+    },
+    // deno-lint-ignore require-yield
+    *launch(_request) {
+        throw new NativeLauncherUnavailableError();
+    },
+});
+/** Hold the foreground-terminal lease for the calling scope. */
+export function reserveTerminal() {
+    return NativeLauncher.operations.reserve();
+}
+/** Give the reader everything the document has produced so far. */
+export function flushOutput() {
+    return NativeLauncher.operations.flush();
+}
+/** Run one native UI as a foreground child and report how it ended. */
+export function nativeLaunch(request) {
+    return NativeLauncher.operations.launch(request);
+}
+export const NO_TERMINAL = "<Session.Launch> needs a terminal: a native agent UI reads keystrokes and " +
+    "draws on the screen, and this invocation has none. Run xmd from a terminal, " +
+    "or use a host that installs its own launcher.";
+/**
+ * How long an interrupted child is given to leave on its own before the
+ * launcher escalates. Cancellation is not permitted to strand a process
+ * holding the terminal, so the escalation is bounded rather than patient.
+ */
+const INTERRUPT_GRACE_MS = 2_000;
+/** How often a reap re-checks whether the child is still reachable. */
+const REAP_POLL_MS = 25;
+/** How long an unanswerable kill is given before the child is called gone. */
+const KILL_SETTLE_MS = 500;
+/**
+ * Install the launcher that hands a native UI this process's own terminal.
+ *
+ * XMD stays the parent. It does not replace itself with the child, because a
+ * process that has execed away cannot cancel the document, reap the child,
+ * own its exit status, or continue after the UI closes.
+ */
+export function* installForegroundLauncher(options = {}) {
+    const isTerminal = options.isTerminal ?? (() => process.stdout.isTTY === true);
+    const drain = options.drain;
+    let held = false;
+    yield* NativeLauncher.around({
+        reserve() {
+            return resource(function* (provide) {
+                if (!isTerminal()) {
+                    throw new NativeLauncherUnavailableError(NO_TERMINAL);
+                }
+                if (held) {
+                    throw new Error("another <Session.Launch> already holds this run's terminal — one " +
+                        "native UI owns the terminal at a time");
+                }
+                held = true;
+                try {
+                    yield* provide();
+                }
+                finally {
+                    held = false;
+                }
+            });
+        },
+        *flush() {
+            if (drain) {
+                yield* drain();
+            }
+            yield* drainStream(process.stdout);
+            yield* drainStream(process.stderr);
+        },
+        *launch([request]) {
+            return yield* runForeground(request);
+        },
+    }, { at: "min" });
+}
+/**
+ * Wait until the host stream has written what was handed to it.
+ *
+ * A TTY write usually completes synchronously and `write()` reports it did;
+ * when it reports back-pressure instead the bytes are still queued, and the
+ * child would draw over them.
+ */
+function drainStream(stream) {
+    return until(new Promise((resolve) => {
+        if (stream.writableLength === 0) {
+            resolve();
+            return;
+        }
+        stream.write("", () => resolve());
+    }));
+}
+function runForeground(request) {
+    return scoped(function* () {
+        const [command, ...args] = request.command;
+        if (command === undefined) {
+            throw new Error("native launch: command must not be empty");
+        }
+        const settled = withResolvers();
+        const failed = withResolvers();
+        let child;
+        // Interrupt, then insist. A cancelled document may not continue — or
+        // finish tearing down — while a child still holds the terminal, so this
+        // waits for the child to be gone rather than for the signal to have been
+        // sent. Registered before the spawn, because a halt between acquiring a
+        // process and registering its cleanup leaks the process.
+        yield* ensure(() => (child ? until(reap(child)) : undefined));
+        // `inherit` is the whole point: the child reads this terminal and draws on
+        // it directly, so nothing between it and the person using it can buffer,
+        // reorder, capture or journal what passes.
+        child = spawnChild(command, args, {
+            cwd: request.cwd,
+            env: request.env,
+            stdio: "inherit",
+        });
+        child.once("error", (error) => failed.reject(error));
+        child.once("exit", (code, signal) => {
+            const outcome = {};
+            if (code !== null) {
+                outcome.exitCode = code;
+            }
+            if (signal !== null) {
+                outcome.signal = signal;
+            }
+            settled.resolve(outcome);
+        });
+        return yield* race([settled.operation, failed.operation]);
+    });
+}
+/**
+ * End one foreground child and wait for it to be gone.
+ *
+ * Deliberately one promise rather than an Effection race: this runs while the
+ * scope is already being dismantled, and the cheapest correct thing to do
+ * there is to wait on the process's own events instead of starting more
+ * structured work beside them.
+ *
+ * A child that ignores the interrupt is killed outright once the grace period
+ * is spent — a native UI holding the terminal is not something a cancelled run
+ * can afford to wait on indefinitely.
+ */
+function reap(child) {
+    const pid = child.pid;
+    if (pid === undefined || child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // What the escalation established. Bounded settlement is only permitted on
+        // the strength of one of these: a fatal signal the kernel accepted, or a
+        // process that was already gone. Anything else — a refused delivery, a
+        // permission error — leaves a child that may still be running, and
+        // reporting that as a successful reap would let the document continue
+        // while a native UI still owns the terminal.
+        let fatal;
+        const done = (outcome) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearInterval(poll);
+            clearTimeout(escalation);
+            clearTimeout(deadline);
+            // Deno's `node:child_process` stops reporting a child's exit once a
+            // signal that child ignored has been delivered, and holds the runtime
+            // open on the handle it will now never settle. Dropping the reference is
+            // what lets a cancelled run finish.
+            try {
+                child.unref();
+            }
+            catch {
+                // The runtime already released the handle, which is the state this
+                // was asking for.
+            }
+            if (outcome) {
+                reject(outcome);
+                return;
+            }
+            resolve();
+        };
+        child.once("exit", () => done());
+        // Reachability rather than the exit event, because that is the fact this
+        // has to establish and the event is not dependable across runtimes here.
+        const poll = setInterval(() => {
+            if (!isReachable(pid)) {
+                done();
+            }
+        }, REAP_POLL_MS);
+        const escalation = setTimeout(() => {
+            fatal = signal(pid, "SIGKILL");
+        }, INTERRUPT_GRACE_MS);
+        // A process does not survive SIGKILL, so once the kernel accepted one this
+        // stops waiting on a report rather than on the child. What it will not do
+        // is call an undelivered signal a termination.
+        const deadline = setTimeout(() => {
+            if (fatal === "delivered" || fatal === "absent") {
+                done();
+                return;
+            }
+            done(new Error(`native launch could not establish that process ${pid} stopped: ` +
+                `SIGKILL was ${fatal ?? "not delivered"}`));
+        }, INTERRUPT_GRACE_MS + KILL_SETTLE_MS);
+        signal(pid, "SIGINT");
+    });
+}
+/**
+ * Send one signal to the child by pid, and report what that established.
+ *
+ * Deliberately not `child.kill()`. Deno's `node:child_process` marks a child as
+ * killed after the first call and delivers nothing on any later one, so a child
+ * that ignores the interrupt could never be escalated through the handle — the
+ * run would keep waiting on a native UI still holding the terminal. Addressing
+ * the process directly is what makes escalation real.
+ */
+function signal(pid, name) {
+    try {
+        process.kill(pid, name);
+        return "delivered";
+    }
+    catch (error) {
+        // Gone between the decision and the delivery is the outcome this was
+        // asking for. Anything else is a delivery that did not happen, and is not
+        // evidence of termination.
+        return isNoSuchProcess(error) ? "absent" : "refused";
+    }
+}
+function isNoSuchProcess(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ESRCH");
+}
+/**
+ * Whether a process still exists. Signal 0 delivers nothing: it asks the
+ * kernel whether the pid is reachable, which is the whole question here.
+ */
+function isReachable(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function* installControlledLauncher(options = {}) {
+    let held = false;
+    yield* NativeLauncher.around({
+        reserve() {
+            return resource(function* (provide) {
+                if (held) {
+                    throw new Error("another <Session.Launch> already holds this run's terminal — one " +
+                        "native UI owns the terminal at a time");
+                }
+                held = true;
+                options.onReserve?.();
+                try {
+                    yield* provide();
+                }
+                finally {
+                    held = false;
+                }
+            });
+        },
+        // deno-lint-ignore require-yield
+        *flush() {
+            options.onFlush?.();
+        },
+        *launch([request]) {
+            options.record?.(request);
+            if (options.wait) {
+                yield* options.wait(request);
+            }
+            return options.outcome?.(request) ?? { exitCode: 0 };
+        },
+    }, { at: "min" });
+}

package/esm/mod.js

@@ -8,7 +8,7 @@
  * Seven domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
  * - `API.Fs` — the low-level host filesystem (`readTextFile`, `writeTextFile`,
- *   `stat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
+ *   `stat`, `lstat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
  * - `API.Files` — document filesystem access as whole semantic operations,
  *   with no host default. `useHostFiles()` installs the host provider.
  * - `API.Fetch` — HTTP requests (`fetch`)
@@ -16,15 +16,23 @@
  *   this xmd, and eval-block compilation
  *   (`cwd`, `env`, `platform`, `command`, `compile`)
  * - `API.Service` — scoped attached service startup (`startService`)
+ * - `NativeLauncher` — handing one native agent UI the foreground terminal
+ *   (`reserveTerminal`, `flushOutput`, `nativeLaunch`)
  * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
  */
+import "./_dnt.polyfills.js";
 export { API } from "./apis.js";
-export { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
+export { exec, readTextFile, writeTextFile, stat, lstat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
 export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
 export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
 export { asDuration, durationError, parseDuration } from "./duration.js";
 export { asFilesFatal, FILES_ERROR, FILES_ERROR_MESSAGE, FILES_FATAL, FILES_INVARIANT_MESSAGE, FILES_OPERATION_DENIED_MESSAGE, FILES_PROVIDER_UNAVAILABLE_MESSAGE, FILES_WRITE_SUCCESS, Files, FilesError, FilesInvariantError, FilesOperationDeniedError, FilesProviderUnavailableError, fileWriteFailure, fileWriteSuccess, filesFailure, isFilesFatal, parseFilesPhase, parseFilesReason, parseFileWriteFailure, parseFileWritePhase, parseFileWriteSuccess, parseFilesFailure, parseFilesFatal, } from "./files.js";
+export { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, reserveTerminal, } from "./launcher.js";
 export { hostFilesHandler, useHostFiles } from "./host-files.js";
+export { AgentSessionBusy, agentSessionKeyDigest, AgentSessionRecoveryRequired, parseAgentSessionOwnership, serializeAgentSessionOwnership, } from "./agent-session-coordinator.js";
+export { createDenoAgentSessionCoordinator, hasDenoAgentSessionCoordinator, } from "./deno-agent-session-coordinator.js";
+export { ExecutableObservationError } from "./executable-observer.js";
+export { createDenoExecutableObserver, hasDenoExecutableObserver, } from "./deno-executable-observer.js";

package/esm/test/mod.js

@@ -8,4 +8,5 @@
  * - `useFailingExec(exitCode, stderr)` — always-failing exec
  * - `useStubService(endpoint)` — scoped provider-neutral service attachment
  */
+import "../_dnt.polyfills.js";
 export { useStubFs, useEchoExec, useFailingExec, useStubService } from "./stubs.js";

package/esm/test/stubs.js

@@ -43,6 +43,8 @@ export function* useStubService(endpoint) {
  *
  * - `readTextFile` returns content from the `files` map; throws ENOENT for missing keys.
  * - `stat` returns `{ exists: true, isFile: true }` for keys in the map.
+ * - `lstat` answers the same, with `isSymbolicLink: false`: an in-memory map
+ *   holds file content, so nothing in it is a link to somewhere else.
  * - `glob` throws (not stubbed). Install `API.Fs.around()` directly if needed.
  * - the writing half — `writeTextFile`, `ensureDir`, `rename`, `remove`, and
  *   `realpath` — is not stubbed and reaches the real filesystem. A test that
@@ -65,6 +67,10 @@ export function* useStubFs(files) {
             const exists = path in files;
             return { exists, isFile: exists, isDirectory: false };
         },
+        *lstat([path], _next) {
+            const exists = path in files;
+            return { exists, isFile: exists, isDirectory: false, isSymbolicLink: false };
+        },
         *glob(_args, _next) {
             throw new Error("glob not stubbed");
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {

package/types/_dnt.polyfills.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface Error {
+        cause?: unknown;
+    }
+}
+export {};

package/types/_dnt.shims.d.ts

@@ -0,0 +1 @@
+export declare const dntGlobalThis: Omit<typeof globalThis, never>;