bazis 0.134.0 → 0.136.0

package/core/access/contracts/References.ts

@@ -25,6 +25,8 @@ export interface ReferenceItem {
 export interface ReferenceContext {
   readonly scope: Scope;
   readonly language?: string;
+  /** The area the ids are looked for in: the fields of one table. A kind without areas ignores it. */
+  readonly within?: string;
 }
 
 export interface ReferencePage {

package/core/agent/AgentToolExecutor.ts

@@ -62,6 +62,8 @@ export interface AgentToolExecutionContext {
   readonly actor?: ToolActor;
   /** A trial: the Tool, one with `dryRun: "supported"`, changes nothing (WORKFLOW-002 §5.4). */
   readonly dryRun?: boolean;
+  /** Who calls: `"agent"` or the caller id of `ToolRunner.as`. */
+  readonly caller?: string;
   readonly metadata: JsonObject;
   readonly signal: AbortSignal;
 }
@@ -1672,6 +1674,7 @@ export class AgentToolExecutor {
       approval,
       ...(options.actor !== undefined ? { actor: options.actor } : {}),
       ...(options.dryRun === true ? { dryRun: true } : {}),
+      ...(callerOf(options) === undefined ? {} : { caller: callerOf(options)! }),
       metadata,
       signal,
     });

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.134.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.136.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/tools/StandardTools.module.ts

@@ -1,14 +1,22 @@
 import { AccessModule } from "../access";
 import { Module, singleton } from "../di";
+import { toolsConfig } from "./contracts/Tools.config";
+import { HttpRequestTool } from "./http/HttpRequest.tool";
 import { OrmEntityReferences, OrmFieldReferences } from "./orm/OrmEntity.references";
+import { ConfigSecretStore, SecretStore } from "./secrets/SecretStore";
 
 /**
  * Tools that come with the framework (WORKFLOW-002 §7): not needed until an
- * application imports it. For now it owns the reference kinds of `ormEntityTools`.
+ * application imports it. Here are `http.request`, closed until `tools.http.allow`
+ * lists a host, the values of `$secrets` and the reference kinds of `ormEntityTools`.
+ * The application replaces the secrets by registering its `SecretStore`.
  */
 @Module({
   imports: [AccessModule],
+  config: [toolsConfig],
   references: { "orm.entity": OrmEntityReferences, "orm.field": OrmFieldReferences },
-  providers: [singleton(OrmEntityReferences), singleton(OrmFieldReferences)],
+  tools: [HttpRequestTool],
+  providers: [singleton(OrmEntityReferences), singleton(OrmFieldReferences), singleton(SecretStore, ConfigSecretStore)],
+  exports: [SecretStore],
 })
 export class StandardToolsModule {}

package/core/tools/contracts/Tools.config.ts

@@ -0,0 +1,30 @@
+import { defineConfig } from "../../kernel";
+
+/**
+ * Settings of the standard Tools. `http.allow` is the comma-separated list of hosts
+ * `http.request` may reach: `api.example.com`, `*.example.com`, `localhost:8080`.
+ * Empty by default: requests go nowhere. `http.allowPrivateNetworks` lets it reach
+ * private and loopback addresses of a listed host: intranet services, tests.
+ * `http.callers` says who may call it: `workflow`, `agent`.
+ */
+export interface ToolsSettings {
+  readonly "http.allow": string;
+  readonly "http.callers": string;
+  readonly "http.allowPrivateNetworks": boolean;
+  readonly "http.maxResponseBytes": number;
+  readonly "http.timeoutMs": number;
+}
+
+export const toolsConfig = defineConfig<ToolsSettings>("tools", {
+  default: {
+    "http.allow": "",
+    "http.callers": "workflow",
+    "http.allowPrivateNetworks": false,
+    "http.maxResponseBytes": 1_048_576,
+    "http.timeoutMs": 30_000,
+  },
+  validate: {
+    "http.maxResponseBytes": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 104_857_600 ? undefined : "must be an integer 1–104857600"),
+    "http.timeoutMs": (value) => (Number.isSafeInteger(value) && value >= 1 && value <= 600_000 ? undefined : "must be an integer 1–600000"),
+  },
+});

