@datalayer/agent-runtimes 1.5.41 → 1.5.42

package/lib/examples/ShieldPolicyExample.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The Shield's policy, from TypeScript (SHIELD §5.1, SH-53; SH-23).
+ *
+ * An organization's document typed by `@datalayer/agent-shield` (the types
+ * generated from the schema the Python package publishes), what it decides
+ * for each class, how ACP's tool kinds are classed, the limits soft then
+ * hard, and decisions in the words `describeDecision` gives every card and
+ * row. Needs nothing running: it reads the package only.
+ *
+ * `@datalayer/agent-shield` is not on npm yet: the page reads it from the
+ * sibling checkout `ai/agent-shield` beside agent-runtimes (see
+ * `shield/shieldPolicyDemo`), and says so where it is not there.
+ *
+ * @module examples/ShieldPolicyExample
+ */
+import React from 'react';
+declare const ShieldPolicyExample: React.FC;
+export default ShieldPolicyExample;

package/lib/examples/ShieldPolicyExample.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The Shield's policy, from TypeScript (SHIELD §5.1, SH-53; SH-23).
+ *
+ * An organization's document typed by `@datalayer/agent-shield` (the types
+ * generated from the schema the Python package publishes), what it decides
+ * for each class, how ACP's tool kinds are classed, the limits soft then
+ * hard, and decisions in the words `describeDecision` gives every card and
+ * row. Needs nothing running: it reads the package only.
+ *
+ * `@datalayer/agent-shield` is not on npm yet: the page reads it from the
+ * sibling checkout `ai/agent-shield` beside agent-runtimes (see
+ * `shield/shieldPolicyDemo`), and says so where it is not there.
+ *
+ * @module examples/ShieldPolicyExample
+ */
+import { useEffect, useState } from 'react';
+import { Heading, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { AGENT_SHIELD_MISSING, ORGANIZATION_POLICY, classRows, decisionRows, kindRows, limitRows, loadAgentShield, } from './shield/shieldPolicyDemo';
+const cell = {
+    borderBottom: '1px solid',
+    borderColor: 'border.muted',
+    py: 1,
+    pr: 3,
+};
+function Table({ head, rows, }) {
+    return (_jsxs(Box, { as: "table", sx: { borderCollapse: 'collapse', fontSize: 1, mb: 4 }, children: [_jsx("thead", { children: _jsx("tr", { children: head.map(title => (_jsx(Box, { as: "th", sx: { ...cell, textAlign: 'left' }, children: title }, title))) }) }), _jsx("tbody", { children: rows.map(row => (_jsx("tr", { children: row.map((value, index) => (_jsx(Box, { as: "td", sx: cell, children: value }, index))) }, row.join('|')))) })] }));
+}
+function Tables({ shield, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: "By class" }), _jsx(Table, { head: ['Class', `The ${ORGANIZATION_POLICY.scope}'s document says`], rows: classRows(shield).map(row => [row.actionClass, row.says]) }), _jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: "A coding agent's tool kinds" }), _jsx(Table, { head: ['ACP kind', 'Decided as'], rows: kindRows(shield).map(row => [row.kind, row.actionClass]) }), _jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: "Limits, soft then hard" }), _jsx(Table, { head: ['Limit', 'Soft: asks once', 'Hard: refuses'], rows: limitRows(shield).map(row => [row.limit, row.soft, row.hard]) }), _jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 2 }, children: "Decisions, in their words" }), _jsx(Table, { head: ['The Shield said', 'describeDecision'], rows: decisionRows(shield).map(row => [row.sentence, row.words]) })] }));
+}
+const ShieldPolicyExample = () => {
+    // `undefined` while reading, `null` without the sibling checkout.
+    const [shield, setShield] = useState(undefined);
+    useEffect(() => {
+        let live = true;
+        void loadAgentShield().then(loaded => live && setShield(loaded));
+        return () => {
+            live = false;
+        };
+    }, []);
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { p: 4, maxWidth: "900px", mx: "auto", "data-testid": "shield-policy-example", children: [_jsx(Heading, { as: "h1", sx: { fontSize: 4, mb: 2 }, children: "The Shield's policy, typed" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mb: 4 }, children: "An organization's document in `@datalayer/agent-shield`'s shape, and what it decides. Three levels decide every action \u2014 the organization's, the application's, the session's \u2014 strictest first; a lower level only tightens." }), shield === undefined ? (_jsx(Text, { as: "p", children: "Reading @datalayer/agent-shield\u2026" })) : shield === null ? (_jsx(Text, { as: "p", sx: { color: 'attention.fg' }, children: AGENT_SHIELD_MISSING })) : (_jsx(Tables, { shield: shield }))] }) }));
+};
+export default ShieldPolicyExample;

