@datalayer/agent-runtimes 1.5.28 → 1.5.31

package/lib/voice/ComposerVoice.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef } from 'react';
 import { DeviceHearing } from './hearing';
+import { HandsFree } from './HandsFree';
 import { ServerHearing, hearingPlace } from './serverHearing';
 import { VoiceInput } from './VoiceInput';
 import { VoiceMenu } from './VoiceMenu';
@@ -14,7 +15,7 @@ export function spokenOf(value) {
         ? said
         : undefined;
 }
-export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, onInterimChange, answers = false, }) {
+export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, running = false, onStopRun, onInterrupted, onInterimChange, answers = false, }) {
     // In the browser, or on Datalayer's servers where the application, the
     // language or the person's detection asks for it (§5, VO-14, VO-34).
     const place = hearingPlace(voice);
@@ -45,7 +46,14 @@ export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled
     if (!hearing) {
         return null;
     }
-    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
+    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), voice.input === 'hands_free' ? (_jsx(HandsFree, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', microphoneId: voice.microphoneId, turnSilenceMs: voice.turnSilenceMs, disabled: disabled, running: running, speaking: speaking, onStopSpeaking: onStopSpeaking, onStopRun: onStopRun, onInterrupted: onInterrupted, onInterim: (words) => {
+                    setInput(words ? afterBase(words) : base.current);
+                    onInterimChange?.(words !== '');
+                }, send: (text, metadata) => {
+                    onInterimChange?.(false);
+                    setInput(base.current);
+                    send(text, metadata);
+                } })) : null, _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
                     base.current = input.trim();
                     onStopSpeaking?.();
                 }, 

package/lib/voice/HandsFree.d.ts

@@ -0,0 +1,55 @@
+/**
+ * *Talk with it*: a conversation by voice, hands-free (VOICE.md VO-12,
+ * VO-13), beside the composer's microphone where the application's voice
+ * says `input: hands_free`.
+ *
+ * On, the microphone stays open. The words are written in the composer as
+ * they are heard (VO-11); once the person has spoken and been silent for the
+ * turn's silence (`turnSilenceMs`, 700 ms unless said), what was said is
+ * heard whole and **sent** — nothing waits for a click. The answer is said as
+ * it is written (hands-free implies `output: always`), and listening goes
+ * on through it: speech heard while the agent thinks or speaks is
+ * **barge-in** (VO-13) — its voice stops at once, the run is stopped while
+ * the answer is still being written, the interrupted answer is marked in
+ * the conversation, and what was heard starts the next turn. The state is
+ * shown at all times: *Listening…*, *Thinking…*, *Speaking…*, *Paused*.
+ * `Esc` or *Pause* pauses it; the toggle again turns it off.
+ *
+ * The microphone is opened anew when the agent begins answering, so what it
+ * holds then is the person's; the browser's echo cancellation keeps the
+ * answer's own sound out (`openMicrophone`). The first use asks for the
+ * microphone as the click-to-talk does (VO-61), under the same consent.
+ *
+ * @module voice/HandsFree
+ */
+import type { JSX } from 'react';
+import type { Hearing } from './hearing';
+import type { SpokenMetadata } from './types';
+export interface HandsFreeProps {
+    hearing: Hearing;
+    /** The language listened to, BCP 47. */
+    language: string;
+    /** Whose consent to the microphone is remembered: the application's id. */
+    consentKey: string;
+    /** The microphone the person chose (VO-30); the browser's own when unsaid. */
+    microphoneId?: string;
+    /** The silence after speech that ends a turn, in ms; 700 unless said (VO-12). */
+    turnSilenceMs?: number;
+    /** A turn, heard whole: sent at once. */
+    send: (text: string, metadata: SpokenMetadata) => void;
+    /** The words heard so far, for the composer (VO-11); `''` gives it back. */
+    onInterim?: (text: string) => void;
+    /** The agent is answering: a run is in progress. */
+    running?: boolean;
+    /** The agent's answer is being said. */
+    speaking?: boolean;
+    /** Stops the agent's voice at once (barge-in, VO-13). */
+    onStopSpeaking?: () => void;
+    /** Stops the run while the answer is still being written (barge-in, VO-13). */
+    onStopRun?: () => void;
+    /** The answer being written was interrupted: marked in the conversation (VO-13). */
+    onInterrupted?: () => void;
+    disabled?: boolean;
+}
+export declare function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs, send, onInterim, running, speaking, onStopSpeaking, onStopRun, onInterrupted, disabled, }: HandsFreeProps): JSX.Element;
+export default HandsFree;

