@datalayer/agent-runtimes 1.3.95 → 1.3.96

package/lib/apps/apps/sceneShape.js

@@ -0,0 +1,191 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { SCENE_SCHEMA } from '../../specs/sceneSchema';
+import { sectionOfKey } from './sceneChecks';
+const DEFS = (SCENE_SCHEMA.$defs ?? {});
+/**
+ * Field names pydantic also takes for an alias (`populate_by_name`): the
+ * schema names `schema` and `as`, the model `schema_` and `shown_as`.
+ */
+const FIELD_NAMES = {
+    schema_: 'schema',
+    shown_as: 'as',
+};
+const isMapping = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A value as Python prints it in a choice: `'browser'`. */
+const python = (value) => typeof value === 'string'
+    ? `'${value}'`
+    : value === null
+        ? 'None'
+        : typeof value === 'boolean'
+            ? value
+                ? 'True'
+                : 'False'
+            : String(value);
+/** pydantic's list of choices: `'a'`, `'a' or 'b'`, `'a', 'b' or 'c'`. */
+const choices = (values) => values.length <= 1
+    ? values.map(python).join('')
+    : `${values.slice(0, -1).map(python).join(', ')} or ${python(values[values.length - 1])}`;
+/** The definition a `$ref` names, and its name. */
+const resolved = (schema) => {
+    if (typeof schema.$ref === 'string') {
+        const model = schema.$ref.split('/').pop() ?? '';
+        return { schema: DEFS[model] ?? {}, model };
+    }
+    return { schema };
+};
+const said = (loc, message) => [
+    { loc, kind: 'said', message },
+];
+/** A number as pydantic reads one in lax mode, or why it does not. */
+function numberIssue(value, integer) {
+    if (typeof value === 'boolean') {
+        return undefined;
+    }
+    if (typeof value === 'number') {
+        return integer && !Number.isInteger(value)
+            ? 'Input should be a valid integer, got a number with a fractional part'
+            : undefined;
+    }
+    if (typeof value === 'string') {
+        const read = Number(value.trim());
+        if (value.trim() === '' || Number.isNaN(read)) {
+            return integer
+                ? 'Input should be a valid integer, unable to parse string as an integer'
+                : 'Input should be a valid number, unable to parse string as a number';
+        }
+        return integer && !Number.isInteger(read)
+            ? 'Input should be a valid integer, unable to parse string as an integer'
+            : undefined;
+    }
+    return integer
+        ? 'Input should be a valid integer'
+        : 'Input should be a valid number';
+}
+function issuesOf(given, value, loc) {
+    // `X | null`: nothing is fine, anything else is read as X.
+    if (Array.isArray(given.anyOf)) {
+        const branches = given.anyOf.filter(branch => branch.type !== 'null');
+        if (value === null && branches.length < given.anyOf.length) {
+            return [];
+        }
+        if (branches.length === 1) {
+            return issuesOf(branches[0], value, loc);
+        }
+    }
+    const { schema, model } = resolved(given);
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.includes(value)
+            ? []
+            : said(loc, `Input should be ${choices(schema.enum)}`);
+    }
+    switch (schema.type) {
+        case 'object':
+            return objectIssues(schema, model, value, loc);
+        case 'array': {
+            if (!Array.isArray(value)) {
+                return said(loc, 'Input should be a valid list');
+            }
+            const items = schema.items;
+            return items
+                ? value.flatMap((item, index) => issuesOf(items, item, [...loc, index]))
+                : [];
+        }
+        case 'string': {
+            if (typeof value !== 'string') {
+                return said(loc, 'Input should be a valid string');
+            }
+            const pattern = schema.pattern;
+            return typeof pattern === 'string' && !new RegExp(pattern).test(value)
+                ? said(loc, `String should match pattern '${pattern}'`)
+                : [];
+        }
+        case 'number':
+        case 'integer': {
+            const wrong = numberIssue(value, schema.type === 'integer');
+            if (wrong) {
+                return said(loc, wrong);
+            }
+            const read = Number(value);
+            if (typeof schema.minimum === 'number' && read < schema.minimum) {
+                return said(loc, `Input should be greater than or equal to ${schema.minimum}`);
+            }
+            if (typeof schema.maximum === 'number' && read > schema.maximum) {
+                return said(loc, `Input should be less than or equal to ${schema.maximum}`);
+            }
+            return [];
+        }
+        case 'boolean':
+            return typeof value === 'boolean'
+                ? []
+                : said(loc, 'Input should be a valid boolean');
+        default:
+            return [];
+    }
+}
+function objectIssues(schema, model, value, loc) {
+    if (!isMapping(value)) {
+        return said(loc, model
+            ? `Input should be a valid dictionary or instance of ${model}`
+            : 'Input should be a valid dictionary');
+    }
+    const properties = schema.properties;
+    if (!properties) {
+        // A mapping of one kind of thing: `positions`, each a place.
+        const each = schema.additionalProperties;
+        return typeof each === 'object' && each !== null
+            ? Object.entries(value).flatMap(([key, item]) => issuesOf(each, item, [...loc, key]))
+            : [];
+    }
+    const given = Object.fromEntries(Object.entries(value).map(([key, item]) => [FIELD_NAMES[key] ?? key, item]));
+    const required = Array.isArray(schema.required)
+        ? schema.required
+        : [];
+    // Each field in the model's order, then what the model has no field for.
+    const issues = Object.entries(properties).flatMap(([key, field]) => key in given
+        ? issuesOf(field, given[key], [...loc, key])
+        : required.includes(key)
+            ? [{ loc: [...loc, key], kind: 'missing' }]
+            : []);
+    if (schema.additionalProperties === false) {
+        for (const key of Object.keys(given)) {
+            if (!(key in properties)) {
+                issues.push({ loc: [...loc, key], kind: 'extra' });
+            }
+        }
+    }
+    return issues;
+}
+/** One issue as agentspecs says it (`_sentences`). */
+const sentence = (issue) => {
+    const where = issue.loc.join('.');
+    if (issue.kind === 'missing') {
+        return `${where} is missing`;
+    }
+    if (issue.kind === 'extra') {
+        return `${where} is not a field of the spec`;
+    }
+    return where ? `${where}: ${issue.message}` : (issue.message ?? '');
+};
+/**
+ * What `loop` says of a scene's shape — every issue, after the scene's id —
+ * filed under the part of the scene its first issue is about; nothing when
+ * the shape is right. `data` is the text read as plain data, in agentspecs'
+ * spelling.
+ */
+export function sceneShapeSays(data) {
+    const issues = issuesOf(SCENE_SCHEMA, data, []);
+    if (!issues.length) {
+        return undefined;
+    }
+    const id = isMapping(data) && 'id' in data
+        ? python(data.id).replace(/^'|'$/g, '')
+        : 'the scene';
+    const first = String(issues[0].loc[0] ?? '');
+    return {
+        says: `${id}: ${issues.map(sentence).join('; ')}`,
+        section: sectionOfKey(first),
+    };
+}