package/lib/examples/example-selector.js

@@ -133,6 +133,9 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('AgentA2ATeamExample', () => import('./AgentA2ATeamExample'), 'Two applications as a team over A2A: Sales in the browser (@a2a-js/sdk) asks Accounting on a runtime (fasta2a, Odoo read only), each an Office Assistant character.'),
     makeEntry('ProtocolSignedRequestsExample', () => import('./ProtocolSignedRequestsExample'), 'Web Bot Auth in the browser: a key made in the page signs a request — its three headers and the signature base — verified, then a replay and a changed path refused.'),
     makeEntry('ProtocolUcpCheckoutExample', () => import('./ProtocolUcpCheckoutExample'), 'A UCP checkout at a test store in the page: the exact purchase proposed, approved on a card once, bought once.'),
+    // The Shield (SHIELD.md SH-23): a coding agent behind it, and its policy's types.
+    makeEntry('ShieldHarnessExample', () => import('./ShieldHarnessExample'), 'A coding agent behind the Shield in the web chat: its changes as diffs, its commands as terminals, what a rule asks first in the approval banner. Needs `python examples/shield/harness_on_the_runtime.py --serve` (the fake agent, no key).', ['example', 'shield', 'harness', 'acp', 'ag-ui', 'chat']),
+    makeEntry('ShieldPolicyExample', () => import('./ShieldPolicyExample'), 'The Shield’s policy from TypeScript: an organization’s document typed by @datalayer/agent-shield, what it decides by class, the tool kinds classed, the limits soft then hard, decisions in describeDecision’s words.', ['example', 'shield', 'policy']),
     makeEntry('PapCompanyDiscoveryExample', () => import('./PapCompanyDiscoveryExample'), 'Validate a PAP company document and reduce it to the public capabilities safe for an agent or UI.'),
     makeEntry('PapAgentIdentityExample', () => import('./PapAgentIdentityExample'), 'Verify personal-agent client metadata and signing policy without exposing JWK coordinates.'),
     makeEntry('PapAuthorizationBoundaryExample', () => import('./PapAuthorizationBoundaryExample'), 'Generate real Session and Direct Sign-In security material while showing only safe policy status.'),

package/lib/examples/exampleGroups.d.ts

@@ -5,5 +5,5 @@
  *
  * @module examples/exampleGroups
  */
-export declare const EXAMPLE_GROUP_ORDER: readonly ["Apps", "Assistant", "A2UI", "A2A", "Personal Agent Protocol", "Agent protocols", "AG-UI", "Chat", "Document", "Notebook", "Capabilities", "Cell", "CopilotKit"];
+export declare const EXAMPLE_GROUP_ORDER: readonly ["Apps", "Assistant", "A2UI", "A2A", "Personal Agent Protocol", "Agent protocols", "Shield", "AG-UI", "Chat", "Document", "Notebook", "Capabilities", "Cell", "CopilotKit"];
 export declare const getExampleGroup: (id: string) => string;

package/lib/examples/exampleGroups.js

