@anteros/core 0.0.41 → 0.0.42

package/types/config.d.ts

@@ -8,6 +8,7 @@ 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;
@@ -67,6 +68,18 @@ export type ServerConfig = {
              */
             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;
         };
@@ -187,4 +200,7 @@ export type Config = ServerConfig & {
     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

@@ -16,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;
 };
 
@@ -31,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'];
@@ -54,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 */

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

@@ -4,6 +4,8 @@ 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";
@@ -12,6 +14,10 @@ export type LifecycleReason = "SIGINT" | "SIGTERM";
 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). */

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

@@ -31,6 +31,17 @@ export type ReplicationDestination = {
     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). */
@@ -54,6 +65,20 @@ export type ReplicationConfig = {
      * 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[];
 };
@@ -98,6 +123,10 @@ export type ReplicationState = {
     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;
 };

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

@@ -27,6 +27,19 @@ export type Tenant = {
          */
         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;
     },

package/types/vars.d.ts

@@ -3,7 +3,7 @@ import type { useRest } from "../database/rest";
 import type { fn } from "../lib/error";
 import type { jwt } from "../utils/func";
 
-/** Actions exposed by the variables HTTP API (`POST /vars/:tenant_id/:action`). */
+/** Actions exposed by the variables HTTP API (`POST /api/:tenant_id/vars/:action`). */
 export type VarsActions =
     | "set"
     | "setMany"
@@ -82,7 +82,7 @@ export type VarDefinition = {
     meta?: Field[];
     /** Variables — a raw default value, or a `VarSpec`. */
     vars: Record<string, any>;
-    /** HTTP API access rules — required to expose this namespace over `POST /vars/:tenant_id/:action`. */
+    /** HTTP API access rules — required to expose this namespace over `POST /api/:tenant_id/vars/:action`. */
     api?: VarsApi;
     /** Opt this namespace into replication — like a collection, but scoped to this namespace. */
     replication?: VarsReplicationConfig;

package/types/websocket.d.ts

@@ -1,5 +1,7 @@
 import type { Server as SocketIO, Socket as SocketClient } from "socket.io";
 import type { useRest } from "../database/rest";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
 
 
 
@@ -11,5 +13,9 @@ export type WebSocketHandler = {
         io: SocketIO;
         socket: SocketClient;
         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;
     }) => void | Promise<void>;
 };

package/types/workflow.d.ts

@@ -1,10 +1,21 @@
+import type { useRest } from "../database/rest";
+import type { TenantAgents } from "./agent";
+import type { Api } from "../lib/api";
+
 export type WorkflowStepHandler<TData = any> = (ctx: {
   data: TData;
   prevOutput: any;
   input?: any;
-  rest: any;
+  /** Tenant-scoped client — `rest.find`, `rest.insertOne`, `rest.workflow`, `rest.vars`… */
+  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;
   error: any;
   jwt: any;
+  /** Aborted when the step exceeds its `timeout` — forward it to your own IO */
+  signal?: AbortSignal;
 }) => Promise<any>;
 
 export type WorkflowCompensationHandler<TData = any> = (ctx: {
@@ -13,9 +24,13 @@ export type WorkflowCompensationHandler<TData = any> = (ctx: {
   stepOutput: any;
   /** The error that caused the failure */
   stepError: { message: string; code?: string };
-  rest: any;
+  rest: InstanceType<typeof useRest>;
+  agents: TenantAgents;
+  /** The in-process facade — `api.collection("orders")`, `api.service("analytics")`, `api.vars`, `api.files`, `api.agent(id)`. */
+  api: Api;
   error: any;
   jwt: any;
+  signal?: AbortSignal;
 }) => Promise<void>;
 
 export type WorkflowStep<TData = any> = {
@@ -27,6 +42,12 @@ export type WorkflowStep<TData = any> = {
   compensate?: WorkflowCompensationHandler<TData>;
   /** List of step IDs this compensation depends on / targets */
   depend?: string[];
+  /** Attempts after the first failure (default: 0 — no retry) */
+  retries?: number;
+  /** Base delay before a retry, doubled on each attempt (default: 250ms, capped at 5s) */
+  backoffMs?: number;
+  /** Abort the step after this duration (`'5s'`, `'2m'`, or ms) — the ctx receives an aborted `signal` */
+  timeout?: string | number;
   condition?: (ctx: {
     data: TData;
     prevOutput: any;
@@ -42,12 +63,32 @@ export type WorkflowContextField = {
 
 export type WorkflowContextFields = Record<string, WorkflowContextField>;
 
+/**
+ * Index created on `_workflows_` for this workflow. Dotted paths are allowed
+ * (`context.companyId`, `status`, …), so compound indexes can be declared:
+ *
+ * ```ts
+ * indexes: [{ key: { 'context.companyId': 1, status: 1 } }]
+ * ```
+ */
+export type WorkflowIndex = {
+  key: Record<string, 1 | -1>;
+  /** Explicit index name — defaults to MongoDB's `field_1_field_-1` */
+  name?: string;
+  unique?: boolean;
+  sparse?: boolean;
+};
+
 export type WorkflowDefinition<TData = any> = {
   id: string;
   name: string;
   description?: string;
   version?: number;
+  /** Set to `false` to keep the definition in the codebase without registering it. Default: `true`. */
+  enabled?: boolean;
   context?: WorkflowContextFields;
+  /** Indexes to create on `_workflows_` (compound, unique, sparse — beyond `context.index`) */
+  indexes?: WorkflowIndex[];
   exec?: WorkflowStepHandler<TData>;
   steps: WorkflowStep<TData>[];
   /** Global compensation handlers executed when any step fails (reverse order) */
@@ -56,7 +97,7 @@ export type WorkflowDefinition<TData = any> = {
   _isWorkflow_?: boolean;
 };
 
-export type WorkflowRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'paused' | 'cancelled' | 'skipped';
+export type WorkflowRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'compensated' | 'paused' | 'cancelled' | 'skipped';
 
 export type WorkflowRunStep = {
   stepId: string;
@@ -84,6 +125,12 @@ export type WorkflowRun = {
   steps: WorkflowRunStep[];
   /** Compensation steps that were executed */
   compensations?: WorkflowRunStep[];
+  /** PID of the process executing this run (`reusePort` / forked deployments) */
+  pid?: number;
+  /** Hostname of that process — a PID is only meaningful on its own host */
+  hostname?: string;
+  /** The store this run was last claimed by (distributed lock holder) */
+  lockedAt?: Date;
   error?: { message: string; code?: string; stepId?: string };
   createdAt: Date;
   updatedAt: Date;