@executablemd/runtime 0.8.1 → 0.9.1

package/types/agent-session-coordinator.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Exclusive ownership of one logical agent session
+ * (specs/native-agent-session-launch-spec.md §Ownership and concurrency).
+ *
+ * An advertised provider-returned session can be handed to a native UI, and a
+ * native UI is a live owner nothing on the XMD side can observe. So every
+ * operation that could act on such a session — establishing it, running a turn,
+ * launching into it — enters here first, and a host that cannot answer the
+ * ownership question refuses rather than guessing.
+ *
+ * This is a plain capability, injected directly by the host into the provider
+ * that needs it. It is deliberately not a contextual Api: ownership is a
+ * security decision, and a decision document middleware can replace is not one.
+ *
+ * Acquisition never waits. A native UI may stay open for hours, and a caller
+ * that queued would hold the reader's terminal while offering no way to reach
+ * the owner it waits for.
+ */
+import type { Operation, Result } from "effection";
+/** Which logical session is being owned. Never an authored alias. */
+export interface AgentSessionKey {
+    provider: string;
+    agent: string;
+    sessionKey: string;
+}
+/** What is asking. Recorded so a tombstone says what failed to finish. */
+export type AgentSessionOwnerKind = "session" | "prompt" | "native-launch";
+export interface AgentSessionOwner {
+    kind: AgentSessionOwnerKind;
+    /** A fresh opaque id per live attempt. Never a launch or native identity. */
+    operationId: string;
+}
+/**
+ * The acknowledgement a body gives when its session can no longer be acted on.
+ *
+ * One use, and only from inside the body. Returning without it — by success,
+ * failure or cancellation — leaves the durable marker active, because what it
+ * acknowledges is not "I finished" but "nothing I started can still touch this
+ * session".
+ */
+export interface AgentSessionOwnership {
+    quiesced(): void;
+}
+/** Another live owner holds this session right now. */
+export declare class AgentSessionBusy extends Error {
+    name: string;
+}
+/**
+ * The last owner never proved it stopped.
+ *
+ * A crash releases the kernel lock but not this: nothing observable afterwards
+ * distinguishes a session whose owner died mid-turn from one it left cleanly,
+ * so the conservative answer stands until someone recovers it deliberately.
+ */
+export declare class AgentSessionRecoveryRequired extends Error {
+    name: string;
+}
+export interface AgentSessionCoordinator {
+    /**
+     * Run `body` while holding exclusive ownership of `key`.
+     *
+     * The body runs only once ownership is established. Busy and
+     * recovery-required arrive on the failure channel of the `Result`; an
+     * unexpected filesystem or protocol failure raises, having preserved the
+     * conservative marker.
+     */
+    coordinate<T>(key: AgentSessionKey, owner: AgentSessionOwner, body: (ownership: AgentSessionOwnership) => Operation<T>): Operation<Result<T>>;
+}
+/**
+ * The digest that names one session's sidecar and ownership record.
+ *
+ * Canonical, so every process derives the same name, and a digest, so the
+ * coordination namespace holds no agent name, session name, path or authored
+ * value.
+ */
+export declare function agentSessionKeyDigest(key: AgentSessionKey): string;
+/** The exact durable record one owner writes. No other member is accepted. */
+export interface AgentSessionOwnershipRecordV1 {
+    schema: "agent-session-ownership.v1";
+    keyDigest: string;
+    state: "active" | "idle";
+    ownerKind: AgentSessionOwnerKind;
+    operationId: string;
+}
+/**
+ * Read an ownership record strictly.
+ *
+ * An unknown schema, a missing field, or a member this build cannot account for
+ * describes state it must not act on — so it is refused rather than read
+ * partially, and never repaired.
+ */
+export declare function parseAgentSessionOwnership(value: unknown): AgentSessionOwnershipRecordV1 | undefined;
+export declare function serializeAgentSessionOwnership(record: AgentSessionOwnershipRecordV1): string;

package/types/apis.d.ts

@@ -85,6 +85,25 @@ export interface StatResult {
     isFile: boolean;
     isDirectory: boolean;
 }