package/core/tools/generated/deps.ts

@@ -2,9 +2,14 @@
 // Do not edit manually.
 import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
 import { ServiceProvider } from "../../di/ServiceProvider";
+import { Configuration } from "../../kernel/config/Configuration";
+import { HttpRequestTool } from "../http/HttpRequest.tool";
 import { OrmEntityReferences, OrmFieldReferences } from "../orm/OrmEntity.references";
+import { ConfigSecretStore } from "../secrets/SecretStore";
 
 registerFrameworkClassDeps([
+  [ConfigSecretStore, [Configuration]],
+  [HttpRequestTool, ["Config:tools"]],
   [OrmEntityReferences, [ServiceProvider]],
   [OrmFieldReferences, [ServiceProvider]],
 ]);

package/core/tools/http/HttpRequest.tool.ts

@@ -0,0 +1,246 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { Tool, ToolError, type AgentToolExecutionContext } from "../../agent";
+import type { ConfigView } from "../../kernel";
+import type { ToolsSettings } from "../contracts/Tools.config";
+import { hostAllowed, isPublicAddress } from "./publicAddress";
+
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+const SAFE_METHODS = new Set(["GET", "HEAD"]);
+const MAX_REDIRECTS = 5;
+/** What a redirect to another host must not carry. */
+const CREDENTIALS = new Set(["authorization", "cookie", "proxy-authorization"]);
+
+const secretText = { type: "string", description: "Usually $secrets.NAME" };
+
+const INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    method: { enum: [...METHODS] },
+    url: { type: "string", format: "uri" },
+    headers: { type: "object", additionalProperties: { type: "string" } },
+    body: { description: "Sent as JSON" },
+    auth: {
+      type: "object",
+      description: "none; bearer with token; basic with username and password; apiKey with header and value",
+      properties: {
+        type: { enum: ["none", "bearer", "basic", "apiKey"] },
+        token: secretText,
+        username: { type: "string" },
+        password: secretText,
+        header: { type: "string" },
+        value: secretText,
+      },
+      required: ["type"],
+    },
+    successCodes: { type: "array", items: { type: "integer", minimum: 100, maximum: 599 } },
+    timeoutMs: { type: "integer", minimum: 1 },
+  },
+  required: ["url"],
+  additionalProperties: false,
+};
+
+const OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "integer" },
+    headers: { type: "object" },
+    body: { description: "JSON, or text when the response is not JSON" },
+    dryRun: { type: "boolean" },
+  },
+};
+
+interface Request {
+  readonly method: string;
+  readonly url: URL;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string | undefined;
+  readonly successCodes: ReadonlySet<number> | undefined;
+  readonly timeoutMs: number;
+  /** The header `auth` of type `apiKey` puts the key in: a redirect to another host drops it. */
+  readonly apiKeyHeader: string | undefined;
+}
+
+/**
+ * A request to the outside (WORKFLOW-002 §7.1), closed by default: an empty
+ * `tools.http.allow` lets nothing through. A host must be listed, and every address
+ * it resolves to must be public, on each redirect too; `http` goes to the address
+ * that was checked, `https` is held to its certificate. A status outside the success
+ * codes is an error with the reason `http_<status>`; 5xx and 429 are plain failures,
+ * so `retry` of the step repeats them. A trial makes only `GET` and `HEAD`.
+ */
+@Tool({
+  name: "http.request",
+  description: "Makes an HTTP request to an allowed host.",
+  sideEffect: "external",
+  dryRun: "supported",
+  callers: ["workflow", "agent"],
+  inputSchema: INPUT_SCHEMA,
+  outputSchema: OUTPUT_SCHEMA,
+})
+export class HttpRequestTool {
+  constructor(private readonly config: ConfigView<ToolsSettings>) {}
+
+  async execute(raw: unknown, context: AgentToolExecutionContext): Promise<unknown> {
+    const callers = this.config.get("http.callers").split(",").map((item) => item.trim());
+    if (context.caller !== undefined && !callers.includes(context.caller)) throw new ToolError(`tools.http.callers does not list ${context.caller}`, { reason: "caller_not_allowed" });
+    const request = this.requestOf(raw);
+    if (context.dryRun === true && !SAFE_METHODS.has(request.method)) return { dryRun: true };
+    const signal = AbortSignal.any([context.signal, AbortSignal.timeout(request.timeoutMs)]);
+    const response = await this.follow(request, signal);
+    const body = await this.bodyOf(response, request.method, signal);
+    const allowed = request.successCodes === undefined ? response.ok : request.successCodes.has(response.status);
+    if (!allowed) {
+      const message = `${request.method} ${request.url.host} answered ${response.status}`;
+      if (response.status >= 500 || response.status === 429) throw new Error(message);
+      throw new ToolError(message, { reason: `http_${response.status}` });
+    }
+    const headers = Object.fromEntries([...response.headers].filter(([name]) => name !== "set-cookie"));
+    return { status: response.status, headers, body, ...(context.dryRun === true ? { dryRun: true } : {}) };
+  }
+
+  private requestOf(raw: unknown): Request {
+    const input = (typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {}) as Record<string, unknown>;
+    const method = String(input.method ?? "GET").toUpperCase();
+    if (!METHODS.has(method)) throw invalid(`method must be one of ${[...METHODS].join(", ")}`);
+    if (typeof input.url !== "string") throw invalid("url is required");
+    let url: URL;
+    try {
+      url = new URL(input.url);
+    } catch {
+      throw invalid("url is not a URL");
+    }
+    const headers: Record<string, string> = {};
+    if (input.headers !== undefined && input.headers !== null) {
+      if (typeof input.headers !== "object" || Array.isArray(input.headers)) throw invalid("headers must be an object");
+      for (const [name, value] of Object.entries(input.headers)) {
+        if (typeof value !== "string") throw invalid(`header ${name} must be a string`);
+        headers[name.toLowerCase()] = value;
+      }
+    }
+    Object.assign(headers, authHeaders(input.auth));
+    let body: string | undefined;
+    if (input.body !== undefined && input.body !== null) {
+      if (SAFE_METHODS.has(method)) throw invalid(`${method} has no body`);
+      body = JSON.stringify(input.body);
+      headers["content-type"] ??= "application/json";
+    }
+    let successCodes: Set<number> | undefined;
+    if (input.successCodes !== undefined && input.successCodes !== null) {
+      if (!Array.isArray(input.successCodes) || input.successCodes.length === 0 || !input.successCodes.every((code) => Number.isInteger(code) && code >= 100 && code <= 599)) throw invalid("successCodes must be a list of status codes");
+      successCodes = new Set(input.successCodes as number[]);
+    }
+    const limit = this.config.get("http.timeoutMs");
+    const asked = input.timeoutMs ?? limit;
+    if (!Number.isSafeInteger(asked) || (asked as number) < 1) throw invalid("timeoutMs must be a positive integer");
+    const apiKeyHeader = (input.auth as { type?: unknown; header?: unknown } | null | undefined)?.type === "apiKey" ? String((input.auth as { header: unknown }).header).toLowerCase() : undefined;
+    return { method, url, headers, body, successCodes, timeoutMs: Math.min(asked as number, limit), apiKeyHeader };
+  }
+
+  /** The request and its redirects, each hop checked as the first one. */
+  private async follow(first: Request, signal: AbortSignal): Promise<Response> {
+    let { method, url, body } = first;
+    let headers: Record<string, string> = { ...first.headers };
+    const origin = first.url.host;
+    const apiKeyHeader = first.apiKeyHeader;
+    for (let hop = 0; ; hop += 1) {
+      const target = await this.checked(url);
+      const response = await fetch(target, {
+        method,
+        headers: target.href === url.href ? headers : { ...headers, host: url.host },
+        redirect: "manual",
+        signal,
+        ...(body === undefined ? {} : { body }),
+      });
+      const location = response.status >= 300 && response.status < 400 ? response.headers.get("location") : null;
+      if (location === null) return response;
+      await response.body?.cancel();
+      if (hop >= MAX_REDIRECTS) throw new ToolError(`More than ${MAX_REDIRECTS} redirects`, { reason: "too_many_redirects" });
+      url = new URL(location, url);
+      if (url.host !== origin) headers = Object.fromEntries(Object.entries(headers).filter(([name]) => !CREDENTIALS.has(name) && name !== apiKeyHeader));
+      // 301, 302 and 303 turn a write into a read, as browsers do.
+      if (response.status !== 307 && response.status !== 308 && !SAFE_METHODS.has(method)) {
+        method = "GET";
+        body = undefined;
+        delete headers["content-type"];
+      }
+    }
+  }
+
+  /** The URL to connect to, once the host is allowed and its addresses are public. Refused otherwise. */
+  private async checked(url: URL): Promise<URL> {
+    if (url.protocol !== "https:" && url.protocol !== "http:") throw invalid("only http and https are supported");
+    if (url.username !== "" || url.password !== "") throw invalid("credentials go to auth, not to the url");
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const port = url.port !== "" ? url.port : url.protocol === "https:" ? "443" : "80";
+    if (!hostAllowed(this.config.get("http.allow"), hostname, port)) throw new ToolError(`tools.http.allow does not list ${url.host}`, { reason: "host_not_allowed" });
+    if (this.config.get("http.allowPrivateNetworks")) return url;
+    const addresses = isIP(hostname) !== 0 ? [hostname] : (await lookup(hostname, { all: true })).map((item) => item.address);
+    if (addresses.length === 0 || !addresses.every(isPublicAddress)) throw new ToolError(`${url.host} is not a public address`, { reason: "address_not_allowed" });
+    if (url.protocol === "https:" || isIP(hostname) !== 0) return url;
+    // Past this check the name could resolve elsewhere: plain http goes to the address that passed it.
+    const pinned = new URL(url);
+    const address = addresses[0]!;
+    pinned.hostname = isIP(address) === 6 ? `[${address}]` : address;
+    return pinned;
+  }
+
+  /** The body within `http.maxResponseBytes`: JSON when it is JSON. */
+  private async bodyOf(response: Response, method: string, signal: AbortSignal): Promise<unknown> {
+    if (method === "HEAD" || response.body === null) return null;
+    const limit = this.config.get("http.maxResponseBytes");
+    const tooLarge = () => new ToolError(`The response is larger than ${limit} bytes`, { reason: "response_too_large" });
+    if (Number(response.headers.get("content-length") ?? 0) > limit) {
+      await response.body.cancel();
+      throw tooLarge();
+    }
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    const reader = response.body.getReader();
+    for (;;) {
+      signal.throwIfAborted();
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > limit) {
+        await reader.cancel();
+        throw tooLarge();
+      }
+      chunks.push(value);
+    }
+    const text = new TextDecoder().decode(Buffer.concat(chunks));
+    if (text === "") return null;
+    if (!/[/+]json\b/i.test(response.headers.get("content-type") ?? "")) return text;
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      return text;
+    }
+  }
+}
+
+function invalid(message: string): ToolError {
+  return new ToolError(message, { reason: "invalid_input" });
+}
+
+function authHeaders(auth: unknown): Record<string, string> {
+  if (auth === undefined || auth === null) return {};
+  if (typeof auth !== "object" || Array.isArray(auth)) throw invalid("auth must be an object");
+  const { type, token, username, password, header, value } = auth as Record<string, unknown>;
+  const text = (item: unknown, name: string): string => {
+    if (typeof item !== "string" || item === "") throw invalid(`auth.${name} is required for ${String(type)}`);
+    return item;
+  };
+  switch (type) {
+    case "none":
+      return {};
+    case "bearer":
+      return { authorization: `Bearer ${text(token, "token")}` };
+    case "basic":
+      return { authorization: `Basic ${Buffer.from(`${text(username, "username")}:${text(password, "password")}`).toString("base64")}` };
+    case "apiKey":
+      return { [text(header, "header").toLowerCase()]: text(value, "value") };
+    default:
+      throw invalid("auth.type must be none, bearer, basic or apiKey");
+  }
+}

