bazis 0.96.1

package/core/agent/internal/AgentJsonSchema.ts

@@ -0,0 +1,150 @@
+import { validateBoundaryValueV1 } from "../../../library/boundary";
+
+type Schema = boolean | Readonly<Record<string, unknown>>;
+const TYPES = new Set(["object", "array", "string", "number", "integer", "boolean", "null"]);
+const FORMATS = new Set(["email", "uri", "uuid", "date", "time", "date-time", "decimal", "int64-string"]);
+const ANNOTATIONS = new Set(["title", "description", "default", "examples", "example", "readOnly", "writeOnly", "deprecated", "$comment"]);
+const COUNTS = new Set(["minLength", "maxLength", "minItems", "maxItems", "minProperties", "maxProperties"]);
+const BOUNDS = new Set(["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"]);
+const KEYWORDS = new Set(["type", "nullable", "properties", "required", "additionalProperties", "items", "anyOf", "oneOf", "allOf", "enum", "const", "uniqueItems", "pattern", "format", "contentMediaType", ...ANNOTATIONS, ...COUNTS, ...BOUNDS]);
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function equal(left: unknown, right: unknown): boolean {
+  if (left === right) return true;
+  if (Array.isArray(left)) return Array.isArray(right) && left.length === right.length && left.every((item, i) => equal(item, right[i]));
+  if (!record(left) || !record(right)) return false;
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && equal(left[key], right[key]));
+}
+
+/** The runtime's supported JSON Schema subset. Unsupported rules fail closed. */
+export function validateAgentJsonSchema(value: unknown, schema: unknown): readonly string[] {
+  const patterns = new Map<Schema, RegExp>();
+  let schemaNodes = 0;
+  let valueNodes = 0;
+  function inspect(node: unknown, path: string, depth: number): asserts node is Schema {
+    if (++schemaNodes > 2_048 || depth > 32) throw new Error("JSON Schema exceeds traversal limits.");
+    if (typeof node === "boolean") return;
+    if (!record(node)) throw new Error(`${path} must be a schema object or boolean.`);
+    for (const [key, item] of Object.entries(node)) {
+      if (!KEYWORDS.has(key)) throw new Error(`${path}: unsupported JSON Schema keyword "${key}".`);
+      if (COUNTS.has(key) && (typeof item !== "number" || !Number.isSafeInteger(item) || item < 0)) throw new Error(`${path}.${key} must be a non-negative integer.`);
+      if (BOUNDS.has(key) && (typeof item !== "number" || !Number.isFinite(item))) throw new Error(`${path}.${key} must be finite.`);
+    }
+    if (node.type !== undefined) {
+      const types = Array.isArray(node.type) ? node.type : [node.type];
+      if (!types.length || types.some((type) => typeof type !== "string" || !TYPES.has(type))) throw new Error(`${path}.type is unsupported.`);
+    }
+    for (const key of ["nullable", "uniqueItems"]) {
+      if (node[key] !== undefined && typeof node[key] !== "boolean") throw new Error(`${path}.${key} must be boolean.`);
+    }
+    if (node.required !== undefined && (!Array.isArray(node.required) || node.required.some((key) => typeof key !== "string"))) throw new Error(`${path}.required must be an array of names.`);
+    if (node.enum !== undefined && (!Array.isArray(node.enum) || !node.enum.length)) throw new Error(`${path}.enum must be a non-empty array.`);
+    if (node.properties !== undefined) {
+      if (!record(node.properties)) throw new Error(`${path}.properties must be an object.`);
+      for (const [name, child] of Object.entries(node.properties)) inspect(child, `${path}.properties.${name}`, depth + 1);
+    }
+    for (const key of ["items", "additionalProperties"]) {
+      if (node[key] !== undefined) inspect(node[key], `${path}.${key}`, depth + 1);
+    }
+    for (const key of ["anyOf", "oneOf", "allOf"]) {
+      if (node[key] === undefined) continue;
+      if (!Array.isArray(node[key]) || !node[key].length) throw new Error(`${path}.${key} must be a non-empty schema array.`);
+      node[key].forEach((child, i) => inspect(child, `${path}.${key}[${i}]`, depth + 1));
+    }
+    if (node.pattern !== undefined) {
+      if (typeof node.pattern !== "string") throw new Error(`${path}.pattern must be a string.`);
+      patterns.set(node, new RegExp(node.pattern));
+    }
+    if (node.format !== undefined && (typeof node.format !== "string" || !FORMATS.has(node.format))) throw new Error(`${path}.format is unsupported.`);
+    if (node.contentMediaType !== undefined && node.contentMediaType !== "application/json") throw new Error(`${path}.contentMediaType is unsupported.`);
+  }
+
+  function matchesType(item: unknown, type: unknown): boolean {
+    if (type === "null") return item === null;
+    if (type === "object") return record(item);
+    if (type === "array") return Array.isArray(item);
+    if (type === "integer") return typeof item === "number" && Number.isInteger(item);
+    if (type === "number") return typeof item === "number" && Number.isFinite(item);
+    return typeof item === type;
+  }
+
+  function check(item: unknown, node: Schema, path: string, issues: string[], depth: number): void {
+    if (++valueNodes > 100_000 || depth > 64) throw new Error("JSON Schema validation exceeds traversal limits.");
+    if (issues.length >= 64) return;
+    if (node === true) return;
+    if (node === false) { issues.push(`${path} is not allowed.`); return; }
+    if (item === null && node.nullable === true) return;
+    for (const key of ["anyOf", "oneOf", "allOf"] as const) {
+      const alternatives = node[key] as Schema[] | undefined;
+      if (alternatives === undefined) continue;
+      let matches = 0;
+      for (const child of alternatives) {
+        const childIssues: string[] = [];
+        check(item, child, path, childIssues, depth + 1);
+        if (!childIssues.length) matches++;
+      }
+      if ((key === "anyOf" && matches === 0) || (key === "oneOf" && matches !== 1) || (key === "allOf" && matches !== alternatives.length)) issues.push(`${path} does not satisfy ${key}.`);
+    }
+    if (Object.hasOwn(node, "const") && !equal(item, node.const)) issues.push(`${path} must equal the declared constant.`);
+    if (Array.isArray(node.enum) && !node.enum.some((allowed) => equal(item, allowed))) issues.push(`${path} is not an allowed enum value.`);
+    const types = node.type === undefined ? undefined : Array.isArray(node.type) ? node.type : [node.type];
+    if (types !== undefined && !types.some((type) => matchesType(item, type))) { issues.push(`${path} has an invalid type.`); return; }
+    if (record(item)) {
+      const properties = record(node.properties) ? node.properties : {};
+      const keys = Object.keys(item);
+      if (typeof node.minProperties === "number" && keys.length < node.minProperties) issues.push(`${path} has too few properties.`);
+      if (typeof node.maxProperties === "number" && keys.length > node.maxProperties) issues.push(`${path} has too many properties.`);
+      for (const key of (node.required ?? []) as string[]) if (!Object.hasOwn(item, key)) issues.push(`${path}.${key} is required.`);
+      for (const [key, child] of Object.entries(item)) {
+        const childSchema = Object.hasOwn(properties, key) ? properties[key] : node.additionalProperties;
+        if (childSchema !== undefined) check(child, childSchema as Schema, `${path}.${key}`, issues, depth + 1);
+      }
+    }
+    if (Array.isArray(item)) {
+      if (typeof node.minItems === "number" && item.length < node.minItems) issues.push(`${path} has too few items.`);
+      if (typeof node.maxItems === "number" && item.length > node.maxItems) issues.push(`${path} has too many items.`);
+      if (node.uniqueItems === true) {
+        const seen = new Set<string>();
+        const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical) : record(value) ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])])) : value;
+        for (const child of item) {
+          const key = JSON.stringify(canonical(child));
+          if (seen.has(key)) { issues.push(`${path} must contain unique items.`); break; }
+          seen.add(key);
+        }
+      }
+      if (node.items !== undefined) item.forEach((child, i) => check(child, node.items as Schema, `${path}[${i}]`, issues, depth + 1));
+    }
+    if (typeof item === "string") {
+      const length = [...item].length;
+      if (typeof node.minLength === "number" && length < node.minLength) issues.push(`${path} is too short.`);
+      if (typeof node.maxLength === "number" && length > node.maxLength) issues.push(`${path} is too long.`);
+      if (patterns.has(node) && !patterns.get(node)!.test(item)) issues.push(`${path} does not match pattern.`);
+      if (node.format !== undefined) {
+        // Reuse Bazis's boundary formats; URI follows the model validator.
+        const valid = node.format === "uri" ? URL.canParse(item) : validateBoundaryValueV1({ type: "string", format: node.format }, item).ok;
+        if (!valid) issues.push(`${path} does not match format ${node.format}.`);
+      }
+      if (node.contentMediaType === "application/json") {
+        try { JSON.parse(item); } catch { issues.push(`${path} must contain JSON.`); }
+      }
+    }
+    if (typeof item === "number") {
+      if (typeof node.minimum === "number" && item < node.minimum) issues.push(`${path} is below minimum.`);
+      if (typeof node.maximum === "number" && item > node.maximum) issues.push(`${path} is above maximum.`);
+      if (typeof node.exclusiveMinimum === "number" && item <= node.exclusiveMinimum) issues.push(`${path} is below exclusive minimum.`);
+      if (typeof node.exclusiveMaximum === "number" && item >= node.exclusiveMaximum) issues.push(`${path} is above exclusive maximum.`);
+    }
+  }
+  try {
+    inspect(schema, "$schema", 0);
+    const issues: string[] = [];
+    check(value, schema, "$", issues, 0);
+    return issues.slice(0, 64);
+  } catch (error) {
+    return [error instanceof Error ? error.message : "JSON Schema validation failed."];
+  }
+}

