@datalayer/agent-runtimes 1.6.49 → 1.6.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1869,6 +1869,26 @@ export interface AgentPolicy {
1869
1869
  * keep it out (`listed: false`), as the home page's five since agentspecs 0.0.187.
1870
1870
  */
1871
1871
  export declare const isAgentspecOffered: (spec: Pick<Agentspec, "enabled" | "listed"> | undefined | null) => boolean;
1872
+ /**
1873
+ * What an agent starts without (agentspecs 0.0.188, the user, 14 November
1874
+ * 2026): MCP servers and skills of its own, by id without version. One whose
1875
+ * secrets are not set up is left out, and the agent told which, instead of
1876
+ * holding the start back; of each group of `atLeastOne`, one must be set up.
1877
+ */
1878
+ export interface AgentspecOptional {
1879
+ mcpServers: string[];
1880
+ skills: string[];
1881
+ atLeastOne: string[][];
1882
+ }
1883
+ /** A component of an agent: one of its MCP servers or skills. */
1884
+ export type AgentspecComponentKind = 'mcpServer' | 'skill';
1885
+ /** Whether the agent starts without this MCP server or skill when its secrets are not set up. */
1886
+ export declare const isAgentspecComponentOptional: (spec: Pick<Agentspec, "optional"> | undefined | null, kind: AgentspecComponentKind, id: string) => boolean;
1887
+ /**
1888
+ * The groups of an agent's optional components none of which is set up:
1889
+ * each names its members by id. `isSetUp` says whether one is, by id.
1890
+ */
1891
+ export declare const unmetAgentspecGroups: (spec: Pick<Agentspec, "optional"> | undefined | null, isSetUp: (id: string) => boolean) => string[][];
1872
1892
  /** The engines that run and host an agent (`runtime_engine`), the default first. */
1873
1893
  export declare const RUNTIME_ENGINES: readonly ["datalayer", "kagent", "agentcore"];
1874
1894
  /** What runs and hosts an agent: a Datalayer runtime, kagent, or AWS AgentCore. */
@@ -1902,6 +1922,12 @@ export interface Agentspec {
1902
1922
  * not listed runs by id and as a default, without being offered.
1903
1923
  */
1904
1924
  listed?: boolean;
1925
+ /**
1926
+ * What the agent starts without (agentspecs 0.0.188): its MCP servers and
1927
+ * skills, by id, left out when their secrets are not set up, and groups of
1928
+ * which one must be.
1929
+ */
1930
+ optional?: AgentspecOptional;
1905
1931
  /** AI model identifier to use for this agent */
1906
1932
  model?: string;
1907
1933
  /**
@@ -11,6 +11,17 @@ export const stagedRefOf = (stage) => stage.scene || stage.app || stage.battle;
11
11
  * keep it out (`listed: false`), as the home page's five since agentspecs 0.0.187.
12
12
  */
13
13
  export const isAgentspecOffered = (spec) => spec?.enabled === true && spec.listed !== false;
14
+ const componentIdOf = (ref) => String(ref ?? '').split(':')[0];
15
+ /** Whether the agent starts without this MCP server or skill when its secrets are not set up. */
16
+ export const isAgentspecComponentOptional = (spec, kind, id) => {
17
+ const listed = kind === 'mcpServer' ? spec?.optional?.mcpServers : spec?.optional?.skills;
18
+ return (listed ?? []).includes(componentIdOf(id));
19
+ };
20
+ /**
21
+ * The groups of an agent's optional components none of which is set up:
22
+ * each names its members by id. `isSetUp` says whether one is, by id.
23
+ */
24
+ export const unmetAgentspecGroups = (spec, isSetUp) => (spec?.optional?.atLeastOne ?? []).filter(group => !group.some(id => isSetUp(componentIdOf(id))));
14
25
  /** The engines that run and host an agent (`runtime_engine`), the default first. */
15
26
  export const RUNTIME_ENGINES = ['datalayer', 'kagent', 'agentcore'];
16
27
  /** How an engine is named to a person. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@datalayer/agent-runtimes",
3
- "version": "1.6.49",
3
+ "version": "1.6.50",
4
4
  "type": "module",
5
5
  "workspaces": [
6
6
  ".",
@@ -514,6 +514,38 @@ def check_model_additionals(
514
514
  raise SystemExit("\n".join(problems))
515
515
 
516
516
 
517
+ def optional_of(spec: Dict[str, Any]) -> Dict[str, Any] | None:
518
+ """What an agent starts without (agentspecs 0.0.188), by id without version.
519
+
520
+ Refuses an entry that is not among the agent's own MCP servers or skills,
521
+ and a group naming what is not optional: the catalogue says it once.
522
+ """
523
+ optional = spec.get("optional")
524
+ if optional is None:
525
+ return None
526
+ base = lambda ref: str(ref).split(":")[0] # noqa: E731
527
+ servers = [base(ref) for ref in optional.get("mcp_servers") or []]
528
+ skills = [base(ref) for ref in optional.get("skills") or []]
529
+ own_servers = {base(ref) for ref in spec.get("mcp_servers") or []}
530
+ own_skills = {base(ref) for ref in spec.get("skills") or []}
531
+ agent = spec.get("id")
532
+ for kind, named, own in (
533
+ ("MCP server", servers, own_servers),
534
+ ("skill", skills, own_skills),
535
+ ):
536
+ for ref in named:
537
+ if ref not in own:
538
+ raise SystemExit(f"{agent}: optional {kind} {ref} is not its own")
539
+ groups = [
540
+ [base(ref) for ref in group] for group in optional.get("at_least_one") or []
541
+ ]
542
+ for group in groups:
543
+ for ref in group:
544
+ if ref not in servers and ref not in skills:
545
+ raise SystemExit(f"{agent}: {ref} in at_least_one is not optional")
546
+ return {"mcp_servers": servers, "skills": skills, "at_least_one": groups}
547
+
548
+
517
549
  def generate_python_code(specs: List[tuple[str, Dict[str, Any]]]) -> str:
518
550
  """Generate Python code from agent specifications."""
519
551
  # Header
@@ -665,6 +697,10 @@ from agent_runtimes.types import (
665
697
  if model_additionals
666
698
  else ""
667
699
  )
700
+ optional = optional_of(spec)
701
+ optional_py_line = (
702
+ f" optional={_fmt_py_literal(optional)},\n" if optional else ""
703
+ )
668
704
  voice = voice_of(spec)
669
705
  voice_py_line = (
670
706
  f" voice={_fmt_py_literal(voice)},\n" if voice is not None else ""
@@ -797,7 +833,7 @@ from agent_runtimes.types import (
797
833
  domain={f'"{domain_value}"' if domain_value else "None"},
798
834
  enabled={spec.get("enabled", True)},
799
835
  listed={spec.get("listed", True)},
800
- model={model_str},
836
+ {optional_py_line} model={model_str},
801
837
  {model_additionals_py_line} inference_provider={inference_provider_str},
802
838
  mcp_servers=[{mcp_servers_str}],
803
839
  skills={_fmt_list(skill_refs)},
@@ -1066,6 +1102,9 @@ def generate_typescript_code(
1066
1102
  import type { Agentspec } from '"""
1067
1103
  code += types_import_path
1068
1104
  code += """';
1105
+ import { isAgentspecComponentOptional } from '"""
1106
+ code += types_import_path
1107
+ code += """/agentspecs';
1069
1108
  """
1070
1109
 
1071
1110
  # Only add MCP server imports if needed
@@ -1309,6 +1348,20 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
1309
1348
  if model_additionals
1310
1349
  else ""
1311
1350
  )
1351
+ optional = optional_of(spec)
1352
+ optional_ts_line = (
1353
+ " optional: "
1354
+ + _fmt_ts_literal(
1355
+ {
1356
+ "mcpServers": optional["mcp_servers"],
1357
+ "skills": optional["skills"],
1358
+ "atLeastOne": optional["at_least_one"],
1359
+ }
1360
+ )
1361
+ + ",\n"
1362
+ if optional
1363
+ else ""
1364
+ )
1312
1365
  voice = voice_of(spec)
1313
1366
  voice_ts_line = (
1314
1367
  f" voice: {_fmt_ts_literal(voice)},\n" if voice is not None else ""
@@ -1390,7 +1443,7 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
1390
1443
  domain: {domain_ts},
1391
1444
  enabled: {str(spec.get("enabled", True)).lower()},
1392
1445
  listed: {str(spec.get("listed", True)).lower()},
1393
- model: {model_ts},
1446
+ {optional_ts_line} model: {model_ts},
1394
1447
  {model_additionals_ts_line}{inference_provider_line} mcpServers: [{mcp_servers_str}],
1395
1448
  skills: [{skills_str}].filter(Boolean) as SkillSpec[],
1396
1449
  backendTools: [{tools_str}],
@@ -1487,17 +1540,20 @@ export function listAgentspecs(prefix?: string): Agentspec[] {
1487
1540
  * Collect all required environment variables for an agent spec.
1488
1541
  *
1489
1542
  * Iterates over the spec's MCP servers and skills and returns the
1490
- * deduplicated union of their `requiredEnvVars` arrays.
1543
+ * deduplicated union of their `requiredEnvVars` arrays, without those of
1544
+ * the servers and skills it starts without (`optional`, agentspecs 0.0.188).
1491
1545
  */
1492
1546
  export function getAgentspecRequiredEnvVars(spec: Agentspec): string[] {
1493
1547
  const vars = new Set<string>();
1494
1548
  const baseEnvVar = (v: string): string => v.split(':')[0] ?? v;
1495
1549
  for (const server of spec.mcpServers) {
1550
+ if (isAgentspecComponentOptional(spec, 'mcpServer', server.id)) continue;
1496
1551
  for (const v of server.requiredEnvVars ?? []) {
1497
1552
  vars.add(baseEnvVar(v));
1498
1553
  }
1499
1554
  }
1500
1555
  for (const skill of spec.skills) {
1556
+ if (isAgentspecComponentOptional(spec, 'skill', skill.id)) continue;
1501
1557
  for (const v of skill.requiredEnvVars ?? []) {
1502
1558
  vars.add(baseEnvVar(v));
1503
1559
  }
@@ -1742,6 +1798,7 @@ __all__ = ["AGENTSPECS", "get_agent_spec", "list_agentspecs"]
1742
1798
  */
1743
1799
 
1744
1800
  import type { Agentspec } from '../../types';
1801
+ import { isAgentspecComponentOptional } from '../../types/agentspecs';
1745
1802
 
1746
1803
  """
1747
1804
 
@@ -1799,16 +1856,19 @@ export function listAgentspecs(prefix?: string): Agentspec[] {
1799
1856
  }
1800
1857
 
1801
1858
  /**
1802
- * Collect all required environment variables for an agent spec.
1859
+ * Collect all required environment variables for an agent spec, without
1860
+ * those of the servers and skills it starts without (`optional`).
1803
1861
  */
1804
1862
  export function getAgentspecRequiredEnvVars(spec: Agentspec): string[] {
1805
1863
  const vars = new Set<string>();
1806
1864
  for (const server of spec.mcpServers) {
1865
+ if (isAgentspecComponentOptional(spec, 'mcpServer', server.id)) continue;
1807
1866
  for (const v of server.requiredEnvVars ?? []) {
1808
1867
  vars.add(v);
1809
1868
  }
1810
1869
  }
1811
1870
  for (const skill of spec.skills) {
1871
+ if (isAgentspecComponentOptional(spec, 'skill', skill.id)) continue;
1812
1872
  for (const v of skill.requiredEnvVars ?? []) {
1813
1873
  vars.add(v);
1814
1874
  }