@anteros/core 0.0.40 → 0.0.42

package/types/collection.d.ts

@@ -8,6 +8,7 @@ import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
 import type { ActionsApiList, ApiAccess, ApiActions } from "./api";
 import type { Server as SocketIO } from "socket.io";
+import type { CollectionReplicationConfig } from "./replication";
 
 /** Context passed to a collection custom action (`define.Action`). */
 export type CollectionActionContext = {
@@ -85,6 +86,8 @@ export type Collection = {
         /** Default TTL for cached queries — human string ('5m', '2h') or ms */
         ttl?: string | number;
     };
+    /** Opt-in one-way replication to destination databases — see `ReplicationConfig`. */
+    replication?: CollectionReplicationConfig;
     /**
      * The tenant id of the collection
      * @type {string}

package/types/config.d.ts

@@ -7,6 +7,9 @@ import type { Service } from "./service";
 import type { Script } from "./scripts";
 import type { FileCollection } from "./file";
 import type { McpTool, McpResource } from "./mcp";
+import type { VarDefinition } from "./vars";
+import type { AgentDefinition } from "./agent";
+import type { AuditFileConfig } from "../lib/audit";
 export type ServerConfig = {
     debug?: boolean;
     version?: string;
@@ -21,9 +24,82 @@ export type ServerConfig = {
         metricsPort?: number;
         /** When true, trusts proxy headers (CF-Connecting-IP / X-Forwarded-For) as the client IP. Default: false. */
         trustProxy?: boolean;
+        /**
+         * Audit trail defaults for every tenant. A tenant declaring its own
+         * `tenant.audit` always wins (even `false`).
+         */
+        audit?: {
+            /**
+             * How long `_audit_` entries are kept (MongoDB TTL on `ts`).
+             * Duration string: `'90d'`, `'24h'`.
+             * `false` → explicitly disabled (drops the TTL index if one exists).
+             * Omitted → untouched: entries are kept forever.
+             */
+            retention?: string | false;
+            /**
+             * Local append-only JSONL copy of the audit trail (one file per day,
+             * rotated on size, pruned by age).
+             * `true` → defaults, `string` → directory, object → full options.
+             * `false` / omitted → disabled.
+             */
+            file?: AuditFileConfig;
+            /**
+             * Object keys whose value is replaced by `"[redacted]"` in every audit
+             * entry (`operation.input`, `operation.result` and `meta`), at any depth,
+             * case-insensitively. `false` → disabled.
+             *
+             * Default: password, passwd, pwd, token, authorization, apikey, api_key,
+             * key, secret, cookie, otp, pin.
+             */
+            redact?: string[] | false;
+            /**
+             * What an audit entry keeps of the operation's **result**
+             * (default: `'summary'`).
+             *
+             * - `'summary'` (default) → the **generated identifiers** (`_id`,
+             *   `insertedIds`) plus the operational counters (`matchedCount`,
+             *   `modifiedCount`, `deletedCount`, `nIndexesWas`…). Never a document:
+             *   the data lives in the collection (and in its replications).
+             * - `'none'`    → the generated identifiers only.
+             * - `'full'`    → the raw result, documents included.
+             *
+             * Reads (`find`, `findOne`, `aggregate`, streams, `watch`) and custom
+             * actions/services never store a result, whatever this setting.
+             */
+            results?: 'none' | 'summary' | 'full';
+        };
+        /**
+         * Workflow defaults for every tenant — a tenant declaring its own
+         * `tenant.workflows` always wins.
+         */
+        workflows?: {
+            /**
+             * How long **finished** workflow runs are kept (MongoDB TTL on
+             * `completedAt`). Duration string: `'30d'`, `'90d'`.
+             * `false` → explicitly disabled. Omitted → untouched.
+             */
+            retention?: string | false;
+        };
         body?: {
             maxSize?: number;
         };
+        /**
+         * Boot mode (default: `'full'`).
+         *
+         * - `'full'` — HTTP API **and** the replication engine.
+         * - `'replication-only'` — a process dedicated to the replication engine: no
+         *   HTTP API, no websocket handlers, no scripts, no services, no MCP tools,
+         *   no middlewares. Loaded: tenant databases, collections, file collections,
+         *   variables and lifecycle hooks (`beforeBoot` / `onDestroy`).
+         * - `'no-replication'` — a full server that never starts the replication
+         *   engine (no scheduling, no tombstones, no `_replication_` state).
+         * - `'api-only'` — the HTTP API and nothing around it: no replication, no
+         *   scripts, no sockets.
+         *
+         * Flags always win over this setting: `--replication-only`, `--no-replication`,
+         * `--api-only`, `--no-scripts`, `--no-sockets`.
+         */
+        mode?: 'full' | 'replication-only' | 'no-replication' | 'api-only';
         cors?: {
             origin: string | string[] | ((ctx: { origin: string, c: Context }) => string | string[]);
             credentials?: boolean;
@@ -123,4 +199,8 @@ export type Config = ServerConfig & {
     fileCollections?: FileCollection[]
     mcpTools?: McpTool[]
     mcpResources?: McpResource[]
+    vars?: VarDefinition[]
+    agents?: AgentDefinition[]
+    /** Mongo collections used as agent memory — published by `syncAgents()` (see the Memory page). */
+    agentMemories?: Array<{ _tenant_: string; collection: string }>
 }

package/types/file.d.ts

@@ -4,6 +4,7 @@ import type { HooksCollection } from "./hook";
 import type Joi from "joi";
 import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
+import type { CollectionReplicationConfig } from "./replication";
 
 type FileAccessHandler = (ctx: {
     rest: InstanceType<typeof useRest>;
@@ -15,11 +16,11 @@ type FileAccessHandler = (ctx: {
 type FileApiAccess = {
     /** Default access rule applied when no per-operation rule is set */
     '*'?: boolean | FileAccessHandler;
-    /** Access control for POST /upload/:tenant_id/:slug */
+    /** Access control for POST /api/:tenant_id/upload/:slug */
     upload?: boolean | FileAccessHandler;
-    /** Access control for GET /files/:tenant_id/:slug/:file */
+    /** Access control for GET /api/:tenant_id/files/:slug/:file */
     read?: boolean | FileAccessHandler;
-    /** Access control for DELETE /files/:tenant_id/:slug/:file */
+    /** Access control for DELETE /api/:tenant_id/files/:slug/:file */
     delete?: boolean | FileAccessHandler;
 };
 
@@ -30,11 +31,11 @@ type FileApiAccess = {
  * for handling file uploads, storage, and serving.
  *
  * Each file collection generates:
- *   POST   /upload/:tenant_id/:slug       — upload a file
- *   GET    /files/:tenant_id/:slug/:file  — serve/download a file
+ *   POST   /api/:tenant_id/upload/:slug       — upload a file
+ *   GET    /api/:tenant_id/files/:slug/:file  — serve/download a file
  */
 export type FileCollection = {
-    /** Unique identifier used in routes: `/upload/:tenant_id/:slug` */
+    /** Unique identifier used in routes: `/api/:tenant_id/upload/:slug` */
     slug: string;
     hooks?: {
         beforeOperation?: HooksCollection['beforeOperation'];
@@ -42,6 +43,8 @@ export type FileCollection = {
     };
     /** Metadata fields stored alongside the file document */
     fields?: Field[];
+    /** Opt this file collection into the data replication engine (its documents). */
+    replication?: CollectionReplicationConfig;
     /** Upload validation rules */
     upload?: {
         /** Allowed MIME types for upload.
@@ -51,7 +54,7 @@ export type FileCollection = {
         maxSize?: number;
         /**
          * Image transformations (resize, format, etc.).
-         * Applied on-the-fly when serving via GET /files/:tenant_id/:slug/:file
+         * Applied on-the-fly when serving via GET /api/:tenant_id/files/:slug/:file
          */
         transformations?: {
             /** Resize to max width in pixels */
@@ -103,7 +106,7 @@ export type FileCollection = {
             /** Private key path for SSH auth */
             privateKey?: string;
         }[];
-        /** Enregistrer les métadonnées du fichier en base. Défaut: true */
+        /** Save the file metadata in the database. Default: true */
         trackMetaData?: boolean;
     api?: {
         access?: FileApiAccess;

package/types/hook.d.ts

@@ -1,6 +1,8 @@
 import type { MongoRest } from "../database/mongodbadapter";
 import type { Server as SocketIO } from "socket.io";
 import type { ActionsApiList } from "./api";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
 
 export type HookMeta = {
     action: ActionsApiList;
@@ -19,6 +21,10 @@ export type HookMeta = {
 /** Context passed to a collection hook (`define.Hook`). */
 export type HookContext = {
     rest: MongoRest;
+    /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+    agents: TenantAgents;
+    /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+    api: Api;
     action: ActionsApiList;
     meta: HookMeta;
     io: SocketIO;

package/types/lifecycle.d.ts

@@ -0,0 +1,77 @@
+import type { useRest } from "../database/rest";
+import type { Tenant } from "./tenant";
+import type { Config } from "./config";
+import type { logger } from "../utils/logger";
+import type { Server as SocketIO } from "socket.io";
+import type { TenantReplicationApi } from "./replication";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
+
+/** Signal that triggered the shutdown. */
+export type LifecycleReason = "SIGINT" | "SIGTERM";
+
+/** Base context shared by every lifecycle hook. `rest` is tenant-scoped. */
+export type LifecycleContext = {
+    tenant: Tenant;
+    rest: InstanceType<typeof useRest>;
+    /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+    agents: TenantAgents;
+    /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+    api: Api;
+    logger: typeof logger;
+    cfg: Config;
+    /** Tenant-scoped replication API — `reset()`, `seed()`, `now()`, `state()` (no tenant id needed). */
+    replication: TenantReplicationApi;
+};
+
+/** Context of `beforeBoot` — runs before replication and before the HTTP server listens. */
+export type LifecycleBootContext = LifecycleContext;
+
+/** Context of `afterBoot` — runs once the server is listening. */
+export type LifecycleReadyContext = LifecycleContext & {
+    io: SocketIO;
+    server: ReturnType<typeof Bun.serve>;
+};
+
+/** Context of `onDestroy` — runs on SIGINT/SIGTERM, before replication stops and DB clients close. */
+export type LifecycleDestroyContext = LifecycleContext & {
+    reason: LifecycleReason;
+};
+
+/**
+ * Per-tenant lifecycle — one `lifecycle.ts` at the tenant root.
+ *
+ * @example
+ * ```ts
+ * export default define.Lifecycle({
+ *   beforeBoot: async ({ rest, tenant }) => { await rest.insertOne('settings', { tenant: tenant.id }) },
+ *   afterBoot: async ({ server, logger }) => { logger.info(`ready on :${server.port}`) },
+ *   onDestroy: async ({ reason }) => { await flushSomething(reason) },
+ * })
+ * ```
+ */
+export type Lifecycle = {
+    _isLifecycle_?: boolean;
+    /** Injected by the loader — the tenant this lifecycle belongs to. */
+    _tenant_?: string;
+    /** Turn this lifecycle off without removing the file (default: true). */
+    enabled?: boolean;
+    /**
+     * Blocking — runs after databases are connected and collections are loaded,
+     * before replication starts and before the HTTP server listens. Ideal for
+     * migrations, seeding, warmup. Throwing aborts the boot.
+     */
+    beforeBoot?: (ctx: LifecycleBootContext) => Promise<void> | void;
+    /**
+     * Runs once the server is listening (after `Bun.serve`). Ideal for
+     * notifications and cache warming. Errors are logged, never fatal.
+     */
+    afterBoot?: (ctx: LifecycleReadyContext) => Promise<void> | void;
+    /**
+     * Runs on SIGINT/SIGTERM, before replication stops and tenant DB clients
+     * close — so `rest` is still usable. Errors are logged; shutdown proceeds.
+     */
+    onDestroy?: (ctx: LifecycleDestroyContext) => Promise<void> | void;
+    /** Max time (ms) allowed for `onDestroy` before shutdown proceeds anyway (default: 10000). */
+    destroyTimeout?: number;
+};

package/types/mcp.d.ts

@@ -2,6 +2,8 @@ import type Joi from "joi";
 import type { ContentBlock } from "@modelcontextprotocol/sdk/types.js";
 import type { Context } from "hono";
 import type { useRest } from "../database/rest";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
 
 /**
  * MCP tool result — the Model Context Protocol `CallToolResult` shape.
@@ -15,7 +17,7 @@ export type McpToolResult = {
 
 /**
  * MCP tool definition — auto-loaded from `{tenant.dir}/mcp/tools/**\/*.tool.ts`.
- * Served over the MCP protocol at `GET/POST /mcp/:tenant_id` (Streamable HTTP).
+ * Served over the MCP protocol at `GET/POST /api/:tenant_id/mcp` (Streamable HTTP).
  */
 export type McpTool = {
     _isMcpTool_?: boolean;
@@ -32,6 +34,10 @@ export type McpTool = {
     exec: (ctx: {
         c: Context;
         rest: InstanceType<typeof useRest>;
+        /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+        agents: TenantAgents;
+        /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+        api: Api;
         /** Parsed & validated arguments */
         args: Record<string, any>;
     }) => McpToolResult | Promise<McpToolResult>;
@@ -73,6 +79,10 @@ export type McpResource = {
     read: (ctx: {
         c: Context;
         rest: InstanceType<typeof useRest>;
+        /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+        agents: TenantAgents;
+        /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+        api: Api;
         /** Params extracted from the URI template (e.g. `{ id: '123' }`) */
         params: Record<string, string>;
         /** The exact URI the client requested */

package/types/replication.d.ts

@@ -0,0 +1,228 @@
+import type { MongoClientOptions } from "mongodb";
+
+/** When to run replication — either a cron expression or a fixed interval. */
+export type ReplicationSchedule =
+    | { cron: string }
+    | { interval: string | number };
+
+/**
+ * Initial synchronization mode — how replication starts when no `_replication_`
+ * state exists yet.
+ * - `"full"` — backfill everything (default)
+ * - `"skip"` — ignore existing documents, start from now
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationInitialSync = "full" | "skip" | "latest" | (string & {}) | Date;
+
+/** A destination database that receives replicated documents. */
+export type ReplicationDestination = {
+    /** Unique identifier — used as the `_replication_` state key (required). */
+    id: string;
+    /** MongoDB connection string (required). */
+    uri: string;
+    /** Database name override — defaults to the name in the URI. */
+    name?: string;
+    /** Extra MongoDB client options (pool size, timeouts…). */
+    options?: MongoClientOptions;
+    /** Restrict replication to these collection slugs (default: all enabled). */
+    collections?: string[];
+    /** Turn this destination off without removing it. */
+    enabled?: boolean;
+};
+
+/**
+ * Framework (internal) collections that replication covers **by default**.
+ *
+ * The name is the collection name without its underscores: `_audit_` → `'audit'`,
+ * `_workflows_` → `'workflows'`, `_locks_` → `'locks'`, `_replication_` →
+ * `'replication'`, `_vars_` → `'vars'`, `_memories_` → `'memory'`.
+ *
+ * Every one of them is left out with `replication.exclude: ['audit', …]`.
+ */
+export type ReplicationMetaName = 'audit' | 'workflows' | 'locks' | 'replication' | 'vars' | 'memory';
+
+/** Per-tenant replication configuration (source → destination, one-way). */
+export type ReplicationConfig = {
+    /** Enable/disable replication for this scope (default: true when `destinations` is non-empty). */
+    enabled?: boolean;
+    /** Scheduling — `{ cron }` or `{ interval }` (default: every 5 minutes). */
+    schedule?: ReplicationSchedule;
+    /** Date key used for incremental replication (default: `'updatedAt'`). */
+    key?: string;
+    /**
+     * Rewind the cursor by this many milliseconds on each run, so documents
+     * written slightly out of order (clock skew) are not missed (default: 0).
+     */
+    lookback?: number;
+    /** Documents transferred per batch (default: 1000). */
+    batchSize?: number;
+    /** Run a first replication right after boot (default: true). */
+    runOnBoot?: boolean;
+    /**
+     * How the initial synchronization starts when no `_replication_` state exists
+     * yet (default: `'full'`). Use `'skip'` or `'latest'` to avoid the full
+     * backfill when the destination is already pre-loaded (e.g. via `mongorestore`).
+     */
+    initialSync?: ReplicationInitialSync;
+    /**
+     * Framework collections to **leave out** of replication. All of them are
+     * replicated by default (`audit`, `workflows`, `locks`, `replication`,
+     * `vars`) — excluding one is what you opt out of.
+     *
+     * ```ts
+     * replication: { exclude: ['locks', 'replication'] }
+     * ```
+     *
+     * ⚠️ `vars` covers *every* namespace of `_vars_`, including the ones that
+     * never declared `replication: { enabled: true }`; a namespace can still opt
+     * out with `replication: { enabled: false }`, but this list wins over it.
+     */
+    exclude?: ReplicationMetaName[];
+    /** Destination databases (required). */
+    destinations: ReplicationDestination[];
+};
+
+/** Per-collection opt-in replication. */
+export type CollectionReplicationConfig = {
+    /** Opt this collection into replication (required). */
+    enabled: boolean;
+    /** Date key override — defaults to `replication.key`. */
+    key?: string;
+    /** Initial sync override — defaults to `replication.initialSync`. */
+    initialSync?: ReplicationInitialSync;
+};
+
+export type ReplicationStatus = "idle" | "running" | "success" | "error";
+
+/** Cursor of the last replicated document — `value` is the date key, `id` the tie-breaker. */
+export type ReplicationCursor = {
+    value: Date | null;
+    id: any;
+};
+
+export type ReplicationStats = {
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+};
+
+/** State document persisted in `_replication_`, one per (tenant, destination, collection). */
+export type ReplicationState = {
+    _id: string;
+    type: "state";
+    tenant: string;
+    destination: string;
+    collection: string;
+    key: string;
+    cursor: ReplicationCursor;
+    status: ReplicationStatus;
+    lastRunAt: Date | null;
+    lastError: string | null;
+    stats: ReplicationStats;
+    /** PID of the process that ran this replication (`reusePort` / forked workers) */
+    pid?: number;
+    /** Hostname of that process — a PID is only meaningful on its own host */
+    hostname?: string;
+    createdAt?: Date;
+    updatedAt: Date;
+};
+
+/** Tombstone document persisted in `_replication_` when a replicated document is deleted. */
+export type ReplicationDeleteMarker = {
+    _id: string;
+    type: "delete";
+    tenant: string;
+    collection: string;
+    docId: string;
+    deletedAt: Date;
+    /** Destination ids that already applied the delete. */
+    synced: string[];
+    updatedAt: Date;
+};
+
+/** Scope of a `replication.reset()` call. */
+export type ReplicationResetOptions = {
+    /** Only reset this destination id (default: every destination). */
+    destination?: string;
+    /** Only reset this collection slug (default: every replicated collection). */
+    collection?: string;
+    /**
+     * Also delete pending delete tombstones (default: true). Ignored when
+     * `destination` is set — tombstones are shared across destinations.
+     */
+    tombstones?: boolean;
+};
+
+/** Result of a `replication.reset()` call. */
+export type ReplicationResetResult = {
+    tenant: string;
+    /** State documents deleted (one per destination + collection). */
+    state: number;
+    /** Delete tombstones deleted. */
+    tombstones: number;
+};
+
+/**
+ * Where to (re)start replication from — accepted by `replication.seed()`.
+ * - `"now"` — start from now (same as `initialSync: 'skip'`)
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationSeedValue = "now" | "latest" | (string & {}) | Date;
+
+/** Scope of a `replication.seed()` call. */
+export type ReplicationSeedOptions = {
+    /** Only seed this destination id (default: every destination). */
+    destination?: string;
+    /** Only seed this collection slug (default: every replicated collection). */
+    collection?: string;
+    /** Optional `_id` tie-breaker for the cursor. */
+    id?: any;
+};
+
+/** Result of a `replication.seed()` call. */
+export type ReplicationSeedResult = {
+    tenant: string;
+    /** State documents written (one per destination + collection). */
+    seeded: number;
+};
+
+/** Shape of the `replication` namespace exported by the package (multi-tenant). */
+export type ReplicationApi = {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    now: (tenantId?: string) => Promise<ReplicationRunResult[]>;
+    state: (tenantId: string, destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (tenantId: string, opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (tenantId: string, value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/**
+ * Tenant-scoped replication API — like `rest`, the tenant is implicit. This is
+ * the `replication` passed to lifecycle hooks. Engine control (`start`/`stop`)
+ * stays on the global `ReplicationApi`.
+ */
+export type TenantReplicationApi = {
+    now: () => Promise<ReplicationRunResult[]>;
+    state: (destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/** Outcome of a single (tenant, destination, collection) replication. */
+export type ReplicationRunResult = {
+    tenant: string;
+    destination: string;
+    collection: string;
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+    error?: string;
+};

package/types/route.d.ts

@@ -1,10 +1,16 @@
 import type { Context } from "hono";
 import type { useRest } from "../database/rest";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
 
 type routeContext = {
     rest: InstanceType<typeof useRest>;
+    /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+    agents: TenantAgents;
+    /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+    api: Api;
     jwt: typeof jwt;
-    io: InstanceType<typeof IO>;
+    io: InstanceType<IO>;
     c: Context
 }
 

package/types/scripts.d.ts

@@ -1,5 +1,7 @@
 import { useRest } from "../database/rest"
 import type { Tenant } from "./tenant"
+import type { TenantAgents } from "./agent"
+import type { Api } from "../lib/api"
 
 
 export type Script = {
@@ -15,6 +17,10 @@ export type Script = {
     timeout?: number;
     exec: (ctx: {
         rest: InstanceType<typeof useRest>
+        /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+        agents: TenantAgents;
+        /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+        api: Api;
         /** Report progress — only wired for heavy scripts (sent via IPC to the parent) */
         progress?: (percent: number, info?: any) => void;
         /** Tenant this script runs for */

package/types/service.d.ts

@@ -2,6 +2,8 @@ import type { Server as SocketIO } from "socket.io";
 import type { useRest } from "../database/rest";
 import type { fn } from "../lib/error";
 import type { jwt } from "../utils/func";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
 
 export type Service = {
     _isService_?: boolean;
@@ -31,7 +33,11 @@ export type Service = {
             jwt: typeof jwt;
             error: typeof fn.error;
             io: SocketIO;
-            rest: InstanceType<typeof useRest>
+            rest: InstanceType<typeof useRest>;
+            /** Tenant-scoped LLM registry — `agents.get('support')`, bound to `rest`. */
+            agents: TenantAgents;
+            /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+            api: Api;
         }) => Promise<any>
     }
 }

package/types/tenant.d.ts

@@ -1,9 +1,45 @@
 import type { Db, MongoClient, MongoClientOptions } from "mongodb";
+import type { ReplicationConfig } from "./replication";
+import type { AuditFileConfig } from "../lib/audit";
 export type Tenant = {
     id: string;
     name?: string;
     description?: string;
     dir: string;
+    /** Per-tenant replication — each tenant has its own destinations and schedule. */
+    replication?: ReplicationConfig;
+    /**
+     * Audit trail (`_audit_`) — query indexes are always ensured in the background,
+     * retention is opt-in.
+     */
+    audit?: {
+        /**
+         * How long audit entries are kept, as a MongoDB TTL index on `ts`.
+         * Duration string: `'90d'`, `'24h'`, `'30m'`.
+         * `false` → explicitly disabled (drops the TTL index if one exists).
+         * Omitted → untouched: entries are kept forever.
+         */
+        retention?: string | false;
+        /**
+         * Local append-only JSONL copy of this tenant's audit trail.
+         * `true` → defaults, `string` → directory, object → full options.
+         * `false` → explicitly disabled (overrides `server.audit.file`).
+         */
+        file?: AuditFileConfig;
+    };
+    /**
+     * Workflow runs (`_workflows_`). Indexes are always ensured in the
+     * background; retention is opt-in and only prunes **finished** runs.
+     */
+    workflows?: {
+        /**
+         * How long finished runs are kept, as a MongoDB TTL index on `completedAt`
+         * (runs still running, paused or failed keep no `completedAt` and are never
+         * pruned). Duration string: `'30d'`, `'90d'`.
+         * `false` → explicitly disabled. Omitted → untouched.
+         */
+        retention?: string | false;
+    };
     routes?: {
         prefix?: string;
     },