package/core/tools/http/publicAddress.ts

@@ -0,0 +1,94 @@
+/** A dotted IPv4 address as a number, or `undefined`. */
+function ipv4(text: string): number | undefined {
+  const parts = text.split(".");
+  if (parts.length !== 4) return undefined;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part) || Number(part) > 255) return undefined;
+    value = value * 256 + Number(part);
+  }
+  return value;
+}
+
+/** An IPv6 address as eight 16-bit groups, or `undefined`. */
+function ipv6(text: string): number[] | undefined {
+  let source = text.split("%")[0]!;
+  // A dotted tail: ::ffff:127.0.0.1.
+  const tail = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(source);
+  if (tail) {
+    const value = ipv4(tail[2]!);
+    if (value === undefined) return undefined;
+    source = `${tail[1]}${Math.floor(value / 65536).toString(16)}:${(value % 65536).toString(16)}`;
+  }
+  const [head, rest, ...more] = source.split("::");
+  if (more.length > 0) return undefined;
+  const groups = (part: string | undefined) => (part === undefined || part === "" ? [] : part.split(":"));
+  const left = groups(head);
+  const right = groups(rest);
+  const missing = 8 - left.length - right.length;
+  if (rest === undefined ? missing !== 0 : missing < 1) return undefined;
+  const all = [...left, ...new Array<string>(rest === undefined ? 0 : missing).fill("0"), ...right];
+  return all.every((group) => /^[0-9a-f]{1,4}$/i.test(group)) ? all.map((group) => Number.parseInt(group, 16)) : undefined;
+}
+
+function inRange(value: number, base: string, bits: number): boolean {
+  const size = 2 ** (32 - bits);
+  return Math.floor(value / size) === Math.floor(ipv4(base)! / size);
+}
+
+const NOT_PUBLIC_V4: readonly (readonly [string, number])[] = [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+];
+
+function isPublicV4(value: number): boolean {
+  return !NOT_PUBLIC_V4.some(([base, bits]) => inRange(value, base, bits));
+}
+
+/**
+ * Whether an address can be reached from the outside: not loopback, private,
+ * link-local, multicast or reserved. An IPv6 address that carries an IPv4 one is
+ * judged by it. What cannot be read is not public.
+ */
+export function isPublicAddress(address: string): boolean {
+  const v4 = ipv4(address);
+  if (v4 !== undefined) return isPublicV4(v4);
+  const v6 = ipv6(address);
+  if (v6 === undefined) return false;
+  const carried = (high: number, low: number) => isPublicV4(high * 65536 + low);
+  // ::, ::1 and the old form ::a.b.c.d.
+  if (v6.slice(0, 6).every((group) => group === 0)) return v6[6] !== 0 && carried(v6[6]!, v6[7]!);
+  // ::ffff:a.b.c.d.
+  if (v6.slice(0, 5).every((group) => group === 0) && v6[5] === 0xffff) return carried(v6[6]!, v6[7]!);
+  // 64:ff9b::a.b.c.d.
+  if (v6[0] === 0x64 && v6[1] === 0xff9b) return carried(v6[6]!, v6[7]!);
+  // 2002:a.b.c.d::.
+  if (v6[0] === 0x2002) return carried(v6[1]!, v6[2]!);
+  // fc00::/7, fe80::/10, fec0::/10, ff00::/8, 2001:db8::/32.
+  if ((v6[0]! & 0xfe00) === 0xfc00 || (v6[0]! & 0xffc0) === 0xfe80 || (v6[0]! & 0xffc0) === 0xfec0 || (v6[0]! & 0xff00) === 0xff00) return false;
+  return !(v6[0] === 0x2001 && v6[1] === 0xdb8);
+}
+
+/** Whether `tools.http.allow` lets this host and port through: `api.example.com`, `*.example.com`, `localhost:8080`. */
+export function hostAllowed(allow: string, hostname: string, port: string): boolean {
+  const host = hostname.toLowerCase().replace(/\.$/, "");
+  return allow.split(",").map((item) => item.trim().toLowerCase()).filter((item) => item !== "").some((item) => {
+    // An IPv6 address goes in brackets, as in a URL: [::1]:8080.
+    const match = /^\[(.+)\](?::(\d+))?$/.exec(item) ?? /^(.*?)(?::(\d+))?$/.exec(item)!;
+    const [name, wanted] = [match[1]!, match[2]];
+    if (wanted !== undefined && wanted !== port) return false;
+    return name.startsWith("*.") ? host.endsWith(name.slice(1)) && host.length > name.length - 1 : host === name;
+  });
+}

