@anteros/core 0.0.41 → 0.0.42

package/lib/routes.ts

@@ -1,5 +1,6 @@
 import { Glob } from "bun"
 import { cfg } from "../server/config"
+import { isReservedFamily } from "./endpoints"
 import path from "path"
 import fs from "fs/promises"
 
@@ -25,6 +26,18 @@ async function loadRoutes() {
                             _tenant_: tenant.id,
                             _prefix_: tenant.routes?.prefix,
                         })
+
+                        // A route mounted under a family segment the framework owns
+                        // (`/api/v1/vars/x`) is registered first and would shadow the
+                        // framework API silently — say it out loud.
+                        const path = String(routeModule.default.path ?? '');
+                        const family = path.replace(/^\/+/, '').split('/')[0];
+                        if (family && isReservedFamily(family)) {
+                            console.warn(
+                                `Route '${tenant.routes?.prefix}${path}' of tenant '${tenant.id}' shadows the `
+                                + `framework '/api/…/${family}/…' API: rename it or change the route prefix.`,
+                            );
+                        }
                     }
                 }
             }
@@ -41,4 +54,4 @@ async function loadRoutes() {
 
 export {
     loadRoutes
-}
+}

package/lib/scriptWorker.ts

@@ -3,6 +3,8 @@ import { useRest } from "../database/rest";
 import { syncTenants } from "../database/tenant";
 import { syncCollections } from "../database/collection";
 import { syncFileCollections } from "../database/file";
+import { syncAgents, createAgents } from "./agents";
+import { createApi } from "./api";
 import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage";
 
 // ─── Heavy-script worker entrypoint ─────────────────────────────────────────
