@datalayer/agent-runtimes 1.5.35 → 1.5.36

package/lib/specs/policies.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Policy Catalog.
+ *
+ * The Shield's policy documents the platform ships or shows (SHIELD.md SH-50).
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+import type { PolicySpec } from '../types/agentspecs';
+export declare const DEFAULT_POLICY_0_0_1: PolicySpec;
+export declare const ORGANIZATION_BASELINE_POLICY_0_0_1: PolicySpec;
+export declare const POLICY_CATALOGUE: Record<string, PolicySpec>;
+/** A policy by id. */
+export declare function getPolicy(policyId: string): PolicySpec | undefined;
+/** Every policy of the catalogue. */
+export declare function listPolicySpecs(): PolicySpec[];

package/lib/specs/policies.js

@@ -0,0 +1,228 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const DEFAULT_POLICY_0_0_1 = {
+    id: 'default',
+    version: '0.0.1',
+    name: 'The default policy',
+    description: "Decision 5's default, the session document every Shield decides with under the organization's and the application's: read, search, edit and move inside the workspace are done; delete, run a command, reach outside the workspace, a command naming a credential, sudo, a package install from the network or git push are asked first with the command shown; a fetch goes through the allow-list, which is empty; send and buy are asked.",
+    enabled: true,
+    tags: ['policy', 'default'],
+    policy: {
+        scope: 'session',
+        version: 1,
+        rules: [
+            {
+                name: 'read inside the workspace',
+                decision: 'allow',
+                classes: ['read'],
+                kinds: [],
+                where: 'inside',
+                paths: [],
+                commands: [],
+            },
+            {
+                name: 'edit and move inside the workspace',
+                decision: 'allow',
+                classes: ['write'],
+                kinds: [],
+                where: 'inside',
+                paths: [],
+                commands: [],
+                reason: 'shown as diffs',
+            },
+            {
+                name: 'delete',
+                decision: 'ask',
+                classes: ['delete'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [],
+            },
+            {
+                name: 'a command naming a credential',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [
+                    '(?i)(api[_-]?key|secret|token|password|passwd|credential|\\.env\\b|id_(rsa|ed25519)|\\.ssh/|\\.aws/|\\.netrc|\\.datalayer/|datalayerrc)',
+                ],
+                reason: 'the command is shown',
+            },
+            {
+                name: 'sudo',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: ['(?:^|[\\s;&|(])(?:sudo|doas|su)\\b'],
+                reason: 'the command is shown',
+            },
+            {
+                name: 'a package install from the network',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [
+                    '\\b(?:pip3?|pipx|uv|npm|pnpm|yarn|bun|apt(?:-get)?|brew|cargo|gem|conda|mamba|go)(?:\\s+pip)?\\s+(?:install|add|i|get)\\b',
+                ],
+                reason: 'the command is shown',
+            },
+            {
+                name: 'git push',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: ['\\bgit\\b[^;&|]*\\bpush\\b'],
+                reason: 'the command is shown',
+            },
+            {
+                name: 'run a command',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [],
+            },
+            {
+                name: 'outside the workspace',
+                decision: 'ask',
+                classes: [],
+                kinds: [],
+                where: 'outside',
+                paths: [],
+                commands: [],
+            },
+            {
+                name: 'send or buy',
+                decision: 'ask',
+                classes: ['send', 'buy'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [],
+            },
+        ],
+        limits: {
+            tool_calls: {
+                soft: 100,
+                hard: 200,
+            },
+            terminals_open: {
+                soft: 4,
+                hard: 8,
+            },
+            bytes_written: {
+                soft: 5242880,
+                hard: 20971520,
+            },
+        },
+        network: {
+            fetch: [],
+        },
+        mcp: {
+            allow: [],
+        },
+        harnesses: {
+            admit: [],
+            credentials: 'account',
+        },
+    },
+};
+export const ORGANIZATION_BASELINE_POLICY_0_0_1 = {
+    id: 'organization-baseline',
+    version: '0.0.1',
+    name: "An organization's baseline",
+    description: "An example of the organization scope an administrator writes in IAM (SHIELD.md §6.7): running a command asks, nothing is deleted, nothing outside the workspace; the limits of §6.3 with a model budget of 200 000 then 400 000 tokens and a spend limit of 5 then 10 USD (500 then 1 000 credits); fetches to *.datalayer.io alone; Claude Code and Codex admitted, each on the account's own key.",
+    enabled: true,
+    tags: ['policy', 'organization', 'example'],
+    policy: {
+        scope: 'organization',
+        version: 1,
+        rules: [
+            {
+                name: 'running a command asks',
+                decision: 'ask',
+                classes: ['execute'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [],
+                reason: "the organization's rule: every command is shown to a person first",
+            },
+            {
+                name: 'nothing is deleted',
+                decision: 'deny',
+                classes: ['delete'],
+                kinds: [],
+                where: 'any',
+                paths: [],
+                commands: [],
+                reason: "the organization's rule",
+            },
+            {
+                name: 'outside the workspace: leave it to me',
+                decision: 'deny',
+                classes: [],
+                kinds: [],
+                where: 'outside',
+                paths: [],
+                commands: [],
+            },
+        ],
+        limits: {
+            tool_calls: {
+                soft: 100,
+                hard: 200,
+            },
+            terminals_open: {
+                soft: 2,
+                hard: 4,
+            },
+            bytes_written: {
+                soft: 5242880,
+                hard: 20971520,
+            },
+            model_tokens: {
+                soft: 200000,
+                hard: 400000,
+            },
+            spend: {
+                soft: 500,
+                hard: 1000,
+            },
+        },
+        network: {
+            fetch: ['*.datalayer.io'],
+        },
+        mcp: {
+            allow: [],
+        },
+        harnesses: {
+            admit: ['claude-code', 'codex'],
+            credentials: 'account',
+        },
+    },
+};
+export const POLICY_CATALOGUE = {
+    default: DEFAULT_POLICY_0_0_1,
+    'organization-baseline': ORGANIZATION_BASELINE_POLICY_0_0_1,
+};
+/** A policy by id. */
+export function getPolicy(policyId) {
+    return POLICY_CATALOGUE[policyId];
+}
+/** Every policy of the catalogue. */
+export function listPolicySpecs() {
+    return Object.values(POLICY_CATALOGUE);
+}

package/lib/types/agentspecs.d.ts

@@ -226,6 +226,49 @@ export interface HarnessAcpSpec {
  * one beside `pydantic-ai` and `vercel-ai`; the Datalayer runtime serves it
  * through its ACP adapter, `ACPAgent` (SHIELD SH-10), never the browser.
  */
+/**
+ * A Shield policy document the platform ships or shows (`agentspecs/policies`,
+ * SHIELD.md SH-50): the catalogue's fields around a document of
+ * `@datalayer/agent-shield`'s `Policy`, whose schema agentspecs carries verbatim.
+ */
+export interface PolicySpec {
+    id: string;
+    version: string;
+    name: string;
+    description: string;
+    enabled: boolean;
+    tags: string[];
+    /** The Shield's document: scope, version, rules, limits, network, mcp, harnesses. */
+    policy: {
+        scope: 'organization' | 'team' | 'session';
+        version?: number;
+        expires?: string | null;
+        rules?: Array<{
+            name: string;
+            decision: 'allow' | 'ask' | 'deny';
+            classes?: string[];
+            kinds?: string[];
+            where?: 'inside' | 'outside' | 'any';
+            paths?: string[];
+            commands?: string[];
+            reason?: string | null;
+        }>;
+        limits?: Record<string, {
+            soft: number;
+            hard: number;
+        } | null>;
+        network?: {
+            fetch?: string[];
+        };
+        mcp?: {
+            allow?: string[];
+        };
+        harnesses?: {
+            admit?: string[];
+            credentials?: 'account' | 'platform' | 'either';
+        };
+    };
+}
 export interface HarnessSpec {
     /** What `harness:` names (e.g. 'claude-code'). */
     id: string;

package/package.json

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

package/scripts/codegen/generate_agents.py

@@ -1782,6 +1782,7 @@ export * from './protocols';
 export * from './frames';
 export * from './cogs';
 export * from './harnesses';
+export * from './policies';
 export * from './guards';
 export * from './gates';
 export * from './tracks';

package/scripts/codegen/generate_policies.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+Generate Python and TypeScript code from the YAML policy specifications.
+
+One YAML per policy under ``agentspecs/policies`` (SHIELD.md SH-50, §6.7):
+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
+it here before it is written out.
+
+Usage:
+    python generate_policies.py \\
+      --specs-dir agentspecs/agentspecs/policies \\
+      --python-output agent_runtimes/specs/policies.py \\
+      --typescript-output src/specs/policies.ts
+"""
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import yaml
+from versioning import ensure_spec_version, version_suffix
+
+SHIELD_SCHEMA = "shield-policy.schema.json"
+
+
+def load_policy_specs(specs_dir: Path) -> list[dict[str, Any]]:
+    """Every policy spec of a directory, each named for its id, its document valid."""
+    validator = jsonschema.Draft202012Validator(
+        json.loads((specs_dir / SHIELD_SCHEMA).read_text())
+    )
+    specs = []
+    for yaml_file in sorted(specs_dir.glob("*.yaml")):
+        spec = yaml.safe_load(yaml_file.read_text()) or {}
+        ensure_spec_version(spec)
+        if spec["id"] != yaml_file.stem:
+            raise ValueError(
+                f"{yaml_file.name}: the file is named for {yaml_file.stem!r}, the spec says {spec['id']!r}"
+            )
+        problems = sorted(
+            validator.iter_errors(spec.get("policy")),
+            key=lambda e: list(e.absolute_path),
+        )
+        if problems:
+            where = (
+                ".".join(str(part) for part in problems[0].absolute_path)
+                or "the document"
+            )
+            raise ValueError(
+                f"{yaml_file.name}: policy: {where}: {problems[0].message}"
+            )
+        specs.append(spec)
+    return specs
+
+
+def _const(spec: dict[str, Any]) -> str:
+    return (
+        spec["id"].replace("-", "_").upper()
+        + "_POLICY"
+        + version_suffix(spec["version"])
+    )
+
+
+def _s(value: Any) -> str:
+    return json.dumps(" ".join(str(value or "").split()), ensure_ascii=False)
+
+
+def generate_python_code(specs: list[dict[str, Any]]) -> str:
+    lines = [
+        "# Copyright (c) 2025-2026 Datalayer, Inc.",
+        "# Distributed under the terms of the Modified BSD License.",
+        '"""',
+        "Policy Catalog.",
+        "",
+        "The Shield's policy documents the platform ships or shows (SHIELD.md SH-50):",
+        "each a catalogue entry whose ``policy`` is a document of ``agent_shield.policy``.",
+        "",
+        "This file is AUTO-GENERATED from YAML specifications.",
+        "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        '"""',
+        "",
+        "from typing import Any, Dict, List, Optional",
+        "",
+        "from agent_runtimes.types import PolicySpec",
+    ]
+    for spec in specs:
+        lines += [
+            "",
+            f"{_const(spec)} = PolicySpec(",
+            f"    id={_s(spec['id'])},",
+            f"    version={_s(spec['version'])},",
+            f"    name={_s(spec['name'])},",
+            f"    description={_s(spec.get('description'))},",
+            f"    enabled={bool(spec.get('enabled', True))},",
+            f"    tags={json.dumps(list(spec.get('tags') or []))},",
+            f"    policy={json.dumps(spec['policy'], ensure_ascii=False, indent=8).replace('true', 'True').replace('false', 'False').replace('null', 'None')},",
+            ")",
+        ]
+    lines += [
+        "",
+        "",
+        "POLICY_CATALOGUE: Dict[str, PolicySpec] = {",
+        *[f"    {_s(spec['id'])}: {_const(spec)}," for spec in specs],
+        "}",
+        "",
+        "",
+        "def get_policy(policy_id: str) -> Optional[PolicySpec]:",
+        '    """A policy by id, or None."""',
+        "    return POLICY_CATALOGUE.get(policy_id)",
+        "",
+        "",
+        "def list_policies() -> List[PolicySpec]:",
+        '    """Every policy of the catalogue."""',
+        "    return list(POLICY_CATALOGUE.values())",
+        "",
+        "",
+        "def policy_documents() -> Dict[str, Dict[str, Any]]:",
+        '    """Each policy\'s Shield document, by id."""',
+        "    return {key: dict(spec.policy) for key, spec in POLICY_CATALOGUE.items()}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _t(value: Any) -> str:
+    return json.dumps(" ".join(str(value or "").split()), ensure_ascii=False)
+
+
+def _ts_value(value: Any, indent: int = 2) -> str:
+    text = json.dumps(value, ensure_ascii=False, indent=2)
+    pad = " " * indent
+    return "\n".join(
+        pad + line if i else line for i, line in enumerate(text.splitlines())
+    )
+
+
+def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
+    lines = [
+        "/*",
+        " * Copyright (c) 2025-2026 Datalayer, Inc.",
+        " * Distributed under the terms of the Modified BSD License.",
+        " */",
+        "",
+        "/**",
+        " * Policy Catalog.",
+        " *",
+        " * The Shield's policy documents the platform ships or shows (SHIELD.md SH-50).",
+        " *",
+        " * This file is AUTO-GENERATED from YAML specifications.",
+        " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        " */",
+        "",
+        "import type { PolicySpec } from '../types/agentspecs';",
+    ]
+    for spec in specs:
+        lines += [
+            "",
+            f"export const {_const(spec)}: PolicySpec = {{",
+            f"  id: {_t(spec['id'])},",
+            f"  version: {_t(spec['version'])},",
+            f"  name: {_t(spec['name'])},",
+            f"  description: {_t(spec.get('description'))},",
+            f"  enabled: {'true' if spec.get('enabled', True) else 'false'},",
+            f"  tags: {json.dumps(list(spec.get('tags') or []))},",
+            f"  policy: {_ts_value(spec['policy'])},",
+            "};",
+        ]
+    lines += [
+        "",
+        "export const POLICY_CATALOGUE: Record<string, PolicySpec> = {",
+        *[f"  {_t(spec['id'])}: {_const(spec)}," for spec in specs],
+        "};",
+        "",
+        "/** A policy by id. */",
+        "export function getPolicy(policyId: string): PolicySpec | undefined {",
+        "  return POLICY_CATALOGUE[policyId];",
+        "}",
+        "",
+        "/** Every policy of the catalogue. */",
+        "export function listPolicySpecs(): PolicySpec[] {",
+        "  return Object.values(POLICY_CATALOGUE);",
+        "}",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--specs-dir", type=Path, required=True)
+    parser.add_argument("--python-output", type=Path, required=True)
+    parser.add_argument("--typescript-output", type=Path, required=True)
+    args = parser.parse_args()
+    specs = load_policy_specs(args.specs_dir)
+    args.python_output.write_text(generate_python_code(specs))
+    args.typescript_output.write_text(generate_typescript_code(specs))
+    print(
+        f"Generated {len(specs)} policies: {args.python_output}, {args.typescript_output}"
+    )
+
+
+if __name__ == "__main__":
+    main()