@anteros/core 0.0.44 → 0.0.47

package/types/agent.d.ts

@@ -1,4 +1,5 @@
 import type Joi from "joi";
+import type { z } from "zod";
 import type { useRest } from "../database/rest";
 import type { fn } from "../lib/error";
 import type { jwt } from "../utils/func";
@@ -55,6 +56,75 @@ export type AgentProvider = {
     headers?: Record<string, string>;
     /** Sampling and transport — `{ temperature, maxTokens, topP, timeout, retries }`. */
     options?: AgentOptions;
+    /**
+     * Tried **in order** when the primary fails for a reason another endpoint may not
+     * have: `429`, `5xx`, a network error or a timeout. `options` are merged over the
+     * primary's, so a fallback only states what differs.
+     */
+    fallbacks?: AgentFallback[];
+    /**
+     * USD per **million** tokens — turns `usage` into `usage.cost`. A fallback may
+     * price differently: the model that answered is the one billed.
+     */
+    pricing?: AgentPricing;
+};
+
+/** One step of `provider.fallbacks` — what may differ from the primary. */
+export type AgentFallback = {
+    model: string;
+    apiKey?: string;
+    protocol?: AgentProtocol;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    options?: AgentOptions;
+    pricing?: AgentPricing;
+};
+
+/** Cost of a model, per million tokens (USD). */
+export type AgentPricing = {
+    /** USD per million **input** tokens. */
+    input: number;
+    /** USD per million **output** tokens. */
+    output: number;
+};
+
+/**
+ * A guardrail — a check that can **stop** a run. `check` throws to block; the
+ * thrown message is what the caller reads.
+ */
+export type AgentGuardrail = {
+    /** Named in the error, so a failing check is identifiable. */
+    name: string;
+    check: (value: string, ctx: AgentGuardrailContext) => void | Promise<void>;
+};
+
+/** Where a guardrail runs. The lists are additive: declaration first, then the call. */
+export type AgentGuardrails = {
+    /** Before the first model call — the caller's prompt (the last user turn). */
+    input?: AgentGuardrail[];
+    /** Before the answer is returned or stored — what the model produced. */
+    output?: AgentGuardrail[];
+    /**
+     * After a tool **succeeded**, on its serialized result, before the model sees
+     * it (a tool result can carry what the prompt may not).
+     *
+     * A check that throws blocks **that result**, not the run: the model reads
+     * `Error [AGENT_GUARDRAIL_BLOCKED]: …` and goes on. A failed tool result is
+     * never checked.
+     */
+    tool?: AgentGuardrail[];
+};
+
+export type AgentGuardrailContext = {
+    agent: Agent;
+    tenant?: string;
+    thread?: string;
+    resource?: string;
+    signal: AbortSignal;
+    /** Set when the check runs on a **tool result** — the tool's name. */
+    tool?: string;
+    /** Set when the check runs on a tool result — the call it answers. */
+    toolCallId?: string;
 };
 
 /**
@@ -238,7 +308,13 @@ export type AgentToolMessage = {
     /** Id of the `tool_use` / `tool_call` this message answers. */
     toolCallId: string;
     name: string;
-    content: string;
+    /**
+     * What the model reads. Text is the default; a tool may also return **media**
+     * (`{ content: [{ type: 'image', … }] }`) — Anthropic receives the image as a
+     * `tool_result` block, OpenAI only text plus a marker (its tool message is
+     * text-only), and the stored thread keeps a marker, never the base64.
+     */
+    content: string | AgentMediaPart[];
     isError?: boolean;
 };
 
@@ -291,6 +367,12 @@ export type AgentToolResultEntry = {
     result?: any;
     /** Set when the tool threw, was unknown, or its arguments were invalid. */
     error?: string;
+    /**
+     * Stable code of that failure — `AGENT_TOOL_FAILED`, `AGENT_TOOL_TIMEOUT`,
+     * `AGENT_TOOL_ARGS_INVALID`, `AGENT_TOOL_UNKNOWN`, or the `AppError` code the
+     * tool threw. The model reads it as `Error [CODE]: message`, so it can branch.
+     */
+    errorCode?: string;
     durationMs: number;
 };
 