package/lib/voice/HandsFree.js

@@ -0,0 +1,211 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Button, IconButton, Text, Tooltip } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { openMicrophone } from './capture';
+import { CONSENT_SENTENCE, SERVER_CONSENT_SENTENCE, consent, consentKeyFor, consented, } from './consent';
+import { HANDS_FREE_WORDS, IDLE_PAUSE_MS, TURN_SILENCE_MS, bargedIn, handsFreeState, turnEnded, } from './handsFree';
+import { INTERIM_MS } from './VoiceInput';
+/** Waits. */
+const pause = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+export function HandsFree({ hearing, language, consentKey, microphoneId, turnSilenceMs = TURN_SILENCE_MS, send, onInterim, running = false, speaking = false, onStopSpeaking, onStopRun, onInterrupted, disabled = false, }) {
+    const [on, setOn] = useState(false);
+    const [paused, setPaused] = useState(false);
+    const [asking, setAsking] = useState(false);
+    const [problem, setProblem] = useState();
+    const state = handsFreeState({ on, paused, speaking, running });
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    const runningRef = useRef(running);
+    runningRef.current = running;
+    const capture = useRef(undefined);
+    const latest = useRef({
+        send,
+        onInterim,
+        onStopSpeaking,
+        onStopRun,
+        onInterrupted,
+    });
+    latest.current = {
+        send,
+        onInterim,
+        onStopSpeaking,
+        onStopRun,
+        onInterrupted,
+    };
+    const key = consentKeyFor(consentKey, hearing.where);
+    const turnOn = useCallback(() => {
+        if (!consented(key)) {
+            setAsking(true);
+            return;
+        }
+        setProblem(undefined);
+        setPaused(false);
+        setOn(true);
+    }, [key]);
+    const turnOff = useCallback(() => {
+        setOn(false);
+        setPaused(false);
+        capture.current?.cancel();
+        capture.current = undefined;
+        latest.current.onInterim?.('');
+    }, []);
+    /*
+     * The loop: while on and not paused, the microphone is open and what it
+     * heard so far is looked at every INTERIM_MS. Listening, the turn ends on
+     * the silence and is sent; thinking or speaking, speech is barge-in. The
+     * microphone is opened anew when the agent begins answering, and after
+     * each turn, so what it holds is only what came since.
+     */
+    const heardWhile = useRef('listening');
+    useEffect(() => {
+        if (!on || paused) {
+            return;
+        }
+        let alive = true;
+        let quietSince = Date.now();
+        void (async () => {
+            try {
+                await hearing.ready(language);
+                capture.current = await openMicrophone(microphoneId);
+            }
+            catch (error) {
+                if (alive) {
+                    setProblem(error instanceof Error
+                        ? error.message
+                        : 'The microphone could not be opened.');
+                    setOn(false);
+                }
+                return;
+            }
+            heardWhile.current =
+                stateRef.current === 'listening' ? 'listening' : 'answering';
+            while (alive) {
+                await pause(INTERIM_MS);
+                const open = capture.current;
+                if (!alive || !open) {
+                    return;
+                }
+                const now = stateRef.current;
+                const answering = now === 'thinking' || now === 'speaking';
+                // The agent began answering, or finished: hear anew from here.
+                if ((answering && heardWhile.current === 'listening') ||
+                    (!answering && heardWhile.current === 'answering')) {
+                    open.cancel();
+                    try {
+                        capture.current = await openMicrophone(microphoneId);
+                    }
+                    catch {
+                        return;
+                    }
+                    heardWhile.current = answering ? 'answering' : 'listening';
+                    quietSince = Date.now();
+                    continue;
+                }
+                let so;
+                try {
+                    so = await hearing.hearSoFar(open.peek(), language);
+                }
+                catch {
+                    so = undefined;
+                }
+                if (!alive || capture.current !== open || !so) {
+                    continue;
+                }
+                if (so.text) {
+                    latest.current.onInterim?.(so.text);
+                }
+                if (so.spoke) {
+                    quietSince = Date.now();
+                }
+                if (bargedIn(now, so)) {
+                    // The person speaks over the agent (VO-13): its voice and its run
+                    // stop; what was heard goes on as the next turn.
+                    latest.current.onStopSpeaking?.();
+                    if (now === 'thinking' || runningRef.current) {
+                        latest.current.onStopRun?.();
+                    }
+                    latest.current.onInterrupted?.();
+                    heardWhile.current = 'listening';
+                    continue;
+                }
+                if (now === 'listening' && turnEnded(so, turnSilenceMs)) {
+                    capture.current = undefined;
+                    const audio = await open.stop();
+                    let heard;
+                    try {
+                        heard = await hearing.hear(audio, language);
+                    }
+                    catch (error) {
+                        heard = undefined;
+                        if (alive) {
+                            setProblem(error instanceof Error
+                                ? error.message
+                                : 'What you said could not be heard.');
+                        }
+                    }
+                    if (!alive) {
+                        return;
+                    }
+                    latest.current.onInterim?.('');
+                    if (heard) {
+                        latest.current.send(heard.text, heard.metadata);
+                    }
+                    try {
+                        capture.current = await openMicrophone(microphoneId);
+                    }
+                    catch {
+                        return;
+                    }
+                    heardWhile.current = 'listening';
+                    quietSince = Date.now();
+                    continue;
+                }
+                if (now === 'listening' && Date.now() - quietSince >= IDLE_PAUSE_MS) {
+                    setPaused(true);
+                    return;
+                }
+            }
+        })();
+        return () => {
+            alive = false;
+            capture.current?.cancel();
+            capture.current = undefined;
+        };
+        // The loop reads the state through a ref: it is not restarted on it.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [on, paused, hearing, language, microphoneId, turnSilenceMs]);
+    // Esc pauses it.
+    useEffect(() => {
+        if (!on) {
+            return;
+        }
+        const down = (event) => {
+            if (event.key === 'Escape' && !paused) {
+                setPaused(true);
+                capture.current?.cancel();
+                capture.current = undefined;
+                latest.current.onInterim?.('');
+            }
+        };
+        window.addEventListener('keydown', down);
+        return () => window.removeEventListener('keydown', down);
+    }, [on, paused]);
+    return (_jsxs(Box, { display: "inline-flex", alignItems: "center", sx: { gap: 1, position: 'relative' }, "data-hands-free": state, children: [_jsx(Tooltip, { text: on
+                    ? 'Stop talking with it'
+                    : 'Talk with it: speak, it answers, and listens on (hands-free)', direction: "n", children: _jsx(Button, { size: "small", variant: on ? 'primary' : 'invisible', "aria-pressed": on, "aria-label": on ? 'Stop talking with it' : 'Talk with it', disabled: disabled, "data-hands-free-toggle": "", onClick: () => (on ? turnOff() : turnOn()), children: HANDS_FREE_WORDS.off }) }), on ? (_jsxs(_Fragment, { children: [_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, role: "status", "aria-live": "polite", "data-hands-free-state": state, children: HANDS_FREE_WORDS[state] }), paused ? (_jsx(IconButton, { icon: () => _jsx("span", { "aria-hidden": "true", children: "\u25B6" }), size: "small", variant: "invisible", "aria-label": "Resume listening", "data-hands-free-resume": "", onClick: () => setPaused(false) })) : (_jsx(IconButton, { icon: () => _jsx("span", { "aria-hidden": "true", children: "\u275A\u275A" }), size: "small", variant: "invisible", "aria-label": "Pause listening (Esc)", "data-hands-free-pause": "", onClick: () => {
+                            setPaused(true);
+                            capture.current?.cancel();
+                            capture.current = undefined;
+                            latest.current.onInterim?.('');
+                        } }))] })) : null, problem ? (_jsx(Text, { sx: { fontSize: 0, color: 'danger.fg' }, "data-hands-free-problem": "", children: problem })) : null, asking ? (_jsxs(Box, { role: "dialog", "aria-label": "The microphone", "data-hands-free-consent": "", position: "absolute", bottom: "100%", left: 0, width: 280, p: 3, bg: "canvas.overlay", border: "1px solid", borderColor: "border.default", borderRadius: 2, boxShadow: "shadow.large", zIndex: 10, children: [_jsx(Text, { as: "p", sx: { fontSize: 1, mb: 2 }, children: hearing.where === 'server'
+                            ? SERVER_CONSENT_SENTENCE
+                            : CONSENT_SENTENCE }), _jsxs(Box, { display: "flex", gap: 2, justifyContent: "flex-end", children: [_jsx(Button, { size: "small", onClick: () => setAsking(false), children: "Not now" }), _jsx(Button, { size: "small", variant: "primary", "data-hands-free-consent-yes": "", onClick: () => {
+                                    consent(key);
+                                    setAsking(false);
+                                    setProblem(undefined);
+                                    setPaused(false);
+                                    setOn(true);
+                                }, children: "Use the microphone" })] })] })) : null] }));
+}
+export default HandsFree;

