bazis 0.135.0 → 0.136.0

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.135.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/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/generated/deps.ts

@@ -65,7 +65,7 @@ registerFrameworkClassDeps([
   [TasksController, [IWorkflowTasks]],
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
-  [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools, WorkflowReferences, WorkflowLanguages]],
+  [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools, WorkflowReferences, WorkflowLanguages, ServiceProvider]],
   [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowReferences, ServiceProvider]],
   [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
   [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],

package/core/workflow/runtime_module/internal/ToolStep.ts

@@ -1,5 +1,8 @@
 import type { AgentSchemaContract, AgentToolResult } from "../../../agent";
-import { durationMs, inputReferences, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
+import { redactValues, rememberSecretValue } from "../../../../library/redaction";
+import { durationMs, inputReferences, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, secretNames, type ProcessDocument } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { SecretStore } from "../../../tools/secrets/SecretStore";
 import type { WorkflowToolMetadata } from "../../contracts/types";
 import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
 import type { WorkflowReferences } from "../../internal/WorkflowReferences";
@@ -27,6 +30,8 @@ export class ToolStep {
     private readonly tools: WorkflowTools,
     private readonly references: WorkflowReferences,
     private readonly languages: WorkflowLanguages,
+    /** The scope: the application's own `SecretStore` replaces the default. */
+    private readonly services: ServiceProvider,
   ) {}
 
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
@@ -39,7 +44,9 @@ export class ToolStep {
     const graph = await this.engine.graphOf(instance.versionId);
     const node = graph.document.nodes[token.nodeId];
     const name = String(node?.config?.tool ?? "");
-    const input = resolveInput(node?.config?.input ?? {}, dataOf(instance, this.engine.now(), token));
+    const { values: secrets, missing: noSecret } = await this.secretsOf(node?.config?.input, instance.partition);
+    const revealed = Object.values(secrets);
+    const input = resolveInput(node?.config?.input ?? {}, { ...dataOf(instance, this.engine.now(), token), secrets });
     const timeoutMs = stepTimeoutMs(node?.config?.timeout, graph.document);
     // A step may run longer than the lease: another worker must not take the job and call the Tool again meanwhile.
     if (timeoutMs !== undefined && timeoutMs >= LEASE_MS) {
@@ -48,8 +55,10 @@ export class ToolStep {
     const runner = this.tools.bound;
     const trial = instance.test ? runner?.getTool(name)?.metadata.dryRun : undefined;
     const missing = await this.references.missing(inputReferences(this.references.inputSchemaOf(name), input), { scope: instance.partition, language: this.languages.default });
-    const result: AgentToolResult = runner === undefined
+    const raw: AgentToolResult = runner === undefined
       ? { callId: token.id, name, status: "error", error: { code: "TOOL_NOT_FOUND", message: `Tool ${name} is not available to processes` }, metadata: {} } as AgentToolResult
+      : noSecret !== undefined
+      ? { callId: token.id, name, status: "error", error: { code: "secret_not_found", message: `There is no secret ${noSecret}`, details: { reason: "secret_not_found" } }, metadata: {} } as AgentToolResult
       : missing.length > 0
       // A value computed by the process, or one that is gone since the publication (WORKFLOW-002 §6.3).
       ? { callId: token.id, name, status: "error", error: { code: "ref_not_found", message: `${missing[0]!.kind} ${JSON.stringify(missing[0]!.id)} does not exist`, details: { reason: "ref_not_found", path: missing[0]!.path } }, metadata: {} } as AgentToolResult
@@ -65,9 +74,11 @@ export class ToolStep {
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
       });
 
+    // What the Tool got back from the outside may echo a secret: it goes no further than the Tool.
+    const result = redactValues(raw, revealed);
     const timedOut = TIMEOUT_CODES.has(result.error?.code ?? "");
     const reason = timedOut ? "timeout" : reasonOf(result);
-    const payloads = graph.document.settings?.log?.toolPayloads === true ? this.payloads(graph.document, name, node?.config?.input, input, result) : {};
+    const payloads = graph.document.settings?.log?.toolPayloads === true ? redactValues(this.payloads(graph.document, name, node?.config?.input, input, result), revealed) : {};
     await this.engine.inStep(instance.id, async (step) => {
       const current = step.tokens.find((t) => t.id === token.id);
       const retryAt = current?.status === "waiting" && step.instance.status === "running" && result.status === "error" && (reason === undefined || timedOut)
@@ -103,6 +114,21 @@ export class ToolStep {
     });
   }
 
+  /** The values of `$secrets` this input names, and the first one there is not. Remembered, so that a log masks them too. */
+  private async secretsOf(input: unknown, partition: string | null): Promise<{ readonly values: Record<string, string>; readonly missing?: string }> {
+    const values: Record<string, string> = {};
+    const names = secretNames(input);
+    if (names.length === 0) return { values };
+    const store = this.services.tryResolve(SecretStore);
+    for (const name of names) {
+      const value = await store?.get(name, { partition });
+      if (value === undefined) return { values, missing: name };
+      rememberSecretValue(value);
+      values[name] = value;
+    }
+    return { values };
+  }
+
   /** The input and output for the history under `log.toolPayloads`; personal data is masked unless `log.maskPersonal` is `false`. */
   private payloads(document: ProcessDocument, name: string, mapping: unknown, input: unknown, result: AgentToolResult): Record<string, unknown> {
     if (!masksPersonal(document)) return { input, output: result.output ?? null };

package/library/redaction/index.ts

@@ -52,6 +52,34 @@ export const MIN_REMEMBERED_SECRET_LENGTH = 10;
 const rememberedSecrets = new Set<string>();
 let longestFirst: readonly string[] = [];
 
+/**
+ * A copy of `value` with these exact strings cut out of every text and key: the
+ * secrets of one call. Unlike {@link rememberSecretValue} it knows nothing of the
+ * rest of the process, so it takes values of any length.
+ */
+export function redactValues<T>(value: T, secrets: readonly string[], replacement = DEFAULT_REPLACEMENT): T {
+  const list = secrets.filter((item) => item !== "").sort((left, right) => right.length - left.length);
+  if (list.length === 0) return value;
+  const text = (source: string) => list.reduce((current, secret) => current.split(secret).join(replacement), source);
+  const seen = new WeakMap<object, unknown>();
+  const walk = (item: unknown): unknown => {
+    if (typeof item === "string") return text(item);
+    if (typeof item !== "object" || item === null || item instanceof Date) return item;
+    if (seen.has(item)) return seen.get(item);
+    if (Array.isArray(item)) {
+      const copy: unknown[] = [];
+      seen.set(item, copy);
+      for (const element of item) copy.push(walk(element));
+      return copy;
+    }
+    const copy: Record<string, unknown> = {};
+    seen.set(item, copy);
+    for (const [key, element] of Object.entries(item)) copy[text(key)] = walk(element);
+    return copy;
+  };
+  return walk(value) as T;
+}
+
 /**
  * Remembers a secret value: from now on every redaction removes it wherever it
  * appears, also in plain text without a marker such as `password=`. `Secret`

package/library/workflow/expressions.ts

@@ -267,6 +267,8 @@ export interface ExpressionScope {
   readonly nodes?: ReadonlySet<string>;
   /** Whether it is read inside a loop body: `$item` and `$index` exist only there. */
   readonly loop?: boolean;
+  /** Whether it is the input of a Tool: `$secrets` exists only there, a value must go nowhere else. */
+  readonly secrets?: boolean;
 }
 
 /** What is wrong with an expression, or `null`: its shape, functions, argument types, paths and limits. */
@@ -333,11 +335,16 @@ function literalArgumentProblem(name: ExprFunctionName, args: readonly unknown[]
 
 /** What is wrong with a `$` path, or `null`. */
 export function checkPath(path: unknown, scope: ExpressionScope = {}): string | null {
-  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id, $now, $item.field or $index`;
+  if (typeof path !== "string" || !DATA_PATH.test(path)) return `path ${JSON.stringify(path)} must look like $input.field, $vars.name, $nodes.Node.field, $event.field, $trigger, $run.id, $now, $item.field, $index or $secrets.NAME`;
   const [root, first] = path.split(".");
   if (root === "$now" && first !== undefined) return "$now has no fields";
   if (root === "$index" && first !== undefined) return "$index has no fields";
   if ((root === "$item" || root === "$index") && scope.loop === false) return `path ${path}: ${root} exists only inside a loop body`;
+  if (root === "$secrets") {
+    if (scope.secrets !== true) return `path ${path}: $secrets exists only in the input of a Tool`;
+    if (first === undefined || path.split(".").length !== 2) return "$secrets needs a name: $secrets.NAME";
+    return null;
+  }
   if (root === "$nodes" && first === undefined) return "$nodes needs a node: $nodes.Node.field";
   if (first === undefined) return null;
   if (root === "$input" && scope.input && !scope.input.has(first)) return `path ${path}: the input has no field ${first}`;

package/library/workflow/index.ts

@@ -22,7 +22,7 @@ export {
 } from "./ProcessDocument";
 export { NODE_KINDS, nodeKindOf, ISO_DURATION, MAX_ITERATIONS, MAX_LOOP_PARALLEL, PROCESS_KEY, ISO_MOMENT, type JsonSchema, type NodeKindDefinition, type NodeRole } from "./nodeKinds";
 export { PROCESS_LIMITS, validateProcess, hasErrors, type ProcessIssue, type ProcessIssueCode, type ValidateProcessOptions } from "./validateProcess";
-export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, type InstanceData } from "./paths";
+export { DATA_PATH, DATA_PATHS, isPath, readPath, resolveInput, secretNames, type InstanceData } from "./paths";
 export {
   EXPRESSION_FUNCTIONS,
   EXPRESSION_LIMITS,

package/library/workflow/paths.ts

@@ -20,10 +20,12 @@ export interface InstanceData {
   readonly item?: unknown;
   /** Inside a loop body: the number of this iteration, from 0. */
   readonly index?: number;
+  /** Only while the input of a Tool is resolved: the values of `$secrets.NAME`. */
+  readonly secrets?: Readonly<Record<string, string>>;
 }
 
 /** `$input.amount`, `$vars.payment.id`, `$nodes.Pay.paymentId`, `$event.record.id`, `$run.partition`, `$now`, `$item.id`, `$index`. */
-export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
+export const DATA_PATH = /^\$(input|vars|nodes|event|trigger|run|now|item|index|secrets)((\.[A-Za-z_][A-Za-z0-9_]*)*)$/;
 
 /** The roots of `$` paths, for a designer. */
 export const DATA_PATHS: readonly { readonly path: string; readonly description: string }[] = Object.freeze([
@@ -36,8 +38,26 @@ export const DATA_PATHS: readonly { readonly path: string; readonly description:
   { path: "$now", description: "The engine's time" },
   { path: "$item", description: "Inside a loop body: the element of this iteration" },
   { path: "$index", description: "Inside a loop body: the number of this iteration, from 0" },
+  { path: "$secrets.<name>", description: "Only in the input of a Tool: the value of a secret, which goes nowhere else" },
 ]);
 
+/** The secrets a Tool input names, in paths and expressions at any depth. */
+export function secretNames(input: unknown): string[] {
+  const names = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (typeof value === "string") {
+      const match = /^\$secrets\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+      if (match) names.add(match[1]!);
+    } else if (Array.isArray(value)) {
+      value.forEach(walk);
+    } else if (typeof value === "object" && value !== null) {
+      Object.values(value).forEach(walk);
+    }
+  };
+  walk(input);
+  return [...names];
+}
+
 /** `true` if the value is a path to instance data. */
 export function isPath(value: unknown): value is string {
   return typeof value === "string" && DATA_PATH.test(value);

package/library/workflow/validateProcess.ts

@@ -65,8 +65,6 @@ export type ProcessIssueCode =
 export const PROCESS_LIMITS = Object.freeze({ nodes: 500, flows: 1000, bytes: 1_000_000 });
 
 const ID = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
-/** Paths that come with later stages of WORKFLOW-002: until then they are an error, not a silent literal. */
-const NOT_YET = /^\$secrets(\.|$)/;
 /** Who a boundary error may hang on: the steps that fail by an error of their own. */
 const CAN_FAIL: ReadonlySet<string | undefined> = new Set(["serviceTask", "callProcess", "loop"]);
 
@@ -447,7 +445,7 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
       if (problem) out.push(`config.assignments[${index}].value: ${problem}`);
     }
   }
-  if ((kind === "serviceTask" || kind === "callProcess") && config.input !== undefined) walkInput(config.input, "config.input", scope, out);
+  if ((kind === "serviceTask" || kind === "callProcess") && config.input !== undefined) walkInput(config.input, "config.input", kind === "serviceTask" ? { ...scope, secrets: true } : scope, out);
   if (kind === "loop" && config.over !== undefined) {
     const problem = checkExpression(config.over, scope);
     if (problem) out.push(`config.over: ${problem}`);
@@ -475,8 +473,10 @@ function configExpressionProblems(kind: string, config: Json, scope: ExpressionS
 
 function walkInput(value: unknown, at: string, scope: ExpressionScope, out: string[]): void {
   if (typeof value === "string") {
-    if (NOT_YET.test(value)) out.push(`${at}: ${value} is not supported`);
-    else if (isPath(value)) {
+    if (value === "$secrets" || value.startsWith("$secrets.")) {
+      const problem = checkPath(value, scope);
+      if (problem) out.push(`${at}: ${problem}`);
+    } else if (isPath(value)) {
       const problem = checkPath(value, scope);
       if (problem) out.push(`${at}: ${problem}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.135.0",
+  "version": "0.136.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",