+/**
+ * Result of an `lstat` call: what the entry itself is, rather than what it
+ * leads to.
+ *
+ * A final symbolic link is the answer here instead of being followed, which is
+ * the whole reason this exists beside `stat`. `isSymbolicLink` is therefore its
+ * own member rather than an absence to infer: a link reports `isFile: false`
+ * and `isDirectory: false` whatever it points at, and "neither" is also what a
+ * socket or a device reports.
+ *
+ * Missing answers `{ exists: false, … }` rather than throwing, for the same
+ * reason `stat` does.
+ */
+export interface LinkStatResult {
+    exists: boolean;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
 /**
  * Minimal response headers interface.
  *
@@ -93,6 +112,34 @@ export interface StatResult {
  */
 export interface ResponseHeaders {
     get(key: string): string | null;
+    /**
+     * Every header the response carries, as name/value pairs in the order the
+     * provider reports them.
+     *
+     * Optional, because a provider written against `get()` alone still satisfies
+     * this interface. A caller that must retain the whole set — `<Fetch>` — fails
+     * when it is absent rather than recording the part of a response `get()`
+     * happens to be asked for.
+     */
+    entries?(): Iterable<readonly [string, string]>;
+}
+/** What a request may say about itself, beyond where it is going. */
+export interface FetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeout?: number;
+    /**
+     * Fail the request on any status outside 2xx.
+     *
+     * Part of the request rather than something a caller applies to the answer,
+     * because middleware wrapping this operation is entitled to know it: a
+     * provider that authenticates, routes or refuses a request reads what the
+     * caller asked for, and "this caller treats a non-2xx as a failure" is part of
+     * that. The default adapter hands it to the transport, which raises its own
+     * `HttpError`.
+     */
+    expect?: boolean;
 }
 /**
  * Response shape returned by the fetch context API.
@@ -138,6 +185,14 @@ interface ProcessHandler {
 interface FsHandler {
     readTextFile(path: string): Operation<string>;
     stat(path: string): Operation<StatResult>;
+    /**
+     * What the entry at `path` is, without following a final symbolic link.
+     *
+     * A caller that has to decide whether to *remove* a path asks this rather
+     * than `stat`: `stat` answers about the file a link names, and removing the
+     * link is not removing that file. Missing is an answer here too.
+     */
+    lstat(path: string): Operation<LinkStatResult>;
     /**
      * Files and symbolic links beneath `root` whose path relative to it matches
      * `patterns` and matches none of `exclude`. Paths come back relative and
@@ -178,12 +233,7 @@ interface FsHandler {
     realpath(path: string): Operation<string | undefined>;
 }
 interface FetchHandler {
-    fetch(input: string, init?: {
-        method?: string;
-        headers?: Record<string, string>;
-        body?: string;
-        timeout?: number;
-    }): Operation<RuntimeFetchResponse>;
+    fetch(input: string, init?: FetchInit): Operation<RuntimeFetchResponse>;
 }
 /**
  * A compiled eval block accepts the document binding environment and returns
@@ -237,13 +287,32 @@ export declare function exec(options: ProcessExecOptions & {
 }>;
 export declare const readTextFile: typeof API.Fs.operations.readTextFile;
 export declare const stat: typeof API.Fs.operations.stat;
+export declare const lstat: typeof API.Fs.operations.lstat;
 export declare const glob: typeof API.Fs.operations.glob;
 export declare const writeTextFile: typeof API.Fs.operations.writeTextFile;
 export declare const ensureDir: typeof API.Fs.operations.ensureDir;
 export declare const rename: typeof API.Fs.operations.rename;
 export declare const remove: typeof API.Fs.operations.remove;
 export declare const realpath: typeof API.Fs.operations.realpath;
-export declare const fetch: typeof API.Fetch.operations.fetch;
+/**
+ * One HTTP request, ready to be yielded or chained.
+ *
+ * Yielding it gives the settled response, which is what every caller inside the
+ * engine wants. The chain is for authored eval code, whose calling shape
+ * predates this operation: `fetch(url).expect()` and
+ * `fetch(url, init).expect().json()` are what documents in this repository are
+ * written with, and they mean the same thing here — with the request now
+ * crossing `API.Fetch`, so a host that narrows destinations narrows theirs too.
+ */
+export interface FetchOperation extends Operation<RuntimeFetchResponse> {
+    /** The response body as text. */
+    text(): Operation<string>;
+    /** The response body parsed as JSON. */
+    json(): Operation<unknown>;
+    /** The same request, asked for with `expect` — failing outside 2xx. */
+    expect(): FetchOperation;
+}
+export declare function fetch(input: string, init?: FetchInit): FetchOperation;
 export declare const env: typeof API.Env.operations.env;
 export declare const cwd: typeof API.Env.operations.cwd;
 export declare const platform: typeof API.Env.operations.platform;