package/core/tools/index.ts

@@ -1,8 +1,11 @@
 /**
- * Tools that come with the framework (WORKFLOW-002 §7): actions over the
- * application's entities for processes and agents, closed by default.
+ * Tools that come with the framework (WORKFLOW-002 §7): HTTP requests, actions over
+ * the application's entities and secrets, for processes and agents, closed by default.
  */
 import "./generated/deps";
 
 export { StandardToolsModule } from "./StandardTools.module";
+export { toolsConfig, type ToolsSettings } from "./contracts/Tools.config";
+export { HttpRequestTool } from "./http/HttpRequest.tool";
+export { ConfigSecretStore, SecretStore, type SecretContext } from "./secrets/SecretStore";
 export { ormEntityTools, type OrmEntityOperation, type OrmEntityToolsOptions } from "./orm/ormEntityTools";

package/core/tools/orm/OrmEntity.references.ts

@@ -46,7 +46,7 @@ export class OrmEntityReferences extends References {
   }
 }
 
-/** Reference kind `orm.field`: a field open to processes, `Order.status`. */
+/** Reference kind `orm.field`: a field open to processes, `Order.status`, or `status` within `Order`. */
 export class OrmFieldReferences extends References {
   constructor(private readonly services: ServiceProvider) {
     super();
@@ -56,16 +56,20 @@ export class OrmFieldReferences extends References {
     return opened(this.services).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
   }
 
-  async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
+  async exists(ids: readonly string[], context: ReferenceContext): Promise<ReadonlySet<string>> {
     const known = new Set(this.ids());
-    return new Set(ids.filter((id) => known.has(id)));
+    const { within } = context;
+    return new Set(ids.filter((id) => known.has(within === undefined ? id : `${within}.${id}`)));
   }
 
-  async describe(ids: readonly string[]): Promise<readonly ReferenceItem[]> {
-    return [...await this.exists(ids)].map((id) => ({ id, title: id }));
+  async describe(ids: readonly string[], context: ReferenceContext): Promise<readonly ReferenceItem[]> {
+    return [...await this.exists(ids, context)].map((id) => ({ id, title: id }));
   }
 
-  async search(text: string, _context: ReferenceContext, range: ReferencePage): Promise<readonly ReferenceItem[]> {
-    return page(this.ids(), text, range);
+  async search(text: string, context: ReferenceContext, range: ReferencePage): Promise<readonly ReferenceItem[]> {
+    const { within } = context;
+    if (within === undefined) return page(this.ids(), text, range);
+    const prefix = `${within}.`;
+    return page(this.ids().filter((id) => id.startsWith(prefix)).map((id) => id.slice(prefix.length)), text, range);
   }
 }

package/core/tools/secrets/SecretStore.ts

@@ -0,0 +1,28 @@
+import type { Configuration } from "../../kernel";
+
+/** Whose secret is asked for. */
+export interface SecretContext {
+  /** The partition of the instance: a tenant may have secrets of its own. */
+  readonly partition: string | null;
+}
+
+/**
+ * Values of `$secrets.NAME` (WORKFLOW-002 §7.2): a document holds only the name.
+ * The application registers its implementation in any module; by default the
+ * values come from the configuration.
+ */
+export abstract class SecretStore {
+  /** The value, or `undefined` when there is no such secret. */
+  abstract get(name: string, context: SecretContext): string | undefined | Promise<string | undefined>;
+}
+
+/** `secrets.<name>` of the configuration: `BAZIS_SECRETS__API_TOKEN` gives `$secrets.API_TOKEN`. */
+export class ConfigSecretStore extends SecretStore {
+  constructor(private readonly configuration: Configuration) {
+    super();
+  }
+
+  get(name: string): string | undefined {
+    return this.configuration.get(`secrets.${name}`);
+  }
+}

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -6,6 +6,7 @@ import { DefaultWorkflowExtensions, WorkflowExtensions } from "../contracts/Work
 import { DefaultWorkflowPartitions, WorkflowPartitions } from "../contracts/WorkflowPartitions";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowLanguages } from "../internal/WorkflowLanguages";
+import { WorkflowReferences } from "../internal/WorkflowReferences";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { definitionsPermissions } from "./access/Definitions.permissions";
 import { FolderReferences } from "./access/Folder.references";
@@ -42,6 +43,7 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(WorkflowExtensions, DefaultWorkflowExtensions),
     singleton(WorkflowPartitions, DefaultWorkflowPartitions),
     scoped(WorkflowEvents),
+    scoped(WorkflowReferences),
     scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
     scoped(ProcessReferences),
@@ -51,6 +53,6 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, WorkflowPartitions, ProcessFolderLookup],
+  exports: [IWorkflowDefinitions, WorkflowReferences, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, WorkflowPartitions, ProcessFolderLookup],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/code/CodeProcessPublisher.ts

@@ -1,6 +1,7 @@
 import { markConfigurationError, type ServiceProvider } from "../../../di";
 import type { HostedService } from "../../../di/extensions/hosted-service";
 import { LOGGER } from "../../../kernel";
+import { WorkflowReferences } from "../../internal/WorkflowReferences";
 import { WorkflowTools } from "../../internal/WorkflowTools";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 import { CatalogImport } from "./CatalogImport";
@@ -12,7 +13,9 @@ import { definitionProblems, WorkflowSetupError } from "./codeProcesses";
  * (WORKFLOW-002 §9), then publishes the processes of `@Module({ processes })`
  * (WORKFLOW-001 §14). A document with an unknown Tool or process, or an `extensions`
  * namespace nobody checks, stops the start with every finding of every process; the same
- * document again gives no new version.
+ * document again gives no new version. So does a reference kind no module owns, in a Tool
+ * or a document. A value that does not exist only warns: it may be data that is yet to come,
+ * and the step then fails with `ref_not_found`.
  */
 export class CodeProcessPublisher implements HostedService {
   readonly diagnosticName = "workflow:processes";
@@ -25,6 +28,11 @@ export class CodeProcessPublisher implements HostedService {
     try {
       const imported = await scope.resolve(CatalogImport).run();
       if (imported > 0) logger?.info("workflow catalog brought over from the old store", { processes: imported });
+      const references = scope.resolve(WorkflowReferences);
+      const unowned = references.unownedToolKinds();
+      if (unowned.length > 0) {
+        throw markConfigurationError(new WorkflowSetupError(`Tools refer to kinds no module owns:\n${unowned.map(({ tool, kind }) => `  - ${tool}: ${kind}${kind.startsWith("orm.") ? " (import StandardToolsModule from bazis/core/tools)" : " (declare it in @Module({ references }))"}`).join("\n")}`));
+      }
       const entries = this.services.resolve(CodeProcessCatalog).list();
       if (entries.length === 0) return;
       const tools = this.services.resolve(WorkflowTools);
@@ -35,6 +43,10 @@ export class CodeProcessPublisher implements HostedService {
         const found = [...definitionProblems(process, (name) => tools.has(name))];
         for (const issue of await definitions.validate(process.document, { processes })) {
           if (issue.severity === "error" && (issue.code === "extension_unknown" || issue.code === "extension_invalid" || issue.code === "unknown_process")) found.push(`${issue.message} (${issue.code})`);
+          else if (issue.code === "broken_ref") {
+            if (issue.message.startsWith("no module owns")) found.push(`${issue.message} (${issue.code})`);
+            else logger?.warn("workflow process refers to what does not exist", { process: process.key, node: issue.node, message: issue.message });
+          }
         }
         if (found.length > 0) problems.push(`${module}: process "${process.key}":\n${found.map((line) => `  - ${line}`).join("\n")}`);
       }

package/core/workflow/definitions_module/code/inspectProcesses.ts

@@ -1,6 +1,6 @@
 import { expandModuleMetadata, type BazisModuleRef } from "../../../di";
-import { toolMetadataOf } from "../../../agent";
-import { validateProcess } from "../../../../library/workflow";
+import { describeTool, toolMetadataOf } from "../../../agent";
+import { documentReferences, schemaReferenceKinds, validateProcess } from "../../../../library/workflow";
 import { WORKFLOW_CALLER } from "../../internal/WorkflowTools";
 import { WorkflowDefinitionsModule } from "../WorkflowDefinitions.module";
 import { definitionProblems, type OwnedCodeProcess } from "./codeProcesses";
@@ -28,16 +28,23 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
   const found: OwnedCodeProcess[] = [];
   const errors: string[] = [];
   const tools = new Set<string>();
+  const schemas = new Map<string, unknown>();
+  const kinds = new Set<string>();
   const visited = new Set<BazisModuleRef>();
   const visit = (moduleRef: BazisModuleRef): void => {
     if (visited.has(moduleRef)) return;
     visited.add(moduleRef);
     const module = typeof moduleRef === "function" ? moduleRef.name || "<anonymous module>" : "<module>";
-    const fields = moduleRef as { readonly processes?: unknown; readonly tools?: unknown };
+    const fields = moduleRef as { readonly processes?: unknown; readonly tools?: unknown; readonly references?: unknown };
+    if (typeof fields.references === "object" && fields.references !== null) for (const kind of Object.keys(fields.references)) kinds.add(kind);
     if (Array.isArray(fields.tools)) {
       for (const target of fields.tools) {
         const metadata = typeof target === "function" ? toolMetadataOf(target as new () => object) : undefined;
-        if (metadata?.callers.includes(WORKFLOW_CALLER)) tools.add(metadata.name);
+        if (metadata?.callers.includes(WORKFLOW_CALLER)) {
+          tools.add(metadata.name);
+          const input = describeTool({ target: target as new () => object, metadata }).input;
+          if (input?.kind === "json-schema") schemas.set(metadata.name, input.schema);
+        }
       }
     }
     if (fields.processes !== undefined) {
@@ -54,6 +61,10 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
   if (found.length > 0 && !visited.has(WorkflowDefinitionsModule)) {
     errors.push(`${found[0]!.module} declares processes, but the application does not import WorkflowModule (bazis/core/workflow).`);
   }
+  // The values live in the database: `check` knows only whether someone owns their kind.
+  for (const [tool, schema] of schemas) {
+    for (const kind of schemaReferenceKinds(schema)) if (!kinds.has(kind)) errors.push(`Tool ${tool} refers to the kind ${kind}, and no module owns it.`);
+  }
   const owners = new Map<string, string>();
   for (const { process, module } of found) {
     const other = owners.get(process.key);