@datalayer/agent-runtimes 1.5.28 → 1.5.31

package/lib/apps/apps/appspec.d.ts

@@ -99,11 +99,6 @@ export declare const PAP_PROFILE: PapProfile;
  * (`pap_profile_problem`); `undefined` when it is one Datalayer speaks.
  */
 export declare function papProfileProblem(value: unknown): string | undefined;
-/**
- * Why `interface.voice.input: hands_free` is refused until VOICE.md VO-12 is
- * built (decided 14 October 2026): never taken for click-to-talk.
- */
-export declare const HANDS_FREE_NOT_BUILT = "hands_free is not built yet (VOICE.md VO-12): say push_to_talk \u2014 click the microphone or hold it, speak, and it stops when let go or once the person stops speaking";
 /** An application's voice (VOICE.md VO-41): off unless said. */
 export declare const DEFAULT_VOICE: AppVoiceSpec;
 /** What a page's output may be drawn with (LOOP P-05), and the property of each that shows its value. */

package/lib/apps/apps/appspec.js

@@ -713,11 +713,6 @@ function parseSurface(data) {
         composedAt: text(data.composed_at),
     };
 }
-/**
- * Why `interface.voice.input: hands_free` is refused until VOICE.md VO-12 is
- * built (decided 14 October 2026): never taken for click-to-talk.
- */
-export const HANDS_FREE_NOT_BUILT = 'hands_free is not built yet (VOICE.md VO-12): say push_to_talk — click the microphone or hold it, speak, and it stops when let go or once the person stops speaking';
 /** An application's voice (VOICE.md VO-41): off unless said. */
 export const DEFAULT_VOICE = {
     enabled: false,
@@ -731,7 +726,7 @@ function parseVoice(data) {
     const voice = isData(data) ? data : {};
     return {
         enabled: voice.enabled === true,
-        input: oneOf(voice.input, ['off', 'push_to_talk'], DEFAULT_VOICE.input),
+        input: oneOf(voice.input, ['off', 'push_to_talk', 'hands_free'], DEFAULT_VOICE.input),
         output: oneOf(voice.output, ['off', 'on_request', 'always'], DEFAULT_VOICE.output),
         voice: text(voice.voice),
         language: text(voice.language),

package/lib/apps/apps/checks.js

@@ -38,8 +38,9 @@ import { getSkillSpec } from '../../specs/skills';
 import { getTeamSpec } from '../../specs/teams';
 import { getBackendToolSpec } from '../../specs/backendTools';
 import { getTrack } from '../../specs/tracks';
+import { unservedHarnessProblem } from '../../runtimes/variants';
 import { pluginsOffSetupNotes } from '../plugins/canvas-blocks';
-import { APP_THEME_MODES, APP_THEME_VARIANTS, HANDS_FREE_NOT_BUILT, isAssistantCharacterId, PAGE_OUTPUT_SHOWS, parseAppspec, } from './appspec';
+import { APP_THEME_MODES, APP_THEME_VARIANTS, isAssistantCharacterId, PAGE_OUTPUT_SHOWS, parseAppspec, } from './appspec';
 import { classesOf, splitRef, toolBehaviours } from './rules';
 import { COMMAND_INPUT, COMMAND_NAME, MODE_ID } from './composer';
 import { HOST_NAME, HOST_USERS, hostToolsOf } from './hostTools';
@@ -397,6 +398,14 @@ function referenceProblems(app, organizationFrames) {
     if (app.agent && !getAgentspecs(idOf(app.agent)) && !getCog(app.agent)) {
         missing('agent or Cog', app.agent);
     }
+    // An agent on a catalogue harness is served by the runtime's ACP adapter
+    // (SHIELD SH-10); `custom` and a harness that is none are refused, not run
+    // on pydantic-ai in their place (SH-01).
+    const agent = app.agent ? getAgentspecs(idOf(app.agent)) : undefined;
+    const unserved = agent ? unservedHarnessProblem(agent) : undefined;
+    if (unserved) {
+        problems.push(unserved);
+    }
     if (app.team && !getTeamSpec(idOf(app.team))) {
         missing('team', app.team);
     }
@@ -685,7 +694,7 @@ const ENUMS = {
     visibility: ['private', 'invited', 'organization', 'link', 'public'],
     mode: ['inline', 'bubble', 'panel', 'assistant'],
     balloon: ['history', 'current'],
-    voiceInput: ['off', 'push_to_talk'],
+    voiceInput: ['off', 'push_to_talk', 'hands_free'],
     voiceOutput: ['off', 'on_request', 'always'],
     voiceWhere: ['auto', 'device', 'server'],
     themeVariant: APP_THEME_VARIANTS,
@@ -843,14 +852,9 @@ export function documentShapeProblems(document) {
         if (ui.assistant !== undefined && !isAssistantCharacterId(ui.assistant)) {
             at('interface.assistant', 'names a character by the id a plugin contributes it under, lowercase words joined by a hyphen: `paperclip`, `acme-owl`');
         }
-        // Its voice (VOICE.md VO-41); hands-free refused until it is built (VO-12).
+        // Its voice (VOICE.md VO-41, VO-12).
         mapping(ui.voice, 'interface.voice', voice => {
-            if (voice.input === 'hands_free') {
-                at('interface.voice.input', HANDS_FREE_NOT_BUILT);
-            }
-            else {
-                oneOf(voice.input, ENUMS.voiceInput, 'interface.voice.input');
-            }
+            oneOf(voice.input, ENUMS.voiceInput, 'interface.voice.input');
             oneOf(voice.output, ENUMS.voiceOutput, 'interface.voice.output');
             oneOf(voice.where, ENUMS.voiceWhere, 'interface.voice.where');
         });

package/lib/apps/embed/element.js

@@ -383,7 +383,7 @@ export function defineDatalayerAppElement(options = {}) {
                 // A public application, as a visitor without an account (D-07):
                 // an example kept warm or an address open to visitors, run on the
                 // visitors' runtime; a decision framed; a refusal said.
-                const visitor = await readVisitorApp({ api: this.api(), app });
+                const visitor = await readVisitorApp({ api: this.agents(), app });
                 if (visitor.kind === 'decision') {
                     return { kind: 'frame', src: frameSrcOf(this.origin(), visitor.app) };
                 }
@@ -408,11 +408,22 @@ export function defineDatalayerAppElement(options = {}) {
             }
             return this.spoken;
         }
-        /** Datalayer's services: the `api` attribute, else the platform's, else prod1's. */
+        /**
+         * ai-agents, where a visitor's address is read and beside which the
+         * visitors' runtime and ai-inference answer: the `api` attribute, else
+         * the platform's, else r1's. Not Spacer's address (`api()`), which lives
+         * on another plane.
+         */
+        agents() {
+            return (this.getAttribute('api') ||
+                coreStore.getState().configuration?.aiAgentsUrl ||
+                DEFAULT_API).replace(/\/+$/, '');
+        }
+        /** Spacer, where an application is read with its embed token: the `api` attribute, else the platform's, else prod1's. */
         api() {
             return (this.getAttribute('api') ||
                 coreStore.getState().configuration?.spacerUrl ||
-                DEFAULT_API).replace(/\/+$/, '');
+                'https://prod1.datalayer.run').replace(/\/+$/, '');
         }
         async load() {
             const turn = ++this.loading;

package/lib/apps/embed/embedConfig.d.ts

@@ -32,7 +32,7 @@ export declare const EMBED_ATTRIBUTES: {
     readonly theme: "light, dark or auto (the visitor’s system); auto by default.";
     readonly font: "A CSS font family for the application’s text; Inter, then the system’s sans-serif, by default.";
     readonly server: "An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.";
-    readonly api: "Datalayer’s API, where an application is read with its token; the platform’s by default.";
+    readonly api: "Datalayer’s API: where an application is read with its token (Spacer), and where a visitor’s address is read (ai-agents); the platform’s by default.";
     readonly height: "The height of an inline application, in pixels; 640 by default.";
     readonly resume: "true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.";
     readonly language: "The language the visitor reads the application in, as BCP 47 tags it (fr, pt-BR): its translation into it, and the chat’s own words; the visitor’s browser’s by default.";

package/lib/apps/embed/embedConfig.js

@@ -23,7 +23,7 @@ export const EMBED_ATTRIBUTES = {
     theme: 'light, dark or auto (the visitor’s system); auto by default.',
     font: 'A CSS font family for the application’s text; Inter, then the system’s sans-serif, by default.',
     server: 'An agent-runtimes server the application’s agent runs on; a Datalayer runtime by default.',
-    api: 'Datalayer’s API, where an application is read with its token; the platform’s by default.',
+    api: 'Datalayer’s API: where an application is read with its token (Spacer), and where a visitor’s address is read (ai-agents); the platform’s by default.',
     height: 'The height of an inline application, in pixels; 640 by default.',
     resume: 'true or false: whether a visit’s conversation is picked up again after the page reloads, kept in the page’s storage; true by default.',
     language: 'The language the visitor reads the application in, as BCP 47 tags it (fr, pt-BR): its translation into it, and the chat’s own words; the visitor’s browser’s by default.',

package/lib/apps/embed/visitorApp.d.ts

@@ -42,8 +42,15 @@ export declare const VISITORS_PATH = "/api/runtime-visitors";
 export declare const VISITOR_EXAMPLES: readonly string[];
 /** The key of an application at its address, as a visitor's token names it. */
 export declare const AT_PREFIX = "at:";
-/** Datalayer's services, where the element names none (`api`). */
-export declare const DEFAULT_API = "https://prod1.datalayer.run";
+/**
+ * Datalayer's services for a visitor, where the element names none (`api`)
+ * and the platform's configuration says none: ai-agents, where an address is
+ * read, and beside it the visitors' runtime and ai-inference, which mints the
+ * visitor's token. Not Spacer's address, which reads an application with its
+ * embed token: the two live on different planes (ai-agents on r1, Spacer on
+ * prod1), found 15 October 2026 on datalayer.ai's embed.
+ */
+export declare const DEFAULT_API = "https://r1.datalayer.run";
 /** An application's id on Datalayer: a ULID. */
 export declare const isAppUid: (value: string) => boolean;
 /** What `app` with no token resolves to. */

package/lib/apps/embed/visitorApp.js

@@ -14,8 +14,15 @@ export const VISITOR_EXAMPLES = [
 ];
 /** The key of an application at its address, as a visitor's token names it. */
 export const AT_PREFIX = 'at:';
-/** Datalayer's services, where the element names none (`api`). */
-export const DEFAULT_API = 'https://prod1.datalayer.run';
+/**
+ * Datalayer's services for a visitor, where the element names none (`api`)
+ * and the platform's configuration says none: ai-agents, where an address is
+ * read, and beside it the visitors' runtime and ai-inference, which mints the
+ * visitor's token. Not Spacer's address, which reads an application with its
+ * embed token: the two live on different planes (ai-agents on r1, Spacer on
+ * prod1), found 15 October 2026 on datalayer.ai's embed.
+ */
+export const DEFAULT_API = 'https://r1.datalayer.run';
 /** An application's id on Datalayer: a ULID. */
 export const isAppUid = (value) => /^[0-9A-HJKMNP-TV-Z]{26}$/.test(value);
 /** An address, as ai-agents spells one. */

package/lib/apps/plugins/chat/ChatView.js

@@ -1700,7 +1700,10 @@ export default function ChatView({ workspace }) {
         footerExtras: promptActions.length > 0 || (voice && voice.input !== 'off') ? (_jsxs(_Fragment, { children: [promptActions.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.promptAction, props: { workspace } })) : null, voice && voice.input !== 'off' ? (_jsx(ComposerVoice, { voice: voice, input: draft, setInput: setDraft, disabled: chatDisabled, 
                     // The chat's own speaker, never a second one: the microphone
                     // opening stops it, and *Stop speaking* while it speaks.
-                    speaking: speaking, onStopSpeaking: () => controlsRef.current?.stopSpeaking?.(), onInterimChange: setVoiceInterim, 
+                    speaking: speaking, onStopSpeaking: () => controlsRef.current?.stopSpeaking?.(), 
+                    // Hands-free (VO-12, VO-13): the run in progress, stopped when
+                    // the person speaks over it.
+                    running: busy, onStopRun: () => controlsRef.current?.stop?.(), onInterimChange: setVoiceInterim, 
                     // The menu offers when answers are heard where the
                     // application lets them be (VO-21, VO-30).
                     answers: Boolean(config?.voice?.output &&

package/lib/chat/base/ChatBase.js

@@ -2968,6 +2968,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const ownVoice = useVoiceSpeaker(settled, !hostSpeaks);
     useSpokenAnswers(displayItems, isLoading, !hostSpeaks && settled?.output === 'always', ownVoice.speaker);
     const speakingNow = voiceSpeaking || ownVoice.state.speaking;
+    // Answers spoken over, hands-free (VOICE.md VO-13): marked *interrupted*.
+    const [interruptedIds, setInterruptedIds] = useState(() => new Set());
     const stopSpeaking = onStopSpeaking ?? (ownVoice.speaker ? ownVoice.stop : undefined);
     const readAnswerAloud = onReadAloud ?? (ownVoice.speaker ? ownVoice.read : undefined);
     const handleSend = useCallback(async (messageOverride, 
@@ -3724,10 +3726,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             .reverse()
             .find((item) => !isToolCallMessage(item) && item.role === 'assistant')?.id
         : undefined;
-    const readAloudFooter = readAnswerAloud
+    const readAloudFooter = readAnswerAloud || interruptedIds.size
         ? (message) => {
             const text = getMessageText(message);
-            return readsAloud(message, text, writingId) ? (_jsx(ReadAloud, { onRead: () => readAnswerAloud(text) })) : null;
+            return (_jsxs(_Fragment, { children: [interruptedIds.has(message.id) ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', fontStyle: 'italic' }, "data-interrupted": "", children: "interrupted" })) : null, readAnswerAloud && readsAloud(message, text, writingId) ? (_jsx(ReadAloud, { onRead: () => readAnswerAloud(text) })) : null] }));
         }
         : undefined;
     const messagesContent = children ? (children) : (_jsxs(Box, { display: "flex", flexDirection: "column", minHeight: 0, 
@@ -3745,7 +3747,14 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 // so every chat with a headless notebook gets the same transcript.
                 notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, renderMessageFooter: readAloudFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
     // The microphone, in the composer's footer (VO-10, VO-11).
-    const voiceControl = settled && settled.input !== 'off' ? (_jsx(ComposerVoice, { voice: settled, input: input, setInput: setInput, disabled: disabled || launching, speaking: speakingNow, onStopSpeaking: stopSpeaking, onInterimChange: setVoiceInterim, 
+    const voiceControl = settled && settled.input !== 'off' ? (_jsx(ComposerVoice, { voice: settled, input: input, setInput: setInput, disabled: disabled || launching, speaking: speakingNow, onStopSpeaking: stopSpeaking, 
+        // Hands-free (VO-12, VO-13): the run in progress, stopped when the
+        // person speaks over it, and the answer marked interrupted.
+        running: isLoading, onStopRun: handleStop, onInterrupted: () => {
+            if (writingId) {
+                setInterruptedIds(ids => new Set([...ids, writingId]));
+            }
+        }, onInterimChange: setVoiceInterim, 
         // The menu offers when answers are heard where the application
         // lets them be (VO-21, VO-30).
         answers: Boolean(voice?.output && voice.output !== 'off' && voice.speechUrl), onSpoken: metadata => {

package/lib/runtimes/variants.d.ts

@@ -1,31 +1,3 @@
-/**
- * Agent runtime variants: where an agent's loop runs, and what runs it.
- *
- * There have always been two ways to start an agent — a local agent-runtimes
- * server and a cloud one — and they were named after the service each talked
- * to (`local-agent-runtimes`, `backend-services`). That naming held while both
- * ran the same framework. A browser agent breaks it: it talks to no service at
- * all, and it runs a different framework.
- *
- * So a variant names the two things that actually vary, in that order:
- *
- *     <location>-<harness>        browser-vercelai
- *                                 local-pydanticai
- *                                 cloud-pydanticai
- *
- * The point of splitting them is that most code cares about exactly one half.
- * Anything about *reaching* a runtime — a URL, a lifecycle, a sandbox — is a
- * question of location. Anything about *turning the loop* — the SDK, the tool
- * protocol, the streaming format — is a question of harness. Code that branches
- * on the whole variant string has to be edited every time either axis gains a
- * value; code that asks {@link locationOf} or {@link harnessOf} does not.
- *
- * That is what makes the next ones cheap. `cloud-ax` is a new harness against
- * an existing location, so only harness-specific code changes; `browser-ax` is
- * a combination of two things that already exist.
- *
- * @module runtimes/variants
- */
 import type { Agentspec } from '../types/agentspecs';
 /** Where the agent's loop runs. */
 export type AgentLocation = 'browser' | 'local' | 'cloud';
@@ -58,6 +30,27 @@ export declare const DEFAULT_AGENT_RUNTIME_VARIANT: AgentRuntimeVariant;
 export declare const SPEC_HARNESS_BY_HARNESS: Record<AgentHarness, string>;
 /** The reverse, for reading an agentspec's declared harness. */
 export declare const HARNESS_BY_SPEC_HARNESS: Record<string, AgentHarness>;
+/** The one catalogue harness whose command an organization's own spec supplies. */
+export declare const CUSTOM_HARNESS = "custom";
+/**
+ * Why no variant runs an agent on this harness, in a sentence, or undefined
+ * when one does.
+ *
+ * A harness of the catalogue (`agentspecs/harnesses`, SHIELD.md SH-01) — Claude
+ * Code, Codex, Gemini CLI, goose, OpenCode, OpenHands, fast-agent — is served
+ * by the Datalayer runtime through its ACP adapter (`ACPAgent`, SHIELD SH-10):
+ * the runtime launches the harness as its subprocess, so the runtime's
+ * locations run it and the browser, which has no process to launch, does not.
+ * Two are refused: `custom`, which names no command in the shared catalogue
+ * (an organization's own harness spec names it), and a harness neither built
+ * in nor of the catalogue. Nothing runs such an agent in its place.
+ */
+export declare function unservedHarnessProblem(spec: Pick<Agentspec, 'id' | 'harness'>): string | undefined;
+/**
+ * Whether a harness id names a harness the Datalayer runtime serves through
+ * its ACP adapter: one of the catalogue, launchable, so not `custom`.
+ */
+export declare function isServedCatalogueHarness(harness: string): boolean;
 /**
  * The names the two original ways to start an agent went by.
  *
@@ -113,7 +106,7 @@ export declare function variantForLocation(location: AgentLocation): AgentRuntim
  * An agentspec says which framework it *prefers* — `harness:` is where the
  * agent normally runs, not a demand — and a variant says which framework a
  * location can actually provide. Where they disagree the location wins, which
- * is why the browser accepts any spec:
+ * is why the browser accepts any spec built for a framework:
  *
  *     harness: pydantic-ai  +  browser  →  runs, with the Vercel AI SDK
  *
@@ -125,15 +118,22 @@ export declare function variantForLocation(location: AgentLocation): AgentRuntim
  * The remote locations are stricter: a spec built for the browser harness
  * assumes frontend tools and no server, so running it on a runtime would be
  * running something else.
+ *
+ * A harness of the catalogue (Claude Code, Codex, …) is a program, not a
+ * framework: the Datalayer runtime launches it as its subprocess and serves it
+ * through its ACP adapter (SHIELD SH-10), so the runtime's locations run it
+ * and the browser does not — the page has no process to launch, and nothing
+ * is run in the harness's place.
  */
 export declare function variantSupportsSpecHarness(variant: AgentRuntimeVariant, specHarness: string | undefined | null): boolean;
 /**
  * The variants that could run an agent with this declared harness.
  *
  * What a host offers a person choosing where to run something. The browser is
- * always among them — it can run anything, because it overrides the harness —
- * while an agent built for the browser is not offered a remote runtime that
- * would be running something else.
+ * among them for any framework — it can run those, because it overrides the
+ * harness — while an agent built for the browser is not offered a remote
+ * runtime that would be running something else, and an agent on a catalogue
+ * harness is offered the runtimes alone, which launch it.
  */
 export declare function variantsForSpecHarness(specHarness: string | undefined | null): AgentRuntimeVariant[];
 /**
@@ -147,19 +147,24 @@ export declare function variantsForSpecHarness(specHarness: string | undefined |
  */
 export declare function legacyTargetOf(variant: AgentRuntimeVariant): RuntimeCreationTarget;
 /**
- * The harness a spec asks for, in the variant spelling.
+ * The harness a spec asks for: a framework in the variant spelling
+ * (`pydanticai`, `vercelai`), or a catalogue harness by its id (`claude-code`).
  *
  * Defaulted rather than optional: every agent is run by something, and a spec
  * that says nothing is run by the framework that has always run it. That
- * default is what lets every spec written before this field stay correct.
+ * default is what lets every spec written before this field stay correct. A
+ * catalogue harness keeps its own id, because no variant spells it: the
+ * variant that serves it is the Datalayer runtime's, whose own loop is
+ * pydantic-ai's and whose ACP adapter turns the harness's.
  */
-export declare function specHarnessOf(spec: Pick<Agentspec, 'harness'>): AgentHarness;
+export declare function specHarnessOf(spec: Pick<Agentspec, 'id' | 'harness'>): string;
 /**
  * The variants that could run this agent.
  *
  * What a host offers when someone picks where to run something: an agent built
  * for the browser harness should not be offered a cloud runtime that cannot
- * turn its loop, and a server-side agent should not be offered the page.
+ * turn its loop, a server-side agent should not be offered the page, and an
+ * agent on a catalogue harness is offered the runtimes that launch it.
  */
 export declare function variantsForSpec(spec: Pick<Agentspec, 'harness'>): AgentRuntimeVariant[];
 /**
@@ -169,4 +174,4 @@ export declare function variantsForSpec(spec: Pick<Agentspec, 'harness'>): Agent
  * variant that can run it at all — so a `harness: vercel-ai` agent lands in
  * the browser without every caller having to know that is where it belongs.
  */
-export declare function defaultVariantForSpec(spec: Pick<Agentspec, 'harness'>): AgentRuntimeVariant;
+export declare function defaultVariantForSpec(spec: Pick<Agentspec, 'id' | 'harness'>): AgentRuntimeVariant;

package/lib/runtimes/variants.js

@@ -2,6 +2,40 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Agent runtime variants: where an agent's loop runs, and what runs it.
+ *
+ * There have always been two ways to start an agent — a local agent-runtimes
+ * server and a cloud one — and they were named after the service each talked
+ * to (`local-agent-runtimes`, `backend-services`). That naming held while both
+ * ran the same framework. A browser agent breaks it: it talks to no service at
+ * all, and it runs a different framework.
+ *
+ * So a variant names the two things that actually vary, in that order:
+ *
+ *     <location>-<harness>        browser-vercelai
+ *                                 local-pydanticai
+ *                                 cloud-pydanticai
+ *
+ * The point of splitting them is that most code cares about exactly one half.
+ * Anything about *reaching* a runtime — a URL, a lifecycle, a sandbox — is a
+ * question of location. Anything about *turning the loop* — the SDK, the tool
+ * protocol, the streaming format — is a question of harness. Code that branches
+ * on the whole variant string has to be edited every time either axis gains a
+ * value; code that asks {@link locationOf} or {@link harnessOf} does not.
+ *
+ * That is what makes the next ones cheap. `cloud-ax` is a new harness against
+ * an existing location, so only harness-specific code changes; `browser-ax` is
+ * a combination of two things that already exist.
+ *
+ * @module runtimes/variants
+ */
+import { getHarness } from '../specs/harnesses';
 /**
  * The combinations that exist today.
  *
@@ -32,6 +66,44 @@ export const HARNESS_BY_SPEC_HARNESS = {
     'pydantic-ai': 'pydanticai',
     'vercel-ai': 'vercelai',
 };
+/** The one catalogue harness whose command an organization's own spec supplies. */
+export const CUSTOM_HARNESS = 'custom';
+/**
+ * Why no variant runs an agent on this harness, in a sentence, or undefined
+ * when one does.
+ *
+ * A harness of the catalogue (`agentspecs/harnesses`, SHIELD.md SH-01) — Claude
+ * Code, Codex, Gemini CLI, goose, OpenCode, OpenHands, fast-agent — is served
+ * by the Datalayer runtime through its ACP adapter (`ACPAgent`, SHIELD SH-10):
+ * the runtime launches the harness as its subprocess, so the runtime's
+ * locations run it and the browser, which has no process to launch, does not.
+ * Two are refused: `custom`, which names no command in the shared catalogue
+ * (an organization's own harness spec names it), and a harness neither built
+ * in nor of the catalogue. Nothing runs such an agent in its place.
+ */
+export function unservedHarnessProblem(spec) {
+    const harness = spec.harness ?? '';
+    if (!harness || harness in HARNESS_BY_SPEC_HARNESS) {
+        return undefined;
+    }
+    const catalogued = getHarness(harness);
+    if (!catalogued) {
+        return `The agent “${spec.id}” runs on “${harness}”, which is no harness.`;
+    }
+    if (harness === CUSTOM_HARNESS) {
+        return `The agent “${spec.id}” runs on the harness “custom”, which names no command: an organization's own harness spec names it, and is never typed into a form.`;
+    }
+    return undefined;
+}
+/**
+ * Whether a harness id names a harness the Datalayer runtime serves through
+ * its ACP adapter: one of the catalogue, launchable, so not `custom`.
+ */
+export function isServedCatalogueHarness(harness) {
+    return (harness !== CUSTOM_HARNESS &&
+        !(harness in HARNESS_BY_SPEC_HARNESS) &&
+        getHarness(harness) !== undefined);
+}
 const VARIANT_BY_LEGACY_TARGET = {
     'backend-services': 'cloud-pydanticai',
     'local-agent-runtimes': 'local-pydanticai',
@@ -104,7 +176,7 @@ export function variantForLocation(location) {
  * An agentspec says which framework it *prefers* — `harness:` is where the
  * agent normally runs, not a demand — and a variant says which framework a
  * location can actually provide. Where they disagree the location wins, which
- * is why the browser accepts any spec:
+ * is why the browser accepts any spec built for a framework:
  *
  *     harness: pydantic-ai  +  browser  →  runs, with the Vercel AI SDK
  *
@@ -116,8 +188,19 @@ export function variantForLocation(location) {
  * The remote locations are stricter: a spec built for the browser harness
  * assumes frontend tools and no server, so running it on a runtime would be
  * running something else.
+ *
+ * A harness of the catalogue (Claude Code, Codex, …) is a program, not a
+ * framework: the Datalayer runtime launches it as its subprocess and serves it
+ * through its ACP adapter (SHIELD SH-10), so the runtime's locations run it
+ * and the browser does not — the page has no process to launch, and nothing
+ * is run in the harness's place.
  */
 export function variantSupportsSpecHarness(variant, specHarness) {
+    if (specHarness && !(specHarness in HARNESS_BY_SPEC_HARNESS)) {
+        // A catalogue harness runs where a runtime can launch it; `custom` and a
+        // harness that is none run nowhere.
+        return (isServedCatalogueHarness(specHarness) && needsRuntimeService(variant));
+    }
     if (runsInBrowser(variant)) {
         return true;
     }
@@ -131,9 +214,10 @@ export function variantSupportsSpecHarness(variant, specHarness) {
  * The variants that could run an agent with this declared harness.
  *
  * What a host offers a person choosing where to run something. The browser is
- * always among them — it can run anything, because it overrides the harness —
- * while an agent built for the browser is not offered a remote runtime that
- * would be running something else.
+ * among them for any framework — it can run those, because it overrides the
+ * harness — while an agent built for the browser is not offered a remote
+ * runtime that would be running something else, and an agent on a catalogue
+ * harness is offered the runtimes alone, which launch it.
  */
 export function variantsForSpecHarness(specHarness) {
     return AGENT_RUNTIME_VARIANTS.filter(variant => variantSupportsSpecHarness(variant, specHarness));
@@ -153,21 +237,32 @@ export function legacyTargetOf(variant) {
         : 'local-agent-runtimes';
 }
 /**
- * The harness a spec asks for, in the variant spelling.
+ * The harness a spec asks for: a framework in the variant spelling
+ * (`pydanticai`, `vercelai`), or a catalogue harness by its id (`claude-code`).
  *
  * Defaulted rather than optional: every agent is run by something, and a spec
  * that says nothing is run by the framework that has always run it. That
- * default is what lets every spec written before this field stay correct.
+ * default is what lets every spec written before this field stay correct. A
+ * catalogue harness keeps its own id, because no variant spells it: the
+ * variant that serves it is the Datalayer runtime's, whose own loop is
+ * pydantic-ai's and whose ACP adapter turns the harness's.
  */
 export function specHarnessOf(spec) {
-    return HARNESS_BY_SPEC_HARNESS[spec.harness ?? ''] ?? 'pydanticai';
+    const problem = unservedHarnessProblem(spec);
+    if (problem) {
+        // Never pydantic-ai in its place: said, and refused (SHIELD SH-01).
+        throw new Error(problem);
+    }
+    const harness = spec.harness ?? '';
+    return HARNESS_BY_SPEC_HARNESS[harness] ?? (harness || 'pydanticai');
 }
 /**
  * The variants that could run this agent.
  *
  * What a host offers when someone picks where to run something: an agent built
  * for the browser harness should not be offered a cloud runtime that cannot
- * turn its loop, and a server-side agent should not be offered the page.
+ * turn its loop, a server-side agent should not be offered the page, and an
+ * agent on a catalogue harness is offered the runtimes that launch it.
  */
 export function variantsForSpec(spec) {
     return variantsForSpecHarness(spec.harness);
@@ -183,5 +278,10 @@ export function defaultVariantForSpec(spec) {
     if (variantSupportsSpecHarness(DEFAULT_AGENT_RUNTIME_VARIANT, spec.harness)) {
         return DEFAULT_AGENT_RUNTIME_VARIANT;
     }
-    return variantsForSpec(spec)[0] ?? DEFAULT_AGENT_RUNTIME_VARIANT;
+    const [first] = variantsForSpec(spec);
+    if (!first) {
+        throw new Error(unservedHarnessProblem(spec) ??
+            `No variant runs the agent “${spec.id}” on “${spec.harness}”.`);
+    }
+    return first;
 }

package/lib/specs/appspecSchema.js

@@ -2522,8 +2522,8 @@ export const APPSPEC_SCHEMA = {
             type: 'string',
         },
         VoiceInput: {
-            description: 'How a person talks to the application (VOICE.md VO-10).\n\n`hands_free` (VO-12) is not one yet: it is refused in a sentence until it\nis built, never taken for click-to-talk.',
-            enum: ['off', 'push_to_talk'],
+            description: 'How a person talks to the application (VOICE.md VO-10, VO-12).\n\n`push_to_talk`: the microphone in the composer, clicked or held.\n`hands_free`: a conversation by voice — the composer offers *Talk with\nit*; a turn ends after a short silence and is sent, the answer is said,\nand listening goes on; speaking over the agent stops its voice (VO-13).\nHands-free implies answers said as they are written (`output: always`).',
+            enum: ['off', 'push_to_talk', 'hands_free'],
             title: 'VoiceInput',
             type: 'string',
         },

package/lib/specs/envvars.d.ts

@@ -8,13 +8,17 @@
  */
 import type { EnvvarSpec } from '../types';
 export declare const ALPHAVANTAGE_API_KEY_SPEC_0_0_1: EnvvarSpec;
+export declare const ANTHROPIC_API_KEY_SPEC_0_0_1: EnvvarSpec;
 export declare const EARTHDATA_PASSWORD_SPEC_0_0_1: EnvvarSpec;
 export declare const EARTHDATA_USERNAME_SPEC_0_0_1: EnvvarSpec;
+export declare const GEMINI_API_KEY_SPEC_0_0_1: EnvvarSpec;
 export declare const GITHUB_TOKEN_SPEC_0_0_1: EnvvarSpec;
 export declare const GOOGLE_OAUTH_CLIENT_ID_SPEC_0_0_1: EnvvarSpec;
 export declare const GOOGLE_OAUTH_CLIENT_SECRET_SPEC_0_0_1: EnvvarSpec;
 export declare const HF_TOKEN_SPEC_0_0_1: EnvvarSpec;
 export declare const KAGGLE_API_TOKEN_SPEC_0_0_1: EnvvarSpec;
+export declare const LLM_API_KEY_SPEC_0_0_1: EnvvarSpec;
+export declare const OPENAI_API_KEY_SPEC_0_0_1: EnvvarSpec;
 export declare const SLACK_BOT_TOKEN_SPEC_0_0_1: EnvvarSpec;
 export declare const SLACK_CHANNEL_IDS_SPEC_0_0_1: EnvvarSpec;
 export declare const SLACK_TEAM_ID_SPEC_0_0_1: EnvvarSpec;