@datalayer/agent-runtimes 1.5.30 → 1.5.31

package/lib/apps/apps/checks.js

@@ -38,6 +38,7 @@ 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, isAssistantCharacterId, PAGE_OUTPUT_SHOWS, parseAppspec, } from './appspec';
 import { classesOf, splitRef, toolBehaviours } from './rules';
@@ -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);
     }

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/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;

package/lib/specs/envvars.js

@@ -15,6 +15,16 @@ export const ALPHAVANTAGE_API_KEY_SPEC_0_0_1 = {
     icon: 'key',
     emoji: '🔑',
 };
+export const ANTHROPIC_API_KEY_SPEC_0_0_1 = {
+    id: 'ANTHROPIC_API_KEY',
+    version: '0.0.1',
+    name: 'Anthropic API Key',
+    description: "API key for Anthropic's Claude API. Required by the Claude Code harness, and by any harness configured with Anthropic as its model provider; the person's own, never a Claude.ai subscription login.",
+    registrationUrl: 'https://platform.claude.com/settings/keys',
+    tags: ['authentication', 'api-key', 'anthropic', 'harness'],
+    icon: 'key',
+    emoji: '🔑',
+};
 export const EARTHDATA_PASSWORD_SPEC_0_0_1 = {
     id: 'EARTHDATA_PASSWORD',
     version: '0.0.1',
@@ -35,6 +45,16 @@ export const EARTHDATA_USERNAME_SPEC_0_0_1 = {
     icon: 'key',
     emoji: '🔑',
 };
+export const GEMINI_API_KEY_SPEC_0_0_1 = {
+    id: 'GEMINI_API_KEY',
+    version: '0.0.1',
+    name: 'Gemini API Key',
+    description: "API key for Google's Gemini API. Required by the Gemini CLI harness in place of a Google login; the person's own.",
+    registrationUrl: 'https://aistudio.google.com/apikey',
+    tags: ['authentication', 'api-key', 'google', 'harness'],
+    icon: 'key',
+    emoji: '🔑',
+};
 export const GITHUB_TOKEN_SPEC_0_0_1 = {
     id: 'GITHUB_TOKEN',
     version: '0.0.1',
@@ -92,6 +112,26 @@ export const KAGGLE_API_TOKEN_SPEC_0_0_1 = {
     icon: 'key',
     emoji: '🔑',
 };
+export const LLM_API_KEY_SPEC_0_0_1 = {
+    id: 'LLM_API_KEY',
+    version: '0.0.1',
+    name: 'OpenHands LLM API Key',
+    description: "The model provider's key the OpenHands CLI reads, with LLM_MODEL, when started with --override-with-envs. Required by the OpenHands harness; the person's own key at their provider.",
+    registrationUrl: 'https://docs.openhands.dev/openhands/usage/cli/installation',
+    tags: ['authentication', 'api-key', 'openhands', 'harness'],
+    icon: 'key',
+    emoji: '🔑',
+};
+export const OPENAI_API_KEY_SPEC_0_0_1 = {
+    id: 'OPENAI_API_KEY',
+    version: '0.0.1',
+    name: 'OpenAI API Key',
+    description: "API key for OpenAI's API. Required by the Codex harness, which takes it in place of a ChatGPT login; the person's own.",
+    registrationUrl: 'https://platform.openai.com/api-keys',
+    tags: ['authentication', 'api-key', 'openai', 'harness'],
+    icon: 'key',
+    emoji: '🔑',
+};
 export const SLACK_BOT_TOKEN_SPEC_0_0_1 = {
     id: 'SLACK_BOT_TOKEN',
     version: '0.0.1',
@@ -136,13 +176,17 @@ export const TAVILY_API_KEY_SPEC_0_0_1 = {
 // ============================================================================
 export const ENVVAR_CATALOG = {
     ALPHAVANTAGE_API_KEY: ALPHAVANTAGE_API_KEY_SPEC_0_0_1,
+    ANTHROPIC_API_KEY: ANTHROPIC_API_KEY_SPEC_0_0_1,
     EARTHDATA_PASSWORD: EARTHDATA_PASSWORD_SPEC_0_0_1,
     EARTHDATA_USERNAME: EARTHDATA_USERNAME_SPEC_0_0_1,
+    GEMINI_API_KEY: GEMINI_API_KEY_SPEC_0_0_1,
     GITHUB_TOKEN: GITHUB_TOKEN_SPEC_0_0_1,
     GOOGLE_OAUTH_CLIENT_ID: GOOGLE_OAUTH_CLIENT_ID_SPEC_0_0_1,
     GOOGLE_OAUTH_CLIENT_SECRET: GOOGLE_OAUTH_CLIENT_SECRET_SPEC_0_0_1,
     HF_TOKEN: HF_TOKEN_SPEC_0_0_1,
     KAGGLE_API_TOKEN: KAGGLE_API_TOKEN_SPEC_0_0_1,
+    LLM_API_KEY: LLM_API_KEY_SPEC_0_0_1,
+    OPENAI_API_KEY: OPENAI_API_KEY_SPEC_0_0_1,
     SLACK_BOT_TOKEN: SLACK_BOT_TOKEN_SPEC_0_0_1,
     SLACK_CHANNEL_IDS: SLACK_CHANNEL_IDS_SPEC_0_0_1,
     SLACK_TEAM_ID: SLACK_TEAM_ID_SPEC_0_0_1,

package/lib/specs/harnesses.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Harness Catalog.
+ *
+ * An agent program driven over the Agent Client Protocol (SHIELD.md SH-01).
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { HarnessSpec } from '../types/agentspecs';
+export declare const CLAUDE_CODE_HARNESS_0_0_1: HarnessSpec;
+export declare const CODEX_HARNESS_0_0_1: HarnessSpec;
+export declare const CUSTOM_HARNESS_0_0_1: HarnessSpec;
+export declare const FAST_AGENT_HARNESS_0_0_1: HarnessSpec;
+export declare const GEMINI_CLI_HARNESS_0_0_1: HarnessSpec;
+export declare const GOOSE_HARNESS_0_0_1: HarnessSpec;
+export declare const OPENCODE_HARNESS_0_0_1: HarnessSpec;
+export declare const OPENHANDS_HARNESS_0_0_1: HarnessSpec;
+export declare const HARNESS_CATALOGUE: Record<string, HarnessSpec>;
+/** A harness by id. */
+export declare function getHarness(harnessId: string): HarnessSpec | undefined;
+/** Every harness of the catalogue. */
+export declare function listHarnesses(): HarnessSpec[];