package/core/agent/internal/AgentModelBinding.ts

@@ -0,0 +1,57 @@
+import type { Class } from "../../di";
+import { bindModel } from "../../http/Binding/modelBinder";
+import { getGeneratedOpenApiMetadata, getGeneratedOpenApiSchemaName } from "../../http/OpenApi/generatedOpenApiRegistry";
+import { ModelValidationError } from "../../http/Errors/HttpError";
+import { normalizeJsonValue, type JsonObject } from "../semantic";
+
+// Validation belongs to the Agent execution phase (and may be asynchronous).
+// Never pick up an unrelated process-wide HTTP validator while hydrating a DTO.
+const bindingOnly = Object.freeze({ validate: () => ({ isValid: true, errors: [] }) });
+
+export function bindAgentModel(contract: Class<object>, value: unknown): object {
+  try {
+    return bindModel(contract, value, bindingOnly, {
+      unknownFields: "reject",
+      declaredFields(model) {
+        const name = getGeneratedOpenApiSchemaName(model) ?? model.name;
+        const properties = getGeneratedOpenApiMetadata().schemas[name]?.properties;
+        return properties !== null && typeof properties === "object" && !Array.isArray(properties)
+          ? Object.keys(properties) : undefined;
+      },
+    });
+  } catch (error) {
+    if (error instanceof ModelValidationError) {
+      throw new Error(error.errors.map((issue) => issue.message).join("; "), { cause: error });
+    }
+    throw error;
+  }
+}
+
+/** Project hydrated DTOs to JSON without calling arbitrary toJSON methods. */
+export function agentModelJson(instance: object, path: string): JsonObject {
+  const stack = new WeakSet<object>();
+  let nodes = 0;
+  function plain(value: unknown, depth: number): unknown {
+    if (++nodes > 100_000 || depth > 64) throw new Error(`${path} exceeds model JSON traversal limits.`);
+    if (value === null || typeof value !== "object") return value;
+    if (stack.has(value)) throw new Error(`${path} must be acyclic JSON.`);
+    stack.add(value);
+    try {
+      if (Array.isArray(value)) return value.map((item) => plain(item, depth + 1));
+      if (Object.prototype.toString.call(value) !== "[object Object]") {
+        throw new Error(`${path} contains a non-JSON object.`);
+      }
+      const output = Object.create(null) as Record<string, unknown>;
+      const prototype = Object.getPrototypeOf(value);
+      const dto = prototype !== null && prototype !== Object.prototype;
+      for (const [key, item] of Object.entries(value)) {
+        // Unset optional class fields are absent in JSON. Array slots remain strict.
+        if (item !== undefined || !dto) output[key] = plain(item, depth + 1);
+      }
+      return output;
+    } finally {
+      stack.delete(value);
+    }
+  }
+  return normalizeJsonValue(plain(instance, 0), path) as JsonObject;
+}