package/types/deno-agent-session-coordinator.d.ts

@@ -0,0 +1,11 @@
+import type { AgentSessionCoordinator } from "./agent-session-coordinator.js";
+/** Whether this host can coordinate agent sessions at all. */
+export declare function hasDenoAgentSessionCoordinator(): boolean;
+/**
+ * Build the coordinator rooted at `root`.
+ *
+ * Returns nothing on a host with no such filesystem: a host that cannot answer
+ * the ownership question installs no coordinator, and every advertised
+ * provider-returned operation refuses.
+ */
+export declare function createDenoAgentSessionCoordinator(root: string): AgentSessionCoordinator | undefined;

package/types/deno-executable-observer.d.ts

@@ -0,0 +1,14 @@
+import type { ExecutableObserver } from "./executable-observer.js";
+/** Whether this host can observe an executable at all. */
+export declare function hasDenoExecutableObserver(): boolean;
+/**
+ * Build an observer rooted in this process's real environment.
+ *
+ * `overrides` exist for the focused proof only: a test that wants to watch
+ * PATH search happen supplies its own search path and working directory rather
+ * than moving the ones every other thing in the process is using.
+ */
+export declare function createDenoExecutableObserver(overrides?: {
+    path?: string;
+    cwd?: string;
+}): ExecutableObserver | undefined;

package/types/executable-observer.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+import type { Operation } from "effection";
+/** Why an executable could not be observed, in terms a caller can act on. */
+export type ExecutableRefusal = "not-found" | "not-a-file" | "not-executable" | "unreadable" | "version-unavailable";
+/**
+ * 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 declare class ExecutableObservationError extends Error {
+    name: string;
+    refusal: ExecutableRefusal;
+    constructor(message: string, options: {
+        refusal: ExecutableRefusal;
+        cause?: unknown;
+    });
+}
+/**
+ * One executable, as it exists during this invocation.
+ *
+ * `path` is canonical and live: it is what a caller spawns and what it asked
+ * for a version, and it is absent from everything durable. `versionOutput` is
+ * raw — the adapter that knows the provider parses it, and neither this string
+ * nor the path may reach a record, a diagnostic, or the environment of
+ * anything but the matching child.
+ */
+export interface ObservedExecutable {
+    path: string;
+    digest: {
+        algorithm: "sha256";
+        value: string;
+    };
+    versionOutput: string;
+}
+export interface ExecutableObserver {
+    /**
+     * Resolve `command`, canonicalize it, require an executable regular file,
+     * hash its bytes, and ask that exact path for its version.
+     *
+     * Asking the same path that was hashed is the point: a version read from a
+     * differently-resolved file describes a build this observation did not make.
+     */
+    observe(command: string, options?: {
+        versionArgs?: readonly string[];
+    }): Operation<ObservedExecutable>;
+}

package/types/files.d.ts

@@ -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 { type Api } from "@effectionx/context-api";
 import type { Operation, Result } from "effection";
 /** The stable discriminant on ordinary filesystem failure data. */
@@ -65,7 +68,7 @@ export declare const FILES_WRITE_SUCCESS = "executablemd.runtime.files-write-suc
  */
 export type FilesReason = "empty-path" | "absolute-path" | "lexical-escape" | "resolved-escape" | "missing" | "directory" | "special-file" | "not-directory" | "permission-denied" | "read-only" | "too-many-symlinks" | "path-too-long" | "no-space" | "quota-exhausted" | "cross-device" | "busy" | "too-many-open-files" | "directory-not-empty" | "invalid-pattern" | "operation-failed";
 /** The operations whose failure carries no commit outcome. */
