@datalayer/agent-runtimes 1.5.128 → 1.6.5

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.
@@ -726,6 +726,71 @@ export interface StageSpec {
726
726
  icon: string;
727
727
  emoji: string;
728
728
  }
729
+ /**
730
+ * Who is acting when an agent acts, issued by whom and proven how
731
+ * (`agentspecs/identities`): a person, an agent, an application, an
732
+ * organization, a visitor or a service, under Datalayer IAM, the Personal
733
+ * Agent Protocol, Amazon Bedrock AgentCore Identity or an organization's OIDC.
734
+ */
735
+ export interface IdentitySpec {
736
+ id: string;
737
+ version: string;
738
+ name: string;
739
+ description: string;
740
+ subject: 'person' | 'agent' | 'application' | 'organization' | 'visitor' | 'service';
741
+ provider: 'datalayer' | 'pap' | 'aws-agentcore' | 'oidc';
742
+ /** Protocols of the catalogue it speaks, by id. */
743
+ protocols: string[];
744
+ /** How a caller proves it on the way in. */
745
+ inbound: {
746
+ kind: 'none' | 'session' | 'jwt' | 'sigv4' | 'api-key' | 'dpop' | 'http-signature';
747
+ issuer: string;
748
+ discoveryUrl: string;
749
+ algorithms: string[];
750
+ audiences: string[];
751
+ clients: string[];
752
+ scopes: string[];
753
+ claims: Record<string, string>;
754
+ lifetimeSeconds: number;
755
+ };
756
+ /** The token the agent holds while it acts. */
757
+ workload: {
758
+ token: 'none' | 'acting' | 'client-credentials' | 'agentcore-runtime' | 'agentcore-jwt';
759
+ lifetimeSeconds: number;
760
+ };
761
+ /** Where third-party credentials are kept, and for which providers. */
762
+ credentials: {
763
+ vault: 'none' | 'datalayer' | 'agentcore';
764
+ providers: {
765
+ name: string;
766
+ kind: 'oauth2' | 'api-key';
767
+ flow: '' | 'user-federation' | 'm2m';
768
+ scopes: string[];
769
+ }[];
770
+ };
771
+ /** Who keeps the signing keys, and the algorithm. */
772
+ custody: {
773
+ keys: string;
774
+ algorithm: string;
775
+ };
776
+ /** Who consents, who hosts it, and whether it is bound to the session that asked. */
777
+ consent: {
778
+ by: string;
779
+ hostedBy: string;
780
+ binding: boolean;
781
+ };
782
+ /** For a PAP identity: what the protocol binds. */
783
+ pap?: {
784
+ roles: ('personal-agent' | 'company')[];
785
+ clientIdPerApplication: boolean;
786
+ pairwise: boolean;
787
+ dpop: boolean;
788
+ };
789
+ enabled: boolean;
790
+ tags: string[];
791
+ icon: string;
792
+ emoji: string;
793
+ }
729
794
  /** What is on a Stage. */
730
795
  export type StageKind = 'scene' | 'app' | 'battle';
731
796
  /** What is on a Stage: the one of `scene`, `app` and `battle` it names. */
@@ -1917,6 +1982,11 @@ export interface Agentspec {
1917
1982
  * the fields an Appspec says under `interface.voice`; absent when unsaid.
1918
1983
  */
1919
1984
  voice?: AppVoiceSpec;
1985
+ /**
1986
+ * Who it acts as: an Identity of the catalogue (`agentspecs/identities`),
1987
+ * `id` or `id:version`; absent when unsaid (the platform's default).
1988
+ */
1989
+ identity?: string;
1920
1990
  }
1921
1991
  /**
1922
1992
  * Where a subagent reached over A2A lives, or how to launch it.
@@ -11,6 +11,15 @@ export interface MCPServerTool {
11
11
  /** JSON schema for tool input parameters */
12
12
  inputSchema?: Record<string, unknown>;
13
13
  }
14
+ /**
15
+ * How a remote MCP server's bearer is minted for the run (AC-20).
16
+ */
17
+ export interface MCPServerAuth {
18
+ /** Who mints it: an Amazon Bedrock AgentCore Gateway's inbound authorizer trusts the identity */
19
+ kind: 'agentcore-gateway';
20
+ /** The identity of the identities catalogue the server trusts, by id */
21
+ identity: string;
22
+ }
14
23
  /**
15
24
  * Configuration for an MCP server.
16
25
  */
