@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/inspect/serializeValue.js

@@ -0,0 +1,149 @@
+import { isSignal, value as readSignal } from "@spearwolf/signalize";
+const SerializeDefaults = Object.freeze({
+  maxDepth: 3,
+  maxArrayLength: 20,
+  maxObjectEntries: 30,
+  maxStringLength: 200
+});
+const orDefault = (val, fallback) => val !== void 0 && Number.isFinite(val) ? val : fallback;
+const resolveSerializeLimits = (limits) => ({
+  maxDepth: orDefault(limits?.maxDepth, SerializeDefaults.maxDepth),
+  maxArrayLength: orDefault(limits?.maxArrayLength, SerializeDefaults.maxArrayLength),
+  maxObjectEntries: orDefault(limits?.maxObjectEntries, SerializeDefaults.maxObjectEntries),
+  maxStringLength: orDefault(limits?.maxStringLength, SerializeDefaults.maxStringLength)
+});
+const isDomNode = (val) => typeof val.nodeType === "number" && typeof val.nodeName === "string";
+const isPlainObject = (val) => {
+  const proto = Object.getPrototypeOf(val);
+  return proto === Object.prototype || proto === null;
+};
+const className = (val) => {
+  const ctor = val.constructor;
+  return typeof ctor === "function" && ctor.name ? ctor.name : "Object";
+};
+const errorEntry = (error) => ({
+  $type: "object",
+  class: "Error",
+  preview: { message: error instanceof Error ? error.message : String(error) }
+});
+const TRUNCATED_KEY = "$truncated";
+function serializeValue(value, limits) {
+  return new Serializer(resolveSerializeLimits(limits)).serialize(value, 0, /* @__PURE__ */ new Set());
+}
+class Serializer {
+  constructor(limits) {
+    this.limits = limits;
+  }
+  serialize(val, depth, path) {
+    switch (typeof val) {
+      case "undefined":
+        return { $type: "undefined" };
+      case "boolean":
+        return val;
+      case "number":
+        return Number.isFinite(val) ? val : String(val);
+      case "string":
+        return this.string(val);
+      case "bigint":
+        return { $type: "bigint", value: val.toString() };
+      case "symbol":
+        return val.description === void 0 ? { $type: "symbol" } : { $type: "symbol", description: val.description };
+      case "function":
+        try {
+          if (isSignal(val)) return this.signal(val, depth, path);
+          return { $type: "function", name: val.name };
+        } catch (error) {
+          return errorEntry(error);
+        }
+      case "object":
+        if (val === null) return null;
+        try {
+          if (isSignal(val)) return this.signal(val, depth, path);
+          return this.object(val, depth, path);
+        } catch (error) {
+          return errorEntry(error);
+        }
+    }
+  }
+  string(val) {
+    if (val.length <= this.limits.maxStringLength) return val;
+    return { $type: "truncated", reason: "string", original: val.length, preview: val.slice(0, this.limits.maxStringLength) };
+  }
+  signal(sig, depth, path) {
+    if (path.has(sig)) return { $type: "circular" };
+    path.add(sig);
+    try {
+      let current;
+      try {
+        current = readSignal(sig);
+      } catch (error) {
+        return errorEntry(error);
+      }
+      return { $type: "signal", value: this.serialize(current, depth, path) };
+    } finally {
+      path.delete(sig);
+    }
+  }
+  object(val, depth, path) {
+    if (val instanceof Date) return { $type: "date", iso: Number.isNaN(val.getTime()) ? "Invalid Date" : val.toISOString() };
+    if (val instanceof ArrayBuffer) return { $type: "array-buffer", byteLength: val.byteLength, class: "ArrayBuffer" };
+    if (ArrayBuffer.isView(val)) return { $type: "typed-array", byteLength: val.byteLength, class: className(val) };
+    if (isDomNode(val)) {
+      return typeof val.id === "string" && val.id ? { $type: "dom", nodeName: val.nodeName, id: val.id } : { $type: "dom", nodeName: val.nodeName };
+    }
+    if (val instanceof Error) return { $type: "object", class: className(val), preview: { name: val.name, message: val.message } };
+    if (depth > this.limits.maxDepth) return { $type: "truncated", reason: "depth" };
+    if (path.has(val)) return { $type: "circular" };
+    path.add(val);
+    try {
+      if (Array.isArray(val)) return this.array(val, depth, path);
+      if (val instanceof Map) {
+        return {
+          $type: "object",
+          class: "Map",
+          preview: { size: val.size, entries: this.array(Array.from(val.entries()), depth, path) }
+        };
+      }
+      if (val instanceof Set) {
+        return { $type: "object", class: "Set", preview: { size: val.size, entries: this.array(Array.from(val), depth, path) } };
+      }
+      if (isPlainObject(val)) return this.entries(val, depth, path);
+      return { $type: "object", class: className(val), preview: this.entries(val, depth, path) };
+    } finally {
+      path.delete(val);
+    }
+  }
+  array(val, depth, path) {
+    const out = [];
+    const max = this.limits.maxArrayLength;
+    for (let i = 0; i < val.length && i < max; i++) {
+      out.push(this.serialize(val[i], depth + 1, path));
+    }
+    if (val.length > max) out.push({ $type: "truncated", reason: "length", original: val.length });
+    return out;
+  }
+  entries(val, depth, path) {
+    const out = {};
+    const keys = Object.keys(val);
+    const max = this.limits.maxObjectEntries;
+    for (let i = 0; i < keys.length && i < max; i++) {
+      const key = keys[i];
+      let entry;
+      try {
+        entry = val[key];
+      } catch (error) {
+        out[key] = errorEntry(error);
+        continue;
+      }
+      out[key] = this.serialize(entry, depth + 1, path);
+    }
+    if (keys.length > max) out[TRUNCATED_KEY] = { $type: "truncated", reason: "entries", original: keys.length };
+    return out;
+  }
+}
+export {
+  SerializeDefaults,
+  resolveSerializeLimits,
+  serializeValue
+};
+//# sourceMappingURL=serializeValue.js.map