package/lib/apps/apps/sceneYaml.d.ts

@@ -0,0 +1,64 @@
+import type { SceneSpec } from '../../types/scenes';
+import { type SceneOwnApps, type SceneProblem, type SceneSection } from './sceneChecks';
+export type { SceneSpec };
+/** What a scene spec says of itself. */
+export declare const SCENE_SCHEMA = "loop.scene/v1";
+/** A spec with nothing said yet: signed-in people may watch, the transcript shows everything. */
+export declare const emptySceneSpec: () => SceneSpec;
+/**
+ * What is written: the spec without what says nothing — an empty string, an
+ * empty list, an empty map — as `generate_apps.py` drops them, so the text
+ * beside the stage reads as a person would write it.
+ */
+export declare function compactScene(value: unknown): unknown;
+/**
+ * The keys agentspecs spells with an underscore, as the TypeScript spec
+ * spells them (`generate_scenes.py`'s `CAMEL`): the text beside the stage
+ * is written as agentspecs reads it, so that a scene's YAML pastes in and
+ * the schema's completion names what is there.
+ */
+export declare const TEXT_KEYS: Readonly<Record<string, string>>;
+/**
+ * What a scene spec carries that is not written by hand: what it names that
+ * is not enabled today (`setup`, computed by agentspecs' `scene_setup`) and
+ * the last rehearsal played (`played`, what *Live* is read from). agentspecs
+ * refuses both in a scene file — they are read off a scene, never into one —
+ * so the text does not write them, and an edit of the text does not erase
+ * them (`sceneWithDerived`).
+ */
+export declare const SCENE_DERIVED_KEYS: readonly ["setup", "played"];
+/** The spec with what is not written by hand carried over from another: the one the text was read from. */
+export declare const sceneWithDerived: (spec: SceneSpec, from: SceneSpec) => SceneSpec;
+/**
+ * The scene as YAML, spelled as agentspecs spells it: the text under the
+ * stage (S-01, S-08), edited there as on the stage (`sceneOfYaml`). What is
+ * not written by hand is left out, so the text reads as a scene file
+ * (`SCENE_DERIVED_KEYS`).
+ */
+export declare function sceneYamlOf(spec: SceneSpec): string;
+/**
+ * The scene the text says, in the words the problem is said with when it
+ * says none: not YAML, not a mapping, not `loop.scene/v1`. A spec that is
+ * one is laid over the empty spec, as one read from its item is.
+ */
+export declare function sceneOfYaml(text: string): {
+    spec?: SceneSpec;
+    problem?: string;
+    /** The part of the scene the problem is about, when it is about one. */
+    section?: SceneSection;
+};
+/**
+ * A spec said in part, laid over the empty one: a part left unsaid — of the
+ * scene, of a cast member, of a system of the setting, of the rehearsal —
+ * reads as empty rather than as `undefined`, so that what was written
+ * compact (`compactScene`) reads back whole.
+ */
+export declare function sceneOfData(spec: Partial<SceneSpec>): SceneSpec;
+/**
+ * What the text says of itself (S-08): what stands in the way, each in
+ * agentspecs' sentence with the part of the scene it is about — a text that
+ * is no scene first of all, since nothing else can be read of it.
+ */
+export declare function sceneTextProblems(text: string, own?: SceneOwnApps): SceneProblem[];
+/** The member the audience talks to, as the text says it (`entryOf`); empty while it does not read. */
+export declare function sceneTextEntry(text: string): string;