@@ -42,6 +44,7 @@ async function main() {
         await syncTenants();
         await syncCollections();
         await syncFileCollections();
+        await syncAgents(); // a heavy script gets the same `agents` registry as any other context
     } catch (err: any) {
         console.error('[script-worker] failed to bootstrap context:', err?.message);
         process.exit(1);
@@ -62,7 +65,7 @@ async function main() {
         await asyncContextStorage.run(new Map(), async () => {
             requestCtxStorage.set('trace', { id: crypto.randomUUID() });
             requestCtxStorage.set('internal', true);
-            await script.exec({ rest, progress, tenant });
+            await script.exec({ rest, progress, tenant, agents: createAgents(tenant.id, rest), api: createApi(rest) });
         });
         process.send?.({ type: 'done' });
         process.exit(0);

package/lib/scripts.ts

@@ -5,6 +5,8 @@ import fs from "fs/promises"
 import type { Script } from "../types/scripts"
 import type { Tenant } from "../types/tenant"
 import { useRest } from "../database/rest"
+import { createAgents } from "./agents"
+import { createApi } from "./api"
 import { asyncContextStorage, requestCtxStorage } from "./asyncContextStorage"
 
 
@@ -95,9 +97,12 @@ async function runScripts() {
         await asyncContextStorage.run(new Map(), async () => {
             requestCtxStorage.set('trace', { id: crypto.randomUUID() })
             requestCtxStorage.set('internal', true)
+            const rest = new useRest({ tenant_id: tenant.id })
             await script.exec({
-                rest: new useRest({ tenant_id: tenant.id }),
+                rest,
                 tenant,
+                agents: createAgents(tenant.id, rest),
+                api: createApi(rest),
             })
         })
     }

package/lib/sockets.ts

@@ -3,6 +3,8 @@ import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
 import { useRest } from "../database/rest"
+import { createAgents } from "../lib/agents"
+import { createApi } from "../lib/api"
 import { io } from "../server/io"
 import type { WebSocketHandler } from "../types/websocket"
 
@@ -26,7 +28,7 @@ async function loadSockets() {
                     const rest = new useRest({ tenant_id: tenant.id })
 
                     io.on('connection', (socket) => {
-                        handler.exec({ io, rest, socket })
+                        handler.exec({ io, rest, socket, agents: createAgents(tenant.id, rest), api: createApi(rest) })
                     })
 
                     console.log(`[socket] ${tenant.id}/${path.basename(file, '.ws.ts')} loaded`)

package/lib/workflow.ts

@@ -1,60 +1,232 @@
 import { Glob } from "bun"
-import { cfg } from "../server/config"
 import path from "path"
 import fs from "fs/promises"
-import type { WorkflowDefinition } from "../types/workflow"
+import { cfg } from "../server/config"
+import { logger } from "../utils/logger"
+import { AppError } from "./error"
+import { syncTtlRetention } from "../database/ttl"
+import type { WorkflowDefinition, WorkflowIndex } from "../types/workflow"
+import type { Tenant } from "../types/tenant"
 import { getTenant } from "../database/tenant"
 
+/** Every workflow of every tenant, keyed by `{tenant}:{id}` */
 const workflows: Map<string, WorkflowDefinition> = new Map();
 
+/**
+ * Indexes the engine itself filters on (see `database/workflow.ts`):
+ * - `listRuns()` → `find({ workflowId }).sort({ createdAt: -1 })`
+ * - `resumeAll()` → `find({ status: { $in: […] } })`
+ *
+ * Field names match MongoDB's default index naming, so an existing index with
+ * the same key is recognised (and never re-created or duplicated).
+ */
+const ENGINE_INDEXES: Record<string, 1 | -1>[] = [
+    { workflowId: 1, createdAt: -1 },
+    { status: 1 },
+]
+
+/** TTL index used for run retention — only prunes **finished** runs (`completedAt`) */
+const RUNS_TTL_INDEX = '_workflow_runs_ttl_'
+
+/**
+ * Run retention — **the tenant always wins**, `server.workflows.retention` is
+ * the fallback:
+ * - `tenant.workflows.retention` set (even `false`) → used as-is
+ * - otherwise                                     → `server.workflows.retention`
+ * - neither                                       → `undefined` (kept forever)
+ */
+function resolveWorkflowsRetention(tenant: Tenant): string | false | undefined {
+    if (tenant.workflows?.retention !== undefined) return tenant.workflows.retention
+    return cfg.server?.workflows?.retention
+}
+
+/** MongoDB's default index name for a key spec — `{ a: 1, b: -1 }` → `a_1_b_-1` */
+function indexName(key: Record<string, 1 | -1>): string {
+    return Object.entries(key).map(([field, direction]) => `${field}_${direction}`).join('_')
+}
+
 async function syncWorkflows() {
-    try {
-        workflows.clear();
-        for (let tenant of cfg.tenants ?? []) {
-            const TENANT_PATH = path.join(process.cwd(), tenant.dir)
-            const WORKFLOWS_PATH = path.join(TENANT_PATH, 'workflows')
-            let exist = await fs.exists(WORKFLOWS_PATH)
-            if (!exist) continue;
-            const isDirectory = await (await fs.stat(WORKFLOWS_PATH)).isDirectory()
-            if (!isDirectory) continue;
+    workflows.clear()
+
+    // ── Discovery — `{tenant.dir}/workflows/**/*.workflow.ts` ──────────────
+    // A broken file (or a broken tenant) must never hide the others.
+    for (const tenant of cfg.tenants ?? []) {
+        const WORKFLOWS_PATH = path.join(process.cwd(), tenant.dir, 'workflows')
+        try {
+            if (!(await fs.exists(WORKFLOWS_PATH))) continue
+            if (!(await fs.stat(WORKFLOWS_PATH)).isDirectory()) continue
 
             const glob = new Glob(path.join(WORKFLOWS_PATH, '**/*.workflow.ts'))
-            for await (let file of glob.scan('.')) {
-                let module = await import(file)
-                if (module?.default?._isWorkflow_) {
-                    const wf: WorkflowDefinition = { ...module.default, _tenant_: tenant.id }
-                    workflows.set(`${tenant.id}:${wf.id}`, wf)
+            for await (const file of glob.scan('.')) {
+                try {
+                    const module = await import(file)
+                    const definition = module?.default as WorkflowDefinition | undefined
+                    if (!definition?._isWorkflow_) continue
+                    if (definition.enabled === false) continue
+                    if (!definition.id) {
+                        console.warn(`⚠ Workflow ignored (no "id"): ${file}`)
+                        continue
+                    }
+
+                    const key = `${tenant.id}:${definition.id}`
+                    if (workflows.has(key)) {
+                        console.warn(
+                            `⚠ Duplicate workflow id '${definition.id}' for tenant '${tenant.id}' — ${file} overrides the previous definition`,
+                        )
+                    }
+                    workflows.set(key, { ...definition, _tenant_: tenant.id })
+                } catch (err: any) {
+                    console.error(`Failed to load workflow '${file}':`, err?.message)
                 }
             }
+        } catch (err: any) {
+            console.error(`Failed to load workflows for tenant '${tenant.id}':`, err?.message)
         }
+    }
 
-        // Create the indexes on _workflows_ for the defined contexts
-        for (const [key, wf] of workflows) {
-          const tenantId = key.split(':')[0]
-          if (!wf.context || !tenantId) continue
-          const tenant = getTenant(tenantId)
-          const db = tenant?.database?.db
-          if (!db) continue
-
-          for (const [field, config] of Object.entries(wf.context)) {
-            const direction = config.index === true || config.index === 1 ? 1 : config.index === -1 ? -1 : 0
-            if (direction === 0) continue
-
-            try {
-              const indexKey = `context.${field}`
-              await db.collection('_workflows_').createIndex({ [indexKey]: direction })
-            } catch (err: any) {
-              console.error(`Failed to create index on _workflows_.${field}:`, err?.message)
+    logger.file('workflows: loaded', {
+        total: workflows.size,
+        tenants: [...new Set([...workflows.values()].map((wf) => wf._tenant_))],
+    })
+
+    // Indexes are a background concern: boot never waits for an index build.
+    ensureWorkflowIndexes().catch((err) => console.error('Failed to create workflow indexes:', err?.message))
+}
+
+/**
+ * Create the indexes `_workflows_` needs — the engine's query fields, the
+ * `context` fields declared by the workflows, and any explicit `indexes`.
+ * Only the missing ones are built (`background: true`), and a failure is
+ * logged, never fatal.
+ */
+async function ensureWorkflowIndexes(): Promise<void> {
+    for (const tenant of cfg.tenants ?? []) {
+        const db = getTenant(tenant.id)?.database?.db
+        if (!db) continue
+
+        // Desired indexes: engine queries first, then what the workflows declare
+        const desired = new Map<string, { key: Record<string, 1 | -1>; options: any }>()
+        for (const key of ENGINE_INDEXES) {
+            desired.set(indexName(key), { key, options: { background: true } })
+        }
+
+        for (const wf of workflows.values()) {
+            if (wf._tenant_ !== tenant.id) continue
+
+            // `context: { field: { index: true | 1 | -1 } }`
+            for (const [field, config] of Object.entries(wf.context ?? {})) {
+                const direction = config.index === true || config.index === 1 ? 1 : config.index === -1 ? -1 : 0
+                if (!direction) continue
+                const key = { [`context.${field}`]: direction } as Record<string, 1 | -1>
+                desired.set(indexName(key), { key, options: { background: true } })
+            }
+
+            // `indexes: [{ key, name?, unique?, sparse? }]` — compound and friends
+            for (const index of wf.indexes ?? []) {
+                if (!index?.key || !Object.keys(index.key).length) continue
+                // Never send `null`/`undefined` on the wire: Mongo rejects `unique: null`
+                desired.set(index.name ?? indexName(index.key), {
+                    key: index.key,
+                    options: {
+                        background: true,
+                        ...(index.name ? { name: index.name } : {}),
+                        ...(index.unique !== undefined ? { unique: index.unique } : {}),
+                        ...(index.sparse !== undefined ? { sparse: index.sparse } : {}),
+                    },
+                })
+            }
+        }
+
+        try {
+            // `listIndexes()` requires the collection to exist — create it first,
+            // like the file-collection loader does (`_workflows_` is only written
+            // when a workflow actually runs).
+            const exists = await db.listCollections({ name: '_workflows_' }).toArray()
+            if (!exists.length) await db.createCollection('_workflows_')
+
+            const collection = db.collection('_workflows_')
+            const existing = new Set(
+                (await collection.listIndexes().toArray()).map((index: any) => index.name),
+            )
+
+            for (const [name, { key, options }] of desired) {
+                if (existing.has(name)) continue
+                await collection.createIndex(key as any, options)
+                logger.file('workflows: index created', { tenant: tenant.id, index: name })
+            }
+
+            // Retention of finished runs — opt-in (`completedAt` is only set when a
+            // run finishes, so running/paused/failed runs are never pruned)
+            const retention = resolveWorkflowsRetention(tenant)
+            if (retention !== undefined) {
+                await syncTtlRetention(db, {
+                    collection: '_workflows_',
+                    index: RUNS_TTL_INDEX,
+                    field: 'completedAt',
+                    retention,
+                    label: 'Workflows',
+                })
+            }
+        } catch (err: any) {
+            console.error(`Failed to create workflow indexes for tenant '${tenant.id}':`, err?.message)
+        }
+    }
+}
+
+/**
+ * Validate — and coerce — the `context` of a run against the workflow's own
+ * declaration: this is what the `type` of a context field is for. Undeclared
+ * keys are kept as-is (the declaration is a contract on what you declare, not a
+ * closed schema). Dates sent as ISO strings are stored as real `Date`s, so the
+ * indexes on `context.*` stay typed.
+ */
+function validateWorkflowContext(wf: WorkflowDefinition, context: any): any {
+    if (!wf.context || context === undefined || context === null || typeof context !== 'object') {
+        return context
+    }
+
+    const out: Record<string, any> = { ...context }
+    const errors: string[] = []
+
+    for (const [field, spec] of Object.entries(wf.context)) {
+        const value = out[field]
+        if (value === undefined || value === null) continue
+
+        switch (spec.type) {
+            case 'string':
+                if (typeof value !== 'string') errors.push(`'${field}' must be a string (received ${typeof value})`)
+                break
+            case 'number':
+                if (typeof value !== 'number' || Number.isNaN(value)) errors.push(`'${field}' must be a number (received ${typeof value})`)
+                break
+            case 'date': {
+                const date = value instanceof Date ? value : new Date(String(value))
+                if (Number.isNaN(date.getTime())) errors.push(`'${field}' must be a date (Date or ISO string)`)
+                else out[field] = date
+                break
             }
-          }
         }
-    } catch (err: any) {
-        console.error('Failed to sync workflows:', err?.message)
     }
+
+    if (errors.length) {
+        throw new AppError(`Invalid workflow context: ${errors.join('; ')}`, {
+            code: 'WORKFLOW_CONTEXT_INVALID',
+            status: 400,
+        })
+    }
+    return out
 }
 
 function getWorkflow(id: string, tenantId: string): WorkflowDefinition | undefined {
     return workflows.get(`${tenantId}:${id}`)
 }
 
-export { syncWorkflows, getWorkflow }
+/** What was loaded — used by the boot banner and logs */
+function workflowStats(): { total: number; tenants: string[] } {
+    return {
+        total: workflows.size,
+        tenants: [...new Set([...workflows.values()].map((wf) => wf._tenant_!))],
+    }
+}
+
+export { syncWorkflows, ensureWorkflowIndexes, validateWorkflowContext, resolveWorkflowsRetention, getWorkflow, workflowStats, RUNS_TTL_INDEX as WORKFLOW_RUNS_TTL_INDEX }

package/lib/zip.ts

@@ -0,0 +1,109 @@
+import { inflateRawSync } from "node:zlib";
+import { AppError } from "./error";
+
+/**
+ * A minimal, **read-only** ZIP reader — enough to open a `.docx` or a `.xlsx`
+ * (both are ZIP containers) without adding a dependency.
+ *
+ * `Bun.Archive` only handles tar, and a document is not worth a package: the
+ * central directory of a ZIP is a simple, stable structure — find it, list the
+ * entries, inflate the one you need. Entries are decompressed **lazily**, so a
+ * workbook full of images never pays for them.
+ *
+ * Deliberately not supported (they never appear in an Office file): ZIP64
+ * archives, encrypted entries and multi-disk sets.
+ */
+
+const SIGNATURE = {
+    end: 0x06054b50,
+    central: 0x02014b50,
+    local: 0x04034b50,
+} as const;
+
+/** Zip entries are never larger than this in a document we read — sanity guard. */
+const MAX_EOCD_SCAN = 65_535 + 22; // the folder comment cap + the record itself
+
+type Entry = {
+    method: number;
+    compressedSize: number;
+    localOffset: number;
+};
+
+export type ZipArchive = {
+    /** Every entry name, in central-directory order. */
+    names(): string[];
+    /** The decompressed bytes of an entry, or `null` when it does not exist. */
+    read(name: string): Uint8Array | null;
+};
+
+function bad(reason: string): AppError {
+    return new AppError(`Unreadable archive: ${reason}`, { status: 400, code: "AGENT_FILE_INVALID" });
+}
+
+/** Open a ZIP buffer — throws `AGENT_FILE_INVALID` when it is not a readable ZIP. */
+function openZip(buffer: Uint8Array): ZipArchive {
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+
+    // ── End Of Central Directory — the only reliable place to start ───────
+    let end = -1;
+    const lowest = Math.max(0, buffer.length - MAX_EOCD_SCAN);
+    for (let offset = buffer.length - 22; offset >= lowest; offset--) {
+        if (view.getUint32(offset, true) === SIGNATURE.end) {
+            end = offset;
+            break;
+        }
+    }
+    if (end < 0) throw bad("no ZIP central directory (is it a real .docx/.xlsx?)");
+
+    const entries = new Map<string, Entry>();
+    const count = view.getUint16(end + 10, true);
+    let offset = view.getUint32(end + 16, true);
+
+    // ── Central directory ────────────────────────────────────────────────
+    for (let index = 0; index < count; index++) {
+        if (offset + 46 > buffer.length || view.getUint32(offset, true) !== SIGNATURE.central) {
+            throw bad("truncated central directory");
+        }
+
+        const method = view.getUint16(offset + 10, true);
+        const compressedSize = view.getUint32(offset + 20, true);
+        const nameLength = view.getUint16(offset + 28, true);
+        const extraLength = view.getUint16(offset + 30, true);
+        const commentLength = view.getUint16(offset + 32, true);
+        const localOffset = view.getUint32(offset + 42, true);
+
+        if (compressedSize === 0xffffffff || localOffset === 0xffffffff) {
+            throw bad("ZIP64 archives are not supported");
+        }
+
+        const name = new TextDecoder().decode(buffer.subarray(offset + 46, offset + 46 + nameLength));
+        entries.set(name, { method, compressedSize, localOffset });
+        offset += 46 + nameLength + extraLength + commentLength;
+    }
+
+    return {
+        names: () => [...entries.keys()],
+
+        read(name: string): Uint8Array | null {
+            const entry = entries.get(name);
+            if (!entry) return null;
+
+            // The local header repeats the name/extra — the payload starts after them.
+            const local = entry.localOffset;
+            if (local + 30 > buffer.length || view.getUint32(local, true) !== SIGNATURE.local) {
+                throw bad(`corrupted entry '${name}'`);
+            }
+
+            const start = local + 30 + view.getUint16(local + 26, true) + view.getUint16(local + 28, true);
+            const data = buffer.subarray(start, start + entry.compressedSize);
+            if (start + entry.compressedSize > buffer.length) throw bad(`truncated entry '${name}'`);
+
+            // 0 = stored, 8 = deflate — the only two methods Office writes
+            if (entry.method === 0) return data;
+            if (entry.method === 8) return new Uint8Array(inflateRawSync(data));
+            throw bad(`unsupported compression method ${entry.method} for '${name}'`);
+        },
+    };
+}
+
+export { openZip };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anteros/core",
   "module": "index.ts",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "type": "module",
   "description": "Anteros Core",
   "private": false,

package/server/access.ts

@@ -0,0 +1,96 @@
+import { AppError, fn } from "../lib/error";
+import * as func from "../utils/func";
+import type { useRest } from "../database/rest";
+
+/**
+ * Shared HTTP plumbing between the collection/vars/service API (`server/api.ts`)
+ * and the agents API (`server/agents.ts`).
+ *
+ * Extracted rather than duplicated: the access rule semantics (wildcard, boolean
+ * vs function, token requirement) must stay identical everywhere — a divergence
+ * here is a hole.
+ */
+
+function getAccessToken(c: any) {
+    const t = c.get('token');
+    return {
+        value: (t?.value ?? null) as string | null,
+        decoded: (t?.decoded ?? null) as Record<string, unknown> | null,
+        provided: (t?.provided ?? false) as boolean,
+        expired: (t?.expired ?? false) as boolean,
+    };
+}
+
+function errorResponse(c: any, err: any) {
+    const isAppError = err instanceof AppError;
+    const status = isAppError ? Number(err.status) : 500;
+    return c.json({
+        message: isAppError ? err.message : 'Internal server error',
+        code: isAppError ? err.code : 'INTERNAL_SERVER_ERROR',
+        meta: isAppError ? err.meta : undefined,
+    }, status);
+}
+
+/**
+ * Evaluate an `api.access` rule — **no rule = denied** (secure by default).
+ *
+ * - `true` → allowed without a token (public)
+ * - `false` → denied
+ * - function → **requires a valid, non-expired token**, then the rule decides
+ *
+ * `extra` is merged into the rule context (agents pass the agent, the action and
+ * the input so a rule can decide on the payload it is about to run).
+ */
+async function evaluateAccess(
+    access: { [key: string]: boolean | ((ctx: any) => boolean | Promise<boolean>) | undefined } | undefined,
+    operation: string,
+    rest: InstanceType<typeof useRest>,
+    label: string,
+    c: any,
+    extra: Record<string, any> = {},
+): Promise<void> {
+    if (!access) {
+        throw new AppError('Access denied', { status: 401, code: 'ACCESS_DENIED' });
+    }
+
+    const hasWildcard = access['*'] !== undefined;
+    const hasSpecific = access[operation] !== undefined;
+
+    if (!hasWildcard && !hasSpecific) {
+        throw new AppError('Access denied', { status: 401, code: 'ACCESS_DENIED' });
+    }
+
+    const rule = hasSpecific ? access[operation] : access['*'];
+    if (rule === undefined) return;
+
+    // Boolean `true` → allow without requiring a token
+    if (typeof rule === 'boolean') {
+        if (!rule) {
+            throw new AppError(`${label} not allowed`, { status: 401, code: 'ACCESS_DENIED' });
+        }
+        return;
+    }
+
+    // Function → requires a valid token
+    const accessToken = getAccessToken(c);
+
+    if (accessToken.expired) {
+        throw new AppError('Token expired', { status: 401, code: 'TOKEN_EXPIRED' });
+    }
+    if (!accessToken.value) {
+        throw new AppError('Authentication required', { status: 401, code: 'AUTH_REQUIRED' });
+    }
+
+    const allowed = await (rule as Function)({
+        rest,
+        error: fn.error,
+        jwt: func.jwt,
+        token: accessToken,
+        ...extra,
+    });
+    if (!allowed) {
+        throw new AppError(`${label} not allowed`, { status: 401, code: 'ACCESS_DENIED' });
+    }
+}
+
+export { getAccessToken, errorResponse, evaluateAccess };