@spearwolf/shadow-objects 0.33.0 → 0.35.0

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/model-context/exposeShadowEnvsToModelContext.ts"],
+  "sourcesContent": ["import type {InspectRequest} from '../inspect/types.js';\nimport {ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport {findModelContext, type ModelContextLike} from './ModelContextLike.js';\nimport type {RedactRule} from './redactProps.js';\nimport {joinSharedExposure} from './sharedExposure.js';\nimport type {NamespaceRule} from './toolSupport.js';\n\nexport interface ExposeOptions {\n  /** Where to register. Default: `document.modelContext`, then `navigator.modelContext`; neither means \"not available\". */\n  modelContext?: ModelContextLike;\n  /** Prefix for every tool name. Default `'shae-'`. Together with `modelContext` it names the registration this call shares. */\n  toolPrefix?: string;\n  /** Aborting it takes this call's share back; the tools leave with the last share. */\n  signal?: AbortSignal;\n  /** Passed through to `registerTool()` by the call that opens the registration. Default: not set, so the platform default applies. */\n  exposedTo?: string[];\n  /** Default limits for every tool call, set by the call that opens the registration; a call's own input wins field by field. */\n  limits?: Partial<InspectRequest>;\n  /** 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. */\n  redactProps?: RedactRule;\n  /** 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. */\n  namespaces?: NamespaceRule;\n}\n\nexport interface ExposeHandle {\n  /** `false` when no model context was found; then `tools` is empty and nothing was registered. */\n  available: boolean;\n  /** The tool names of the shared registration, with the prefix. */\n  tools: string[];\n  /** Takes this call's share back; the tools leave with the last share. Idempotent. The same as aborting `options.signal`. */\n  dispose(): void;\n}\n\nexport const DefaultToolPrefix = 'shae-';\n\n/**\n * Registers the five read-only inspection tools on the platform's model context, so that an\n * agent can see the Shadow Environments on the page. Nothing is exposed without this call or\n * the `expose-to-model-context` attribute of `<shae-worker>`, which goes through it; every value\n * in every answer is application state, and the docs say what that means before they show the\n * first line of code.\n *\n * One registration per model context and prefix, shared: every call and every element is a\n * share of it, the first opens it, the last to go closes it, and the tools answer from the union\n * of what the shares expose and redact. A second call under the same prefix therefore joins\n * rather than fails.\n *\n * Resolves, never rejects, where the platform has no model context -- the same application code\n * runs in every browser. Rejects with what `registerTool()` rejected with -- a `NotAllowedError`\n * under a Permissions Policy that disables `tools` -- and those are the caller's to handle.\n * Registration is all-or-nothing: a rejection midway takes back what was registered before it.\n */\nexport async function exposeShadowEnvsToModelContext(options: ExposeOptions = {}): Promise<ExposeHandle> {\n  const modelContext = options.modelContext ?? findModelContext();\n\n  if (modelContext === undefined) {\n    new ConsoleLogger('ModelContext').info('no model context on this platform, nothing registered');\n    return {available: false, tools: [], dispose() {}};\n  }\n\n  const {signal} = options;\n  if (signal?.aborted) return {available: true, tools: [], dispose() {}};\n\n  const settings = {limits: options.limits ?? {}, ...(options.exposedTo !== undefined ? {exposedTo: options.exposedTo} : {})};\n  const membership = joinSharedExposure(\n    modelContext,\n    options.toolPrefix ?? DefaultToolPrefix,\n    {namespaces: options.namespaces, redactProps: options.redactProps},\n    settings,\n  );\n\n  const dispose = () => {\n    membership.leave();\n    signal?.removeEventListener('abort', dispose);\n  };\n  signal?.addEventListener('abort', dispose, {once: true});\n\n  try {\n    const tools = await membership.tools;\n    return {available: true, tools, dispose};\n  } catch (error) {\n    dispose();\n    throw error;\n  }\n}\n"],
+  "mappings": "AACA,SAAQ,qBAAoB;AAC5B,SAAQ,wBAA8C;AAEtD,SAAQ,0BAAyB;AA6B1B,MAAM,oBAAoB;AAmBjC,eAAsB,+BAA+B,UAAyB,CAAC,GAA0B;AACvG,QAAM,eAAe,QAAQ,gBAAgB,iBAAiB;AAE9D,MAAI,iBAAiB,QAAW;AAC9B,QAAI,cAAc,cAAc,EAAE,KAAK,uDAAuD;AAC9F,WAAO,EAAC,WAAW,OAAO,OAAO,CAAC,GAAG,UAAU;AAAA,IAAC,EAAC;AAAA,EACnD;AAEA,QAAM,EAAC,OAAM,IAAI;AACjB,MAAI,QAAQ,QAAS,QAAO,EAAC,WAAW,MAAM,OAAO,CAAC,GAAG,UAAU;AAAA,EAAC,EAAC;AAErE,QAAM,WAAW,EAAC,QAAQ,QAAQ,UAAU,CAAC,GAAG,GAAI,QAAQ,cAAc,SAAY,EAAC,WAAW,QAAQ,UAAS,IAAI,CAAC,EAAE;AAC1H,QAAM,aAAa;AAAA,IACjB;AAAA,IACA,QAAQ,cAAc;AAAA,IACtB,EAAC,YAAY,QAAQ,YAAY,aAAa,QAAQ,YAAW;AAAA,IACjE;AAAA,EACF;AAEA,QAAM,UAAU,MAAM;AACpB,eAAW,MAAM;AACjB,YAAQ,oBAAoB,SAAS,OAAO;AAAA,EAC9C;AACA,UAAQ,iBAAiB,SAAS,SAAS,EAAC,MAAM,KAAI,CAAC;AAEvD,MAAI;AACF,UAAM,QAAQ,MAAM,WAAW;AAC/B,WAAO,EAAC,WAAW,MAAM,OAAO,QAAO;AAAA,EACzC,SAAS,OAAO;AACd,YAAQ;AACR,UAAM;AAAA,EACR;AACF;",
+  "names": []
+}

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

@@ -0,0 +1,14 @@
+import type { EnvSnapshot } from '../inspect/types.js';
+/** Property names whose values are hidden: a list of names, or a predicate over name and Entity uuid. */
+export type RedactRule = string[] | ((name: string, uuid: string) => boolean);
+export type RedactPredicate = (name: string, uuid: string) => boolean;
+export declare const toRedactPredicate: (rule: RedactRule | undefined) => RedactPredicate | undefined;
+/**
+ * Replaces the value of every property the rule names by `{$type: 'redacted'}`, on the Kernel's
+ * Entities and the View's components alike, in place. Property values only: an Entity Context
+ * that carries the same secret is not covered, and the docs say so. In place is safe because a
+ * snapshot is built fresh for every call -- plain data from the builder, or a structured clone
+ * from the worker -- and nobody else holds it.
+ */
+export declare function redactSnapshot(snapshot: EnvSnapshot, redact: RedactPredicate): EnvSnapshot;
+//# sourceMappingURL=redactProps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redactProps.d.ts","sourceRoot":"","sources":["../../../src/model-context/redactProps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAe,MAAM,qBAAqB,CAAC;AAEnE,yGAAyG;AACzG,MAAM,MAAM,UAAU,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;AAE9E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEtE,eAAO,MAAM,iBAAiB,SAAU,UAAU,GAAG,SAAS,KAAG,eAAe,GAAG,SAKlF,CAAC;AAgBF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,GAAG,WAAW,CAI1F"}