package/lib/apps/apps/sceneYaml.js

@@ -0,0 +1,253 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A scene's spec, `loop.scene/v1`, as text: how it is read and how it is
+ * written — what `appspec.ts` is for an application.
+ *
+ * agentspecs writes a scene in its own spelling (`talks_to`, `runs_in`) and
+ * agent-runtimes' `SceneSpec` in its own (`talksTo`, `runsIn`); a text in
+ * either reads (`sceneOfYaml`) and is written back in agentspecs' spelling
+ * (`sceneYamlOf`), so that what an editor saves is what `loop` reads. What is
+ * read *off* a scene rather than written into one — its `setup`, its recorded
+ * `played` — is never written into the text and never erased by an edit of it
+ * (`SCENE_DERIVED_KEYS`, `sceneWithDerived`). A text's own refusals are the
+ * scene's checks over what it reads (`sceneTextProblems`).
+ *
+ * Moved from the landing's Studio on 2026-10-10 with `sceneChecks.ts`
+ * (plans/STUDIO.md S-10), so that every shell editing a scene reads and writes
+ * it alike. Pure: no React, no network.
+ *
+ * @module apps/apps/sceneYaml
+ */
+import { parse, stringify } from 'yaml';
+import { entryOf, sceneCheck, } from './sceneChecks';
+import { sceneShapeSays } from './sceneShape';
+/** What a scene spec says of itself. */
+export const SCENE_SCHEMA = 'loop.scene/v1';
+/** A spec with nothing said yet: signed-in people may watch, the transcript shows everything. */
+export const emptySceneSpec = () => ({
+    schema: SCENE_SCHEMA,
+    id: '',
+    version: '0.0.1',
+    name: '',
+    description: '',
+    tags: [],
+    icon: '',
+    emoji: '',
+    team: '',
+    entry: '',
+    cast: [],
+    setting: { systems: [], period: '', language: 'en', assumes: '' },
+    script: [],
+    stage: {
+        positions: {},
+        opensFirst: '',
+        transcript: { tools: true, narration: true },
+        inspectors: [],
+        restsAfter: '',
+        pace: 'steady',
+    },
+    audience: { who: 'signed-in', ceilingPerAsk: 0, asksADay: 0 },
+    rehearsal: {
+        beats: [],
+        within: '',
+        verified: { live: [], recorded: [], unverified: [] },
+    },
+    deployment: { account: '', page: '', addresses: {} },
+    setup: [],
+});
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+/**
+ * What is written: the spec without what says nothing — an empty string, an
+ * empty list, an empty map — as `generate_apps.py` drops them, so the text
+ * beside the stage reads as a person would write it.
+ */
+export function compactScene(value) {
+    if (Array.isArray(value)) {
+        return value.map(compactScene);
+    }
+    if (isRecord(value)) {
+        const kept = {};
+        for (const [key, item] of Object.entries(value)) {
+            if (item === '' || item === undefined || item === null) {
+                continue;
+            }
+            if (Array.isArray(item) && item.length === 0) {
+                continue;
+            }
+            if (isRecord(item) && Object.keys(item).length === 0) {
+                continue;
+            }
+            kept[key] = compactScene(item);
+        }
+        return kept;
+    }
+    return value;
+}
+/**
+ * The keys agentspecs spells with an underscore, as the TypeScript spec
+ * spells them (`generate_scenes.py`'s `CAMEL`): the text beside the stage
+ * is written as agentspecs reads it, so that a scene's YAML pastes in and
+ * the schema's completion names what is there.
+ */
+export const TEXT_KEYS = {
+    runs_in: 'runsIn',
+    talks_to: 'talksTo',
+    opens_first: 'opensFirst',
+    rests_after: 'restsAfter',
+    ceiling_per_ask: 'ceilingPerAsk',
+    asks_a_day: 'asksADay',
+    must_say: 'mustSay',
+    must_not_say: 'mustNotSay',
+};
+const SPEC_KEYS = Object.fromEntries(Object.entries(TEXT_KEYS).map(([text, spec]) => [spec, text]));
+/** Every key renamed by a map, deep; a key the map does not name — a member's id among them — is left as it is. */
+function respelled(value, keys) {
+    if (Array.isArray(value)) {
+        return value.map(item => respelled(item, keys));
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            keys[key] ?? key,
+            respelled(item, keys),
+        ]));
+    }
+    return value;
+}
+/**
+ * What a scene spec carries that is not written by hand: what it names that
+ * is not enabled today (`setup`, computed by agentspecs' `scene_setup`) and
+ * the last rehearsal played (`played`, what *Live* is read from). agentspecs
+ * refuses both in a scene file — they are read off a scene, never into one —
+ * so the text does not write them, and an edit of the text does not erase
+ * them (`sceneWithDerived`).
+ */
+export const SCENE_DERIVED_KEYS = ['setup', 'played'];
+/** The spec with what is not written by hand carried over from another: the one the text was read from. */
+export const sceneWithDerived = (spec, from) => ({
+    ...spec,
+    setup: from.setup ?? [],
+    ...(from.played ? { played: from.played } : {}),
+});
+/**
+ * The scene as YAML, spelled as agentspecs spells it: the text under the
+ * stage (S-01, S-08), edited there as on the stage (`sceneOfYaml`). What is
+ * not written by hand is left out, so the text reads as a scene file
+ * (`SCENE_DERIVED_KEYS`).
+ */
+export function sceneYamlOf(spec) {
+    const written = Object.fromEntries(Object.entries(spec).filter(([key]) => !SCENE_DERIVED_KEYS.includes(key)));
+    return stringify(respelled(compactScene(written), SPEC_KEYS), {
+        lineWidth: 0,
+    });
+}
+/**
+ * The scene the text says, in the words the problem is said with when it
+ * says none: not YAML, not a mapping, not `loop.scene/v1`. A spec that is
+ * one is laid over the empty spec, as one read from its item is.
+ */
+export function sceneOfYaml(text) {
+    let parsed;
+    try {
+        parsed = parse(text);
+    }
+    catch (error) {
+        const why = error instanceof Error ? error.message.split('\n')[0] : String(error);
+        return { problem: `The text does not read: ${why}` };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            problem: 'The text is not a scene: it starts with its name and its cast.',
+        };
+    }
+    if (parsed.schema !== SCENE_SCHEMA) {
+        return {
+            problem: `The text is not a scene: it says schema ${JSON.stringify(parsed.schema ?? '')}, and a scene says ${SCENE_SCHEMA}.`,
+        };
+    }
+    // A scene of the wrong shape is refused as `loop` refuses it, before it is
+    // read into a spec: read into one, a cast written as one word made the
+    // reader throw (`sceneShape`, 2026-10-10). Checked as agentspecs spells it.
+    const shape = sceneShapeSays(respelled(parsed, SPEC_KEYS));
+    if (shape) {
+        return { problem: shape.says, section: shape.section };
+    }
+    // Spelled as agentspecs spells it, or as the spec does: both read.
+    return {
+        spec: sceneOfData(respelled(parsed, TEXT_KEYS)),
+    };
+}
+/** A cast member with nothing said: what `compactScene` dropped reads as empty again. */
+const EMPTY_MEMBER = {
+    app: '',
+    ref: '',
+    server: '',
+    brief: '',
+    persona: { name: '', face: '', line: '' },
+};
+/**
+ * A spec said in part, laid over the empty one: a part left unsaid — of the
+ * scene, of a cast member, of a system of the setting, of the rehearsal —
+ * reads as empty rather than as `undefined`, so that what was written
+ * compact (`compactScene`) reads back whole.
+ */
+export function sceneOfData(spec) {
+    const empty = emptySceneSpec();
+    const setting = spec.setting ?? {};
+    const rehearsal = spec.rehearsal ?? {};
+    return {
+        ...empty,
+        ...spec,
+        schema: SCENE_SCHEMA,
+        cast: (spec.cast ?? []).map(member => ({
+            ...EMPTY_MEMBER,
+            ...member,
+            persona: { ...EMPTY_MEMBER.persona, ...(member.persona ?? {}) },
+        })),
+        setting: {
+            ...empty.setting,
+            ...setting,
+            systems: (setting.systems ?? []).map(system => ({
+                ...system,
+                as: system.as ?? '',
+                holds: system.holds ?? '',
+            })),
+        },
+        script: spec.script ?? [],
+        stage: {
+            ...empty.stage,
+            ...(spec.stage ?? {}),
+            transcript: {
+                ...empty.stage.transcript,
+                ...(spec.stage?.transcript ?? {}),
+            },
+        },
+        audience: { ...empty.audience, ...(spec.audience ?? {}) },
+        rehearsal: {
+            ...empty.rehearsal,
+            ...rehearsal,
+            verified: { ...empty.rehearsal.verified, ...(rehearsal.verified ?? {}) },
+        },
+        deployment: { ...empty.deployment, ...(spec.deployment ?? {}) },
+        setup: spec.setup ?? [],
+    };
+}
+/**
+ * What the text says of itself (S-08): what stands in the way, each in
+ * agentspecs' sentence with the part of the scene it is about — a text that
+ * is no scene first of all, since nothing else can be read of it.
+ */
+export function sceneTextProblems(text, own) {
+    const read = sceneOfYaml(text);
+    if (!read.spec) {
+        return [{ says: read.problem ?? '', section: read.section ?? 'scene' }];
+    }
+    return sceneCheck(read.spec, own, { written: true });
+}
+/** The member the audience talks to, as the text says it (`entryOf`); empty while it does not read. */
+export function sceneTextEntry(text) {
+    const read = sceneOfYaml(text);
+    return read.spec ? entryOf(read.spec) : '';
+}