@@ -303,6 +385,8 @@ export type AgentUsage = {
     totalTokens: number;
     /** How many model calls the run needed (1 + one per tool round). */
     requests: number;
+    /** USD, when the provider declares `pricing` (delegated runs included). */
+    cost?: number;
 };
 
 /** One model call of a run, with the tools it asked for. */
@@ -364,6 +448,12 @@ export type AgentTool = {
     /** Shown to the model — say what it does and when to use it. */
     description?: string;
     enabled?: boolean;
+    /**
+     * The tool only **reads** — it may run concurrently with the other read-only
+     * tools of the same step, even when `parallelTools` is off. A tool that writes
+     * stays sequential: two writes must not interleave.
+     */
+    readOnly?: boolean;
     /** Arguments schema: Joi, zod or a plain JSON Schema (defaults to an open object). */
     inputSchema?: Joi.Schema | any;
     /** Handler. The returned value is serialized back to the model. */
@@ -387,8 +477,26 @@ export type AgentTool = {
     approval?: boolean;
 };
 
-/** What a tool must carry to be **declared** — `define.Tool` enforces the id. */
-export type AgentToolDefinition = AgentTool & { id: string };
+/**
+ * What a tool must carry to be **declared** — `define.Tool` enforces the `id`
+ * **and** the `description`: a tool the model cannot understand is a tool it cannot
+ * choose, so both are required at the type level.
+ *
+ * `TInput` is the handler's input. It is **inferred** from a zod schema
+ * (`z.output`); Joi has no type inference, so give it explicitly:
+ *
+ * ```ts
+ * define.Tool({ inputSchema: z.object({ city: z.string() }), execute: ({ city }) => … });
+ * define.Tool<{ city: string }>({ inputSchema: v.object({ city: … }), execute: ({ city }) => … });
+ * ```
+ */
+export type AgentToolDefinition<TInput = any> = Omit<AgentTool, "inputSchema" | "execute"> & {
+    id: string;
+    description: string;
+    /** Joi (`v`), zod, or a plain JSON Schema. */
+    inputSchema?: Joi.Schema | z.ZodType | any;
+    execute?: (input: TInput, ctx: AgentToolContext) => any | Promise<any>;
+};
 
 export type AgentTools = Record<string, AgentTool> | AgentTool[];
 
@@ -457,6 +565,83 @@ export type AgentMemoryProcessor = {
     ) => AgentMessage[] | void | Promise<AgentMessage[] | void>;
 };
 