@@ -35,6 +44,8 @@ export interface MCPServer {
35
44
  args: string[];
36
45
  /** The headers a remote server is sent with every request, `${VAR}` expanded as it starts: the bearer among them */
37
46
  headers?: Record<string, string>;
47
+ /** A bearer minted for the run instead of one in `headers`: an AgentCore Gateway trusting the identity named (AC-20) */
48
+ auth?: MCPServerAuth;
38
49
  /** Whether the server is available (based on tool discovery) */
39
50
  isAvailable: boolean;
40
51
  /** Transport type: 'stdio', 'http', or 'streamable-http' — a remote server reached at `url` with its `headers` when it has no `command`, a command run as a local HTTP process at `url` when it has one */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@datalayer/agent-runtimes",
3
- "version": "1.5.128",
3
+ "version": "1.6.5",
4
4
  "type": "module",
5
5
  "workspaces": [
6
6
  ".",
@@ -306,6 +306,7 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
306
306
  check_protocols(resolved, load_protocol_ids(specs_dir))
307
307
  check_harnesses(resolved, load_harnesses(specs_dir))
308
308
  check_voices(resolved)
309
+ check_identities(resolved, load_identity_ids(specs_dir))
309
310
  return resolved
310
311
 
311
312
 
@@ -342,6 +343,37 @@ def load_protocol_ids(specs_dir: Path) -> set[str]:
342
343
  return ids
343
344
 
344
345
 
346
+ def load_identity_ids(specs_dir: Path) -> set[str]:
347
+ """Every id of the identities catalogue (`agentspecs/identities`)."""
348
+ ids: set[str] = set()
349
+ for yaml_file in sorted((specs_dir.parent / "identities").glob("*.yaml")):
350
+ identity = yaml.safe_load(yaml_file.read_text()) or {}
351
+ if identity.get("id"):
352
+ ids.add(str(identity["id"]))
353
+ return ids
354
+
355
+
356
+ def check_identities(
357
+ specs: List[tuple[str, Dict[str, Any]]], identity_ids: set[str]
358
+ ) -> None:
359
+ """Refuse an agent that names no identity, or one the identities catalogue does not hold."""
360
+ problems = []
361
+ for _, spec in specs:
362
+ said = spec.get("identity")
363
+ if not said:
364
+ if identity_ids:
365
+ problems.append(f"{spec.get('id')}: identity is required (who the agent acts as)")
366
+ continue
367
+ base, _, version = str(said).rpartition(":")
368
+ identity = base if base and "." in version else str(said)
369
+ if identity not in identity_ids:
370
+ problems.append(
371
+ f"{spec.get('id')}: identity names what the catalogue does not know: {said}"
372
+ )
373
+ if problems:
374
+ raise SystemExit("\n".join(problems))
375
+
376
+
345
377
  def check_protocols(
346
378
  specs: List[tuple[str, Dict[str, Any]]], protocol_ids: set[str]
347
379
  ) -> None:
@@ -608,6 +640,10 @@ from agent_runtimes.types import (
608
640
  voice_py_line = (
609
641
  f" voice={_fmt_py_literal(voice)},\n" if voice is not None else ""
610
642
  )
643
+ identity_val = spec.get("identity")
644
+ voice_py_line += (
645
+ f' identity="{identity_val}",\n' if identity_val else ""
646
+ )
611
647
  inference_provider = spec.get("inference_provider")
612
648
  inference_provider_str = (
613
649
  f'"{inference_provider}"' if inference_provider else "None"
@@ -1242,6 +1278,10 @@ const FRONTEND_TOOL_MAP: Record<string, any> = {
1242
1278
  voice_ts_line = (
1243
1279
  f" voice: {_fmt_ts_literal(voice)},\n" if voice is not None else ""
1244
1280
  )
1281
+ identity_val = spec.get("identity")
1282
+ voice_ts_line += (
1283
+ f" identity: '{identity_val}',\n" if identity_val else ""
1284
+ )
1245
1285
  inference_provider = spec.get("inference_provider")
1246
1286
  inference_provider_ts = (
1247
1287
  f"'{inference_provider}'" if inference_provider else "undefined"
@@ -53,7 +53,8 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
53
53
  "import tempfile",
54
54
  "from typing import Dict",
55
55
  "",
56
- "from agent_runtimes.types import MCPServer",
56
+ "from agent_runtimes.types import MCPServer"
57
+ + (", MCPServerAuth" if any(spec.get("auth") for spec in specs) else ""),
57
58
  "",
58
59
  "# " + "=" * 76,
59
60
  "# MCP Server Definitions",
@@ -140,6 +141,13 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
140
141
  for key, value in headers.items():
141
142
  lines.append(f' "{key}": "{value}",')
142
143
  lines.append(" },")
144
+ # A bearer minted for the run (AC-20): an AgentCore Gateway trusting
145
+ # the identity named, never a header written in the spec.
146
+ if spec.get("auth"):
147
+ auth = spec["auth"]
148
+ lines.append(
149
+ f' auth=MCPServerAuth(kind="{auth["kind"]}", identity="{auth["identity"]}"),'
150
+ )
143
151
 
144
152
  # Add env field if present
145
153
  if env_formatted:
@@ -251,7 +259,9 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
251
259
  def _actions_of(spec: dict[str, Any]) -> dict[str, Any]:
252
260
  """What the spec says its tools do, as plain data: the classes by tool, the day checked, the note."""
253
261
  actions = spec.get("actions") or {}
254
- tidy: dict[str, Any] = {"tools": {str(k): str(v) for k, v in (actions.get("tools") or {}).items()}}
262
+ tidy: dict[str, Any] = {
263
+ "tools": {str(k): str(v) for k, v in (actions.get("tools") or {}).items()}
264
+ }
255
265
  if actions.get("checked"):
256
266
  tidy["checked"] = str(actions["checked"])
257
267
  if actions.get("note"):
@@ -334,6 +344,11 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
334
344
  if spec.get("headers")
335
345
  else []
336
346
  ),
347
+ *(
348
+ [f" auth: {json.dumps(spec['auth'], ensure_ascii=False)},"]
349
+ if spec.get("auth")
350
+ else []
351
+ ),
337
352
  f" transport: '{spec.get('transport', 'stdio')}',",
338
353
  f" enabled: {str(spec.get('enabled', False)).lower()},",
339
354
  " isAvailable: false,",
@@ -77,6 +77,16 @@ KINDS: dict[str, dict[str, str]] = {
77
77
  "title": "Stage Catalog.",
78
78
  "about": "Something of the catalogue put on stage, and where it plays: a scene played whole,\nan app or a Battle; each member on a runtime at the deployment that answers for it;\nwhether anyone may watch without an account. Resolved: a Stage wears what it stages.",
79
79
  },
80
+ "identities": {
81
+ "model": "IdentitySpec",
82
+ "suffix": "IDENTITY",
83
+ "catalogue": "IDENTITY_CATALOGUE",
84
+ "one": "identity",
85
+ "One": "Identity",
86
+ "Many": "Identities",
87
+ "title": "Identity Catalog.",
88
+ "about": "Who is acting when an agent acts: a person, an agent, an application, an\norganization, a visitor or a service, issued by Datalayer IAM, the Personal Agent\nProtocol, Amazon Bedrock AgentCore Identity or an organization's OIDC provider;\nhow each proves it, the token it holds, where its third-party credentials are kept.",
89
+ },
80
90
  "ops": {
81
91
  "model": "OpSpec",
82
92
  "suffix": "OP",
@@ -100,6 +110,10 @@ CAMEL = {
100
110
  "clock_seconds": "clockSeconds",
101
111
  "decides_by": "decidesBy",
102
112
  "runs_in": "runsIn",
113
+ "discovery_url": "discoveryUrl",
114
+ "lifetime_seconds": "lifetimeSeconds",
115
+ "hosted_by": "hostedBy",
116
+ "client_id_per_application": "clientIdPerApplication",
103
117
  }
104
118
 
105
119
  def _flat(text: Any) -> str:
@@ -153,6 +167,11 @@ def load_specs(kind: str, specs_dir: Path) -> list[dict[str, Any]]:
153
167
  elif kind == "stages":
154
168
  stages = module.load_stages(specs_dir)
155
169
  specs = [stages[identity].model_dump(mode="json") for identity in sorted(stages)]
170
+ elif kind == "identities":
171
+ identities = module.load_identities(specs_dir)
172
+ specs = [
173
+ identities[identity].model_dump(mode="json") for identity in sorted(identities)
174
+ ]
156
175
  elif kind == "tracks":
157
176
  tracks = module.load_tracks(specs_dir)
158
177
  specs = [
@@ -371,7 +390,7 @@ def generate_typescript_code(kind: str, specs: list[dict[str, Any]]) -> str:
371
390
  " );",
372
391
  "}",
373
392
  "",
374
- f"export function list{names['One']}s(): {names['model']}[] {{",
393
+ f"export function list{names.get('Many', names['One'] + 's')}(): {names['model']}[] {{",
375
394
  f" return Object.values({names['catalogue']});",
376
395
  "}",
377
396
  "",
@@ -408,7 +427,7 @@ def generate_typescript_code(kind: str, specs: list[dict[str, Any]]) -> str:
408
427
  def main() -> None:
409
428
  """Generate one kind's catalogues."""
410
429
  parser = argparse.ArgumentParser(
411
- description="Generate Python and TypeScript code from YAML Op, Guard, Gate, Track, Battle and Stage specifications"
430
+ description="Generate Python and TypeScript code from YAML Op, Guard, Gate, Track, Battle, Stage and Identity specifications"
412
431
  )
413
432
  parser.add_argument(
414
433
  "--kind",