package/lib/apps/core/canvasParts.d.ts

@@ -0,0 +1,28 @@
+/** The kinds of part an agent is built from on the Canvas. */
+export type CanvasPartKind = 'connection' | 'rule' | 'skill' | 'test' | 'event' | 'model';
+/**
+ * A part of an agent the Canvas may place (LOOP C-20): a connection to a
+ * server of the catalogue, a skill, a model, a rule, a test, an event —
+ * contributed by the plugin of what it comes from. The toolbox is what the
+ * enabled plugins contribute here, and nothing else: a plugin disabled takes
+ * its parts off it, as it takes its blocks off the palette.
+ */
+export type CanvasPartContribution = {
+    /** Unique among the parts: its kind and what it is, `connection:tavily`. */
+    id: string;
+    kind: CanvasPartKind;
+    /** What the toolbox calls it. */
+    label: string;
+    /** One line of what it is. */
+    says: string;
+    emoji?: string;
+    /**
+     * What it arrives with, spelled as the Appspec's text spells it: a
+     * connection's, a rule's, a test's or an event's object, a skill's or a
+     * model's id. Every example is one the Appspec's schema takes as it is.
+     */
+    example: unknown;
+    /** Whether what it names is enabled today; a part that is not is offered, and its application's setup notes say so. */
+    enabled: boolean;
+};
+export declare const LoopCanvasPart: import("@datalayer/reactor").ContributionPoint<CanvasPartContribution>;