package/src/inspect/serializeValue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/inspect/serializeValue.ts"],
+  "sourcesContent": ["import {isSignal, value as readSignal} from '@spearwolf/signalize';\nimport type {SerializedValue, SerializeLimits} from './types.js';\n\nexport const SerializeDefaults: SerializeLimits = Object.freeze({\n  maxDepth: 3,\n  maxArrayLength: 20,\n  maxObjectEntries: 30,\n  maxStringLength: 200,\n});\n\n/** A limit that is not a finite number -- `NaN`, an infinity -- reads as the default. */\nconst orDefault = (val: number | undefined, fallback: number): number =>\n  val !== undefined && Number.isFinite(val) ? val : fallback;\n\nexport const resolveSerializeLimits = (limits?: Partial<SerializeLimits>): SerializeLimits => ({\n  maxDepth: orDefault(limits?.maxDepth, SerializeDefaults.maxDepth),\n  maxArrayLength: orDefault(limits?.maxArrayLength, SerializeDefaults.maxArrayLength),\n  maxObjectEntries: orDefault(limits?.maxObjectEntries, SerializeDefaults.maxObjectEntries),\n  maxStringLength: orDefault(limits?.maxStringLength, SerializeDefaults.maxStringLength),\n});\n\nconst isDomNode = (val: object): val is {nodeType: number; nodeName: string; id?: unknown} =>\n  typeof (val as {nodeType?: unknown}).nodeType === 'number' && typeof (val as {nodeName?: unknown}).nodeName === 'string';\n\nconst isPlainObject = (val: object): boolean => {\n  const proto = Object.getPrototypeOf(val);\n  return proto === Object.prototype || proto === null;\n};\n\nconst className = (val: object): string => {\n  const ctor = (val as {constructor?: unknown}).constructor;\n  return typeof ctor === 'function' && ctor.name ? ctor.name : 'Object';\n};\n\nconst errorEntry = (error: unknown): SerializedValue => ({\n  $type: 'object',\n  class: 'Error',\n  preview: {message: error instanceof Error ? error.message : String(error)},\n});\n\n/** Marks the entries cut of an object in its serialized preview. */\nconst TRUNCATED_KEY = '$truncated';\n\n/**\n * Turns any value into plain, JSON-safe data under a set of limits. Never throws, for any value: a\n * getter that throws while it is read, a revoked proxy, a trap that refuses -- whatever inspecting a\n * value costs, the throw becomes an error entry in place of the value.\n *\n * The rules and their order are the ones spec \u00A77 lists. Cycles are detected along the current\n * path, so a sub-object shared between two keys appears twice rather than as `$circular`.\n */\nexport function serializeValue(value: unknown, limits?: Partial<SerializeLimits>): SerializedValue {\n  return new Serializer(resolveSerializeLimits(limits)).serialize(value, 0, new Set());\n}\n\nclass Serializer {\n  constructor(private readonly limits: SerializeLimits) {}\n\n  serialize(val: unknown, depth: number, path: Set<object>): SerializedValue {\n    switch (typeof val) {\n      case 'undefined':\n        return {$type: 'undefined'};\n      case 'boolean':\n        return val;\n      case 'number':\n        return Number.isFinite(val) ? val : String(val);\n      case 'string':\n        return this.string(val);\n      case 'bigint':\n        return {$type: 'bigint', value: val.toString()};\n      case 'symbol':\n        return val.description === undefined ? {$type: 'symbol'} : {$type: 'symbol', description: val.description};\n      case 'function':\n        // a hostile object answers `isSignal` and even `name` with a throw; the entry takes its place\n        try {\n          if (isSignal(val)) return this.signal(val, depth, path);\n          return {$type: 'function', name: val.name};\n        } catch (error) {\n          return errorEntry(error);\n        }\n      case 'object':\n        if (val === null) return null;\n        // a revoked proxy, a throwing trap, an inherited getter -- anything a look at the value\n        // costs becomes the error entry in its place, so this function never throws\n        try {\n          if (isSignal(val)) return this.signal(val, depth, path);\n          return this.object(val, depth, path);\n        } catch (error) {\n          return errorEntry(error);\n        }\n    }\n  }\n\n  private string(val: string): SerializedValue {\n    if (val.length <= this.limits.maxStringLength) return val;\n    return {$type: 'truncated', reason: 'string', original: val.length, preview: val.slice(0, this.limits.maxStringLength)};\n  }\n\n  private signal(sig: unknown, depth: number, path: Set<object>): SerializedValue {\n    // a signal holding itself, or a chain of signals closing on one, ends here instead of on the stack\n    if (path.has(sig as object)) return {$type: 'circular'};\n\n    path.add(sig as object);\n    try {\n      let current: unknown;\n      try {\n        current = readSignal(sig as Parameters<typeof readSignal>[0]);\n      } catch (error) {\n        return errorEntry(error);\n      }\n      return {$type: 'signal', value: this.serialize(current, depth, path)};\n    } finally {\n      path.delete(sig as object);\n    }\n  }\n\n  private object(val: object, depth: number, path: Set<object>): SerializedValue {\n    if (val instanceof Date) return {$type: 'date', iso: Number.isNaN(val.getTime()) ? 'Invalid Date' : val.toISOString()};\n    if (val instanceof ArrayBuffer) return {$type: 'array-buffer', byteLength: val.byteLength, class: 'ArrayBuffer'};\n    if (ArrayBuffer.isView(val)) return {$type: 'typed-array', byteLength: val.byteLength, class: className(val)};\n    if (isDomNode(val)) {\n      return typeof val.id === 'string' && val.id\n        ? {$type: 'dom', nodeName: val.nodeName, id: val.id}\n        : {$type: 'dom', nodeName: val.nodeName};\n    }\n    if (val instanceof Error) return {$type: 'object', class: className(val), preview: {name: val.name, message: val.message}};\n\n    if (depth > this.limits.maxDepth) return {$type: 'truncated', reason: 'depth'};\n    if (path.has(val)) return {$type: 'circular'};\n\n    path.add(val);\n    try {\n      if (Array.isArray(val)) return this.array(val, depth, path);\n      if (val instanceof Map) {\n        return {\n          $type: 'object',\n          class: 'Map',\n          preview: {size: val.size, entries: this.array(Array.from(val.entries()), depth, path)},\n        };\n      }\n      if (val instanceof Set) {\n        return {$type: 'object', class: 'Set', preview: {size: val.size, entries: this.array(Array.from(val), depth, path)}};\n      }\n      if (isPlainObject(val)) return this.entries(val, depth, path);\n      return {$type: 'object', class: className(val), preview: this.entries(val, depth, path)};\n    } finally {\n      path.delete(val);\n    }\n  }\n\n  private array(val: unknown[], depth: number, path: Set<object>): SerializedValue[] {\n    const out: SerializedValue[] = [];\n    const max = this.limits.maxArrayLength;\n    for (let i = 0; i < val.length && i < max; i++) {\n      out.push(this.serialize(val[i], depth + 1, path));\n    }\n    if (val.length > max) out.push({$type: 'truncated', reason: 'length', original: val.length});\n    return out;\n  }\n\n  private entries(val: object, depth: number, path: Set<object>): Record<string, SerializedValue> {\n    const out: Record<string, SerializedValue> = {};\n    const keys = Object.keys(val);\n    const max = this.limits.maxObjectEntries;\n    for (let i = 0; i < keys.length && i < max; i++) {\n      const key = keys[i]!;\n      let entry: unknown;\n      try {\n        entry = (val as Record<string, unknown>)[key];\n      } catch (error) {\n        out[key] = errorEntry(error);\n        continue;\n      }\n      out[key] = this.serialize(entry, depth + 1, path);\n    }\n    if (keys.length > max) out[TRUNCATED_KEY] = {$type: 'truncated', reason: 'entries', original: keys.length};\n    return out;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/src/inspect/types.d.ts

@@ -0,0 +1,260 @@
+import type { RegistryDescription } from '../types.js';
+export type SerializedValue = null | boolean | number | string | SerializedValue[] | {
+    [key: string]: SerializedValue;
+} | {
+    $type: 'undefined';
+} | {
+    $type: 'bigint';
+    value: string;
+} | {
+    $type: 'symbol';
+    description?: string;
+} | {
+    $type: 'function';
+    name: string;
+} | {
+    $type: 'date';
+    iso: string;
+} | {
+    $type: 'signal';
+    value: SerializedValue;
+} | {
+    $type: 'object';
+    class: string;
+    preview?: Record<string, SerializedValue>;
+} | {
+    $type: 'dom';
+    nodeName: string;
+    id?: string;
+} | {
+    $type: 'array-buffer' | 'typed-array';
+    byteLength: number;
+    class: string;
+} | {
+    $type: 'circular';
+} | {
+    $type: 'redacted';
+} | {
+    $type: 'truncated';
+    reason: 'depth' | 'length' | 'entries' | 'string';
+    original?: number;
+    preview?: string;
+};
+export interface SerializeLimits {
+    /** How deep nested arrays and objects are followed. Default 3. */
+    maxDepth: number;
+    /** How many items of an array are kept. Default 20. */
+    maxArrayLength: number;
+    /** How many entries of an object or preview are kept. Default 30. */
+    maxObjectEntries: number;
+    /** How many characters of a string are kept. Default 200. */
+    maxStringLength: number;
+}
+export type InspectInclude = 'props' | 'shadowObjects' | 'contexts' | 'registry';
+export interface InspectRequest {
+    /** What to include per Entity. Default: all four. */
+    include?: InspectInclude[];
+    /** Descend from these uuids instead of the roots. Unknown uuids are reported under `truncation`, not thrown. */
+    rootUuids?: string[];
+    /** Tree depth below each root that is walked. Default 4. A non-finite number reads as the maximum, 64. */
+    maxDepth?: number;
+    /** Total number of nodes across the walk. Default 250. */
+    maxNodes?: number;
+    values?: Partial<SerializeLimits>;
+    /**
+     * Search instead of walk: every Entity that meets the filter is listed under `search`, and
+     * `roots` stays empty. `maxDepth`, `maxNodes` and `rootUuids` do not apply to a search, and
+     * `include` does not restrict what it reads. The View side ignores it.
+     */
+    filter?: EntityFilter;
+}
+/**
+ * What an Entity has to meet to be listed by a search. Every given criterion must match; a filter
+ * without criteria matches every Entity. `contextName` takes a string name only -- a symbol name
+ * cannot be named from outside, and a symbol context is findable through the tree alone.
+ */
+export interface EntityFilter {
+    /** The Entity's token, exact. */
+    token?: string;
+    /** A property name the Entity carries -- set from the View or read by a Shadow Object, with or without a value; the same names its `props` list shows. */
+    propName?: string;
+    /** The display name of a Shadow Object attached to the Entity. */
+    shadowObject?: string;
+    /** A string Entity Context name the Entity uses or provides. */
+    contextName?: string;
+    /** How many matches are carried. Default 50; `total` counts every match regardless. */
+    limit?: number;
+}
+export interface EntityMatch {
+    uuid: string;
+    token: string;
+    /** The token chain from the root down to this Entity, its own token last. */
+    path: string[];
+}
+/** The answer to a request that carried a `filter`. */
+export interface EntitySearchSnapshot {
+    matches: EntityMatch[];
+    /** How many Entities matched, before `limit`. */
+    total: number;
+}
+/** Where a limit of the request cut a walk short, and how to get the rest. */
+export interface TruncationNote {
+    reason: 'max-depth' | 'max-nodes' | 'unknown-root';
+    /** The node whose children were not walked, or the root uuid that was not found. */
+    uuid?: string;
+    message: string;
+}
+/** A string context name as it is; a symbol name as its description, marked as such. */
+export type ContextName = string | {
+    symbol: string;
+};
+export interface PropSnapshot {
+    name: string;
+    value: SerializedValue;
+    /** Whether the value counts as truthy for property routing (`Entity.truthyProps()`). */
+    routes: boolean;
+}
+export interface ShadowObjectSnapshot {
+    /** `ShadowObjectCreationScope.displayName` -- the constructor's `displayName` or `name`. */
+    displayName: string;
+    /** The tokens the constructor is defined under in this Kernel's Registry. Usually one. */
+    definedUnder: string[];
+    usesProperties: string[];
+    usesContexts: ContextName[];
+    usesParentContexts: ContextName[];
+    providesContexts: ContextName[];
+    providesGlobalContexts: ContextName[];
+    /** Which of the four lifecycle hooks the instance implements. */
+    hooks: ('onCreate' | 'onDestroy' | 'onParentChanged' | 'onViewEvent')[];
+}
+export type EntityContextSource = {
+    kind: 'self';
+} | {
+    kind: 'ancestor';
+    uuid: string;
+} | {
+    kind: 'global';
+} | {
+    kind: 'none';
+};
+export interface EntityContextSnapshot {
+    name: ContextName;
+    /** The value this Entity's own providers wrote, if any. Absent when nothing is provided here. */
+    provided?: SerializedValue;
+    /** The value inherited from the parent, or from the global chain at a root. Absent when there is none. */
+    inherited?: SerializedValue;
+    /** What `useContext(name)` on this Entity reads: provided where present, inherited otherwise. */
+    effective: SerializedValue;
+    /** Display names of the Shadow Objects on this Entity that provide the name. */
+    providedBy: string[];
+    /** Where the effective value comes from: this Entity, an ancestor by uuid, the global chain, or nowhere. */
+    source: EntityContextSource;
+}
+export interface GlobalContextSnapshot {
+    name: ContextName;
+    value: SerializedValue;
+    /** The Entities contributing to the chain, in chain order; the first one holding a value wins. */
+    providers: {
+        uuid: string;
+        providedBy: string[];
+        value: SerializedValue;
+    }[];
+}
+export interface EntityNodeSnapshot {
+    uuid: string;
+    token: string;
+    order: number;
+    parentUuid?: string;
+    autoDestructionOnParentRemoval: boolean;
+    props?: PropSnapshot[];
+    shadowObjects?: ShadowObjectSnapshot[];
+    contexts?: EntityContextSnapshot[];
+    /** Absent when the depth limit cut the walk here; `childCount` still says how many there are. */
+    children?: EntityNodeSnapshot[];
+    childCount: number;
+    /** Same meaning and shape as in `getEntityGraph()`. */
+    omittedChildren?: {
+        uuid: string;
+        reason: 'already-in-graph' | 'not-in-kernel';
+    }[];
+    /**
+     * Set on a node the request named in `rootUuids`: the chain from the root down to this node's
+     * parent, top down, empty for a root. Absent on a walk from the natural roots.
+     */
+    ancestors?: {
+        uuid: string;
+        token: string;
+    }[];
+}
+export interface RegistrySnapshot extends RegistryDescription {
+    /** Whether this is the default registry shared by every local environment of the thread. */
+    isDefault: boolean;
+}
+export interface KernelSnapshot {
+    /** `Date.now()` on the thread that built the snapshot. */
+    takenAt: number;
+    /** The realm the snapshot was built in. */
+    thread: 'main' | 'worker';
+    counts: {
+        entities: number;
+        roots: number;
+        shadowObjects: number;
+    };
+    roots: EntityNodeSnapshot[];
+    globalContexts: GlobalContextSnapshot[];
+    registry?: RegistrySnapshot;
+    /** Set when a limit of the request cut the walk short. */
+    truncation?: TruncationNote[];
+    /** Present when the request carried a `filter`; `roots` is empty then. */
+    search?: EntitySearchSnapshot;
+}
+export interface ViewComponentSnapshot {
+    uuid: string;
+    token?: string;
+    order: number;
+    parentUuid?: string;
+    /** The properties as the Component Memory holds them -- the last committed state, not pending changes. */
+    props?: PropSnapshot[];
+    /** A CSS selector path to the `<shae-ent>` element carrying this component, where one exists. */
+    element?: string;
+    children?: ViewComponentSnapshot[];
+    childCount: number;
+    /** A child the walk had already placed elsewhere; same meaning as the Kernel side's entry of that reason. */
+    omittedChildren?: {
+        uuid: string;
+        reason: 'already-in-graph';
+    }[];
+}
+export interface ViewSnapshot {
+    takenAt: number;
+    counts: {
+        components: number;
+        roots: number;
+    };
+    roots: ViewComponentSnapshot[];
+    /** Set when a depth or node limit cut the walk short. */
+    truncation?: TruncationNote[];
+}
+export interface EnvSnapshot {
+    /** The namespace as a string; the global namespace reports its symbol description. Empty while the environment has no view. */
+    namespace: string;
+    /** Whether the namespace is the global one. */
+    isGlobalNamespace: boolean;
+    /** `'local'` for a LocalShadowObjectEnv, `'worker'` for a RemoteWorkerEnv, `'custom'` for any other proxy, `'none'` without a proxy. */
+    kind: 'local' | 'worker' | 'custom' | 'none';
+    state: {
+        viewReady: boolean;
+        proxyReady: boolean;
+        isReady: boolean;
+        isDestroyed: boolean;
+    };
+    /** What the View holds for this namespace. Present while the environment has a view, unless building it threw -- then `error` says why. */
+    view?: ViewSnapshot;
+    /** What the Kernel holds. Absent while the proxy is not ready, or when the inspection failed -- then `error` says why. */
+    kernel?: KernelSnapshot;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/src/inspect/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/inspect/types.ts"],"names":[],"mappings":"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"}

package/src/inspect/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/src/inspect/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/src/model-context/ModelContextLike.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What this package needs from the platform's model context, named structurally so that the
+ * rest of the code never sees `document.modelContext`. WebMCP is a moving specification: the
+ * registration method changed name and semantics within six months of this file being written.
+ * When it moves again, this file and `findModelContext()` are where the change lands.
+ */
+/**
+ * The envelope every tool of this package returns. `content` is the compatibility floor every
+ * agent reads; `structuredContent` is the same data for an agent that reads structured results.
+ * `isError` marks a refusal the tool could phrase -- an unknown namespace, a missing criterion --
+ * so that the wording reaches the agent instead of being flattened into a generic failure.
+ */
+export interface ModelContextToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export interface ModelContextToolAnnotations {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+    consequentialHint?: boolean;
+}
+export interface ModelContextToolLike {
+    name: string;
+    title?: string;
+    description: string;
+    /** A JSON Schema object. */
+    inputSchema: object;
+    annotations?: ModelContextToolAnnotations;
+    /** `input` is whatever the platform parsed -- an object for the tools here, but nothing forces that. */
+    execute(input: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown> | unknown;
+}
+export interface ModelContextRegisterOptions {
+    /** Aborting it takes the tool back. */
+    signal?: AbortSignal;
+    /** Passed through as the platform defines it; absent means the platform default. */
+    exposedTo?: string[];
+}
+export interface ModelContextLike {
+    /**
+     * `unknown` rather than a promise on purpose: an early Chrome preview returned nothing, the
+     * specification returns a promise, and the caller awaits whatever it gets.
+     */
+    registerTool(tool: ModelContextToolLike, options?: ModelContextRegisterOptions): Promise<unknown> | unknown;
+}
+export declare const isModelContextLike: (value: unknown) => value is ModelContextLike;
+/**
+ * The platform's model context, or `undefined` where there is none: a worker, Node, a browser
+ * without WebMCP, an insecure context. `document.modelContext` is the current name and is read
+ * first; `navigator.modelContext` is the older one, and reading it where the document carries
+ * the object logs a deprecation warning in Chromium, so it is touched only as the fallback.
+ */
+export declare function findModelContext(): ModelContextLike | undefined;
+//# sourceMappingURL=ModelContextLike.d.ts.map

package/src/model-context/ModelContextLike.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelContextLike.d.ts","sourceRoot":"","sources":["../../../src/model-context/ModelContextLike.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IACxC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,wGAAwG;IACxG,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAC,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACvF;AAED,MAAM,WAAW,2BAA2B;IAC1C,uCAAuC;IACvC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAC7G;AAED,eAAO,MAAM,kBAAkB,UAAW,OAAO,KAAG,KAAK,IAAI,gBAC0D,CAAC;AAExH;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,GAAG,SAAS,CAQ/D"}

package/src/model-context/ModelContextLike.js

@@ -0,0 +1,15 @@
+const isModelContextLike = (value) => typeof value === "object" && value !== null && typeof value.registerTool === "function";
+function findModelContext() {
+  const doc = globalThis.document;
+  const fromDocument = doc?.modelContext;
+  if (isModelContextLike(fromDocument)) return fromDocument;
+  const nav = globalThis.navigator;
+  const fromNavigator = nav?.modelContext;
+  if (isModelContextLike(fromNavigator)) return fromNavigator;
+  return void 0;
+}
+export {
+  findModelContext,
+  isModelContextLike
+};
+//# sourceMappingURL=ModelContextLike.js.map

package/src/model-context/ModelContextLike.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/model-context/ModelContextLike.ts"],
+  "sourcesContent": ["/**\n * What this package needs from the platform's model context, named structurally so that the\n * rest of the code never sees `document.modelContext`. WebMCP is a moving specification: the\n * registration method changed name and semantics within six months of this file being written.\n * When it moves again, this file and `findModelContext()` are where the change lands.\n */\n\n/**\n * The envelope every tool of this package returns. `content` is the compatibility floor every\n * agent reads; `structuredContent` is the same data for an agent that reads structured results.\n * `isError` marks a refusal the tool could phrase -- an unknown namespace, a missing criterion --\n * so that the wording reaches the agent instead of being flattened into a generic failure.\n */\nexport interface ModelContextToolResult {\n  content: {type: 'text'; text: string}[];\n  structuredContent?: Record<string, unknown>;\n  isError?: boolean;\n}\n\nexport interface ModelContextToolAnnotations {\n  readOnlyHint?: boolean;\n  untrustedContentHint?: boolean;\n  consequentialHint?: boolean;\n}\n\nexport interface ModelContextToolLike {\n  name: string;\n  title?: string;\n  description: string;\n  /** A JSON Schema object. */\n  inputSchema: object;\n  annotations?: ModelContextToolAnnotations;\n  /** `input` is whatever the platform parsed -- an object for the tools here, but nothing forces that. */\n  execute(input: unknown, options?: {signal?: AbortSignal}): Promise<unknown> | unknown;\n}\n\nexport interface ModelContextRegisterOptions {\n  /** Aborting it takes the tool back. */\n  signal?: AbortSignal;\n  /** Passed through as the platform defines it; absent means the platform default. */\n  exposedTo?: string[];\n}\n\nexport interface ModelContextLike {\n  /**\n   * `unknown` rather than a promise on purpose: an early Chrome preview returned nothing, the\n   * specification returns a promise, and the caller awaits whatever it gets.\n   */\n  registerTool(tool: ModelContextToolLike, options?: ModelContextRegisterOptions): Promise<unknown> | unknown;\n}\n\nexport const isModelContextLike = (value: unknown): value is ModelContextLike =>\n  typeof value === 'object' && value !== null && typeof (value as {registerTool?: unknown}).registerTool === 'function';\n\n/**\n * The platform's model context, or `undefined` where there is none: a worker, Node, a browser\n * without WebMCP, an insecure context. `document.modelContext` is the current name and is read\n * first; `navigator.modelContext` is the older one, and reading it where the document carries\n * the object logs a deprecation warning in Chromium, so it is touched only as the fallback.\n */\nexport function findModelContext(): ModelContextLike | undefined {\n  const doc = (globalThis as {document?: {modelContext?: unknown}}).document;\n  const fromDocument = doc?.modelContext;\n  if (isModelContextLike(fromDocument)) return fromDocument;\n  const nav = (globalThis as {navigator?: {modelContext?: unknown}}).navigator;\n  const fromNavigator = nav?.modelContext;\n  if (isModelContextLike(fromNavigator)) return fromNavigator;\n  return undefined;\n}\n"],
+  "mappings": "AAmDO,MAAM,qBAAqB,CAAC,UACjC,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAQ,MAAmC,iBAAiB;AAQtG,SAAS,mBAAiD;AAC/D,QAAM,MAAO,WAAqD;AAClE,QAAM,eAAe,KAAK;AAC1B,MAAI,mBAAmB,YAAY,EAAG,QAAO;AAC7C,QAAM,MAAO,WAAsD;AACnE,QAAM,gBAAgB,KAAK;AAC3B,MAAI,mBAAmB,aAAa,EAAG,QAAO;AAC9C,SAAO;AACT;",
+  "names": []
+}

package/src/model-context/exposeShadowEnvsToModelContext.d.ts

@@ -0,0 +1,48 @@
+import type { InspectRequest } from '../inspect/types.js';
+import { type ModelContextLike } from './ModelContextLike.js';
+import type { RedactRule } from './redactProps.js';
+import type { NamespaceRule } from './toolSupport.js';
+export interface ExposeOptions {
+    /** Where to register. Default: `document.modelContext`, then `navigator.modelContext`; neither means "not available". */
+    modelContext?: ModelContextLike;
+    /** Prefix for every tool name. Default `'shae-'`. Together with `modelContext` it names the registration this call shares. */
+    toolPrefix?: string;
+    /** Aborting it takes this call's share back; the tools leave with the last share. */
+    signal?: AbortSignal;
+    /** Passed through to `registerTool()` by the call that opens the registration. Default: not set, so the platform default applies. */
+    exposedTo?: string[];
+    /** Default limits for every tool call, set by the call that opens the registration; a call's own input wins field by field. */
+    limits?: Partial<InspectRequest>;
+    /** Property names whose values are replaced by `{$type: 'redacted'}` in every answer, on the Kernel's and the View's side alike. Property values only. Cumulates with every other share of the registration. */
+    redactProps?: RedactRule;
+    /** Which environments this share exposes: a list of namespaces or a predicate over the namespace an environment is registered under. Default: every environment that holds a namespace. The registration exposes the union over its shares; a namespace outside it is refused like an unknown one. */
+    namespaces?: NamespaceRule;
+}
+export interface ExposeHandle {
+    /** `false` when no model context was found; then `tools` is empty and nothing was registered. */
+    available: boolean;
+    /** The tool names of the shared registration, with the prefix. */
+    tools: string[];
+    /** Takes this call's share back; the tools leave with the last share. Idempotent. The same as aborting `options.signal`. */
+    dispose(): void;
+}
+export declare const DefaultToolPrefix = "shae-";
+/**
+ * Registers the five read-only inspection tools on the platform's model context, so that an
+ * agent can see the Shadow Environments on the page. Nothing is exposed without this call or
+ * the `expose-to-model-context` attribute of `<shae-worker>`, which goes through it; every value
+ * in every answer is application state, and the docs say what that means before they show the
+ * first line of code.
+ *
+ * One registration per model context and prefix, shared: every call and every element is a
+ * share of it, the first opens it, the last to go closes it, and the tools answer from the union
+ * of what the shares expose and redact. A second call under the same prefix therefore joins
+ * rather than fails.
+ *
+ * Resolves, never rejects, where the platform has no model context -- the same application code
+ * runs in every browser. Rejects with what `registerTool()` rejected with -- a `NotAllowedError`
+ * under a Permissions Policy that disables `tools` -- and those are the caller's to handle.
+ * Registration is all-or-nothing: a rejection midway takes back what was registered before it.
+ */
+export declare function exposeShadowEnvsToModelContext(options?: ExposeOptions): Promise<ExposeHandle>;
+//# sourceMappingURL=exposeShadowEnvsToModelContext.d.ts.map

package/src/model-context/exposeShadowEnvsToModelContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposeShadowEnvsToModelContext.d.ts","sourceRoot":"","sources":["../../../src/model-context/exposeShadowEnvsToModelContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAmB,KAAK,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,yHAAyH;IACzH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,8HAA8H;IAC9H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qIAAqI;IACrI,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+HAA+H;IAC/H,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACjC,gNAAgN;IAChN,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,sSAAsS;IACtS,UAAU,CAAC,EAAE,aAAa,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,iGAAiG;IACjG,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4HAA4H;IAC5H,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,8BAA8B,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgCvG"}

package/src/model-context/exposeShadowEnvsToModelContext.js

@@ -0,0 +1,39 @@
+import { ConsoleLogger } from "../utils/ConsoleLogger.js";
+import { findModelContext } from "./ModelContextLike.js";
+import { joinSharedExposure } from "./sharedExposure.js";
+const DefaultToolPrefix = "shae-";
+async function exposeShadowEnvsToModelContext(options = {}) {
+  const modelContext = options.modelContext ?? findModelContext();
+  if (modelContext === void 0) {
+    new ConsoleLogger("ModelContext").info("no model context on this platform, nothing registered");
+    return { available: false, tools: [], dispose() {
+    } };
+  }
+  const { signal } = options;
+  if (signal?.aborted) return { available: true, tools: [], dispose() {
+  } };
+  const settings = { limits: options.limits ?? {}, ...options.exposedTo !== void 0 ? { exposedTo: options.exposedTo } : {} };
+  const membership = joinSharedExposure(
+    modelContext,
+    options.toolPrefix ?? DefaultToolPrefix,
+    { namespaces: options.namespaces, redactProps: options.redactProps },
+    settings
+  );
+  const dispose = () => {
+    membership.leave();
+    signal?.removeEventListener("abort", dispose);
+  };
+  signal?.addEventListener("abort", dispose, { once: true });
+  try {
+    const tools = await membership.tools;
+    return { available: true, tools, dispose };
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+}
+export {
+  DefaultToolPrefix,
+  exposeShadowEnvsToModelContext
+};
+//# sourceMappingURL=exposeShadowEnvsToModelContext.js.map