@xenosystem/agent-interface-host 0.1.3

package/dist/isolation/RunExecutionEnvironment.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Where a run's commands execute, and what that means for containment — ADE §5.3.
+ *
+ * 🔴 **The two answers come from ONE lookup, and that is the whole point.**
+ *
+ * The reporting half (`RunIsolationService`) and the enforcing half
+ * (`SandboxCommandExecutor`) were built separately and could trivially disagree:
+ * a composition could install the sandbox executor and forget to flip the
+ * report, and the product would confine correctly while telling the user it does
+ * not — or, far worse, the reverse. Two facts that must always agree, written in
+ * two places, is the shape this ecosystem has shipped repeatedly.
+ *
+ * So neither is stored. `resolve()` produces BOTH from the same record, and
+ * `executorFor`/`isolationFor` are thin readers of it. A mismatch is not
+ * "prevented by a test"; there is no code path that can express one.
+ *
+ * ## Which sites this serves — and which it deliberately does not
+ *
+ * §5.3 is about confining the AGENT. It is not about confining our own
+ * plumbing, and the distinction is load-bearing:
+ *
+ * - **Agent-reachable** — `workspace.command.run` and the agent's terminal tool.
+ *   The agent chooses what runs. These are what a sandbox exists to contain.
+ * - **Host plumbing** — `EngineeringWorkbenchService`'s `git`/`gh` checks. We
+ *   choose what runs, and it needs the user's git credentials, their `gh` auth
+ *   and network access. Routing it into a `--network none`, `--read-only`
+ *   container would break every check while confining nothing that was ever a
+ *   threat. It stays LOCAL, deliberately, and this class is not offered to it.
+ *
+ * Stated here because "we sandboxed some of it" is exactly the kind of partial
+ * truth that gets remembered as "it's sandboxed".
+ *
+ * ## The identity mismatch, and why it is resolved here
+ *
+ * Isolation is a property of a RUN. The call sites know a CONVERSATION —
+ * `AgentWorkspaceAccessContext` carries `conversationId`, not `runId`. Rather
+ * than push that mismatch onto every caller, the binding records both and this
+ * class indexes by each. The host already has both at the one moment that
+ * matters: `runObservationBinder.begin` is handed `{ runId, conversationId }`.
+ */
+import type { CommandExecutionPort } from './CommandExecution.js';
+import type { RunIsolation, RunIsolationReport, RunIsolationSource } from './RunIsolationService.js';
+import { type SandboxCommandMount } from './SandboxCommandExecutor.js';
+/** What confines a run, when something does. Supplied by the composition. */
+export interface RunSandboxBinding {
+    sandboxId: string;
+    mount: SandboxCommandMount;
+    /** Base URL of the `xeno-use` service. */
+    baseUrl: string;
+    token: string;
+    /**
+     * What is doing the confining, in the substrate's own words — surfaced to the
+     * user beside `sandboxed`. Free-form because this host does not own that
+     * vocabulary.
+     */
+    mechanism: string;
+}
+/** Everything a run's execution site needs, produced together. */
+export interface RunExecutionResolution {
+    executor: CommandExecutionPort;
+    isolation: RunIsolationReport;
+}
+/**
+ * A sandbox that is still being created.
+ *
+ * 🔴 This exists to close a RACE, and the race produces exactly the lie every
+ * gate in this directory exists to prevent. Spawning a container takes seconds
+ * and the composition deliberately does not block a turn on it. So a run can
+ * begin, execute its first command, and only then acquire a sandbox — with the
+ * command having run on the HOST while the run goes on to report `sandboxed`.
+ *
+ * The fix is not to make the spawn synchronous (that stalls every turn) and not
+ * to upgrade the report mid-run (isolation is a property of a RUN; a value that
+ * changes halfway describes neither half). It is to make the EXECUTOR wait:
+ * `execute()` is already async, so a command issued before the container is
+ * ready simply waits for it. No command runs unconfined, no turn is blocked for
+ * a run that never executes anything, and the report is true from the start.
+ *
+ * If the spawn FAILS the run reports `unknown` — not `none`. Nothing executed
+ * unconfined (the executor refuses rather than falling back), so "unconfined" is
+ * the wrong word; what is true is that the host cannot say what confined it.
+ */
+export type PendingSandbox = Promise<RunSandboxBinding | undefined>;
+export interface RunExecutionEnvironmentOptions {
+    /**
+     * Used for every run that has no sandbox. Injectable so a test can observe
+     * which implementation a resolution actually chose, rather than inferring it.
+     */
+    localExecutor?: CommandExecutionPort;
+    createSandboxExecutor?: (binding: RunSandboxBinding) => CommandExecutionPort;
+}
+export declare class RunExecutionEnvironment implements RunIsolationSource {
+    #private;
+    constructor(options?: RunExecutionEnvironmentOptions);
+    /**
+     * Records where a run executes.
+     *
+     * 🔴 Called for EVERY run, with or without a sandbox — the same discipline
+     * `runObservationBinder.begin` follows. A run that is bound without one is
+     * positively known to be unconfined; a run that was never bound is a run this
+     * host has no record of, and those are different answers.
+     */
+    bind(context: {
+        runId: string;
+        conversationId: string;
+        sandbox?: RunSandboxBinding;
+        /**
+         * A sandbox still being created. Commands WAIT for it rather than running
+         * on the host — see `PendingSandbox`.
+         *
+         * Resolving to `undefined` means the spawn failed, and the run then reports
+         * `unknown`: nothing ran unconfined, so `none` would be the wrong word.
+         */
+        pendingSandbox?: PendingSandbox;
+    }): void;
+    release(runId: string): void;
+    /**
+     * The single lookup. Everything else on this class reads it.
+     *
+     * An unknown run resolves to the LOCAL executor and `unknown` — not `none`.
+     * The two are genuinely different and the distinction is the one that matters
+     * for a user's next action: `none` says nothing confines this, `unknown` says
+     * this host cannot account for the run at all, and the second is the one where
+     * they should not proceed. Reporting `none` here would turn "I have no record"
+     * into a confident all-clear.
+     */
+    resolve(runId: string | undefined): RunExecutionResolution;
+    /** The executor for a CONVERSATION's current run — the identity call sites have. */
+    executorFor(conversationId: string | undefined): CommandExecutionPort;
+    /** `RunIsolationSource`. Same lookup, so it cannot disagree with the executor. */
+    isolationFor(runId: string): RunIsolationReport | undefined;
+    /** Whether a run is confined — for tests and diagnostics that want the bare fact. */
+    isolationKindFor(runId: string): RunIsolation;
+}
+//# sourceMappingURL=RunExecutionEnvironment.d.ts.map

