@datalayer/agent-runtimes 1.5.52 → 1.5.53

package/lib/voice/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Voice: agents that listen and speak (VOICE.md).
+ * Voice: agents that listen and speak.
  *
  * Push-to-talk heard on the device (Moonshine, Whisper, Silero VAD, from
  * Datalayer's origin and as pinned), answers spoken by Datalayer's speech
@@ -77,7 +77,7 @@ export interface ChatVoice {
     /** ai-agents, whose speech service says the answers, and hears where the browser does not. */
     speechUrl?: string;
     /**
-     * Where what is said is heard (§5): `device`, the browser; `server`,
+     * Where what is said is heard: `device`, the browser; `server`,
      * Datalayer's speech service; `auto`, the default, the browser where a
      * model there hears the language, else the server. The Appspec's
      * `interface.voice.where`.

package/lib/voice/pinned.d.ts

@@ -1,6 +1,6 @@
 /**
- * The browser's models, from Datalayer's origin and as pinned (VOICE.md
- * VO-49, VO-03): every file a model is made of is fetched from the models'
+ * The browser's models, from Datalayer's origin and as pinned (VO-49, VO-03):
+ * every file a model is made of is fetched from the models'
  * origin, laid out as the pinned store is (`<provider>/<model id>/<path>`), and its
  * SHA-256 checked against the catalogue before anything reads it. A file
  * that is not the one pinned is refused; nothing is asked of another origin.

package/lib/voice/pinned.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * The browser's models, from Datalayer's origin and as pinned (VOICE.md
- * VO-49, VO-03): every file a model is made of is fetched from the models'
+ * The browser's models, from Datalayer's origin and as pinned (VO-49, VO-03):
+ * every file a model is made of is fetched from the models'
  * origin, laid out as the pinned store is (`<provider>/<model id>/<path>`), and its
  * SHA-256 checked against the catalogue before anything reads it. A file
  * that is not the one pinned is refused; nothing is asked of another origin.

package/lib/voice/sayAloud.d.ts

@@ -1,6 +1,6 @@
 /**
- * What only the runtime knows of voice, as it says it over AG-UI (VOICE.md
- * VO-35) and Vercel AI (VO-36): `voice.settings` — the running application's
+ * What only the runtime knows of voice, as it says it over AG-UI (VO-35)
+ * and Vercel AI (VO-36): `voice.settings` — the running application's
  * voice and language, at a run's start — and `voice.say` — a short line the
  * agent wants heard and not written (*One moment*), shown as a caption while
  * it is said. The chat reads `voice.say` from a run's custom events

package/lib/voice/sayAloud.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * What only the runtime knows of voice, as it says it over AG-UI (VOICE.md
- * VO-35) and Vercel AI (VO-36): `voice.settings` — the running application's
+ * What only the runtime knows of voice, as it says it over AG-UI (VO-35)
+ * and Vercel AI (VO-36): `voice.settings` — the running application's
  * voice and language, at a run's start — and `voice.say` — a short line the
  * agent wants heard and not written (*One moment*), shown as a caption while
  * it is said. The chat reads `voice.say` from a run's custom events

package/lib/voice/sentences.d.ts

@@ -1,5 +1,5 @@
 /**
- * An answer as it is heard (VOICE.md VO-20): read as plain words, the way
+ * An answer as it is heard (VO-20): read as plain words, the way
  * the balloon reads it (T-23), and cut into sentences as it is written, so
  * that the first one is said before the answer is finished.
  *

package/lib/voice/sentences.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * An answer as it is heard (VOICE.md VO-20): read as plain words, the way
+ * An answer as it is heard (VO-20): read as plain words, the way
  * the balloon reads it (T-23), and cut into sentences as it is written, so
  * that the first one is said before the answer is finished.
  *

package/lib/voice/serverHearing.d.ts

@@ -8,6 +8,12 @@ export declare const TRANSCRIPTION_STREAM_PATH = "/api/ai-agents/v1/speech/trans
 export declare const STREAM_IDLE_MS = 3000;
 /** How long the final words of a stream are waited for. */
 export declare const STREAM_FINAL_MS = 60000;
+/**
+ * How much of the sound before a stream the service ended for its silence
+ * (with no words) is sent again to the next: a word begun at the cut is
+ * heard whole.
+ */
+export declare const STREAM_LOOKBACK_SAMPLES: number;
 /** The model the speech service hears with (agentspecs' catalogue). */
 export declare const SERVER_HEARING_MODEL = "whisper-large-v3-turbo";
 /** Where a chat's voice hears: in the browser, or on Datalayer's servers. */
@@ -26,7 +32,7 @@ export interface HearingAsked {
     speechUrl?: string;
 }
 /**
- * Where a chat's voice hears (§5): in the browser unless the speech service
+ * Where a chat's voice hears: in the browser unless the speech service
  * is named and the person asked for detection, the application says
  * `server`, or it says `auto` and no model in the browser hears the language.
  */
@@ -94,7 +100,7 @@ export declare class ServerHearing implements Hearing {
 /** Said when the device's model did not load and the server will hear instead. */
 export declare const MOVED_TO_SERVER = "This device could not load its model: what you say will be heard on Datalayer's servers instead. Press the microphone again to agree.";
 /**
- * `where: auto` (§5): each press heard on the device when a model there
+ * `where: auto`: each press heard on the device when a model there
  * hears the language and loads, on the speech service otherwise.
  *
  * The device's model failing to load moves the hearing to the server, and

package/lib/voice/serverHearing.js

@@ -3,11 +3,11 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Hearing on Datalayer's servers (VOICE.md VO-34, VO-14, §5): what was said
+ * Hearing on Datalayer's servers (VO-34, VO-14): what was said
  * in one press, kept to its speech by Silero VAD in the page, then sent as a
  * WAV recording to the speech service's `POST /speech/transcriptions`, where
  * Whisper hears it — small for a spoken turn, large-v3-turbo past one
- * (decision 17) — in any language it knows, and finding
+ * — in any language it knows, and finding
  * the language itself when the person asks for that (detection, VO-14). The
  * sound is held in the request only: the service keeps neither it nor the
  * words (VO-60).
@@ -37,6 +37,12 @@ export const TRANSCRIPTION_STREAM_PATH = '/api/ai-agents/v1/speech/transcription
 export const STREAM_IDLE_MS = 3000;
 /** How long the final words of a stream are waited for. */
 export const STREAM_FINAL_MS = 60_000;
+/**
+ * How much of the sound before a stream the service ended for its silence
+ * (with no words) is sent again to the next: a word begun at the cut is
+ * heard whole.
+ */
+export const STREAM_LOOKBACK_SAMPLES = HEARING_RATE / 2;
 /** The model the speech service hears with (agentspecs' catalogue). */
 export const SERVER_HEARING_MODEL = 'whisper-large-v3-turbo';
 /** The shortest speech worth hearing, in samples: a word said alone. */
@@ -45,7 +51,7 @@ const SHORTEST = HEARING_RATE * 0.2;
 export class ServerRefused extends Error {
 }
 /**
- * Where a chat's voice hears (§5): in the browser unless the speech service
+ * Where a chat's voice hears: in the browser unless the speech service
  * is named and the person asked for detection, the application says
  * `server`, or it says `auto` and no model in the browser hears the language.
  */
@@ -121,7 +127,9 @@ class PressStream {
     waiting;
     closed = false;
     idle;
-    constructor(open, speechUrl, first) {
+    constructor(open, speechUrl, first, from = 0) {
+        // The press's sound from `from` on: what came before was heard already.
+        this.sent = from;
         this.socket = open(streamUrlOf(speechUrl));
         this.socket.binaryType = 'arraybuffer';
         this.socket.onopen = () => {
@@ -152,6 +160,7 @@ class PressStream {
                 this.final = {
                     text: typeof said.text === 'string' ? said.text.trim() : '',
                     language: typeof said.language === 'string' ? said.language : '',
+                    why: typeof said.why === 'string' ? said.why : '',
                 };
                 this.settle();
             }
@@ -170,6 +179,16 @@ class PressStream {
         this.socket.onerror = () => undefined;
         this.touch();
     }
+    /**
+     * The service ended it for its silence, with no words, while the press
+     * goes on: a person who waits before speaking (hands-free's microphone
+     * stays open) is heard by the next stream.
+     */
+    get silencedEmpty() {
+        return (this.final !== undefined &&
+            this.final.why === 'silence' &&
+            !this.final.text);
+    }
     /** Send what the press added since the last call. */
     feed(audio) {
         this.touch();
@@ -272,15 +291,23 @@ export class ServerHearing {
         if (!open) {
             return undefined;
         }
+        let from = 0;
         if (this.press && audio.length < this.press.sent) {
             this.press.close();
             this.press = undefined;
         }
+        else if (this.press?.silencedEmpty) {
+            // Ended by the service for its silence, nothing said: a new stream
+            // hears the rest of the press, from just before the cut.
+            from = Math.max(0, this.press.sent - STREAM_LOOKBACK_SAMPLES);
+            this.press.close();
+            this.press = undefined;
+        }
         if (!this.press) {
             this.press = new PressStream(open, this.options.speechUrl, {
                 token: this.options.token,
                 language: this.options.detect ? '' : language,
-            });
+            }, from);
         }
         return this.press;
     }
@@ -297,6 +324,10 @@ export class ServerHearing {
     }
     async hear(audio, language) {
         const started = performance.now();
+        if (this.press?.silencedEmpty && audio.length >= this.press.sent) {
+            // Cut for its silence before the person spoke: heard by a new stream.
+            this.streamFor(audio, language);
+        }
         const press = this.press && audio.length >= this.press.sent ? this.press : undefined;
         if (this.press && !press) {
             this.press.close();
@@ -368,7 +399,7 @@ export class ServerHearing {
 /** Said when the device's model did not load and the server will hear instead. */
 export const MOVED_TO_SERVER = "This device could not load its model: what you say will be heard on Datalayer's servers instead. Press the microphone again to agree.";
 /**
- * `where: auto` (§5): each press heard on the device when a model there
+ * `where: auto`: each press heard on the device when a model there
  * hears the language and loads, on the speech service otherwise.
  *
  * The device's model failing to load moves the hearing to the server, and

package/lib/voice/settings.d.ts

@@ -1,5 +1,5 @@
 /**
- * A person's own voice settings (VOICE.md VO-30), and what a chat's voice is
+ * A person's own voice settings (VO-30), and what a chat's voice is
  * once they are taken into account (VO-14, VO-25).
  *
  * An application says what voice it wants — `interface.voice` in its spec,
@@ -35,7 +35,7 @@ export declare const VOLUME_RANGE: {
 };
 /**
  * How much longer than usual the person pauses before they are done
- * (VOICE.md VO-69): the silence that stops a microphone clicked on, and the
+ * (VO-69): the silence that stops a microphone clicked on, and the
  * one that ends a hands-free turn, times this.
  */
 export declare const PAUSE_RANGE: {

package/lib/voice/settings.js

@@ -9,7 +9,7 @@ export const RATE_RANGE = { min: 0.5, max: 2, default: 1 };
 export const VOLUME_RANGE = { min: 0, max: 1, default: 1 };
 /**
  * How much longer than usual the person pauses before they are done
- * (VOICE.md VO-69): the silence that stops a microphone clicked on, and the
+ * (VO-69): the silence that stops a microphone clicked on, and the
  * one that ends a hands-free turn, times this.
  */
 export const PAUSE_RANGE = { min: 1, max: 4, default: 1 };
@@ -191,7 +191,7 @@ export function voiceForPerson(voice, person = {}, browser = browserLanguage())
     }
     if (chosen.onDeviceOnly) {
         // Nothing is asked of the speech service: no token, no origin. Answers
-        // are said by that service only (decision 1: no voice made in the
+        // are said by that service only (no voice made in the
         // browser), so they are not heard; listening stays on the device.
         next.speechUrl = undefined;
         next.token = undefined;

package/lib/voice/speaker.d.ts

@@ -1,6 +1,6 @@
 /**
- * Answers heard, from Datalayer's speech service (VOICE.md VO-20, VO-33,
- * decision 1): each sentence is sent to ai-agents as soon as it is written
+ * Answers heard, from Datalayer's speech service (VO-20, VO-33):
+ * each sentence is sent to ai-agents as soon as it is written
  * and played as soon as its audio arrives, one after the other, while the
  * next ones are being made. The level of what plays moves the assistant's
  * mouth (VO-23). Nothing is kept: each sentence's audio is dropped once played.
@@ -11,7 +11,13 @@
 export declare const SYNTHESES_PATH = "/api/ai-agents/v1/speech/syntheses";
 /** What the speaker is doing, for the assistant and the controls. */
 export interface SpeakerState {
-    /** Sound is playing. */
+    /**
+     * Sound is playing, or a sentence given is being made into sound to play
+     * next: from the moment there is something to say, so that hands-free
+     * reads speech in that moment as the person speaking over it (VO-12,
+     * VO-13). What moves the mouth is the sound's level, and the sentence
+     * marked is the one playing.
+     */
     speaking: boolean;
     /** The sentence being said, for the balloon (VO-26). */
     sentence?: string;
@@ -26,7 +32,7 @@ export interface SpeakerOptions {
     language: string;
     /**
      * The person's token, an application's principal's, a visitor's or an
-     * embed's — whose deployment is the one it names (VO-19, decision 16).
+     * embed's — whose deployment is the one it names (VO-19).
      */
     token?: string;
     /**

package/lib/voice/speaker.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Answers heard, from Datalayer's speech service (VOICE.md VO-20, VO-33,
- * decision 1): each sentence is sent to ai-agents as soon as it is written
+ * Answers heard, from Datalayer's speech service (VO-20, VO-33):
+ * each sentence is sent to ai-agents as soon as it is written
  * and played as soon as its audio arrives, one after the other, while the
  * next ones are being made. The level of what plays moves the assistant's
  * mouth (VO-23). Nothing is kept: each sentence's audio is dropped once played.
@@ -100,6 +100,9 @@ export class ServerSpeaker {
             return;
         }
         this.queue.push({ text: sentence, asked: performance.now() });
+        if (!this.state.speaking) {
+            this.set({ speaking: true });
+        }
         this.askAhead();
         if (!this.running) {
             void this.run(this.generation);

package/lib/voice/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Voice in the page (VOICE.md §6): what the chat needs to listen and speak.
+ * Voice in the page: what the chat needs to listen and speak.
  *
  * The packages that hear — transformers.js for Moonshine and Whisper, and
  * vad-web for Silero VAD — are given by the host page (`VoiceEngines`), each

package/lib/voice/useSpokenAnswers.js

@@ -3,8 +3,8 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * The answers of a conversation, heard as they are written (VOICE.md VO-20,
- * VO-21): the newest answer of the agent is cut into sentences as it grows,
+ * The answers of a conversation, heard as they are written (VO-20, VO-21):
+ * the newest answer of the agent is cut into sentences as it grows,
  * and each is given to the speaker as soon as it is complete. The answers
  * already there when voice was turned on are not read.
  *

package/lib/voice/useVoiceSettings.js

@@ -4,7 +4,7 @@
  */
 /**
  * A person's voice settings, as a React state that follows every change —
- * the composer's menu, a settings page, another tab (VOICE.md VO-30).
+ * the composer's menu, a settings page, another tab (VO-30).
  *
  * @module voice/useVoiceSettings
  */

package/lib/voice/useVoiceSpeaker.js

@@ -3,7 +3,7 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * A chat's speaker (VOICE.md VO-20, VO-21, VO-33): its answers said by
+ * A chat's speaker (VO-20, VO-21, VO-33): its answers said by
  * Datalayer's speech service — `POST /api/ai-agents/v1/speech/syntheses` on
  * ai-agents, `datalayer-speech` — while its voice's `output` is not `off`.
  * One for `ChatFloating` and for `ChatBase` alone, so that a chat given a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.52",
+    "version": "1.5.53",
     "type": "module",
     "workspaces": [
         ".",
@@ -137,7 +137,7 @@
         "watch:lib:res": "gulp resources-to-lib-watch",
         "watch:lib:src": "tsc -b -w"
     },
-    "//": "@datalayer/agent-shield (SHIELD SH-53: the policy types, the decisions' sentences, the diff and terminal displays, the report renderer) is not depended on yet: npm holds the scaffold's 1.1.3 as latest, which blocks the real 0.1.x until the user unpublishes it; add \"@datalayer/agent-shield\": \"^0.1.7\" here once it resolves.",
+    "//": "@datalayer/agent-shield (SH-53: the policy types, the decisions' sentences, the diff and terminal displays, the report renderer) is not depended on yet: npm holds the scaffold's 1.1.3 as latest, which blocks the real 0.1.x until the user unpublishes it; add \"@datalayer/agent-shield\": \"^0.1.7\" here once it resolves.",
     "dependencies": {
         "@a2a-js/sdk": "^1.3.0",
         "@a2ui/markdown-it": "0.2.0",

package/scripts/codegen/generate_agentic_commerce.sh

@@ -3,7 +3,7 @@
 # Distributed under the terms of the Modified BSD License.
 #
 # The Agentic Commerce Protocol's checkout models, generated from the
-# specification's JSON Schema (AGENT_PROTOCOLS PR-41), in both languages:
+# specification's JSON Schema (PR-41), in both languages:
 #   agent_runtimes/protocols/agentic_commerce/models.py   (datamodel-code-generator 0.34.0)
 #   src/protocols/agentic-commerce/models.ts              (json-schema-to-typescript 15.0.4)
 #

package/scripts/codegen/generate_agents.py

@@ -236,7 +236,7 @@ def load_fragments(specs_dir: Path) -> List[Dict[str, Any]]:
 
 def refuse_tools_field(spec: Dict[str, Any], path: Path) -> None:
     """Refuse an agent spec that still says `tools` (it is `backend_tools` now) or
-    `ui_plugin` (it is `ui` now, AGENT_PROTOCOLS PS-03).
+    `ui_plugin` (it is `ui` now, PS-03).
     """
     if "ui_plugin" in spec:
         raise SystemExit(
@@ -249,7 +249,7 @@ def refuse_tools_field(spec: Dict[str, Any], path: Path) -> None:
     ):
         raise SystemExit(
             f"Error: {path} says `ui: {ui!r}`: `ui` lists UI plugins, each "
-            "`{plugin, renderer}` (AGENTIC_UI R8); a renderer is said as a plugin's `renderer`"
+            "`{plugin, renderer}` (R8); a renderer is said as a plugin's `renderer`"
         )
     if "tools" in spec:
         raise SystemExit(
@@ -310,7 +310,7 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
 
 
 def check_voices(specs: List[tuple[str, Dict[str, Any]]]) -> None:
-    """Refuse an agent whose `voice` is not an `interface.voice` block of the voice catalogue (VOICE.md VO-41)."""
+    """Refuse an agent whose `voice` is not an `interface.voice` block of the voice catalogue (VO-41)."""
     from agentspecs.apps import agent_voice_problems
 
     problems = [
@@ -333,7 +333,7 @@ def voice_of(spec: Dict[str, Any]) -> Dict[str, Any] | None:
 
 
 def load_protocol_ids(specs_dir: Path) -> set[str]:
-    """Every id of the protocols catalogue (`agentspecs/protocols`, AGENT_PROTOCOLS PS-01)."""
+    """Every id of the protocols catalogue (`agentspecs/protocols`, PS-01)."""
     ids: set[str] = set()
     for yaml_file in sorted((specs_dir.parent / "protocols").glob("*.yaml")):
         protocol = yaml.safe_load(yaml_file.read_text()) or {}
@@ -369,7 +369,7 @@ 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."""
+    """Every harness of the catalogue (`agentspecs/harnesses`, 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":

package/scripts/codegen/generate_apps.py

@@ -172,7 +172,7 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
             mode="json", by_alias=True
         ):
             spec.pop("pap")
-        # PACT, commerce, signed fetch and A2A's extensions the same way (AGENT_PROTOCOLS PI-01, PR-02, EX-11).
+        # PACT, commerce, signed fetch and A2A's extensions the same way (PI-01, PR-02, EX-11).
         for block in ("pact", "commerce", "signed_fetch", "a2a"):
             if block in spec and spec[block] == type(getattr(app, block))().model_dump(
                 mode="json", by_alias=True
@@ -222,7 +222,7 @@ def load_specs(specs_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
                 if (signs := actions_module.server_tool_signs(server, name))
             },
         }
-    # The agent protocols' tools (AGENT_PROTOCOLS PR-54): by protocol, the
+    # The agent protocols' tools (PR-54): by protocol, the
     # connection prefix its connections take and what each tool can do.
     protocols = {
         identity: {
@@ -569,7 +569,7 @@ def _drop_nulls(value: Any) -> Any:
 
 
 def generate_schema_typescript_code() -> str:
-    """The Appspec's JSON Schema, for the editors of the page (LOOP S-01, S-02).
+    """The Appspec's JSON Schema, for the editors of the page (S-01, S-02).
 
     Taken from the agentspecs the catalogue is generated from, so that what
     an editor completes and explains is what the spec accepts.

package/scripts/codegen/generate_harnesses.py

@@ -5,10 +5,10 @@
 """
 Generate Python and TypeScript code from the YAML harness specifications.
 
-One YAML per harness under ``agentspecs/harnesses`` (SHIELD.md SH-01, §3.1):
+One YAML per harness under ``agentspecs/harnesses`` (SH-01):
 an agent program driven over the Agent Client Protocol, how it is launched,
 what it needs, what it honours of an agent spec, and the terms it is served
-under. ``register.yaml`` beside them is the register (SH-04, §3.3): a harness
+under. ``register.yaml`` beside them is the register (SH-04): a harness
 without an entry is refused here as it is in agentspecs.
 
 Usage:
@@ -104,7 +104,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         '"""',
         "Harness Catalog.",
         "",
-        "An agent program driven over the Agent Client Protocol (SHIELD.md SH-01).",
+        "An agent program driven over the Agent Client Protocol (SH-01).",
         "",
         "This file is AUTO-GENERATED from YAML specifications.",
         "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
@@ -234,7 +234,7 @@ def generate_typescript_code(
         "/**",
         " * Harness Catalog.",
         " *",
-        " * An agent program driven over the Agent Client Protocol (SHIELD.md SH-01).",
+        " * An agent program driven over the Agent Client Protocol (SH-01).",
         " *",
         " * This file is AUTO-GENERATED from YAML specifications.",
         " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",

package/scripts/codegen/generate_mcp_servers.py

@@ -122,7 +122,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             ]
         )
         # A server its command runs as a local HTTP process: where it is
-        # reached (STUDIO W-02, `google-workspace`).
+        # reached (W-02, `google-workspace`).
         if spec.get("url"):
             lines.append(f'    url="{spec["url"]}",')
 
@@ -132,7 +132,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
 
         lines.append(f"    required_env_vars={envvars_formatted},")
         # What the code its tools write reads in the code sandbox: given there
-        # when the account has them, never required (LOOP R-19).
+        # when the account has them, never required (R-19).
         sandbox_envvars = spec.get("sandbox_envvars", [])
         if sandbox_envvars:
             lines.append(

package/scripts/codegen/generate_policies.py

@@ -5,7 +5,7 @@
 """
 Generate Python and TypeScript code from the YAML policy specifications.
 
-One YAML per policy under ``agentspecs/policies`` (SHIELD.md SH-50, §6.7):
+One YAML per policy under ``agentspecs/policies`` (SH-50):
 the Shield's policy document under the catalogue's fields. The document's
 schema is the ``agent-shield`` package's, carried by agentspecs verbatim
 (``policies/shield-policy.schema.json``); each document is validated against
@@ -78,7 +78,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         '"""',
         "Policy Catalog.",
         "",
-        "The Shield's policy documents the platform ships or shows (SHIELD.md SH-50):",
+        "The Shield's policy documents the platform ships or shows (SH-50):",
         "each a catalogue entry whose ``policy`` is a document of ``agent_shield.policy``.",
         "",
         "This file is AUTO-GENERATED from YAML specifications.",
@@ -150,7 +150,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         "/**",
         " * Policy Catalog.",
         " *",
-        " * The Shield's policy documents the platform ships or shows (SHIELD.md SH-50).",
+        " * The Shield's policy documents the platform ships or shows (SH-50).",
         " *",
         " * This file is AUTO-GENERATED from YAML specifications.",
         " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",

package/scripts/codegen/generate_protocols.py

@@ -5,8 +5,7 @@
 """
 Generate Python and TypeScript code from the YAML protocol specifications.
 
-One YAML per agent protocol under ``agentspecs/protocols`` (AGENT_PROTOCOLS
-PS-01); an agent spec's or an application's ``protocols`` names the ones it
+One YAML per agent protocol under ``agentspecs/protocols`` (PS-01); an agent spec's or an application's ``protocols`` names the ones it
 speaks (PS-02).
 
 Usage:
@@ -68,7 +67,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         '"""',
         "Protocol Catalog.",
         "",
-        "The agent protocols Datalayer targets (AGENT_PROTOCOLS PS-01).",
+        "The agent protocols Datalayer targets (PS-01).",
         "",
         "This file is AUTO-GENERATED from YAML specifications.",
         "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
@@ -137,7 +136,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         "/**",
         " * Protocol Catalog.",
         " *",
-        " * The agent protocols Datalayer targets (AGENT_PROTOCOLS PS-01).",
+        " * The agent protocols Datalayer targets (PS-01).",
         " *",
         " * This file is AUTO-GENERATED from YAML specifications.",
         " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",

package/scripts/codegen/generate_scenes.py

@@ -5,7 +5,7 @@
 """
 Generate Python and TypeScript code from YAML scene specifications.
 
-A scene (agentspecs >= 0.0.61, LOOP A-11) stages a team: the team says who
+A scene (agentspecs >= 0.0.61, A-11) stages a team: the team says who
 is on stage, the scene says what happens there — the setting, the script,
 the stage directions, the audience, the rehearsal and where it plays. One
 YAML per scene under ``agentspecs/scenes``.
@@ -19,7 +19,7 @@ Empty optional lists are dropped, as ``generate_apps.py`` drops them.
 The scene spec's JSON Schema is written beside the TypeScript catalogue as
 ``sceneSchema.ts`` (``agentspecs.scenes.json_schema``), the way
 ``generate_apps.py`` writes ``appspecSchema.ts``: what an editor of the text
-completes and explains is what the spec accepts (LOOP S-01, A-03).
+completes and explains is what the spec accepts (S-01, A-03).
 
 Usage:
     python generate_scenes.py \\
@@ -88,7 +88,7 @@ def load_specs(specs_dir: Path) -> list[dict[str, Any]]:
     for identity in sorted(scenes):
         scene = scenes[identity]
         spec = scene.model_dump(mode="json", by_alias=True)
-        # A scripted scene stages no team (PAP_DATALAYER X-02): no entry, no cast.
+        # A scripted scene stages no team (X-02): no entry, no cast.
         scripted = spec.get("kind") == "scripted"
         spec["entry"] = "" if scripted else scene.entry_of()
         spec["cast"] = (
@@ -291,7 +291,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
 
 
 def generate_schema_typescript_code(specs_dir: Path) -> str:
-    """The scene spec's JSON Schema, for the editor of its text (LOOP S-01, A-03).
+    """The scene spec's JSON Schema, for the editor of its text (S-01, A-03).
 
     Taken from the agentspecs the catalogue is generated from, so that what
     the editor completes and explains is what the spec accepts. The

package/scripts/codegen/generate_standards.py

@@ -5,7 +5,7 @@
 """
 Generate Python and TypeScript code from the YAML standard specifications.
 
-One YAML per standard under ``agentspecs/standards`` (SHIELD.md SH-60, §6.9):
+One YAML per standard under ``agentspecs/standards`` (SH-60):
 its version, domains and controls, each control with its evidence items,
 cadence and crosswalks. The catalogue is carried whole: the Studio's
 conformance screens read a control's title, status words and crosswalks
@@ -73,7 +73,7 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
         '"""',
         "Standard Catalog.",
         "",
-        "The standards a conformance report answers (SHIELD.md SH-60, §6.9): each a",
+        "The standards a conformance report answers (SH-60): each a",
         "catalogue entry carrying the standard's domains and controls whole.",
         "",
         "This file is AUTO-GENERATED from YAML specifications.",
@@ -158,7 +158,7 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
         "/**",
         " * Standard Catalog.",
         " *",
-        " * The standards a conformance report answers (SHIELD.md SH-60, §6.9).",
+        " * The standards a conformance report answers (SH-60).",
         " *",
         " * This file is AUTO-GENERATED from YAML specifications.",
         " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",

package/scripts/codegen/generate_teams.py

@@ -490,7 +490,7 @@ from agent_runtimes.types import (
             # `shared` by default: routing only makes sense if the member
             # receiving the work can see what was already said.
             context = spec.get("context") or {}
-            # The Frames of its shared context (LOOP A-04): written only when
+            # The Frames of its shared context (A-04): written only when
             # it names some, as the parser reads it.
             frames = context.get("frames") or []
             code += (