package/src/model-context/redactProps.js

@@ -0,0 +1,22 @@
+const toRedactPredicate = (rule) => {
+  if (rule === void 0) return void 0;
+  if (typeof rule === "function") return rule;
+  const names = new Set(rule);
+  return (name) => names.has(name);
+};
+const redactNode = (node, redact) => {
+  for (const prop of node.props ?? []) {
+    if (redact(prop.name, node.uuid)) prop.value = { $type: "redacted" };
+  }
+  for (const child of node.children ?? []) redactNode(child, redact);
+};
+function redactSnapshot(snapshot, redact) {
+  for (const root of snapshot.kernel?.roots ?? []) redactNode(root, redact);
+  for (const root of snapshot.view?.roots ?? []) redactNode(root, redact);
+  return snapshot;
+}
+export {
+  redactSnapshot,
+  toRedactPredicate
+};
+//# sourceMappingURL=redactProps.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/model-context/redactProps.ts"],
+  "sourcesContent": ["import type {EnvSnapshot, PropSnapshot} from '../inspect/types.js';\n\n/** Property names whose values are hidden: a list of names, or a predicate over name and Entity uuid. */\nexport type RedactRule = string[] | ((name: string, uuid: string) => boolean);\n\nexport type RedactPredicate = (name: string, uuid: string) => boolean;\n\nexport const toRedactPredicate = (rule: RedactRule | undefined): RedactPredicate | undefined => {\n  if (rule === undefined) return undefined;\n  if (typeof rule === 'function') return rule;\n  const names = new Set(rule);\n  return (name) => names.has(name);\n};\n\ninterface NodeWithProps {\n  uuid: string;\n  props?: PropSnapshot[];\n  children?: NodeWithProps[];\n}\n\nconst redactNode = (node: NodeWithProps, redact: RedactPredicate): void => {\n  for (const prop of node.props ?? []) {\n    // `routes` stays: whether a value routes is not the value\n    if (redact(prop.name, node.uuid)) prop.value = {$type: 'redacted'};\n  }\n  for (const child of node.children ?? []) redactNode(child, redact);\n};\n\n/**\n * Replaces the value of every property the rule names by `{$type: 'redacted'}`, on the Kernel's\n * Entities and the View's components alike, in place. Property values only: an Entity Context\n * that carries the same secret is not covered, and the docs say so. In place is safe because a\n * snapshot is built fresh for every call -- plain data from the builder, or a structured clone\n * from the worker -- and nobody else holds it.\n */\nexport function redactSnapshot(snapshot: EnvSnapshot, redact: RedactPredicate): EnvSnapshot {\n  for (const root of snapshot.kernel?.roots ?? []) redactNode(root, redact);\n  for (const root of snapshot.view?.roots ?? []) redactNode(root, redact);\n  return snapshot;\n}\n"],
+  "mappings": "AAOO,MAAM,oBAAoB,CAAC,SAA8D;AAC9F,MAAI,SAAS,OAAW,QAAO;AAC/B,MAAI,OAAO,SAAS,WAAY,QAAO;AACvC,QAAM,QAAQ,IAAI,IAAI,IAAI;AAC1B,SAAO,CAAC,SAAS,MAAM,IAAI,IAAI;AACjC;AAQA,MAAM,aAAa,CAAC,MAAqB,WAAkC;AACzE,aAAW,QAAQ,KAAK,SAAS,CAAC,GAAG;AAEnC,QAAI,OAAO,KAAK,MAAM,KAAK,IAAI,EAAG,MAAK,QAAQ,EAAC,OAAO,WAAU;AAAA,EACnE;AACA,aAAW,SAAS,KAAK,YAAY,CAAC,EAAG,YAAW,OAAO,MAAM;AACnE;AASO,SAAS,eAAe,UAAuB,QAAsC;AAC1F,aAAW,QAAQ,SAAS,QAAQ,SAAS,CAAC,EAAG,YAAW,MAAM,MAAM;AACxE,aAAW,QAAQ,SAAS,MAAM,SAAS,CAAC,EAAG,YAAW,MAAM,MAAM;AACtE,SAAO;AACT;",
+  "names": []
+}

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

@@ -0,0 +1,32 @@
+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';
+/** What one share of a registration brings: the environments it exposes and the properties it hides. */
+export interface ExposureMember {
+    /** `undefined` exposes every environment that holds a namespace. */
+    namespaces: NamespaceRule | undefined;
+    redactProps: RedactRule | undefined;
+}
+/** What the registration takes from the member that opens it, and from nobody after that. */
+export interface ExposureSettings {
+    limits: Partial<InspectRequest>;
+    exposedTo?: string[];
+}
+export interface ExposureMembership {
+    /**
+     * The names the registration ended with -- empty when it was closed while it was still
+     * registering. Rejects with what `registerTool()` rejected with; the registration is gone then.
+     */
+    readonly tools: Promise<string[]>;
+    /** Takes this share back. The last share out closes the registration. Idempotent. */
+    leave(): void;
+}
+/**
+ * Joins the registration under `prefix` on `modelContext`, opening it when there is none. The
+ * member's rules count from the next tool call on; `settings` count only for the member that
+ * opens -- a later member with other values is reported and joins under the opener's, because
+ * `exposedTo` has gone to the platform by then and one set of `limits` is all a tool has.
+ */
+export declare function joinSharedExposure(modelContext: ModelContextLike, prefix: string, member: ExposureMember, settings: ExposureSettings): ExposureMembership;
+//# sourceMappingURL=sharedExposure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharedExposure.d.ts","sourceRoot":"","sources":["../../../src/model-context/sharedExposure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAGxD,OAAO,KAAK,EAAC,gBAAgB,EAA8B,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAuB,KAAK,UAAU,EAAoB,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAC,KAAK,aAAa,EAAyC,MAAM,kBAAkB,CAAC;AAG5F,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,UAAU,EAAE,aAAa,GAAG,SAAS,CAAC;IACtC,WAAW,EAAE,UAAU,GAAG,SAAS,CAAC;CACrC;AAED,6FAA6F;AAC7F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,qFAAqF;IACrF,KAAK,IAAI,IAAI,CAAC;CACf;AAkHD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,gBAAgB,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,kBAAkB,CA8BpB"}

package/src/model-context/sharedExposure.js

