@xenosystem/agent-interface-host 0.1.3

package/dist/observation/RunObservationService.js

@@ -0,0 +1,248 @@
+/**
+ * Tier-1 run observation — the live producer behind §2.9's review capability.
+ *
+ * `RunDiff` (in `core`) folds a filesystem event stream into a net change set,
+ * `capabilityTier` says review is deliverable at tier 1 for ANY agent, and
+ * `xeno-use` emits the stream. All three existed and **nothing connected them**,
+ * which is the same "built, tested, unreachable" shape as xeno-workflow's 76
+ * node types and xeno-tools' never-called `install`. This is the connection.
+ *
+ * ## The source is a PORT, and that is a licensing boundary before it is a
+ * design preference
+ *
+ * 🔴 **`xeno-use` is AGPL-3.0** — it ships the AGPL text and its Cargo workspace
+ * declares `license = "AGPL-3.0-only"`. XENO Agent is proprietary. So this
+ * package must not import `@xeno-use/core`, link its N-API binding, or take it
+ * as a dependency in any direction, and neither may any composition that ships
+ * inside a proprietary installer.
+ *
+ * `RunObservationSource` is therefore declared HERE, provider-neutral, and an
+ * adapter is supplied from outside. That is the right design under either
+ * outcome of the open licence question: if `xeno-use` stays AGPL the adapter
+ * talks to it out of process over its own `/v1/use/*` surface — the consumption
+ * model it was built for — and if it is ever relicensed, an in-process adapter
+ * plugs into the identical port. The port is not a workaround for the licence;
+ * it is what makes the licence answer swappable.
+ *
+ * ## Completeness travels with the diff, never beside it
+ *
+ * A `RunChange[]` cannot say whether it is the whole story. A stream that
+ * dropped events yields a *shorter* diff, not an error — and a shorter diff is
+ * the most dangerous possible output here, because a reviewer reads "3 files
+ * changed" and approves. This is the same rule `SandboxObservation` applies one
+ * layer down, and it has to be re-applied here rather than assumed: the
+ * completeness signal does not survive a fold unless the fold carries it.
+ */
+import { RunDiff, detectLandingOverlaps, resolveCapabilityTier, } from '@xenosystem/agent-interface-core';
+const DEFAULT_MAX_EVENTS_PER_DRAIN = 5_000;
+const DEFAULT_MAX_DRAINS_PER_POLL = 8;
+export class RunObservationService {
+    #runs = new Map();
+    #maxEventsPerDrain;
+    #maxDrainsPerPoll;
+    #emit;
+    constructor(options = {}) {
+        this.#maxEventsPerDrain = options.maxEventsPerDrain ?? DEFAULT_MAX_EVENTS_PER_DRAIN;
+        this.#maxDrainsPerPoll = options.maxDrainsPerPoll ?? DEFAULT_MAX_DRAINS_PER_POLL;
+        this.#emit = options.emit ?? (() => { });
+    }
+    /** Mirrors `CoordinationService.setEventSink` — the host is constructed with
+     *  its services, so a sink fixed at construction could not be the host. */
+    setEventSink(emit) {
+        this.#emit = emit;
+    }
+    /**
+     * Begins observing a run.
+     *
+     * `baseline` is the set of paths that existed when the run started. Its
+     * ABSENCE is meaningful and not a default: with no baseline every modified
+     * file reports as `added`, because nothing says it was there before. Callers
+     * that cannot supply one get a diff that is still useful and still honest —
+     * `added` really does mean "this run touched a path we have no prior record
+     * of" — but they should know that is what they are reading.
+     */
+    observe(runId, source, options = {}) {
+        this.#runs.set(runId, {
+            source,
+            diff: new RunDiff(options.baseline ? { baseline: options.baseline } : {}),
+            content: options.content,
+            droppedEvents: 0,
+            problems: new Set(options.problems ?? []),
+            degraded: options.degraded === true,
+        });
+    }
+    /**
+     * Content for one changed path, for hunk-level review.
+     *
+     * ⚠️ **A SNAPSHOT, not the state at the event.** The agent may have written
+     * again between the change being observed and this read, so a hunk view can
+     * disagree with the change list that prompted it. That is inherent to sampling
+     * a live filesystem rather than a defect to engineer away — but it means a
+     * surface must never label this "what the agent did at 10:04:03".
+     *
+     * Refuses a path the run has not actually changed. Reading arbitrary paths
+     * through a review API would turn a review pane into a file browser scoped to
+     * the sandbox, which is a different capability with a different consent story.
+     */
+    async readChange(runId, path) {
+        const run = this.#runs.get(runId);
+        if (!run?.content)
+            return undefined;
+        if (!run.diff.changes().some((change) => change.path === path))
+            return undefined;
+        return run.content.read(path);
+    }
+    stopObserving(runId) {
+        this.#runs.delete(runId);
+    }
+    observedRuns() {
+        return [...this.#runs.keys()].sort();
+    }
+    /**
+     * Drains what the sandbox has produced and folds it in.
+     *
+     * Returns the snapshot rather than only emitting it, so a caller that wants
+     * the answer does not have to subscribe to learn the result of its own call.
+     */
+    async poll(runId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            return undefined;
+        for (let drain = 0; drain < this.#maxDrainsPerPoll; drain += 1) {
+            const batch = await run.source.drain(this.#maxEventsPerDrain);
+            run.diff.applyAll(batch.events);
+            // Accumulated, never overwritten: a run that was degraded at 10:01 is
+            // still a run whose diff has a hole, even if the drain at 10:02 was
+            // clean. Completeness is a property of the RECORD, not of the last read.
+            if (batch.degraded)
+                run.degraded = true;
+            run.droppedEvents += batch.droppedEvents ?? 0;
+            for (const problem of batch.problems ?? [])
+                run.problems.add(problem);
+            if (!batch.morePending)
+                break;
+            // Falling out of this loop with `morePending` still true is not an error:
+            // the next poll continues. Blocking here until a busy run went quiet
+            // would make one noisy sandbox stall the host — the bound is the point.
+        }
+        const snapshot = this.snapshot(runId);
+        if (snapshot)
+            this.#emit(summarise(snapshot));
+        return snapshot;
+    }
+    /**
+     * What a run can deliver for a capability, and from which tier.
+     *
+     * §8: *"Reporting them unavailable for a third-party agent is a defect, not
+     * honest degradation — the data is in the sandbox."* This is the only place
+     * that can answer honestly, because it is the only place that knows whether a
+     * sandbox is actually being observed for this run — so the answer is DERIVED
+     * from that fact rather than configured.
+     *
+     * `acp` and `vendorSideChannel` are passed in by the caller, which knows what
+     * the run's provider supports. Absent, the answer is the tier-1 one: correct
+     * for a third-party agent in `native-tui`, which is the case §2.9 exists for.
+     */
+    capabilityFor(runId, capability, sources = {}) {
+        return resolveCapabilityTier(capability, {
+            // Observed means observed. A run this service has never been told about
+            // has no sandbox stream as far as anything here can tell, and claiming
+            // tier 1 for it would invent the sensor §2.9 rests on.
+            sandboxObservation: this.#runs.has(runId),
+            vendorSideChannel: sources.vendorSideChannel ?? false,
+            acp: sources.acp ?? false,
+        });
+    }
+    /**
+     * Where the observed runs collide — §5.7 conflict-aware landing.
+     *
+     * Computed from OBSERVED diffs rather than from claims, because nothing forces
+     * an agent to claim a path before writing it, and the agent that surprises us
+     * is exactly the one whose overlap matters. Claims remain complementary: pass
+     * them in and the report says whether a collision was invisible to the
+     * registry or whether a claim was released.
+     *
+     * Available *while the runs are alive*, which is the point — after the merge
+     * it is archaeology. Completeness rides along: a run with a hole in its diff
+     * cannot rule out an overlap, and `mayLand` refuses on that rather than
+     * reporting a clean landing it did not measure.
+     */
+    landingOverlaps(claimedPathsByRun = {}, 
+    /**
+     * 🔴 Runs the CALLER knows exist. Any of them this service never observed
+     * makes the report incomplete, so `mayLand` refuses.
+     *
+     * This rule lives HERE, not in the caller, because it was in the caller
+     * once and the shipping landing gate bypassed it: `apps/desktop` calls this
+     * method directly while the host's RPC reader had its own copy of the check.
+     * The surface told the truth and the gate that actually merges did not —
+     * so the rule belongs where every caller passes through.
+     *
+     * A caller that knows of no other runs passes nothing and loses nothing.
+     */
+    knownRunIds = []) {
+        const sets = [];
+        for (const runId of this.#runs.keys()) {
+            const snapshot = this.snapshot(runId);
+            if (!snapshot)
+                continue;
+            const claimed = claimedPathsByRun[runId];
+            sets.push({
+                runId,
+                changes: snapshot.changes.map((change) => ({ path: change.path, kind: change.kind })),
+                complete: snapshot.complete,
+                ...(claimed ? { claimedPaths: claimed } : {}),
+            });
+        }
+        const report = detectLandingOverlaps(sets);
+        const observed = new Set(sets.map((set) => set.runId));
+        const unobserved = [...new Set([...knownRunIds, ...Object.keys(claimedPathsByRun)])]
+            .filter((runId) => !observed.has(runId))
+            .sort();
+        if (unobserved.length === 0)
+            return report;
+        return {
+            ...report,
+            // Both kinds of hole in one list: the reader's next action is the same.
+            incompleteRuns: [...new Set([...report.incompleteRuns, ...unobserved])].sort(),
+            complete: false,
+        };
+    }
+    /** The current diff without draining. */
+    snapshot(runId) {
+        const run = this.#runs.get(runId);
+        if (!run)
+            return undefined;
+        return {
+            runId,
+            changes: run.diff.changes(),
+            // Dropped events are the definitive incompleteness: those changes exist
+            // on disk and are absent from this diff forever.
+            complete: !run.degraded && run.droppedEvents === 0,
+            droppedEvents: run.droppedEvents,
+            problems: [...run.problems],
+        };
+    }
+}
+function summarise(snapshot) {
+    let added = 0;
+    let modified = 0;
+    let deleted = 0;
+    for (const change of snapshot.changes) {
+        if (change.kind === 'added')
+            added += 1;
+        else if (change.kind === 'modified')
+            modified += 1;
+        else
+            deleted += 1;
+    }
+    return {
+        runId: snapshot.runId,
+        added,
+        modified,
+        deleted,
+        complete: snapshot.complete,
+        droppedEvents: snapshot.droppedEvents,
+    };
+}
+//# sourceMappingURL=RunObservationService.js.map

package/dist/observation/RunObservationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunObservationService.js","sourceRoot":"","sources":["../../src/observation/RunObservationService.ts"],"names":[],"mappings":"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"}

package/dist/observation/XenoUseObservationSource.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `RunObservationSource` over `xeno-use`'s HTTP surface.
+ *
+ * 🔒 **This is the ONLY sanctioned way this repo consumes `xeno-use`** — locked
+ * decision 17. `xeno-use` is AGPL-3.0 and this package is proprietary, so
+ * importing `@xeno-use/*` or linking its N-API binding would make this a
+ * derivative work. An HTTP client is not linkage.
+ *
+ * ⚠️ **Nothing here may import from `xeno-use`.** The batch shape is redeclared
+ * by `RunObservationSource`; this file only knows a URL and a JSON shape. If a
+ * future change makes it convenient to import a type from there, that
+ * convenience is the boundary being crossed.
+ *
+ * ## Why a poll and not a stream
+ *
+ * The remote drain is bounded and reports `more_pending`, so this is a few
+ * requests per second per sandbox rather than one per event — measured at ~30
+ * requests/second across six concurrent sandboxes. That is why this needed no
+ * WebSocket, no SSE, and no reconnect logic: there is no long-lived connection
+ * to lose.
+ */
+import type { RunObservationBatch, RunObservationSource } from './RunObservationService.js';
+export interface XenoUseObservationSourceOptions {
+    /** Base URL of the `xeno-use` service, e.g. `http://127.0.0.1:8787`. */
+    baseUrl: string;
+    sandboxId: string;
+    /** Bearer token. Its workspace is what authorizes every call — the sandbox id
+     *  alone proves nothing, which is the point of the remote ownership check. */
+    token: string;
+    /** Injected so this is testable without a server, and so a composition can
+     *  supply a fetch with its own timeouts and proxy rules. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout. A drain that never returns would stall the poll loop
+     *  that owns it, so there is no unbounded wait anywhere on this path. */
+    timeoutMs?: number;
+}
+export declare class XenoUseObservationSource implements RunObservationSource {
+    #private;
+    constructor(options: XenoUseObservationSourceOptions);
+    drain(maxEvents: number): Promise<RunObservationBatch>;
+}
+//# sourceMappingURL=XenoUseObservationSource.d.ts.map

package/dist/observation/XenoUseObservationSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XenoUseObservationSource.d.ts","sourceRoot":"","sources":["../../src/observation/XenoUseObservationSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAc3F,MAAM,WAAW,+BAA+B;IAC9C,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB;kFAC8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb;gEAC4D;IAC5D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B;6EACyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAID,qBAAa,wBAAyB,YAAW,oBAAoB;;gBAKvD,OAAO,EAAE,+BAA+B;IAU9C,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAuE7D"}

package/dist/observation/XenoUseObservationSource.js

@@ -0,0 +1,104 @@
+/**
+ * `RunObservationSource` over `xeno-use`'s HTTP surface.
+ *
+ * 🔒 **This is the ONLY sanctioned way this repo consumes `xeno-use`** — locked
+ * decision 17. `xeno-use` is AGPL-3.0 and this package is proprietary, so
+ * importing `@xeno-use/*` or linking its N-API binding would make this a
+ * derivative work. An HTTP client is not linkage.
+ *
+ * ⚠️ **Nothing here may import from `xeno-use`.** The batch shape is redeclared
+ * by `RunObservationSource`; this file only knows a URL and a JSON shape. If a
+ * future change makes it convenient to import a type from there, that
+ * convenience is the boundary being crossed.
+ *
+ * ## Why a poll and not a stream
+ *
+ * The remote drain is bounded and reports `more_pending`, so this is a few
+ * requests per second per sandbox rather than one per event — measured at ~30
+ * requests/second across six concurrent sandboxes. That is why this needed no
+ * WebSocket, no SSE, and no reconnect logic: there is no long-lived connection
+ * to lose.
+ */
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class XenoUseObservationSource {
+    #options;
+    constructor(options) {
+        this.#options = {
+            baseUrl: options.baseUrl.replace(/\/+$/, ''),
+            sandboxId: options.sandboxId,
+            token: options.token,
+            fetch: options.fetch ?? globalThis.fetch,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        };
+    }
+    async drain(maxEvents) {
+        const { baseUrl, sandboxId, token, fetch, timeoutMs } = this.#options;
+        const url = `${baseUrl}/v1/use/sandbox/${encodeURIComponent(sandboxId)}/observation/drain?max=${maxEvents}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${token}` },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                return this.#unreachable(`the observation service answered ${response.status}`);
+            }
+            const body = (await response.json());
+            return this.#toBatch(body);
+        }
+        catch (error) {
+            return this.#unreachable(error instanceof Error && error.name === 'AbortError'
+                ? `the observation service did not answer within ${timeoutMs}ms`
+                : 'the observation service could not be reached');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * 🔴 A failure is DEGRADED, never an empty batch.
+     *
+     * An unreachable service and a sandbox that changed nothing produce the same
+     * zero events, and reading the first as the second is the false-clean diff
+     * this whole path exists to prevent — now with a network in the middle, which
+     * makes it far likelier. `degraded` propagates through `RunObservationService`
+     * into the snapshot and on into `mayLand`, which refuses to land on it.
+     *
+     * It does NOT count as `droppedEvents`: nothing is known to have been lost.
+     * Events may still be waiting on the other side, which is a different fact
+     * from events that will never arrive.
+     */
+    #unreachable(reason) {
+        return {
+            events: [],
+            morePending: false,
+            degraded: true,
+            droppedEvents: 0,
+            problems: [reason],
+        };
+    }
+    #toBatch(body) {
+        const data = body.data;
+        if (!data) {
+            return this.#unreachable('the observation service returned no data');
+        }
+        return {
+            // Unknown event kinds are DROPPED and reported rather than coerced: a
+            // kind this build does not understand must not become `modified` by
+            // default, which would put a fabricated change in a diff.
+            events: (data.events ?? []).flatMap((event) => event.path && isEventKind(event.kind)
+                ? [{ kind: event.kind, path: event.path }]
+                : []),
+            morePending: data.more_pending === true,
+            degraded: data.degraded === true,
+            droppedEvents: data.dropped_events ?? 0,
+            problems: data.problems ?? [],
+        };
+    }
+}
+function isEventKind(value) {
+    return value === 'created' || value === 'modified' || value === 'removed';
+}
+//# sourceMappingURL=XenoUseObservationSource.js.map