+/** One hit returned by the vector search of a semantic-recall processor. */
+export type AgentRecallHit = {
+    /** Stable id of the indexed message — the one `upsert` stored. */
+    id?: string;
+    /** The text to put back in the prompt (the store may expand `messageRange`). */
+    text: string;
+    role?: string;
+    thread?: string;
+    resourceId?: string;
+    score?: number;
+};
+
+/** One message handed to the vector store by the recall processor. */
+export type AgentRecallRecord = {
+    id: string;
+    text: string;
+    vector: number[];
+    thread?: string;
+    resourceId?: string;
+    role?: string;
+};
+
+/** What a recall processor asks the vector store — Mastra's `semanticRecall` options. */
+export type AgentRecallQuery = {
+    /** Number of similar messages to retrieve. */
+    topK: number;
+    /** Surrounding messages the store should include with each hit. */
+    messageRange: number;
+    /** Search the current thread only, or every thread of the caller. */
+    scope: "thread" | "resource";
+    /** Metadata criteria, applied by the store when it supports them. */
+    filter?: Record<string, unknown>;
+    /** The run's thread (scoping the search). */
+    thread?: string;
+    /** The run's caller (namespacing the search). */
+    resourceId?: string;
+};
+
+/**
+ * Options of `agents.memory.semanticRecall()` — the framework's processor-shaped
+ * projection of Mastra's `semanticRecall`.
+ *
+ * Mapping: Mastra's `embedder` → `embed`, `vector.search` → `search`,
+ * `vector.upsert` → `upsert`, and `options.semanticRecall` → `topK`,
+ * `messageRange`, `scope`, `filter`.
+ */
+export type AgentSemanticRecallOptions = {
+    /**
+     * Embed texts. `kind` separates the two sides of an asymmetric model:
+     * `'query'` for the current question, `'passage'` for indexed messages
+     * (E5 wants `query:` / `passage:` prefixes).
+     */
+    embed: (texts: string[], kind: "query" | "passage") => Promise<number[][]> | number[][];
+    /**
+     * Vector search — return `[]` when nothing is close enough. `ctx` is the run
+     * context: a Mongo-backed store reaches the tenant database through `ctx.rest`.
+     */
+    search: (vector: number[], query: AgentRecallQuery, ctx: AgentMemoryContext) => Promise<AgentRecallHit[]> | AgentRecallHit[];
+    /**
+     * Index messages. Optional: without it the processor only **recalls** from an
+     * index you fill elsewhere (a job, `remember()`, another writer). Should be
+     * idempotent — the same `id` may be written again after a restart. `ctx` is
+     * the run context, with the same `rest` as `search`.
+     */
+    upsert?: (records: AgentRecallRecord[], ctx: AgentMemoryContext) => Promise<void> | void;
+    /** Similar messages retrieved (default `3`). */
+    topK?: number;
+    /** Messages around each hit, left to the store (default `2`). */
+    messageRange?: number;
+    /** `'thread'` (default) or `'resource'` — the caller's other conversations. */
+    scope?: "thread" | "resource";
+    /** Metadata filter forwarded to the store. */
+    filter?: Record<string, unknown>;
+    /** How the hits are rendered into the injected system message. */
+    format?: (hits: AgentRecallHit[]) => string;
+};
+
 /** What a memory store knows about the run asking for a thread. */
 export type AgentMemoryContext = {
     agentId?: string;
@@ -502,6 +687,36 @@ export type AgentMemoryOptions = {
     scoped?: boolean;
 };
 
+/**
+ * Options of `agents.memory.custom()` — your own storage behind the `AgentMemory`
+ * contract, with the framework's scoping (`scoped`) and message cap
+ * (`maxMessages`) applied for you.
+ *
+ * A handler receives the **resolved key**: `resourceId:threadId` when `scoped`
+ * (default) and a caller identity is present, the bare thread id otherwise. The
+ * caller's context (`thread`, `resourceId`, `agentId`, `tenant`, `rest`) travels
+ * as the second argument, so a handler can key on whatever it needs.
+ */
+export type CustomAgentMemoryOptions = AgentMemoryOptions & {
+    /** A label for logs and error messages (default `'custom'`). */
+    name?: string;
+    /** Read a thread — `[]` when it does not exist. */
+    get: (key: string, ctx: AgentMemoryContext) => Promise<AgentMessage[]> | AgentMessage[];
+    /** Persist a thread — `messages` is already capped to `maxMessages`. */
+    save: (key: string, messages: AgentMessage[], ctx: AgentMemoryContext) => Promise<void> | void;
+    /** Forget a thread. */
+    clear: (key: string, ctx: AgentMemoryContext) => Promise<void> | void;
+    /** The caller's threads, most recent first (needed by a chat UI). */
+    list?: (ctx: AgentMemoryContext & { limit?: number }) => Promise<AgentThread[]> | AgentThread[];
+    /** Working memory — one durable value per scope key. */
+    getState?: (key: string, ctx: AgentMemoryContext) => Promise<AgentMemoryState | undefined> | AgentMemoryState | undefined;
+    setState?: (key: string, value: AgentMemoryState, ctx: AgentMemoryContext) => Promise<void> | void;
+    /** Forget a scratchpad. */
+    clearState?: (key: string, ctx: AgentMemoryContext) => Promise<void> | void;
+    /** Storage collections to replicate (Mongo-backed stores only). */
+    collections?: () => string[];
+};
+
 /**
  * The agent's **working memory** — a durable scratchpad it keeps up to date
  * (a user profile, the state of a task):
@@ -632,6 +847,49 @@ export type AgentResume = {
     decisions: Record<string, boolean>;
 };
 
+/**
+ * What a run leaves behind at a step boundary — enough to continue it later
+ * (`agent.resumeRun()`), whatever killed the process in between.
+ *
+ * The conversation is **always valid**: an assistant turn with unanswered tool
+ * calls is never stored, so replaying it back to the model is safe.
+ */
+export type AgentRunState = {
+    runId: string;
+    agentId?: string;
+    /** Completed steps. */
+    step: number;
+    /** The whole conversation as of the last completed step — always valid (no unanswered tool call). */
+    messages: AgentMessage[];
+    usage: AgentUsage;
+    toolStats: AgentToolStats;
+    model?: string;
+    finishReason?: string;
+    /** ISO timestamp. */
+    at: string;
+};
+
+/**
+ * Durable checkpoint of a run — one state per run id, overwritten at every step
+ * boundary and cleared when the run completes.
+ *
+ * ```ts
+ * const checkpoint: AgentRunStore = {
+ *   load: (runId) => runs.get(runId),
+ *   save: (runId, state) => { runs.set(runId, state); },
+ *   clear: (runId) => { runs.delete(runId); },
+ * };
+ * ```
+ *
+ * The three methods may be synchronous; a failure of `save` never fails the run
+ * (it is logged), and the run id is the caller's identity for that run.
+ */
+export type AgentRunStore = {
+    load(runId: string): Promise<AgentRunState | undefined> | AgentRunState | undefined;
+    save(runId: string, state: AgentRunState): Promise<void> | void;
+    clear(runId: string): Promise<void> | void;
+};
+
 export type AgentCallOptions = {
     /** Thread to read from / write to the memory (same as `memory.thread`). */
     thread?: string;
@@ -730,6 +988,23 @@ export type AgentCallOptions = {
     };
     /** Called after each model call, before its tools run. */
     onStepFinish?: (step: AgentStep) => void | Promise<void>;
+    /**
+     * Observations of this run — see `AgentTraceEvent`. Overrides the agent's
+     * `onTrace`; a hook that throws is ignored (it never fails the run).
+     */
+    onTrace?: (event: AgentTraceEvent) => void;
+    /**
+     * Identifies this run in the trace (`run.start.runId`) — and the key of its
+     * durable checkpoint: with a `checkpoint` store, the run saves its state after
+     * every completed step under this id, and `agent.resumeRun(runId)` continues it.
+     * No `runId` means no checkpoint (a run without identity cannot be resumed).
+     */
+    runId?: string;
+    /**
+     * Where this run's state is saved after each completed step — overrides the
+     * agent's `checkpoint` for this call. Needs a `runId`.
+     */
+    checkpoint?: AgentRunStore;
     /**
      * Give up on a single tool after N ms (default: the agent's `toolTimeoutMs`).
      * A tool that times out is reported to the model as an error, and the run goes on.
@@ -739,9 +1014,25 @@ export type AgentCallOptions = {
      * Run the tools of one step **in parallel** (default `false` — sequential).
      *
      * Only safe when the tools do not write to the same place: two calls of the same
-     * tool with the same target can interleave. Read-only tools are the point.
+     * tool with the same target can interleave. Read-only tools (`readOnly: true`)
+     * already run together without this flag.
      */
     parallelTools?: boolean;
+    /**
+     * How many tool calls of one step may be in flight at once (default `8`).
+     * A model that emits 50 calls in a turn must not open 50 outbound requests.
+     */
+    maxParallelToolCalls?: number;
+    /** Stop cleanly (`finishReason: 'budget'`) once the run used that many tokens. */
+    maxTokens?: number;
+    /** Stop cleanly once the run has lasted that long, in milliseconds. */
+    maxDurationMs?: number;
+    /** Stop cleanly once the run cost that much (USD) — needs `provider.pricing`. */
+    maxCost?: number;
+    /** Prompt budget in **tokens** — the oldest turns are dropped beyond it. */
+    contextTokens?: number;
+    /** Input/output guardrails for this run — added to the declared ones. */
+    guardrails?: AgentGuardrails;
     /**
      * Store what the run produced even when it **fails** (default `false`).
      *
@@ -757,6 +1048,41 @@ export type AgentCallOptions = {
     resume?: AgentResume;
 };
 
+/** Aggregate of the tool calls of one run — what `result.toolStats` carries. */
+export type AgentToolStats = {
+    /** Calls executed (unknown tools and invalid arguments included). */
+    calls: number;
+    /** Calls that failed, whatever the cause. */
+    errors: number;
+    /** Failures by code (`AGENT_TOOL_TIMEOUT`, `AGENT_TOOL_UNKNOWN`…). */
+    byCode: Record<string, number>;
+    /** Abandoned at their deadline (`AGENT_TOOL_TIMEOUT`). */
+    timeouts: number;
+    /** Sum of the durations of every call, in milliseconds. */
+    durationMs: number;
+};
+
+/**
+ * One milestone of a run, handed to `onTrace` — a **plain** event, not a span.
+ *
+ * `at` is `Date.now()`; turning the events into spans (durations, parents,
+ * attributes) is the caller's job, so no tracing dependency is involved.
+ *
+ * ```ts
+ * const agent = new Agent({
+ *   …,
+ *   onTrace: (event) => console.log(event.type, event.at),
+ * });
+ * ```
+ */
+export type AgentTraceEvent =
+    | { type: "run.start"; at: number; agentId?: string; runId?: string; thread?: string; resource?: string }
+    | { type: "step.start"; at: number; step: number }
+    | { type: "model.end"; at: number; step: number; durationMs: number; model: string; usage: AgentUsage; finishReason: string }
+    | { type: "tool.start"; at: number; step: number; tool: string; toolCallId: string }
+    | { type: "tool.end"; at: number; step: number; tool: string; toolCallId: string; durationMs: number; errorCode?: string }
+    | { type: "run.end"; at: number; finishReason: string; durationMs: number; usage: AgentUsage; toolStats: AgentToolStats; error?: string };
+
 export type AgentGenerateResult<T = any> = {
     text: string;
     /** Present when a `schema` / `structuredOutput` was requested. */
@@ -765,11 +1091,17 @@ export type AgentGenerateResult<T = any> = {
     reasoning?: string;
     toolCalls: AgentToolCall[];
     toolResults: AgentToolResultEntry[];
+    /** Aggregate of every tool call of the run — counts, failures, time. */
+    toolStats: AgentToolStats;
     steps: AgentStep[];
     usage: AgentUsage;
     finishReason: string;
     /** The complete conversation, ready to be persisted. */
     messages: AgentMessage[];
+    /** The model that answered (a fallback may have been used). */
+    model?: string;
+    /** Present when the run stopped on a budget rather than on an answer. */
+    budget?: { limit: "tokens" | "cost" | "duration"; value: number };
     /**
      * Calls waiting for a decision — present (and `finishReason`
      * `'approval_required'`) when a tool declaring `approval: true` was called.
@@ -787,6 +1119,12 @@ export type AgentStreamChunk =
     | { type: "tool_call"; toolCall: AgentToolCall }
     | { type: "tool_result"; toolResult: AgentToolResultEntry }
     | { type: "step"; step: AgentStep }
+    /**
+     * A chunk of a **delegated** run, re-emitted by the parent while the sub-agent
+     * streams — `name` is the child's id. Only emitted when the parent streams;
+     * the child's text never reaches the parent's `textStream`.
+     */
+    | { type: "subagent"; name: string; chunk: AgentStreamChunk }
     | { type: "finish"; finishReason: string; usage: AgentUsage };
 
 /**
@@ -804,6 +1142,12 @@ export type AgentStreamResult<T = any> = {
     object: Promise<T | undefined>;
     toolCalls: Promise<AgentToolCall[]>;
     toolResults: Promise<AgentToolResultEntry[]>;
+    /** Aggregate of every tool call of the run — same as `generate()`. */
+    toolStats: Promise<AgentToolStats>;
+    /** The model that answered (a fallback may have been used). */
+    model: Promise<string | undefined>;
+    /** Present when the run stopped on a budget. */
+    budget: Promise<{ limit: "tokens" | "cost" | "duration"; value: number } | undefined>;
     steps: Promise<AgentStep[]>;
     usage: Promise<AgentUsage>;
     finishReason: Promise<string>;
@@ -812,6 +1156,21 @@ export type AgentStreamResult<T = any> = {
     abort: (reason?: string) => void;
 };
 
+/**
+ * `agent.streamObject()` result — everything `stream()` returns, plus the
+ * objects parsed from the text as it arrives.
+ *
+ * `partialObjectStream` **consumes** the run's text, so a caller chooses either
+ * `textStream` or `partialObjectStream` — not both.
+ */
+export type AgentStreamObjectResult<T = any> = AgentStreamResult<T> & {
+    /**
+     * A best-effort parse of the answer so far — `undefined` until the partial
+     * JSON parses. The final, **validated** object is `result.object`.
+     */
+    partialObjectStream: AsyncIterable<T | undefined>;
+};
+
 /** Instructions — static text, or computed per call (A/B tests, dynamic prompts). */
 export type AgentInstructions =
     | string
@@ -987,8 +1346,31 @@ export type AgentConfig = {
     toolTimeoutMs?: number;
     /** Run the tools of one step in parallel by default — see `AgentCallOptions`. */
     parallelTools?: boolean;
+    /** Cap the tool calls in flight per step — see `AgentCallOptions`. */
+    maxParallelToolCalls?: number;
+    /** Default run budget in tokens — see `AgentCallOptions.maxTokens`. */
+    maxTokens?: number;
+    /** Default wall-clock budget of a run, in milliseconds. */
+    maxDurationMs?: number;
+    /** Default cost budget (USD) — needs `provider.pricing`. */
+    maxCost?: number;
+    /** Default prompt budget in tokens — see `AgentCallOptions.contextTokens`. */
+    contextTokens?: number;
+    /** Guardrails of every run — input before the first call, output before the answer. */
+    guardrails?: AgentGuardrails;
     /** Store a failed run's conversation by default — see `AgentCallOptions`. */
     savePartial?: boolean;
+    /**
+     * Default durable checkpoint — a run that declares a `runId` saves its state
+     * after each completed step there, and `resumeRun()` continues it. A call's own
+     * `checkpoint` wins. See `AgentRunStore`.
+     */
+    checkpoint?: AgentRunStore;
+    /**
+     * Observe every run of this agent — see `AgentTraceEvent`. A call's own
+     * `onTrace` takes precedence; a hook that throws never fails the run.
+     */
+    onTrace?: (event: AgentTraceEvent) => void;
     /**
      * Other agents exposed to this one **as tools** — the model decides when to
      * delegate: `agents: [researcher]` (an agent definition, usually the default

package/types/config.d.ts

@@ -110,9 +110,42 @@ export type ServerConfig = {
             denyList?: IPRestrictionRule[];
             allowList?: IPRestrictionRule[];
         }
+        /**
+         * Security headers (Hono `secureHeaders`).
+         *
+         * `crossOriginResourcePolicy` sets `Cross-Origin-Resource-Policy` on the
+         * API responses. The default (`'same-origin'`) blocks another origin (a
+         * front served from a different host) from embedding them — an `<img
+         * src="https://api…">` then fails with `corp-not-same-origin`.
+         * Set `'cross-origin'` to allow embedding, or keep the default for an
+         * API only consumed by same-origin scripts.
+         */
+        security?: {
+            crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin';
+        }
+        /**
+         * File serving (`GET /api/:tenant_id/files/:collection/:filename`).
+         */
+        files?: {
+            /**
+             * `Cross-Origin-Resource-Policy` on file responses (default:
+             * `'cross-origin'` — files are meant to be embedded by the app,
+             * possibly served from another origin). Set `'same-origin'` to
+             * forbid cross-origin embedding (tightest), or `'same-site'`.
+             */
+            crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin';
+        }
         jwt?: {
             secret?: string;
             expiresIn?: string;
+            /**
+             * Reject a token that carries **no tenant claim** (default `false`).
+             *
+             * Tokens issued by the login action always carry `tenant` (the claim is
+             * injected by the framework). Legacy tokens issued before that change have
+             * no claim: set this to `true` once they have expired to require one.
+             */
+            requireTenantClaim?: boolean;
         }
         rateLimit?: {
             enabled?: boolean;
@@ -139,16 +172,37 @@ export type ServerConfig = {
             level?: 'debug' | 'info' | 'warn' | 'error';
             /** Also write to the console (default: true) */
             console?: boolean;
-            /** File logging: true → <dir>/anteros.log, string → custom path, false → disabled (default: true) */
+            /** File logging: true → <dir>/app.log, string → custom path, false → disabled (default: true) */
             file?: boolean | string;
             /** Directory used when `file` is true (default: '.logs') */
             dir?: string;
-            /** Rotate when the log file exceeds this size in bytes (default: 10MB) */
+            /** Rotation trigger (default: 'size'): size | hourly | daily | weekly | monthly | yearly */
+            rotate?: 'size' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly';
+            /** Rotate when the log file exceeds this size in bytes — `rotate: 'size'` only (default: 10MB) */
             maxSize?: number;
             /** Keep this many rotated files (default: 5) */
             maxFiles?: number;
             /** Log database operations slower than this many ms (default: 200) */
             slowQueryMs?: number;
+            /** HTTP access-log options (everything about requests) */
+            http?: {
+                /** Write the per-request access log (default: true) */
+                enabled?: boolean;
+                /** Capture raw request bodies in the access log (default: false) — may contain secrets, file only */
+                body?: boolean;
+                /** HTTP methods whose body is captured (default: GET, POST, PUT, PATCH, DELETE); [] disables it */
+                methods?: string[];
+                /** Max bytes captured per request body (default: 65536); beyond is truncated */
+                maxBodyBytes?: number;
+                /** @deprecated Use `logging.http.body`. */
+                captureBody?: boolean;
+                /** @deprecated Use `logging.http.methods`. */
+                captureMethods?: string[];
+            };
+            /** @deprecated Use `logging.http.captureBody`. */
+            captureBody?: boolean;
+            /** @deprecated Use `logging.http.maxBodyBytes`. */
+            maxBodyBytes?: number;
         };
         /** DB query caching (find + useCache) — driver + defaults for the query cache */
         cache?: {

package/types/file.d.ts

@@ -50,7 +50,7 @@ export type FileCollection = {
         /** Allowed MIME types for upload.
          * @example ['image/jpeg', 'image/png', 'application/pdf'] */
         allowedMimeTypes?: string[];
-        /** Maximum file size in bytes. Default: 10MB */
+        /** Maximum file size in bytes. Default: 100MB (a larger body than `server.body.maxSize` still hits the request body limit) */
         maxSize?: number;
         /**
          * Image transformations (resize, format, etc.).

package/types/mcp.d.ts

@@ -16,7 +16,7 @@ export type McpToolResult = {
 };
 
 /**
- * MCP tool definition — auto-loaded from `{tenant.dir}/mcp/tools/**\/*.tool.ts`.
+ * MCP tool definition — auto-loaded from `{tenant.dir}/ai/mcp/tools/**\/*.tool.ts`.
  * Served over the MCP protocol at `GET/POST /api/:tenant_id/mcp` (Streamable HTTP).
  */
 export type McpTool = {
@@ -58,7 +58,7 @@ export type McpResourceResult = {
 
 /**
  * MCP resource — read-only data exposed by URI (like a file the LLM can open).
- * Auto-loaded from `{tenant.dir}/mcp/resources/**\/*.resource.ts`.
+ * Auto-loaded from `{tenant.dir}/ai/mcp/resources/**\/*.resource.ts`.
  *
  * The `uri` can be static (`orders://summary`) or a template
  * (`users://{id}`) — template params are extracted and passed to `read`.

package/utils/func.ts

@@ -912,6 +912,24 @@ function clone<T>(data: T): T {
 const MAX_REGEX_LENGTH = 1000;
 const MAX_IN_ARRAY_SIZE = 10000;
 
+/** Filter operators a client must never reach MongoDB with (JS execution). */
+const FORBIDDEN_MATCH_KEYS = ['$where', '$expr', '$accumulator', '$function'];
+
+/** Bound and sanitize a raw Mongo filter (#45) — same rules as `find`.
+ *  Used by internal methods that accept a filter directly (`findOneAndUpdate`,
+ *  `bulkWrite`, `bulkUpdate`, `countDocuments`). */
+function assertSafeFilter(filter: unknown): void {
+    if (filter === null || filter === undefined || typeof filter !== 'object') return;
+    const forbidden = hasUnauthorizedKeys(filter, FORBIDDEN_MATCH_KEYS);
+    if (forbidden.length > 0) {
+        throw new AppError('Unauthorized match keys: ' + forbidden.join(', '), {
+            code: 'UNAUTHORIZED_MATCH_KEYS',
+            status: 400,
+        });
+    }
+    boundMatchOperators(filter);
+}
+
 function boundMatchOperators(node: unknown): void {
     if (node === null || node === undefined) return;
 
@@ -1240,6 +1258,8 @@ function parseDuration(value: string | number): number | null {
 }
 
 export {
+    assertSafeFilter,
+    boundMatchOperators,
     buildPipeline,
     reorder,
     omit,