@datalayer/agent-runtimes 1.3.84 → 1.3.85

package/lib/components/a2ui/custom/sandbox.js

@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The frame a component its developer wrote is drawn in (LOOP P-17), and
+ * what passes between it and the page.
+ *
+ * A hosted application lives on the origin where people are signed in, and
+ * no script an application supplies reaches that page (LOOP D-22). A custom
+ * component's module is such a script, so it never runs in the page: it runs
+ * in an `<iframe sandbox="allow-scripts">` — no `allow-same-origin`, so the
+ * frame has an origin of its own that is no one's: no cookie, no storage, no
+ * access to the page, its DOM or its tokens — whose document allows nothing
+ * but its own bootstrap and the module it is handed (`default-src 'none'`):
+ * no request leaves the frame, no form, no navigation of the page.
+ *
+ * The page fetches the module — without credentials — checks it against the
+ * hash it was reviewed with when the spec gives one (`integrity`), and hands
+ * its text to the frame, which imports it from a `blob:` address. Its
+ * default export draws it: `export default function (root, {props, send})`,
+ * returning `{update(props)}` to be told of new properties. What it is given
+ * is its properties and what it shows; what it gives back is what it sends,
+ * by name, each refused unless declared.
+ *
+ * @module components/a2ui/custom/sandbox
+ */
+/** What the frame of a custom component may do: run scripts, nothing else. */
+export const CUSTOM_FRAME_SANDBOX = 'allow-scripts';
+/** The largest module the page hands to a frame, in bytes. */
+export const MAX_MODULE_BYTES = 2 * 1024 * 1024;
+/** The tag every message between the page and a frame carries. */
+export const FRAME_TAG = 'loop.component';
+/** The policy of the frame's document: its bootstrap, the module it is handed, nothing else. */
+export function customFramePolicy(nonce) {
+    return [
+        "default-src 'none'",
+        `script-src 'nonce-${nonce}' blob:`,
+        "style-src 'unsafe-inline'",
+        'img-src data: blob:',
+        'font-src data:',
+        'media-src data: blob:',
+        "form-action 'none'",
+        "base-uri 'none'",
+    ].join('; ');
+}
+/** A nonce for one frame's bootstrap. */
+export function frameNonce() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * The document of a custom component's frame (its `srcdoc`): the policy,
+ * the root it draws into, and the bootstrap that imports the module it is
+ * handed and passes properties in and what it sends out.
+ */
+export function customFrameDocument(nonce, label) {
+    const escaped = label.replace(/[&<>"]/g, char => `&#${char.charCodeAt(0)};`);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="${customFramePolicy(nonce)}">
+<title>${escaped}</title>
+<style>html,body{margin:0;padding:0;background:transparent;color-scheme:light dark;font-family:system-ui,-apple-system,sans-serif}#root{box-sizing:border-box;min-height:100vh}</style>
+</head>
+<body>
+<div id="root"></div>
+<script nonce="${nonce}">
+(() => {
+  const TAG = ${JSON.stringify(FRAME_TAG)};
+  const root = document.getElementById('root');
+  let props = {};
+  let drawn = null;
+  let started = false;
+  const say = message => parent.postMessage(Object.assign({ tag: TAG }, message), '*');
+  const send = (name, value) => say({ kind: 'send', name: String(name), value: value });
+  addEventListener('message', async event => {
+    if (event.source !== parent) return;
+    const data = event.data;
+    if (!data || data.tag !== TAG) return;
+    if (data.kind === 'props') {
+      props = data.props || {};
+      if (drawn && typeof drawn.update === 'function') drawn.update(props);
+      return;
+    }
+    if (data.kind !== 'module' || started) return;
+    started = true;
+    try {
+      const url = URL.createObjectURL(new Blob([data.code], { type: 'text/javascript' }));
+      const module = await import(url);
+      URL.revokeObjectURL(url);
+      if (typeof module.default !== 'function') {
+        throw new Error('its module has no default export that draws it');
+      }
+      drawn = (await module.default(root, { props: props, send: send })) || {};
+      say({ kind: 'drawn' });
+    } catch (error) {
+      say({ kind: 'failed', message: String((error && error.message) || error) });
+    }
+  });
+  say({ kind: 'ready' });
+})();
+</script>
+</body>
+</html>`;
+}
+/** What a frame said, when it is a message of the frame drawn here; null otherwise. */
+export function fromFrame(event, frame) {
+    if (!frame || event.source !== frame) {
+        return null;
+    }
+    const data = event.data;
+    if (!data || typeof data !== 'object' || data.tag !== FRAME_TAG) {
+        return null;
+    }
+    switch (data.kind) {
+        case 'ready':
+        case 'drawn':
+            return { kind: data.kind };
+        case 'failed':
+            return { kind: 'failed', message: String(data.message ?? '') };
+        case 'send':
+            return typeof data.name === 'string'
+                ? { kind: 'send', name: data.name, value: data.value }
+                : null;
+        default:
+            return null;
+    }
+}
+const ALGORITHMS = {
+    sha256: 'SHA-256',
+    sha384: 'SHA-384',
+    sha512: 'SHA-512',
+};
+function base64(bytes) {
+    let binary = '';
+    for (const byte of new Uint8Array(bytes)) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/** Whether a module's bytes are the ones its Subresource Integrity hash names. */
+export async function integrityHolds(bytes, integrity) {
+    const at = integrity.indexOf('-');
+    const algorithm = ALGORITHMS[integrity.slice(0, at)];
+    if (at < 0 || !algorithm) {
+        return false;
+    }
+    const digest = await crypto.subtle.digest(algorithm, bytes);
+    return base64(digest) === integrity.slice(at + 1);
+}
+/** The modules fetched, by address and hash: each fetched once per page. */
+const MODULES = new Map();
+/**
+ * The text of a custom component's module, fetched without credentials and
+ * checked against its hash when one is given. It throws, with a sentence,
+ * for a module that cannot be fetched, is too large, or is not the one
+ * reviewed.
+ */
+export function customModule(source, integrity, fetcher = fetch) {
+    const key = `${source}\n${integrity}`;
+    let module = MODULES.get(key);
+    if (!module) {
+        module = (async () => {
+            const response = await fetcher(source, {
+                credentials: 'omit',
+                mode: 'cors',
+            });
+            if (!response.ok) {
+                throw new Error(`Its module could not be fetched from ${source} (${response.status}).`);
+            }
+            const bytes = await response.arrayBuffer();
+            if (bytes.byteLength > MAX_MODULE_BYTES) {
+                throw new Error(`Its module is larger than ${MAX_MODULE_BYTES / 1024 / 1024} MB.`);
+            }
+            if (integrity && !(await integrityHolds(bytes, integrity))) {
+                throw new Error('Its module is not the one reviewed: its hash differs from its integrity.');
+            }
+            return new TextDecoder().decode(bytes);
+        })();
+        // A failure is not kept: the next drawing tries again.
+        module.catch(() => MODULES.delete(key));
+        MODULES.set(key, module);
+    }
+    return module;
+}

package/lib/components/a2ui/datalayer/index.d.ts

@@ -14,7 +14,7 @@ import type { ReactComponentImplementation } from '@a2ui/react/v0_9';
  * a renderer for one it no longer has, fails at once.
  */
 export declare const OWN_COMPONENTS: ReactComponentImplementation[];
-export { OWN_COMPONENT_IDS, ownComponentSchema } from './schema';
+export { OWN_COMPONENT_IDS, componentSchemaOf, ownComponentSchema, } from './schema';
 export { DRAWN_OWN_COMPONENTS, type DrawnOwnComponent } from './drawn';
 export { chartOption, chartPoints, chartSeries } from './Chart';
 export { chatItems } from './Chat';

package/lib/components/a2ui/datalayer/index.js

@@ -35,7 +35,7 @@ export const OWN_COMPONENTS = (() => {
     }
     return OWN_COMPONENT_IDS.map(id => RENDERERS[id]);
 })();
-export { OWN_COMPONENT_IDS, ownComponentSchema } from './schema';
+export { OWN_COMPONENT_IDS, componentSchemaOf, ownComponentSchema, } from './schema';
 export { DRAWN_OWN_COMPONENTS } from './drawn';
 export { chartOption, chartPoints, chartSeries } from './Chart';
 export { chatItems } from './Chat';

package/lib/components/a2ui/datalayer/schema.d.ts

@@ -32,3 +32,13 @@ export declare function ownComponentSchema(id: string): z.ZodObject<Record<strin
 }, {
     [x: string]: any;
 }>;
+/**
+ * The A2UI schema of a component of Datalayer's own kind, from its entry in
+ * the catalog — one of Datalayer's own, or one an application's developer
+ * wrote (LOOP P-17), listed as the catalog lists a component.
+ */
+export declare function componentSchemaOf(component: ComponentSpec): z.ZodObject<Record<string, z.ZodTypeAny>, "strict", z.ZodTypeAny, {
+    [x: string]: any;
+}, {
+    [x: string]: any;
+}>;

package/lib/components/a2ui/datalayer/schema.js

@@ -83,7 +83,18 @@ export function bindingNames(component) {
  * catalog's are: a key it does not declare refuses the tree.
  */
 export function ownComponentSchema(id) {
-    const component = ownComponent(id);
+    return componentSchemaOf(ownComponent(id));
+}
+/**
+ * The A2UI schema of a component of Datalayer's own kind, from its entry in
+ * the catalog — one of Datalayer's own, or one an application's developer
+ * wrote (LOOP P-17), listed as the catalog lists a component.
+ */
+export function componentSchemaOf(component) {
+    const id = component.id;
+    if (!component.bindings) {
+        throw new Error(`${id} says nothing of what it shows or sends.`);
+    }
     const json = component.properties;
     const required = new Set(json.required ?? []);
     const shape = {};

package/lib/components/a2ui/index.d.ts

@@ -4,3 +4,4 @@ export * from './styles';
 export * from './visibleWhen';
 export * from './visibility';
 export * from './datalayer';
+export * from './custom';

package/lib/components/a2ui/index.js

@@ -8,3 +8,4 @@ export * from './styles';
 export * from './visibleWhen';
 export * from './visibility';
 export * from './datalayer';
+export * from './custom';

package/lib/components/a2ui/visibleWhen.d.ts

@@ -22,5 +22,16 @@ export declare const datalayerCatalog: Catalog<ReactComponentImplementation, imp
  * plugins contribute as blocks (LOOP R-01b, `loop.canvas.block`), so that an
  * application's page draws what its Canvas can place and nothing else. Under
  * the same id; a name the catalog does not draw is an error.
+ *
+ * `own` are the renderers of the components the application's developer
+ * wrote (LOOP P-17, `customImplementations`): drawn for that application's
+ * page alone, each behind `visible_when` as the catalog's are. One that
+ * takes the name of a component of the catalog is an error.
  */
-export declare function catalogOfBlocks(names: readonly string[]): Catalog<ReactComponentImplementation>;
+export declare function catalogOfBlocks(names: readonly string[], own?: readonly ReactComponentImplementation[]): Catalog<ReactComponentImplementation>;
+/**
+ * Datalayer's whole catalog with the components an application's developer
+ * wrote (LOOP P-17): what its answers and the elements its code shows are
+ * drawn with (P-04, P-18). Datalayer's catalog itself when it wrote none.
+ */
+export declare function catalogWithOwn(own: readonly ReactComponentImplementation[]): Catalog<ReactComponentImplementation>;

package/lib/components/a2ui/visibleWhen.js

@@ -60,11 +60,32 @@ export const datalayerCatalog = new Catalog(basicCatalog.id, basicCatalog.protoc
  * plugins contribute as blocks (LOOP R-01b, `loop.canvas.block`), so that an
  * application's page draws what its Canvas can place and nothing else. Under
  * the same id; a name the catalog does not draw is an error.
+ *
+ * `own` are the renderers of the components the application's developer
+ * wrote (LOOP P-17, `customImplementations`): drawn for that application's
+ * page alone, each behind `visible_when` as the catalog's are. One that
+ * takes the name of a component of the catalog is an error.
  */
-export function catalogOfBlocks(names) {
-    const unknown = names.filter(name => !datalayerCatalog.components.has(name));
+export function catalogOfBlocks(names, own = []) {
+    const custom = new Map(own.map(component => [component.name, withVisibleWhen(component)]));
+    const taken = [...custom.keys()].filter(name => datalayerCatalog.components.has(name));
+    if (taken.length > 0) {
+        throw new Error(`${taken.join(', ')} ${taken.length === 1 ? 'is a component' : 'are components'} of the catalog: a component of an application's own is named otherwise.`);
+    }
+    const unknown = names.filter(name => !datalayerCatalog.components.has(name) && !custom.has(name));
     if (unknown.length > 0) {
         throw new Error(`No renderer draws ${unknown.join(', ')}: a block is contributed by a plugin whose component the catalog draws.`);
     }
-    return new Catalog(datalayerCatalog.id, datalayerCatalog.protocolVersion, names.map(name => datalayerCatalog.components.get(name)), [...datalayerCatalog.functions.values()], datalayerCatalog.themeSchema, datalayerCatalog.instructions);
+    return new Catalog(datalayerCatalog.id, datalayerCatalog.protocolVersion, names.map(name => datalayerCatalog.components.get(name) ?? custom.get(name)), [...datalayerCatalog.functions.values()], datalayerCatalog.themeSchema, datalayerCatalog.instructions);
+}
+/**
+ * Datalayer's whole catalog with the components an application's developer
+ * wrote (LOOP P-17): what its answers and the elements its code shows are
+ * drawn with (P-04, P-18). Datalayer's catalog itself when it wrote none.
+ */
+export function catalogWithOwn(own) {
+    if (own.length === 0) {
+        return datalayerCatalog;
+    }
+    return catalogOfBlocks([...datalayerCatalog.components.keys(), ...own.map(each => each.name)], own);
 }

package/lib/components/inspector/AgentInspector.d.ts

@@ -1,59 +1,40 @@
 /**
- * The Agent Inspector: what agents do, one row a thing, newest last — the
- * time (to the millisecond, and since the first), who did it and toward
- * whom, its source and kind, its name with its mark, its status and
- * duration, and a line that says it. A row unfolds to its payload as a JSON
- * tree (a call's arguments and its result), and to what was made of it.
+ * The Agent Inspector: what agents do, as the OpenTelemetry spans the page
+ * records (`agentSpans`, `chatSpans`, `a2aSpans`), drawn by core's OTEL view
+ * (`OtelLiveSpans`): each turn a trace, its tool calls and its A2A requests
+ * under it, newest last; a span opens to its attributes (a call's arguments
+ * and result, a request whole), its events (what the peer answered, event by
+ * event) and its trace tree.
  *
- * Filters by source, kind and actor; *Pause* holds the rows still while the
- * record goes on, *Clear* empties it, *Export* saves the session as JSON. A
- * large payload (a notebook) says its size and stays folded until asked.
- *
- * Fed by a sink (`useAgentInspector`) or given its entries.
+ * One agent's own (`agent`): what it did, and what was sent to it — one A2A
+ * request shows in the asker's and in the peer's. Filters by source (A2A,
+ * MCP, frontend tool, skill, codemode, runtime tool, model), operation and
+ * agent; *Pause*, *Clear*, *Export* as the OTEL view has them.
  *
  * @module components/inspector/AgentInspector
  */
 import type { JSX } from 'react';
-import { type AgentInspectorEntry, type AgentInspectorExport, type AgentInspectorSink, type AgentInspectorSource } from './agentInspector';
+import type { OtelLiveTracer } from '@datalayer/core/lib/otel/live';
+import type { OtelSpan } from '@datalayer/core/lib/otel/types';
+import { type OtelSpanFacet } from '@datalayer/core/lib/otel/views/OtelLiveSpans';
 export type AgentInspectorProps = {
     /** The record to show, kept current. */
-    sink?: AgentInspectorSink | null;
-    /** Or its entries, as given. */
-    entries?: readonly AgentInspectorEntry[];
-    /** How tall the rows grow before they scroll. */
+    tracer?: OtelLiveTracer | null;
+    /** Or its spans, as given. */
+    spans?: readonly OtelSpan[];
+    /** One agent's own record: what it did, and what was sent to it. */
+    agent?: string;
+    /** How tall the list grows before it scrolls. */
     maxHeight?: number | string;
-    /** Payloads larger than this, in bytes, stay folded until asked. */
-    largeBytes?: number;
+    /** Narrower, the detail under the list: beside other content. */
+    compact?: boolean;
     /** What is said while nothing is recorded. */
     emptyText?: string;
-    /** The file name the session is exported as, without `.json`. */
+    /** The file the spans are exported as, without `.json`. */
     exportName?: string;
-    /**
-     * One agent's own record: what it did (`actor`), and the A2A messages it
-     * sent or received — one message shows in the sender's and in the
-     * receiver's, the same entry, as sent in one and received in the other.
-     */
-    agent?: string;
-};
-/** Whether an entry is one agent's: done by it, or sent to or by it. */
-export declare function isAgentsEntry(entry: AgentInspectorEntry, agent: string): boolean;
-/** Which way an entry went, from one agent's side: `→ Accounting`, `← Accounting`. */
-export declare function directionFrom(entry: AgentInspectorEntry, agent: string | undefined): string;
-/** A time of day, to the millisecond: `15:44:31.299`. */
-export declare function clockTime(at: number): string;
-/** Time since the first entry: `+1.204s`. */
-export declare function sinceFirst(at: number, first: number): string;
-/** How long a call took: `412 ms`, `3.4 s`. */
-export declare function durationText(ms: number): string;
-export type AgentInspectorFilter = {
-    sources: ReadonlySet<AgentInspectorSource>;
-    kinds: ReadonlySet<string>;
-    actors: ReadonlySet<string>;
 };
-/** The entries a filter keeps: an empty set keeps every value. */
-export declare function filterEntries(entries: readonly AgentInspectorEntry[], filter: AgentInspectorFilter): AgentInspectorEntry[];
-/** A session, as JSON. */
-export declare function exportEntries(entries: readonly AgentInspectorEntry[]): AgentInspectorExport;
+/** The Inspector's filters: where a span comes from, what it does, which agent. */
+export declare const AGENT_INSPECTOR_FACETS: readonly OtelSpanFacet[];
 /** The Agent Inspector. */
-export declare function AgentInspector({ sink, entries: given, maxHeight, largeBytes, emptyText, exportName, agent, }: AgentInspectorProps): JSX.Element;
+export declare function AgentInspector({ tracer, spans, agent, maxHeight, compact, emptyText, exportName, }: AgentInspectorProps): JSX.Element;
 export default AgentInspector;