@@ -0,0 +1,108 @@
+import { ConsoleLogger } from "../utils/ConsoleLogger.js";
+import { toRedactPredicate } from "./redactProps.js";
+import { toNamespacePredicate } from "./toolSupport.js";
+import { createTools } from "./tools/index.js";
+const registry = /* @__PURE__ */ new WeakMap();
+const logger = new ConsoleLogger("ModelContext");
+const unionNamespaces = (members) => {
+  const predicates = [];
+  for (const member of members) {
+    const predicate = toNamespacePredicate(member.namespaces);
+    if (predicate === void 0) return void 0;
+    predicates.push(predicate);
+  }
+  return (ns) => predicates.some((accepts) => accepts(ns));
+};
+const unionRedaction = (members) => {
+  const predicates = [];
+  for (const member of members) {
+    const predicate = toRedactPredicate(member.redactProps);
+    if (predicate !== void 0) predicates.push(predicate);
+  }
+  if (predicates.length === 0) return void 0;
+  return (name, uuid) => predicates.some((hides) => hides(name, uuid));
+};
+const registerAll = async (modelContext, ctx, exposure) => {
+  const { controller, settings } = exposure;
+  const registerOptions = { signal: controller.signal };
+  if (settings.exposedTo !== void 0) registerOptions.exposedTo = settings.exposedTo;
+  const registered = [];
+  try {
+    for (const tool of createTools(ctx)) {
+      if (controller.signal.aborted) break;
+      await modelContext.registerTool(tool, registerOptions);
+      registered.push(tool.name);
+    }
+  } catch (error) {
+    controller.abort(error);
+    logger.error("registering the tools failed", error);
+    throw error;
+  }
+  if (controller.signal.aborted) return [];
+  logger.info(`registered ${registered.length} tools`, registered);
+  return registered;
+};
+const open = (modelContext, prefix, settings) => {
+  const members = /* @__PURE__ */ new Set();
+  const exposure = {
+    members,
+    controller: new AbortController(),
+    settings,
+    tools: Promise.resolve([]),
+    closed: false
+  };
+  const ctx = {
+    prefix,
+    limits: settings.limits,
+    get isExposed() {
+      return unionNamespaces(members);
+    },
+    get redact() {
+      return unionRedaction(members);
+    }
+  };
+  exposure.tools = registerAll(modelContext, ctx, exposure);
+  exposure.tools.catch(() => close(modelContext, prefix, exposure));
+  return exposure;
+};
+const close = (modelContext, prefix, exposure) => {
+  if (exposure.closed) return;
+  exposure.closed = true;
+  exposure.controller.abort();
+  const byPrefix = registry.get(modelContext);
+  if (byPrefix?.get(prefix) === exposure) byPrefix.delete(prefix);
+};
+const sameSettings = (a, b) => JSON.stringify(a.limits) === JSON.stringify(b.limits) && JSON.stringify(a.exposedTo) === JSON.stringify(b.exposedTo);
+function joinSharedExposure(modelContext, prefix, member, settings) {
+  let byPrefix = registry.get(modelContext);
+  if (byPrefix === void 0) {
+    byPrefix = /* @__PURE__ */ new Map();
+    registry.set(modelContext, byPrefix);
+  }
+  let exposure = byPrefix.get(prefix);
+  if (exposure === void 0) {
+    exposure = open(modelContext, prefix, settings);
+    byPrefix.set(prefix, exposure);
+  } else if (!sameSettings(exposure.settings, settings)) {
+    logger.warn(
+      `the tools under "${prefix}" are already registered with other limits or exposedTo; the values of the first call apply`,
+      { inEffect: exposure.settings, ignored: settings }
+    );
+  }
+  const joined = exposure;
+  joined.members.add(member);
+  let left = false;
+  return {
+    tools: joined.tools,
+    leave() {
+      if (left) return;
+      left = true;
+      joined.members.delete(member);
+      if (joined.members.size === 0) close(modelContext, prefix, joined);
+    }
+  };
+}
+export {
+  joinSharedExposure
+};
+//# sourceMappingURL=sharedExposure.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/model-context/sharedExposure.ts"],
+  "sourcesContent": ["import type {InspectRequest} from '../inspect/types.js';\nimport type {NamespaceType} from '../types.js';\nimport {ConsoleLogger} from '../utils/ConsoleLogger.js';\nimport type {ModelContextLike, ModelContextRegisterOptions} from './ModelContextLike.js';\nimport {type RedactPredicate, type RedactRule, toRedactPredicate} from './redactProps.js';\nimport {type NamespaceRule, type ToolContext, toNamespacePredicate} from './toolSupport.js';\nimport {createTools} from './tools/index.js';\n\n/** What one share of a registration brings: the environments it exposes and the properties it hides. */\nexport interface ExposureMember {\n  /** `undefined` exposes every environment that holds a namespace. */\n  namespaces: NamespaceRule | undefined;\n  redactProps: RedactRule | undefined;\n}\n\n/** What the registration takes from the member that opens it, and from nobody after that. */\nexport interface ExposureSettings {\n  limits: Partial<InspectRequest>;\n  exposedTo?: string[];\n}\n\nexport interface ExposureMembership {\n  /**\n   * The names the registration ended with -- empty when it was closed while it was still\n   * registering. Rejects with what `registerTool()` rejected with; the registration is gone then.\n   */\n  readonly tools: Promise<string[]>;\n  /** Takes this share back. The last share out closes the registration. Idempotent. */\n  leave(): void;\n}\n\ninterface Exposure {\n  readonly members: Set<ExposureMember>;\n  readonly controller: AbortController;\n  readonly settings: ExposureSettings;\n  tools: Promise<string[]>;\n  closed: boolean;\n}\n\n/*\n * One registration per model context and prefix, per copy of the package: the tools carry\n * fixed names and the platform refuses a duplicate, so whoever wants them joins the one that\n * exists. Keyed weakly on the model context, so a fake built in a test goes when the test does.\n */\nconst registry = new WeakMap<ModelContextLike, Map<string, Exposure>>();\n\nconst logger = new ConsoleLogger('ModelContext');\n\n/**\n * The namespaces a registration exposes right now: `undefined` -- every environment -- as soon\n * as one member has no rule, otherwise \"any member's rule accepts it\".\n */\nconst unionNamespaces = (members: Iterable<ExposureMember>): ((ns: NamespaceType) => boolean) | undefined => {\n  const predicates: ((ns: NamespaceType) => boolean)[] = [];\n  for (const member of members) {\n    const predicate = toNamespacePredicate(member.namespaces);\n    if (predicate === undefined) return undefined;\n    predicates.push(predicate);\n  }\n  return (ns) => predicates.some((accepts) => accepts(ns));\n};\n\n/**\n * The redaction a registration applies right now: a value is hidden when any member's rule\n * says so. `undefined` while no member brings a rule, so the walk over the snapshot is skipped.\n */\nconst unionRedaction = (members: Iterable<ExposureMember>): RedactPredicate | undefined => {\n  const predicates: RedactPredicate[] = [];\n  for (const member of members) {\n    const predicate = toRedactPredicate(member.redactProps);\n    if (predicate !== undefined) predicates.push(predicate);\n  }\n  if (predicates.length === 0) return undefined;\n  return (name, uuid) => predicates.some((hides) => hides(name, uuid));\n};\n\n/**\n * The registration loop, all-or-nothing: a rejection midway aborts the controller, which takes\n * back what was registered before it, and is rethrown for every member to see.\n */\nconst registerAll = async (modelContext: ModelContextLike, ctx: ToolContext, exposure: Exposure): Promise<string[]> => {\n  const {controller, settings} = exposure;\n  const registerOptions: ModelContextRegisterOptions = {signal: controller.signal};\n  if (settings.exposedTo !== undefined) registerOptions.exposedTo = settings.exposedTo;\n\n  const registered: string[] = [];\n  try {\n    for (const tool of createTools(ctx)) {\n      if (controller.signal.aborted) break;\n      await modelContext.registerTool(tool, registerOptions);\n      registered.push(tool.name);\n    }\n  } catch (error) {\n    controller.abort(error);\n    logger.error('registering the tools failed', error);\n    throw error;\n  }\n\n  // closed while registering: the platform has already taken the tools back\n  if (controller.signal.aborted) return [];\n\n  logger.info(`registered ${registered.length} tools`, registered);\n  return registered;\n};\n\nconst open = (modelContext: ModelContextLike, prefix: string, settings: ExposureSettings): Exposure => {\n  const members = new Set<ExposureMember>();\n  const exposure: Exposure = {\n    members,\n    controller: new AbortController(),\n    settings,\n    tools: Promise.resolve([]),\n    closed: false,\n  };\n  // getters, not values: the tools read both at the start of every call (`inspectEnvs`), so a\n  // member joining or leaving is seen by the next call and nothing has to be re-registered\n  const ctx: ToolContext = {\n    prefix,\n    limits: settings.limits,\n    get isExposed() {\n      return unionNamespaces(members);\n    },\n    get redact() {\n      return unionRedaction(members);\n    },\n  };\n  exposure.tools = registerAll(modelContext, ctx, exposure);\n  // a registration that failed is not kept: the next member to arrive first opens a new one\n  exposure.tools.catch(() => close(modelContext, prefix, exposure));\n  return exposure;\n};\n\nconst close = (modelContext: ModelContextLike, prefix: string, exposure: Exposure): void => {\n  if (exposure.closed) return;\n  exposure.closed = true;\n  exposure.controller.abort();\n  const byPrefix = registry.get(modelContext);\n  if (byPrefix?.get(prefix) === exposure) byPrefix.delete(prefix);\n};\n\nconst sameSettings = (a: ExposureSettings, b: ExposureSettings): boolean =>\n  JSON.stringify(a.limits) === JSON.stringify(b.limits) && JSON.stringify(a.exposedTo) === JSON.stringify(b.exposedTo);\n\n/**\n * Joins the registration under `prefix` on `modelContext`, opening it when there is none. The\n * member's rules count from the next tool call on; `settings` count only for the member that\n * opens -- a later member with other values is reported and joins under the opener's, because\n * `exposedTo` has gone to the platform by then and one set of `limits` is all a tool has.\n */\nexport function joinSharedExposure(\n  modelContext: ModelContextLike,\n  prefix: string,\n  member: ExposureMember,\n  settings: ExposureSettings,\n): ExposureMembership {\n  let byPrefix = registry.get(modelContext);\n  if (byPrefix === undefined) {\n    byPrefix = new Map();\n    registry.set(modelContext, byPrefix);\n  }\n\n  let exposure = byPrefix.get(prefix);\n  if (exposure === undefined) {\n    exposure = open(modelContext, prefix, settings);\n    byPrefix.set(prefix, exposure);\n  } else if (!sameSettings(exposure.settings, settings)) {\n    logger.warn(\n      `the tools under \"${prefix}\" are already registered with other limits or exposedTo; the values of the first call apply`,\n      {inEffect: exposure.settings, ignored: settings},\n    );\n  }\n\n  const joined = exposure;\n  joined.members.add(member);\n  let left = false;\n  return {\n    tools: joined.tools,\n    leave() {\n      if (left) return;\n      left = true;\n      joined.members.delete(member);\n      if (joined.members.size === 0) close(modelContext, prefix, joined);\n    },\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -0,0 +1,72 @@
+import type { EnvSnapshot, InspectInclude, InspectRequest } from '../inspect/types.js';
+import type { NamespaceType } from '../types.js';
+import type { ModelContextToolAnnotations, ModelContextToolLike, ModelContextToolResult } from './ModelContextLike.js';
+import { type RedactPredicate } from './redactProps.js';
+/** What every tool shares: the name prefix, the defaults of the exposure, and the redaction rule. */
+export interface ToolContext {
+    prefix: string;
+    /** Defaults for every call; the call's own input wins field by field. */
+    limits: Partial<InspectRequest>;
+    redact: RedactPredicate | undefined;
+    /** Which environments the tools see, by the namespace each is registered under; `undefined` means every one. */
+    isExposed: ((ns: NamespaceType) => boolean) | undefined;
+}
+/** Every tool declares both: nothing here writes, and every value may be what a user typed. */
+export declare const ReadOnlyAnnotations: Readonly<ModelContextToolAnnotations>;
+/** The global namespace as a tool names it: the description of its symbol, the same string `EnvSnapshot.namespace` carries. */
+export declare const GlobalNamespaceName: string;
+/** The namespace a tool input names, as `ShadowEnv.get()` takes it. */
+export declare const toNamespace: (name: string) => NamespaceType;
+/** Which environments an exposure covers: a list of namespaces, or a predicate over the namespace an environment is registered under. */
+export type NamespaceRule = NamespaceType[] | ((ns: NamespaceType) => boolean);
+export declare const toNamespacePredicate: (rule: NamespaceRule | undefined) => ((ns: NamespaceType) => boolean) | undefined;
+export declare const NamespaceInputSchema: Readonly<{
+    type: "string";
+    description: `The namespace of one Shadow Environment, as the list-envs tool reports it; the global namespace is "${string}". Without it, every environment answers.`;
+}>;
+/** A refusal the tool can phrase. `runTool()` turns it into an error result with the bare message. */
+export declare class ToolError extends Error {
+    name: string;
+}
+/**
+ * A typed reader over whatever the platform handed to `execute`: anything but an object reads as
+ * empty, a missing or `null` field is `undefined`, a field of the wrong type is a `ToolError`.
+ */
+export declare class ToolInput {
+    #private;
+    constructor(input: unknown);
+    string(key: string): string | undefined;
+    requiredString(key: string): string;
+    number(key: string): number | undefined;
+    stringList(key: string): string[] | undefined;
+}
+export declare const readInclude: (input: ToolInput) => InspectInclude[] | undefined;
+export declare const textResult: (summary: string, structured: Record<string, unknown>) => ModelContextToolResult;
+export declare const errorResult: (message: string) => ModelContextToolResult;
+/**
+ * Wraps a tool body. The input is read through `ToolInput`; a refused input and a failure inside
+ * the environment come back as an error result, so the wording reaches the agent -- a platform
+ * that sees a rejection reports a generic failure and drops the message. Only the caller's own
+ * abort rejects.
+ */
+export declare const runTool: (body: (input: ToolInput, signal: AbortSignal | undefined) => Promise<ModelContextToolResult>) => (input: unknown, options?: {
+    signal?: AbortSignal;
+}) => Promise<ModelContextToolResult>;
+/** The request of one call: the exposure's defaults under the call's own fields, `values` merged one level down. */
+export declare const buildRequest: (limits: Partial<InspectRequest>, own: InspectRequest) => InspectRequest;
+/**
+ * The environments a call addresses -- one by namespace, or every one that holds a namespace --
+ * each described by `ShadowEnv.inspect()` and redacted where the exposure asks for it. An
+ * unknown namespace is a `ToolError`; an environment that cannot answer costs its own entry,
+ * with the reason under `error`, exactly as `inspectAll()` reports it.
+ *
+ * A namespace the exposure does not cover is refused with the same words as an unknown one, so an
+ * agent cannot tell the two apart. Both rules are read once, at the top: an exposure whose members
+ * change answers every call from the set it had when the call began.
+ */
+export declare const inspectEnvs: (namespace: string | undefined, request: InspectRequest, signal: AbortSignal | undefined, ctx: ToolContext) => Promise<EnvSnapshot[]>;
+/** One line per environment, for the text half of a result. */
+export declare const describeEnv: (s: EnvSnapshot) => string;
+export declare const NoEnvironments = "no Shadow Environment holds a namespace";
+export declare const defineTool: (ctx: ToolContext, name: string, tool: Omit<ModelContextToolLike, 'name' | 'annotations'>) => ModelContextToolLike;
+//# sourceMappingURL=toolSupport.d.ts.map

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

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

package/src/model-context/toolSupport.js

@@ -0,0 +1,145 @@
+import { GlobalNS } from "../constants.js";
+import { ShadowEnv } from "../view/ShadowEnv.js";
+import { redactSnapshot } from "./redactProps.js";
+const ReadOnlyAnnotations = Object.freeze({
+  readOnlyHint: true,
+  untrustedContentHint: true
+});
+const namespaceName = (ns) => typeof ns === "symbol" ? ns.description ?? "" : ns;
+const GlobalNamespaceName = namespaceName(GlobalNS);
+const toNamespace = (name) => name === GlobalNamespaceName ? GlobalNS : name;
+const toNamespacePredicate = (rule) => {
+  if (rule === void 0) return void 0;
+  if (typeof rule === "function") return rule;
+  const names = new Set(rule);
+  return (ns) => names.has(ns);
+};
+const NamespaceInputSchema = Object.freeze({
+  type: "string",
+  description: `The namespace of one Shadow Environment, as the list-envs tool reports it; the global namespace is "${GlobalNamespaceName}". Without it, every environment answers.`
+});
+class ToolError extends Error {
+  constructor() {
+    super(...arguments);
+    this.name = "ToolError";
+  }
+}
+class ToolInput {
+  #raw;
+  constructor(input) {
+    this.#raw = typeof input === "object" && input !== null ? input : {};
+  }
+  string(key) {
+    const val = this.#raw[key];
+    if (val === void 0 || val === null) return void 0;
+    if (typeof val !== "string") throw new ToolError(`"${key}" must be a string`);
+    return val;
+  }
+  requiredString(key) {
+    const val = this.string(key);
+    if (val === void 0 || val === "") throw new ToolError(`"${key}" is required`);
+    return val;
+  }
+  number(key) {
+    const val = this.#raw[key];
+    if (val === void 0 || val === null) return void 0;
+    if (typeof val !== "number" || Number.isNaN(val)) throw new ToolError(`"${key}" must be a number`);
+    return val;
+  }
+  stringList(key) {
+    const val = this.#raw[key];
+    if (val === void 0 || val === null) return void 0;
+    if (!Array.isArray(val) || !val.every((item) => typeof item === "string")) {
+      throw new ToolError(`"${key}" must be a list of strings`);
+    }
+    return val;
+  }
+}
+const Includes = ["props", "shadowObjects", "contexts", "registry"];
+const readInclude = (input) => {
+  const list = input.stringList("include");
+  if (list === void 0) return void 0;
+  for (const item of list) {
+    if (!Includes.includes(item)) {
+      throw new ToolError(`"include" knows only ${Includes.join(", ")}; got "${item}"`);
+    }
+  }
+  return list;
+};
+const textResult = (summary, structured) => ({
+  content: [{ type: "text", text: `${summary}
+
+${JSON.stringify(structured)}` }],
+  structuredContent: structured
+});
+const errorResult = (message) => ({
+  content: [{ type: "text", text: message }],
+  isError: true
+});
+const describeFailure = (error) => {
+  if (error instanceof ToolError) return error.message;
+  if (error instanceof Error) return `${error.name}: ${error.message}`;
+  return String(error);
+};
+const runTool = (body) => async (input, options) => {
+  const signal = options?.signal;
+  try {
+    return await body(new ToolInput(input), signal);
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return errorResult(describeFailure(error));
+  }
+};
+const buildRequest = (limits, own) => {
+  const request = { ...limits, ...own };
+  if (limits.values !== void 0 || own.values !== void 0) request.values = { ...limits.values, ...own.values };
+  return request;
+};
+const inspectEnvs = async (namespace, request, signal, ctx) => {
+  const only = ctx.isExposed;
+  const redact = ctx.redact;
+  let snapshots;
+  if (namespace === void 0) {
+    snapshots = await ShadowEnv.inspectAll(request, signal, only);
+  } else {
+    const ns = toNamespace(namespace);
+    const env = only === void 0 || only(ns) ? ShadowEnv.get(ns) : void 0;
+    if (env === void 0) throw new ToolError(`no Shadow Environment holds the namespace "${namespace}"`);
+    snapshots = [await env.inspect(request, signal)];
+  }
+  if (redact !== void 0) {
+    for (const snapshot of snapshots) redactSnapshot(snapshot, redact);
+  }
+  return snapshots;
+};
+const describeEnv = (s) => {
+  const parts = [s.kind, s.state.isReady ? "ready" : "not ready"];
+  if (s.kernel !== void 0) parts.push(`${s.kernel.counts.entities} entities`);
+  if (s.error !== void 0) parts.push(`error: ${s.error.name}: ${s.error.message}`);
+  return `${s.namespace} (${parts.join(", ")})`;
+};
+const NoEnvironments = "no Shadow Environment holds a namespace";
+const defineTool = (ctx, name, tool) => ({
+  name: `${ctx.prefix}${name}`,
+  annotations: { ...ReadOnlyAnnotations },
+  ...tool
+});
+export {
+  GlobalNamespaceName,
+  NamespaceInputSchema,
+  NoEnvironments,
+  ReadOnlyAnnotations,
+  ToolError,
+  ToolInput,
+  buildRequest,
+  defineTool,
+  describeEnv,
+  errorResult,
+  inspectEnvs,
+  readInclude,
+  runTool,
+  textResult,
+  toNamespace,
+  toNamespacePredicate
+};
+//# sourceMappingURL=toolSupport.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/model-context/toolSupport.ts"],
+  "sourcesContent": ["import {GlobalNS} from '../constants.js';\nimport type {EnvSnapshot, InspectInclude, InspectRequest} from '../inspect/types.js';\nimport type {NamespaceType} from '../types.js';\nimport {ShadowEnv} from '../view/ShadowEnv.js';\nimport type {ModelContextToolAnnotations, ModelContextToolLike, ModelContextToolResult} from './ModelContextLike.js';\nimport {type RedactPredicate, redactSnapshot} from './redactProps.js';\n\n/** What every tool shares: the name prefix, the defaults of the exposure, and the redaction rule. */\nexport interface ToolContext {\n  prefix: string;\n  /** Defaults for every call; the call's own input wins field by field. */\n  limits: Partial<InspectRequest>;\n  redact: RedactPredicate | undefined;\n  /** Which environments the tools see, by the namespace each is registered under; `undefined` means every one. */\n  isExposed: ((ns: NamespaceType) => boolean) | undefined;\n}\n\n/** Every tool declares both: nothing here writes, and every value may be what a user typed. */\nexport const ReadOnlyAnnotations: Readonly<ModelContextToolAnnotations> = Object.freeze({\n  readOnlyHint: true,\n  untrustedContentHint: true,\n});\n\nconst namespaceName = (ns: NamespaceType): string => (typeof ns === 'symbol' ? (ns.description ?? '') : ns);\n\n/** The global namespace as a tool names it: the description of its symbol, the same string `EnvSnapshot.namespace` carries. */\nexport const GlobalNamespaceName: string = namespaceName(GlobalNS);\n\n/** The namespace a tool input names, as `ShadowEnv.get()` takes it. */\nexport const toNamespace = (name: string): NamespaceType => (name === GlobalNamespaceName ? GlobalNS : name);\n\n/** Which environments an exposure covers: a list of namespaces, or a predicate over the namespace an environment is registered under. */\nexport type NamespaceRule = NamespaceType[] | ((ns: NamespaceType) => boolean);\n\nexport const toNamespacePredicate = (rule: NamespaceRule | undefined): ((ns: NamespaceType) => boolean) | undefined => {\n  if (rule === undefined) return undefined;\n  if (typeof rule === 'function') return rule;\n  const names = new Set<NamespaceType>(rule);\n  return (ns) => names.has(ns);\n};\n\nexport const NamespaceInputSchema = Object.freeze({\n  type: 'string',\n  description: `The namespace of one Shadow Environment, as the list-envs tool reports it; the global namespace is \"${GlobalNamespaceName}\". Without it, every environment answers.`,\n});\n\n/** A refusal the tool can phrase. `runTool()` turns it into an error result with the bare message. */\nexport class ToolError extends Error {\n  override name = 'ToolError';\n}\n\n/**\n * A typed reader over whatever the platform handed to `execute`: anything but an object reads as\n * empty, a missing or `null` field is `undefined`, a field of the wrong type is a `ToolError`.\n */\nexport class ToolInput {\n  readonly #raw: Record<string, unknown>;\n\n  constructor(input: unknown) {\n    this.#raw = typeof input === 'object' && input !== null ? (input as Record<string, unknown>) : {};\n  }\n\n  string(key: string): string | undefined {\n    const val = this.#raw[key];\n    if (val === undefined || val === null) return undefined;\n    if (typeof val !== 'string') throw new ToolError(`\"${key}\" must be a string`);\n    return val;\n  }\n\n  requiredString(key: string): string {\n    const val = this.string(key);\n    if (val === undefined || val === '') throw new ToolError(`\"${key}\" is required`);\n    return val;\n  }\n\n  number(key: string): number | undefined {\n    const val = this.#raw[key];\n    if (val === undefined || val === null) return undefined;\n    if (typeof val !== 'number' || Number.isNaN(val)) throw new ToolError(`\"${key}\" must be a number`);\n    return val;\n  }\n\n  stringList(key: string): string[] | undefined {\n    const val = this.#raw[key];\n    if (val === undefined || val === null) return undefined;\n    if (!Array.isArray(val) || !val.every((item) => typeof item === 'string')) {\n      throw new ToolError(`\"${key}\" must be a list of strings`);\n    }\n    return val as string[];\n  }\n}\n\nconst Includes: readonly InspectInclude[] = ['props', 'shadowObjects', 'contexts', 'registry'];\n\nexport const readInclude = (input: ToolInput): InspectInclude[] | undefined => {\n  const list = input.stringList('include');\n  if (list === undefined) return undefined;\n  for (const item of list) {\n    if (!(Includes as readonly string[]).includes(item)) {\n      throw new ToolError(`\"include\" knows only ${Includes.join(', ')}; got \"${item}\"`);\n    }\n  }\n  return list as InspectInclude[];\n};\n\nexport const textResult = (summary: string, structured: Record<string, unknown>): ModelContextToolResult => ({\n  content: [{type: 'text', text: `${summary}\\n\\n${JSON.stringify(structured)}`}],\n  structuredContent: structured,\n});\n\nexport const errorResult = (message: string): ModelContextToolResult => ({\n  content: [{type: 'text', text: message}],\n  isError: true,\n});\n\nconst describeFailure = (error: unknown): string => {\n  if (error instanceof ToolError) return error.message;\n  if (error instanceof Error) return `${error.name}: ${error.message}`;\n  return String(error);\n};\n\n/**\n * Wraps a tool body. The input is read through `ToolInput`; a refused input and a failure inside\n * the environment come back as an error result, so the wording reaches the agent -- a platform\n * that sees a rejection reports a generic failure and drops the message. Only the caller's own\n * abort rejects.\n */\nexport const runTool =\n  (body: (input: ToolInput, signal: AbortSignal | undefined) => Promise<ModelContextToolResult>) =>\n  async (input: unknown, options?: {signal?: AbortSignal}): Promise<ModelContextToolResult> => {\n    const signal = options?.signal;\n    try {\n      return await body(new ToolInput(input), signal);\n    } catch (error) {\n      if (signal?.aborted) throw error;\n      return errorResult(describeFailure(error));\n    }\n  };\n\n/** The request of one call: the exposure's defaults under the call's own fields, `values` merged one level down. */\nexport const buildRequest = (limits: Partial<InspectRequest>, own: InspectRequest): InspectRequest => {\n  const request: InspectRequest = {...limits, ...own};\n  if (limits.values !== undefined || own.values !== undefined) request.values = {...limits.values, ...own.values};\n  return request;\n};\n\n/**\n * The environments a call addresses -- one by namespace, or every one that holds a namespace --\n * each described by `ShadowEnv.inspect()` and redacted where the exposure asks for it. An\n * unknown namespace is a `ToolError`; an environment that cannot answer costs its own entry,\n * with the reason under `error`, exactly as `inspectAll()` reports it.\n *\n * A namespace the exposure does not cover is refused with the same words as an unknown one, so an\n * agent cannot tell the two apart. Both rules are read once, at the top: an exposure whose members\n * change answers every call from the set it had when the call began.\n */\nexport const inspectEnvs = async (\n  namespace: string | undefined,\n  request: InspectRequest,\n  signal: AbortSignal | undefined,\n  ctx: ToolContext,\n): Promise<EnvSnapshot[]> => {\n  const only = ctx.isExposed;\n  const redact = ctx.redact;\n\n  let snapshots: EnvSnapshot[];\n  if (namespace === undefined) {\n    snapshots = await ShadowEnv.inspectAll(request, signal, only);\n  } else {\n    const ns = toNamespace(namespace);\n    const env = only === undefined || only(ns) ? ShadowEnv.get(ns) : undefined;\n    if (env === undefined) throw new ToolError(`no Shadow Environment holds the namespace \"${namespace}\"`);\n    snapshots = [await env.inspect(request, signal)];\n  }\n  if (redact !== undefined) {\n    for (const snapshot of snapshots) redactSnapshot(snapshot, redact);\n  }\n  return snapshots;\n};\n\n/** One line per environment, for the text half of a result. */\nexport const describeEnv = (s: EnvSnapshot): string => {\n  const parts = [s.kind, s.state.isReady ? 'ready' : 'not ready'];\n  if (s.kernel !== undefined) parts.push(`${s.kernel.counts.entities} entities`);\n  if (s.error !== undefined) parts.push(`error: ${s.error.name}: ${s.error.message}`);\n  return `${s.namespace} (${parts.join(', ')})`;\n};\n\nexport const NoEnvironments = 'no Shadow Environment holds a namespace';\n\nexport const defineTool = (\n  ctx: ToolContext,\n  name: string,\n  tool: Omit<ModelContextToolLike, 'name' | 'annotations'>,\n): ModelContextToolLike => ({\n  name: `${ctx.prefix}${name}`,\n  annotations: {...ReadOnlyAnnotations},\n  ...tool,\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/src/model-context/tools/findEntities.d.ts

@@ -0,0 +1,15 @@
+import type { EntityMatch } from '../../inspect/types.js';
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import { type ToolContext } from '../toolSupport.js';
+export interface FindEntitiesEntry {
+    namespace: string;
+    matches: EntityMatch[];
+    /** How many matched before the limit. */
+    total: number;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export declare const createFindEntitiesTool: (ctx: ToolContext) => ModelContextToolLike;
+//# sourceMappingURL=findEntities.d.ts.map

package/src/model-context/tools/findEntities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findEntities.d.ts","sourceRoot":"","sources":["../../../../src/model-context/tools/findEntities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,WAAW,EAAC,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAOL,KAAK,WAAW,EAGjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC;CACzC;AAED,eAAO,MAAM,sBAAsB,QAAS,WAAW,KAAG,oBAkEtD,CAAC"}

package/src/model-context/tools/findEntities.js

@@ -0,0 +1,71 @@
+import {
+  buildRequest,
+  defineTool,
+  inspectEnvs,
+  NamespaceInputSchema,
+  NoEnvironments,
+  runTool,
+  ToolError,
+  textResult
+} from "../toolSupport.js";
+const createFindEntitiesTool = (ctx) => defineTool(ctx, "find-entities", {
+  title: "Find Entities",
+  description: "Search the Entity Tree of one Shadow Environment, or of every one, so that the answer stays small: every Entity that meets all given criteria, as uuid, token and the token path from the root. At least one criterion. The search runs where the Kernel runs and ships the matches, not the tree.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      namespace: NamespaceInputSchema,
+      token: { type: "string", description: "The token of the Entity, exact." },
+      propName: { type: "string", description: "A property name the Entity carries." },
+      shadowObject: { type: "string", description: "The display name of a Shadow Object attached to the Entity." },
+      contextName: { type: "string", description: "A string Entity Context name the Entity uses or provides." },
+      limit: {
+        type: "integer",
+        minimum: 1,
+        description: "How many matches to carry. Default 50; total counts every match regardless."
+      }
+    },
+    additionalProperties: false
+  },
+  execute: runTool(async (input, signal) => {
+    const filter = {};
+    const token = input.string("token");
+    if (token !== void 0) filter.token = token;
+    const propName = input.string("propName");
+    if (propName !== void 0) filter.propName = propName;
+    const shadowObject = input.string("shadowObject");
+    if (shadowObject !== void 0) filter.shadowObject = shadowObject;
+    const contextName = input.string("contextName");
+    if (contextName !== void 0) filter.contextName = contextName;
+    const limit = input.number("limit");
+    if (limit !== void 0) filter.limit = limit;
+    if (token === void 0 && propName === void 0 && shadowObject === void 0 && contextName === void 0) {
+      throw new ToolError("at least one of token, propName, shadowObject, contextName is required");
+    }
+    const envs = await inspectEnvs(
+      input.string("namespace"),
+      buildRequest(ctx.limits, { filter, maxDepth: 0, maxNodes: 1, include: [] }),
+      signal,
+      ctx
+    );
+    const results = envs.map((s) => {
+      const entry = {
+        namespace: s.namespace,
+        matches: s.kernel?.search?.matches ?? [],
+        total: s.kernel?.search?.total ?? 0
+      };
+      if (s.error !== void 0) entry.error = s.error;
+      return entry;
+    });
+    const summary = results.map((r) => {
+      const carried = r.matches.length < r.total ? `, ${r.matches.length} carried` : "";
+      const failed = r.error === void 0 ? "" : ` (error: ${r.error.name}: ${r.error.message})`;
+      return `${r.namespace}: ${r.total} match${r.total === 1 ? "" : "es"}${carried}${failed}`;
+    }).join("; ");
+    return textResult(summary || NoEnvironments, { results });
+  })
+});
+export {
+  createFindEntitiesTool
+};
+//# sourceMappingURL=findEntities.js.map

package/src/model-context/tools/findEntities.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/model-context/tools/findEntities.ts"],
+  "sourcesContent": ["import type {EntityFilter, EntityMatch} from '../../inspect/types.js';\nimport type {ModelContextToolLike} from '../ModelContextLike.js';\nimport {\n  buildRequest,\n  defineTool,\n  inspectEnvs,\n  NamespaceInputSchema,\n  NoEnvironments,\n  runTool,\n  type ToolContext,\n  ToolError,\n  textResult,\n} from '../toolSupport.js';\n\nexport interface FindEntitiesEntry {\n  namespace: string;\n  matches: EntityMatch[];\n  /** How many matched before the limit. */\n  total: number;\n  error?: {name: string; message: string};\n}\n\nexport const createFindEntitiesTool = (ctx: ToolContext): ModelContextToolLike =>\n  defineTool(ctx, 'find-entities', {\n    title: 'Find Entities',\n    description:\n      'Search the Entity Tree of one Shadow Environment, or of every one, so that the answer stays small: every Entity that meets all given criteria, as uuid, token and the token path from the root. At least one criterion. The search runs where the Kernel runs and ships the matches, not the tree.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        namespace: NamespaceInputSchema,\n        token: {type: 'string', description: 'The token of the Entity, exact.'},\n        propName: {type: 'string', description: 'A property name the Entity carries.'},\n        shadowObject: {type: 'string', description: 'The display name of a Shadow Object attached to the Entity.'},\n        contextName: {type: 'string', description: 'A string Entity Context name the Entity uses or provides.'},\n        limit: {\n          type: 'integer',\n          minimum: 1,\n          description: 'How many matches to carry. Default 50; total counts every match regardless.',\n        },\n      },\n      additionalProperties: false,\n    },\n    execute: runTool(async (input, signal) => {\n      const filter: EntityFilter = {};\n      const token = input.string('token');\n      if (token !== undefined) filter.token = token;\n      const propName = input.string('propName');\n      if (propName !== undefined) filter.propName = propName;\n      const shadowObject = input.string('shadowObject');\n      if (shadowObject !== undefined) filter.shadowObject = shadowObject;\n      const contextName = input.string('contextName');\n      if (contextName !== undefined) filter.contextName = contextName;\n      const limit = input.number('limit');\n      if (limit !== undefined) filter.limit = limit;\n\n      if (token === undefined && propName === undefined && shadowObject === undefined && contextName === undefined) {\n        throw new ToolError('at least one of token, propName, shadowObject, contextName is required');\n      }\n\n      // the Kernel side ignores the walk limits under a filter; they cut the View half, which\n      // this tool does not report, to the least the request allows\n      const envs = await inspectEnvs(\n        input.string('namespace'),\n        buildRequest(ctx.limits, {filter, maxDepth: 0, maxNodes: 1, include: []}),\n        signal,\n        ctx,\n      );\n\n      const results = envs.map((s) => {\n        const entry: FindEntitiesEntry = {\n          namespace: s.namespace,\n          matches: s.kernel?.search?.matches ?? [],\n          total: s.kernel?.search?.total ?? 0,\n        };\n        if (s.error !== undefined) entry.error = s.error;\n        return entry;\n      });\n\n      const summary = results\n        .map((r) => {\n          const carried = r.matches.length < r.total ? `, ${r.matches.length} carried` : '';\n          const failed = r.error === undefined ? '' : ` (error: ${r.error.name}: ${r.error.message})`;\n          return `${r.namespace}: ${r.total} match${r.total === 1 ? '' : 'es'}${carried}${failed}`;\n        })\n        .join('; ');\n      return textResult(summary || NoEnvironments, {results});\n    }),\n  });\n"],
+  "mappings": "AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OACK;AAUA,MAAM,yBAAyB,CAAC,QACrC,WAAW,KAAK,iBAAiB;AAAA,EAC/B,OAAO;AAAA,EACP,aACE;AAAA,EACF,aAAa;AAAA,IACX,MAAM;AAAA,IACN,YAAY;AAAA,MACV,WAAW;AAAA,MACX,OAAO,EAAC,MAAM,UAAU,aAAa,kCAAiC;AAAA,MACtE,UAAU,EAAC,MAAM,UAAU,aAAa,sCAAqC;AAAA,MAC7E,cAAc,EAAC,MAAM,UAAU,aAAa,8DAA6D;AAAA,MACzG,aAAa,EAAC,MAAM,UAAU,aAAa,4DAA2D;AAAA,MACtG,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,QACT,aAAa;AAAA,MACf;AAAA,IACF;AAAA,IACA,sBAAsB;AAAA,EACxB;AAAA,EACA,SAAS,QAAQ,OAAO,OAAO,WAAW;AACxC,UAAM,SAAuB,CAAC;AAC9B,UAAM,QAAQ,MAAM,OAAO,OAAO;AAClC,QAAI,UAAU,OAAW,QAAO,QAAQ;AACxC,UAAM,WAAW,MAAM,OAAO,UAAU;AACxC,QAAI,aAAa,OAAW,QAAO,WAAW;AAC9C,UAAM,eAAe,MAAM,OAAO,cAAc;AAChD,QAAI,iBAAiB,OAAW,QAAO,eAAe;AACtD,UAAM,cAAc,MAAM,OAAO,aAAa;AAC9C,QAAI,gBAAgB,OAAW,QAAO,cAAc;AACpD,UAAM,QAAQ,MAAM,OAAO,OAAO;AAClC,QAAI,UAAU,OAAW,QAAO,QAAQ;AAExC,QAAI,UAAU,UAAa,aAAa,UAAa,iBAAiB,UAAa,gBAAgB,QAAW;AAC5G,YAAM,IAAI,UAAU,wEAAwE;AAAA,IAC9F;AAIA,UAAM,OAAO,MAAM;AAAA,MACjB,MAAM,OAAO,WAAW;AAAA,MACxB,aAAa,IAAI,QAAQ,EAAC,QAAQ,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC,EAAC,CAAC;AAAA,MACxE;AAAA,MACA;AAAA,IACF;AAEA,UAAM,UAAU,KAAK,IAAI,CAAC,MAAM;AAC9B,YAAM,QAA2B;AAAA,QAC/B,WAAW,EAAE;AAAA,QACb,SAAS,EAAE,QAAQ,QAAQ,WAAW,CAAC;AAAA,QACvC,OAAO,EAAE,QAAQ,QAAQ,SAAS;AAAA,MACpC;AACA,UAAI,EAAE,UAAU,OAAW,OAAM,QAAQ,EAAE;AAC3C,aAAO;AAAA,IACT,CAAC;AAED,UAAM,UAAU,QACb,IAAI,CAAC,MAAM;AACV,YAAM,UAAU,EAAE,QAAQ,SAAS,EAAE,QAAQ,KAAK,EAAE,QAAQ,MAAM,aAAa;AAC/E,YAAM,SAAS,EAAE,UAAU,SAAY,KAAK,YAAY,EAAE,MAAM,IAAI,KAAK,EAAE,MAAM,OAAO;AACxF,aAAO,GAAG,EAAE,SAAS,KAAK,EAAE,KAAK,SAAS,EAAE,UAAU,IAAI,KAAK,IAAI,GAAG,OAAO,GAAG,MAAM;AAAA,IACxF,CAAC,EACA,KAAK,IAAI;AACZ,WAAO,WAAW,WAAW,gBAAgB,EAAC,QAAO,CAAC;AAAA,EACxD,CAAC;AACH,CAAC;",
+  "names": []
+}

package/src/model-context/tools/getEntity.d.ts

@@ -0,0 +1,16 @@
+import type { EntityNodeSnapshot, TruncationNote, ViewComponentSnapshot } from '../../inspect/types.js';
+import type { ModelContextToolLike } from '../ModelContextLike.js';
+import { type ToolContext } from '../toolSupport.js';
+/** One Entity in one environment, with the chain above it and the View's component of the same uuid. */
+export interface EntityMatchEntry {
+    namespace: string;
+    entity: Omit<EntityNodeSnapshot, 'ancestors'>;
+    ancestors: {
+        uuid: string;
+        token: string;
+    }[];
+    view?: ViewComponentSnapshot;
+    truncation?: TruncationNote[];
+}
+export declare const createGetEntityTool: (ctx: ToolContext) => ModelContextToolLike;
+//# sourceMappingURL=getEntity.d.ts.map