@@ -16,6 +16,7 @@ export const EXAMPLE_GROUP_ORDER = [
     'A2A',
     'Personal Agent Protocol',
     'Agent protocols',
+    'Shield',
     'AG-UI',
     'Chat',
     'Document',
@@ -43,6 +44,9 @@ export const getExampleGroup = (id) => {
     // The other agent protocols' examples: signed requests, commerce (AGENT_PROTOCOLS EX-10).
     if (id.startsWith('Protocol'))
         return 'Agent protocols';
+    // The Shield: a coding agent behind it, and its policy (SHIELD.md SH-23).
+    if (id.startsWith('Shield'))
+        return 'Shield';
     if (id.startsWith('AgUi'))
         return 'AG-UI';
     if (id.startsWith('CopilotKit'))

package/lib/examples/shield/shieldHarness.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What `ShieldHarnessExample` connects to and offers (SHIELD SH-23).
+ *
+ * `examples/shield/harness_on_the_runtime.py --serve` names the harness's
+ * agent `chat`, as `loop --harness` does with `AGENT_RUNTIMES_AGENT_NAME`;
+ * the openers are the fake agent's words (its docstring says what each does).
+ *
+ * @module examples/shield/shieldHarness
+ */
+import type { Suggestion } from '../../types/chat';
+/** The agent the local runtime serves the harness as. */
+export declare const SHIELD_HARNESS_AGENT = "chat";
+/** What to ask the fake agent: one of each decision. */
+export declare const SHIELD_HARNESS_OPENERS: Suggestion[];

package/lib/examples/shield/shieldHarness.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The agent the local runtime serves the harness as. */
+export const SHIELD_HARNESS_AGENT = 'chat';
+/** What to ask the fake agent: one of each decision. */
+export const SHIELD_HARNESS_OPENERS = [
+    {
+        title: 'Edit a file',
+        message: 'edit and read README.md',
+    },
+    {
+        title: 'Run a command',
+        message: 'run echo hello',
+    },
+    {
+        title: 'Read outside the workspace',
+        message: 'outside',
+    },
+];

package/lib/examples/shield/shieldPolicyDemo.d.ts

@@ -0,0 +1,85 @@
+/**
+ * What `ShieldPolicyExample` draws, as data (SHIELD §5.1, SH-53; SH-23).
+ *
+ * `@datalayer/agent-shield` is the Shield's TypeScript: the policy
+ * document's types generated from the schema the Python package publishes,
+ * the classes and the verdicts, ACP's tool kinds mapped to the classes, the
+ * limits' words, and `describeDecision` — the one place a decision's words
+ * are written. It is not on npm yet (npm's latest is an old scaffold), so
+ * agent-runtimes does not depend on it: this page reads it from the sibling
+ * checkout, `ai/agent-shield/src/policy.ts` beside `ai/agent-runtimes`, the
+ * way the monorepo lays them out — through Vite's `import.meta.glob`, which
+ * finds nothing (and the page says so) where the sibling is not there, as in
+ * agent-runtimes' own CI. The shapes below name only what the page reads;
+ * the types themselves are the package's.
+ *
+ * @module examples/shield/shieldPolicyDemo
+ */
+export type Verdict = 'allow' | 'ask' | 'deny';
+/** A decision as the Shield returns it (the package's `Decision`). */
+export type Decision = {
+    verdict: Verdict;
+    sentence: string;
+    scope?: 'organization' | 'team' | 'session' | null;
+    rule?: string | null;
+    decided_by: 'rule' | 'limit' | 'network' | 'default';
+};
+/** The part of a policy document the page draws (the package's `Policy`). */
+export type PolicyDocument = {
+    scope: 'organization' | 'team' | 'session';
+    rules?: Array<{
+        name: string;
+        decision: Verdict;
+        classes?: string[];
+        commands?: string[];
+        where?: 'inside' | 'outside' | 'any';
+        reason?: string;
+    }>;
+    limits?: Record<string, {
+        soft: number;
+        hard: number;
+    } | null | undefined>;
+    harnesses?: {
+        admit?: string[];
+        credentials?: 'account' | 'platform' | 'either';
+    };
+};
+/** What the page reads from `@datalayer/agent-shield`'s `policy.ts`. */
+export type AgentShieldPolicyModule = {
+    ACTION_CLASSES: readonly string[];
+    TOOL_KINDS: readonly string[];
+    KIND_CLASS: Record<string, string | null>;
+    LIMIT_NAMES: readonly string[];
+    LIMIT_WORDS: Record<string, string>;
+    VERDICT_WORDS: Record<Verdict, string>;
+    describeDecision: (decision: Decision) => string;
+};
+/** What the page says when the sibling checkout is not beside this one. */
+export declare const AGENT_SHIELD_MISSING = "This page reads @datalayer/agent-shield from the sibling checkout ai/agent-shield, which is not beside this one: clone github.com/datalayer/agent-shield next to agent-runtimes (the package is not on npm yet).";
+/** `@datalayer/agent-shield`'s policy module, or `null` without the sibling checkout. */
+export declare function loadAgentShield(): Promise<AgentShieldPolicyModule | null>;
+/** An organization's document, in the package's shape: what an administrator writes. */
+export declare const ORGANIZATION_POLICY: PolicyDocument;
+/** One row per class: what the organization's document decides for it, in words. */
+export declare function classRows(shield: AgentShieldPolicyModule, policy?: PolicyDocument): Array<{
+    actionClass: string;
+    says: string;
+}>;
+/** ACP's tool kinds and the class each is decided as (§4.5). */
+export declare function kindRows(shield: AgentShieldPolicyModule): Array<{
+    kind: string;
+    actionClass: string;
+}>;
+/** The limits a document sets, soft then hard, in the sentences' words. */
+export declare function limitRows(shield: AgentShieldPolicyModule, policy?: PolicyDocument): Array<{
+    limit: string;
+    soft: string;
+    hard: string;
+}>;
+/** Decisions as the Shield returns them. */
+export declare const DECISIONS: Decision[];
+/** Each decision and its words through `describeDecision`. */
+export declare function decisionRows(shield: AgentShieldPolicyModule): Array<{
+    sentence: string;
+    words: string;
+}>;

package/lib/examples/shield/shieldPolicyDemo.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/// <reference types="vite/client" />
+/** The sibling checkout's module, when it is there. */
+const SIBLING = import.meta.glob('../../../../agent-shield/src/policy.ts');
+/** What the page says when the sibling checkout is not beside this one. */
+export const AGENT_SHIELD_MISSING = 'This page reads @datalayer/agent-shield from the sibling checkout ai/agent-shield, which is not beside this one: clone github.com/datalayer/agent-shield next to agent-runtimes (the package is not on npm yet).';
+/** `@datalayer/agent-shield`'s policy module, or `null` without the sibling checkout. */
+export async function loadAgentShield() {
+    const load = Object.values(SIBLING)[0];
+    return load ? load() : null;
+}
+/** An organization's document, in the package's shape: what an administrator writes. */
+export const ORGANIZATION_POLICY = {
+    scope: 'organization',
+    rules: [
+        {
+            name: 'commands ask',
+            decision: 'ask',
+            classes: ['execute'],
+            reason: 'a person sees every command first',
+        },
+        {
+            name: 'nothing deleted outside',
+            decision: 'deny',
+            classes: ['delete'],
+            where: 'outside',
+        },
+        {
+            name: 'no pushes',
+            decision: 'deny',
+            commands: ['git push*'],
+        },
+    ],
+    limits: {
+        tool_calls: { soft: 200, hard: 400 },
+        model_tokens: { soft: 200000, hard: 500000 },
+        spend: { soft: 500, hard: 1000 },
+    },
+    harnesses: { admit: ['claude-code', 'codex'], credentials: 'account' },
+};
+/** One row per class: what the organization's document decides for it, in words. */
+export function classRows(shield, policy = ORGANIZATION_POLICY) {
+    return shield.ACTION_CLASSES.map(actionClass => {
+        const rule = (policy.rules ?? []).find(item => (item.classes ?? []).includes(actionClass));
+        return {
+            actionClass,
+            says: rule
+                ? `${shield.VERDICT_WORDS[rule.decision]} — '${rule.name}'${rule.where && rule.where !== 'any' ? ` (${rule.where} the workspace)` : ''}`
+                : 'nothing said: the next level decides',
+        };
+    });
+}
+/** ACP's tool kinds and the class each is decided as (§4.5). */
+export function kindRows(shield) {
+    return shield.TOOL_KINDS.map(kind => ({
+        kind,
+        actionClass: shield.KIND_CLASS[kind] ?? 'nothing to decide',
+    }));
+}
+/** The limits a document sets, soft then hard, in the sentences' words. */
+export function limitRows(shield, policy = ORGANIZATION_POLICY) {
+    return shield.LIMIT_NAMES.flatMap(name => {
+        const threshold = policy.limits?.[name];
+        return threshold
+            ? [
+                {
+                    limit: shield.LIMIT_WORDS[name],
+                    soft: String(threshold.soft),
+                    hard: String(threshold.hard),
+                },
+            ]
+            : [];
+    });
+}
+/** Decisions as the Shield returns them. */
+export const DECISIONS = [
+    {
+        verdict: 'allow',
+        sentence: 'Edit main.py: do it',
+        scope: 'session',
+        rule: 'edit and move inside the workspace',
+        decided_by: 'rule',
+    },
+    {
+        verdict: 'ask',
+        sentence: 'Run `pytest`: ask me first',
+        scope: 'organization',
+        rule: 'commands ask',
+        decided_by: 'rule',
+    },
+    {
+        verdict: 'deny',
+        sentence: 'a model request: refused',
+        scope: 'organization',
+        decided_by: 'limit',
+    },
+    {
+        verdict: 'ask',
+        sentence: 'Fetch https://example.com/: ask me first',
+        decided_by: 'default',
+    },
+];
+/** Each decision and its words through `describeDecision`. */
+export function decisionRows(shield) {
+    return DECISIONS.map(decision => ({
+        sentence: decision.sentence,
+        words: shield.describeDecision(decision),
+    }));
+}

package/lib/specs/harnesses.d.ts

@@ -6,7 +6,7 @@
  * This file is AUTO-GENERATED from YAML specifications.
  * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
  */
-import type { HarnessSpec } from '../types/agentspecs';
+import type { HarnessSpec, ListedHarness } 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;
@@ -20,3 +20,11 @@ export declare const HARNESS_CATALOGUE: Record<string, HarnessSpec>;
 export declare function getHarness(harnessId: string): HarnessSpec | undefined;
 /** Every harness of the catalogue. */
 export declare function listHarnesses(): HarnessSpec[];
+/**
+ * The register's listed tier (SH-57): agents known to speak ACP, registered
+ * with their documented command and their terms, not drilled — offered by
+ * nothing until moved to the catalogue.
+ */
+export declare const LISTED_HARNESSES: ListedHarness[];
+/** The sentence a listed harness is refused in (agentspecs' LISTED_NOT_DRILLED). */
+export declare const LISTED_NOT_DRILLED = "listed, not drilled yet";