package/dist/observation/XenoUseObservationSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XenoUseObservationSource.js","sourceRoot":"","sources":["../../src/observation/XenoUseObservationSource.ts"],"names":[],"mappings":"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"}

package/dist/observation/XenoUseRunObserver.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Binds a RUN to a real sandbox, so tier-1 observation reaches the running app.
+ *
+ * `RunObservationService` folds a stream it is given; `XenoUseObservationSource`
+ * carries that stream over HTTP. Neither of them starts anything. Something has
+ * to spawn the sandbox, mount the run's directory into it, tell `xeno-use` to
+ * watch it, work out what was already there, and register all of that against a
+ * run id — and then take it down again. That is this.
+ *
+ * Without it the service is mounted and permanently empty, which is the exact
+ * "built, tested, unreachable" shape this ecosystem has shipped four times.
+ *
+ * 🔒 **HTTP only** (locked decision 17). `xeno-use` is AGPL-3.0 and this package
+ * is proprietary, so nothing here imports from it — the request bodies and JSON
+ * shapes are written out by hand for the same reason `RunObservationSource`
+ * redeclares its event type. That is the boundary, not duplication.
+ *
+ * ## 🔴 A failed start must NOT register the run
+ *
+ * This is the rule the whole module is organised around. If a sandbox cannot be
+ * created and the run is registered anyway, everything downstream reports
+ * success: `capabilityFor` answers tier 1 because the service has the run,
+ * `snapshot` answers `changes: [], complete: true` because nothing arrived, and
+ * a reviewer is shown a clean diff of a run that was never watched. An
+ * unobserved run must therefore be *absent*, and absent is what every consumer
+ * already handles honestly — `capabilityFor` drops below tier 1 and `mayLand`
+ * refuses for want of a diff.
+ *
+ * Degrading loudly is right when observation started and then broke. Refusing
+ * to start is right when it never began. They are different facts and this
+ * distinction is what keeps them apart.
+ */
+import type { RunContentReader, RunObservationService } from './RunObservationService.js';
+/** What the run's directory is called on each side of the mount. */
+export interface RunMountRequest {
+    /** Host directory holding the run's work, e.g. `D:\work\repo`. */
+    hostDirectory: string;
+    /** Where it appears inside the sandbox. Events come back in THESE terms. */
+    containerDirectory?: string;
+    readOnly?: boolean;
+}
+/**
+ * The paths that already existed when the run began, in CONTAINER terms.
+ *
+ * A port, because walking a filesystem is a node-side concern and this class is
+ * otherwise pure HTTP. `complete: false` is a first-class answer: a baseline
+ * that hit its bound is not "a slightly shorter list", it is a list that will
+ * report pre-existing files as things the agent added.
+ */
+export interface RunBaselineScanner {
+    scan(request: {
+        hostDirectory: string;
+        containerDirectory: string;
+    }): Promise<{
+        paths: string[];
+        complete: boolean;
+        problem?: string;
+    }>;
+}
+export interface XenoUseRunObserverOptions {
+    /** Base URL of the `xeno-use` service, e.g. `http://127.0.0.1:8787`. */
+    baseUrl: string;
+    /** Bearer token. Its workspace is what authorizes every call. */
+    token: string;
+    service: RunObservationService;
+    /** Container image for the observation sandbox. `xeno-use`'s default when omitted. */
+    image?: string;
+    baselineScanner?: RunBaselineScanner;
+    /** Builds the hunk-content reader once the mount is known. Optional: review
+     *  degrades to a change list without it, which is honest and still useful. */
+    createContentReader?: (mount: {
+        hostDirectory: string;
+        containerDirectory: string;
+    }) => RunContentReader;
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout for the lifecycle calls. Distinct from the drain's own:
+     *  spawning a container is slower than reading a batch off one. */
+    timeoutMs?: number;
+    /** Reported rather than thrown. A run whose observation could not start is a
+     *  run that proceeds unobserved — never a run that fails to start. */
+    onProblem?: (problem: {
+        runId: string;
+        reason: string;
+    }) => void;
+}
+/**
+ * The sandbox a run is bound to, in both sides' terms.
+ *
+ * Exposed so a composition can route EXECUTION into the same container this
+ * observes — which is ADE §2.9's architecture, not a shortcut: the observation
+ * plane is meant to watch the sandbox the agent runs in. What was never
+ * legitimate, and is what `isolationIsNotObservation.test.ts` pins, is deriving
+ * `sandboxed` from this binding while execution still goes to the host. The
+ * binding is necessary for containment; it has never been sufficient.
+ */
+export interface RunSandboxDescriptor {
+    sandboxId: string;
+    hostDirectory: string;
+    containerDirectory: string;
+}
+export declare class XenoUseRunObserver {
+    #private;
+    constructor(options: XenoUseRunObserverOptions);
+    /**
+     * The sandbox bound to a run, for a composition routing EXECUTION into it.
+     *
+     * Returns `undefined` when the run has none — which every caller must treat
+     * as "not confined", never as "probably fine". Deliberately a plain lookup
+     * with no side effects: asking where a run executes must not start anything.
+     */
+    sandboxFor(runId: string): RunSandboxDescriptor | undefined;
+    /** Runs this observer currently holds a sandbox for. */
+    observedRuns(): string[];
+    /**
+     * Starts observing `runId` against a fresh sandbox mounting `hostDirectory`.
+     *
+     * Resolves `true` when the run is registered and genuinely being watched, and
+     * `false` when it is not — including every failure. It never throws: a broken
+     * observation service must not take a turn down with it, because observation
+     * is a review capability and the run itself is the user's actual work.
+     *
+     * Idempotent per run: a second call while the first is in flight, or after it
+     * succeeded, returns the first answer rather than spawning another container.
+     */
+    start(runId: string, mount: RunMountRequest): Promise<boolean>;
+    /**
+     * Stops observing and removes the sandbox.
+     *
+     * The service entry is dropped FIRST and unconditionally. If the remote
+     * teardown fails, the alternative — leaving the run registered against a dead
+     * sandbox — means every later poll degrades against a container that no longer
+     * exists, which reads as "the agent's changes were lost" rather than "we
+     * stopped looking".
+     */
+    stop(runId: string): Promise<void>;
+    /** Tears every observation down. For app shutdown: a leaked container outlives
+     *  the process that spawned it, which is how six were once found running. */
+    stopAll(): Promise<void>;
+}
+//# sourceMappingURL=XenoUseRunObserver.d.ts.map

package/dist/observation/XenoUseRunObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XenoUseRunObserver.d.ts","sourceRoot":"","sources":["../../src/observation/XenoUseRunObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,4BAA4B,CAAA;AAGnC,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,OAAO,EAAE;QACZ,aAAa,EAAE,MAAM,CAAA;QACrB,kBAAkB,EAAE,MAAM,CAAA;KAC3B,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtE;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,qBAAqB,CAAA;IAC9B,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,kBAAkB,CAAA;IACpC;kFAC8E;IAC9E,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE;QAC5B,aAAa,EAAE,MAAM,CAAA;QACrB,kBAAkB,EAAE,MAAM,CAAA;KAC3B,KAAK,gBAAgB,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B;uEACmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;0EACsE;IACtE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACjE;AAWD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,qBAAa,kBAAkB;;gBAejB,OAAO,EAAE,yBAAyB;IAY9C;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAU3D,wDAAwD;IACxD,YAAY,IAAI,MAAM,EAAE;IAIxB;;;;;;;;;;OAUG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAmEpE;;;;;;;;OAQG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC;iFAC6E;IACvE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgF/B"}