package/dist/isolation/RunExecutionEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunExecutionEnvironment.d.ts","sourceRoot":"","sources":["../../src/isolation/RunExecutionEnvironment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AACpG,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAA;AAEpC,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,mBAAmB,CAAA;IAC1B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,SAAS,EAAE,kBAAkB,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAA;AAWnE,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAA;IACpC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,oBAAoB,CAAA;CAC7E;AAED,qBAAa,uBAAwB,YAAW,kBAAkB;;gBAOpD,OAAO,GAAE,8BAAmC;IAaxD;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,EAAE;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,cAAc,EAAE,MAAM,CAAA;QACtB,OAAO,CAAC,EAAE,iBAAiB,CAAA;QAC3B;;;;;;WAMG;QACH,cAAc,CAAC,EAAE,cAAc,CAAA;KAChC,GAAG,IAAI;IAiER,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAW5B;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,sBAAsB;IA0C1D,oFAAoF;IACpF,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB;IAKrE,kFAAkF;IAClF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI3D,qFAAqF;IACrF,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;CAG9C"}

package/dist/isolation/RunExecutionEnvironment.js

@@ -0,0 +1,206 @@
+/**
+ * Where a run's commands execute, and what that means for containment — ADE §5.3.
+ *
+ * 🔴 **The two answers come from ONE lookup, and that is the whole point.**
+ *
+ * The reporting half (`RunIsolationService`) and the enforcing half
+ * (`SandboxCommandExecutor`) were built separately and could trivially disagree:
+ * a composition could install the sandbox executor and forget to flip the
+ * report, and the product would confine correctly while telling the user it does
+ * not — or, far worse, the reverse. Two facts that must always agree, written in
+ * two places, is the shape this ecosystem has shipped repeatedly.
+ *
+ * So neither is stored. `resolve()` produces BOTH from the same record, and
+ * `executorFor`/`isolationFor` are thin readers of it. A mismatch is not
+ * "prevented by a test"; there is no code path that can express one.
+ *
+ * ## Which sites this serves — and which it deliberately does not
+ *
+ * §5.3 is about confining the AGENT. It is not about confining our own
+ * plumbing, and the distinction is load-bearing:
+ *
+ * - **Agent-reachable** — `workspace.command.run` and the agent's terminal tool.
+ *   The agent chooses what runs. These are what a sandbox exists to contain.
+ * - **Host plumbing** — `EngineeringWorkbenchService`'s `git`/`gh` checks. We
+ *   choose what runs, and it needs the user's git credentials, their `gh` auth
+ *   and network access. Routing it into a `--network none`, `--read-only`
+ *   container would break every check while confining nothing that was ever a
+ *   threat. It stays LOCAL, deliberately, and this class is not offered to it.
+ *
+ * Stated here because "we sandboxed some of it" is exactly the kind of partial
+ * truth that gets remembered as "it's sandboxed".
+ *
+ * ## The identity mismatch, and why it is resolved here
+ *
+ * Isolation is a property of a RUN. The call sites know a CONVERSATION —
+ * `AgentWorkspaceAccessContext` carries `conversationId`, not `runId`. Rather
+ * than push that mismatch onto every caller, the binding records both and this
+ * class indexes by each. The host already has both at the one moment that
+ * matters: `runObservationBinder.begin` is handed `{ runId, conversationId }`.
+ */
+import { LocalCommandExecutor } from './LocalCommandExecutor.js';
+import { SandboxCommandExecutor, } from './SandboxCommandExecutor.js';
+export class RunExecutionEnvironment {
+    #runs = new Map();
+    /** conversationId → runId. Rebuilt on bind/release so it cannot outlive its run. */
+    #byConversation = new Map();
+    #localExecutor;
+    #createSandboxExecutor;
+    constructor(options = {}) {
+        this.#localExecutor = options.localExecutor ?? new LocalCommandExecutor();
+        this.#createSandboxExecutor =
+            options.createSandboxExecutor ??
+                ((binding) => new SandboxCommandExecutor({
+                    baseUrl: binding.baseUrl,
+                    token: binding.token,
+                    sandboxId: binding.sandboxId,
+                    mount: binding.mount,
+                }));
+    }
+    /**
+     * Records where a run executes.
+     *
+     * 🔴 Called for EVERY run, with or without a sandbox — the same discipline
+     * `runObservationBinder.begin` follows. A run that is bound without one is
+     * positively known to be unconfined; a run that was never bound is a run this
+     * host has no record of, and those are different answers.
+     */
+    bind(context) {
+        const record = { conversationId: context.conversationId };
+        if (context.sandbox) {
+            record.sandbox = {
+                executor: this.#createSandboxExecutor(context.sandbox),
+                mechanism: context.sandbox.mechanism,
+            };
+        }
+        else if (context.pendingSandbox) {
+            const pending = { executor: undefined, failed: false };
+            const ready = context.pendingSandbox.then((binding) => {
+                if (!binding) {
+                    pending.failed = true;
+                    return undefined;
+                }
+                pending.executor = this.#createSandboxExecutor(binding);
+                const current = this.#runs.get(context.runId);
+                // Only if this record is still the live one: a second run on the same
+                // conversation, or a release, must not be overwritten by a container
+                // that finished spawning for a run nobody is watching any more.
+                if (current === record) {
+                    current.sandbox = { executor: pending.executor, mechanism: binding.mechanism };
+                    delete current.pending;
+                }
+                return pending.executor;
+            }, () => {
+                pending.failed = true;
+                return undefined;
+            });
+            record.pending = {
+                failed: false,
+                // Every call waits on the SAME promise, so N commands issued during the
+                // spawn do not each try to create a container.
+                executor: {
+                    execute: async (request) => {
+                        const executor = await ready;
+                        if (!executor) {
+                            // Refused, never run locally. The whole point of waiting is that
+                            // no command escapes to the host; falling back here would undo it
+                            // at the one moment it matters.
+                            return {
+                                stdout: '',
+                                stderr: '',
+                                exitCode: null,
+                                timedOut: false,
+                                truncated: false,
+                                error: 'The sandbox for this run could not be created, so the command was not run.',
+                            };
+                        }
+                        return await executor.execute(request);
+                    },
+                },
+            };
+            // `failed` is read through the closure below rather than copied.
+            Object.defineProperty(record.pending, 'failed', {
+                get: () => pending.failed,
+                enumerable: true,
+            });
+        }
+        this.#runs.set(context.runId, record);
+        this.#byConversation.set(context.conversationId, context.runId);
+    }
+    release(runId) {
+        const record = this.#runs.get(runId);
+        if (!record)
+            return;
+        this.#runs.delete(runId);
+        // Only if it still points here: a conversation can start a second run, and
+        // releasing the first must not orphan the second's index entry.
+        if (this.#byConversation.get(record.conversationId) === runId) {
+            this.#byConversation.delete(record.conversationId);
+        }
+    }
+    /**
+     * The single lookup. Everything else on this class reads it.
+     *
+     * An unknown run resolves to the LOCAL executor and `unknown` — not `none`.
+     * The two are genuinely different and the distinction is the one that matters
+     * for a user's next action: `none` says nothing confines this, `unknown` says
+     * this host cannot account for the run at all, and the second is the one where
+     * they should not proceed. Reporting `none` here would turn "I have no record"
+     * into a confident all-clear.
+     */
+    resolve(runId) {
+        const record = runId === undefined ? undefined : this.#runs.get(runId);
+        if (!record) {
+            return {
+                executor: this.#localExecutor,
+                isolation: {
+                    isolation: 'unknown',
+                    reason: 'This host has no record of the run these commands belong to.',
+                },
+            };
+        }
+        if (record.sandbox) {
+            return {
+                executor: record.sandbox.executor,
+                isolation: { isolation: 'sandboxed', mechanism: record.sandbox.mechanism },
+            };
+        }
+        if (record.pending) {
+            // A spawn that FAILED. `unknown`, not `none`: nothing ran unconfined —
+            // the waiting executor refuses rather than falling back — so "nothing
+            // confines this" is the wrong sentence. What is true is that the host
+            // cannot say what confined it.
+            if (record.pending.failed) {
+                return {
+                    executor: record.pending.executor,
+                    isolation: {
+                        isolation: 'unknown',
+                        reason: 'The sandbox for this run could not be created.',
+                    },
+                };
+            }
+            // Still spawning. Reported `sandboxed` because it is the answer that will
+            // be true for every command this run executes: the executor waits, so no
+            // command can reach the host in the meantime.
+            return {
+                executor: record.pending.executor,
+                isolation: { isolation: 'sandboxed', mechanism: 'container (starting)' },
+            };
+        }
+        return { executor: this.#localExecutor, isolation: { isolation: 'none' } };
+    }
+    /** The executor for a CONVERSATION's current run — the identity call sites have. */
+    executorFor(conversationId) {
+        const runId = conversationId === undefined ? undefined : this.#byConversation.get(conversationId);
+        return this.resolve(runId).executor;
+    }
+    /** `RunIsolationSource`. Same lookup, so it cannot disagree with the executor. */
+    isolationFor(runId) {
+        return this.resolve(runId).isolation;
+    }
+    /** Whether a run is confined — for tests and diagnostics that want the bare fact. */
+    isolationKindFor(runId) {
+        return this.resolve(runId).isolation.isolation;
+    }
+}
+//# sourceMappingURL=RunExecutionEnvironment.js.map

package/dist/isolation/RunExecutionEnvironment.js.map

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

package/dist/isolation/RunIsolationService.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Whether a run is CONTAINED — ADE §5.3's reporting half.
+ *
+ * §5.3: *"Isolation strength is surfaced in the UI — the user always knows
+ * whether the thing running is contained or not."* Nothing reported it. The
+ * settings surface went further and asserted the opposite, calling host
+ * execution "Sandboxed" until `181c251`; correcting that stopped the product
+ * lying, and left it silent. Silence is better than a lie and is still not what
+ * §5.3 asks for.
+ *
+ * ## This is the REPORTING half, deliberately not the enforcing half
+ *
+ * §5.3 puts implementing containers, VMs and worktrees explicitly out of scope
+ * for this repo, and its gate requires an out-of-mount write to be refused **by
+ * the substrate, not by a rule inside the shell it runs in**. So nothing here
+ * confines anything. It answers one question — *is this run contained?* — and
+ * answers it honestly while the answer is still "no".
+ *
+ * That ordering is not a compromise. A surface that can display containment is
+ * the thing that makes adopting a sandbox observable: land the adapter and the
+ * badge changes by itself. Building enforcement first would mean shipping
+ * containment nobody could see, which is how "sandboxed" got written in the UI
+ * in the first place.
+ *
+ * ## The source is a PORT — a licensing boundary before a design preference
+ *
+ * 🔴 **`xeno-use` is AGPL-3.0** and XENO Agent is proprietary, so this package
+ * must not import `@xeno-use/*`, link its N-API binding, or depend on it in any
+ * direction. `RunIsolationSource` is declared HERE, provider-neutral, and an
+ * adapter is supplied from outside — talking to `xeno-use` out of process over
+ * its own `/v1/use/*` surface. Exactly the shape `RunObservationSource` already
+ * uses one directory over, and for exactly the same reason.
+ */
+/**
+ * What confines a run, as a SHAPE rather than an import.
+ *
+ * `unknown` is a first-class member and the reason this is a three-member union
+ * rather than a boolean. The three are genuinely different facts:
+ *
+ * - `none` — POSITIVE knowledge that nothing confines this run. When no source
+ *   is configured at all, this is what the host knows: execution goes through
+ *   `WorkspaceHostService.runCommand` to a host process as the signed-in user.
+ *   "No sandbox is installed" is not ignorance about containment; it is
+ *   containment's absence, and the user is entitled to be told so plainly.
+ * - `sandboxed` — a source answered that this run is confined.
+ * - `unknown` — a source EXISTS and could not answer for this run. Never
+ *   collapse this into `none`: "nothing confines it" and "I could not find out"
+ *   lead a person to different actions, and the second one is the one where
+ *   they should not proceed.
+ */
+export type RunIsolation = 'none' | 'sandboxed' | 'unknown';
+export interface RunIsolationReport {
+    isolation: RunIsolation;
+    /**
+     * What is doing the confining, when something is — e.g. a container runtime.
+     *
+     * Free-form because this host does not own the vocabulary; the substrate does.
+     * Present ONLY alongside `sandboxed`: a mechanism named beside `none` would
+     * read as a confinement that exists and merely failed this time.
+     */
+    mechanism?: string;
+    /** Why the answer is `unknown`, when it is. Never a bare unknown. */
+    reason?: string;
+}
+/**
+ * A provider of containment facts. Supplied by the composition, never imported.
+ *
+ * Returning `undefined` for a run means the source has no opinion about it,
+ * which resolves to `unknown` — not to `none`. A source that knows a run is
+ * unconfined must say so by answering `none` explicitly.
+ */
+export interface RunIsolationSource {
+    isolationFor(runId: string): RunIsolationReport | undefined;
+}
+/**
+ * Answers "is this run contained?" for every run, with or without a source.
+ *
+ * 🔴 Constructed with NO source in the shipped composition today, and that path
+ * is the one that must be right: it reports `none`, because that is true.
+ */
+export declare class RunIsolationService {
+    #private;
+    constructor(options?: {
+        source?: RunIsolationSource;
+    });
+    /** Whether a containment substrate is configured at all. */
+    get hasSource(): boolean;
+    report(runId: string): RunIsolationReport;
+}
+//# sourceMappingURL=RunIsolationService.d.ts.map

package/dist/isolation/RunIsolationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunIsolationService.d.ts","sourceRoot":"","sources":["../../src/isolation/RunIsolationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAA;AAE3D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,YAAY,CAAA;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;CAC5D;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;;gBAGlB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,kBAAkB,CAAA;KAAO;IAIzD,4DAA4D;IAC5D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB;CAkC1C"}

package/dist/isolation/RunIsolationService.js

@@ -0,0 +1,86 @@
+/**
+ * Whether a run is CONTAINED — ADE §5.3's reporting half.
+ *
+ * §5.3: *"Isolation strength is surfaced in the UI — the user always knows
+ * whether the thing running is contained or not."* Nothing reported it. The
+ * settings surface went further and asserted the opposite, calling host
+ * execution "Sandboxed" until `181c251`; correcting that stopped the product
+ * lying, and left it silent. Silence is better than a lie and is still not what
+ * §5.3 asks for.
+ *
+ * ## This is the REPORTING half, deliberately not the enforcing half
+ *
+ * §5.3 puts implementing containers, VMs and worktrees explicitly out of scope
+ * for this repo, and its gate requires an out-of-mount write to be refused **by
+ * the substrate, not by a rule inside the shell it runs in**. So nothing here
+ * confines anything. It answers one question — *is this run contained?* — and
+ * answers it honestly while the answer is still "no".
+ *
+ * That ordering is not a compromise. A surface that can display containment is
+ * the thing that makes adopting a sandbox observable: land the adapter and the
+ * badge changes by itself. Building enforcement first would mean shipping
+ * containment nobody could see, which is how "sandboxed" got written in the UI
+ * in the first place.
+ *
+ * ## The source is a PORT — a licensing boundary before a design preference
+ *
+ * 🔴 **`xeno-use` is AGPL-3.0** and XENO Agent is proprietary, so this package
+ * must not import `@xeno-use/*`, link its N-API binding, or depend on it in any
+ * direction. `RunIsolationSource` is declared HERE, provider-neutral, and an
+ * adapter is supplied from outside — talking to `xeno-use` out of process over
+ * its own `/v1/use/*` surface. Exactly the shape `RunObservationSource` already
+ * uses one directory over, and for exactly the same reason.
+ */
+/**
+ * Answers "is this run contained?" for every run, with or without a source.
+ *
+ * 🔴 Constructed with NO source in the shipped composition today, and that path
+ * is the one that must be right: it reports `none`, because that is true.
+ */
+export class RunIsolationService {
+    #source;
+    constructor(options = {}) {
+        this.#source = options.source;
+    }
+    /** Whether a containment substrate is configured at all. */
+    get hasSource() {
+        return this.#source !== undefined;
+    }
+    report(runId) {
+        const source = this.#source;
+        if (!source) {
+            // No substrate is installed, so nothing confines anything. Stated as a
+            // fact rather than as an absence of information.
+            return { isolation: 'none' };
+        }
+        let answer;
+        try {
+            answer = source.isolationFor(runId);
+        }
+        catch (error) {
+            // A source that throws has not told us the run is unconfined; it has
+            // failed to tell us anything. Reporting `none` here would turn a broken
+            // sensor into a confident all-clear.
+            return {
+                isolation: 'unknown',
+                reason: `The isolation source failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+        if (!answer) {
+            return { isolation: 'unknown', reason: 'The isolation source has no record of this run.' };
+        }
+        if (answer.isolation === 'sandboxed') {
+            return {
+                isolation: 'sandboxed',
+                ...(answer.mechanism === undefined ? {} : { mechanism: answer.mechanism }),
+            };
+        }
+        if (answer.isolation === 'none')
+            return { isolation: 'none' };
+        return {
+            isolation: 'unknown',
+            ...(answer.reason === undefined ? {} : { reason: answer.reason }),
+        };
+    }
+}
+//# sourceMappingURL=RunIsolationService.js.map

package/dist/isolation/RunIsolationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunIsolationService.js","sourceRoot":"","sources":["../../src/isolation/RunIsolationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA8CH;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACrB,OAAO,CAAgC;IAEhD,YAAY,UAA2C,EAAE;QACvD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAA;IAC/B,CAAC;IAED,4DAA4D;IAC5D,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,KAAK,SAAS,CAAA;IACnC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAA;QAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,uEAAuE;YACvE,iDAAiD;YACjD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAA;QAC9B,CAAC;QACD,IAAI,MAAsC,CAAA;QAC1C,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,wEAAwE;YACxE,qCAAqC;YACrC,OAAO;gBACL,SAAS,EAAE,SAAS;gBACpB,MAAM,EAAE,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;aACjG,CAAA;QACH,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAA;QAC5F,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,KAAK,WAAW,EAAE,CAAC;YACrC,OAAO;gBACL,SAAS,EAAE,WAAW;gBACtB,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;aAC3E,CAAA;QACH,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,KAAK,MAAM;YAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAA;QAC7D,OAAO;YACL,SAAS,EAAE,SAAS;YACpB,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;SAClE,CAAA;IACH,CAAC;CACF"}

package/dist/isolation/SandboxCommandExecutor.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `CommandExecutionPort` over a `xeno-use` sandbox — the CONFINING implementation.
+ *
+ * Reached through `RunExecutionEnvironment`, which is what a composition wires
+ * and what decides — in ONE lookup — both that this executor serves a run and
+ * that the run reports `sandboxed`. Nothing constructs this directly.
+ *
+ * ⚠️ What remains before a run is actually confined is the BINDING: no
+ * composition yet spawns a sandbox the agent RUNS in. `XenoUseRunObserver`
+ * spawns an OBSERVATION sandbox, and binding execution to that one is exactly
+ * the convenient wrong turn `isolationIsNotObservation.test.ts` exists to pin —
+ * a sandbox that is watched is not a sandbox that confines. Everything
+ * downstream of the binding is now live, so that step is a spawn plus a
+ * `bind({ sandbox })`, not a rewrite.
+ *
+ * This is the other half of the port `LocalCommandExecutor` exists beside, and
+ * the reason the port was built at all: adopting a sandbox becomes a composition
+ * change rather than a rewrite at each call site. Where the local executor
+ * starts a real process on the user's machine as the signed-in user, this one
+ * runs the command inside a container with `--network none`, `--read-only`,
+ * `--cap-drop ALL`, a non-root uid, and only the mounts it was given.
+ *
+ * ## 🔒 Out of process, always — a licensing boundary before a design preference
+ *
+ * `xeno-use` is AGPL-3.0 and this package is proprietary, so nothing here
+ * imports `@xeno-use/*` or links its N-API binding. The request and response
+ * shapes are written out by hand and reached over `/v1/use/*` — exactly what
+ * `RunObservationSource` and `XenoUseRunObserver` already do, for exactly the
+ * same reason. It looks like duplication and is the boundary.
+ *
+ * ## 🔴 It NEVER falls back to local execution
+ *
+ * The single most important property in this file, and the one most likely to
+ * be "fixed" in later. If the sandbox is unreachable, this returns a FAILED
+ * result — it does not quietly run the command on the host instead. A fallback
+ * would mean a run reporting itself contained while executing with the user's
+ * full privileges, which is strictly worse than having no sandbox at all:
+ * without one the report says `none` and the user knows where they stand.
+ *
+ * Same shape as the convenient wrong turn `isolationIsNotObservation.test.ts`
+ * pins one directory over. A sandbox that is watched is not a sandbox that
+ * confines; a sandbox that silently degrades to the host does not confine
+ * either, and lies about it.
+ *
+ * ## Why the executor is bound to ONE sandbox
+ *
+ * `CommandExecutionRequest` carries no run id, deliberately — a call site asks
+ * to run a command, not to route one. So the binding happens at construction:
+ * the composition makes an executor per run, against that run's sandbox. A
+ * resolver taking a run id would put routing in the hot path and make "which
+ * sandbox did this actually run in?" a question with a computed answer.
+ */
+import type { CommandExecutionPort, CommandExecutionRequest, CommandExecutionResult } from './CommandExecution.js';
+/** Where the run's directory sits on each side of the mount. */
+export interface SandboxCommandMount {
+    /** Host directory holding the run's work, e.g. `D:\work\repo`. */
+    hostDirectory: string;
+    /** Where it appears inside the sandbox, e.g. `/mnt/xeno/work`. */
+    containerDirectory: string;
+}
+export interface SandboxCommandExecutorOptions {
+    /** Base URL of the `xeno-use` service, e.g. `http://127.0.0.1:8787`. */
+    baseUrl: string;
+    /** Bearer token. Its workspace is what authorizes the call. */
+    token: string;
+    /** The sandbox this executor runs in. One executor, one sandbox. */
+    sandboxId: string;
+    mount: SandboxCommandMount;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Maps a host path into container terms.
+ *
+ * Returns `undefined` when the path is not under the mount — which is not a
+ * security check. Confinement comes from the sandbox's filesystem namespace,
+ * not from a rule applied at the call: a process can `chdir` after it starts,
+ * so a path rule enforced on entry decides nothing. This is a REPRESENTABILITY
+ * question — a host directory outside the mount has no name inside the
+ * container, so the request cannot be expressed and must be refused rather than
+ * silently rewritten to the mount root.
+ *
+ * Case-insensitive on the host segment because Windows paths are, and the run
+ * directory reaching us from a UI and from a config may differ only in case.
+ * The CONTAINER half preserves case exactly — Linux paths are case-sensitive
+ * and folding them would produce a path that does not exist.
+ */
+export declare function toContainerPath(mount: SandboxCommandMount, hostPath: string): string | undefined;
+export declare class SandboxCommandExecutor implements CommandExecutionPort {
+    #private;
+    constructor(options: SandboxCommandExecutorOptions);
+    execute(request: CommandExecutionRequest): Promise<CommandExecutionResult>;
+}
+//# sourceMappingURL=SandboxCommandExecutor.d.ts.map

package/dist/isolation/SandboxCommandExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxCommandExecutor.d.ts","sourceRoot":"","sources":["../../src/isolation/SandboxCommandExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,uBAAuB,CAAA;AAE9B,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,mBAAmB,CAAA;IAC1B,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAapB;AAED,qBAAa,sBAAuB,YAAW,oBAAoB;;gBAOrD,OAAO,EAAE,6BAA6B;IAQ5C,OAAO,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;CA2FjF"}