package/lib/apps/core/canvasParts.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The agent's toolbox as a contribution point (LOOP C-20), beside the
+ * Canvas's palette of blocks (`canvasBlocks`, C-12): kept apart so that
+ * reading the toolbox loads the reactor and the catalogue, and nothing of the
+ * workspace.
+ *
+ * @module apps/core/canvasParts
+ */
+import { defineContributionPoint } from '@datalayer/reactor';
+export const LoopCanvasPart = defineContributionPoint('loop.canvas.part');

package/lib/apps/core/index.d.ts

@@ -598,6 +598,7 @@ export type AssistantMenuContribution = {
 };
 export declare const LoopAssistantMenu: import("@datalayer/reactor").ContributionPoint<AssistantMenuContribution>;
 export { LoopCanvasBlock, type CanvasBlockContribution } from './canvasBlocks';
+export { LoopCanvasPart, type CanvasPartContribution, type CanvasPartKind, } from './canvasParts';
 export { LoopA2uiComponent, type A2uiComponentContribution, } from './a2uiComponents';
 /**
  * The per-example chat extras a host feeds the loop's conversation live.

package/lib/apps/core/index.js

@@ -173,6 +173,8 @@ export const LoopAssistantMenu = defineContributionPoint('loop.assistant.menu');
 // A block the Canvas may place (LOOP C-12), in a module of its own so that
 // the palette is read without the rest of the contracts.
 export { LoopCanvasBlock } from './canvasBlocks';
+// A part of an agent the Canvas may place (LOOP C-20), beside the blocks.
+export { LoopCanvasPart, } from './canvasParts';
 // A component an application adds to the catalog it is drawn with (LOOP
 // P-17): the components its developer wrote, for its workspace alone.
 export { LoopA2uiComponent, } from './a2uiComponents';

package/lib/apps/embed/loader.js

@@ -28,6 +28,16 @@
         console.error('datalayer-app: the script has to be loaded by a script tag with a src, so it knows where its module is.');
         return;
     }
+    // `@jupyter-widgets` assigns to a bare `__webpack_public_path__` at the top
+    // of the module (see `loop-main.tsx`): in an ES module that is a
+    // ReferenceError unless the global exists, and the module's own body runs
+    // after everything it imports, so it is declared here, before the import —
+    // without it no application loads (`… did not load (__webpack_public_path__
+    // is not defined)`, seen with `loop apps run --web`, LOOP P-08).
+    const globals = window;
+    if (globals['__webpack_public_path__'] === undefined) {
+        globals['__webpack_public_path__'] = '';
+    }
     const main = new URL(MODULE_FILE, script.src).href;
     import(/* @vite-ignore */ main).catch((error) => {
         const reason = error instanceof Error ? error.message : String(error);

package/lib/apps/plugins/agents/SandboxSelector.js

@@ -6,7 +6,7 @@ import { KernelIndicator } from '@datalayer/jupyter-react/kernel-indicator';
 import { useSignalValue } from '@datalayer/reactor/react';
 import { IDLE_SANDBOX_SNAPSHOT_SIGNAL, sandboxIndicatorState, } from '../../core';
 import { useOptionalSandboxService } from './useSandboxService';
-import { SANDBOX_TARGETS, TARGET_SPECS, } from './switchable';
+import { SANDBOX_TARGETS, TARGET_SPECS, heldTargetReason, } from './switchable';
 export function SandboxSelector(_props) {
     const service = useOptionalSandboxService();
     const [moving, setMoving] = useState(false);
@@ -58,7 +58,18 @@ export function SandboxSelector(_props) {
                     p: 0,
                     '& > li': { listStyle: 'none' },
                     '& > li::marker': { content: 'none' },
-                }, children: SANDBOX_TARGETS.map((entry, position) => (_jsx(SegmentedControl.Button, { selected: position === index, sx: { listStyle: 'none' }, title: TARGET_SPECS[entry].hint, onClick: () => void choose(entry), children: TARGET_SPECS[entry].label }, entry))) }), failure || snapshot.errorReason ? (
+                }, children: SANDBOX_TARGETS.map((entry, position) => {
+                    // Held here: drawn, said why on hover, not taken. `aria-disabled`
+                    // rather than `disabled`: a disabled button takes no pointer, and
+                    // its reason would never be read.
+                    const held = heldTargetReason(entry);
+                    return (_jsx(SegmentedControl.Button, { selected: position === index, "aria-disabled": held ? true : undefined, "data-sandbox-target": entry, "data-sandbox-target-held": held ? '' : undefined, sx: {
+                            listStyle: 'none',
+                            ...(held
+                                ? { color: 'fg.subtle', cursor: 'not-allowed' }
+                                : null),
+                        }, title: held ?? TARGET_SPECS[entry].hint, onClick: () => (held ? undefined : void choose(entry)), children: TARGET_SPECS[entry].label }, entry));
+                }) }), failure || snapshot.errorReason ? (
             // The reason, in the header, in full. It used to read "switch failed"
             // with the cause hidden in a `title` — which is why a switch that
             // could not reach the server looked like a click that did nothing.

package/lib/apps/plugins/agents/host.d.ts

@@ -0,0 +1,2 @@
+/** Whether the page is JupyterLab's own. */
+export declare const insideJupyterLab: () => boolean;

package/lib/apps/plugins/agents/host.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What the page the agent is drawn in can offer, asked in one place.
+ *
+ * A local agent and the Jupyter server it starts run beside JupyterLab, not
+ * in a web page (`heldTargetReason`). The question is jupyter-react's; it is
+ * asked here so that a test can answer it without loading jupyter-react.
+ *
+ * @module apps/plugins/agents/host
+ */
+import { loadJupyterConfig } from '@datalayer/jupyter-react';
+/** Whether the page is JupyterLab's own. */
+export const insideJupyterLab = () => loadJupyterConfig().insideJupyterLab;

package/lib/apps/plugins/agents/plugin.js

@@ -12,8 +12,10 @@ import { AnonymousKeyBadge, AnonymousKeyHeaderBadge, } from './AnonymousKeyBadge
 import { SandboxSelector } from './SandboxSelector';
 import { TeamMemberPicker } from './TeamMemberPicker';
 import { createTeamSelection } from './team';
-import { createSwitchableSandboxService, TARGET_SPECS, targetHasAgent, } from './switchable';
+import { createSwitchableSandboxService, heldTargetReason, TARGET_SPECS, targetHasAgent, } from './switchable';
 export const AGENTS_PLUGIN_NAME = '@datalayer/loop-plugin-agents';
+/** The target asked for, or the page itself when this page holds it. */
+const offeredTarget = (target) => heldTargetReason(target) ? 'browser' : target;
 export const AgentsPlugin = definePlugin({
     name: AGENTS_PLUGIN_NAME,
     displayName: 'Agents',
@@ -43,7 +45,13 @@ export const AgentsPlugin = definePlugin({
                 // must not be started on a target the reader cannot move off — unless
                 // the host fixed the target itself, as an application deployed on
                 // Datalayer is (AppRenderer): there is nothing for the reader to move.
-                initialTarget: showVariants || config.targetFixed ? config.target : 'browser',
+                //
+                // And never on a target this page holds: *Local*, the default, is
+                // held on the web (`heldTargetReason`), so a page starts in itself.
+                // A host that names no target gets the service's own default, Local —
+                // read here, so that it is held on the web like any other.
+                initialTarget: offeredTarget((showVariants || config.targetFixed ? config.target : 'browser') ??
+                    'local'),
                 kernelSource: config.kernelSource,
                 localAgent: config.localAgent,
                 // The capacity plugins' say, read at switch time — lazily, because a