package/lib/voice/chatVoice.d.ts

@@ -35,7 +35,8 @@ export interface ChatVoicePlace {
  * - **Listening**: a microphone in the composer — click it and speak, the
  *   words written in the box as they are heard, stopped by a second click
  *   or when the person stops speaking; or held, and let go (VO-10, VO-11).
- *   `hands_free` (VO-12) is not built: `checkAppspec` refuses it.
+ *   `hands_free` (VO-12): the microphone, and *Talk with it* beside it; it
+ *   implies answers said as they are written.
  * - **Speaking**: its answers said by Datalayer's speech service, on request
  *   or always (VO-20, VO-21); refused here when its host says no service.
  */

package/lib/voice/chatVoice.js

@@ -35,7 +35,8 @@ export const DATALAYER_VOICE_ENGINES = {
  * - **Listening**: a microphone in the composer — click it and speak, the
  *   words written in the box as they are heard, stopped by a second click
  *   or when the person stops speaking; or held, and let go (VO-10, VO-11).
- *   `hands_free` (VO-12) is not built: `checkAppspec` refuses it.
+ *   `hands_free` (VO-12): the microphone, and *Talk with it* beside it; it
+ *   implies answers said as they are written.
  * - **Speaking**: its answers said by Datalayer's speech service, on request
  *   or always (VO-20, VO-21); refused here when its host says no service.
  */
@@ -49,8 +50,9 @@ export function chatVoiceOf(spec, place) {
     const language = spec.language || place.language || 'en-US';
     return {
         language,
-        input: spec.input === 'off' ? 'off' : 'push_to_talk',
-        output: spec.output,
+        input: spec.input,
+        // Hands-free implies the answers heard as they are written (VO-12).
+        output: spec.input === 'hands_free' ? 'always' : spec.output,
         voice: spec.voice || voiceFor(language)?.id || '',
         modelsUrl: place.modelsUrl || DATALAYER_SPEECH_MODELS_URL,
         engines: DATALAYER_VOICE_ENGINES,

package/lib/voice/handsFree.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A conversation by voice, hands-free (VOICE.md VO-12, VO-13): what the
+ * composer is doing at every moment, and when a turn ends or the person
+ * speaks over the agent. Pure: the component (`HandsFree`) keeps the
+ * microphone and the clock, this decides.
+ *
+ * - **Listening**: the microphone is open; the turn ends after
+ *   `turnSilenceMs` of silence once the person has spoken (700 ms unless
+ *   the application or the person says otherwise), and is sent.
+ * - **Thinking**: the turn was sent and the agent is answering, nothing
+ *   said yet.
+ * - **Speaking**: the answer is being said. The microphone stays open:
+ *   speech heard now is barge-in (VO-13) — the voice stops at once, the run
+ *   is stopped when the answer is still being written, and what was heard
+ *   starts the next turn.
+ * - **Paused**: the person paused it (`Esc`, *Pause*), or nothing was said
+ *   for `IDLE_PAUSE_MS`; nothing is heard until resumed.
+ *
+ * @module voice/handsFree
+ */
+/** What hands-free is doing, shown at all times (VO-12). */
+export type HandsFreeState = 'off' | 'listening' | 'thinking' | 'speaking' | 'paused';
+/** The word for each state, as the composer shows it. */
+export declare const HANDS_FREE_WORDS: Record<HandsFreeState, string>;
+/** The silence after speech that ends a turn, in ms, unless said otherwise (VO-12). */
+export declare const TURN_SILENCE_MS = 700;
+/** Listening with nothing said for this long pauses it: a microphone is not left open on an empty room. */
+export declare const IDLE_PAUSE_MS: number;
+/** What decides the state. */
+export interface HandsFreeInputs {
+    /** The toggle is on. */
+    on: boolean;
+    /** The person paused it, or the room went quiet. */
+    paused: boolean;
+    /** The agent's answer is being said. */
+    speaking: boolean;
+    /** A run is in progress: the agent is answering. */
+    running: boolean;
+}
+/** The state for what is known: speaking wins over thinking, pausing over both. */
+export declare function handsFreeState(inputs: HandsFreeInputs): HandsFreeState;
+/** What the microphone heard so far, as the hearing says it (`HeardSoFar`). */
+export interface HeardSoFarLike {
+    spoke: boolean;
+    silentMs: number;
+}
+/**
+ * Whether the turn ended: the person spoke, and has been silent for the
+ * turn's silence since (VO-12).
+ */
+export declare function turnEnded(heard: HeardSoFarLike, turnSilenceMs?: number): boolean;
+/**
+ * Whether the person spoke over the agent (VO-13): speech found since the
+ * agent began answering, while it thinks or speaks. The microphone is opened
+ * anew when the agent begins, so what it holds is the person's, not the
+ * answer's echo — the browser's echo cancellation keeps that out.
+ */
+export declare function bargedIn(state: HandsFreeState, heard: HeardSoFarLike): boolean;

package/lib/voice/handsFree.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The word for each state, as the composer shows it. */
+export const HANDS_FREE_WORDS = {
+    off: 'Talk with it',
+    listening: 'Listening…',
+    thinking: 'Thinking…',
+    speaking: 'Speaking…',
+    paused: 'Paused',
+};
+/** The silence after speech that ends a turn, in ms, unless said otherwise (VO-12). */
+export const TURN_SILENCE_MS = 700;
+/** Listening with nothing said for this long pauses it: a microphone is not left open on an empty room. */
+export const IDLE_PAUSE_MS = 5 * 60_000;
+/** The state for what is known: speaking wins over thinking, pausing over both. */
+export function handsFreeState(inputs) {
+    if (!inputs.on) {
+        return 'off';
+    }
+    if (inputs.paused) {
+        return 'paused';
+    }
+    if (inputs.speaking) {
+        return 'speaking';
+    }
+    if (inputs.running) {
+        return 'thinking';
+    }
+    return 'listening';
+}
+/**
+ * Whether the turn ended: the person spoke, and has been silent for the
+ * turn's silence since (VO-12).
+ */
+export function turnEnded(heard, turnSilenceMs = TURN_SILENCE_MS) {
+    return heard.spoke && heard.silentMs >= turnSilenceMs;
+}
+/**
+ * Whether the person spoke over the agent (VO-13): speech found since the
+ * agent began answering, while it thinks or speaks. The microphone is opened
+ * anew when the agent begins, so what it holds is the person's, not the
+ * answer's echo — the browser's echo cancellation keeps that out.
+ */
+export function bargedIn(state, heard) {
+    return (state === 'speaking' || state === 'thinking') && heard.spoke;
+}

package/lib/voice/index.d.ts

@@ -14,6 +14,8 @@ export * from './pinned';
 export * from './capture';
 export * from './hearing';
 export * from './serverHearing';
+export * from './handsFree';
+export { HandsFree, type HandsFreeProps } from './HandsFree';
 export * from './speaker';
 export * from './consent';
 export * from './settings';
@@ -47,8 +49,14 @@ export type { VoiceSpeaker } from './useVoiceSpeaker';
 export interface ChatVoice {
     /** The language listened to and spoken, BCP 47. */
     language: string;
-    /** `push_to_talk`: the microphone in the composer; `off`: none. Hands-free is Phase V3. */
-    input: 'off' | 'push_to_talk';
+    /**
+     * `push_to_talk`: the microphone in the composer; `hands_free`: that, and
+     * *Talk with it* beside it — a conversation by voice (VO-12, VO-13);
+     * `off`: none.
+     */
+    input: 'off' | 'push_to_talk' | 'hands_free';
+    /** The silence after speech that ends a hands-free turn, in ms (VO-12): 700 when unsaid. */
+    turnSilenceMs?: number;
     /**
      * When answers are heard: `always`, as they are written; `on_request`, a
      * *Read aloud* under each answer (VO-21); or `off`, the default.

package/lib/voice/index.js

@@ -8,6 +8,8 @@ export * from './pinned';
 export * from './capture';
 export * from './hearing';
 export * from './serverHearing';
+export * from './handsFree';
+export { HandsFree } from './HandsFree';
 export * from './speaker';
 export * from './consent';
 export * from './settings';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.28",
+    "version": "1.5.31",
     "type": "module",
     "workspaces": [
         ".",

package/scripts/codegen/generate_agents.py

@@ -304,6 +304,7 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
 
     check_model_additionals(resolved, load_model_ids(specs_dir))
     check_protocols(resolved, load_protocol_ids(specs_dir))
+    check_harnesses(resolved, load_harnesses(specs_dir))
     check_voices(resolved)
     return resolved
 
@@ -364,6 +365,60 @@ def check_protocols(
         raise SystemExit("\n".join(problems))
 
 
+BUILTIN_HARNESSES = ("pydantic-ai", "vercel-ai")
+
+
+def load_harnesses(specs_dir: Path) -> dict[str, dict[str, Any]]:
+    """Every harness of the catalogue (`agentspecs/harnesses`, SHIELD.md SH-01), by id."""
+    harnesses: dict[str, dict[str, Any]] = {}
+    for yaml_file in sorted((specs_dir.parent / "harnesses").glob("*.yaml")):
+        if yaml_file.name == "register.yaml":
+            continue
+        harness = yaml.safe_load(yaml_file.read_text()) or {}
+        if harness.get("id"):
+            harnesses[str(harness["id"])] = harness
+    return harnesses
+
+
+def check_harnesses(
+    specs: List[tuple[str, Dict[str, Any]]], harnesses: dict[str, dict[str, Any]]
+) -> None:
+    """Refuse an agent naming a harness the catalogue does not know, or asking what it cannot honour (SH-01)."""
+    problems = []
+    for _, spec in specs:
+        harness_id = str(spec.get("harness") or BUILTIN_HARNESSES[0])
+        if harness_id in BUILTIN_HARNESSES:
+            continue
+        harness = harnesses.get(harness_id)
+        if harness is None:
+            problems.append(
+                f"{spec.get('id')}: there is no harness named {harness_id!r}: one of "
+                f"{', '.join([*BUILTIN_HARNESSES, *sorted(harnesses)])}"
+            )
+            continue
+        if harness_id == "custom":
+            problems.append(
+                f"{spec.get('id')}: the harness 'custom' names no command: an organization's "
+                "own harness spec names it"
+            )
+            continue
+        honours = harness.get("honours") or {}
+        if spec.get("model") and not honours.get("model"):
+            problems.append(
+                f"{spec.get('id')}: the harness {harness_id!r} does not take a model"
+            )
+        if spec.get("subagents") and not honours.get("subagents"):
+            problems.append(
+                f"{spec.get('id')}: the harness {harness_id!r} has its own subagents"
+            )
+        if spec.get("skills") and (harness.get("skills") or {}).get("format") == "none":
+            problems.append(
+                f"{spec.get('id')}: the harness {harness_id!r} reads no skills"
+            )
+    if problems:
+        raise SystemExit("\n".join(problems))
+
+
 def load_model_ids(specs_dir: Path) -> set[str]:
     """Every id the models catalogue answers to: its ids and their aliases."""
     ids: set[str] = set()
@@ -1726,6 +1781,7 @@ export * from './uiRenderers';
 export * from './protocols';
 export * from './frames';
 export * from './cogs';
+export * from './harnesses';
 export * from './guards';
 export * from './gates';
 export * from './tracks';

package/scripts/codegen/generate_envvars.py

@@ -13,6 +13,7 @@ Usage:
 """
 
 import argparse
+import json
 import sys
 from pathlib import Path
 from typing import Any
@@ -85,7 +86,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
                 f'    id="{envvar_id}",',
                 f'    version="{version}",',
                 f'    name="{spec["name"]}",',
-                f'    description="{spec["description"]}",',
+                f"    description={json.dumps(spec['description'], ensure_ascii=False)},",
                 f"    registrationUrl={registration_url_value},",
                 f"    tags={_fmt_list(spec.get('tags', []))},",
                 f"    icon={icon},",
@@ -185,7 +186,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
                 f"  id: '{envvar_id}',",
                 f"  version: '{version}',",
                 f"  name: '{spec['name']}',",
-                f"  description: '{spec['description']}',",
+                f"  description: {json.dumps(spec['description'], ensure_ascii=False)},",
             ]
         )