-export type FilesOperation = "check-file-path" | "read" | "glob" | "temporary-directory";
+export type FilesOperation = "check-file-path" | "read" | "delete" | "glob" | "temporary-directory";
 /** Where a non-write operation stopped. */
 export type FilesPhase = "lexical" | "resolution" | "target" | "access" | "pattern" | "traversal" | "acquire";
 /** Where a write stopped, which is what decides what may be said about the target. */
@@ -131,6 +134,17 @@ export interface FilesHandler {
     checkFilePath(input: FilePathInput): Operation<Result<void>>;
     readTextFile(input: FilePathInput): Operation<Result<string>>;
     writeTextFile(input: FileWriteInput): Operation<Result<FileWriteSuccess>>;
+    /**
+     * Remove one entry this path names, and answer with nothing.
+     *
+     * Mandatory, like every other operation here: a provider that has no
+     * deletion to offer does not omit it and fall through to a host. Success
+     * carries no value at all — there is no receipt, no path, and no record of
+     * whether anything was there — because a document that asked for a file to be
+     * gone has been answered by its absence. A path that already names nothing is
+     * that same success.
+     */
+    deleteFile(input: FilePathInput): Operation<Result<void>>;
     /** Sorted, deduplicated, POSIX-separated paths of the regular files that match. */
     globFiles(input: GlobInput): Operation<Result<string[]>>;
     /**

package/types/host-files.d.ts

@@ -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
@@ -55,13 +74,21 @@ import type { FilesHandler } from "./files.js";
  * observable rather than merely stated.
  */
 export interface HostFilesEvent {
-    readonly operation: "read" | "write" | "glob";
+    readonly operation: "read" | "write" | "delete" | "glob";
     readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir";
 }
 /** Synchronous, so nothing can run between the observation and the call it precedes. */
 export type HostFilesObserver = (event: HostFilesEvent) => void;
 export interface HostFilesOptions {
     readonly observe?: HostFilesObserver;
+    /**
+     * The directory temporary directories are minted under, defaulting to the
+     * host's temporary root. The host's root is shared by every process on the
+     * machine, so a caller that censuses the minted namespace — a lifetime test
+     * proving nothing survives a cancellation — points this at a directory it
+     * owns, where the only entries are the ones this provider created.
+     */
+    readonly temporaryRoot?: string;
 }
 /**
  * Build a host provider.

package/types/launcher.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 { type Api } from "@effectionx/context-api";
+import type { Operation } from "effection";
+/**
+ * What a provider asks the host to run.
+ *
+ * `command` is the complete argv, built by the provider's adapter from the
+ * provider-native session identity. Raw prepared instructions never appear in
+ * it, and never in `env`: a process's arguments and environment are readable
+ * by other processes, so the instruction layer travels through the provider's
+ * own session API instead.
+ */
+export interface NativeLaunchRequest {
+    command: string[];
+    cwd: string;
+    env?: Record<string, string>;
+}
+/**
+ * How the native UI ended. A child that exited on a signal reports the signal
+ * and no code, which is how a signalled exit stays distinguishable from
+ * status 0.
+ */
+export interface NativeLaunchOutcome {
+    exitCode?: number;
+    signal?: string;
+}
+export interface NativeLauncherHandler {
+    reserve(): Operation<void>;
+    flush(): Operation<void>;
+    launch(request: NativeLaunchRequest): Operation<NativeLaunchOutcome>;
+}
+export declare const NATIVE_LAUNCHER_UNAVAILABLE: string;
+export declare class NativeLauncherUnavailableError extends Error {
+    name: string;
+    constructor(message?: string);
+}
+export declare const NativeLauncher: Api<NativeLauncherHandler>;
+/** Hold the foreground-terminal lease for the calling scope. */
+export declare function reserveTerminal(): Operation<void>;
+/** Give the reader everything the document has produced so far. */
+export declare function flushOutput(): Operation<void>;
+/** Run one native UI as a foreground child and report how it ended. */
+export declare function nativeLaunch(request: NativeLaunchRequest): Operation<NativeLaunchOutcome>;
+export declare const NO_TERMINAL: string;
+interface ForegroundLauncherOptions {
+    /**
+     * Whether this host can hand a child the terminal. Read once, when the
+     * launcher installs, so a run learns what it is before a document starts.
+     */
+    isTerminal?: () => boolean;
+    /** Everything this host has still to show the reader. */
+    drain?: () => Operation<void>;
+}
+/**
+ * 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 declare function installForegroundLauncher(options?: ForegroundLauncherOptions): Operation<void>;
+/**
+ * A launcher a host installs when it has no terminal to give away, and no
+ * intention of starting a native UI.
+ *
+ * `record` sees each request in the order the provider made it; `outcome`
+ * decides what the child did; and `wait` is the operation the launch blocks
+ * on, so a test controls exactly how long the document stays suspended.
+ */
+export interface ControlledLauncherOptions {
+    record?: (request: NativeLaunchRequest) => void;
+    outcome?: (request: NativeLaunchRequest) => NativeLaunchOutcome;
+    wait?: (request: NativeLaunchRequest) => Operation<void>;
+    onReserve?: () => void;
+    onFlush?: () => void;
+}
+export declare function installControlledLauncher(options?: ControlledLauncherOptions): Operation<void>;
+export {};

package/types/mod.d.ts

@@ -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,14 +16,17 @@
  *   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 type { EvalBlock, ResponseHeaders, RuntimeFetchResponse, StatResult } 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 type { EvalBlock, FetchInit, FetchOperation, LinkStatResult, ResponseHeaders, RuntimeFetchResponse, StatResult, } 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 type { ServiceEndpoint, ServiceHandler, ServiceAttachment, ServiceStartOptions, } from "./service.js";
 export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
@@ -32,5 +35,13 @@ export { asDuration, durationError, parseDuration } from "./duration.js";
 export type { ProcessExecOptions, ProcessOutcome } from "./apis.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 type { FilePathInput, FilesDeniableOperation, FilesErrorData, FilesFailureData, FilesFatalData, FilesFatalFailure, FilesHandler, FilesInvariantCategory, FilesOperation, FilesPhase, FilesReason, FileWriteFailureData, FileWriteInput, FileWritePhase, FileWriteSuccess, FileWriteTarget, GlobInput, } from "./files.js";
+export { flushOutput, installControlledLauncher, installForegroundLauncher, NATIVE_LAUNCHER_UNAVAILABLE, NativeLauncher, NativeLauncherUnavailableError, nativeLaunch, NO_TERMINAL, reserveTerminal, } from "./launcher.js";
+export type { ControlledLauncherOptions, NativeLauncherHandler, NativeLaunchOutcome, NativeLaunchRequest, } from "./launcher.js";
 export { hostFilesHandler, useHostFiles } from "./host-files.js";
 export type { HostFilesEvent, HostFilesObserver, HostFilesOptions } from "./host-files.js";
+export { AgentSessionBusy, agentSessionKeyDigest, AgentSessionRecoveryRequired, parseAgentSessionOwnership, serializeAgentSessionOwnership, } from "./agent-session-coordinator.js";
+export type { AgentSessionCoordinator, AgentSessionKey, AgentSessionOwner, AgentSessionOwnerKind, AgentSessionOwnership, AgentSessionOwnershipRecordV1, } from "./agent-session-coordinator.js";
+export { createDenoAgentSessionCoordinator, hasDenoAgentSessionCoordinator, } from "./deno-agent-session-coordinator.js";
+export { ExecutableObservationError } from "./executable-observer.js";
+export type { ExecutableObserver, ExecutableRefusal, ObservedExecutable, } from "./executable-observer.js";
+export { createDenoExecutableObserver, hasDenoExecutableObserver, } from "./deno-executable-observer.js";

package/types/test/mod.d.ts

@@ -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/types/test/stubs.d.ts

@@ -28,6 +28,8 @@ export declare function useStubService(endpoint: ServiceEndpoint): Operation<voi
  *
  * - `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