@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/loop/plugins/agents/switchable.js

@@ -0,0 +1,405 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * One sandbox, four places it can run.
+ *
+ * `browser` is Pyodide in the page. The other three are server-backed and
+ * differ in what the server is asked to run: a Jupyter server beside you, an
+ * anonymous one anybody can reach, or a Datalayer runtime. A workspace should
+ * not care which; the notebook binds to whatever kernel is there, and the
+ * switch is one control.
+ *
+ * Local and `datalayer` bring an agent with them. Browser and anonymous
+ * Jupyter are sandbox-only, which is why `hasAgent` is part of the target's
+ * description rather than something each caller works out.
+ *
+ * The composite owns both implementations and delegates to the active one, so
+ * switching is a real swap rather than a flag: the old backing is disconnected
+ * before the new one starts, and every signal a view reads follows across.
+ *
+ * @module loop/plugins/agents/switchable
+ */
+import { computed, signal, } from '@datalayer/reactor';
+import { browserSource, createBrowserSandboxService, } from './browserService';
+import { createServerSandboxService, } from './service';
+/**
+ * The anonymous Jupyter server the `jupyter` target uses.
+ *
+ * The same one the jupyter-react examples point at: a real server, reachable
+ * without an account, so a workspace can execute code with nothing installed
+ * and nobody signed in.
+ */
+export const ANONYMOUS_JUPYTER_URL = 'https://prod1.datalayer.run/api/jupyter-server';
+export const ANONYMOUS_JUPYTER_TOKEN = '60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6';
+/** The four, in the order the control shows them: nearest first. */
+export const SANDBOX_TARGETS = [
+    'browser',
+    'local',
+    'jupyter',
+    'datalayer',
+];
+export const TARGET_SPECS = {
+    browser: {
+        label: 'Browser',
+        hint: 'Python in this page (Pyodide), with the agent loop running here too. Only the model is asked over the network.',
+        // The agent runs here now, with the Vercel AI SDK. "No server" stopped
+        // meaning "no agent" when the loop learned to turn in the page — and the
+        // location decides the harness, whatever a spec's own `harness` asks for,
+        // because a page cannot turn a pydantic-ai loop at all.
+        hasAgent: true,
+        noAgentReason: '',
+    },
+    local: {
+        label: 'Local',
+        hint: 'A local agent, with the Jupyter server it starts beside itself.',
+        hasAgent: true,
+        noAgentReason: '',
+        /*
+         * `jupyter-server` with the URL explicitly cleared.
+         *
+         * The variant names *where the sandbox is relative to the agent*, not
+         * which server it is: colocated, so the agent starts one and the UI drives
+         * that. Sending no URL is not the same as sending an empty one — the
+         * server reads a missing URL as "keep what you have", so coming here from
+         * the Jupyter target left the local agent driving the anonymous server on
+         * prod1, which is the opposite of what this target means.
+         */
+        configure: {
+            variant: 'jupyter-server',
+            jupyter_url: '',
+            jupyter_token: '',
+        },
+    },
+    jupyter: {
+        label: 'Jupyter',
+        // Named, unlike Local and Datalayer, whose servers belong to their agent.
+        hint: 'A named Jupyter server: the anonymous one on prod1.datalayer.run.',
+        hasAgent: false,
+        noAgentReason: 'No agent on an anonymous Jupyter server',
+        configure: {
+            variant: 'jupyter-server',
+            jupyter_url: ANONYMOUS_JUPYTER_URL,
+            jupyter_token: ANONYMOUS_JUPYTER_TOKEN,
+        },
+    },
+    datalayer: {
+        label: 'Datalayer',
+        hint: 'A Datalayer runtime running the agent this workspace asks for.',
+        hasAgent: true,
+        noAgentReason: '',
+        /*
+         * No `configure`, and that is the change.
+         *
+         * It used to tell the *host's* agent-runtimes server to put its sandbox on
+         * a Datalayer runtime — a Jupyter server in the cloud with the agent still
+         * running locally, which is not what the target says it is. A person
+         * picked Datalayer and stayed on whatever agent the host had.
+         *
+         * The agent is launched from an agentspec instead, by
+         * `DatalayerAgentBridge`, which reports the runtime it gets back.
+         */
+    },
+};
+/** Whether an agent runs on this target — the question the chat asks. */
+export function targetHasAgent(target) {
+    return TARGET_SPECS[target]?.hasAgent ?? false;
+}
+/**
+ * Whether that agent's loop turns in this page rather than on a server.
+ *
+ * The other half of {@link targetHasAgent}, and the one that decides which
+ * protocol a chat speaks: an in-page agent is reached by calling it, not by
+ * addressing it.
+ */
+export function targetRunsAgentInPage(target) {
+    return target === 'browser';
+}
+export function createSwitchableSandboxService({ serverUrl, initialTarget = 'local', kernelSource, localAgent, blueprint, }) {
+    const target = signal(initialTarget);
+    // Both implementations exist from the start, but neither connects until it is
+    // the active one — a Pyodide kernel that nobody asked for is megabytes of
+    // download, and a WebSocket to a server nobody chose is noise in the logs.
+    const server = createServerSandboxService(serverUrl);
+    const browser = createBrowserSandboxService(kernelSource ?? browserSource());
+    const active = computed(() => target.value === 'browser' ? browser : server);
+    let disconnect = null;
+    let agentId;
+    const snapshot = computed(() => active.value.snapshot.value);
+    const status = computed(() => active.value.status.value);
+    const ready = computed(() => active.value.ready.value);
+    const lastExecution = computed(() => active.value.lastExecution.value);
+    /**
+     * Ask the server to run what this target means, and wait for it to say yes.
+     *
+     * Awaited and checked rather than fired and forgotten: a switch that quietly
+     * failed left the control showing the new target while the old sandbox kept
+     * running, which is the worst of both — the header lies and nothing moved.
+     * The error travels back to the caller so the control can stay where it was.
+     */
+    async function applyVariant(next) {
+        /*
+         * Local needs both: an agent, and a sandbox told where to be.
+         *
+         * It used to return here, having started the agent — and never sent the
+         * `configure` below. The sandbox therefore kept whatever it was last set
+         * to, so arriving from the Jupyter target left the local agent executing
+         * on the anonymous server at prod1: `!hostname` in a cell answered with
+         * a pod name from the cloud.
+         *
+         * Starting the agent is a precondition for the switch, not the whole of
+         * it. The configure that follows is what makes the sandbox colocated.
+         */
+        if (next === 'local') {
+            // The blueprint — a capacity plugin's contribution — wins over the
+            // host's own `localAgent`: mounting the capacity is the more specific
+            // statement about what this workspace runs.
+            const createPayload = blueprint?.() ?? localAgent?.createPayload;
+            if (createPayload) {
+                await ensureLocalAgent(createPayload);
+            }
+        }
+        const configure = TARGET_SPECS[next]?.configure;
+        if (!configure) {
+            return;
+        }
+        const label = TARGET_SPECS[next].label;
+        let response;
+        try {
+            response = await fetch(`${serverUrl}/api/v1/agents/sandbox/configure`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(configure),
+            });
+        }
+        catch (reason) {
+            // `fetch` rejects rather than answering when nothing is listening, and
+            // the browser's message for that is "Failed to fetch" — which names
+            // neither the address nor the thing that should be at it. Every target
+            // but Browser needs an agent-runtimes server, and the commonest reason
+            // a switch does nothing is that nobody started one.
+            throw new Error(`${label} needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
+                `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
+        }
+        if (!response.ok) {
+            throw new Error(`The server could not switch to ${label} (${response.status} ${response.statusText}). ` +
+                (await detail(response)));
+        }
+        // Configure only changes what will be created on the next use. Starting it
+        // here makes the segmented control an operation rather than a preference:
+        // when the promise resolves, the selected sandbox has actually launched.
+        const restart = await fetch(`${serverUrl}/api/v1/agents/sandbox/restart`, {
+            method: 'POST',
+        });
+        if (!restart.ok) {
+            throw new Error(`The server could not start ${label} (${restart.status} ${restart.statusText}). ` +
+                (await detail(restart)));
+        }
+    }
+    /**
+     * Create the agent whose per-agent Jupyter sandbox backs Local.
+     *
+     * The payload is passed rather than read from the closure: the caller has
+     * already established that it exists, and TypeScript cannot carry that
+     * narrowing across a function boundary.
+     */
+    async function ensureLocalAgent(createPayload) {
+        const id = agentId?.trim();
+        if (!id) {
+            throw new Error('Local needs an agent id before its runtime can start.');
+        }
+        let existing;
+        try {
+            existing = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}`);
+        }
+        catch (reason) {
+            throw new Error(`Local needs an agent-runtimes server at ${serverUrl}, and nothing answered there. ` +
+                `Start one and try again. (${reason instanceof Error ? reason.message : String(reason)})`, { cause: reason });
+        }
+        if (existing.ok) {
+            // The agent is there, which does not mean its sandbox is. Reconfiguring
+            // or restarting the manager stops the per-agent sandboxes, because they
+            // were built under the previous settings — so coming back to Local after
+            // a spell on Jupyter finds the agent alive and nothing behind it. Asking
+            // for the sandbox is idempotent, so it costs a round trip and nothing
+            // else when one is already running.
+            await ensureLocalSandbox(id);
+            return;
+        }
+        if (existing.status !== 404) {
+            throw new Error(`The server could not inspect local agent ${id} (${existing.status} ${existing.statusText}). ` +
+                (await detail(existing)));
+        }
+        const created = await fetch(`${serverUrl}/api/v1/agents`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                // Defaults first, so a blueprint that names its own transport or
+                // sandbox variant — the sandbox capacity plugins do — wins over
+                // them; the name last, because Local's agent id is not negotiable.
+                transport: 'ag-ui',
+                sandbox_variant: 'jupyter-server',
+                ...createPayload,
+                name: id,
+            }),
+        });
+        if (!created.ok && created.status !== 409) {
+            throw new Error(`The server could not launch local agent ${id} (${created.status} ${created.statusText}). ` +
+                (await detail(created)));
+        }
+        // A 409 means somebody else created it between the two calls above, and
+        // that agent is as unlikely to have a sandbox as one found by the GET.
+        if (created.status === 409) {
+            await ensureLocalSandbox(id);
+        }
+    }
+    /**
+     * Make sure the agent has somewhere to run.
+     *
+     * Creating an agent starts its sandbox, so this is only ever needed for one
+     * that already existed. Selecting a target is an operation, not a
+     * preference: when the promise resolves the sandbox is meant to be up, and
+     * without this the kernel indicator sits empty and the notebook binds to
+     * nothing.
+     */
+    async function ensureLocalSandbox(id) {
+        const response = await fetch(`${serverUrl}/api/v1/agents/${encodeURIComponent(id)}/sandbox/ensure`, { method: 'POST' });
+        if (!response.ok) {
+            throw new Error(`The server could not start a sandbox for local agent ${id} ` +
+                `(${response.status} ${response.statusText}). ` +
+                (await detail(response)));
+        }
+    }
+    /**
+     * What the server said went wrong, when it said anything.
+     *
+     * FastAPI puts the reason in `detail`, and a status code on its own sends a
+     * reader to the network tab for something the response already contained.
+     */
+    async function detail(response) {
+        try {
+            const body = (await response.json());
+            return typeof body.detail === 'string' ? body.detail : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    function connectActive() {
+        disconnect?.();
+        /*
+         * Datalayer connects nothing here, and that is the whole of the fix.
+         *
+         * Every other server target is the host's own sandbox, and `connect`
+         * subscribes to that server's status stream. Datalayer is not: the agent
+         * runs on a runtime allocated from an agentspec, and `DatalayerAgentBridge`
+         * reports it through `report()`.
+         *
+         * Subscribing anyway meant the host's stream kept answering — with the
+         * variant it was last configured for, which is `jupyter-server` — and
+         * overwrote the bridge's report on its next poll. Picking Datalayer moved
+         * the target and left the workspace describing a Jupyter server, which is
+         * exactly what it looked like: a switch that did not take.
+         */
+        if (target.peek() === 'datalayer') {
+            disconnect = null;
+            // Said out loud, so the surfaces show "starting" rather than claiming
+            // there is nothing here while the runtime is allocated.
+            server.setState('starting');
+            return;
+        }
+        disconnect = active.peek().connect(agentId);
+    }
+    return {
+        get kind() {
+            return target.peek() === 'browser'
+                ? 'browser'
+                : 'server';
+        },
+        target,
+        snapshot,
+        status,
+        ready,
+        lastExecution,
+        serverUrl,
+        getServiceManager: () => target.peek() === 'browser' ? browser.getServiceManager() : null,
+        report(next) {
+            active.peek().report(next);
+        },
+        setState(state) {
+            active.peek().setState(state);
+        },
+        execute(code) {
+            return active.peek().execute(code);
+        },
+        connect(id) {
+            agentId = id;
+            /*
+             * Starting on Local is a switch nobody made, and the agent still has to
+             * exist. A workspace that opens there with something to create it from
+             * — a capacity plugin's blueprint, or the host's own payload — used to
+             * connect straight to an agent nobody had created: the header said
+             * "running", and the first message came back 404. So the agent is
+             * ensured first, the way a switch to Local ensures it, and connected
+             * once it is there. Only the agent, not the sandbox reconfiguration a
+             * switch also does: at start there is no previous target to move away
+             * from, and restarting an existing agent's sandbox on every open would
+             * cost a reader the kernel they had.
+             */
+            const createPayload = target.peek() === 'local' && id
+                ? (blueprint?.() ?? localAgent?.createPayload)
+                : undefined;
+            if (!createPayload) {
+                connectActive();
+                return () => {
+                    disconnect?.();
+                    disconnect = null;
+                };
+            }
+            let cancelled = false;
+            server.setState('starting');
+            void ensureLocalAgent(createPayload).then(() => {
+                if (!cancelled) {
+                    connectActive();
+                }
+            }, (error) => {
+                // No control to hand this back to at start: the sandbox says so
+                // instead, and the console has the reason.
+                if (!cancelled) {
+                    server.setState('error');
+                    console.error('[loop] Local agent could not be started:', error);
+                }
+            });
+            return () => {
+                cancelled = true;
+                disconnect?.();
+                disconnect = null;
+            };
+        },
+        async setTarget(next) {
+            const previous = target.peek();
+            if (next === previous) {
+                return;
+            }
+            // Disconnect first: two live sandboxes would race to report status, and
+            // the reader would watch the header flicker between them.
+            disconnect?.();
+            disconnect = null;
+            try {
+                await applyVariant(next);
+            }
+            catch (error) {
+                // Put the old one back rather than leaving the workspace with nothing:
+                // a failed switch should cost the person the switch, not the sandbox
+                // they already had.
+                connectActive();
+                throw error;
+            }
+            target.value = next;
+            // Connect the new backing, so choosing a target *starts* it rather than
+            // arming it for whenever something happens to ask.
+            connectActive();
+        },
+    };
+}

package/lib/loop/plugins/agents/team.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Which member of a team the person is talking to.
+ *
+ * A team is a group of agents with one front door. The teamspec says who that
+ * is — its `supervisor` — and lists the members it routes between, so the
+ * selection starts there and moves when a person picks somebody else.
+ *
+ * The selection is a signal rather than React state because two things read
+ * it: the header control that changes it, and the chat that has to send the
+ * next prompt to whoever is chosen. Those live in different plugins and must
+ * not own copies that can disagree.
+ *
+ * What switching member does to the conversation is not decided here. It comes
+ * from the teamspec's `context.sharing`, because it follows from what the team
+ * is: a supervisor team routing between a tutor and a compactor needs one
+ * thread both can read, and a delegation team needs the opposite.
+ *
+ * @module loop/plugins/agents/team
+ */
+import { type ReadonlySignal } from '@datalayer/reactor';
+import type { TeamContextSharing, TeamSpec } from '../../../types/teams';
+import type { BrowserSubagent } from '../../../runtimes/browser';
+/** One agent a person can address, as the picker shows it. */
+export type TeamMember = {
+    /** The member's id within the team. */
+    id: string;
+    /** What the picker calls it. */
+    name: string;
+    /** The agentspec it runs, without the version. */
+    specId: string;
+    /** One line about what it is for. */
+    description?: string;
+    emoji?: string;
+    /** The octicon name its agentspec asked for. */
+    icon?: string;
+    /** Whether this is the team's front door. */
+    isSupervisor: boolean;
+};
+export type TeamSelection = {
+    /** The team being worked with. */
+    team: TeamSpec;
+    /** Everyone a person may address, supervisor first. */
+    members: TeamMember[];
+    /** Who is being addressed now. */
+    selected: ReadonlySignal<string>;
+    /** Address somebody else. */
+    select: (memberId: string) => void;
+    /** What each member is told about the conversation so far. */
+    sharing: TeamContextSharing;
+    /** The member currently addressed, resolved. */
+    active: ReadonlySignal<TeamMember | undefined>;
+};
+/**
+ * The members of a team, supervisor first.
+ *
+ * The supervisor is listed among them rather than above them: in this team it
+ * is the tutor, which does work as well as routing, and a front door that
+ * cannot be addressed directly would be a strange front door. It is marked
+ * so the picker can say which it is.
+ */
+export declare function teamMembers(team: TeamSpec): TeamMember[];
+/**
+ * Track which member is being addressed.
+ *
+ * Starts on the supervisor, which is the team's own answer to "who reads this
+ * first". Falls back to the first member for a team with no supervisor ref.
+ */
+export declare function createTeamSelection(teamId: string): TeamSelection | undefined;
+/**
+ * The agents a given member may hand work to.
+ *
+ * Read from the teamspec rather than assumed, because a team says two separate
+ * things about delegation and they mean different things:
+ *
+ * - `delegation.allowPeerDelegation` — whether a member may reach *another
+ *   member*. The jupyter team says no: the Tutor handing work to the
+ *   Compactor would edit a notebook the learner is working in, which is the one
+ *   thing the Tutor exists not to do. Routing between them is the supervisor's
+ *   job, where a person can see it happen.
+ * - a member's own `subagents` — specialists that belong to it alone. The
+ *   Compactor has a CellFixer and a NotebookReproducer, and neither is a member
+ *   of the team.
+ *
+ * So the supervisor gets the other members, everyone gets their own subagents,
+ * and a peer only appears where the team allows it.
+ */
+export declare function subagentsFor(team: TeamSpec, memberId: string): BrowserSubagent[];

package/lib/loop/plugins/agents/team.js

@@ -0,0 +1,143 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Which member of a team the person is talking to.
+ *
+ * A team is a group of agents with one front door. The teamspec says who that
+ * is — its `supervisor` — and lists the members it routes between, so the
+ * selection starts there and moves when a person picks somebody else.
+ *
+ * The selection is a signal rather than React state because two things read
+ * it: the header control that changes it, and the chat that has to send the
+ * next prompt to whoever is chosen. Those live in different plugins and must
+ * not own copies that can disagree.
+ *
+ * What switching member does to the conversation is not decided here. It comes
+ * from the teamspec's `context.sharing`, because it follows from what the team
+ * is: a supervisor team routing between a tutor and a compactor needs one
+ * thread both can read, and a delegation team needs the opposite.
+ *
+ * @module loop/plugins/agents/team
+ */
+import { computed, signal, } from '@datalayer/reactor';
+import { TEAM_SPECS } from '../../../specs/teams/teams';
+import { AGENTSPECS } from '../../../specs/agents/agents';
+/** A `ref` such as `jupyter-tutor:0.0.1`, without its version. */
+function specIdOf(ref) {
+    return (ref ?? '').split(':')[0] ?? '';
+}
+/**
+ * The members of a team, supervisor first.
+ *
+ * The supervisor is listed among them rather than above them: in this team it
+ * is the tutor, which does work as well as routing, and a front door that
+ * cannot be addressed directly would be a strange front door. It is marked
+ * so the picker can say which it is.
+ */
+export function teamMembers(team) {
+    const supervisorSpecId = specIdOf(team.supervisor?.ref);
+    const describe = (specId) => {
+        const spec = AGENTSPECS[specId];
+        return {
+            description: spec?.description,
+            emoji: spec?.emoji,
+            icon: spec?.icon,
+        };
+    };
+    const members = (team.agents ?? []).map(agent => {
+        const specId = specIdOf(agent.ref);
+        return {
+            id: agent.id,
+            name: agent.name || specId || agent.id,
+            specId,
+            isSupervisor: specId !== '' && specId === supervisorSpecId,
+            ...describe(specId),
+        };
+    });
+    // The supervisor answers first because it is what a prompt reaches by
+    // default; a list that buried it would make the default look arbitrary.
+    return [
+        ...members.filter(member => member.isSupervisor),
+        ...members.filter(member => !member.isSupervisor),
+    ];
+}
+/**
+ * Track which member is being addressed.
+ *
+ * Starts on the supervisor, which is the team's own answer to "who reads this
+ * first". Falls back to the first member for a team with no supervisor ref.
+ */
+export function createTeamSelection(teamId) {
+    const team = TEAM_SPECS[teamId];
+    if (!team) {
+        return undefined;
+    }
+    const members = teamMembers(team);
+    if (members.length === 0) {
+        return undefined;
+    }
+    const selected = signal(members[0].id);
+    return {
+        team,
+        members,
+        selected,
+        select: (memberId) => {
+            if (members.some(member => member.id === memberId)) {
+                selected.value = memberId;
+            }
+        },
+        sharing: team.context?.sharing ?? 'shared',
+        active: computed(() => members.find(member => member.id === selected.value)),
+    };
+}
+/**
+ * The agents a given member may hand work to.
+ *
+ * Read from the teamspec rather than assumed, because a team says two separate
+ * things about delegation and they mean different things:
+ *
+ * - `delegation.allowPeerDelegation` — whether a member may reach *another
+ *   member*. The jupyter team says no: the Tutor handing work to the
+ *   Compactor would edit a notebook the learner is working in, which is the one
+ *   thing the Tutor exists not to do. Routing between them is the supervisor's
+ *   job, where a person can see it happen.
+ * - a member's own `subagents` — specialists that belong to it alone. The
+ *   Compactor has a CellFixer and a NotebookReproducer, and neither is a member
+ *   of the team.
+ *
+ * So the supervisor gets the other members, everyone gets their own subagents,
+ * and a peer only appears where the team allows it.
+ */
+export function subagentsFor(team, memberId) {
+    const members = teamMembers(team);
+    const member = members.find(entry => entry.id === memberId);
+    if (!member) {
+        return [];
+    }
+    const asSubagent = (name, specId, description) => {
+        const spec = AGENTSPECS[specId];
+        if (!spec) {
+            return undefined;
+        }
+        return {
+            name,
+            // The description is what the parent's model chooses on, so a team's own
+            // wording wins over the spec's: it says when to reach for this one *in
+            // this team*, which is the question being asked.
+            description: description || spec.description || name,
+            instructions: spec.systemPrompt,
+            model: spec.model,
+            icon: spec.icon,
+        };
+    };
+    const peers = member.isSupervisor || team.delegation?.allowPeerDelegation
+        ? members
+            .filter(entry => entry.id !== memberId)
+            .map(entry => asSubagent(entry.name, entry.specId, entry.description))
+        : [];
+    const declared = (team.agents ?? []).find((entry) => entry.id === memberId);
+    const own = (declared?.subagents ?? []).map(subagent => asSubagent(subagent.name, (subagent.ref ?? '').split(':')[0] ?? '', subagent.description));
+    return [...peers, ...own].filter(Boolean);
+}

package/lib/loop/plugins/agents/useSandboxService.d.ts

@@ -0,0 +1,11 @@
+import type { SwitchableSandboxService } from './switchable';
+/** The sandbox service, or `undefined` when the plugin is not mounted. */
+export declare function useOptionalSandboxService(): SwitchableSandboxService | undefined;
+/**
+ * The sandbox service, insisting it is there.
+ *
+ * A view that declares the sandbox plugin as a dependency has it by
+ * construction; if it does not, the reactor graph is wrong and saying so
+ * plainly beats rendering something half-alive.
+ */
+export declare function useSandboxService(): SwitchableSandboxService;

package/lib/loop/plugins/agents/useSandboxService.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Reaching the sandbox service from a component.
+ *
+ * A plugin that depends on the sandbox asks the reactor for it by name, rather
+ * than importing a singleton: that is what makes the dependency visible in the
+ * extension graph and what lets a host swap the implementation — a JupyterLab
+ * front-end backed by the running server instead of a cloud runtime.
+ *
+ * @module loop/plugins/agents/useSandboxService
+ */
+import { useReactorPlatform } from '@datalayer/reactor/react';
+import { AGENTS_PLUGIN_NAME } from './plugin';
+/** The sandbox service, or `undefined` when the plugin is not mounted. */
+export function useOptionalSandboxService() {
+    const reactor = useReactorPlatform();
+    return reactor.getOutput(AGENTS_PLUGIN_NAME)?.sandbox;
+}
+/**
+ * The sandbox service, insisting it is there.
+ *
+ * A view that declares the sandbox plugin as a dependency has it by
+ * construction; if it does not, the reactor graph is wrong and saying so
+ * plainly beats rendering something half-alive.
+ */
+export function useSandboxService() {
+    const service = useOptionalSandboxService();
+    if (!service) {
+        throw new Error(`The code sandbox plugin (${AGENTS_PLUGIN_NAME}) is not mounted. ` +
+            'A view that needs a sandbox must declare it as a dependency.');
+    }
+    return service;
+}