package/core/agent/internal/Schema.contract.ts

@@ -0,0 +1,36 @@
+export function inlineGeneratedSchema(
+  value: unknown,
+  schemas: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
+  stack: ReadonlySet<string> = new Set(),
+  depth = 0,
+): unknown {
+  if (depth > 32 || value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => inlineGeneratedSchema(item, schemas, stack, depth + 1));
+  }
+  const record = value as Readonly<Record<string, unknown>>;
+  const reference = record.$ref;
+  if (typeof reference === "string" && reference.startsWith("#/components/schemas/")) {
+    const name = reference.slice("#/components/schemas/".length);
+    const target = schemas[name];
+    if (target === undefined || stack.has(name)) {
+      return { type: "object" };
+    }
+    const next = new Set(stack);
+    next.add(name);
+    return inlineGeneratedSchema(target, schemas, next, depth + 1);
+  }
+  const output: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(record)) {
+    if (item !== undefined) {
+      output[key] = inlineGeneratedSchema(item, schemas, stack, depth + 1);
+    }
+  }
+  if ((output.type === "object" || output.properties !== undefined) && output.additionalProperties === undefined) {
+    output.additionalProperties = false;
+  }
+  return output;
+}
+

package/core/agent/internal/ToolAudit.projector.ts

@@ -0,0 +1,163 @@
+import type { SensitiveRedactionOptions } from "../../../library/redaction";
+import { redactSensitive } from "../../../library/redaction";
+import type { ToolDefinition } from "../AgentRegistry";
+import type { AgentToolAuditHookProjectionV1 } from "../AgentToolHooks";
+import type { AgentToolCall, AgentToolResult, JsonObject, JsonValue } from "../semantic";
+import { toolContractName } from "./ToolContract.validator";
+
+export type AgentToolAuditPhase = "attempt" | "enforcement" | "result" | "settlement" | "observer";
+export type AgentToolAuditFailureMode = "fail-closed" | "best-effort";
+
+export interface AgentToolAuditToolInfo {
+  readonly name: string;
+  readonly sideEffect: ToolDefinition["metadata"]["sideEffect"];
+  readonly approval: ToolDefinition["metadata"]["approval"];
+  readonly tags: readonly string[];
+  readonly timeoutMs?: number;
+  readonly inputSchema?: string;
+  readonly outputSchema?: string;
+}
+
+export interface AgentToolAuditEntry {
+  readonly kind: "agent-tool";
+  readonly phase: AgentToolAuditPhase;
+  readonly callId: string;
+  readonly toolName: string;
+  readonly agentName?: string;
+  readonly invocationId?: string;
+  readonly attempt?: number;
+  readonly maxAttempts?: number;
+  readonly idempotencyKey?: string;
+  readonly input: JsonValue;
+  readonly tool?: AgentToolAuditToolInfo;
+  readonly result?: AgentToolResult;
+  readonly startedAtUnixMs: number;
+  readonly finishedAtUnixMs?: number;
+  readonly durationMs?: number;
+  readonly metadata: JsonObject;
+  readonly hook?: AgentToolAuditHookProjectionV1;
+}
+
+interface ToolAuditOptions {
+  readonly agentName?: string;
+  readonly invocationId?: string;
+  readonly auditRedaction?: SensitiveRedactionOptions | false;
+}
+interface ToolAuditAttempt {
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly idempotencyKey?: string;
+}
+
+/** Builds the immutable audit projection; sink delivery and failure policy stay with execution. */
+export class ToolAuditProjector {
+  public constructor(private readonly auditRedaction: SensitiveRedactionOptions | false) {}
+
+  public create(
+    phase: AgentToolAuditPhase,
+    call: AgentToolCall,
+    startedAt: number,
+    metadata: JsonObject,
+    options: ToolAuditOptions,
+    tool?: ToolDefinition,
+    agentName?: string,
+    result?: AgentToolResult,
+    attempt?: ToolAuditAttempt,
+  ): AgentToolAuditEntry {
+    const finishedAt = result ? Date.now() : undefined;
+    const entry: {
+      kind: "agent-tool";
+      phase: AgentToolAuditPhase;
+      callId: string;
+      toolName: string;
+      agentName?: string;
+      invocationId?: string;
+      attempt?: number;
+      maxAttempts?: number;
+      idempotencyKey?: string;
+      input: JsonValue;
+      tool?: AgentToolAuditToolInfo;
+      result?: AgentToolResult;
+      startedAtUnixMs: number;
+      finishedAtUnixMs?: number;
+      durationMs?: number;
+      metadata: JsonObject;
+    } = {
+      kind: "agent-tool",
+      phase,
+      callId: call.id,
+      toolName: call.name,
+      input: this.redactAuditValue(call.input, options),
+      startedAtUnixMs: startedAt,
+      metadata: this.redactAuditValue(metadata, options) as JsonObject,
+    };
+
+    if (agentName !== undefined || options.agentName !== undefined) {
+      entry.agentName = agentName ?? options.agentName;
+    }
+    if (options.invocationId !== undefined) {
+      entry.invocationId = options.invocationId;
+    }
+    if (attempt !== undefined) {
+      entry.attempt = attempt.attempt;
+      entry.maxAttempts = attempt.maxAttempts;
+      if (attempt.idempotencyKey !== undefined) {
+        entry.idempotencyKey = attempt.idempotencyKey;
+      }
+    }
+    if (tool !== undefined) {
+      entry.tool = this.auditToolInfo(tool);
+    }
+    if (result !== undefined) {
+      entry.result = this.redactAuditValue(result, options) as AgentToolResult;
+      entry.finishedAtUnixMs = finishedAt;
+      entry.durationMs = result.durationMs ?? Math.max(0, Date.now() - startedAt);
+    }
+
+    return this.freezeAuditEntry(this.redactAuditValue(entry, options));
+  }
+
+  private redactAuditValue<T>(value: T, options: ToolAuditOptions): T {
+    const redaction = options.auditRedaction ?? this.auditRedaction;
+    return redaction === false ? value : redactSensitive(value, redaction);
+  }
+
+  private freezeAuditEntry(entry: AgentToolAuditEntry): AgentToolAuditEntry {
+    const visit = (value: unknown, seen: WeakSet<object>): void => {
+      if (value === null || typeof value !== "object" || seen.has(value)) return;
+      seen.add(value);
+      for (const child of Object.values(value as Record<string, unknown>)) visit(child, seen);
+      Object.freeze(value);
+    };
+    visit(entry, new WeakSet<object>());
+    return entry;
+  }
+
+  private auditToolInfo(tool: ToolDefinition): AgentToolAuditToolInfo {
+    const info: {
+      name: string;
+      sideEffect: ToolDefinition["metadata"]["sideEffect"];
+      approval: ToolDefinition["metadata"]["approval"];
+      tags: readonly string[];
+      timeoutMs?: number;
+      inputSchema?: string;
+      outputSchema?: string;
+    } = {
+      name: tool.metadata.name,
+      sideEffect: tool.metadata.sideEffect,
+      approval: tool.metadata.approval,
+      tags: Object.freeze([...tool.metadata.tags]),
+    };
+    if (tool.metadata.timeoutMs !== undefined) {
+      info.timeoutMs = tool.metadata.timeoutMs;
+    }
+    if (tool.metadata.input !== undefined) {
+      info.inputSchema = toolContractName(tool.metadata.input);
+    }
+    if (tool.metadata.output !== undefined) {
+      info.outputSchema = toolContractName(tool.metadata.output);
+    }
+    return Object.freeze(info);
+  }
+
+}

package/core/agent/internal/ToolContract.validator.ts

@@ -0,0 +1,102 @@
+import type { Class } from "../../di";
+import type { JsonObject, JsonValue } from "../semantic";
+import { AgentToolExecutionError } from "../errors";
+import { agentModelJson, bindAgentModel } from "./AgentModelBinding";
+
+export interface AgentToolValidationIssue {
+  readonly property: string;
+  readonly message: string;
+  readonly code?: string;
+}
+
+export interface AgentToolValidationResult {
+  readonly isValid: boolean;
+  readonly errors: readonly AgentToolValidationIssue[];
+}
+
+export interface AgentToolSchemaValidator {
+  validate(instance: object): AgentToolValidationResult | Promise<AgentToolValidationResult>;
+}
+
+type ContractResult =
+  | { readonly ok: true; readonly value: object }
+  | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly details: JsonObject } };
+
+/** DTO binding and validation only; execution outcomes belong to the executor. */
+export class ToolContractValidator {
+  public async validate(
+    contract: Class<object>, value: unknown, direction: "input" | "output",
+    toolName: string, validator?: AgentToolSchemaValidator,
+  ): Promise<ContractResult> {
+    const details = () => ({ toolName, schema: toolContractName(contract), direction });
+    let instance: object;
+    try {
+      if (direction === "output" && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        value = agentModelJson(value, "tool.output");
+      }
+      instance = bindAgentModel(contract, value);
+    } catch (error) {
+      return { ok: false, error: {
+        code: direction === "input" ? "TOOL_INPUT_INVALID" : "TOOL_OUTPUT_INVALID",
+        message: toolErrorMessage(error), details: details(),
+      } };
+    }
+    if (!validator) return { ok: true, value: instance };
+    let validation: AgentToolValidationResult;
+    try {
+      const rawValidation = await validator.validate(instance);
+      if (!validationResultIsValid(rawValidation)) throw new AgentToolExecutionError("schema validator returned an invalid result.");
+      validation = rawValidation;
+    } catch (error) {
+      return { ok: false, error: {
+        code: "TOOL_SCHEMA_VALIDATION_FAILED",
+        message: `Tool ${direction} schema validation failed: ${toolErrorMessage(error)}`,
+        details: details(),
+      } };
+    }
+    if (!validation.isValid) return { ok: false, error: {
+      code: direction === "input" ? "TOOL_INPUT_VALIDATION_FAILED" : "TOOL_OUTPUT_VALIDATION_FAILED",
+      message: `Tool "${toolName}" ${direction} failed schema validation.`,
+      details: { ...details(), issues: normalizeValidationIssues(validation.errors) },
+    } };
+    return { ok: true, value: instance };
+  }
+}
+
+export function toolContractName(model: Class<object>): string {
+  return model.name && model.name.trim().length > 0 ? model.name : "<anonymous class>";
+}
+
+export function toolErrorMessage(value: unknown): string {
+  try {
+    return value instanceof Error && typeof value.message === "string" ? value.message : String(value);
+  } catch {
+    return "Unknown error.";
+  }
+}
+
+function normalizeValidationIssues(errors: readonly AgentToolValidationIssue[]): JsonValue {
+  const issues: JsonValue[] = [];
+  for (let index = 0; index < errors.length; index += 1) {
+    const error = errors[index] as AgentToolValidationIssue;
+    const issue: Record<string, JsonValue> = {
+      property: typeof error.property === "string" ? error.property : toolErrorMessage(error.property),
+      message: typeof error.message === "string" ? error.message : toolErrorMessage(error.message),
+    };
+    if (error.code !== undefined) {
+      issue.code = toolErrorMessage(error.code);
+    }
+    issues.push(Object.freeze(issue));
+  }
+  return Object.freeze(issues);
+}
+
+function validationResultIsValid(value: unknown): value is AgentToolValidationResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { isValid?: unknown }).isValid === "boolean" &&
+    Array.isArray((value as { errors?: unknown }).errors)
+  );
+}
+